@antoneeo/kb-agentic-skill 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,142 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.4.0] - 2026-08-03
+
+F-028 — several people on one project. `templates.md` had claimed the workstream
+registry was "Parallel-safe by construction" since F-019, and nothing had ever exercised
+it. Two workstreams opened from one base conflict **twice in one file**: on the row
+insert, and on the file-global `Date:` header. Row-level ownership cannot save a file
+that has a file-level field.
+
+### Changed
+- **`audit/handoff.md` is now GENERATED** from one `HANDOFF_[unit].md` per open
+  workstream, whose frontmatter IS the row. Two writers on two workstreams touch two
+  different files, and the `Date:` header is derived — from the newest `updated:` VALUE
+  in the sources, never a filesystem timestamp (git does not preserve mtimes, and an
+  mtime-derived header would make the file regenerate differently in every fresh clone).
+- **`HANDOFF_[unit].md` is now written for every OPEN workstream**, with or without
+  volatile state — no file, no row. It still carries the resume logistics, and deleting
+  it at closure *is* what removes the row. The DRY boundary against the ANALYSIS Diary
+  is restated in the template, because what used to keep narrative out of that file was
+  its rarity, and the rarity is gone.
+- Project-wide notes move to their own source, `audit/project_notes.md`, so generating
+  the registry cannot destroy notes that belong to no workstream.
+
+### Added
+- **`validate` errors when the registry disagrees with its sources** — which is what
+  turns a merge resolved carelessly from permanent into loud. Resolution is mechanical:
+  re-run `index`. The generated view can still conflict; the authored truth does not.
+- **`index` refuses to write while anything in the file is unaccounted for**, and names
+  it. Converting one row at a time is the state that loses the others, so conversion is
+  per project. A project with no sources is untouched and sees no new finding.
+- **`init` writes a `.gitattributes` stanza** giving the append-only review log
+  `merge=union` — a **built-in** driver, unlike `merge=ours`, which silently does
+  nothing until every clone runs `git config` and leaves the file wrong even then.
+  Create-only; a user's own `.gitattributes` is never clobbered.
+- `scripts/test_merge_safety.py` (shared, ×3): the experiment that found the defect,
+  kept as a regression test — two workstreams from one base, merged, with the assertion
+  that only the generated view may conflict and that regenerating loses no state. Plus
+  the mixed-state, fresh-mtime, ordering, cap and duplicate-id guards, each
+  mutation-verified.
+- A warning when two files claim the same workstream: the collision this design does
+  **not** fix (two people opening the same work under two names) must not pass as two
+  ordinary rows.
+
+The mechanism is files and a generator: **it works with no VCS at all.** The
+`.gitattributes` stanza is defence in depth — without it the outcome is today's, one
+conflict resolved by hand, never a lost row.
+
+### Upgrading
+Nothing happens until you convert: with no `HANDOFF_*.md` sources, `index` and
+`validate` behave exactly as before. When you convert, convert the whole registry at
+once — `index` will tell you what is still unaccounted for.
+
+## [1.3.0] - 2026-08-03
+
+Field defect: an agent handed a 200-page manual emits a few dozen claims and reports
+done. **Nothing it did broke a rule** — the extraction discipline carried a floor ("the
+extractor invents nothing") and no target, so an agent stops the moment nothing it wrote
+is false, and every row it emitted is correct.
+
+### Added
+- **A north star above the rules** in `distillation.md`: *not one assertion the source
+  makes may be lost, and not one it does not make may appear.* One sentence on purpose —
+  the halves counterweight each other, and two rules a paragraph apart get optimized
+  whichever was read last. The unit is the assertion, not the byte: exhaustive means
+  **read**, never *a row per page*.
+- **`extracted_through:`** on the artifact's sidecar (`p=<n>`, `L<n>`, `complete`),
+  required once any claim cites it — the thing that makes "I am finished" falsifiable.
+  Claims with no coverage recorded error; a claim addressing past the declared coverage,
+  or coverage past the end of the stored bytes, is a contradiction and errors; coverage
+  short of the end warns, since partial work is legal mid-ingestion.
+- **Bounded reading windows** (30 pages by default; the plan states the window used),
+  one plan task each. The existing `PLAN_` ledger is the register an ingestion resumes
+  from across sessions — no second register was built.
+- **A coverage cell in `corpus/INDEX.md` for every artifact**, finished ones included: a
+  list of only what is behind would be the work-management dashboard this method refuses.
+
+The limit is written where the field is: **nothing proves a page was read.** A field
+advanced without extracting is invisible to any checker, because a page that asserts
+nothing legitimately yields no rows — that direction belongs to the ingestion review.
+What changed is that the shortcut must be written down to pass.
+
+**Upgrading an existing corpus:** `check` errors on every artifact that has claims and
+no `extracted_through:`. State how far each source was actually read (`complete` if it
+was finished); the message names the artifact and the first row citing it. Run
+`sdlc_check.py index` once as well — `corpus/INDEX.md` gains the coverage cell.
+
+## [1.2.0] - 2026-08-03
+
+### Added
+- **`export --out <dir>` / `import <dir>`** — knowledge built in one project can be
+  carried into another. The export is a **closure**, not a selection: the bundle carries
+  the bytes its claims cite (a claim whose source cannot be reopened is model knowledge
+  arriving by another route) and pulls in the other half of any `CONTESTED` set, saying
+  which topics it added. The import is **additive and all-or-nothing**: it never
+  overwrites a node, never deletes, and computes the whole plan before writing a byte.
+  Duplicate claims are recognised by id, not by comparing text.
+- **`prov: IMPORTED`.** Knowledge crosses the project boundary; authority does not. An
+  imported ruling keeps its text, span and original `basis:` verbatim, must declare
+  `imported_from:`, and **cannot supersede a local row** until you re-ratify it with your
+  own note and your own basis.
+- **`portability.md`** — the doctrine those two commands cite, including what to tell the
+  user in their own words.
+
+## [1.1.1] - 2026-08-03
+
+### Fixed
+Three doctrine-vs-machinery inconsistencies found by a practitioner reading 1.1.0 —
+the worst defect class, because the agent verifies and is confirmed in a false belief.
+- `SKILL.md` never named `anchor`, so the command existed and the agent could not find it.
+- The `corpus/given/*` Write Trigger still carried its pre-1.1.0 wording, contradicting
+  the extraction-as-artifact rule it points at.
+- `anchor` resolved paths only from inside the docs root, unlike every sibling command.
+
+## [1.1.0] - 2026-08-03
+
+### Fixed / Added
+Six findings from the first full application of this skill by a practitioner other than
+its author (51 artifacts, 82 claims). None was an adherence failure: the agent obeyed
+every rule and the outcome was still wrong.
+- **Triage restated in knowledge units.** The levels were undecidable in this domain
+  because they carried the code lens's file counts. The unit here is knowledge, never
+  file count — with one limit: propagation that changes what a claim asserts is not
+  propagation.
+- **Gates are extracted alongside powers.** For every row saying what the subject *can
+  do*, the source is asked what must hold first — default-off, licence tier, version
+  floor, dependency — because "yes, supported" without the gate is a plan that fails on
+  site. The rule stays *ask*, never *produce*.
+- **`anchor <path> <phrase>`** turns a quoted phrase into a verified locator, matching
+  whitespace as `\s+` because a PDF extraction breaks phrases mid-line — the gap that
+  cost a field user two generation rounds.
+- **Extraction-as-artifact** for large binary corpora: the extraction is the artifact,
+  the digest moves onto the bytes locators actually address, and the original stays where
+  it lives as `original_path:` + `original_sha256:` (recorded, never checked — the limit
+  is stated wherever the fields are).
+- **`--help` lists the overlay commands**, so the ones this lens adds are discoverable
+  from the CLI rather than only from the documentation.
+
 ## [1.0.1] - 2026-08-02
 
 ### Fixed

package/README.md

@@ -1,86 +1,89 @@
-# KB Agentic Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
-
-`kb-agentic` turns an AI agent into the keeper of a second brain built **on the documents you supply** — not on what the model remembers. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
-
-The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill), transplanted from source code to knowledge: same process, one different fidelity discipline.
-
-## What it does
-
-Two axes are kept apart on purpose — **abstraction** (a topic made of topics: the graph edges) and **certainty** (how strongly the corpus supports a statement: the claim rows).
-
-1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction **is** the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as `original_path:` + `original_sha256:`. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limit: they let a human re-verify, they check nothing on their own. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
-
-2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists — and `anchor <path> <phrase>` produces it for you, matching spaces as `\s+` because a PDF extraction breaks phrases mid-line. **Gates are extracted alongside powers**: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is *ask*, never *produce*: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies **refuse to sum**. What the source does not assert becomes a `gaps:` line, never a claim.
-
-3. **Placement — five verdicts, after querying the graph.** Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; **MISSING only after the graph was actually asked**; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling **with the distinguishing line written** — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with `redirect_to:`, never a deletion.
-
-4. **Reconciliation — the machine detects and holds, it never decides.** Five outcomes: new / confirmation (the source is appended to the row — the base strengthens, it does not lengthen) / refinement (the old row goes `SUPERSEDED`, its text intact) / coexistence (disjoint scopes) / conflict → the whole set goes `CONTESTED`, **symmetrically**: flipping one cell by hand fails the check. Only new information resolves it — a later source, or **your ruling with a `basis:`**, the fact you know and the corpus does not. No basis, no ruling: a preference is not a fact. A ruling is challengeable — a later document reopens the case with your basis beside it.
-
-5. **Escalation in one batch at the end of the run**, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.
-
-Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard.
-
-## Key features
-
-- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
-- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
-- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
-- **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
-- **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
-- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
-- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus the spine's `stale`/`mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
-- **Installed support files**: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — `SKILL.md`, `templates.md`, `taxonomy.md`, `distillation.md`, `reconciliation.md`, `guides.md`, `vision.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` (the core is the family's shared spine — copy both, or neither).
-
-## Installation
-
-```bash
-npm install -g @antoneeo/kb-agentic-skill@latest
-```
-
-That is enough — the package's `postinstall` runs the installer. If your npm blocks
-install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
-
-```bash
-kb-agentic-install-skill
-```
-
-> The command is on your PATH only after a **global** (`-g`) install; after a local
-> `npm i`, invoke it as `npx kb-agentic-install-skill`.
-
-The installer copies `skills/kb-agentic-skill/` recursively into native skill locations:
-
-- Claude Code: `~/.claude/skills/kb-agentic/`
-- Codex: `~/.codex/skills/kb-agentic/`
-- Gemini CLI: `~/.gemini/skills/kb-agentic/`
-- Google Antigravity: `~/.gemini/config/skills/kb-agentic/` (override the home with `ANTIGRAVITY_HOME`)
-
-Restart the relevant agent, or reload skills where the CLI supports it.
-
-Initialize a project:
-
-```bash
-kb-agentic-init
-```
-
-Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
-
-## The family: three lenses, one spine
-
-| Package | Faithful to | Unit of work |
-|---|---|---|
-| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature |
-| `@antoneeo/kb-agentic-skill` (this one) | the documents you supply | topic |
-| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement |
-
-Triage, the Vision Gate, the review gates, the guide router, question discipline and the validator spine are byte-identical across the three. When two live in the same project, `routing.md` decides which lens owns a given piece of work, and any of the three validators gives the same verdict on the same tree.
-
-## Standalone vs Hybrid
-
-- **Standalone** — `ai_docs/` is the source of truth: vision, topics, corpus, audit, handoff.
-- **Hybrid with devPNT** — devPNT governs `M-VISION`, Master Plan, Action Plan and versioned artifacts; `ai_docs/` stays as readable context, fallback and shadow. Divergence between your request, the local Vision and the M-VISION is surfaced before any work.
-
-## Created By
-
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
-
-MIT (c) 2026 Antonio Pinto.
+# KB Agentic Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
+
+`kb-agentic` turns an AI agent into the keeper of a second brain built **on the documents you supply** — not on what the model remembers. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+
+The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill), transplanted from source code to knowledge: same process, one different fidelity discipline.
+
+## What it does
+
+Two axes are kept apart on purpose — **abstraction** (a topic made of topics: the graph edges) and **certainty** (how strongly the corpus supports a statement: the claim rows).
+
+1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction **is** the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as `original_path:` + `original_sha256:`. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limit: they let a human re-verify, they check nothing on their own. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
+
+2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists — and `anchor <path> <phrase>` produces it for you, matching spaces as `\s+` because a PDF extraction breaks phrases mid-line. **Gates are extracted alongside powers**: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is *ask*, never *produce*: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies **refuse to sum**. What the source does not assert becomes a `gaps:` line, never a claim.
+
+   **The source is exhausted, not sampled.** "Invents nothing" is a floor, and an extractor that stops when nothing it wrote is false stops on page twenty of a two-hundred-page manual with every row correct — which is exactly what a 200-page manual produces in the field. So a long source is read in **bounded windows** (30 pages by default, one plan task each, the ledger holding your place across sessions), and every window closes by advancing `extracted_through:` on the artifact's sidecar. That field is what makes "I am finished" falsifiable: claims with no coverage recorded are an error, a claim addressing a page past the declared coverage is a contradiction, and coverage short of the end is reported until it reaches it. Its limit is stated where it is written — **nothing proves a page was read**; what changes is that the shortcut must now be written down to pass. And exhaustive means read, never *a row per page*: a page that asserts nothing yields nothing.
+
+3. **Placement — five verdicts, after querying the graph.** Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; **MISSING only after the graph was actually asked**; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling **with the distinguishing line written** — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with `redirect_to:`, never a deletion.
+
+4. **Reconciliation — the machine detects and holds, it never decides.** Five outcomes: new / confirmation (the source is appended to the row — the base strengthens, it does not lengthen) / refinement (the old row goes `SUPERSEDED`, its text intact) / coexistence (disjoint scopes) / conflict → the whole set goes `CONTESTED`, **symmetrically**: flipping one cell by hand fails the check. Only new information resolves it — a later source, or **your ruling with a `basis:`**, the fact you know and the corpus does not. No basis, no ruling: a preference is not a fact. A ruling is challengeable — a later document reopens the case with your basis beside it.
+
+5. **Escalation in one batch at the end of the run**, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.
+
+Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
+
+## Key features
+
+- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
+- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
+- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
+- **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
+- **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
+- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
+- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus the spine's `stale`/`mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
+- **Installed support files**: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — `SKILL.md`, `templates.md`, `taxonomy.md`, `distillation.md`, `reconciliation.md`, `guides.md`, `vision.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` (the core is the family's shared spine — copy both, or neither).
+
+## Installation
+
+```bash
+npm install -g @antoneeo/kb-agentic-skill@latest
+```
+
+That is enough — the package's `postinstall` runs the installer. If your npm blocks
+install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
+
+```bash
+kb-agentic-install-skill
+```
+
+> The command is on your PATH only after a **global** (`-g`) install; after a local
+> `npm i`, invoke it as `npx kb-agentic-install-skill`.
+
+The installer copies `skills/kb-agentic-skill/` recursively into native skill locations:
+
+- Claude Code: `~/.claude/skills/kb-agentic/`
+- Codex: `~/.codex/skills/kb-agentic/`
+- Gemini CLI: `~/.gemini/skills/kb-agentic/`
+- Google Antigravity: `~/.gemini/config/skills/kb-agentic/` (override the home with `ANTIGRAVITY_HOME`)
+
+Restart the relevant agent, or reload skills where the CLI supports it.
+
+Initialize a project:
+
+```bash
+kb-agentic-init
+```
+
+Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+## The family: three lenses, one spine
+
+| Package | Faithful to | Unit of work |
+|---|---|---|
+| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature |
+| `@antoneeo/kb-agentic-skill` (this one) | the documents you supply | topic |
+| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement |
+
+Triage, the Vision Gate, the review gates, the guide router, question discipline and the validator spine are byte-identical across the three. When two live in the same project, `routing.md` decides which lens owns a given piece of work, and any of the three validators gives the same verdict on the same tree.
+
+## Standalone vs Hybrid
+
+- **Standalone** — `ai_docs/` is the source of truth: vision, topics, corpus, audit, handoff.
+- **Hybrid with devPNT** — devPNT governs `M-VISION`, Master Plan, Action Plan and versioned artifacts; `ai_docs/` stays as readable context, fallback and shadow. Divergence between your request, the local Vision and the M-VISION is surfaced before any work.
+
+## Created By
+
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
+
+MIT (c) 2026 Antonio Pinto.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -105,6 +105,34 @@ const writeIfNotExists = (relPath, content, description) => {
 
 seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
 
+const EOL = String.fromCharCode(10);
+// 5b. Merge hygiene for the append-only review log (F-028, defence in depth).
+// `merge=union` is a BUILT-IN driver: no per-clone `git config`, unlike
+// `merge=ours`, which silently does nothing until every clone configures it.
+// Rows are date-stamped, so interleaving them loses no information and their
+// order carries none. Create-only, and appended rather than rewritten: a user's
+// own .gitattributes is never clobbered.
+const gitattributes = () => {
+  const marker = 'ai_docs/audit/reviews/REVIEW_LOG.md';
+  const stanza = [
+    '',
+    '# agentic-sdlc: the review log is append-only and its rows are date-stamped,',
+    '# so a union merge keeps both sides instead of asking a human to pick one.',
+    marker + ' merge=union',
+    '',
+  ].join(EOL);
+  const filePath = path.join(cwd, '.gitattributes');
+  if (!fs.existsSync(path.join(cwd, '.git'))) return;   // not a git repo: nothing to do
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  if (current.includes(marker)) {
+    console.log('SKIP  .gitattributes already covers the review log.');
+    return;
+  }
+  fs.writeFileSync(filePath, current + stanza, 'utf8');
+  console.log('OK    .gitattributes: review log set to merge=union (concurrent reviews merge cleanly).');
+};
+gitattributes();
+
 // 6. Client discovery and protocol pointers
 console.log('\n--- Environment Analysis ---');
 

package/skills/kb-agentic-skill/SKILL.md

@@ -13,7 +13,7 @@ This skill guides knowledge management and documentation with a Document-First p
 
 Support files in the skill directory:
 - `templates.md`: templates for Vision, Knowledge ANALYSIS, Research SPIKE, SOP GUIDE, audit plan, and handoff.
-- `portability.md`: carrying knowledge between projects — what a bundle is, why export is a closure rather than a selection, and the rule that knowledge crosses a project boundary while authority does not (`prov: IMPORTED`). Read before `export`/`import`.
+- `portability.md`: carrying knowledge between projects — what a bundle is, why export is a closure rather than a selection, and the rule that knowledge crosses a project boundary while authority does not (`prov: IMPORTED`). Read before `export`/`import`.
 - `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization. Run at L3 before drafting.
 - `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
 - `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check.
@@ -74,8 +74,10 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
 | `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
-| `audit/handoff.md` (workstream registry) | One row per OPEN workstream (topic, level, status, since, next step) — refresh at every L3 closure and session end. ≤ 20 lines. | 5 / session end |
-| `audit/HANDOFF_[topic].md` | Session ends with that topic unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 4 / 5 / session end |
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
+| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
+| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
 | `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal accepted by user. | 4 / 5 |
 | `reference/GUIDE_[topic].md` (`source_kind: code`/`domain`) | Recognized high-complexity domain/concept with no CURRENT guide $\rightarrow$ duty to write autonomously. | 4 / 5 |
@@ -84,9 +86,11 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the knowledge catalog actually changed. | 1 / 5 |
 | `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
 | `topics/<slug>.md` | A placement verdict creates it (MISSING/INADEQUATE-child, `taxonomy.md`); reconciliation updates its claim rows. One node per topic — a similar-but-distinct concept is a sibling with `related:` + a written distinction, never a merge and never a duplicate. Merged/renamed nodes become tombstones (`status: SUPERSEDED` + `redirect_to:`), never deleted. | 4 |
-| a KB bundle (`export`) | Knowledge must leave this project. Export is L1 — it writes nothing into the corpus. **Importing one is L3**: a source enters the corpus and nodes are created, and a bundle is external input, so never L1 whatever its size (`portability.md`). | — |
+| a KB bundle (`export`) | Knowledge must leave this project. Export is L1 — it writes nothing into the corpus. **Importing one is L3**: a source enters the corpus and nodes are created, and a bundle is external input, so never L1 whatever its size (`portability.md`). | — |
 | `corpus/given/*` + sidecar | A source arrives: it becomes a content-addressed artifact with a sidecar carrying digest/date/`supersedes:`. A text source is copied verbatim. A non-text source yields its stored canonical extraction — copied **beside** the original when that is small enough to keep, or **instead of it** on a large binary corpus, where the original stays where it lives and is recorded as `original_path:`/`original_sha256:` (`distillation.md` §1, which owns this rule). Never edited after ingest — the digest check on whatever `given/` holds is what enforces it. | 4 |
 | `corpus/notes/*` | Something is said (`origin: elicited`), synthesised (`derived_from:`), or ruled (`basis:`). A note with none of the three is refused by the validator. | 4 / 5 |
+| `solutions/PLAN_[topic].md` + its ledger | A source too long for one context is ingested: **one task per reading window** (30 pages by default; the plan states the window used), each ending at a declared `extracted_through:`. That ledger is the register the ingestion resumes from across sessions — ingestion never builds a second one (`distillation.md` §3, `templates.md`). | 4 |
+| `corpus/given/*.meta.md` — `extracted_through:` | Every reading window closes by advancing it (`p=<n>`, `L<n>`, `complete`). Required once any claim cites the artifact: unstated, "I am finished" cannot be falsified, which is how a sampled 200-page manual passes for an ingested one. | 4 |
 | `INDEX.md`, `reference/INDEX.md`, `topics/INDEX.md`, `corpus/INDEX.md` | Regenerated by `sdlc_check.py index` at closure — never by hand; `validate` fails on a hand-edited one. | 5 |
 
 ## Operating Modes

package/skills/kb-agentic-skill/distillation.md

@@ -6,6 +6,19 @@ of knowledge get its file".
 **Does not answer**: where a claim's concept lives (above — `taxonomy.md`) or what
 happens when it disagrees with an existing one (`reconciliation.md`).
 
+> **North star.** *Not one assertion the source makes may be lost, and not one it does
+> not make may appear.* These are one rule, not two: a ledger that invents nothing but
+> keeps a tenth of the manual is as useless as one that keeps everything and made half
+> of it up.
+>
+> The unit is the **assertion**, not the byte: layout, ordering, repetition and page
+> furniture are not assertions. A page that asserts nothing yields nothing — exhaustive
+> means **read**, never *a row per page*. And "I am finished" is an assertion like any
+> other: `extracted_through:` is what makes it falsifiable.
+
+Everything below is that one rule made operable. Where a rule below does not reach the
+case in front of you, decide by the north star — both halves of it, in the same breath.
+
 ## 1. Intake — everything becomes a file first
 
 Ingest **never touches the graph**. First the source enters the corpus; the graph is fed
@@ -19,8 +32,9 @@ from the corpus, so everything is re-derivable when the rules improve.
 | an agent synthesis | a note in `corpus/notes/` with `derived_from:` listing its sources — a note with neither `origin:` nor `derived_from:` nor `basis:` is **model knowledge disguised as a source**, and the validator refuses it |
 | a practitioner ruling | a note with `basis:` (`reconciliation.md`) |
 
-Every sidecar (`<artifact>.meta.md`) carries: the digest, the date, provenance, and
-`supersedes:` when it replaces an earlier version. `corpus/INDEX.md` is generated.
+Every sidecar (`<artifact>.meta.md`) carries: the digest, the date, provenance,
+`supersedes:` when it replaces an earlier version, and `extracted_through:` once anything
+has been extracted from it (§3). `corpus/INDEX.md` is generated.
 
 **Extraction-as-artifact — the variant for a large binary corpus.** Copying gigabytes
 of PDFs into the docs root buys nothing: what the digest protects is *the bytes a
@@ -81,6 +95,33 @@ the offset span it came from. The extractor **invents nothing**: no labels, no
 summaries-as-claims, no filling of gaps from model knowledge. What the source does not
 assert does not become a row — it may become a `gaps:` entry on the topic.
 
+**Exhaust the source; never sample it.** *Invents nothing* is a floor, and a floor is not
+a target: an extractor that stops the moment nothing it wrote is false stops on page
+twenty of a two-hundred-page manual, with every row it emitted correct. A source is
+finished when every page has been **read**, not when enough rows exist. The claim count
+settles nothing in either direction — a short source legitimately yields few rows and a
+dense one yields many — so it can never distinguish *finished* from *sampled*.
+
+**Read in a bounded window, and let the plan hold your place.** A long source does not fit
+in one context, and an agent that runs out of room has two moves: summarize, or stop
+silently. It summarizes. So read a fixed span, emit that span's rows, and only then move
+on. **30 pages is the default and the plan states the window actually used** — page
+density and context budgets differ per source and per model, so the number is declared
+per ingestion rather than assumed. The window is also the unit of resumption: one plan
+task per window (below), so a session that ends mid-source resumes at the next task
+instead of re-reading or guessing where it stopped.
+
+**Close each window by advancing `extracted_through:`** on the artifact's sidecar
+(`templates.md`) — `p=<n>`, `L<n>`, or `complete` when the last page is read. It is what
+makes "I am finished" falsifiable, and it makes the rows and the field check each other:
+a claim whose locator addresses past the declared coverage is a contradiction, and the
+validator reports it. Say the limit out loud, as with `original_sha256` above:
+**nothing here proves a page was read.** A field advanced without extracting is not
+mechanically detectable, precisely because a page that asserts nothing legitimately
+yields no rows — that direction is verified at the ingestion review (`review.md`), like
+the gates below. What the field buys is that the shortcut must now be **written down** to
+pass, and a written claim can be reopened by anyone who cares to.
+
 **Cover the gates, not only the powers.** "One row per assertion" is obeyable and still
 leaves the ledger optimistic: reading a capability paragraph, an extractor emits the
 capability and moves on, because that is what the paragraph asserts. So for every row
@@ -110,10 +151,17 @@ locator without it is how two generation rounds get lost.
 
 Extraction is read-only on the corpus and blind to the graph: rows go to placement
 (`taxonomy.md`) afterwards. Ingesting a document set is **L3 by Rule Zero**; the
-ingestion plan derives from the ANALYSIS Action Plan, one task per source, each task's
-`verify` = "claim rows parse; every source resolves under the docs root". Serial in v1:
+ingestion plan derives from the ANALYSIS Action Plan, **one task per reading window** —
+a source that fits one window is one task, a 200-page manual at 30 pages is seven — each
+task's `verify` = "claim rows parse; every source resolves under the docs root; the
+sidecar's `extracted_through:` reaches this window's last page". Serial in v1:
 correctness first.
 
+The plan's ledger already records `status: done` per task (`templates.md`), which is the
+register that survives a session boundary — so ingestion **builds no second one**. What
+has been covered is recorded (the sidecar, the ledger); what remains is derived from
+them, never stored.
+
 ## 4. Signal discipline (what "distillation" still means)
 
 - Contract-first for any prose you write around the rows (reader, action, payload).

package/skills/kb-agentic-skill/scripts/sdlc_check.py

@@ -92,6 +92,8 @@ DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 LOC_PAGE_RE = re.compile(r"^p=(\d+)@(\d+)-(\d+)$")
 LOC_LINE_RE = re.compile(r"^L(\d+)-(\d+)$")
 LOC_CELL_RE = re.compile(r"^Sheet[^!]+![A-Z]+\d+$")
+# F-031. How far a source has been read, in the unit its locators address.
+EXTRACTED_THROUGH_RE = re.compile(r"^(?:complete|p=(\d+)|L(\d+))$")
 
 # Unit conventions, documented in templates.md. effort in person-days
 # (8h day, 5d week, 21d month); duration in calendar days; cost within ONE
@@ -664,6 +666,64 @@ def kb_build_topic_index(root):
     return "\n".join(lines) + "\n"
 
 
+def kb_parse_extracted_through(value):
+    """('complete', None) | ('p', n) | ('L', n), or None when the value is not a
+    coverage statement.
+
+    Fail-closed on purpose: a field whose whole job is to be checkable must be
+    checkable, so an unreadable value is an error rather than a silent pass."""
+    m = EXTRACTED_THROUGH_RE.match((value or "").strip())
+    if not m:
+        return None
+    if m.group(1):
+        return "p", int(m.group(1))
+    if m.group(2):
+        return "L", int(m.group(2))
+    return "complete", None
+
+
+def kb_extraction_extent(artifact, kind):
+    """How far the stored bytes go, in the unit `kind` — or None when nothing
+    measurable is stored.
+
+    Opens exactly the file `kb_check_locator` opens for that locator form: pages
+    live in the stored extraction beside the original, lines in the artifact
+    itself. Coverage is therefore measured against the same bytes a locator
+    addresses, and a binary is never read as text (a .pdf with no extraction
+    beside it is simply unmeasurable — the p= branch needs the .txt)."""
+    if kind == "p":
+        ext = artifact if artifact.suffix == ".txt" else artifact.with_suffix(".txt")
+        if not ext.is_file():
+            return None
+        return len(sdlc_core.read_text(ext).split("\f"))
+    if kind == "L":
+        if not artifact.is_file():
+            return None
+        return sdlc_core.read_text(artifact).count("\n") + 1
+    return None
+
+
+def kb_coverage_cell(artifact, through):
+    """The coverage fact for one corpus row.
+
+    EVERY artifact gets one, including the finished ones: printing only the
+    incomplete ones would turn this index into 'the set that is not current',
+    which the Vision refuses (r9). It is a fact on an existing row, never a
+    filter and never a sort key."""
+    if not (through or "").strip():
+        return "extraction not recorded"
+    parsed = kb_parse_extracted_through(through)
+    if parsed is None:
+        return "extracted through %s (unreadable)" % through.strip()
+    kind, n = parsed
+    if kind == "complete":
+        return "extracted through complete"
+    total = kb_extraction_extent(artifact, kind)
+    stated = ("p=%d" % n) if kind == "p" else ("L%d" % n)
+    return "extracted through %s of %d" % (stated, total) if total \
+        else "extracted through %s" % stated
+
+
 def kb_build_corpus_index(root):
     """One row per corpus artifact, from sidecars and note frontmatter."""
     corpus = root / "corpus"
@@ -676,9 +736,10 @@ def kb_build_corpus_index(root):
             meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
             orig = meta_p.name[:-len(".meta.md")]
             sup = (meta.get("supersedes") or "").strip()
-            lines.append("- `%s` — %s%s" % (
+            lines.append("- `%s` — %s%s — %s" % (
                 orig, (meta.get("date") or "undated"),
-                (" — supersedes `%s`" % sup) if sup else ""))
+                (" — supersedes `%s`" % sup) if sup else "",
+                kb_coverage_cell(given / orig, meta.get("extracted_through"))))
     notes = corpus / "notes"
     if notes.is_dir():
         lines.append("")
@@ -692,12 +753,125 @@ def kb_build_corpus_index(root):
     return "\n".join(lines) + "\n"
 
 
+def kb_cited_extents(root):
+    """Per artifact file name, what the claim rows say about it: the highest page
+    and the highest line any locator addresses (with the row that says so), and
+    every row citing it. One walk of topics/, shared by the supersession and the
+    coverage checks — two walks of the same tree for two questions is how the
+    answers start disagreeing."""
+    cited = {}
+    topics = root / "topics"
+    if not topics.is_dir():
+        return cited
+    for p in sorted(topics.glob("*.md")):
+        for row in kb_parse_claims(sdlc_core.read_text(p))[0]:
+            where = "topics/%s:%d" % (p.name, row["_line"])
+            for src in row["source"].split(";"):
+                src = src.strip()
+                if not src:
+                    continue
+                path_s, loc = src.rsplit("#", 1) if "#" in src else (src, "")
+                parts = Path(path_s.strip().replace("\\", "/")).parts
+                if parts[-3:-1] != ("corpus", "given"):
+                    # Keyed by file name, so a note sharing a name with an
+                    # artifact would otherwise be attributed to it and inflate
+                    # its extents. Both consumers here ask only about given/.
+                    continue
+                name = parts[-1]
+                e = cited.setdefault(name, {"p": 0, "p_where": None,
+                                            "L": 0, "L_where": None, "rows": []})
+                e["rows"].append(where)
+                m = LOC_PAGE_RE.match(loc.strip())
+                if m and int(m.group(1)) > e["p"]:
+                    e["p"], e["p_where"] = int(m.group(1)), where
+                    continue
+                m = LOC_LINE_RE.match(loc.strip())
+                if m and int(m.group(2)) > e["L"]:
+                    e["L"], e["L_where"] = int(m.group(2)), where
+    return cited
+
+
+def _kb_cited_for(cited, artifact_name):
+    """Claims may cite the original or its stored extraction — both address the
+    same bytes, so both count as citing this artifact."""
+    names = [artifact_name]
+    if not artifact_name.endswith(".txt"):
+        names.append(Path(artifact_name).with_suffix(".txt").name)
+    found = [cited[n] for n in names if n in cited]
+    if not found:
+        return None
+    merged = dict(found[0])
+    for e in found[1:]:
+        for kind in ("p", "L"):
+            if e[kind] > merged[kind]:
+                merged[kind], merged[kind + "_where"] = e[kind], e[kind + "_where"]
+        merged["rows"] = merged["rows"] + e["rows"]
+    return merged
+
+
+def kb_check_coverage(rel, artifact, through, facts, errors, warnings):
+    """`extracted_through:` against the rows and against the stored bytes (F-031).
+
+    Four outcomes, and the boundary between them is the whole point: claims with
+    no field errors (an unfalsifiable 'done'); a field that contradicts the bytes
+    or the rows errors; a field short of the end warns, because partial work is
+    legal mid-ingestion; an artifact nobody extracted from stays silent.
+
+    The limit, stated where the code is: nothing here proves a page was READ. A
+    field advanced without extracting is invisible to any checker, since a page
+    that asserts nothing legitimately yields no rows — that direction belongs to
+    the ingestion review. What this buys is that the shortcut must be written
+    down to pass."""
+    if not through:
+        if facts:
+            errors.append("%s: claims cite this artifact and the sidecar has no "
+                          "'extracted_through:' — how far a source was read is an "
+                          "assertion like any other, and unstated 'I am finished' "
+                          "cannot be falsified. Record it: 'p=<n>', 'L<n>', or "
+                          "'complete' (first row at %s)" % (rel, facts["rows"][0]))
+        return
+    parsed = kb_parse_extracted_through(through)
+    if parsed is None:
+        errors.append("%s: extracted_through: %r is not a coverage statement — use "
+                      "'complete', 'p=<n>' or 'L<n>'" % (rel, through))
+        return
+    kind, n = parsed
+    if kind == "complete":
+        return
+    other = "L" if kind == "p" else "p"
+    unit = "pages" if kind == "p" else "lines"
+    total = kb_extraction_extent(artifact, kind)
+    if facts and facts[other] and not facts[kind]:
+        errors.append("%s: coverage is stated in %s while every claim addresses %s "
+                      "(%s) — stated in the wrong unit it compares with nothing, "
+                      "and nothing here is checkable"
+                      % (rel, unit, "lines" if kind == "p" else "pages",
+                         facts[other + "_where"]))
+        return
+    if total and n > total:
+        errors.append("%s: extracted_through: %s, past the end of the stored bytes "
+                      "(%d %s) — coverage cannot exceed what was stored"
+                      % (rel, through, total, unit))
+    elif total and n < total:
+        warnings.append("%s: extracted through %s of %d %s — ingestion is incomplete "
+                        "(legal mid-work: a source is finished when every page has "
+                        "been read, not when enough rows exist)"
+                        % (rel, through, total, unit))
+    if facts and facts[kind] > n:
+        reached = ("p=%d" % facts[kind]) if kind == "p" else ("L%d" % facts[kind])
+        errors.append("%s: a claim addresses %s, past the declared coverage %s (%s) — "
+                      "the sidecar and the rows contradict each other; one of the two "
+                      "is wrong" % (rel, reached, through, facts[kind + "_where"]))
+
+
 def kb_corpus_check(root):
-    """Corpus integrity: digests, supersession, laundered notes. Findings only."""
+    """Corpus integrity: digests, supersession, coverage, laundered notes.
+    Findings only."""
     errors, warnings = [], []
     corpus = root / "corpus"
     if not corpus.is_dir():
         return errors, warnings
+    cited = kb_cited_extents(root)
     superseded = set()
     given = corpus / "given"
     if given.is_dir():
@@ -721,6 +895,9 @@ def kb_corpus_check(root):
                 if not (given / sup).is_file():
                     warnings.append("%s: supersedes %r which is not in given/"
                                     % (rel, sup))
+            kb_check_coverage(rel, orig,
+                              (meta.get("extracted_through") or "").strip(),
+                              _kb_cited_for(cited, orig.name), errors, warnings)
     notes = corpus / "notes"
     if notes.is_dir():
         for p in sorted(notes.glob("*.md")):
@@ -730,20 +907,11 @@ def kb_corpus_check(root):
                 errors.append("corpus/notes/%s: neither 'derived_from:' nor "
                               "'origin:' nor 'basis:' — model knowledge disguised "
                               "as a source" % p.name)
-    # claims resting on superseded originals (UC4)
-    if superseded:
-        topics = root / "topics"
-        if topics.is_dir():
-            for p in sorted(topics.glob("*.md")):
-                rows, _ = kb_parse_claims(sdlc_core.read_text(p))
-                for row in rows:
-                    for src in row["source"].split(";"):
-                        name = Path(src.split("#")[0].strip()).name
-                        if name in superseded:
-                            warnings.append(
-                                "topics/%s:%d: claim rests on %s, which a newer "
-                                "version supersedes — re-verify or re-place"
-                                % (p.name, row["_line"], name))
+    # claims resting on superseded originals (UC4), from the same single walk
+    for name in sorted(superseded):
+        for where in (cited.get(name) or {}).get("rows", []):
+            warnings.append("%s: claim rests on %s, which a newer version "
+                            "supersedes — re-verify or re-place" % (where, name))
     return errors, warnings
 
 

package/skills/kb-agentic-skill/scripts/sdlc_core.py

@@ -215,7 +215,11 @@ DEFAULT_DOMAIN = "code"
 PORTABLE_CHECKS = {}
 # Which check namespaces this distribution actually carries. Set by the entry point;
 # a `checks:` entry outside it WARNS visibly rather than passing silently.
-_ENTRY_POINT = {"domain": DEFAULT_DOMAIN, "provides": ()}
+_ENTRY_POINT = {"domain": DEFAULT_DOMAIN, "provides": (), "script": "sdlc_check.py"}
+# "script" is what generated headers tell the reader to RUN. Declared, never
+# derived from sys.argv: the generated bytes must not depend on how the command
+# was invoked, or the alignment check would fail on the invocation instead of on
+# the content.
 
 
 # --- distribution profile ----------------------------------------------------
@@ -292,10 +296,17 @@ def portable_check(name):
     return register
 
 
-def set_entry_point(domain, provides=()):
+def set_entry_point(domain, provides=(), script=None):
     """Declare which domain this distribution is and which check namespaces it ships."""
     _ENTRY_POINT["domain"] = domain
     _ENTRY_POINT["provides"] = tuple(provides)
+    if script:
+        _ENTRY_POINT["script"] = script
+
+
+def entry_script():
+    """The command name a generated header tells the reader to run."""
+    return _ENTRY_POINT["script"]
 
 
 def project_default_domain(root):
@@ -727,6 +738,142 @@ def build_manifest(root):
     return "\n".join(lines).rstrip() + "\n"
 
 
+# ------------------------------------------------- workstream registry (F-028)
+# audit/handoff.md is GENERATED from one source file per open workstream, so two
+# writers working two workstreams touch two different files. Row-per-workstream
+# alone was not enough -- F-019 had that and the file still conflicted twice,
+# because a file-global `Date:` header defeats row-level ownership. The header is
+# now DERIVED, so no writer touches it.
+
+REGISTRY_COLUMNS = ("Workstream", "Level", "Branch", "Status", "Since",
+                    "Next step", "Details")
+REGISTRY_KEYS = ("workstream", "level", "branch", "status", "since", "next")
+REGISTRY_CAP = 20               # a signal, never a truncation (see cmd_index)
+PROJECT_NOTES = "project_notes.md"   # NOT handoff_notes.md: the HANDOFF_*.md
+# glob is case-insensitive on Windows, and that name would be collected as a
+# source. The trap is real; the name is the fix.
+
+
+def registry_header():
+    return (f"<!-- GENERATED by {entry_script()} index - do not edit by hand. "
+            f"Source of truth: the HANDOFF_*.md files in {docs_dir()}/audit/. -->")
+
+
+def list_workstreams(root):
+    """[(path, meta)] for audit/HANDOFF_*.md carrying registry frontmatter.
+
+    Opt-in by the presence of `workstream:` -- a project whose handoff is still
+    hand-written has no sources, so nothing generates and nothing errors (the
+    F-019 migration lesson). Sorted by workstream id: the alignment check is a
+    byte comparison, and glob order differs across filesystems."""
+    aud = ai_path(root, "audit")
+    out = []
+    if not aud.is_dir():
+        return out
+    for p in sorted(aud.glob("HANDOFF_*.md")):
+        meta = load_frontmatter(read_text(p).splitlines())
+        if str(meta.get("workstream") or "").strip():
+            out.append((p, meta))
+    out.sort(key=lambda pm: (str(pm[1].get("workstream")).strip().lower(), pm[0].name))
+    return out
+
+
+def _registry_cell(value):
+    text = str(value if value is not None else "").strip()
+    return text.replace("|", "\\|") or "-"
+
+
+def build_registry(root):
+    """The generated registry, or "" when there is no source to build it from.
+
+    Deterministic by construction: sorted rows, and a `Date:` taken from the
+    newest `updated:` VALUE written inside the sources -- never a filesystem
+    timestamp. Git does not preserve mtimes, so an mtime-derived header would
+    regenerate differently in every fresh clone and the alignment check would
+    fire on a tree nobody touched."""
+    rows = list_workstreams(root)
+    if not rows:
+        return ""
+    stamp = max(str(m.get("updated") or m.get("since") or "").strip() or "0000-00-00"
+                for _p, m in rows)
+    lines = ["# Handoff — workstream registry",
+             f"Date: {stamp} (UTC)",
+             "",
+             registry_header(),
+             "",
+             "| " + " | ".join(REGISTRY_COLUMNS) + " |",
+             "|" + "---|" * len(REGISTRY_COLUMNS)]
+    for p, meta in rows:
+        extra = str(meta.get("details") or "").strip()
+        details = f"{p.name} · {extra}" if extra else p.name
+        cells = [_registry_cell(meta.get(k)) for k in REGISTRY_KEYS]
+        lines.append("| " + " | ".join(cells) + f" | {_registry_cell(details)} |")
+    notes = ai_path(root, "audit", PROJECT_NOTES)
+    if notes.is_file():
+        body = read_text(notes).strip()
+        if body:
+            lines += ["", "## Project-wide notes", "", body]
+    return "\n".join(lines) + "\n"
+
+
+def parse_registry_rows(text):
+    """Workstream ids in a registry table, hand-written or generated."""
+    ids = []
+    for line in text.splitlines():
+        s = line.strip()
+        if not s.startswith("|") or set(s) <= {"|", "-", " ", ":"}:
+            continue
+        first = s.strip("|").split("|")[0].strip()
+        if first and first.lower() != "workstream":
+            ids.append(first)
+    return ids
+
+
+def registry_conversion_blockers(root):
+    """What stops `index` from writing over a hand-written handoff.md.
+
+    The mixed state is the trap this exists for: converting one row at a time
+    leaves a project at one source file and five hand-written rows, and
+    regenerating from the one source DELETES the other five -- silently, in the
+    file whose whole purpose is not losing them. So conversion is per project.
+    Empty list = writing is safe."""
+    hand = ai_path(root, "audit", "handoff.md")
+    if not hand.is_file():
+        return []
+    text = read_text(hand)
+    if "GENERATED by sdlc_check.py index" in text:
+        return []                                   # already ours
+    blockers = []
+    known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
+    orphans = [r for r in parse_registry_rows(text) if r not in known]
+    if orphans:
+        blockers.append("rows no HANDOFF_*.md accounts for: " + ", ".join(orphans))
+    # Everything else in the file must have a home too, or it is lost on write:
+    # a pre-1.17 narrative handoff carries no table at all, so orphan rows alone
+    # would not notice it.
+    notes_ok = ai_path(root, "audit", PROJECT_NOTES).is_file()
+    leftovers, in_notes = [], False
+    for line in text.splitlines():
+        s = line.strip()
+        if not s or s.startswith("|") or s.startswith("<!--"):
+            continue
+        if s.startswith("# ") or re.match(r"^(?:Date|Data):", s):
+            continue
+        if re.match(r"^##\s+Project-wide notes\s*$", s):
+            in_notes = True
+            continue
+        if s.startswith("## "):
+            in_notes = False
+        if in_notes and notes_ok:
+            continue
+        leftovers.append(s)
+    if leftovers:
+        blockers.append("content outside the table with nowhere to go (%d line(s), first: %r) "
+                        "-- project-wide notes belong in audit/%s"
+                        % (len(leftovers), leftovers[0][:60], PROJECT_NOTES))
+    return blockers
+
+
 def list_guides(root):
     """[(rel_to_ai_docs, path, meta, text)] for ai_docs/reference/GUIDE_*.md."""
     ref = ai_path(root, "reference")
@@ -821,6 +968,30 @@ def cmd_index(root):
                         "a comprehension map (`source_kind: code`) -- see `guides.md`.\n",
                         encoding="utf-8")
         print(f"[ok] guide router regenerated (empty stub): {gidx}")
+    return max(rc_registry(root), 0)
+
+
+def rc_registry(root):
+    """Write the generated workstream registry, or refuse and say why (F-028)."""
+    ws = list_workstreams(root)
+    if not ws:
+        return 0                # no sources: a hand-written handoff is untouched
+    blockers = registry_conversion_blockers(root)
+    hand = ai_path(root, "audit", "handoff.md")
+    if blockers:
+        print(f"[ERROR] {docs_dir()}/audit/handoff.md NOT regenerated -- it still holds "
+              "state no source accounts for:")
+        for b in blockers:
+            print(f"          - {b}")
+        print("          Convert the whole registry at once (templates.md): converting "
+              "one row at a time is the state that loses the others.")
+        return 1
+    hand.parent.mkdir(parents=True, exist_ok=True)
+    hand.write_text(build_registry(root), encoding="utf-8")
+    print(f"[ok] workstream registry regenerated: {hand}")
+    if len(ws) > REGISTRY_CAP:
+        print(f"[warn] {len(ws)} open workstreams: the registry is meant to stay under "
+              f"{REGISTRY_CAP}. Nothing was truncated -- closing one is the fix.")
     return 0
 
 
@@ -1257,8 +1428,33 @@ def cmd_validate(root, strict=False, hybrid=False):
         elif norm_text(read_text(gidx)) != norm_text(build_guide_index(root)):
             errors.append(f"{docs_dir()}/reference/INDEX.md not aligned with the guides: run 'sdlc_check.py index'")
 
-    # Handoff: header and freshness
+    # Handoff: alignment with its sources (F-028), then header and freshness
     hand = ai / "audit" / "handoff.md"
+    workstreams = list_workstreams(root)
+    if workstreams:
+        if not hand.is_file():
+            errors.append(f"{docs_dir()}/audit/handoff.md missing while HANDOFF_*.md sources "
+                          "exist: the registry is the only place a cold agent sees the open "
+                          "workstreams -- run 'sdlc_check.py index'")
+        elif norm_text(read_text(hand)) != norm_text(build_registry(root)):
+            errors.append(f"{docs_dir()}/audit/handoff.md not aligned with its HANDOFF_*.md "
+                          "sources: run 'sdlc_check.py index'. A merge resolved by hand is "
+                          "exactly what this catches")
+        if len(workstreams) > REGISTRY_CAP:
+            warnings.append(f"{len(workstreams)} open workstreams: the registry is meant to "
+                            f"stay under {REGISTRY_CAP}")
+        # Two files claiming one workstream is the collision this design does NOT
+        # fix (two people opening the same work under different file names). It
+        # would otherwise show up as two identical-looking rows and nothing else.
+        seen = {}
+        for p, meta in workstreams:
+            wid = str(meta.get("workstream")).strip()
+            if wid in seen:
+                warnings.append(f"{docs_dir()}/audit/{p.name} and {seen[wid]} both claim "
+                                f"workstream '{wid}': the registry shows two rows for one "
+                                "workstream — decide which file owns it")
+            else:
+                seen[wid] = p.name
     if hand.is_file():
         m = re.search(r"(?:Date|Data):\s*(\d{4}-\d{2}-\d{2})", read_text(hand))
         if not m:

package/skills/kb-agentic-skill/templates.md

@@ -83,7 +83,7 @@ Must-reads for this project, in order. The full manifest of canonical docs is
 1. `reference/INDEX.md` — the guide router: which guide already governs the work you are about to do (generated).
 2. `vision/project_vision.md` — why the project exists (check its Status first).
 3. `strategic/architecture.md` — how it is built.
-4. `audit/handoff.md` — where work stopped last session (if present).
+4. `audit/handoff.md` — where work stopped last session (generated from the `HANDOFF_*.md` beside it; never edited by hand).
 
 Directory purposes: `vision/` (project direction), `strategic/` (architecture and
 feature catalog), `reference/` (operative guides), `solutions/` (per-feature
@@ -355,6 +355,25 @@ owned, validator-read-only): `{ "<task_id>": {"status": "done", "verify_result":
 sentinel skips re-dispatch; any other value (or a missing `status`) is treated
 as pending. A ledger id absent from the plan is a non-fatal orphan warning.
 
+**Ingestion plans: one task per reading window** (`distillation.md` §3). A source too
+long for one context becomes several tasks over the same artifact, each ending at a
+declared page:
+
+```json
+{
+  "id": "T2",
+  "title": "Extract manual-1a2b3c4d.pdf, pages 31-60",
+  "paths": ["ai_docs/topics/pricing.md",
+            "ai_docs/corpus/given/manual-1a2b3c4d.pdf.meta.md"],
+  "produces": ["ai_docs/corpus/given/manual-1a2b3c4d.pdf.meta.md#extracted_through=p=60"],
+  "verify": "python <skill_dir>/scripts/sdlc_check.py check"
+}
+```
+
+That ledger **is** the register an ingestion resumes from across sessions, so ingestion
+adds no second one: what has been covered is recorded (here and on the sidecar), and what
+remains is derived — the next window is the next pending task.
+
 ## ai_docs/audit/audit_plan.md (Standalone mode only)
 
 The `Reference` field (git hash or ISO UTC timestamp) is managed by `sdlc_check.py mark` — do not fill it by hand. Freshness is verified with `sdlc_check.py stale`.
@@ -370,36 +389,50 @@ States: PENDING (to analyze) | ANALYZED (analyzed, with reference) | SKIPPED (wi
 | vendor/ | SKIPPED | - | vendored code |
 ```
 
-## ai_docs/audit/handoff.md — the workstream registry
-
-One row per OPEN workstream, ≤ 20 lines. **Parallel-safe by construction**: closing
-one milestone removes one row and never touches another's resume point — the defect
-this replaces was a single narrative slot where the last session to close overwrote
-everyone else's handoff. It is an **inventory for lookup** (like the generated
-manifest), not a work board: no assignment, no due dates, no execution ordering.
-
-Updated at every L3 closure (row removed) AND at session end with work still
-IN_PROGRESS (row refreshed) — see Write Triggers.
-
-**Coming from a pre-1.17 project** (narrative handoff with `## Active features` /
-`## Next step` / `## Session notes`): nothing is broken and nothing is urgent — the
-validator only checks the `Date:` header and its age, and the orientation hook reads
-the file verbatim. Read it as a one-row registry, and convert it the next time the
-write trigger fires: each `## Active features` bullet becomes a row, `## Next step`
-becomes that row's next step, `## Session notes` becomes `## Project-wide notes`.
-Migrating a repository that is not being worked on buys nothing.
+## ai_docs/audit/handoff.md — the workstream registry (GENERATED)
+
+One row per OPEN workstream. **Never written by hand**: `sdlc_check.py index` builds
+it from the `HANDOFF_[topic].md` files, and `validate` errors when the two disagree.
+It is an **inventory for lookup** (like the generated manifest), not a work board: no
+assignment, no due dates, no execution ordering, no holder.
+
+**Why generated, and not just one row per workstream.** Row-per-workstream alone was
+tried and was not enough: two workstreams opened from one base still conflicted twice
+in this file, because a file-global `Date:` header defeats row-level ownership no
+matter how few rows each writer touches. So the truth moved into the per-workstream
+file, and the header is derived (the newest `updated:` in the sources — a value, never
+a filesystem timestamp, which git does not preserve). Two writers on two workstreams
+now touch two different files. The generated view can still conflict at merge; that
+conflict is resolved **mechanically** by re-running `index`, never by hand, and
+`validate` refuses CLEAN until the file matches its sources.
+
+Project-wide notes have their own source, `ai_docs/audit/project_notes.md`, appended
+verbatim under `## Project-wide notes`. (Not `handoff_notes.md`: the `HANDOFF_*.md`
+glob is case-insensitive on Windows and would collect it as a workstream.)
+
+**Converting an existing project** — lazily, at the first write, and **all at once**.
+Converting one row at a time is the state that loses the others: the next `index`
+would regenerate from the one source and drop the rest. `index` refuses to write while
+anything in the file is unaccounted for, and names it. A pre-1.17 narrative handoff
+(`## Active features` / `## Next step` / `## Session notes`) is the same conversion:
+each bullet becomes a `HANDOFF_[topic].md`, `## Session notes` becomes
+`project_notes.md`. A project with no sources yet is not touched and reports nothing —
+migrating a repository nobody is working on buys nothing.
 
 ```markdown
 # Handoff — workstream registry
 Date: 2026-06-11 (UTC)
 
+<!-- GENERATED by sdlc_check.py index - do not edit by hand. Source of truth: the HANDOFF_*.md files in ai_docs/audit/. -->
+
 | Workstream | Level | Branch | Status | Since | Next step | Details |
 |---|---|---|---|---|---|---|
 | F-001 SSO login | L3 | feature/sso-login | PROGRESS | 2026-06-10 | wire callback tests | HANDOFF_login_sso.md · ANALYSIS_login_sso.md |
-| F-002 Audit refresh | L3 | feature/audit | PAUSED | 2026-06-02 | resume at Phase 4 | ANALYSIS_audit_refresh.md (no volatile state) |
+| F-002 Audit refresh | L3 | feature/audit | PAUSED | 2026-06-02 | resume at Phase 4 | HANDOFF_audit_refresh.md · ANALYSIS_audit_refresh.md |
 
 ## Project-wide notes
-<!-- one or two lines: release pending, environment quirks that affect everyone -->
+
+<!-- from audit/project_notes.md: release pending, environment quirks that affect everyone -->
 ```
 
 ## ai_docs/audit/reviews/REVIEW_LOG.md
