@antoneeo/kb-agentic-skill 1.28.0 → 1.32.0

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

@@ -35,7 +35,10 @@ a fidelity marker: `[source: <snapshot-file>#<anchor-or-line>]` for covered cont
 (doubling as the detail-lookup pointer into the book), or a literal
 `[not covered by source]` for gaps. Sections are CHOSEN from the repertoire below —
 only those the source actually supports; never force empty ones. A guide approaching
-the source's own length is a paraphrase, not a synthesis.
+the source's own length is a paraphrase, not a synthesis. **With a corpus**, a
+`source_kind: document` guide's book is its `corpus/given/` artifact instead of a
+snapshot: `distilled_from:` and the markers name it, and `source_hash` is its
+line-ending-normalized digest (`distillation.md` §1).
 
 ```markdown
 ---
@@ -746,7 +749,7 @@ status: CURRENT
   belong to reconciliation.
 - `qty`: `<value> <unit> <kind>` — effort in person-days (h/d/w/mo/fte-mo; 8h=1d, 1w=5d,
   1mo=21d), duration in calendar days (h/d/w/mo), cost within one currency, count unit-matched.
-- `about`: `<predicate> -> <slug>` for relationship claims; stored once, under the subject.
+- `about`: `<predicate> -> <slug>` for relationship claims; stored once, under the subject. Several share one cell, separated by `; `; `not-yet-honored-by -> ANALYSIS_<name>` (Hybrid: `SHADOW_<doc_key>`) marks a claim the code does not yet honor (`distillation.md` §2).
 - `state`: `OK` | `CONTESTED <id>[,..]` | `SUPERSEDED <id>[,..]` — per claim, never per
   node; a split bundle (`reconciliation.md` §Splitting) names all its successors.
 - A tombstone (merged/renamed topic): `status: SUPERSEDED` + `redirect_to: <slug>`, body empty.
@@ -794,16 +797,18 @@ 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>
+original_sha256: <digest at ingest — checked by stale/inventory only when original_path is local>
 ---
 ```
 
 The two fields are **not** in the same position, and writing them as if they were is
 how a dangling pointer survives a green run:
 
-- `original_sha256` detects nothing on its own — we do not hold the bytes. It lets a
-  human re-verify by hand and it dates the ingest. Keep that limit visible wherever the
-  field is written.
+- `original_sha256` is checked only where `original_path:` resolves to a local file:
+  `stale` and `inventory` report an original that changed since ingest. `check` never
+  hashes originals; elsewhere (remote, cloud-only, no path) it detects nothing. It
+  lets a human re-verify by hand and it dates the ingest. Keep that limit visible
+  wherever the field is written.
 - `original_path` **is** checked for resolution, and warns when it does not resolve
   (never errors — an imported bundle carries no originals). **Write it absolute, or
   relative to the project root**; the validator tries the docs root's parent first and
@@ -814,6 +819,43 @@ how a dangling pointer survives a green run:
 Write these two values with **no trailing `# comment`**: the frontmatter reader does
 not strip inline comments, so the comment lands inside the value.
 
+**Intake hygiene fields** (`distillation.md` §1 owns the rules):
+
+```markdown
+redacted_at_intake: [password, personal-data]
+credential_scan: reviewed — vendor manual's sample value, not a live credential
+original_ref: wiki://team-space/app-config
+```
+
+- `redacted_at_intake:` — the kinds replaced by `[REDACTED: <kind>]` before storing.
+  When present, the sidecar carries **no `original_sha256:`** and no non-text original
+  is copied beside the extraction.
+- `credential_scan: reviewed — <reason>` — a human cleared a flagged line as a false
+  positive. Only this clears the check; a reason is required.
+- `original_ref:` — a non-local identifier of the original; recorded, never resolved.
+
+**A document the project sent** (`distillation.md` §1) — its claims are `DECLARED`:
+
+```markdown
+---
+sha256: <digest of the version sent>
+date: 2026-10-16
+provenance: DECLARED
+recipient: <organization or role — never a private person's name>
+original_path: deliverables/dpia_v5.1.docx
+supersedes: dpia-v5-0a1b2c3d.txt
+---
+Sent to <recipient> with <the package it belonged to>, in one line.
+```
+
+`date:` here is the day it was **sent** (the docs site's chronology says so).
+`original_path:` names the file in the project, so `inventory` recognizes it even when
+redaction left no digest of it. `supersedes:` only for a resend.
+
+A **tombstone** (a withdrawn artifact) is renamed `<stem>-withdrawn-<YYYYMMDD>.<ext>.meta.md`
+and keeps `date:`, `provenance:`, `supersedes:` and `withdrawn: <reason>` — and **no
+`sha256:` or `original_sha256:`**. Its bytes are gone.
+
 `provenance:` has a consumer too: a claim row filed `prov: GIVEN` whose artifact's
 sidecar declares anything else warns. Declare the chain the artifact actually has —
 an OCR, a transcription from an image, a translation are not first-hand evidence, and
@@ -827,6 +869,28 @@ warning catches the author who declared the chain honestly and then filed the ro
 strongly, never the author who declared it wrongly. Nothing requires a `given/` sidecar
 to carry `provenance:` at all; adding that requirement is a new gate, not this one.
 
+## ai_docs/audit/INVENTORY_exclusions.md (what never enters the corpus)
+
+```markdown
+# Inventory exclusions
+
+Project files the practitioner decided never enter the corpus. One row per approval,
+written only after it, dated that day. `inventory` never reads what a row excludes.
+
+| pattern | reason | approved |
+|---|---|---|
+| src/ | application code: knowledge lives in the guides | 2026-10-26 (REQUEST_kb_corpus_reach.md R2) |
+| *.pyc | generated | 2026-10-26 |
+```
+
+Patterns are a gitignore subset, relative to the project root: `*`, `?`, `[...]` within
+a segment, `**` across segments, a trailing `/` for directories, no `/` (other than a
+trailing one) to match a name at any depth; case-insensitive on Windows. `validate` and
+`check` refuse an empty pattern or reason, an `approved` that is not a date, and a
+pattern that leaves the project root. The validator's built-in skipped directories
+(`.git`, `node_modules`, dot-directories, …) need no row: `inventory` lists each once
+as `SKIPPED`.
+
 ## ai_docs/corpus/notes/RULING_[topic]_[date].md (practitioner ruling)
 
 ```markdown