unknown-knowledge 2.1.0

package/payload/protocol/AGENTS.md

@@ -0,0 +1,239 @@
+# AGENTS.md — navigation contract + runtime loop (PRD §7)
+
+> Paths in this document are client-relative — relative to the vendored kit
+> root after init (`ontology/…`, `engine/…`, `protocol/…`). In the kit repo
+> itself these live under `payload/`. Commands are written to run from the
+> **repo root** with the kit dir at its default name `unknown-knowledge/`;
+> substitute your chosen kit dir name if it differs.
+
+You are a coding agent in a repo seeded with the unknown-knowledge kit: three
+YAML stores that map the system, a deterministic engine that checks the map,
+and this protocol. This file is the platform-agnostic contract — per-platform
+wrapper files are thin pointers here. Follow it on every request.
+
+Two `--root` conventions, stated once:
+
+- Every store-reading CLI (`resolve.js`, `preflight.js`, `validate.js`,
+  `validate-values.js`, `audit.js`, `survey-map.js`) takes `--root` as the
+  **repo root** (default: cwd). The stores are auto-located at
+  `<root>/unknown-knowledge/`; source-of-truth pointers resolve against the
+  repo root (§9.1).
+- `log-entry.js` takes `--root` as the **kit dir** (the directory containing
+  `logs/`), e.g. `--root unknown-knowledge`.
+
+## The SSOT contract — the map is never the fact
+
+Stores hold **claims and pointers**; source files hold **facts**. Prose in
+any store — summaries, definitions, even `enumerates` values — is navigation,
+never truth. The rules that follow from this:
+
+- **Always follow the pointer and read the source.** Never answer from a
+  concept's prose or its `enumerates` values; they exist so the engine can
+  diff them against the artifact, not so you can skip the read.
+- **Reference by concept ID and path, never by copied value.** Anything you
+  write into a store or a log carries `K-NNN` / `D-NNN` / leaf accession
+  (`L-NNNNNN`) and
+  file paths — copying a value out of source into prose mints a second,
+  uncheckable claim.
+- **Trust is per-run.** A verdict is valid for the run that computed it;
+  never cache or carry one across sessions (D-011 — a stale "trusted" is a
+  false all-clear).
+
+## Store navigation contract
+
+Three stores, one navigational grammar: **`_catalog.yaml` → `_rules.yaml` →
+entries** (`classes/*.yaml`, tree leaves, `entries/*.yaml`). Enter through
+the catalog, honor the rules file, then read the entry the catalog names —
+never grep the store tree cold, and never raw-traverse the repo (triage
+`engine/survey-map.js` output instead).
+
+| Store | Truth anchor | Points | Write gate |
+|---|---|---|---|
+| `ontology/` | the artifact (code) | inward — `source-of-truth` into the repo | proposal-first; updates travel with the code change |
+| `knowledge/` | the world | outward — `citations` to external evidence | human-only; the kb-build skill is the sole write path |
+| `decisions/` | the team | sideways — typed refs to concepts & leaves | gated append-mostly; see the authoring path below |
+
+Cross-reference semantics (knowledge leaves, §3.2):
+
+- **`class-elsewhere` is a redirect — follow it.** The content lives at the
+  target accession; the leaf you found is a signpost, not an answer.
+- **`see-also` is context.** Related material; consult when useful, never a
+  substitute for the leaf you resolved.
+- **`including` is standing room.** Candidate topics parked under a heading —
+  not authoritative, never citable as fact.
+
+All cross-store references travel by ID (`used-by`, `confusable-with`,
+`rationale`, `relates-to`, cross-refs) — content is never embedded across
+store lines. A `confusable-with` entry on a resolved concept is an explicit
+disambiguation: confirm you have the right concept before acting on it.
+
+**`knowledge/derived/` is engine output, not a store.** Browse trees and the
+resolution index are regenerated by `engine/derive.js` and deleting them loses
+nothing. Two rules when you read one: never hand-edit a derived file, and
+**never cite a synthesized call number** (`SPO/ODD/REF·L-000117`) — it is a
+display string naming a position in one projection, it differs between trees,
+and the citable half is the accession inside it. See
+`protocol/derived-layer.md`.
+
+## The runtime loop (every request)
+
+`RESOLVE → PREFLIGHT → GATHER → ACT → RECORD`
+
+### 1. RESOLVE — request terms → concepts
+
+```
+node unknown-knowledge/engine/resolve.js "export format" --json --root .
+```
+
+Query terms are positional (joined into one query); results come scored with
+`source-of-truth` pointers, `confusable-with` disambiguation, and knowledge
+entry points. Exit 0 = the lookup ran (hits or none); exit 2 = it never ran —
+stop, that is an engine failure, not an empty result.
+
+**Zero resolution is a normal outcome** (common in month one — bootstrap is
+deliberately non-exhaustive). Proceed **without store claims**: fall back to
+search within the paths `survey-scope.yaml` includes, and append a
+`retrieval-miss` finding (RECORD, below) only when the topic plausibly should
+be mapped — an unmapped area the scope excludes is expected, not a miss.
+
+### 2. PREFLIGHT — deterministic verdicts on what you resolved
+
+```
+node unknown-knowledge/engine/preflight.js --concepts K-101,K-102 --json --root .
+```
+
+One verdict per concept — `trusted` / `quarantined` / `unknown` — computed by
+engine code, never by your judgment. Store-wide failures degrade every
+requested verdict to `unknown`. Exit codes: 0 all trusted, 1 quarantines
+present, 2 engine failure / check-never-ran. What you DO with a verdict is
+the conduct policy below. Add `--log --today <YYYY-MM-DD>` so quarantine
+findings auto-append (one fragment per quarantined concept).
+
+With an empty/omitted `--concepts`, preflight validates store health only and
+exits on the store verdict — the zero-resolution branch still preflights.
+
+### 3. GATHER — read the fact, not the map
+
+Follow each resolved concept's `source-of-truth` pointer and **read the
+file**. One targeted read per fact. Knowledge leaves: read the leaf body and
+follow `class-elsewhere` redirects. Never substitute a summary, an
+`enumerates` list, or a leaf heading for the artifact.
+
+### 4. ACT — execute, then attribute before committing
+
+Do the work. Before committing, reverse-look-up every file you changed:
+
+```
+node unknown-knowledge/engine/resolve.js --paths src/registry/export-formats.ts,src/types/color-space.ts --json --root .
+```
+
+This lists every concept whose pointer covers a changed path (folder pointers
+match nested files). **Update those concepts in the same commit** — the store
+change rides your normal PR — and re-run both validators filtered to them:
+
+```
+node unknown-knowledge/engine/validate.js --concepts K-101,K-108 --root .
+node unknown-knowledge/engine/validate-values.js --concepts K-101,K-108 --root .
+```
+
+Exit 0 = clean; exit 1 = findings — fix the store or the code before
+committing; exit 2 = the check never ran — stop. These validators are
+blocking-grade; `engine/audit.js` is advisory (proposals for review) and is
+never a gate.
+
+Where the client has wired the seeded hooks (`hooks/pre-commit`,
+`hooks/reverse-lookup`), both of these run automatically: the pre-commit hook
+runs the blocking validation before the commit exists, and the reverse-lookup
+hook runs the `--paths` lookup over the staged diff. Each is a thin wrapper
+around the command above and exits with its code, unchanged — so a wired repo
+enforces this step mechanically rather than depending on you to remember it.
+Run the commands yourself anyway: seeing the findings before the commit is
+cheaper than being refused by it, and a hook the client never wired enforces
+nothing.
+
+### 5. RECORD — append findings when a trigger fires
+
+See capture obligations below. Findings, misses, and gaps are appended via
+`engine/log-entry.js` — never by hand-editing YAML.
+
+## Conduct-on-verdict policy (D-011)
+
+> **CLIENT-EDITABLE.** Verdicts are deterministic engine facts; what a
+> session does about one is policy in this markdown, which you (the client)
+> own. The table below is the recommended default — quarantine-and-continue.
+> A stricter shop may edit `quarantined` to fail-stop. What is NOT editable:
+> the engine's verdicts, exit codes, and evidence — and a policy edit must
+> never tell an agent to bypass a gate or trust quarantined claims.
+
+| Verdict / outcome | Conduct (recommended default) |
+|---|---|
+| `trusted` | Proceed. The verdict is fresh this run; never cache it. |
+| `quarantined` | **Quarantine-and-continue**: continue the task, but do NOT trust the concept's claims — gather from the source artifact directly (falling back to survey-scoped search if the pointer itself is the problem), and make sure the quarantine finding was appended (run preflight with `--log --today <date>`; it does this for you). |
+| `unknown` | Treat as unverified — draft/proposed concepts and store-wide degradations land here. Work from the source artifact; do not present store claims as checked. |
+| exit 2 — engine failure / check-never-ran | **STOP.** A check that never ran is a blocking defect, never a silent pass. Report the engine error; do not proceed as if preflight passed. |
+
+## Gate rules
+
+- **All store mutations beyond logging are human-gated.** Agents draft;
+  humans approve through the normal PR gate. Logging (`logs/`) is the one
+  agent-writable surface, and only via `engine/log-entry.js`.
+- **Ontology** edits are proposal-first and travel with the code change they
+  describe (ACT step). **Knowledge** is written only through the kb-build
+  skill — cited, human-gated. **Decisions** follow the authoring path below.
+- **Never wire a parser you authored into the validator in the same session**
+  (D-005). Unextractable anchors go to the miss-log; the governed path is
+  `protocol/new-kind-pipeline.md`.
+- **Never bypass a gate to go green**: do not delete or edit findings to
+  unblock a merge, do not hand-edit log YAML, do not skip the ACT re-run,
+  do not pass `--no-verify` or unwire a hook to get a commit through,
+  treat `audit.js` output as advisory (never blocking), and do not carry a
+  cached verdict. Autonomy is graduated per change-category by recorded decision
+  (category `trust`), never assumed.
+
+## Capture obligations — the five triggers
+
+Append a finding whenever one fires; capture is cheap and judgment-free
+(consolidation happens later, in reflect). The `trigger` vocabulary is closed
+(`schemas/finding.schema.json`):
+
+| Trigger | Signal |
+|---|---|
+| `correction` | the user states the agent / a store is wrong |
+| `recurrence` | the same thing is asked for repeatedly |
+| `retrieval-struggle` | found, but slowly or indirectly (resolver missed; aliases lacking) |
+| `retrieval-miss` | could not find it at all (and the topic plausibly belongs in scope) |
+| `quarantine` | engine-attributed: preflight flagged a concept and the session proceeded degraded (auto-appended by `preflight.js --log`) |
+
+Append with the helper — `--date` is mandatory and injected, never wall-clock:
+
+```
+node unknown-knowledge/engine/log-entry.js create --log findings --date 2026-07-08 \
+  --root unknown-knowledge \
+  --entry '{"trigger":"correction","summary":"correction: K-101 src/registry/export-formats.ts","consulted":{"concepts":["K-101"]}}'
+```
+
+Each finding's `consulted:` refs ARE the consultation trail. Sibling logs,
+same helper: `--log misses` (anchors no extractor kind can read) and
+`--log gaps` (requests no protocol/skill could route).
+
+**Capture content policy (§3.4 — not optional):** summaries carry concept IDs
+and file paths only — **never verbatim user text, quoted session content, or
+secrets**. The `session` field is an opaque ID. Committed fragments are
+permanent git history in this repo and are reviewable content like any other
+PR change.
+
+## Decisions-authoring path (§3.5)
+
+When your work surfaces a decision — a trade-off taken, a graduation of
+trust, a scope call — it gets recorded, not lost in a PR description:
+
+1. **Draft** a decision entry in `decisions/entries/` with a provisional
+   date-suffixed id (`D-2026-07-08-<slug>`), `status: proposed`, and
+   `relates-to` refs to the concepts/leaves/decisions it touches.
+2. **Propose** it through the normal PR gate — anyone (agent or human) may
+   draft a proposed entry; that IS the decisions store's write path.
+3. **Human gate**: the steward assigns the final `D-NNN` at acceptance
+   (minted within range, never renumbered once published). Status moves
+   `proposed → accepted → addressed → archived` (plus `rejected` /
+   `superseded`); transitions never rewrite `context`/`decision` — the store
+   is append-mostly, and supersession chains must resolve and stay acyclic.