@@ -434,21 +467,47 @@ records the realization actually used — fresh subagent, one-shot client run, o
 honest; writing nothing, or implying independence you did not have, is the failure
 this column exists to prevent. `findings_real` is how many raised findings survived
 triage: over time it is the only evidence of whether the gate earns its cost.
-
-## ai_docs/audit/HANDOFF_[topic].md — volatile resume logistics (ephemeral)
-
-**Resume logistics ONLY; the ANALYSIS Diary keeps the durable narrative (DRY).**
-The boundary: Diary = what happened and why (decisions, state of the work — survives
-forever); this file = how to pick the work back up (branch/worktree, uncommitted
-state, environment notes, the next concrete command — worthless once resumed).
-Created only when a session pauses the feature WITH volatile state to record;
-**DELETED at the feature's closure**, in the same step that flips the ANALYSIS to
-COMPLETED — anything in it worth keeping was in the wrong file.
+Concurrent reviews: `init` writes a `.gitattributes` stanza giving this file
+`merge=union` — a **built-in** driver (no per-clone `git config`, unlike
+`merge=ours`, which silently does nothing until every clone configures it).
+Rows are date-stamped and their order carries no meaning, so a union merge keeps
+both sides instead of asking a human to choose. It is defence in depth: without
+git, or without the stanza, the outcome is today's — one conflict you resolve by
+hand, never a lost row.
+
+
+## ai_docs/audit/HANDOFF_[topic].md — one open workstream, its own file
+
+**The authored home of that workstream's registry row**, and the only one: the
+registry is generated from these files. **One exists for every OPEN workstream**, with
+or without volatile state — a workstream whose file is missing has no row, and a
+workstream with no row is invisible to the next cold agent. **DELETED at the feature's
+closure**, in the same step that flips the ANALYSIS to COMPLETED: deleting it *is*
+removing the row.
+
+**The DRY boundary, restated because the file is no longer rare.** What used to keep
+narrative out of it was that it barely existed; now it always does. So: the ANALYSIS
+Diary keeps **what happened and why** (decisions, state of the work — survives
+forever), and this file keeps **the row plus the resume logistics** — how to pick the work back up (branch,
+worktree, uncommitted state, the next concrete command — worthless once resumed).
+Prose that would still be worth reading after closure is in the wrong file, because
+this one is deleted.
+
+The frontmatter IS the row. `workstream:` is what marks the file as a source: without
+it the file is still a perfectly good volatile note, and nothing generates.
 
 ```markdown
+---
+workstream: F-001 SSO login
+level: L3
+branch: feature/sso-login (worktree ../wt-sso)
+status: PROGRESS
+since: 2026-06-10
+next: wire the callback tests
+details: ANALYSIS_login_sso.md
+updated: 2026-06-11
+---
 # HANDOFF: [topic] (ephemeral — deleted at closure)
-Updated: 2026-06-11 (UTC)
-Branch: feature/sso-login (worktree ../wt-sso)
 
 ## Resume state
 <!-- uncommitted files, half-run migrations, env vars, running services -->
@@ -460,6 +519,19 @@ Branch: feature/sso-login (worktree ../wt-sso)
 <!-- traps discovered this session that bite on resume (locks, CRLF, flaky test) -->
 ```
 
