# Propose And Apply An OCF Update

Use this workflow when a conversation, document, or downstream tool produces changes for an existing OCF master. Propose the specific changes, review them with the person, and apply the accepted changes to the complete current master.

OCF v0.3 defines complete documents. It does not define an update-file schema or a standard patch envelope. The OCF schema tells you what the resulting document may contain; it does not specify how to package incremental operations. This page is workflow guidance. [Provider-neutral patch sets](v0.4-planning.md#provider-neutral-patch-sets) remain a future consideration.

## Identify The Starting File

Read the complete master before preparing an update. Record its location, declared schema version, and `meta.id` when present. Locate the exact affected items by stable ID and read their surrounding context, including relevant provenance, variants, cautions, and open questions. If an item lacks an ID, identify it unambiguously and propose an ID where useful; never guess which of several similar items was intended.

State what identifies the starting revision. These identifiers serve different purposes:

| Identifier | What it identifies | Practical limit |
| --- | --- | --- |
| `schemaVersion` | The OCF format used by the file | Does not identify a revision of the person's career content. |
| `meta.version` | A content revision label maintained by the file's editor or tool | May be absent or stale; is not necessarily a content hash. |
| File-content hash | The exact bytes read, when the algorithm and scope are specified | Even formatting changes alter a byte hash. Name the algorithm, such as SHA-256; distinguish byte hashing from any tool-specific canonical-JSON hashing. |
| Git revision | A repository snapshot | Also identify the repository and file path. Uncommitted edits are not identified by the commit. |

Avoid an unexplained label such as “version fc7c39ff475f.” Say whether it is a Git revision, a hash, or a literal `meta.version` value. Use the identifiers available in the workflow; Git is optional. A timestamp or familiar filename alone does not establish that the file is unchanged.

## Prepare A Reviewable Proposal

Readable Markdown with partial JSON fragments is sufficient. Label it as an update proposal and label any fragments as partial objects. It is not an independently valid OCF document. A tool may use its own machine-readable proposal format, but should identify that convention rather than claiming it is the OCF update format.

For each proposed change, record:

- a proposal-local label so the person can accept or reject it separately;
- the operation: add, change, or explicitly remove;
- the target item ID and affected field, or the parent and collection for an addition;
- the current value or expected state needed to understand and safely apply the change;
- the proposed value, wording, or new item;
- the reason and source, including proposed provenance, visibility, and review state where applicable.

Group dependent changes visibly. For example, a new variant referencing a source artifact depends on adding that source artifact unless it already exists. Accepting one change must not silently authorize unrelated additions or removals.

Separate factual corrections from alternate wording and application-specific choices. A new career fact may belong in the master; a useful phrasing may belong in an existing variant collection. A job description's preference for Iowa candidates while accepting remote work does not establish that the person will relocate to Iowa. Preserve only deliberately accepted, reusable career memory from that application discussion.

For example, a fictional proposal might read:

> Change U1 — Achievement `northstar-team-growth`, field `statement`.
>
> Current: “Built a team of 12 implementation specialists.”
>
> Proposed: “Grew the implementation team from 8 to 12 specialists.”
>
> Reason: The person clarified that eight specialists were already on the team when they assumed responsibility. Check related metrics and variants for the same attribution issue and propose any necessary corrections separately.

Present the complete proposed set and identify what remains unresolved. Record which changes the person accepts. Generating a proposal or passing validation does not itself establish user acceptance or corroboration.

## Apply Accepted Changes To The Current Master

1. Re-read the complete master immediately before application. Confirm the file identity and compare the starting revision information and affected values with the proposal's assumptions.
2. If the file changed, inspect the differences. Preserve unrelated edits. If an affected value changed, a target disappeared, or a dependency is unresolved, return that change for review rather than overwriting it or silently retargeting it. A tool may conservatively refuse a stale proposal altogether.
3. Apply only the accepted changes and their explicitly accepted dependencies. Preserve unmentioned content, stable IDs, provenance, extensions, and unknown fields. Do not reconstruct the master from a resume, curated subset, proposal fragments, or partial model context.
4. Preserve the master's `meta.id`. Update `meta.version` and `meta.lastModified` if the workflow manages those fields. Preserve a recoverable prior copy through the user's existing backup or versioning practice.
5. Validate the resulting complete document against its declared OCF schema and check semantic integrity, including IDs and references. Validate after combining changes: individually plausible fragments can conflict in the complete file. If validation fails, retain the proposal for correction and leave the prior master intact.
6. Review the resulting diff against the accepted set, then save the validated result as the master under the agreed workflow. If a tool can detect intervening edits during this step, it should refuse to overwrite them. If further substantive changes are needed, present those for acceptance first.
7. Report which changes were applied, skipped, or left unresolved, the validation result, and where the updated master and recoverable prior version can be found.

A tool may serialize the entire JSON file when saving. The logical operation is still a targeted update derived from the complete current object plus accepted changes. If the tool cannot validate the declared schema version, keep the result as a clearly labeled review copy and report that limitation rather than presenting it as a validated master update.

For related guidance, see [file roles and usage patterns](usage-patterns.md), the [Design Guide](design-guide.md), and the [semantic-integrity contract](semantic-integrity.md).