@antoneeo/kb-agentic-skill 1.0.1 → 1.1.1

package/README.md

@@ -8,9 +8,9 @@ The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@a
 
 Two axes are kept apart on purpose — **abstraction** (a topic made of topics: the graph edges) and **certainty** (how strongly the corpus supports a statement: the claim rows).
 
-1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
+1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction **is** the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as `original_path:` + `original_sha256:`. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limit: they let a human re-verify, they check nothing on their own. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
 
-2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists. 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.
+2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists — and `anchor <path> <phrase>` produces it for you, matching spaces as `\s+` because a PDF extraction breaks phrases mid-line. **Gates are extracted alongside powers**: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is *ask*, never *produce*: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies **refuse to sum**. What the source does not assert becomes a `gaps:` line, never a claim.
 
 3. **Placement — five verdicts, after querying the graph.** Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; **MISSING only after the graph was actually asked**; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling **with the distinguishing line written** — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with `redirect_to:`, never a deletion.
 
@@ -22,12 +22,12 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
 
 ## Key features
 
-- **Risk-proportional triage**: L1/L2/L3/Spike (note → SOP → corpus), so a quick fact never pays for heavyweight process, with a **Write Triggers** table mapping each knowledge event to exactly one destination.
+- **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.
 - **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`, 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`, 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.0.1",
+  "version": "1.1.1",
   "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.0.1",
+  "version": "1.1.1",
   "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

@@ -21,7 +21,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`). 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`). 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.
@@ -43,12 +43,19 @@ Always classify the request before choosing the process. Declare the chosen leve
 
 | Level | Criteria | Required process |
 |---|---|---|
-| **L1 - Quick Fact / Snippet** | Small update to an existing note, typo fix in docs, quick preference update (at most 1-2 files). | Implement edit directly in existing note. No new documents. |
-| **L2 - Local Note / SOP Update** | Specific SOP update, local research note, or small document addition (at most 1-2 files). Low risk. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
-| **L3 - Major Knowledge Unit / Corpus** | Ingesting large document sets, complex multi-topic research, multi-part guide creation, or restructuring the KB. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
+| **L1 - Quick Fact / Snippet** | One claim row added to an existing topic; a typo; a preference update. No node created, no source entering the corpus, no frontmatter change. | Implement edit directly in existing note. No new documents. |
+| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
+| **L3 - New knowledge unit / Corpus** | A source enters the corpus; a topic node is created or superseded; the hierarchy moves; a conflict must be reconciled; or what a claim asserts changes. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
 | **Spike - Exploration** | Time-boxed exploratory research or draft without merging into official KB. | Outcome in `ai_docs/solutions/SPIKE_[topic].md`. |
 
 Cross-cutting rules:
+- **The unit of measure here is knowledge, never file count.** In this domain risk is
+  knowledge-shaped: carrying one settled fact into eight documents is small, and one
+  claim that re-parents a node is not. Do not import the code lens's file thresholds —
+  a level is chosen by what the change does to the corpus and the graph. What keeps
+  this from becoming an escape hatch is the trigger list below, which overrides the
+  level whatever the size, plus one limit: **propagation that changes what a claim
+  asserts is not propagation** — it is a new knowledge unit, so L3.
 - **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `mkt-agentic-sdlc`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
 - Personal data, credentials, security-sensitive processes, authN/authZ specs are high-risk: never L1.
 - **Escalation triggers — ANY of these makes it L3, whatever the file count:** the change touches the topic hierarchy (`parents:`, a `GENERALIZES` verdict, a re-parent); it touches more than one node's frontmatter; it creates or supersedes a node other nodes reference. Re-shaping the graph is a unit of change, never a side effect of placing one claim.
@@ -76,7 +83,7 @@ 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 |
-| `corpus/given/*` + sidecar | A source arrives: verbatim copy, content-addressed, sidecar with digest/date/`supersedes:`; non-text originals also get their stored canonical extraction (`distillation.md` §1). Never edited after ingest — the digest check is what enforces it. | 4 |
+| `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 |
 | `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 |
 

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

@@ -14,14 +14,32 @@ from the corpus, so everything is re-derivable when the rules improve.
 | What arrives | Where it lands |
 |---|---|
 | a file from the practitioner | `corpus/given/<name>-<hash8>.<ext>` — verbatim, **content-addressed with a raw-byte sha256**; a newer version is a new file whose sidecar says `supersedes: <old>` — never an overwrite |