+`updated:` is the date this file last changed, and the newest one across all sources
+becomes the registry's `Date:` header — which is why no writer ever edits that header
+and why two concurrent writers no longer collide on it. `details:` holds the *other*
+pointers (the ANALYSIS, a review log entry); the generator prepends this file's own
+name, so nothing points at itself by hand.
+
+## ai_docs/audit/project_notes.md — the registry's project-wide notes (source)
+
+Plain lines, no frontmatter, appended verbatim to the generated registry under
+`## Project-wide notes`. Release pending, environment quirks, anything true for
+everyone rather than for one workstream. It exists so that generating the registry
+cannot destroy notes that belong to no workstream.
+
 ## ai_docs/strategic/architecture.md and existing_features.md
 
 Canonical docs: they open with the header (`description:`/`status:`) so they enter the `INDEX.md` manifest cleanly.
@@ -553,6 +625,7 @@ date: 2026-08-01
 provenance: GIVEN
 supersedes: contract-1a2b3c4d.pdf
 extractor: pdftotext 24.02, form-feed page breaks, whitespace collapsed
+extracted_through: p=212
 ---
 Handed over by <who>, <context in one line>.
 ```
@@ -561,6 +634,18 @@ Handed over by <who>, <context in one line>.
 without it the two content-addressed files are unrelated. `extractor:` pins the stored
 canonical extraction (`<name>-<hash8>.txt`) that offset locators address.
 
+`extracted_through:` is how far the source has been read — `p=<n>` (paged extraction),
+`L<n>` (line file), or `complete`. It is **required once any claim cites this artifact**
+and it is advanced at the end of every reading window (`distillation.md` §3): unstated,
+"I am finished" is not falsifiable, which is exactly how a sampled 200-page manual passes
+for an ingested one. Three things are checked: claims with no field (error); a claim
+whose locator addresses **past** the declared coverage, or coverage past the end of the
+stored bytes (error — the sidecar and the rows contradict each other); coverage short of
+the end (warning, because partial work is legal mid-ingestion). Its limit is the mirror
+image of `original_sha256`'s: **nothing proves a page was read**, so a field advanced
+without extracting is caught at the ingestion review, never by the validator. An artifact
+nobody has extracted from yet owes nothing and stays silent.
+
 **Extraction-as-artifact** (`distillation.md` §1 — the variant for a large binary
 corpus): when the extraction IS the artifact and the original was never copied in, two
 more fields record where it came from.