feat(knowledge): add opt-in OKF v0.2 export for reviewed candidate profiles

[akoita]

Outcome

Allow a candidate to explicitly export one exact reviewed canonical profile as a deterministic, local Open Knowledge Format (OKF) v0.2 bundle that humans and other agents can inspect without DraftLoop-specific tooling.

OKF should be an interchange and human-readable derived-knowledge layer. It must not replace the portable SQLite Candidate Knowledge Base (CKB), its managed source bytes, immutable source/version identity, lifecycle evidence, selection snapshots, backup/restore, or run history.

Why this may help DraftLoop

OKF formalizes the LLM-wiki pattern as Markdown concept files with YAML frontmatter, links, provenance, trust, and lifecycle metadata. That shape could make reviewed candidate knowledge portable, diffable, Git-friendly, and consumable by other local tools while preserving DraftLoop's stricter internal contracts.

The likely value is interoperability and candidate ownership, not better retrieval by itself. DraftLoop's current application-grade priority remains exact CKB-scoped lexical retrieval and source-grounded drafting in #80.

Expected impact

Benefits

• Human-readable export that is not coupled to DraftLoop's SQLite schema.
• Portable, agent-friendly concepts for experience, projects, skills, education, certifications, and other reviewed profile facts.
• Bundle-local provenance and lifecycle signals that can complement DraftLoop's existing evidence traceability.
• A future integration surface for local knowledge tools without requiring Google Cloud or another service.

Costs and risks

• OKF has an open taxonomy, while DraftLoop canonical profiles use bounded categories, deterministic IDs, exact source/version provenance, and explicit conflict/duplicate/omission issues. Mapping can be lossy unless it is designed and tested explicitly.
• YAML/frontmatter and Markdown links add parser, traversal, resource-exhaustion, and untrusted-content attack surfaces.
• OKF resource, sources, actor, and timestamp fields can leak original URLs, host paths, provider identity, or sensitive candidate data.
• OKF verified means a recorded review signal; it must not be presented as independent factual verification of a candidate claim.
• Exported plaintext is an independent copy outside CKB retention, deletion, and backup guarantees.
• Supporting a versioned external format adds compatibility and maintenance cost. The implementation must pin v0.2 and handle unknown types/keys without silent data loss.

Scope

• Define a deterministic mapping from an exact reviewed canonical profile version to OKF v0.2 concepts.
• Export only after explicit destination approval, with no network or provider calls.
• Represent provenance using opaque bundle-relative references; do not export machine-local paths, original source URLs, credentials, raw provider payloads, hidden reasoning, or unreviewed raw material.
• Add bounded OKF conformance and privacy validation for the generated bundle.
• Generate stable filenames, ordering, internal links, and an index.md suitable for progressive disclosure.
• Record the supported OKF version and surface unsupported mappings rather than inventing or silently dropping facts.
• Document that the OKF bundle is an interchange artifact, not the canonical CKB backup or evidence source of truth.
• Capture the decision and mapping in an ADR; synchronize architecture, roadmap, README, privacy, and threat-model documentation where affected.

Suggested ownership:

• A framework-free OKF parser/serializer/validator package for bundle mechanics.
• packages/schemas for DraftLoop-owned import/export DTOs only; OKF must not replace canonical profile schemas.
• packages/application for profile-to-OKF mapping, approval, selection, and privacy policy.
• CLI first through the shared application contract; desktop parity must reuse the same contract.
• Existing packages/storage CKB persistence remains canonical and should not require a migration for the first slice.

Non-goals

• Replacing the SQLite CKB, its backup format, or workspace/run persistence.
• Importing or merging arbitrary OKF bundles.
• Using OKF as the feat(retrieval): build knowledge-base-scoped lexical RAG with lifecycle evidence #80 retrieval index or changing provider payloads.
• Automatic LLM-maintained wiki writes or background synchronization.
• Publishing to Git, Google Knowledge Catalog, or any cloud service.
• Following external links, fetching resource URLs, or executing OKF computations, executors, or attesters.
• Claiming that candidate-provided evidence has been independently fact-checked.

Acceptance criteria

• Export takes one exact reviewed profile version and its exact path-free CKB selection snapshot; draft profiles or unresolved review issues are rejected.
• Output is a deterministic, conformant OKF v0.2 bundle containing UTF-8 Markdown concepts with non-empty type fields, stable names/order, bundle-relative links, and an index.md.
• Repeating export from the same immutable input produces byte-identical semantic content, excluding no uncontrolled timestamps.
• Export requires explicit destination approval and performs no network or provider calls.
• Output contains no host paths, original URLs, credentials, raw provider payloads, hidden reasoning, or unreviewed source material.
• Candidate review is represented without implying independent factual verification.
• Validation is bounded and detects malformed frontmatter, non-UTF-8 content, traversal paths, symlinks, excessive depth/size/count, invalid reserved files, broken internal links, and unsupported mappings.
• Unknown OKF keys/types are preserved where round-tripped or surfaced explicitly; unsupported canonical facts are never silently invented or dropped.
• Existing CKB backup/restore, retention/deletion, workspace FTS/BM25 retrieval, and provider payloads remain unchanged.
• Tests cover deterministic output, semantic completeness, privacy redaction, malformed frontmatter, traversal/symlink cases, conflicts/omissions, and trust-language semantics.
• An ADR records the mapping, threat/privacy boundaries, lifecycle ownership of exported copies, supported OKF version, and the decision on whether import warrants a separate issue.
• A representative sanitized profile demonstrates that the bundle is useful to a second consumer without increasing unsupported-claim or provenance ambiguity.
• pnpm validate passes.

Roadmap and dependencies

Treat this as Later / controlled expansion until the evidence-backed CV workflow is validated. Do not add it to the v0.8 milestone or make it a prerequisite of #80. Implementation should build on the stable reviewed-profile contract in #66 and the existing portable CKB boundaries in #78/#111.

Any later OKF import or retrieval integration needs separate decisions for conflict resolution, provenance redaction, retention/deletion ownership, untrusted Markdown handling, index freshness, and CKB isolation.

References

• Google Cloud introduction to OKF
• OKF v0.2 specification
• Karpathy's LLM-wiki pattern
• roadmap: automate the proven application-grade CV workflow #4
• feat(profile): build a persistent canonical candidate career profile #66
• feat(knowledge): manage reusable candidate knowledge bases and source lifecycle #78
• feat(retrieval): build knowledge-base-scoped lexical RAG with lifecycle evidence #80
• feat(knowledge): bind applications to explicit CKB and source-version snapshots #111