@antoneeo/kb-agentic-skill 1.1.1 → 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,22 +12,25 @@ 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
 
 - **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`, 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.
+- **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

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.1.1",
+  "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.1.1",
+  "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",
@@ -36,6 +36,7 @@
     "skills/kb-agentic-skill/review.md",
     "skills/kb-agentic-skill/dispatch.md",
     "skills/kb-agentic-skill/routing.md",
+    "skills/kb-agentic-skill/portability.md",
     "skills/kb-agentic-skill/ENFORCEMENT.md",
     "skills/kb-agentic-skill/scripts/sdlc_check.py",
     "skills/kb-agentic-skill/scripts/sdlc_core.py",

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

@@ -13,6 +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`.
 - `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.
@@ -21,7 +22,7 @@ Support files in the skill directory:
 - `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
 - `dispatch.md`: opt-in subagent execution of an approved plan.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
-- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -83,8 +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`). | — |
 | `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
@@ -69,7 +83,7 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   `p=<n>@<start>-<end>` (character offsets into page n of the stored extraction),
   `L<a>-<b>` (line files), `Sheet<s>!<cell>`. The span must exist — the validator opens
   the file and checks.
-- **prov** — `GIVEN | ELICITED | DERIVED | RULING`. Information for whoever resolves a
+- **prov** — `GIVEN | ELICITED | DERIVED | RULING | IMPORTED`. `IMPORTED` is a ruling that came from another project (`portability.md`): it keeps its text and original `basis:`, its note must say `imported_from:`, and it may not supersede a local row until you re-ratify it. Information for whoever resolves a
   conflict; never a rank.
 - **state** — `OK`, `CONTESTED <ids>`, `SUPERSEDED <id>` (`reconciliation.md` owns the
   transitions).
@@ -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/portability.md

