Open Career Format logo Open Career Format

Readable HTML version. View the Markdown source.

OCF v0.3 Decision Notes

These notes record the design decisions behind the v0.3 schema draft. They preserve the reasoning from planning, but the sections below should be read as a decision record: some items shipped in v0.3, and the rest are explicitly deferred to later planning.

The goal for v0.3 is not to make OCF bigger for its own sake. The goal is to add small concepts that emerged repeatedly in real use and that improve memory, honesty, curation, and reuse.

Ideas that need more evidence before standardization are parked in v0.4 planning notes, especially career tracks, richer location modeling, richer voice calibration, and trust review.

v0.3 Scope

This section is the contract for the v0.3 release. The sections below preserve the design discussion, but headings now distinguish shipped decisions from deferred ideas.

v0.3 includes breaking changes where they produce a cleaner schema and clearer language. This is a clean-language release, not a churn release: break only where the new shape is easier to explain and less ambiguous for tools.

OCF should store what the person and tools need to remember, question, curate, and reuse; it should not adjudicate whether every claim is institutionally true. Boards, registries, employers, schools, unions, courts, and credential issuers own their own evidence rules. OCF can point to them through source artifacts, provenance, public-by-design identifiers, notes, and cautions, but it should not mirror each registry or profession-specific rulebook.

The lineage renames are part of v0.3. meta.fileRole stays limited to file lifecycle and purpose, while meta.source.kind is narrowed to origin mechanics rather than curation/export lifecycle. Migration notes live in CHANGELOG.md.

Treat meta.fileRole as effectively immutable for a file. If a workflow would change a file from master to curated, export-ready, third-party-working, or another role, it should create a child file with lineage rather than rewriting the existing file's role. This keeps role, source, and lineage from collapsing into one mutable lifecycle flag.

The imported-starter file role is retired in v0.3. The first session can create {person}.master.ocf.json immediately; imported or LLM-mined items inside that master carry reviewStatus: "unreviewed" until the subject reviews them. That preserves the safety gate where it belongs, at the item level, instead of requiring a provisional file role and later promotion ceremony.

Shipped foundations:

Shipped promotions:

Still deferred:

Release checklist / blast-radius touch points:

The generated-doc and worked-example snippet checks are part of the release gate. v0.3 should not be released while public docs, examples, prompts, or reference implementations still describe the v0.2 shapes as current.

Schema-core rule: schema-core.json is a minimal subset of the full schema, not a simplified dialect. If a field or object appears in both schemas, it must use the same field name, broad type, enum values, required children where practical, and nested shape. Core may omit fields; it must not rename them, flatten them, or introduce easier starter-only aliases. A file or object authored against core should be able to grow into the full schema without a translation pass.

Experimental / Incubating Shapes

OCF may publish experimental shapes before making them normative. The point is to let users and tools try the same idea in roughly the same way without pretending the schema contract is settled.

Working convention:

OCF v0.3 does not legalize person.extensions; incubation belongs at top-level extensions.user.local unless and until a future schema explicitly adds item-level extension surfaces for the relevant object. Tools should not hide experimental person-level concepts inside invalid person.extensions just because the concept is about the person.

Richer voice calibration remains an incubation area. reviewStatus, stable IDs, source-artifact enum additions, talkingPoints, and positioningVariants are v0.3 decisions recorded below.

v0.3 Decision: Stronger Stable IDs

Decision: allow id on more durable array items, and require or strongly recommend it on cross-referenceable workflow items, especially reflections, cautions, openQuestions, talkingPoints, positioningVariants, review-status-bearing records, or schema-feedback observations.

Problem: OCF works best when tools can update and reference specific items surgically. Achievements, source artifacts, narrative variants, title variants, and positions already benefit from stable IDs. As more workflows create cross-references, weaker ID coverage makes update proposals vague: a tool can say "this screening answer depends on a caution" only if the caution has a stable identifier.

Motivating references:

v0.3 direction:

Open design questions:

Example-Driven Profession Stress Tests

Before adding profession-specific schema, OCF should collect realistic examples from fields where career evidence does not look like a standard technology or business resume. These examples should test whether existing OCF concepts are enough: certifications, experience, education, skills, achievements, memberships, governance, service, references, cautions, openQuestions, visibility, and provenance.

