@antoneeo/kb-agentic-skill 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 Every significant change to this skill is recorded here.
 
+## [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

@@ -12,13 +12,15 @@ Two axes are kept apart on purpose — **abstraction** (a topic made of topics:
 
 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.
+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
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.2.0",
+  "version": "1.3.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.3.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/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.
@@ -84,9 +84,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/templates.md

@@ -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`.
@@ -553,6 +572,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 +581,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.