OKF Conformance — frontmatter, indexes, generated traceability

Promoted docs are born OKF-conformant so future maintenance agents navigate them index-first instead of grepping the corpus — and so that a repo whose toolchain enforces frontmatter accepts them unchanged. This reference defines the frontmatter promote stamps, the docs/okf.yaml bootstrap, and the generation sequence.

Frontmatter templates

Stamp a YAML block as the FIRST lines of every promoted concept doc (requirements, ADRs). The body below the block is the staged content, unchanged except for FR-Local-N → FR-NNN swaps.

FR / NFR (type is Requirement for both — the FR/NFR split lives in the id prefix):

---
id: FR-042
type: Requirement
status: Documented
title: Place a new order
description: User submits a cart and receives an order ID.
adrs: [ADR-007]
specs: [tests/Acme.Specs/Features/Orders.feature]
---

ADR:

---
id: ADR-007
type: ADR
status: Accepted (retroactively)
title: JWT authentication
description: All API endpoints authenticate via JWT bearer tokens issued by the auth service.
---

Field sourcing rules:

• title — the FR-Local heading text (split mode) or the unit name (bundle mode). ADRs: the ADR title.
• description — the FR-Local **Description** one-liner (already single-sentence by Writer-template construction). Bundle mode: first sentence of the unit's cited ## Purpose; if Purpose is a recorded gap and no FR description exists, HALT and ask — never invent (describe-only pact). ADRs: first sentence of the Decision section.
• Single-line values only. The gate's parser is line-based — a multi-line value silently truncates in the index and projection with no error. Collapse to one sentence; drop internal newlines.
• status: Documented for promoted FRs — the behavior is live in the legacy system but its spec proof is pending (Coverage TODO in the projection). Never stamp Done: reverse-engineered specs describe behavior, they do not verify it, so Done should be earned by an observed-GREEN acceptance run — and a repo whose toolchain enforces that will reject a Done with no run behind it. Lifecycle: Documented → dev team implements protocol drivers → scenarios GREEN with a logged run → flip to Done.
• adrs — flow list of promoted global ADR IDs the unit's Traceability section links. Omit the key when empty.
• specs — flow list of repo-relative .feature paths generated for this FR (paths are deterministic once the runner is detected, so stamp before the files are written). Omit when no feature is generated.
• ADRs carry no relation keys — the projection derives ADR → Requirements from the FRs' adrs lists — the child declares the relation, so an ADR needs no keys of its own.
• No ## Bet block on promoted FRs — inventing an expected outcome for existing behavior violates the describe-only pact. When a dev team later ships a feat(FR-NNN) change against a promoted FR, that is the point at which a real Bet can be written, and any commit gate the project runs will correctly ask for one then.

docs/okf.yaml bootstrap

Write ONLY when docs/okf.yaml is absent. Never modify an existing manifest; never flip an existing repo's traceability mode.

Do not add a profile: key. A profile declares that some external toolchain owns the bundle and runs its own generator. Stamping one here would strand the repo: OKF maintenance tooling is expected to halt on a profiled bundle and defer to that toolchain, so a profile naming a generator the project does not have leaves the docs unmaintainable by anything. Only add a profile: if the project genuinely runs its own OKF toolchain, and then let that toolchain's own tooling write it.

okf_version: "0.1"
concept_folders:
  - requirements
  - adr
  - bugs
required_keys:
  - id
  - type
  - status
  - description
reserved_filenames:
  - index.md
  - log.md
index_filename: index.md

• Never write traceability: generated. The key declares a standing sync obligation — that the repo can regenerate TRACEABILITY.md as a projection on every change — and promote has no generator for it. Bootstrap the manifest without the key and use the curated table append (references/traceability-row-template.md).
• Report in the final summary that okf.yaml was written: it arms the OKF commit gate for any contributor in a repo whose toolchain enforces OKF — intended, and the staged diff is human-reviewed before commit.

Generation sequence

Indexes are generated by the okf-maintain skill, which owns the OKF index grammar and ships its own generator. In Claude Code, dispatch it with the Skill tool using the fully namespaced name — never hand-type a node invocation, and never reach into the other plugin's directory for its script:

Skill: okf-maintain:okf-maintain
Argument: regenerate every index.md under docs/ (bundle root: the repo root)

In Codex, discover the installed $okf-maintain:okf-maintain skill, read its SKILL.md, and execute that skill's workflow with the same argument. This is a public skill invocation, not a Doc-This worker dispatch. The skill resolves its own installed script location. If it is unavailable, use the fallback below.

One dispatch covers the whole bundle: okf-maintain walks docs/ and writes each per-folder index.md plus the docs-root index.md in a single pass, honouring any .okfignore. Run it AFTER every concept doc is written — it reads whole folders, so existing docs are re-indexed alongside the new ones automatically.

If okf-maintain is unavailable, hand-write the per-folder indexes in the frozen format below and say so in the final summary.

Traceability mode decision table

TRACEABILITY.md is always curated here — promote appends rows, it never projects them.

Fallback: hand-written index format

Only when okf-maintain is unavailable. A later regeneration adopts a hand-written index only when it renders every row identically; on any difference the generator leaves the file untouched and reports it as a foreign index, and the hand-written rows are what the repo keeps living with. So write rows the generator can reproduce: every concept doc carries id and status, and every description stays inside the index's one-sentence cap — a description past the cap is dropped from the generated row rather than truncated, which is a difference like any other.

# <folder-basename>

<!-- generated by okf.mjs - do not edit; regenerate after changing concept frontmatter -->

* [<id> — <title>](<file.md>) - **<status>** — <description>

Rules: one row per concept doc (skip index.md/log.md); link text is <id> — <title>, or bare <id> when no title; rows sorted lexicographically by id; exactly one trailing newline. Root index: same header/marker with one * [<folder>](<folder>/index.md) per present concept folder — skip the root index entirely when fewer than 2 declared folders exist. Never hand-write the TRACEABILITY projection — its coverage semantics come from the execution ledger.

Existing-index safety

Read the marker line of any target index.md that already exists. Two strings mean okf.mjs owns the file and regenerating it is safe — the default dialect's <!-- generated by okf.mjs - do not edit; regenerate after changing frontmatter --> and the profiled dialect's <!-- generated by okf.mjs - do not edit; regenerate after changing concept frontmatter -->.

Any other marker line is not this generator's. okf-maintain recognises one legacy marker and adopts such a file, but only when regenerating reproduces every row exactly; on any difference it leaves the file untouched and reports it as a foreign index. Treat a foreign-index report — and an index.md carrying no marker at all — as hand-authored: HALT and ask before overwriting (extends promote's never-overwrite rule to indexes).

Re-promotion maintenance loop

After /doc-this --incremental refreshes staged units, re-running promote hits the FR filename collision halt for already-promoted units — pick "diff and merge", keep the existing frontmatter block (update status/description only if behavior changed), then re-run the generation sequence so indexes and the projection reflect the merge.