The goal is not to make OCF a separate schema for every profession. The goal is to find industries where credentials, jurisdiction, confidentiality, nonstandard timelines, regulated claims, or team attribution make ordinary resume structures weak.

Useful stress-test professions and industries:

Suggested first example set before v0.3 freeze:

These should be written as realistic fictional examples, not schema fantasies. Each example should show what can be represented cleanly today, what requires conventions, and what might justify a future field only after repeated examples point to the same gap.

These stress tests are a release gate, not a side quest. At least two or three realistic examples should exist before v0.3 scope freezes, because they are the cheapest way to discover whether Phase 1 is missing a basic pressure such as licensure jurisdiction, credential status, regulated claims, or confidential evidence.

Insider-Legibility Pressures

Some professions are insider-legible: members of the profession can read a career file the way the schema cannot, inferring quality, status, and story from facts the file merely lists. Medicine and law are the strongest cases; military, academia, aviation, and skilled trades share parts of the pattern. The stress-test examples should test these pressures deliberately, not discover them by accident.

Normed progressions. Some career stages have durations and order fixed by the profession: residency length by specialty, apprentice-to-journeyman hour requirements, partner-track clocks, time-in-grade, tenure clocks, ratings sequences. In these pipelines the dates carry little information until they deviate, and then they carry a lot: a four-year internal-medicine residency reads as a repeated year; a gap before residency reads as failing to match. Two consequences:

Narrative legibility. In insider-legible professions, every transition is a seam: institution tier, specialty choice, and the timing of each move imply a story the subject never wrote down. The candidate's defense is owning the why: why-took-role and why-left reflections, cautions against unwanted framings, and narrative variants for how a transition is told to different audiences. The stress test should check whether those existing primitives are enough for a subject to pre-empt the story insiders would otherwise construct on their own.

Lineage and proximity claims. Institution plus department plus years resolves to named people: "trained at that program in those years" implies "under that chief." Proximity claims need graded verbs the way outcome attribution already does. "Trained under," "operated with regularly," and "was in the program while X was chief" are different claims, and in small specialty communities the reference check is ambient. The stress test should ask where a shareable pedigree claim lives, whether anything requires it to carry its basis the way titleVariants does, and how a file pairs precise private detail with cautious shared wording and a caution against the inflated version.

Derivable facts limit visibility controls. Marking a supervisor private does not hide an association that institution and dates already disclose to insiders. This is the sharpest instance of "visibility is not anonymization": understating a derivable association costs nothing, while overstating one is instantly checkable. Examples should demonstrate the honest pattern rather than pretend visibility can hide derivable facts.

Audience-relativity of omission. The same omission can mean different things to different audiences. Leaving rank and MOS out of a consumer-facing healthcare resume may be correct house style; leaving them out of a federal or defense-contractor resume may read as concealment. A public booking page may omit dates because patients do not need them; a credentialing packet or CV may need the same dates to avoid looking evasive. Omission rules are audience-scoped, not absolute.

Un-normed titles. Startup, growth-company, and idiosyncratic corporate titles are the mirror case of normed progressions. In those environments, a title may carry almost no signal without calibration: headcount as a time series, reporting line, budget, board exposure, product stage, market scope, and whether the job actually changed. Preserve literal title strings such as "AVP" rather than auto-expanding them, use cautions to block misleading expansions, and calibrate seniority with scope facts instead of assuming the title is portable.

Roles and achievements stay separate. The Maria rank/MOS example shows why the position timeline and progression evidence should not collapse into one object. Careers can run on parallel, loosely coupled timelines: Army rank versus MOS duty, big-company level cycles versus team moves, startup title succession over an unchanged job, or clinical ladder progression alongside unit assignments. Link and derive summaries where useful, but keep organization positions, achievements, progression facts, and cautions as separate layers unless repeated stress tests prove the schema needs a larger phases/events redesign.

Regulatory shadow. Some professions have an involuntary public career stratum: license registries, NPI records, state disciplinary pages, board certification lookups, court admissions, and similar systems. These records can reconstruct facts that curated profiles omit, and they often preserve fossils the subject never authored: student taxonomies, old addresses, former names, stale specialties, credential numbers, or partial renewal histories. The depth varies by profession. Physicians may have patient-facing profile-grade records; nurses may have employer-facing verification records; other professions may have almost no public shadow at all. Stress tests should treat these records as context for provenance, visibility, identifiers, and cautions, not as proof that v0.3 needs a full registry model. Pointers age better than mirrors: once OCF models one state's physician profile or one board's registry, it implicitly owns every future variation across states, professions, and rule changes.

