@antoneeo/kb-agentic-skill 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -2,14 +2,42 @@
 
 Every significant change to this skill is recorded here.
 
-## [1.18.0] - 2026-09-19
-
-### Added
-- F-057: shared project memory in every lens, no sibling installation required.
-  `index` catalogs original documents; `recall QUERY` searches live metadata.
-  KB integrity is shared; domain ownership and marketing numerical checks remain.
-  Vendored validators now require entry point + sdlc_core.py + knowledge.py.
-
+## [1.20.0] - 2026-10-02
+
+### Changed
+- F-058: route course creation to `course-creator`, keep course artifacts discoverable in shared memory, and guard the fourth shared core copy.
+
+## [1.19.0] - 2026-09-25
+
+### Changed
+- **F-026 revised: a real doubt is asked when it emerges.** The question discipline
+  no longer sends doubts to the deliverable ("Default non-blocking" is gone). A real
+  doubt (a fact the search leaves open, or a choice whose pros and cons do not
+  settle it) is asked before the first write that would embed its answer, grouped,
+  with the pros and cons of each option. A choice that clearly wins the weighing is
+  taken without asking, and the weighing is written next to it — each rejected option
+  stated at its strongest; options that serve different needs, none good enough at
+  both, that nothing the user wrote ranks are a real doubt, however clear the
+  agent's own ranking. Reserved approvals
+  are always asked. A real doubt becomes a declared assumption only in unattended
+  or delegated work. `review.md` makes an unasked doubt a design-review finding; `dispatch.md`
+  tells a subagent to return its real doubts instead of deciding them.
+
+### Fixed
+- **`stale` no longer counts the audit plan against the area that holds it.**
+  Committing a hash mark of `ai_docs/` changed `ai_docs/audit/audit_plan.md` after
+  the recorded commit, so the area went stale again and every re-mark repeated the
+  loop. The plan's own edits are now excluded; any other change in the area still
+  counts.
+
+## [1.18.0] - 2026-09-19
+
+### Added
+- F-057: shared project memory in every lens, no sibling installation required.
+  `index` catalogs original documents; `recall QUERY` searches live metadata.
+  KB integrity is shared; domain ownership and marketing numerical checks remain.
+  Vendored validators now require entry point + sdlc_core.py + knowledge.py.
+
 
 ### Fixed
 - **F-056: `stale` no longer reports an area fresh when it cannot evaluate it.** An

package/README.md

