unknown-knowledge 2.1.0

package/payload/protocol/registry-warrant.md

@@ -0,0 +1,162 @@
+# Registries: warrant-minting and suppression (UCS-1148)
+
+> 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/`.
+
+A **registry** is a governed vocabulary file: the closed set of values one
+facet of a Store may draw from. Registries live at `<store>/_registries/<name>.yaml`
+— underscore-prefixed like `_catalog.yaml` and `_rules.yaml`, and for the same
+reason: they are governed store meta, not records.
+
+The knowledge store's four registries:
+
+| Registry | File | Shape | Governs |
+|---|---|---|---|
+| domains | `knowledge/_registries/domains.yaml` | hierarchical | `facets.domain` — the subject spine |
+| operations | `knowledge/_registries/operations.yaml` | flat | `operations[]` — the verbs a leaf lets a reader do |
+| jurisdictions | `knowledge/_registries/jurisdictions.yaml` | flat | `applies.jurisdictions[]` — where the claim holds |
+| authority tiers | `knowledge/_registries/authority-tiers.yaml` | flat | `citations[].authority` — how far a source can be trusted |
+
+## Why a registry and not a schema enum
+
+Membership could have been a JSON Schema `enum`, and deliberately is not.
+
+An enum is **kit-vendored code**. Under D-001 (seeded once, then owned) a
+seeded repo has no update channel, so a vocabulary living in the schema would
+be frozen at seed time for the life of that repo — a Store could never name a
+subject its own material actually covers. A registry is **client data**: it
+sits in the client zone, is reviewed as code like every other Store file, and
+grows by steward decision without an engine release.
+
+The engine therefore holds no opinion whatsoever about which values exist. It
+enforces exactly one rule — *a governed value must be minted in its registry* —
+and the registry alone says what is minted. This is what the acceptance
+criterion "the domains top level is open" means concretely: the engine's only
+notion of a top-level domain class is "a value with no parent segment", so
+adding one is a registry edit plus a Decisions entry, with no schema change and
+no engine change. There is no allocation table anywhere, and never a fixed
+list of top-level classes to petition for a slot in.
+
+## Literary warrant — the minting rule
+
+> **A value is minted only when material exists to fill it.**
+
+This is *literary warrant*, borrowed from classification practice: a class
+earns its place in the scheme because documents exist that belong in it, never
+because it seems like a category somebody might one day need. A registry minted
+ahead of its material is speculative shelving — it invites authors to file
+knowledge under a heading nobody chose deliberately, and the vocabulary drifts
+into a taxonomy of guesses.
+
+The `warrant:` field on every registry value is where the material is named,
+and it is **required**. If it cannot be filled with something concrete — a leaf,
+a document, a body of material that exists *now* — the value is not ready to be
+minted.
+
+### Conduct: minting a value
+
+1. **Find the warrant.** Name the material that needs this value. If the answer
+   is "we'll need it later", stop: that is the case the rule refuses.
+2. **Check for a suppression.** If the value is already listed with
+   `status: suppressed`, it was proposed and refused before. Re-minting is
+   legitimate but it is a *reversal*: read the suppressing decision first, and
+   record why the refusal no longer holds.
+3. **Choose the level.** For the hierarchical domains registry, mint every
+   segment on the path. A child may not hang off an unminted parent — the
+   validator reports the missing segment, not the whole path, because the
+   segment is the edit you can actually make.
+4. **Draft the Decisions entry** from `templates/decisions/registry-minting.yaml`.
+   Every minting is a governed act with a written rationale (§3.3): the entry
+   records the warrant, the value, and who decided.
+5. **Edit the registry**, citing the decision id in the value's `decision:`
+   field. This is required and it is checked: a value citing no decision fails
+   the schema, and one citing an id no Decisions entry answers to fails as an
+   unresolved ref.
+6. **Open one PR** carrying the registry edit, the Decisions entry, and the
+   material that supplied the warrant. Agents draft; humans approve.
+
+### Conduct: suppressing a value
+
+A value that is proposed and **rejected** is not deleted — it is recorded with
+`status: suppressed` and left in the registry.
+
+Deleting it would lose the decision. The next author to reach for the same term
+would find nothing, propose it again, and the vocabulary question would be
+re-litigated from scratch with no memory of why it went the way it did. A
+suppression makes the refusal durable and visible: the term is on the shelf,
+marked refused, with a decision id pointing at the reasoning.
+
+It also changes what an author is told. Using a suppressed value is a
+`suppressed-value` finding that says the term was *refused*, not the far less
+useful "not in the registry" — which reads like a typo and invites the author
+to fix their spelling rather than read the decision.
+
+Suppression follows the same conduct as minting: a Decisions entry, then the
+registry edit citing it, in one reviewed PR.
+
+## What the engine checks
+
+Registry membership is a **structural-validator** check (`engine/commands/validate.js`),
+not a schema check. The hand-rolled schema subset cannot express "this value
+appears in that file", and hierarchical segment membership is not a JSON Schema
+shape at all.
+
+| Finding | Means |
+|---|---|
+| `unregistered-value` | the value is not minted in its registry |
+| `unminted-segment` | a hierarchical path whose named segment is not minted |
+| `suppressed-value` | the value is listed as refused |
+| `missing-registry` | the record cites a governed facet whose registry the store does not carry |
+| `registry-shape-mismatch` | the registry's `hierarchical` flag disagrees with the facet it governs |
+
+Every one of them names **both the value and the registry file**, so the finding
+points at the edit rather than at the symptom.
+
+The loader refuses a registry file outright — exit 2, before any membership is
+judged — when it contradicts itself: a value declared twice, a value declared
+both minted *and* suppressed (`duplicate-registry-value`), a declared `registry`
+or `store` disagreeing with the file's own path (`registry-name-mismatch`,
+`registry-store-mismatch`), or a `decision` naming no Decisions entry
+(`unresolved-ref`). None of these can be settled by the engine: picking a winner
+by file order would be a governance decision nobody made.
+
+Four engine conducts are worth stating outright, because each is the difference
+between a governed vocabulary and a decorative one:
+
+**Every value cites a decision, and the citation is checked.** `decision` is a
+*required* field, and it resolves through the same cross-store ref graph as
+every other citation — an id naming no Decisions entry is an ordinary
+`unresolved-ref` error. "Each minting a Decisions entry" is therefore enforced,
+not merely encouraged: a vocabulary change nobody signed cannot reach the store.
+
+**A malformed registry is a hard error, never an empty one.** Unparseable YAML
+or a schema defect in a registry file is a loader error that gates every
+surface to exit 2. Degrading to "the registry loaded as empty" would fail every
+value that *was* minted — a check that never ran, wearing the exit code of a
+check that ran and found problems (PRD §5).
+
+**A registry's shape must match the facet it governs.** The `hierarchical` flag
+is what turns on segment-by-segment membership, so a domains registry that lost
+it would judge a whole path as one opaque string — the segment rule switched
+off by an omitted line, at exit 0. The engine therefore declares the shape each
+facet requires and refuses a registry that disagrees
+(`registry-shape-mismatch`), reported once against the registry file.
+
+**An absent registry surfaces where it can mean something.** A Store that
+carries no registries is complete and valid: registries are opt-in governance,
+and demanding them of every Store would fail every repo seeded before this
+layer existed. Absence therefore surfaces at the point a record actually
+*claims* a governed value — a leaf naming `facets.domain` in a Store with no
+domains registry is an explicit `missing-registry` finding. That is never a
+silent pass: the value went unjudged, and the finding says so in those terms.
+The alternative conducts were both worse. Warning at load on every registry-less
+Store would train stewards to ignore the warning; hard-erroring at load would
+break every existing Store for a feature it never opted into.
+
+## Where registries are not the answer
+
+A registry governs a **facet** — a small, stable, shared vocabulary that
+readers navigate by. It is not a place to park free text. If a value would be
+minted once and used once, it is content, not vocabulary: it belongs in the
+leaf's prose or its `terms`, where nothing has to govern it.

package/payload/protocol/skills/kb-build.md

@@ -0,0 +1,303 @@
+# /kb-build — the sole knowledge write path (PRD §3.2, D-019)
+
+> 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.
+
+The knowledge store's truth anchor is the world, not the code — and this
+skill is its **sole write path**: every leaf under `knowledge/` lands
+through this procedure, drafted by an agent and approved by a human through
+the normal PR gate (agents draft; humans approve). You operate under
+`protocol/AGENTS.md` throughout — every gate rule there binds here. Run
+this when someone brings an item worth keeping: a regulation, an industry
+rule, a research result, an operational fact the code cannot testify to.
+
+**The leading rule: citations required — an unsourced claim is not
+promotable.** A claim with no traceable source never becomes a leaf; it
+parks as a gap-log entry (step 2) so the demand signal survives without the
+store vouching for it.
+
+## This skill is thin orchestration
+
+Every mechanical step below **names the engine command that performs it**.
+The commands compute; this skill sequences them and stops on their exit
+codes. Where a step says "run", run it — do not reproduce its answer from
+memory, and do not decide an outcome the engine reports.
+
+Your discretion is limited to three **judgment fills**, and they are the
+only free-form work in the procedure:
+
+| Judgment fill | Where | What it means |
+| --- | --- | --- |
+| **Prose bodies** | step 4 | the leaf's markdown body — written, not generated |
+| **Candidate confirmation** | steps 1–2 | confirming a proposed classification or citation against the source, which is a read no command can do for you |
+| **Mint proposals with warrant evidence** | step 3 | proposing a governed vocabulary value, carrying its literary warrant |
+
+Everything else — locating coverage, minting the accession, checking facet
+values against their registries, checking the catalog, the final gate — is
+the engine's. **Protocol compliance is a property of the mechanism, not of
+agent obedience**: the hooks in `hooks/` run the blocking validation and
+the reverse lookup whether or not anyone remembers to, and they propagate
+the engine's exit codes unchanged.
+
+Two `--root` conventions, stated once (same as AGENTS.md):
+
+- Store-reading CLIs (`resolve.js`, `validate.js`) take `--root` as the
+  **repo root** (default: cwd); the stores are auto-located at
+  `<root>/unknown-knowledge/`.
+- `log-entry.js` takes `--root` as the **kit dir** (the directory
+  containing `logs/`), e.g. `--root unknown-knowledge`.
+
+## The five steps
+
+```
+1. CLASSIFY  item → one facet-set home, via resolve.js
+2. CITE      every claim carries a citation, or it parks via log-entry.js
+3. FACET     fill the governed facets from the registries
+4. DRAFT     the leaf file: §3.2 governance frontmatter + body, at draft stage
+5. VALIDATE  validate.js green, then the human gate
+```
+
+### 1. CLASSIFY — one subject home
+
+Enter through the store's navigational grammar (AGENTS.md): read
+`knowledge/_catalog.yaml`, then `knowledge/_rules.yaml` — the
+domain spine the bootstrap interview wrote. Then ask the engine what
+already exists near the item:
+
+```
+node unknown-knowledge/engine/resolve.js "svg asset export precision" --json --root .
+```
+
+`resolve.js` is what answers "does the store already cover this". Read its
+`decomposition` (which operations, concepts and jurisdictions joined) and
+its `residue` (the tokens nothing consumed) — residue is the store telling
+you where its vocabulary runs out, and it is the raw material a later
+`mint-proposal` is built from. Read any leaf it names before deciding
+placement (the map is never the fact): that read is **candidate
+confirmation**, a judgment fill, and no command substitutes for it.
+
+Decide, in this order:
+
+- **An existing leaf already covers the item** → this run is a *revision*
+  of that leaf: its accession is its identity and never changes (§3.5), so
+  keep it and append a `revision` note in step 4.
+- **The spine names a home** → a new leaf. Classification is a
+  `facets.domain` value, not a position: the subject path says what the leaf
+  is about, and the leaf's identity is a fresh **accession** minted in step
+  4. Nothing has to be looked up to find "the next free" anything — an
+  accession is opaque and drawn from a sequence, so two authors classifying
+  into one domain never contend for a number, and the classification you
+  choose here constrains nothing about the identity you get.
+  Where the classification was contestable (the item could plausibly file
+  under two domains), record the call as a `class-here` note on the leaf.
+- **The spine has no home for it** → the spine is the human's (it came from
+  the bootstrap interview): hand the item back with the domains you
+  considered and ask whether `knowledge/_rules.yaml` should grow — never
+  invent a domain silently.
+
+**Done when** exactly one of the three outcomes holds: one subject home
+settled for a new leaf, one existing leaf identified for revision, or the
+item handed back for a spine decision. Two plausible homes you cannot
+separate is the third outcome, not a coin flip.
+
+### 2. CITE — the promotion gate
+
+Inventory every claim the drafted item makes — each sentence that asserts
+something about the world. Each claim must end this step in exactly one
+state:
+
+- **Cited**: a `source` (+ `accessed` date) a reviewer can follow to the
+  world — a regulation, a standard, a published document, a dated research
+  artifact. The citation supports the claim as written, not the topic in
+  general. Confirming that is **candidate confirmation**: open the source
+  and read it, because a citation nobody followed is a claim about a
+  citation.
+- **Dropped**: reworded out or removed — the leaf says less and stays true.
+- **Parked**: worth keeping as demand but unsourced. An unsourced claim is
+  not promotable — it goes to the gap log, never into a leaf, and
+  `log-entry.js` is the only write path into `logs/`:
+
+```
+node unknown-knowledge/engine/log-entry.js create --log gaps --date 2026-07-09 \
+  --root unknown-knowledge \
+  --entry '{"summary":"kb-build item not promotable: export-precision claim lacks any citation; nearest leaf L-000100","consulted":{"leaves":["L-000100"]}}'
+```
+
+`--date` is injected, never wall-clock; the summary carries leaf ids,
+concept IDs, and file paths only — never verbatim user text or secrets
+(§3.4). `consulted.leaves` cites each leaf by its accession id — the only
+spelling that resolves — and the summary should name that same id, so a
+reader can look up what the entry consulted.
+
+**Done when** zero uncited claims remain in the draft. If citing
+and dropping empties the item, park what remains and end the run here — a
+parked item is a recorded demand signal, not a failure.
+
+### 3. FACET — fill the governed facets from the registries
+
+`facets` is the classification block, and **every value must already be
+minted in its registry** under `knowledge/_registries/`. Read the registry
+file and take the value from it; a value the registry does not carry is a
+blocking `unregistered-value` finding at step 5, which is the mechanism
+refusing an ad-hoc string rather than trusting you not to write one.
+
+| Facet | Registry | What it records |
+| --- | --- | --- |
+| `domain` | `_registries/domains.yaml` | the hierarchical subject path — every segment minted |
+| `form` | `_registries/form.yaml` | what KIND of knowledge this is |
+| `anchor` | `_registries/anchor.yaml` | which truth anchor settles the claim (artifact, world, team — D-003) |
+| `stage` | `_registries/stage.yaml` | where the leaf sits in the promotion path |
+
+Two adjacent governed lists are filled the same way, from the same kind of
+file: `operations` (the verbs this leaf lets a reader DO,
+`_registries/operations.yaml`) and `applies.jurisdictions`
+(`_registries/jurisdictions.yaml` — EMPTY means universal, which is a
+claim, so leave it empty only when the knowledge really does hold
+everywhere). Each `citations` entry carries an `authority` tier from
+`_registries/authority-tiers.yaml`: the tier records how far the source can
+be trusted, and without it a regulator's text and a hallway conversation
+read identically.
+
+**If no minted value fits, that is the signal to propose a minting, not to
+invent a spelling.** A mint proposal is the third **judgment fill**, and it
+is a governed act with a written rationale: draft it from
+`templates/decisions/registry-minting.yaml` and carry its **literary
+warrant** — the material that already exists for the value to hold. Warrant
+is evidence, not intention: a value minted ahead of its material is
+speculative shelving (`protocol/registry-warrant.md`). Where the proposal
+comes from a corroborated residue cluster instead of a single item, it is
+reflect's `mint-proposal` shape and belongs on the reflect queue —
+`protocol/skills/knowledge-reflect.md` owns that path. Either way the
+proposal goes to the human; this skill never edits a registry.
+
+**Done when** every facet, operation, jurisdiction and authority tier the
+draft will carry is a value its registry already mints, or the run is
+paused on a mint proposal awaiting the human.
+
+### 4. DRAFT — §3.2 governance frontmatter + body
+
+The frontmatter shape is `schemas/knowledge-leaf.schema.json` — the single
+source of truth; `validate.js` enforces it in step 5. The governance calls
+this skill makes on top of the schema:
+
+- **`id`** — the accession (`L-NNNNNN`): **required on every leaf**, opaque,
+  never reused, never positional. It is the leaf's identity, what the loader
+  indexes by, and the only spelling other leaves, the catalog, decisions and
+  log fragments may cite it as. Mint the next value in the sequence; because
+  it says nothing about where the leaf sits, refiling the leaf later leaves
+  it untouched and breaks no citation. A collision is a hard error at step 5,
+  never a silently shared identity.
+- **`facets.stage`** — start at **`draft`**. Every agent-authored entry
+  enters at draft stage; this is not a courtesy, it is where the moderation
+  pipeline picks the leaf up. A draft leaf is downranked in resolver output and
+  verdicted `unknown` by preflight, which is correct and not a defect:
+  nothing has certified it yet. Promotion is a moderator's act after the
+  citations are checked, never the author's.
+- **`notes`** — every leaf carries a `scope` note (what it covers and
+  pointedly does not) and every write appends a `revision` note with
+  `date` (initial entry, or what changed); add `class-here` when step 1
+  flagged the classification as contestable.
+- **`cross-references`** — `class-elsewhere` and `see-also` must resolve to
+  leaves the catalog declares. Cite the target's accession id (`L-NNNNNN`),
+  which is the only legal spelling. `including` is standing room —
+  candidate topics parked under the heading, not authoritative, never
+  citable as fact.
+- **`facets`**, **`operations`**, **`applies.jurisdictions`**,
+  **`citations[].authority`** — the step-3 values, verbatim. Nothing minted
+  here that step 3 did not settle.
+- **`citations`** — the step-2 survivors, verbatim; at least one.
+- **`terms`** — the words a future resolve should hit; write them for the
+  searcher, not the author.
+- **`concepts`** — the ontology concepts (`K-NNN`) this leaf is knowledge
+  ABOUT. Declare them even when `terms` already names the concept's term: the
+  concept edge is STRUCTURAL, so it keeps working when the concept is renamed
+  or when your leaf uses different words than the ontology does. `terms` is a
+  text match between two authors' vocabularies; this is a claim. Each must
+  resolve — a concept id nothing mints is a blocking finding.
+- **`paths`** — the repo-relative files or directories this leaf governs. A
+  directory covers its subtree. This is what makes the leaf surface in the
+  reverse lookup, so the files in a diff surface the knowledge that governs
+  them BEFORE the edit — and it is what the `hooks/reverse-lookup` hook
+  reads. Every path must name something that exists INSIDE this repo: a path
+  pointing at nothing governs nothing, one that escapes the repo root
+  (`../elsewhere`, or an absolute path) is not this store's to claim, and
+  `.` — the repo root — attributes nothing by attributing to everything. All
+  three are blocking findings.
+- **`relates`** — typed leaf-to-leaf edges, and the type carries the meaning,
+  so choose it rather than defaulting to `see-also`:
+  `depends-on` (this leaf's claim is only usable once the target's is),
+  `see-also` (worth reading alongside — no dependency, no conflict),
+  `contradicts` (the two claims cannot both hold — recorded, not resolved, so a
+  human can settle it), and `supersedes` (this leaf replaces the target's
+  claim — the disagreement is already settled). A resolver hit carries its
+  neighborhood one hop out, labeled by kind, so these are what an agent reads
+  next. Targets are leaf refs and each must resolve: cite the target's
+  accession, as with `cross-references`.
+- **`provenance`** — `author` and `skill-version`, so a systematic drafting
+  defect can be traced to the vintage that introduced it. The skill is
+  versioned and its changes are gated; record the version you ran.
+- **Body** — the markdown below the frontmatter is the content, and it is
+  the first **judgment fill**: each claim reads back to a listed citation.
+  **Open with a topic sentence**: there is no `description` field (retired
+  in v2), and display prose is DERIVED from the body's first sentence
+  wherever a one-liner is shown. Write it as the sentence you would want to
+  read in a search result.
+
+  What the deriver actually does, so the guidance is not a guess: it skips
+  leading markdown structure line by line — headings, list items, block
+  quotes, fenced code, table rows — and takes the first prose line it finds,
+  joining hard-wrapped continuation lines. It ends the excerpt at the first
+  `.`, `!`, or `?` followed by whitespace, so `§4.2` and `v3.2` do not cut it
+  short. Prose with no terminator is shown whole rather than dropped. The
+  only body with nothing to show is one that is *entirely* structure — all
+  heading, all list, all code — so the failure mode to avoid is opening with
+  a bare list or a code block, not writing a fragment.
+
+Then add the catalog row to `knowledge/_catalog.yaml`: `id` (the leaf's
+accession, the same value as its `id` field, and the only legal spelling),
+`title` (the heading, kept in sync on revision), `file` (the leaf path
+relative to `knowledge/`). Leaf files are sharded by accession prefix —
+`knowledge/<L-NN>/<accession>-<slug>.md`, where the prefix is `L-` plus the
+first two digits of the accession's numeric part (`L-000101` files under
+`knowledge/L-00/`). The shard is a fanout device for directory size and
+**carries no meaning**: it makes no claim about the leaf's subject, and
+nothing reads it. `validate.js`'s `index-drift` and `orphan` checks are what
+verify the row against the file — do not audit that pairing by eye.
+
+**Done when** the leaf file and its catalog row both exist, the body opens
+with a topic sentence, `facets.stage` is `draft`, and every value in the
+frontmatter came from step 2 or step 3.
+
+### 5. VALIDATE — green, then the human gate
+
+```
+node unknown-knowledge/engine/validate.js --root .
+```
+
+This is the same command the `hooks/pre-commit` hook runs, so a commit that
+would fail here is refused before it exists — running it now is how you see
+the findings first, not a substitute for the hook.
+
+- **Exit 0** — done drafting. Hand the change to the human gate: the leaf,
+  the catalog row, and any gap fragments ride one PR; knowledge writes are
+  human-gated, and the merge IS the approval.
+- **Exit 1** — the findings name the defect (`orphan`, `index-drift`,
+  `missing-citation` — an unsourced claim is not promotable;
+  `unregistered-value` — step 3 was skipped or a value was invented): fix
+  the draft, re-run.
+- **Exit 2** — **stop and fix**: the check never ran (an unresolved
+  cross-reference lands here), and a check that never ran is a blocking
+  defect, never a silent pass. Re-run until the run itself completes.
+
+Then attribute what you touched, which the `hooks/reverse-lookup` hook does
+automatically over the staged diff and you can run directly:
+
+```
+node unknown-knowledge/engine/resolve.js --paths knowledge/L-00/L-000110-svg-asset-export-precision.md --json --root .
+```
+
+The skill declares done only on an exit-0 run that saw the final draft —
+a verdict is per-run, never carried (D-011).

package/payload/protocol/skills/knowledge-audit.md

@@ -0,0 +1,183 @@
+# /knowledge-audit — the on-demand health check (PRD §8, D-019)
+
+> 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.
+
+Run this when someone asks how healthy the map is — on demand, before a
+reflect cycle, or when the loop has gone quiet. The audit is **read-only**:
+it runs the engine's checks in a fixed order, sweeps the two lifecycles the
+engine does not compute, and files one human-readable report. It never
+mutates stores — everything it finds is *routed*, not fixed inline:
+validator findings to the owning concepts' normal PR path, reverse-audit
+drafts to the steward (proposal-first), fragments to reflect. You operate
+under `protocol/AGENTS.md` throughout.
+
+Dates are injected, never wall-clock: the invoker supplies today's date
+once (`<TODAY>` below) and every step reuses it.
+
+## The seven steps
+
+```
+1. STRUCTURE  engine/validate.js — whole-store structural truth
+2. VALUES     engine/validate-values.js — enumerates vs source, both ways
+3. REVERSE    engine/audit.js — advisory (never blocking) proposals
+4. KNOWLEDGE  leaf sweep: citations, cross-refs, revision notes
+5. DECISIONS  lifecycle: aging proposed/accepted, orphaned relates-to
+6. HEARTBEAT  last-reflect stamp, open fragments, quarantined concepts
+7. REPORT     the fixed report shape, filled from the outputs above
+```
+
+No step's outcome stops the audit. Exit 2 anywhere is itself the finding —
+a check that never ran is a blocking defect, never a silent pass — so the
+report records that verdict as **CHECK NEVER RAN** (never as a pass) and
+the audit continues, keeping the report whole.
+
+### 1. STRUCTURE — the whole-store validator
+
+```
+node unknown-knowledge/engine/validate.js --root .
+```
+
+Run unfiltered — the audit is a whole-store instrument, never a `--concepts`
+spot check. Capture verbatim: the exit code, the summary line, the
+`checks run:` line (so a green verdict names what actually ran), and every
+finding. Unresolved cross-store references — including a knowledge
+cross-reference or a decision `relates-to` that points at nothing — surface
+here as loader errors at exit 2. **Done when** the exit code and the full
+finding list (or the clean two-liner) are captured for the report.
+
+### 2. VALUES — enumerates vs source
+
+```
+node unknown-knowledge/engine/validate-values.js --root .
+```
+
+Capture verbatim: the counts line, every HARD ERROR (out-of-envelope
+descriptors — on those concepts the check never ran, and the report must
+say so), and every finding (`value-not-in-source`, `source-value-missing`,
+`wrong-pointer`). **Done when** exit code, counts line, hard errors, and
+findings are all captured.
+
+### 3. REVERSE — the advisory scan
+
+```
+node unknown-knowledge/engine/audit.js --root . --today 2026-07-09
+```
+
+Always pass `--today <TODAY>` — without it the stale-last-verified check
+reports itself skipped, and the heartbeat wants that check run. The reverse
+audit is **advisory (never blocking)**: its findings are drafted proposals
+for human review, so capture the header lines (candidates / matched /
+findings, scope, stale check), the finding codes with their paths, and any
+suppressed count — the draft YAML blocks go to the steward, not into the
+report body. `--fail-on-findings` stays a human opt-in — never a CI
+default, never part of this audit. **Done when** the header lines and the
+per-finding one-liners are captured.
+
+### 4. KNOWLEDGE — the leaf sweep
+
+Citation *presence* and cross-reference *resolution* are engine checks —
+they already ran in step 1 (`missing-citation` findings; unresolved refs at
+exit 2). Never re-derive them by hand. This sweep reads every leaf the
+knowledge catalog declares and records what the engine does not compute,
+one row per leaf:
+
+- **citations dated** — every citation carries an `accessed` date (an
+  undated source ages invisibly);
+- **revision note present** — at least one `revision` note with a `date`,
+  and the newest one consistent with `edition` (an edition bump with no
+  note is an unexplained change);
+- **standing room pressure** — `including` topics that sessions keep
+  needing are kb-build candidates; name them.
+
+**Done when** every catalog-declared leaf appears in the sweep table with
+all three columns filled — a leaf skipped is a check that never ran.
+
+### 5. DECISIONS — the lifecycle check
+
+Orphaned `relates-to` references are engine-checked (step 1, exit 2) —
+record here any that fired; never re-derive resolution by hand. This sweep
+computes the ages the engine does not: for every entry in
+`decisions/entries/`, days from its `date` to `<TODAY>`, then flag:
+
+- **aging `proposed`** — older than 30 days: a proposal nobody gated. A
+  provisional date-suffixed id (`D-YYYY-MM-DD-<slug>`) still `proposed`
+  past the window means the steward never minted the final `D-NNN` — name
+  it.
+- **aging `accepted`** — older than 90 days and never moved to
+  `addressed`/`archived`: accepted words with no follow-through.
+
+The thresholds are report headings, not verdicts — aging entries route to
+the steward for triage. **Done when** every catalog-declared decision
+appears with its status and age, and the aging list is exhaustive over that
+table.
+
+### 6. HEARTBEAT — the loop's vital signs (§8)
+
+Three instruments; every one produces a report line — a lapsed steward
+rotation is **visible, never silent**.
+
+**Days since last reflect.** The reflect skill stamps a `last-reflect`
+state file at the kit root:
+
+```sh
+cat unknown-knowledge/last-reflect.yaml
+```
+
+Present → report `<TODAY>` minus the stamped date as
+days-since-last-reflect. Absent (`No such file or directory`) → the report
+line reads **no reflect has run yet** — degrade gracefully; the absence IS
+the datum, and it still prints.
+
+**Open fragments per log.**
+
+```sh
+for log in findings misses gaps; do
+  printf '%s open: ' "$log"
+  grep -rl '^status: open' "unknown-knowledge/logs/$log" 2>/dev/null | wc -l
+done
+```
+
+**Top-N quarantined concepts** (N = 5). List the quarantine-trigger
+fragments, read each one's `consulted.concepts`, count per concept, rank:
+
+```sh
+grep -rl '^trigger: quarantine' unknown-knowledge/logs/findings 2>/dev/null
+```
+
+Report concept IDs and counts only — fragment summaries stay in the
+fragments (§3.4 rides into reports too). **Done when** all three heartbeat
+lines exist, each carrying a real number or the explicit absence line.
+
+### 7. REPORT — the fixed shape
+
+One markdown report, sections in this order, **every section present even
+when empty** — "none" is a real answer; a missing section is a check that
+never ran:
+
+```markdown
+# knowledge-audit report — <TODAY>
+
+## Verdicts
+| step | command | exit | reading |
+(structure, values, reverse audit — one row each; exit 2 reads CHECK NEVER RAN)
+
+## Structural findings
+## Value findings
+## Reverse audit proposals (advisory — never blocking)
+## Knowledge leaves
+## Decisions lifecycle
+## Heartbeat
+- days since last reflect: <n>          (or: no reflect has run yet)
+- open fragments: findings <n>, misses <n>, gaps <n>
+- top quarantined concepts: K-NNN (<count>), …   (or: none)
+```
+
+Fill every line from the outputs captured in steps 1–6 — never from memory
+of a previous run: trust is per-run (D-011). Deliver the report in the
+conversation; the audit commits nothing and edits nothing — anything worth
+fixing routes to its owning path (concept PRs, kb-build, reflect, the
+steward).