What The Physician Example Must Test

The first example set may be reordered around available profession-matched reviewers. Review by a member of the profession is the realism gate, and a willing physician reviewer makes the physician example a natural first target, with the registered nurse example following. A physician cannot stand in for a nurse reviewer or vice versa: the two professions have separate boards, licensure systems, and career grammars, and each example needs its own profession-matched review.

Resolved by convention: dated progression steps. The Maria military record pass initially looked like a schema gap because progression has no dated events, but OCF already structures this: a spanning recognition achievement with each step as a dated supportingFact, which is the schema's documented decompose-the-summary pattern. progression remains the narrative summary. Adopted in the Maria example and the worked walkthrough; revisit only if physician, nurse, attorney, or electrician stress tests strain the convention.

v0.3 Decision: Positioning Variants

Decision: use top-level positioningVariants.

Scope for v0.3: target-aware person-level positioning, constrained to headline and summary-style presentation for now. The field is intentionally named broadly because future releases may learn that profile openers, short bios, or other positioning text belong in the same collection. person.headline remains the default general-purpose headline.

Problem: person.headline is a single positioning line, but the strongest defensible opener changes by target. The same person may need one headline for AI success engineering, another for customer-success leadership, another for advisory work, and a safe default when the target is unknown. Without stored variants, tools either reuse one headline everywhere or improvise new language each time.

This is related to the existing narrativeVariant pattern. OCF already has audience-specific wording for achievements, and that definition already allows headline as one payload shape. positioningVariants gives the same idea a top-level home for person-level positioning without nesting it under person.

Minimal shape:

{
  "id": "hl-ai-success-engineering",
  "audiences": ["ai-success-engineering", "ai-vendor", "post-sales-technical"],
  "headline": "Technical depth, customer obsessed.",
  "reviewStatus": "needs-review",
  "provenance": {
    "source": "interview-derived",
    "date": "2026-06-08",
    "operation": "assembled-target-aware-headline",
    "confidence": 0.7
  },
  "notes": "Use for AI-vendor post-sales technical roles after subject voice-check."
}

Selection behavior should be deterministic:

Final-artifact exporters should not use unreviewed or tool-assembled variants without subject confirmation. v0.3 uses the shared reviewStatus lifecycle rather than a headline-specific draft boolean.

Resolved decisions:

Open design question: whether a small reference selector is useful enough to include under reference/, so consuming tools do not each invent slightly different matching behavior.

v0.3 Decision: Talking Points

Decision: use top-level talkingPoints.

Alternate names considered: careerNarratives, synthesizedNarratives.

Problem: some career stories are real, polished, and reusable, but they are not a single achievement, a raw private reflection, or a narrative variant of one item. Senior candidates often have a few cross-role stories they use repeatedly:

These are valuable for cover letters, interviews, profile summaries, and screens. They should not be hidden in vendor extensions if they are a common career-memory shape.

Counterpoint: less senior users may not have polished narratives yet. The same concept should help them discover value, not only store finished executive positioning. Prompts and tools should ask questions that pull out under-described evidence:

Decision notes: use top-level talkingPoints because these items can span the whole file: multiple experiences, achievements, reflections, source artifacts, and future application workflows. A person-level location would communicate that the content describes the person, but it would not add useful structure, and it may make cross-career evidence links feel artificially nested. Each talking point should link to supporting evidence. A polished story without links is too easy to overuse.

Minimal shape:

{
  "id": "four-startups-four-outcomes",
  "label": "Four startups, four outcomes",
  "statement": "I have repeatedly joined companies at moments of customer or operating ambiguity and helped turn them into repeatable functions.",
  "uses": ["cover-letter", "screening-call", "executive-summary"],
  "audiences": ["startup-leadership", "customer-success", "sales-enablement"],
  "visibility": "shared",
  "supportingItemIds": [
    "northwind-csa-operating-model",
    "cloudforge-cs-function-buildout",
    "brightline-client-success-scale"
  ],
  "provenance": {
    "source": "interview-derived",
    "date": "2026-05-25",
    "operation": "synthesized-cross-role-narrative",
    "confidence": 0.8
  }
}