package/payload/protocol/derived-layer.md

@@ -0,0 +1,174 @@
+# The derived layer: browse trees, call numbers, and the recall gate (UCS-1158)
+
+> Paths in this document are client-relative — relative to the vendored kit
+> root after init (`knowledge/…`, `engine/…`, `protocol/…`). In the kit repo
+> itself these live under `payload/`.
+
+Everything discovery-shaped in this store is **derived**: computed from the flat
+set of leaves, written into one directory, and thrown away without loss.
+
+```
+knowledge/
+├── _registries/          # governed vocabularies — AUTHORED
+├── design-system/…       # leaves — AUTHORED
+└── derived/              # engine output — DISPOSABLE
+    ├── index.json                 # the resolution index
+    ├── tree.domain-form.md        # browse tree, steward ordering
+    └── tree.form-domain.md        # browse tree, agent ordering
+```
+
+Regenerate it with the `derive` surface:
+
+```sh
+node unknown-knowledge/engine/derive.js --root . --today 2026-08-16 --write
+```
+
+Two verbs, and the read-only one is the default — the same shape `phoenix` uses:
+
+| Verb | Effect | Exit |
+|---|---|---|
+| `--check` (default) | compare the layer on disk against what the store projects | 0 up to date / 1 findings |
+| `--write` | replace the directory with what the store projects | 0 written |
+
+## Deleting it loses nothing
+
+That is the design claim, and it is enforced rather than promised:
+
+- **Nothing authored lives here.** No field, no id, no decision. Every byte is a
+  function of the leaves.
+- **Nothing reads it back.** The loader skips `derived/` by name. Browse trees
+  are markdown under `knowledge/`, exactly like leaves, so the name is the only
+  thing distinguishing engine output from a record — and if the walk descended,
+  a generated tree would fail the leaf schema and the store's health would
+  depend on a directory whose whole contract is that it is disposable.
+- **Regeneration is byte-identical.** Delete the directory, re-run `--write`,
+  and the bytes match. A round-trip test asserts exactly that; it fails the
+  moment something unreproducible starts living here.
+- **A file no axis generates is a finding.** `derived-unexpected` fires on
+  anything in the directory the engine did not produce, because a regeneration
+  would delete it.
+
+Never hand-edit a derived file. `--check` reports it as `derived-stale`, and the
+next `--write` overwrites it.
+
+### Commit it, or ignore it — both work
+
+The kit does not decide this for you, because the two choices trade off real
+things and the answer is local:
+
+- **Commit it** and browse trees are readable on the forge, and a reviewer sees
+  a reclassification's effect in the diff. The cost is that every PR touching a
+  leaf also touches the trees, and a contributor who forgets to regenerate lands
+  a stale artifact — which `derive --check` catches in CI.
+- **Ignore it** (`knowledge/derived/` in `.gitignore`) and the store's history
+  stays free of generated churn. The cost is that a reader has to run the
+  command to browse.
+
+Either way nothing is lost, because nothing here is authored. If you commit it,
+run `derive --check --today <date>` in CI so a stale tree is a failed build
+rather than a misleading document.
+
+## Plural browse trees
+
+The store projects along **two axes**, from one flat set of leaves:
+
+| Axis | Ordering | For |
+|---|---|---|
+| `domain-form` | domain → form | stewards — subject matter first, the way a person holds a library in their head |
+| `form-domain` | form → domain | agents — kind of knowledge first, narrowed by subject afterwards |
+
+Plural is the point. The store's first life filed each leaf at one position in
+one tree, and that position was also its identity — so a leaf in the wrong place
+stayed there, because moving it broke every citation to it. Accession identity
+removed that cost, and the derived layer spends the refund: a projection commits
+to nothing, so there can be as many as there are useful reading orders.
+
+A third axis is one row in `AXES` (`engine/lib/derived.js`). Nothing else names
+an axis.
+
+### Stale and draft leaves are annotated, never hidden
+
+A demoted leaf appears in every tree it belongs in, wearing its reason:
+
+```
+- **frontend/** (2)
+  - **runbook/** (1)
+    - `ENG/FRO/RUN·L-000171` Visual regression triage playbook — **demoted** (stage, time)
+      - stage: stage "draft" is pre-promotion — no moderator has certified this leaf's citations
+      - time: verified 154 day(s) ago, past the 90-day limit for volatile knowledge
+```
+
+Hiding it would make the tree lie by omission: a steward would read an empty
+shelf as "we know nothing about this", when the truth is "what we know has
+rotted" — opposite calls to action. Demotion sorts a leaf last within its node
+and does nothing else.
+
+Both demotions come from the surfaces that already own them — `timeVerdict` and
+`isPrePromotionStatus` — so a leaf cannot read stale in a tree and trusted in
+the resolver.
+
+**Time verdicts need `--today`.** Staleness is measured from an injected date,
+never the wall clock. Without `--today` the time verdicts are `skipped` and every
+artifact says so in its header; it is never a silent pass. Stage demotion needs
+no date and still applies.
+
+## Call numbers are display strings, never identities
+
+A call number names a leaf's position in one projection:
+
+```
+SPO/ODD/REF·L-000117      in the domain-first tree
+REF/SPO/ODD·L-000117      the SAME leaf, in the form-first tree
+```
+
+**Cite the accession id. Never a call number.** A call number is the most
+tempting thing in this layer to paste into a `see-also` — compact, readable,
+positional, everything the retired dotted notation was. If that paste ever
+resolved, the accession inversion would reverse itself one convenient citation at
+a time, and references would break on reclassification again.
+
+It cannot resolve, and the defense is structural:
+
+1. **The grammar refuses it.** The middle dot (`·`) appears in no id space, and
+   a test checks every synthesized call number against every grammar in
+   `ID_GRAMMARS` — so a new id space that accepted them would fail the day it
+   was added.
+2. **Nothing accepts one.** Citations are `leaf-ref`, accession-only. A call
+   number in a citation field is both a `pattern-mismatch` and an
+   `unresolved-ref`.
+3. **The accession travels inside it.** The tempting thing to paste contains the
+   correct thing to paste.
+
+The same leaf reads differently on each axis, and that is deliberate: a call
+number describes a position, and a leaf holds one per projection. A string that
+looked stable while changing meaning between trees would be worse than one that
+visibly reorders.
+
+## Embedding recall: the slot and the gate
+
+Probabilistic recall has **exactly one architectural position**, declared in
+`engine/lib/derived.js` as `RECALL_SLOT`:
+
+| Property | Value | Why |
+|---|---|---|
+| `location` | `derived` | recall lives in the disposable layer and nowhere else — deleting `derived/` deletes every probabilistic artifact the system has ever computed |
+| `consulted` | `after-deterministic-exhausted` | recall runs only when the deterministic layer returns nothing; consulting it earlier would let a similarity score outrank a declared edge |
+| `output` | `proposals` | it may propose |
+| `citable` | `false` | a proposal is never a citation |
+| `persistable` | `false` | a proposal never enters the store |
+
+**The implementation is out of scope, deliberately.** This ticket ships the slot
+and the gate; model selection and semantic search are not built here. What the
+slot does is fix the position so it cannot be occupied somewhere worse. An
+embedding cached in frontmatter would be a guess sitting in the same file as
+cited facts, indistinguishable to every later reader — which is precisely the
+failure the three constraints above prevent.
+
+`gateProposal()` refuses **every** proposal, by construction. There is no
+argument that admits one. A future recall implementation calls it, gets a
+refusal, and the only route into the store remains the ordinary one: a human
+reads the proposal and authors an ordinary leaf with citations, which a moderator
+promotes. At that point the record is knowledge, and the probabilistic step is
+history rather than provenance.
+
+Nothing probabilistic persists or is cited without that gate.