@@ -1,176 +1,177 @@
-# KB Agentic Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
-
-## Shared project memory
-
-All three lenses include project memory by default; install the lens you need,
-not a second skill just for recall. `index` registers guides, decisions and plans
-in the docs root's `memory/INDEX.md`, linking originals without copying them.
-`recall "onboarding"` finds related metadata across domains; optional
-`topics: [onboarding]` links documents by subject. Read the originals for authority,
-status and evidence: discovery is not approval or proof of implementation.
-
-Registration happens at `index`/documentation closure, not through a background
-watcher. Existing projects acquire the catalog on their next `index`; `recall`
-also sees live metadata. The KB lens remains the specialist for ingestion and
-taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
-Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
-
-
-`kb-agentic` turns an AI agent into the keeper of a second brain built **on the documents you supply** — not on what the model remembers. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
-
-The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill), transplanted from source code to knowledge: same process, one different fidelity discipline.
-
-## What it does
-
-Two axes are kept apart on purpose — **abstraction** (a topic made of topics: the graph edges) and **certainty** (how strongly the corpus supports a statement: the claim rows).
-
-1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction **is** the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as `original_path:` + `original_sha256:`. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limits, which differ: `original_sha256` checks nothing on its own (we do not hold the bytes), while `original_path` is verified to still resolve, and warns when it does not — a folder you reorganised should not leave sixteen sidecars pointing at nothing behind a green run. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
-
-2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists — and `anchor <path> <phrase>` produces it for you, matching spaces as `\s+` because a PDF extraction breaks phrases mid-line. **Gates are extracted alongside powers**: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is *ask*, never *produce*: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies **refuse to sum**. What the source does not assert becomes a `gaps:` line, never a claim.
-
-   **The source is exhausted, not sampled.** "Invents nothing" is a floor, and an extractor that stops when nothing it wrote is false stops on page twenty of a two-hundred-page manual with every row correct — which is exactly what a 200-page manual produces in the field. So a long source is read in **bounded windows** (30 pages by default, one plan task each, the ledger holding your place across sessions), and every window closes by advancing `extracted_through:` on the artifact's sidecar. That field is what makes "I am finished" falsifiable: claims with no coverage recorded are an error, a claim addressing a page past the declared coverage is a contradiction, and coverage short of the end is reported until it reaches it. Its limit is stated where it is written — **nothing proves a page was read**; what changes is that the shortcut must now be written down to pass. And exhaustive means read, never *a row per page*: a page that asserts nothing yields nothing.
-
-3. **Placement — five verdicts, after querying the graph.** Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; **MISSING only after the graph was actually asked**; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling **with the distinguishing line written** — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with `redirect_to:`, never a deletion.
-
-4. **Reconciliation — the machine detects and holds, it never decides.** Five outcomes: new / confirmation (the source is appended to the row — the base strengthens, it does not lengthen) / refinement (the old row goes `SUPERSEDED`, its text intact) / coexistence (disjoint scopes) / conflict → the whole set goes `CONTESTED`, **symmetrically**: flipping one cell by hand fails the check. Only new information resolves it — a later source, or **your ruling with a `basis:`**, the fact you know and the corpus does not. No basis, no ruling: a preference is not a fact. A ruling is challengeable — a later document reopens the case with your basis beside it.
-
-5. **Escalation in one batch at the end of the run**, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.
-
-6. **Recall — the graph is read when answering, not only written when distilling.** Whenever a reply would assert facts about the project's domain, the agent scans the topic index and descends before answering from model memory — plausibility of coverage is judged ON the scanned index, never before it. Answers cite claim ids; a superseded claim is never cited without its successor; the verdict is declared only when the recall ran (`kb: <slug> → N claims cited`, a matched node with no claims surfaces its `gaps:`, and a missing index is reported as index-absent — not as a missing graph — with the regenerate command). When a DERIVED claim grounds a decision, its chain is walked to non-DERIVED ground (the given artifact or the elicited/ruled note) and that ground is cited — re-reading the agent's own synthesis is the echo chamber this rule exists to break. By construction, not exhortation: the kb `orient` opens every session with the topic router in sight.
-
-7. **Capture — the day's decisions reach the ledger before they evaporate.** At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb `orient` shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.
-
-8. **Revision — documents read as current state.** Incorporating new knowledge into an existing document is a full re-read and a body rewrite, not a stack of dated deltas: anchored edits are each correct while the document as a whole rots. The doctrine keeps history in the Diary (past entries never rewritten), leaves claim tables to reconciliation and graph edges to the taxonomy, and runs per document even in a multi-document pass. Born from a real field post-mortem: twelve documents realigned by append, every untouched sentence left standing as printed truth.
-
-Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
-
-## Key features
-
-- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
-- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
-- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
-- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
-- **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
-- **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
-- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
-- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- superseded-cited documents, expired `valid` windows, superseded derivation chains), plus the spine's `mark`/`benefit`/`gate`/`plan`/`orient`/`migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read; it always exits 0 and carries no verdict. 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`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` (copy all three) — plus the `LICENSE` and `NOTICE` it ships under.
-
-## Installation
-
-```bash
-npm install -g @antoneeo/kb-agentic-skill@latest
-```
-
-That is enough — the package's `postinstall` runs the installer. If your npm blocks
-install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
-
-```bash
-kb-agentic-install-skill
-```
-
-> The command is on your PATH only after a **global** (`-g`) install; after a local
-> `npm i`, invoke it as `npx kb-agentic-install-skill`.
-
-The installer copies `skills/kb-agentic-skill/` recursively into native skill locations:
-
-- Claude Code: `~/.claude/skills/kb-agentic/`
-- Codex: `~/.codex/skills/kb-agentic/`
-- Gemini CLI: `~/.gemini/skills/kb-agentic/`
-- Google Antigravity: `~/.gemini/config/skills/kb-agentic/` (override the home with `ANTIGRAVITY_HOME`)
-
-Restart the relevant agent, or reload skills where the CLI supports it.
-
-Initialize a project:
-
-```bash
-kb-agentic-init
-```
-
-Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
-
-Installing or updating the npm package **wires the session-orientation hook
-machine-wide** (user-level `~/.claude/settings.json`, Claude Code with Python):
-every project with a docs root greets its agent already oriented, and removing
-the entry is a standing opt-out that no update ever overrides. `init` still
-wires per-project where that is the better shape (a vendored validator, a
-shared team file), so an agent opening
-the project is handed the reading guide, the generated manifest, the guide router and the
-last handoff before it does anything — instead of only when it remembers to look. That
-wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
-skipped, and a project could run fully governed with an agent that never met the process.
-
-The hook command names a validator, so where that validator lives decides which file gets
-it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
-(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
-`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
-duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
-with the correction rather than counted as installed. `check` prints a one-line
-note when a machine has no orientation hook at project or user level (or a dead
-one), and an opt-in per-turn reminder exists for long sessions: `sdlc_check.py
-remind`, one constant line via UserPromptSubmit -- documented in `ENFORCEMENT.md`
-par.4, never wired by default.
-
-## The family: three lenses, one spine
-
-| Package | Faithful to | Unit of work |
-|---|---|---|
-| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature |
-| `@antoneeo/kb-agentic-skill` (this one) | the documents you supply | topic |
-| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement |
-
-The three lenses ship the common validator core and knowledge-integrity engine. When two live in the same project, `routing.md` decides which lens owns a given piece of work. Each entry point composes its structural checks: marketing uses its own document validation and numerical checks; code/KB do not certify marketing arithmetic.
-
-## Standalone vs Hybrid
-
-- **Standalone** — `ai_docs/` is the source of truth: vision, topics, corpus, audit, handoff.
-- **Hybrid with devPNT** — devPNT governs `M-VISION`, Master Plan, Action Plan and versioned artifacts; `ai_docs/` stays as readable context, fallback and shadow. Divergence between your request, the local Vision and the M-VISION is surfaced before any work.
-
-## Created By
-
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
-
-## License
-
-Apache-2.0 — the full terms are in the `LICENSE` file, the attribution in `NOTICE`. Copyright 2026 Antonio Pinto.
-
-If you redistribute this skill, or a version you modified, keep `LICENSE` and `NOTICE` with it.
-
-Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.
-
-Versions up to 1.16.0 were released under the MIT license and remain available under it.
-
-If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:
-
-```markdown
-[![Made with kb-agentic](https://img.shields.io/badge/made%20with-kb--agentic-blue)](https://www.npmjs.com/package/@antoneeo/kb-agentic-skill)
-```
-
-## Which model to run it on
-
-The skill names **capability tiers**, never providers — a model name in doctrine
-rots at the next release. The binding is yours to make, and the rule is one line:
-
-> **A session's floor is the highest floor among the roles it performs itself.**
-
-Authoring a governed artifact — the vision, the analysis, the use cases, the
-threat model — is a **deep-tier** role: its output is judgement, and nothing
-downstream scores it. So a session that will DESIGN wants your strongest model.
-A session that only executes an already-approved plan, or does small maintenance,
-can sit a tier lower. The cheapest tier is the wrong choice for the main session
-whatever the task, because the failure there is not a wrong answer — it is
-**silently not applying the process**: a triage never run, a router verdict
-declared without the lookup, a gate nobody noticed. That failure is invisible to
-every check in here.
-
-**The reviewer's tier is not automatically yours.** On some clients a subagent
-inherits the session's model; on others it takes one from its own definition, so
-a strong session can be reviewed by a weak one — and a weak session can buy a
-strong review. Set it deliberately; the
-`model` column in the review log is where the choice becomes visible.
-
-**Avoid one combination**: authoring below the floor AND reviewing below the floor
-on the same unit. One disclosed weakness is a disclosed weakness; two is an
-artifact nobody competent ever read. Where your client offers nothing better, the
-review still runs and both facts are recorded — a disclosed worst case beats
-skipping the review.
+# KB Agentic Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
+
+## Shared project memory
+
+All four lenses include project memory by default; install the lens you need,
+not a second skill just for recall. `index` registers guides, decisions and plans
+in the docs root's `memory/INDEX.md`, linking originals without copying them.
+`recall "onboarding"` finds related metadata across domains; optional
+`topics: [onboarding]` links documents by subject. Read the originals for authority,
+status and evidence: discovery is not approval or proof of implementation.
+
+Registration happens at `index`/documentation closure, not through a background
+watcher. Existing projects acquire the catalog on their next `index`; `recall`
+also sees live metadata. The KB lens remains the specialist for ingestion and
+taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
+Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
+
+
+`kb-agentic` turns an AI agent into the keeper of a second brain built **on the documents you supply** — not on what the model remembers. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+
+The sibling of [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill), transplanted from source code to knowledge: same process, one different fidelity discipline.
+
+## What it does
+
+Two axes are kept apart on purpose — **abstraction** (a topic made of topics: the graph edges) and **certainty** (how strongly the corpus supports a statement: the claim rows).
+
+1. **Intake — the source becomes untouchable.** Every document enters verbatim under `corpus/given/`, content-addressed by a raw-byte digest. A new version is appended with `supersedes:`, never overwritten. Non-text files get a **stored canonical extraction** (`.txt`, registered extractor) — those are the bytes locators point at, so an id stays valid across re-ingestion. On a large binary corpus the extraction **is** the artifact: the digest moves onto it (immutability still enforced, on the bytes that actually matter) and the original stays where it lives, recorded as `original_path:` + `original_sha256:`. 233 MB of manuals do not enter your repository to protect bytes no locator addresses — and the two recorded fields are honest about their limits, which differ: `original_sha256` checks nothing on its own (we do not hold the bytes), while `original_path` is verified to still resolve, and warns when it does not — a folder you reorganised should not leave sixteen sidecars pointing at nothing behind a green run. Spoken input is a note with `origin: elicited`; a synthesis carries `derived_from:`; your decision carries `basis:`. A note with none of the three is model knowledge dressed as a source, and the validator rejects it.
+
+2. **Extraction — the unit is the claim.** Rows of `id | claim | valid | qty | about | source | prov | state`. The **id hashes the location and the quantity, never the text**, so an LLM rephrasing mints no new identity. The locator (`p=17@412-509`) is verified: the validator opens the extraction and checks the span exists — and `anchor <path> <phrase>` produces it for you, matching spaces as `\s+` because a PDF extraction breaks phrases mid-line. **Gates are extracted alongside powers**: for every row saying what something can do, the source is asked what must hold first — default-off, licence tier, version floor, dependency — because "yes, supported" without the gate is a plan that fails on site. The rule is *ask*, never *produce*: a source that states no gate yields no row. Validity scopes are half-open ("until March" and "from March" do not conflict). Quantities are typed — mixed kinds or currencies **refuse to sum**. What the source does not assert becomes a `gaps:` line, never a claim.
+
+   **The source is exhausted, not sampled.** "Invents nothing" is a floor, and an extractor that stops when nothing it wrote is false stops on page twenty of a two-hundred-page manual with every row correct — which is exactly what a 200-page manual produces in the field. So a long source is read in **bounded windows** (30 pages by default, one plan task each, the ledger holding your place across sessions), and every window closes by advancing `extracted_through:` on the artifact's sidecar. That field is what makes "I am finished" falsifiable: claims with no coverage recorded are an error, a claim addressing a page past the declared coverage is a contradiction, and coverage short of the end is reported until it reaches it. Its limit is stated where it is written — **nothing proves a page was read**; what changes is that the shortcut must now be written down to pass. And exhaustive means read, never *a row per page*: a page that asserts nothing yields nothing.
+
+3. **Placement — five verdicts, after querying the graph.** Descent through the generated index following every parent (polyhierarchy). EXISTS → reconcile; INADEQUATE → child; **MISSING only after the graph was actually asked**; GENERALIZES → escalate (a new root stops at you); UNPLACED → quarantine. Similar-but-maybe-different becomes a sibling **with the distinguishing line written** — if you cannot write it, it is the same concept. Cycles are refused at write time; merged nodes leave a tombstone with `redirect_to:`, never a deletion.
+
+4. **Reconciliation — the machine detects and holds, it never decides.** Five outcomes: new / confirmation (the source is appended to the row — the base strengthens, it does not lengthen) / refinement (the old row goes `SUPERSEDED`, its text intact) / coexistence (disjoint scopes) / conflict → the whole set goes `CONTESTED`, **symmetrically**: flipping one cell by hand fails the check. Only new information resolves it — a later source, or **your ruling with a `basis:`**, the fact you know and the corpus does not. No basis, no ruling: a preference is not a fact. A ruling is challengeable — a later document reopens the case with your basis beside it.
+
+5. **Escalation in one batch at the end of the run**, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.
+
+6. **Recall — the graph is read when answering, not only written when distilling.** Whenever a reply would assert facts about the project's domain, the agent scans the topic index and descends before answering from model memory — plausibility of coverage is judged ON the scanned index, never before it. Answers cite claim ids; a superseded claim is never cited without its successor; the verdict is declared only when the recall ran (`kb: <slug> → N claims cited`, a matched node with no claims surfaces its `gaps:`, and a missing index is reported as index-absent — not as a missing graph — with the regenerate command). When a DERIVED claim grounds a decision, its chain is walked to non-DERIVED ground (the given artifact or the elicited/ruled note) and that ground is cited — re-reading the agent's own synthesis is the echo chamber this rule exists to break. By construction, not exhortation: the kb `orient` opens every session with the topic router in sight.
+
+7. **Capture — the day's decisions reach the ledger before they evaporate.** At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb `orient` shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.
+
+8. **Revision — documents read as current state.** Incorporating new knowledge into an existing document is a full re-read and a body rewrite, not a stack of dated deltas: anchored edits are each correct while the document as a whole rots. The doctrine keeps history in the Diary (past entries never rewritten), leaves claim tables to reconciliation and graph edges to the taxonomy, and runs per document even in a multi-document pass. Born from a real field post-mortem: twelve documents realigned by append, every untouched sentence left standing as printed truth.
+
+Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
+
+## Key features
+
+- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
+- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
+- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
+- **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
+- **Question discipline**: a real doubt is asked when it emerges, before its answer is written, with the pros and cons of each option; a choice whose pros clearly win is taken with the weighing written next to it. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks.
+- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
+- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- superseded-cited documents, expired `valid` windows, superseded derivation chains), plus the spine's `mark`/`benefit`/`gate`/`plan`/`orient`/`migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read; it always exits 0 and carries no verdict. 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`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` (copy all three) — plus the `LICENSE` and `NOTICE` it ships under.
+
+## Installation
+
+```bash
+npm install -g @antoneeo/kb-agentic-skill@latest
+```
+
+That is enough — the package's `postinstall` runs the installer. If your npm blocks
+install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
+
+```bash
+kb-agentic-install-skill
+```
+
+> The command is on your PATH only after a **global** (`-g`) install; after a local
+> `npm i`, invoke it as `npx kb-agentic-install-skill`.
+
+The installer copies `skills/kb-agentic-skill/` recursively into native skill locations:
+
+- Claude Code: `~/.claude/skills/kb-agentic/`
+- Codex: `~/.codex/skills/kb-agentic/`
+- Gemini CLI: `~/.gemini/skills/kb-agentic/`
+- Google Antigravity: `~/.gemini/config/skills/kb-agentic/` (override the home with `ANTIGRAVITY_HOME`)
+
+Restart the relevant agent, or reload skills where the CLI supports it.
+
+Initialize a project:
+
+```bash
+kb-agentic-init
+```
+
+Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+Installing or updating the npm package **wires the session-orientation hook
+machine-wide** (user-level `~/.claude/settings.json`, Claude Code with Python):
+every project with a docs root greets its agent already oriented, and removing
+the entry is a standing opt-out that no update ever overrides. `init` still
+wires per-project where that is the better shape (a vendored validator, a
+shared team file), so an agent opening
+the project is handed the reading guide, the generated manifest, the guide router and the
+last handoff before it does anything — instead of only when it remembers to look. That
+wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
+skipped, and a project could run fully governed with an agent that never met the process.
+
+The hook command names a validator, so where that validator lives decides which file gets
+it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
+(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
+`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
+duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
+with the correction rather than counted as installed. `check` prints a one-line
+note when a machine has no orientation hook at project or user level (or a dead
+one), and an opt-in per-turn reminder exists for long sessions: `sdlc_check.py
+remind`, one constant line via UserPromptSubmit -- documented in `ENFORCEMENT.md`
+par.4, never wired by default.
+
+## The family: four lenses, one spine
+
+| Package | Faithful to | Unit of work |
+|---|---|---|
+| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature |
+| `@antoneeo/kb-agentic-skill` (this one) | the documents you supply | topic |
+| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement |
+| [`@antoneeo/course-creator`](../course-creator/README.md) | the learner's starting point and verified teaching sources | course |
+
+The four lenses ship the common validator core and knowledge-integrity engine. When two live in the same project, `routing.md` decides which lens owns a given piece of work. Marketing uses its numerical checks, and course creator checks the instructional graph and references. A course may use KB sources without making the KB topic graph its prerequisite graph.
+
+## Standalone vs Hybrid
+
+- **Standalone** — `ai_docs/` is the source of truth: vision, topics, corpus, audit, handoff.
+- **Hybrid with devPNT** — devPNT governs `M-VISION`, Master Plan, Action Plan and versioned artifacts; `ai_docs/` stays as readable context, fallback and shadow. Divergence between your request, the local Vision and the M-VISION is surfaced before any work.
+
+## Created By
+
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
+
+## License
+
+Apache-2.0 — the full terms are in the `LICENSE` file, the attribution in `NOTICE`. Copyright 2026 Antonio Pinto.
+
+If you redistribute this skill, or a version you modified, keep `LICENSE` and `NOTICE` with it.
+
+Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.
+
+Versions up to 1.16.0 were released under the MIT license and remain available under it.
+
+If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:
+
+```markdown
+[![Made with kb-agentic](https://img.shields.io/badge/made%20with-kb--agentic-blue)](https://www.npmjs.com/package/@antoneeo/kb-agentic-skill)
+```
+
+## Which model to run it on
+
+The skill names **capability tiers**, never providers — a model name in doctrine
+rots at the next release. The binding is yours to make, and the rule is one line:
+
+> **A session's floor is the highest floor among the roles it performs itself.**
+
+Authoring a governed artifact — the vision, the analysis, the use cases, the
+threat model — is a **deep-tier** role: its output is judgement, and nothing
+downstream scores it. So a session that will DESIGN wants your strongest model.
+A session that only executes an already-approved plan, or does small maintenance,
+can sit a tier lower. The cheapest tier is the wrong choice for the main session
+whatever the task, because the failure there is not a wrong answer — it is
+**silently not applying the process**: a triage never run, a router verdict
+declared without the lookup, a gate nobody noticed. That failure is invisible to
+every check in here.
+
+**The reviewer's tier is not automatically yours.** On some clients a subagent
+inherits the session's model; on others it takes one from its own definition, so
+a strong session can be reviewed by a weak one — and a weak session can buy a
+strong review. Set it deliberately; the
+`model` column in the review log is where the choice becomes visible.
+
+**Avoid one combination**: authoring below the floor AND reviewing below the floor
+on the same unit. One disclosed weakness is a disclosed weakness; two is an
+artifact nobody competent ever read. Where your client offers nothing better, the
+review still runs and both facts are recorded — a disclosed worst case beats
+skipping the review.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.18.0",
+  "version": "1.20.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.18.0",
+  "version": "1.20.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",
@@ -39,9 +39,9 @@
     "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",
-    "skills/kb-agentic-skill/scripts/knowledge.py",
-    "skills/kb-agentic-skill/memory.md",
+    "skills/kb-agentic-skill/scripts/sdlc_core.py",
+    "skills/kb-agentic-skill/scripts/knowledge.py",
+    "skills/kb-agentic-skill/memory.md",
     "skills/kb-agentic-skill/LICENSE",
     "skills/kb-agentic-skill/NOTICE",
     "gemini-extension.json",

package/scripts/init.js

@@ -196,16 +196,16 @@ in the skill's \`routing.md\`: it decides which lens's method and validation rul
 that unit. L1 never reaches it. Never refer to a document whose meaning differs by lens
 ("threat model", "vision", \`principles.md\`, \`handoff.md\`) by its bare name.
 
-Select the owning lens by the unit's purpose, then apply only its risk scale.
-The project's always-on pointer stays intact: consult the selected skill rather than
-merging multiple mandatory ladders. All lenses already carry shared project memory
-(\`memory.md\`); another installation is not needed for cross-domain recall.
+Select the owning lens by the unit's purpose, then apply only its risk scale.
+The project's always-on pointer stays intact: consult the selected skill rather than
+merging multiple mandatory ladders. All lenses already carry shared project memory
+(\`memory.md\`); another installation is not needed for cross-domain recall.
 This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
-Delete this note once the routing pointer is integrated.
+Delete this note once the routing pointer is integrated.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
+    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
   }
 }
 

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

@@ -52,13 +52,13 @@ and always fail-open. Event-driven by design: reconciliation §2 runs
 
 ## 2. Check in CI (recommended for teams)
 
-Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
+Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
 
 ```
 python tools/sdlc_check.py validate --strict
 ```
 
-The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
+The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
 
 ```
 python tools/sdlc_check.py graph --root .
@@ -69,7 +69,7 @@ python tools/sdlc_check.py corpus --root .
 
 Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
 
-Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
 
 **Projects whose docs root is not `ai_docs/`.** Pass `--docs-dir <name>` (e.g. `--docs-dir mkt_docs`) on any subcommand, or set `AGENTIC_SDLC_DOCS_DIR`. Without either, the validator walks up from the working directory and takes the nearest root it recognizes. If it finds two side by side — the shape of a half-finished migration — it refuses and names both rather than validating half a project and printing a verdict. `ai_docs/` remains the default and the recommended root: the parameter exists so a legacy tree can be read and migrated, not so a second one can be kept.
 

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.18.0
+version: 1.20.0
 description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -24,7 +24,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, plus the family-wide delegation boundary (what may be delegated at all) — that part applies at any level.
 - `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`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- the time cycle's consolidated view), plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4).  Keep the entry point, `scripts/sdlc_core.py` and `scripts/knowledge.py` together; the last supplies common memory and KB integrity.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- the time cycle's consolidated view), plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4).  Keep the entry point, `scripts/sdlc_core.py` and `scripts/knowledge.py` together; the last supplies common memory and KB integrity.
 - `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.
@@ -38,15 +38,15 @@ Read these files only when needed. `SKILL.md` is the operating contract; the sup
 - **Protect the Vision & User Style:** align all knowledge work with user strategic goals, operational preferences, and expected outcomes.
 - **Map-First Navigation:** rely on `ai_docs/README.md`, `INDEX.md`, and `reference/INDEX.md` router for targeted retrieval before creating new documents — and before *answering from model memory* on the project's domain (`## Topic Recall`).
 
-## Shared project memory
-
-Project memory is available by default, independently of installed sibling lenses.
-Read `memory.md` for the common consult/capture contract during orientation and
-closure. Use `recall` for cross-domain discovery; `index` registers original guides,
-plans and decisions without copying them. One owner still governs each unit.
-The validator now ships as three files: entry point, `sdlc_core.py`, `knowledge.py`.
-
-## Rule Zero: Triage
+## Shared project memory
+
+Project memory is available by default, independently of installed sibling lenses.
+Read `memory.md` for the common consult/capture contract during orientation and
+closure. Use `recall` for cross-domain discovery; `index` registers original guides,
+plans and decisions without copying them. One owner still governs each unit.
+The validator now ships as three files: entry point, `sdlc_core.py`, `knowledge.py`.
+
+## Rule Zero: Triage
 
 Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
 
@@ -67,13 +67,13 @@ Cross-cutting rules:
   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.
+- **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`, `course-creator`), 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.
 - Adding one claim row to an existing topic is L1: the `id` may be left empty (the validator fills it — `claim-id --fill`), and no check errors on a hand-written row.
 - If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
 - When in doubt, pick the higher level.
-- **No useless questions.** Every question to the practitioner passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. Claim-conflict escalations additionally carry their own mandated form and are batched at run end (`reconciliation.md` §4).
+- **Doubts asked, questions legal.** A real doubt is asked when it emerges, before its answer is written; every question passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. Claim-conflict escalations additionally carry their own mandated form and are batched at run end (`reconciliation.md` §4).
 
 ## Write Triggers
 

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

@@ -26,7 +26,11 @@ without an E-ISP.
    - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
      task block, the `produces` of prior-order tasks (interfaces), and
      `guides` pointers (paths, never pasted content) to stdout.
-   - Spawn the subagent with that brief as its entire context window.
+   - Spawn the subagent with that brief plus the return-doubts line as its
+     entire context window. The line: "An open point whose answer changes the
+     work is not yours to decide: return it in your final output with what you
+     searched." The orchestrator treats them as its own candidate doubts
+     (`elicitation.md` §When a doubt emerges).
    - Run `task.verify` out of band (the orchestrator executes it — the
      validator only ever prints it, never runs it) plus the one-shot review
      below.