Open design note: talkingPoints should not become a loophole for unsupported claims. Curation should treat them as reusable framing backed by linked evidence, not as facts that stand on their own.

Real-session pressure: reusable patterns such as a "parachute" story, an "anticipate the real test" framing, or a repeated "what I do when dropped into ambiguity" narrative had no clean home. They were too synthesized for a single achievement, too polished for a raw reflection, and too portable to remain buried in one cover letter draft. This strengthens the case for first-class talkingPoints with evidence links and review status.

Elicitation pattern: after preserving a raw work story, a tool may look across that story and other evidence for an earned through-line the subject may not have named. This is useful because recognition can prime the next memory: "here is a pattern in three things you told me" often opens more useful recall than direct interrogation. But the pattern must be earned, never manufactured. A through-line should cite at least two independent pieces of the subject's own evidence, be offered as a hypothesis ("does that ring true?"), and be saved only after user confirmation or correction. A rejected through-line is also valuable memory because it records how the subject does not want their work interpreted.

Implementation pressure from the Maria worked example: a talking point can cite the SOC-buildout achievement by ID, and story-bearing reflections need stable IDs for the same reason. Migration notes for the published incubating shape at extensions.user.local.candidateTalkingPoints live in CHANGELOG.md.

Two anonymized example directions:

{
  "id": "regulated-buildouts-pattern",
  "label": "Repeated regulated buildouts",
  "statement": "I have repeatedly joined regulated organizations at moments when the operating model was still forming and helped turn ambiguous work into repeatable systems.",
  "uses": ["cover-letter", "screening-call", "executive-summary"],
  "audiences": ["regulated-operations", "security-leadership", "platform-buildout"],
  "visibility": "shared",
  "supportingItemIds": [
    "healthbridge-soc-buildout",
    "northstar-compliance-platform",
    "meridian-incident-response"
  ],
  "sampleTellings": [
    {
      "label": "Cover letter version",
      "text": "I tend to be most useful when the system works well enough to prove demand, but not yet well enough to scale without judgment.",
      "visibility": "private"
    }
  ],
  "provenance": {
    "source": "interview-derived",
    "date": "2026-05-25",
    "operation": "synthesized-cross-role-narrative",
    "confidence": 0.8
  }
}
{
  "id": "steady-operations-owner",
  "label": "Steady operations owner",
  "statement": "I do my best work when expectations are clear, the work matters, and the team needs someone reliable to own outcomes and keep the process moving without drama.",
  "uses": ["resume-summary", "cover-letter", "screening-call"],
  "audiences": ["operations", "customer-support", "administrative", "healthcare-office"],
  "visibility": "shared",
  "supportingItemIds": [
    "clinic-scheduling-backlog-cleanup",
    "inventory-closeout-process",
    "support-queue-weekend-coverage"
  ],
  "sampleTellings": [
    {
      "label": "Screening-call version",
      "text": "I am happy to own outcomes. I just tend to be better at managing problems than managing people. Give me the boundaries, the priorities, and the people who need help, and I will keep the work moving.",
      "visibility": "shared"
    }
  ],
  "provenance": {
    "source": "interview-derived",
    "date": "2026-05-25",
    "operation": "synthesized-cross-role-narrative",
    "confidence": 0.8
  }
}

These examples are deliberately different. talkingPoints should not only support executive or founder-style arcs. It should also help people describe steady, bounded, reliable work without forcing every career story into leadership theater.

v0.3 Convention: User-Local Extension Namespace

Convention: use extensions.user.local.

Alternate namespace considered: extensions.x-ocf-user.

Problem: the schema recommends domain-name extension keys for vendor/tool-owned data. But users and local workflows also need scratch space that no vendor owns. Early LLM workflows used invented namespaces such as extensions.private.ocf.local for user-local notes.

Open design questions:

Decision: reserve extensions.user.local for user-local scratch metadata and make clear that portable concepts should graduate into schema fields only after repeated use.

Suggested rules:

v0.3 Decision: Review Status Lifecycle

Decision: use reviewStatus.

Problem: real imports and LLM conversations repeatedly need to distinguish:

The field would help importers, curators, and validators avoid treating "in the file" as equal to "safe to use."