@@ -0,0 +1,125 @@
+# Portability — carrying knowledge between projects
+
+**For whom**: the agent moving a subgraph out of one project or into another.
+**Answers**: "what travels, what refuses to travel, and what an import may decide".
+**Does not answer**: where a claim's concept belongs (`taxonomy.md` — import *uses* that
+pass, it does not replace it) or how a disagreement is settled (`reconciliation.md`).
+
+## 0. The two commands, and what to tell the user
+
+A bundle is a **folder**, not an archive. Nothing here compresses or unpacks anything:
+the user moves the folder however they already move folders.
+
+**Sending side** — run from the project that owns the knowledge:
+
+```
+sdlc_check.py export --out ../kb-bundle                    # the whole KB
+sdlc_check.py export --out ../kb-bundle --topics pricing,licensing
+```
+
+Write it **outside the docs root**. A bundle sitting inside `ai_docs/` is a second copy
+of topics and corpus files in the tree the validator walks, and that confusion is free
+to avoid.
+
+**Receiving side** — run from the project that is to gain it:
+
+```
+sdlc_check.py import ../kb-bundle --dry-run     # see what would land
+sdlc_check.py import ../kb-bundle
+sdlc_check.py check                             # always, right after
+```
+
+**What to say to the user, in their words.** Say these four things and stop:
+
+1. *"I've written the bundle to `<path>`. It's a folder — move it to the other project
+   however you like."*
+2. *"It carries the source documents too, not just the notes, so it is not small. That is
+   the point: over there the claims can still be traced back to the page they came from."*
+3. After importing: *"Nothing was overwritten. Anything already there stayed as it was"* —
+   and, if a topic was skipped, *"a topic with the same name already exists; I have not
+   merged them, because they may not be the same subject. Do you want me to look?"*
+4. If an imported ruling arrived: *"one decision came from the other project. I have kept
+   it, marked as theirs, and it cannot settle anything here until you confirm it."*
+
+Do not explain the closure, the id hashing or the provenance model unless asked. The
+user asked to move their knowledge, not to learn how it is stored.
+
+## 1. What a bundle is
+
+A directory mirroring the docs-root layout:
+
+```
+<bundle>/
+  MANIFEST.md            kb_bundle: 1, source_project, topics, per-artifact sha256
+  topics/<slug>.md
+  corpus/given/<name>    + <name>.meta.md   (+ the .txt extraction, when there is one)
+  corpus/notes/<name>.md
+```
+
+The layout is mirrored **on purpose**. Claim `source` cells are docs-root-relative, so
+nothing is rewritten on import — and because `kb_claim_id` hashes
+`path#locator#qty` with the text excluded, the same artifact cited at the same span
+mints **the same id in every project**. De-duplication is therefore mechanical, not a
+judgement call, and importing the same bundle twice is a provable no-op.
+
+## 2. Export is a closure, not a selection
+
+You choose topics; the export decides what must travel with them.
+
+- **Every artifact a selected claim cites**, plus its sidecar and its stored extraction.
+  A claim whose source cannot be reopened is model knowledge arriving by another route —
+  the validator would reject it in the target, and correctly.
+- **Every row a `CONTESTED` row points at.** The symmetry check refuses a set that lost
+  half its members, so a partial export ships a tree that cannot pass its own checks.
+  When a partner row lives in an unselected topic, that topic is **added and reported** —
+  never dropped, never silently.
+
+If a conflict partner resolves to no row at all, the export **refuses**: exporting a
+broken set is worse than exporting nothing.
+
+## 3. Import is additive, and decides nothing
+
+`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
+
+- **Never overwrites a topic.** A slug that already exists is reported and skipped: two
+  projects using the word `pricing` may mean two different things, and that judgement is
+  the placement pass's (`taxonomy.md`, five verdicts, `owns:` against double placement).
+- **Never deletes.** The doctrine is tombstones over deletion; an additive import has no
+  business removing anything.
+- **All or nothing.** The whole plan is computed before a byte is written. An import that
+  half-applies leaves a tree whose checks fail and whose owner cannot tell what landed.
+
+It refuses on: a missing or unmarked `MANIFEST.md`; a path that escapes the docs root; an
+artifact whose name matches an existing one **with different bytes** (content-addressed
+names must mean equal content — a mismatch means one of the two is lying about its
+origin); an incomplete conflict set; a dangling `supersedes:`.
+
+After importing, run `check`. The import is deliberately not a validator.
+
+## 4. Knowledge crosses; authority does not
+
+`RULING` means *the fact you know and the corpus does not*, with a `basis:` you gave. It
+is the only thing that settles a `CONTESTED` set. A ruling from another project carries
+another owner's decision, and importing it unchanged would make that decision binding
+here without anyone here granting it — the machine deciding, which reconciliation
+refuses everywhere else.
+
+So an imported ruling arrives as **`prov: IMPORTED`** (owner ruling, 2026-08-03):
+
+- its text, span and original `basis:` travel **verbatim** — the knowledge is not lost,
+  and pretending it is a `DERIVED` synthesis would make the row lie about where it came
+  from;
+- its note carries `imported_from:`, and the validator refuses an `IMPORTED` row without
+  it: unnamed, the class says nothing and the row is a `RULING` with the label filed off;
+- **it cannot supersede a local row.** The validator errors on `SUPERSEDED <id>` when
+  that id is `IMPORTED`.
+
+**Re-ratification** is one act: read it, write your own note with your own `basis:`, and
+set the row's `prov` to `RULING`. That is you deciding, which is the only thing that ever
+settles anything here.
+
+## 5. Triage
+
+Exporting is L1 — it writes nothing into the corpus and changes no knowledge. Importing
+is **L3**: a source enters the corpus and nodes are created, which is the L3 definition
+in Rule Zero, and the bundle is external input, which is never L1 whatever its size.

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

@@ -76,4 +76,19 @@ Whole documents keep the family lifecycle: a superseding note or guide marks the
 `status: SUPERSEDED`; `supersedes:` in the new one's frontmatter links them. Claims and
 documents move independently — superseding a document does not silently resolve the
 claims extracted from it; the `corpus` check reports claims resting on superseded
-originals for re-verification.
+originals for re-verification.
+
+## Rulings that came from another project
+
+An `IMPORTED` row is a ruling made by the owner of a different project
+(`portability.md`). Knowledge crosses a project boundary; authority does not.
+
+- It keeps its text, its span and its original `basis:` verbatim — the knowledge is not
+  lost, and relabelling it `DERIVED` would make the row lie about its origin.
+- Its note must carry `imported_from:`. Unnamed, the class says nothing and the row is a
+  `RULING` with the label filed off; the validator refuses it.
+- **It cannot settle anything here.** `SUPERSEDED <id>` pointing at an `IMPORTED` row is
+  an error: nobody in this project granted that decision its authority.
+
+Re-ratification is one act, and it is you deciding: read it, write your own note with
+your own `basis:`, set `prov` to `RULING`.

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

@@ -62,12 +62,17 @@ sdlc_core.set_profile(
     unit_noun="topic",
     support_files=("templates.md", "taxonomy.md", "guides.md", "vision.md",
                    "distillation.md", "reconciliation.md", "elicitation.md",
-                   "review.md", "dispatch.md", "routing.md", "ENFORCEMENT.md"),
+                   "review.md", "dispatch.md", "routing.md", "portability.md",
+                   "ENFORCEMENT.md"),
     capabilities=(
         # spine
         "triage", "write_triggers", "workstream_registry", "vision_gate",
         "design_review_gate", "guide_router", "worktree_hygiene",
         # knowledge overlay
+        # `knowledge_portability` (F-030) is deliberately NOT declared: the
+        # capability vocabulary lives in the shared spine, and no shared test
+        # guards on portability, so adding a label there would mean editing
+        # sdlc_core.py in three distributions to buy nothing.
         "taxonomy_pass", "subagent_dispatch", "question_discipline",
     ),
     design_gate_between=("### 3. Request Analysis & Taxonomy Pass",
@@ -80,13 +85,15 @@ sdlc_core.set_profile(
 
 CLAIM_COLUMNS = ("id", "claim", "valid", "qty", "about", "source", "prov", "state")
 CLAIM_HEADING = "## Claims"
-PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING")
+PROVENANCES = ("GIVEN", "ELICITED", "DERIVED", "RULING", "IMPORTED")
 SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
 OWNS_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$")
 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
@@ -315,7 +322,7 @@ def kb_check_claims(root):
             prov = row["prov"]
             if prov not in PROVENANCES:
                 errors.append("%s: prov %r not in %s" % (where, prov, "/".join(PROVENANCES)))
-            elif prov in ("DERIVED", "RULING", "ELICITED"):
+            elif prov in ("DERIVED", "RULING", "ELICITED", "IMPORTED"):
                 meta = _note_frontmatter(root, first.rsplit("#", 1)[0])
                 if meta is None:
                     pass  # unresolvable source already reported
@@ -325,6 +332,13 @@ def kb_check_claims(root):
                 elif prov == "RULING" and not meta.get("basis"):
                     errors.append("%s: RULING note carries no 'basis:' — a preference "
                                   "is not a fact; no basis, no ruling" % where)
+                elif prov == "IMPORTED" and not meta.get("imported_from"):
+                    # F-030: IMPORTED exists so a foreign decision cannot pass for
+                    # a local one. Without the origin the class says nothing and
+                    # the row is a RULING with the label filed off.
+                    errors.append("%s: IMPORTED note carries no 'imported_from:' — "
+                                  "the class exists to name whose decision this "
+                                  "was; unnamed, it is a RULING in disguise" % where)
             # --- grammar cells ---
             try:
                 kb_parse_scope(row["valid"])
@@ -384,6 +398,18 @@ def kb_check_claims(root):
                                   "the check, it does not clean up" % (where, kind, t))
                     continue
                 orow, _ = other
+                if kind == "SUPERSEDED" and orow["prov"] == "IMPORTED":
+                    # F-030, owner ruling 2026-08-03: knowledge crosses a project
+                    # boundary, authority does not. An IMPORTED row carries another
+                    # owner's decision; letting it supersede a local row would make
+                    # that decision binding here without anyone here granting it.
+                    # Re-ratify first: write your own ruling note with your own
+                    # basis and flip the row to RULING.
+                    errors.append("%s: SUPERSEDED by %s, which is IMPORTED — a "
+                                  "foreign decision cannot settle a local row. "
+                                  "Re-ratify it (own note, own 'basis:', prov "
+                                  "RULING) or resolve this some other way"
+                                  % (where, t))
                 if kind == "CONTESTED":
                     if orow["state"].startswith("SUPERSEDED"):
                         errors.append("%s: CONTESTED points at SUPERSEDED row %s — "
@@ -640,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"
@@ -652,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("")
@@ -668,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():
@@ -697,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")):
@@ -706,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
 
 
@@ -734,10 +926,179 @@ def kb_sha256_bytes(path):
     return h.hexdigest()
 
 
+# ------------------------------------------------------- portability (F-030)
+# Export a subgraph WITH the bytes its claims cite; import it additively.
+#
+# The bundle mirrors the docs-root layout on purpose: claim `source` cells are
+# docs-root-relative, so nothing is rewritten on import and `kb_claim_id` --
+# sha256(path#locator#qty), text excluded -- mints the SAME id in both projects.
+# That is what makes de-duplication mechanical instead of a judgement call, and
+# it is why this feature is small.
+
+BUNDLE_MANIFEST = "MANIFEST.md"
+
+
+def kb_claim_sources(row):
+    """The docs-root-relative artifact paths a claim row cites (no locators)."""
+    out = []
+    for src in row["source"].split(";"):
+        src = src.strip()
+        if src and "#" in src:
+            out.append(src.rsplit("#", 1)[0])
+        elif src:
+            out.append(src)
+    return out
+
+
+def kb_collect_topics(docs):
+    """{slug: (path, text, rows)} for every topic node that parses."""
+    out = {}
+    tdir = docs / "topics"
+    if not tdir.is_dir():
+        return out
+    for p in sorted(tdir.glob("*.md")):
+        if p.name == "INDEX.md":
+            continue
+        text = sdlc_core.read_text(p)
+        meta = sdlc_core.load_frontmatter(text.splitlines()) or {}
+        rows, _ = kb_parse_claims(text)
+        out[(meta.get("topic") or p.stem).strip()] = (p, text, rows)
+    return out
+
+
+def kb_export_closure(docs, slugs):
+    """(topics, artifacts, added_for_conflicts, errors).
+
+    Closure in two directions, because a partial export produces a target whose
+    own checks fail:
+      * every artifact a selected claim cites travels with it -- a claim whose
+        source cannot be reopened is model knowledge arriving by another route;
+      * every row a CONTESTED row points at travels too, since the symmetry
+        check refuses a set that lost half its members. When such a row lives in
+        an unselected topic, that topic is ADDED and reported, never dropped.
+    """
+    all_topics = kb_collect_topics(docs)
+    errors = []
+    for s in slugs:
+        if s not in all_topics:
+            errors.append("no such topic: %s" % s)
+    if errors:
+        return {}, [], [], errors
+    selected = dict((s, all_topics[s]) for s in slugs)
+    # id -> slug, over the WHOLE graph, so a conflict partner is findable
+    owner_of = {}
+    for slug, (_p, _t, rows) in all_topics.items():
+        for r in rows:
+            if r["id"]:
+                owner_of[r["id"]] = slug
+    added = []
+    pending = list(selected)
+    while pending:
+        slug = pending.pop()
+        for r in selected[slug][2]:
+            m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", r["state"].strip())
+            if not m:
+                continue
+            for ref in [x.strip() for x in m.group(2).split(",") if x.strip()]:
+                other = owner_of.get(ref)
+                if other is None:
+                    errors.append("claim %s in topic '%s' points at id %s, which "
+                                  "no topic owns: export would carry a broken set"
+                                  % (r["id"] or "(no id)", slug, ref))
+                elif other not in selected:
+                    selected[other] = all_topics[other]
+                    added.append(other)
+                    pending.append(other)
+    artifacts = []
+    seen = set()
+    for slug, (_p, _t, rows) in sorted(selected.items()):
+        for r in rows:
+            for rel in kb_claim_sources(r):
+                for cand in (rel, rel + ".meta.md",
+                             rel[:-len(Path(rel).suffix)] + ".txt" if Path(rel).suffix else rel):
+                    if cand in seen:
+                        continue
+                    if (docs / cand).is_file():
+                        seen.add(cand)
+                        artifacts.append(cand)
+    return selected, artifacts, added, errors
+
+
+def kb_bundle_write(docs, out, selected, artifacts, project):
+    """Write the bundle. Mirrors the docs-root layout; no path is rewritten."""
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "topics").mkdir(exist_ok=True)
+    for slug, (p, text, _rows) in sorted(selected.items()):
+        (out / "topics" / p.name).write_text(text, encoding="utf-8")
+    for rel in artifacts:
+        dst = out / rel
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_bytes((docs / rel).read_bytes())
+    lines = ["---", "kb_bundle: 1", "source_project: %s" % project,
+             "topics: [%s]" % ", ".join(sorted(selected)),
+             "artifacts: %d" % len(artifacts), "---",
+             "# KB bundle", "",
+             "Import with `sdlc_check.py import <this directory>`. Additive: it "
+             "never overwrites a node and never deletes anything.", ""]
+    for rel in artifacts:
+        lines.append("- `%s` sha256:%s" % (rel, kb_sha256_bytes(docs / rel)))
+    (out / BUNDLE_MANIFEST).write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def kb_import_plan(bundle, docs):
+    """(writes, skipped_topics, dedup, errors) -- computed BEFORE anything is
+    written, because an import that half-applies leaves a tree whose checks fail
+    and whose owner cannot tell what landed."""
+    errors, writes, skipped, dedup = [], [], [], []
+    man = bundle / BUNDLE_MANIFEST
+    if not man.is_file():
+        return [], [], [], ["not a kb bundle: no %s in %s" % (BUNDLE_MANIFEST, bundle)]
+    meta = sdlc_core.load_frontmatter(sdlc_core.read_text(man).splitlines()) or {}
+    if str(meta.get("kb_bundle", "")).strip() != "1":
+        return [], [], [], ["%s carries no 'kb_bundle: 1'" % BUNDLE_MANIFEST]
+
+    known_ids = set()
+    target = kb_collect_topics(docs)
+    for _slug, (_p, _t, rows) in target.items():
+        for r in rows:
+            if r["id"]:
+                known_ids.add(r["id"])
+
+    for p in sorted(bundle.rglob("*")):
+        if not p.is_file() or p.name == BUNDLE_MANIFEST:
+            continue
+        rel = p.relative_to(bundle).as_posix()
+        dst = sdlc_core.confine_under(docs, rel)
+        if dst is None:
+            errors.append("bundle entry %r escapes the docs root — refusing the "
+                          "whole import, not just this file" % rel)
+            continue
+        if dst.is_file() and not rel.startswith("topics/"):
+            if kb_sha256_bytes(dst) != kb_sha256_bytes(p):
+                errors.append("%s exists with different bytes (target %s… vs "
+                              "bundle %s…): content-addressed names must mean "
+                              "equal content" % (rel, kb_sha256_bytes(dst)[:8],
+                                                 kb_sha256_bytes(p)[:8]))
+            continue
+        if rel.startswith("topics/") and dst.is_file():
+            skipped.append(rel)
+            continue
+        writes.append((rel, p, dst))
+
+    for rel, p, _dst in writes:
+        if not rel.startswith("topics/"):
+            continue
+        rows, _ = kb_parse_claims(sdlc_core.read_text(p))
+        for r in rows:
+            if r["id"] and r["id"] in known_ids:
+                dedup.append(r["id"])
+    return writes, skipped, dedup, errors
+
+
 # ------------------------------------------------------------------ commands
 
 INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
-               "anchor"}
+               "anchor", "export", "import"}
 
 
 def _kb_root(args):
@@ -900,6 +1261,62 @@ def kb_cmd_anchor(args):
     return 0
 
 
+def kb_cmd_export(args):
+    root, docs = _kb_root(args)
+    slugs = ([s.strip() for s in args.topics.split(",") if s.strip()]
+             if args.topics else sorted(kb_collect_topics(docs)))
+    if not slugs:
+        print("[ERROR] no topics to export")
+        return 2
+    selected, artifacts, added, errors = kb_export_closure(docs, slugs)
+    for e in errors:
+        print("[ERROR] %s" % e)
+    if errors:
+        return 1
+    out = Path(args.out)
+    kb_bundle_write(docs, out, selected, artifacts, root.name)
+    print("[ok] bundle written: %s" % out)
+    print("     topics: %d, artifacts: %d" % (len(selected), len(artifacts)))
+    if added:
+        # never silent: a set that grew is a fact about the export, and the
+        # alternative -- dropping the partner rows -- ships a broken tree.
+        print("     +%d topic(s) added to keep conflict sets whole: %s"
+              % (len(added), ", ".join(sorted(added))))
+    return 0
+
+
+def kb_cmd_import(args):
+    _root, docs = _kb_root(args)
+    bundle = Path(args.bundle)
+    if not bundle.is_dir():
+        print("[ERROR] no such bundle directory: %s" % bundle)
+        return 2
+    writes, skipped, dedup, errors = kb_import_plan(bundle, docs)
+    for e in errors:
+        print("[ERROR] %s" % e)
+    if errors:
+        print("[ERROR] nothing was written: an import that half-applies leaves a "
+              "tree whose checks fail and whose owner cannot tell what landed.")
+        return 1
+    if args.dry_run:
+        print("[ok] dry run: %d file(s) would be written" % len(writes))
+    else:
+        for _rel, src, dst in writes:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_bytes(src.read_bytes())
+        print("[ok] imported %d file(s) into %s" % (len(writes), docs))
+    if dedup:
+        print("     %d claim(s) already present, by id — the same artifact cited "
+              "at the same span mints the same id in any project" % len(dedup))
+    for rel in skipped:
+        print("[note] %s already exists: NOT overwritten. Run the placement pass "
+              "(taxonomy.md) and merge by hand — an import never decides that."
+              % rel)
+    print("[note] re-run 'sdlc_check.py check' now: the import is additive, and "
+          "an imported RULING stays IMPORTED until you re-ratify it.")
+    return 0
+
+
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -919,6 +1336,8 @@ knowledge overlay (kb-agentic) -- also available:
   corpus                      corpus integrity: digests, supersession, notes
   claim-id <path> <locator>   compute a claim id (--fill to fill a whole table)
   anchor <path> <phrase>      resolve a phrase to a verified locator span
+  export --out <dir>          bundle a subgraph WITH the bytes its claims cite
+  import <dir>                merge a bundle in additively (never overwrites)
 
   index / validate / check    the spine's behaviour PLUS the claim ledger and
                               the topic graph""")
@@ -962,11 +1381,25 @@ def main(argv=None):
     p.add_argument("--page", type=int)
     p.add_argument("--ignore-case", action="store_true")
     p.add_argument("--all", action="store_true")
+    p = sub.add_parser("export")
+    p.add_argument("--out", required=True)
+    p.add_argument("--topics")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
+    p = sub.add_parser("import")
+    p.add_argument("bundle")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
     args = ap.parse_args(argv)
     if args.cmd == "claim-id":
         return kb_cmd_claim_id(args)
     if args.cmd == "anchor":
         return kb_cmd_anchor(args)
+    if args.cmd == "export":
+        return kb_cmd_export(args)
+    if args.cmd == "import":
+        return kb_cmd_import(args)
     try:
         root, docs = _kb_root(args)
     except sdlc_core.AmbiguousDocsRoot as e:

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.