-| a non-text original (PDF, docx, xlsx) | additionally, its **canonical extraction**: `corpus/given/<name>-<hash8>.txt`, pages separated by form-feed; extractor id, version and normalization recorded in the sidecar. Offsets address THIS file — stored bytes, not a runtime step |
+| a non-text original (PDF, docx, xlsx) | its **canonical extraction**: `corpus/given/<name>-<hash8>.txt`, pages separated by form-feed; extractor id, version and normalization recorded in the sidecar. Offsets address THIS file — stored bytes, not a runtime step. The original is copied beside it when it is small enough to be worth keeping; **on a large or binary-heavy corpus the extraction is the artifact and the original stays where it is** (below) |
 | something the practitioner says | a transcription in `corpus/notes/`, frontmatter `origin: elicited`, dated |
 | 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 (`<original>.meta.md`) carries: the digest, the date, provenance, and
+Every sidecar (`<artifact>.meta.md`) carries: the digest, the date, provenance, and
 `supersedes:` when it replaces an earlier version. `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
+locator addresses*, and those are the extraction's. So the extraction may be the
+corpus artifact on its own. Then `sha256:` is the extraction's digest — immutability is
+enforced exactly as before — and the original is recorded, not copied:
+
+```yaml
+sha256: <digest of this extraction>      # enforced: the bytes locators address
+original_path: /vault/manuals/xyz.pdf    # recorded: where the original lives
+original_sha256: <digest at ingest>      # recorded, NOT verified — we do not hold it
+```
+
+Say the limit out loud, because a field that looks like a guarantee and is not is worse
+than an absent one: **`original_sha256` is never checked.** It lets a human re-verify by
+hand and it dates the ingest; it detects nothing on its own. The digest that bites is
+`sha256:`. Same honesty as a guide's `source_hash`, which proves the source is unchanged
+and never that the guide described it correctly.
+
 ## 2. The claim — one falsifiable assertion
 
 The unit of knowledge is the **claim**, not the document. "Doc A and doc B disagree" is
@@ -63,6 +81,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.
 
+**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
+saying what the subject **can do**, ask the source what must hold first — a documented
+default-off state, a licence or edition gate, a firmware or version floor, something
+that must be enabled elsewhere, a dependency on another construct. Each one the source
+states is **its own row, with its own span**.
+
+The failure this prevents is an answer that is true and unusable: *"yes, supported —
+three verified rows"* is a plan that fails on site when the function ships disabled. On
+a corpus whose purpose is to deflate over-promising, an extraction axis that records
+powers and skips gates inverts the point.
+
+**The rule is _ask_, never _produce_.** A source stating no precondition yields no
+precondition row — the paragraph above still governs. An invented gate is the same
+defect as an invented capability, and a gate you suspect but cannot locate is a `gaps:`
+entry, not a claim. Nothing mechanical can enforce this (no validator detects an
+assertion that was never extracted), which is why it carries no column and no check:
+it is verified at the ingestion review (`review.md`), and it is stated here so the
+extractor knows it before the reviewer does.
+
+**Anchor across line wraps.** A PDF extraction breaks phrases mid-line, so a multi-word
+anchor must match a literal space as `\s+` or it silently finds nothing — and a probe
+that pretty-prints collapsed whitespace will show you the phrase intact while the
+checker sees the break. `sdlc_check.py anchor` does this for you; hand-authoring a
+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

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

@@ -435,6 +435,65 @@ def kb_check_locator(target, loc, where, errors):
                       "(p=<n>@<a>-<b> / L<a>-<b> / Sheet<s>!<cell>)" % (where, loc))
 
 
+def kb_anchor_pattern(phrase, ignore_case=False):
+    """A phrase, compiled so it survives the line wraps an extraction introduces.
+
+    Every run of whitespace in the phrase becomes `\\s+`: a PDF extraction breaks
+    phrases mid-line, so a literal space matches nothing while a probe that
+    pretty-prints collapsed whitespace shows the phrase intact. That gap cost a
+    field user two full generation rounds."""
+    tokens = [t for t in re.split(r"\s+", phrase.strip()) if t]
+    if not tokens:
+        return None
+    body = r"\s+".join(re.escape(t) for t in tokens)
+    return re.compile(body, re.IGNORECASE if ignore_case else 0)
+
+
+def kb_resolve_anchor(target, phrase, ignore_case=False, page=None):
+    """Locate a phrase in stored bytes and return [(locator, context), ...].
+
+    The stored form decides the locator form: form-feeds mean paged bytes and
+    offsets are counted inside the page, exactly as `kb_check_locator` reads
+    them; otherwise line numbers. Every locator produced here is re-verified with
+    that same checker before it is returned, so this can never emit a span its
+    own validator would reject."""
+    rx = kb_anchor_pattern(phrase, ignore_case)
+    if rx is None:
+        return []
+    # Read what the checker will read: for a non-text original the stored
+    # extraction beside it holds the bytes offsets address. `target` stays as
+    # given, because that is the path the claim's `source` cell will carry and
+    # therefore the path the round-trip below must verify.
+    ext = target if target.suffix == ".txt" else target.with_suffix(".txt")
+    text = sdlc_core.read_text(ext if ext.is_file() else target)
+    hits = []
+    if "\f" in text:
+        for idx, body in enumerate(text.split("\f"), start=1):
+            if page is not None and idx != page:
+                continue
+            for m in rx.finditer(body):
+                hits.append(("p=%d@%d-%d" % (idx, m.start(), m.end()),
+                             body[max(0, m.start() - 40):m.end() + 40]))
+    else:
+        lines = text.splitlines()
+        starts, pos = [], 0
+        for ln in lines:
+            starts.append(pos)
+            pos += len(ln) + 1
+        for m in rx.finditer(text):
+            a = sum(1 for s in starts if s <= m.start())
+            b = sum(1 for s in starts if s <= m.end() - 1)
+            hits.append(("L%d-%d" % (a, b),
+                         text[max(0, m.start() - 40):m.end() + 40]))
+    verified = []
+    for loc, ctx in hits:
+        errs = []
+        kb_check_locator(target, loc, "anchor", errs)
+        if not errs:
+            verified.append((loc, ctx))
+    return verified
+
+
 # ---------------------------------------------------------------- topic graph
 # F-024. Findings only; the graph is held in memory, rebuilt per run.
 
@@ -677,7 +736,8 @@ def kb_sha256_bytes(path):
 
 # ------------------------------------------------------------------ commands
 
-INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id"}
+INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
+               "anchor"}
 
 
 def _kb_root(args):
@@ -798,8 +858,80 @@ def kb_cmd_claim_id(args):
     return 0
 
 
+def kb_cmd_anchor(args):
+    """Prose citation -> a verified span. The half `claim-id` never had.
+
+    The path may be given as it appears in a claim's `source` cell
+    (`corpus/given/x-ab12cd34.txt`): when it does not resolve from the current
+    directory it is retried under the docs root, so the command works from
+    anywhere in the project instead of only from inside `ai_docs/`. Reported
+    from the field as an asymmetry with `graph`/`corpus`/`check`, which take
+    `--root`; those scan a tree, this one takes a path, and the fix is to make
+    the path resolve rather than to document where to stand."""
+    p = Path(args.path)
+    if not p.is_file():
+        try:
+            _, docs = _kb_root(args)
+            if (docs / args.path).is_file():
+                p = docs / args.path
+        except sdlc_core.AmbiguousDocsRoot:
+            pass
+    if not p.is_file():
+        print("[ERROR] no such file: %s" % args.path)
+        print("        looked from the current directory and under the docs "
+              "root; give the path as the claim's `source` cell carries it.")
+        return 2
+    hits = kb_resolve_anchor(p, args.phrase, ignore_case=args.ignore_case,
+                             page=args.page)
+    if not hits:
+        print("[ERROR] phrase not found in the stored bytes of %s" % p)
+        print("        nothing written: a locator you cannot verify is worse "
+              "than no locator.")
+        return 2
+    if len(hits) > 1 and not args.all:
+        print("[ERROR] %d matches -- ambiguous, so nothing is emitted. Narrow "
+              "the phrase, add --page, or pass --all to see them:" % len(hits))
+        for loc, ctx in hits:
+            print("        %s" % loc)
+        return 2
+    for loc, ctx in hits:
+        print(loc)
+        print("    ...%s..." % " ".join(ctx.split()))
+    return 0
+
+
+def kb_cmd_help():
+    """The spine's usage, then the overlay's own commands.
+
+    Forward-by-default sends everything the overlay does not intercept to the
+    spine -- including `--help`, whose usage line then lists the spine's nine
+    commands and nothing else. A reader concludes the knowledge overlay is not
+    installed; it is, and every command below works. Only `-h/--help` AT argv[0]
+    lands here, so dispatch is otherwise untouched and a future spine command
+    still reaches the spine."""
+    try:
+        sdlc_core.main(["--help"])
+    except SystemExit:
+        pass
+    print("""
+knowledge overlay (kb-agentic) -- also available:
+  graph                       topic-graph integrity: placement, edges, cycles
+  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
+
+  index / validate / check    the spine's behaviour PLUS the claim ledger and
+                              the topic graph""")
+    return 0
+
+
 def main(argv=None):
     argv = list(sys.argv[1:] if argv is None else argv)
+    # `--help` is the one flag the overlay must answer for itself: forwarded, it
+    # renders the spine's usage and hides every command above (field report,
+    # 2026-08-02). Intercepted at argv[0] ONLY.
+    if argv and argv[0] in ("-h", "--help"):
+        return kb_cmd_help()
     # Forward-by-default: anything not intercepted goes to the spine untouched.
     # Never a hand-copied command tuple - that is how a spine command gets
     # silently dropped (mkt_check.py ships that exact defect with `migrate`).
@@ -822,9 +954,19 @@ def main(argv=None):
     p.add_argument("locator", nargs="?")
     p.add_argument("--qty")
     p.add_argument("--fill", action="store_true")
+    p = sub.add_parser("anchor")
+    p.add_argument("path")
+    p.add_argument("phrase")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
+    p.add_argument("--page", type=int)
+    p.add_argument("--ignore-case", action="store_true")
+    p.add_argument("--all", action="store_true")
     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)
     try:
         root, docs = _kb_root(args)
     except sdlc_core.AmbiguousDocsRoot as e:

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

@@ -253,10 +253,10 @@ end_date:
      what makes a verdict falsifiable. A question, not a form: when every concept
      plainly has its owner, one line under this heading answers it. -->
 
-| Capability | Verdict | Component / gap | Evidence |
+| Capability | Verdict | Owning node / gap | Evidence |
 |---|---|---|---|
-| persist an order | EXISTS | `path/to/store.py#OrderStore` | re-read `save()`: durable, returns the id |
-| notify the customer | MISSING | — | grep notify/alert/dispatch + send, over src/ and legacy/; no owner |
+| scoping authorizations per company | EXISTS | `topics/multi-company.md`, `owns: [multi-company/scoping]` | descended the index from `access-control`; re-read `owns:` — the concept is claimed there, not in `topics/operators.md` |
+| the licence tiers that gate it | MISSING | — | descended `pricing`, `licensing`, `editions`; synonyms tried: edition, tier, SKU. No node owns it and no source asserts it → a `gaps:` entry, not a claim |
 
 ## Impact
 <!-- existing files touched, APIs/contracts, performance, new dependencies.
@@ -548,7 +548,7 @@ status: CURRENT
 
 ```markdown
 ---
-sha256: <raw-byte digest of the original — NOT the LF-normalized text digest>
+sha256: <raw-byte digest of the artifact this sidecar names — NOT the LF-normalized text digest>
 date: 2026-08-01
 provenance: GIVEN
 supersedes: contract-1a2b3c4d.pdf
@@ -561,6 +561,24 @@ 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.
 
+**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.
+
+```markdown
+---
+sha256: <digest of THIS extraction — enforced, these are the bytes locators address>
+date: 2026-08-02
+provenance: GIVEN
+extractor: pdftotext 24.02, form-feed page breaks, whitespace collapsed
+original_path: /vault/manuals/xyz.pdf
+original_sha256: <digest at ingest — RECORDED, never checked: we do not hold the file>
+---
+```
+
+Keep `original_sha256`'s limit visible wherever it is written: it lets a human
+re-verify by hand and it dates the ingest, and it detects nothing on its own.
+
 ## ai_docs/corpus/notes/RULING_[topic]_[date].md (practitioner ruling)
 
 ```markdown