Do not overload reviewStatus with evidence strength or trust verification. A value such as source-supported belongs to provenance or a future trust-review layer, not a workflow lifecycle. Likewise, voice-fit concerns such as "not voice checked" may be captured in review notes, voice guidance, or target-specific curation notes until a richer voice model proves its shape.

This item-level lifecycle also replaces the need for an imported-starter file role. A first-session file can be the candidate-owned master from the start, while its imported, inferred, and LLM-mined items remain individually unreviewed until accepted. Curation tools must not use unreviewed items in externally-facing outputs without surfacing them for confirmation.

Decision notes: start with a small review lifecycle for durable user-facing content, user-quoted material, and imported or LLM-suggested material that may be reused in outputs. Leave formal verification tiers for later after more usage data.

v0.3 values:

Potential lightweight object form:

{
  "reviewStatus": "needs-review",
  "reviewNote": "Confirm whether MEDICC meant MEDDIC or MEDDPICC before using in a resume.",
  "reviewedBy": "subject",
  "reviewedDate": "2026-05-25"
}

Open design note: reviewStatus is not the same as truth verification. It is workflow state for whether the item is safe to use in curation. A future trust/verification model may add stronger evidence labels later. Conflicts should usually be represented with provenance plus an openQuestions item unless examples prove that a first-class conflict status is necessary.

v0.3 Decision: Job Descriptions And Media Source Artifacts

Decision: add sourceArtifact.kind: "job-description", plus related media/source kinds.

Problem: resume-plus-job-description workflows need a clear way to store the target job description as source evidence. Without job-description, tools have to use application-draft, manual-note, or other, which blurs a very common artifact type.

Why it matters:

Decision: add these as small enum expansions without a new object shape.

Related artifact-kind gaps from real files:

Open design note: photo and video should not imply that raw media is embedded in the OCF. They can describe retained or referenced artifacts while still using uri, hash, rawIncluded, and private visibility.

v0.3 Decision: Enum Gap Cleanup

Real files have hit several enum or field gaps where careful data had to be collapsed into less precise values:

Decision: treat low-risk additions as v0.3 compatibility expansions unless they create confusing synonyms. Where the schema already has an escape hatch such as basisLabel, improve documentation before expanding the enum.

v0.3 Decision: Work Authorization Display Wording

Problem: normal resumes and application workflows often need a short work-eligibility line: "Authorized to work in the US", "No sponsorship required", "US work authorization", or a similar statement. This is not quite nationality, not quite a certification, and not the same as future availability.

OCF already has structured person.workAuthorization:

{
  "workAuthorization": [
    {
      "country": "US",
      "status": "citizen"
    }
  ]
}

This should not be downgraded or replaced. The structured field preserves the reusable fact: where the person is authorized to work and what kind of authorization they have, without confusing it with nationality, certifications, availability, or clearances.

Decision: add optional user-approved display wording for resumes and applications as renderAs on each work authorization entry.

Shape:

{
  "person": {
    "workAuthorization": [
      {
        "id": "us-work-auth",
        "country": "US",
        "status": "citizen",
        "renderAs": "Authorized to work in the US; no sponsorship required."
      }
    ]
  }
}

Design notes:

Clearances and public-trust-style credentials remain separate. Security clearances, TWIC, site badges, and similar granted credentials can continue to use person.clearances; earned professional credentials remain in certifications.

Out of scope for v0.3 first-class fields:

Tools that need those transient application facts should ask at the time of use. If the user explicitly wants a durable constraint preserved, use goals, cautions, or private notes with date/provenance rather than treating stale intent as career truth.

v0.3 Decision: Location renderAs

Problem: most resume roles have a location line, and OCF already has structured location objects. Organization location is not the same as the role's resume-facing location, and neither should be treated as where the subject lived, was assigned, or had tax-sensitive presence.

The simple v0.3 need is a display/context string on the existing location object, not a full new location model:

{
  "title": "Director of Cybersecurity",
  "locations": [
    {
      "renderAs": "Remote, company based in New York",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "remote": true
    }
  ]
}

Decision: add optional renderAs to $defs.location, which is already used by role positions[].locations, projects, deployments, person locations, and related fields. It may contain "New York, NY", "Remote", "Greater Chicago Area", "New York / Remote", "Remote, company based in New York", or whatever truthful display phrase the user wants associated with that location.

Rules:

Travel is related but different. A role that expected roughly 50% travel across regional hospital sites is historical context: it may affect scope, credibility, or operating context. In v0.3, preserve historical role travel as a supporting fact, note, achievement context, or caution rather than adding a travel-specific schema.

{
  "label": "Travel pattern",
  "statement": "Role required roughly 50% travel across regional hospital sites.",
  "dateRange": {
    "start": { "year": 2022 },
    "end": { "year": 2024 }
  },
  "visibility": "shared"
}

Current willingness to travel for future roles is outside v0.3 scope. Tools that need it for an application should ask at the time of use, not infer it from historical role travel or preserve stale willingness as durable career memory.

Richer location modeling is deferred to v0.4. The following distinctions are real, but too easy to overbuild in v0.3:

Possible future structured shape:

{
  "locations": [
    {
      "label": "New York, NY",
      "renderAs": "New York / remote",
      "kind": "role-location",
      "structured": {
        "city": "New York",
        "region": "NY",
        "country": "US"
      },
      "dateRange": {
        "start": { "year": 2025, "month": 1 }
      },
      "visibility": "shared",
      "note": "Public-facing company market / role location."
    },
    {
      "label": "Las Vegas, NV",
      "renderAs": "US-based",
      "kind": "residence",
      "structured": {
        "city": "Las Vegas",
        "region": "NV",
        "country": "US"
      },
      "dateRange": {
        "start": { "year": 2025, "month": 1 }
      },
      "visibility": "private",
      "note": "Private residence detail; do not infer into public outputs."
    }
  ]
}

Like person.name.renderAs, a future structured location model may need both canonical/private detail and intentional display text. A person may want to preserve where they really were while rendering a different, truthful phrase such as "New York / remote", "US-based", or "Greater Chicago Area." Some workflows need a free-form display value; others require structured city, region, postal code, or country fields.

Full home street address is different from city/region location. Street number and street name are highly sensitive and should not be normalized into ordinary resume/application curation. If a workflow asks for full home address, a tool should ask how the user wants that handled: continue, pause, substitute a less-specific location if accepted, provide it only at a later stage, or stop the application. Different users will make different choices, and most will appreciate being asked before a tool discloses that detail.

Open design questions:

Likely future direction: consider position-level or reusable location entries with explicit kind, renderAs, optional structured city/region/country fields, dateRange, and visibility. Default residence/tax-sensitive location details to private. Treat full street address as high-sensitivity and require explicit user choice before a curator or exporter includes it in an application workflow.

Deferred: Richer Voice Calibration

Likely location: top-level voice plus richer profile material under a first-class field or extensions.user.local.

Problem: OCF has a useful top-level voice field for broad style, preferred phrases, avoid phrases, and notes. Real LLM-assisted cover-letter work showed a deeper need: the tool must learn how this person writes, what makes prior drafts sound unlike them, and which structures reliably produce authentic output.

The key lesson is that voice is not just vocabulary. It can include:

Voice provenance also needs to distinguish at least three sources:

That distinction matters because "sounds like me" is not the same as "I wrote it." Future tooling should be able to prefer subject-authored samples, use adopted wording carefully, and avoid learning from rejected drafts.

Candidate shape to explore:

{
  "voice": {
    "style": "plain-direct",
    "avoidPhrases": ["uniquely positioned", "drive impact"],
    "preferredPhrases": ["worth knowing", "I've been in it"],
    "notes": "Short, declarative, concrete. Prefer a point of view over credential stacking."
  },
  "extensions": {
    "user.local": {
      "writingVoiceProfile": {
        "calibrationSources": {
          "authentic": ["cover-letter-2021-cs"],
          "antiPatterns": ["cover-letter-2024-ai-1"],
          "canonicalExample": "tabs-cover-letter-2026-05"
        },
        "structuralTemplates": [
          {
            "kind": "cover-letter",
            "name": "intro-three-points-outro",
            "rule": "Use a short take-first opener, three concrete points, and a direct close. Do not pad to meet a length target."
          }
        ],
        "namedPatterns": [
          {
            "name": "filter-preempt",
            "rule": "If a reader may filter the subject out for an obvious reason, name it directly and explain why it should not disqualify them."
          },
          {
            "name": "responsive-close",
            "rule": "Only use a playful or unusual close when it responds to a specific prompt, value, or question in the target artifact."
          }
        ],
        "processRules": [
          "If the user says a draft does not sound like them, revise structure before swapping words.",
          "Prefer one concrete proof per claim, then stop."
        ]
      }
    }
  }
}