package/payload/protocol/new-kind-pipeline.md

@@ -0,0 +1,179 @@
+# The new-kind pipeline (PRD §5.2) — the trust boundary
+
+> Paths in this document are client-relative — relative to the vendored kit
+> root after init (`schemas/…`, `templates/…`, `engine/…`, `protocol/…`). In
+> the kit repo itself these live under `payload/`.
+
+An extractor **kind** is a small deterministic recipe (~30-line parser) that
+reads a value set out of a reified anchor. The shipped kind library covers the
+common shapes (PRD §5.1); everything else surfaces as a **miss** — an anchor no
+shipped kind can read. This document is the governed path from a miss to a new
+kind. It is a trust boundary, not a convenience path: a subtly wrong parser
+produces a false all-clear, which is worse than no check.
+
+> **Hard rule (D-005): validators execute only vendored, versioned,
+> test-covered code — never code authored in the session that runs it.**
+> A kind drafted in a session is NEVER wired into the validator in that same
+> session. It enters via the GATE step: a PR carrying the parser, its fixture
+> tests, and a demo run, merged after human review. Agents draft; humans gate;
+> code validates.
+
+Before drafting any parser, weigh the alternative of **reifying the anchor
+into a standard shape** (product principle 6): when a fact can't be extracted
+because the code never reified it, the right proposal is often a registry/enum
+in the code — pushing the system toward being describable — not a bespoke
+parser.
+
+## Entry point: the miss-log
+
+The pipeline consumes `logs/misses/` — the demand-driven extractor backlog.
+A miss entry is **one file per entry** (`logs/misses/<date>-<hex8>.yaml`,
+D-010) so concurrent sessions never merge-conflict, written via the
+append/transition helper (`engine/log-entry.js`), never by hand-editing YAML.
+
+Fields, per `schemas/miss.schema.json`:
+
+| Field | Req. | Meaning |
+|---|---|---|
+| `schema-version` | yes | integer ≥ 1; stamped by the helper (§3.5, additive-only evolution) |
+| `date` | yes | ISO date the miss was recorded (injected — never wall-clock) |
+| `path` | yes | root-relative path of the anchor no kind can read |
+| `shape` | yes | shape description — enough for this pipeline to draft a parser; paths and structure only, never file contents verbatim |
+| `session` | no | opaque platform/session hint — an ID, never quoted session content |
+| `status` | yes | `open → proposed → resolved / rejected`; re-open-not-duplicate |
+| `verified` | — | stamped by the transition helper when the entry resolves (validator re-run passed); removed on re-open |
+| `reason` | — | required on rejection; travels only with `rejected` |
+| `occurrences` | — | re-open dates: recurrences re-open the same entry, never duplicate |
+
+Lifecycle invariants. The schema gate (`engine/lib/validate-record.js`)
+enforces exactly two of them on any fragment, hand-edited or not, matching
+what the transition helper enforces on its write path — on these two the
+gates cannot disagree:
+`verified` ⇔ status `resolved`, both directions; `rejected` ⇒ non-empty
+`reason`, and `reason` travels only with `rejected`.
+The rest is **helper-only**: only the transition helper's write path drops
+`verified`/`reason` on re-open and appends the re-open date to `occurrences`
+— a hand-edited fragment missing an occurrence entry still validates clean,
+which is one more reason fragments are written via the helper, never by hand.
+
+**Capture content policy (§3.4):** miss entries carry concept IDs and file
+paths only — never verbatim user text, quoted session content, or secrets.
+Committed fragments are permanent git history.
+
+## The six steps
+
+```
+1. SURVEY    read-only: the bootstrap/reflect agent inventories anchor shapes
+2. MATCH     configure concepts from the shipped kind library
+3. DRAFT     for each miss: agent writes the parser
+             + a test fixture (sample file → expected values, following
+               the shipped extractor-fixture template, D-009)
+             + a demo run against the live anchor it was drafted for
+4. GATE      human review — fast, because the claim is mechanical
+5. INTEGRATE parser lands as versioned, tested code (client zone of their repo;
+             kit library if the vendor harvests it for future inits)
+6. RE-RUN    concepts depending on the new kind emit last
+```
+
+### 1. SURVEY — inventory anchor shapes (read-only)
+
+The bootstrap/reflect agent triages the survey-map artifact (never
+raw-traverses the repo) and inventories the anchor shapes concepts point at.
+Anchors with a shipped kind proceed to MATCH. Anchors with **kind-shaped
+evidence but no kind** — a real registry the library can't read — become miss
+entries, written via the helper (verified working invocation; `--date` is
+mandatory and injected, never wall-clock):
+
+```
+node engine/log-entry.js create --log misses --date 2026-07-08 \
+  --entry '{"path":"config/regions.txt","shape":"plain-text list, one region code per line, # comments"}'
+```
+
+SURVEY consumes the misses already in the backlog too — never minting a
+sibling for a known anchor:
+
+- a recurrence of a **still-open** miss needs no transition and gets none:
+  `open → open` is illegal (the helper hard-errors), because the open entry
+  *is* the standing demand signal. The helper offers no occurrences-append
+  for open entries; the agent simply leaves the entry as-is and moves on.
+- a recurrence of a **resolved or rejected** miss **re-opens the same entry**
+  (`transition --to open`), which appends the date to `occurrences` and drops
+  the stale `verified`/`reason`.
+
+### 2. MATCH — configure from the shipped library first
+
+Every anchor that a shipped kind *can* read gets an `enumerates` descriptor
+(`kind` / `source` / `values`, plus `symbol`/`emit` where the kind needs them)
+against the shipped library. Only what remains unmatched justifies DRAFT —
+and even then, weigh reification (principle 6) before a bespoke parser.
+
+### 3. DRAFT — parser + fixture + demo run
+
+For each miss that survives MATCH, the agent drafts, from the shipped template
+(`templates/new-kind/`, see its README):
+
+1. **the parser** — a pure, deterministic function: source text in, value set
+   out; hard-errors loudly on anything it can't parse, and declares a
+   **syntactic envelope**, hard-erroring when out-of-envelope sentinels appear
+   in the matched span — a confident wrong parse is a false all-clear, the
+   D-005/D-012 failure class;
+2. **a test fixture** — sample file → expected values, following the shipped
+   extractor-fixture template (D-009);
+3. **a demo run** against the live anchor the miss recorded (`path`), with the
+   output attached to the PR.
+
+The draft NEVER runs inside the validator in this session (D-005). The miss
+entry transitions `open → proposed` when the draft PR exists.
+
+### 4. GATE — human review
+
+A human reviews the PR. The review is fast because the claim is mechanical:
+parser + fixture + demo-run output — does the fixture cover the envelope, does
+the demo run reproduce the live anchor's values, is the envelope honest about
+what it rejects? Rejection transitions the miss `proposed → rejected` with a
+`reason` (rejections record the reason, §8). A rejected miss that recurs
+re-opens (`rejected → open`) — the backlog keeps the demand signal.
+
+### 5. INTEGRATE — versioned, tested code
+
+The merged parser lands as versioned, test-covered code in the client zone of
+their repo (the vendor harvests it into the kit library only for *future*
+inits — seeded-once, D-001). It is now vendored code the validator may
+execute: this preserves D-014 (the engine never imports/evals/spawns repo
+*content* at validate time — a new kind enters the engine's own reviewed code,
+it is never dynamically loaded from the store or the scanned tree).
+
+### 6. RE-RUN — dependent concepts emit last
+
+Concepts whose `enumerates` descriptors depend on the new kind are (re)emitted
+and validated last, once the kind is merged. A green validator re-run
+transitions the miss `proposed → resolved`; the helper stamps `verified` with
+the run date. A later regression or recurrence re-opens the same entry
+(`resolved → open`, dropping `verified`, appending to `occurrences`).
+
+## Miss lifecycle ↔ pipeline steps
+
+| Transition | When |
+|---|---|
+| *(created `open`)* | SURVEY records an unextractable anchor |
+| `open → proposed` | DRAFT produced parser + fixture + demo run; PR open |
+| `proposed → resolved` (+ `verified`) | GATE approved, INTEGRATE merged, RE-RUN passed |
+| `proposed → rejected` (+ `reason`) | GATE rejected the draft |
+| `resolved → open` / `rejected → open` | recurrence — same entry re-opens, `occurrences` appended; `verified`/`reason` dropped |
+
+These are exactly the legal transitions the helper enforces; any other move is
+a hard error that leaves the fragment untouched.
+
+## Drafting template
+
+`templates/new-kind/` ships the drafting skeleton — six files: a
+framework-agnostic parser module (whose CLI is the demo-run tool), a
+descriptor example, a fixture pair (`fixture/sample.list` →
+`fixture/EXPECTED.yaml`), a stand-in demo anchor
+(`fixture/demo-anchor.list`), and a README that walks the demo run. Together
+these cover the three DRAFT artifacts above (parser, fixture, demo run).
+The template README also records one manual walkthrough of the
+template against its own fixture (an honest seam: a documented manual
+exercise, not CI — the kit's CI pins the template artifacts against each
+other and replays the walkthrough's CLI runs so the transcripts can't rot
+apart, but exercising a draft against a *live* anchor is always manual).