Open design questions:

Decision: keep the current voice field as the portable simple layer, document richer calibration under extensions.user.local for now, and revisit after more users test whether voice profiles help future LLMs react to them rather than to a generic professional ideal.

Deferred: Trust Review Space

Problem: OCF has provenance, confidence, and review status, but not a formal verification model. That is acceptable for v0.3. A premature verification enum risks implying a rigor the file may not have.

Decision for v0.3: leave space for trust review without overdesigning it. The schema should support future outside review, recruiter/headhunter review, document support, peer review, manager attestation, credential verification, or other signals, but v0.3 avoids pretending we know the right model before more people use the format.

Practical near-term note: a headhunter, coach, or third-party tool may create a third-party-working OCF about a subject and mark which items that workflow has reviewed. That review may never enter the subject's candidate-owned master. The schema must stay clear about subject, controller, and editor.

Non-goal: OCF is not a proof system. It preserves claims, evidence context, source pointers, review state, and cautions so people and tools can behave honestly. It should not adjudicate institutional truth or encode every external evidence rule. Consumers, registries, credential issuers, employers, courts, schools, and other institutions remain responsible for their own verification decisions.

Documentation Guidance: Claim Design And Cautions

These principles probably belong in curation, cautions, and LLM-operating documentation more than in schema fields. They should shape v0.3 examples and docs without becoming a premature verification model.

v0.3 Decision: v0.2 Compatibility Renames

v0.2 contained several derived names even though the public language moved toward curation and export:

v0.3 replaces these with curation/export lineage language:

Migration notes live in CHANGELOG.md; tools that intentionally migrate v0.2 files should preserve the old meaning while writing the v0.3 fields.

The provenance value interview-derived remains useful and should not be removed merely because it contains the word derived; it means a fact came from a conversation rather than from a static artifact.

Decision: meta.fileRole is the limited lifecycle/purpose field. meta.source.kind keeps origin mechanisms such as authored, imported, converted, merged, and translated; lifecycle-like values such as derived, curated, or exported do not live there. Curation/export lineage is expressed through fileRole, parentFileId, parentVersion, and lineageNotes.

Boundary: imported means built from unstructured or semi-structured inputs such as resumes, LinkedIn exports, notes, images, transcripts, or conversation; converted means mechanically transformed from another structured schema such as JSON Resume or LER-RS where field mapping, not judgment, did most of the work.

Migration rule for old files: when a v0.2 file has meta.source.kind: "derived", remove that lifecycle value during v0.3 migration and express the relationship through the new lineage fields instead. The migrated file should use the appropriate fileRole, plus parentFileId, parentVersion, and lineageNotes when it was prepared from another OCF file.

Migration rule for imported starters: when a v0.2 file has meta.fileRole: "imported-starter", migrate it to meta.fileRole: "candidate-master" if it is the user's working career memory. Keep meta.source.kind: "imported" to preserve how the file began, and default imported, inferred, or LLM-mined items without review state to reviewStatus: "unreviewed". That preserves the trust posture the old file role encoded while moving review state to the items.

Partly Shipped / Deferred: Export Lineage and Staleness

Problem: when a master changes after an export, users and tools need a way to know whether the exported artifact is stale. v0.3 has lineage fields, but it does not fully define export freshness behavior.

v0.3 ships:

Deferred:

Open design note: OCF should still avoid prescribing git, cloud history, or app snapshots. The schema-level need is narrower: tools need enough lineage and review state to avoid overwriting a candidate-owned master with a reduced file, stale export, or unaccepted replacement.

Deferred: Size And Sharding Guidance

Problem: master OCF files can grow past comfortable LLM context budgets, especially when they preserve source artifacts, longform reflections, sales history, voice samples, and multiple application iterations. A single ~190KB master can be workable today but brittle once it grows through many versions in a short period.

Candidate guidance:

Open design questions:

Deferred Ideas

These may be useful but should not pull v0.3 away from the core. See v0.4 planning notes for the active parking lot, including career tracks.

The narrower pattern is still the project center: preserve career memory accurately, curate it for a purpose, and export what the recipient needs.