@antoneeo/kb-agentic-skill 1.4.1 → 1.4.4

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.4.4] - 2026-08-05
+
+### Changed
+- **Shared-spine sync: use-case grounding clause (inert in this lens).** The shared `review.md`
+  gains the code lens's use-case-grounding finding — a product name in no EXISTS/NEW/METAPHOR
+  bucket, or a use-case tracing to no Vision benefit. The kb lens defines no `## Use Cases`
+  template section, so the clause stays inert here — spine parity only.
+
+## [1.4.3] - 2026-08-05
+
+### Changed
+- **Shared-spine sync: Interface Contract rename (inert in this lens).** The shared `review.md`
+  Interaction Contract clause is renamed to **Interface Contract** and gains the code lens's
+  evolved checks (responsibility-level flow, solution-leakage, universal feedback); the
+  `interaction_contract` capability key is unchanged. The kb lens defines no such template
+  section, so the clause stays inert here — spine parity only.
+
+## [1.4.2] - 2026-08-05
+
+### Fixed
+- **Registry recognition hard-coded to one entry point.** The workstream-registry
+  header is written with `entry_script()` but was recognized as "already ours" only
+  by the literal `sdlc_check.py`; recognition now matches the generated marker for
+  any family entry point — relevant on mixed-lens projects.
+- **Spine battery isolation.** `test_merge_safety` now pins its docs root in
+  `setUpModule` instead of inheriting whichever overlay was imported first by
+  unittest discovery.
+
+### Changed
+- **Shared-spine sync with code 1.22.0 (Interaction Contract, F-032).** The shared
+  `review.md` gains the Interaction Contract conformance clause and the shared core
+  registers the `interaction_contract` capability — both **inert in this lens**: the
+  clause is keyed on the lens whose template defines the section (the code lens),
+  kb claims no such capability, and no kb workflow gains any new step or artifact.
+
 ## [1.4.1] - 2026-08-03
 
 ### Added

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "kb-agentic-skill",
-  "version": "1.4.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)"
-}
+{
+  "name": "kb-agentic-skill",
+  "version": "1.4.4",
+  "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,51 +1,51 @@
-{
-  "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.4.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",
-    "claude-skill",
-    "gemini-cli",
-    "skill",
-    "knowledge-base",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "kb-agentic-init": "scripts/init.js",
-    "kb-agentic-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/kb-agentic-skill/SKILL.md",
-    "skills/kb-agentic-skill/templates.md",
-    "skills/kb-agentic-skill/taxonomy.md",
-    "skills/kb-agentic-skill/guides.md",
-    "skills/kb-agentic-skill/vision.md",
-    "skills/kb-agentic-skill/distillation.md",
-    "skills/kb-agentic-skill/reconciliation.md",
-    "skills/kb-agentic-skill/elicitation.md",
-    "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",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts/lib.js",
-    "scripts/init.js",
-    "scripts/postinstall.js",
-    "scripts/preuninstall.js"
-  ]
-}
+{
+  "name": "@antoneeo/kb-agentic-skill",
+  "version": "1.4.4",
+  "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",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "knowledge-base",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kb-agentic-init": "scripts/init.js",
+    "kb-agentic-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/kb-agentic-skill/SKILL.md",
+    "skills/kb-agentic-skill/templates.md",
+    "skills/kb-agentic-skill/taxonomy.md",
+    "skills/kb-agentic-skill/guides.md",
+    "skills/kb-agentic-skill/vision.md",
+    "skills/kb-agentic-skill/distillation.md",
+    "skills/kb-agentic-skill/reconciliation.md",
+    "skills/kb-agentic-skill/elicitation.md",
+    "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",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

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

@@ -1,148 +1,148 @@
----
-name: kb-agentic
-version: 1.4.1
-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 and knowledge management.
-author: Antonio Pinto (https://github.com/Antoneeo)
-copyright: (c) 2026 Antonio Pinto
----
-
-# KB Agentic
-
-**Why this skill exists:** to prevent *knowledge degradation and myopia* — acting from partial understanding, where new information contradicts un-indexed notes and hard-won knowledge evaporates between sessions. Triage, the Vision Gate, signal distillation, the documentation lifecycle, and operative guide routers are all one defense against that.
-
-This skill guides knowledge management and documentation with a Document-First process proportional to risk. It works fully even without devPNT. When devPNT is available and configured for the current project, the skill works in symbiosis with its governance: M-VISION, Master Plan, Action Plan and versioned artifacts become the authoritative frame for milestones and knowledge nodes.
-
-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.
-- `distillation.md`: from a source to claim rows — intake (content-addressed originals, stored canonical extraction, every provenance a real file), the claim table, extraction discipline, signal rules (symbiosis with `distill`).
-- `reconciliation.md`: what happens when two claims meet — five outcomes, detect-and-hold (the machine never decides), rulings with mandatory `basis:`, the claim state machine, the batched escalation form.
-- `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`, `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.
-
-## Knowledge Values
-
-- **Understand before writing/updating:** do not modify or create knowledge documents without checking root cause, user constraints, and existing notes — trust the primary sources and existing guides, not memory.
-- **Apply DRY and Single Source of Truth:** do not duplicate knowledge across files; extend existing notes (`ANALYSIS_[topic].md` or `GUIDE_[topic].md`).
-- **Signal & Distillation:** eliminate fluff, filler, and speculative statements; keep deterministic facts, constraints, decisions, and clear SOP steps (symbiosis with `distill`).
-- **Lifecycle & Freshness:** mark superseded knowledge (`status: SUPERSEDED` or `DEPRECATED`) so outdated information does not cause hallucination.
-- **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.
-
-## Rule Zero: Triage
-
-Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
-
-**Declare the level WITH the router verdict** (one line, for L2, L3 and Spike — L1 declares the level alone): the result of the guide-router lookup described under `## Operative Guides`, i.e. `Level: L2 · router: no match` or `Level: L3 · router: GUIDE_release_sop.md → read`. Name the guide you matched, or `no match`.
-
-| Level | Criteria | Required process |
-|---|---|---|
-| **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.
-- 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).
-
-## Write Triggers
-
-Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
-
-| Document | Write trigger | Phase |
-|---|---|---|
-| `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
-| `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
-| `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
-| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
-| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
-| `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
-| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
-| `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
-| `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal accepted by user. | 4 / 5 |
-| `reference/GUIDE_[topic].md` (`source_kind: code`/`domain`) | Recognized high-complexity domain/concept with no CURRENT guide $\rightarrow$ duty to write autonomously. | 4 / 5 |
-| `audit/reviews/REVIEW_LOG.md` | Every completed review — recorded in log. | 3 / 5 |
-| ADR / Decision Log — `architecture/` or devPNT DB | A strategic decision was taken (pattern, policy, structural change): record before DONE. | 5 |
-| `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
-
-### Full Standalone
-Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
-- Source of truth: `ai_docs/` (`vision/`, `solutions/`, `reference/`, `audit/`, `strategic/`).
-
-### Hybrid in symbiosis with devPNT
-Use this mode when `devpnt_*` tools are available and point at the current project.
-- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
-- Local `ai_docs/` serves as readable context, Standalone fallback, local handoff, or shadow copy.
-
-## L3 Workflow
-
-### 1. Audit and Alignment
-- Read `ai_docs/audit/handoff.md` (workstream registry) to see active topics.
-- Read `ai_docs/README.md`, `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md` (the guide router) before exploring notes. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do.
-- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/` docs, `strategic/` docs, and `audit/audit_plan.md`, then run `sdlc_check.py index`.
-
-### 2. Vision Gate
-- Read `project_vision.md`, `roadmap.md`, `principles.md` (or devPNT `M-VISION`).
-- Verify request aligns with expected benefits, user goals, and success signals.
-
-### 3. Request Analysis & Taxonomy Pass
-- Run spec elicitation round (`elicitation.md`) before drafting analysis.
-- Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
-- Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
-- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
-
-### 4. Knowledge Processing & Distillation
-- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
-- Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
-- Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
-- **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
-- Handle conflicting or outdated information via **Reconciliation** (`reconciliation.md`). Mark obsolete files `status: SUPERSEDED`.
-
-### 5. Closure & Indexing
-- Run verification checks (`sdlc_check.py check --root <project_root>`).
-- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
-- Update `audit/handoff.md`.
-- Regenerate manifests: `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`.
-- Mark output clean and complete.
-
-## Operative Guides & Router
-Guides are consulted, created, and distilled per `guides.md`.
-- **Consult (before acting)**: check `ai_docs/reference/INDEX.md` — the guide router — and declare the verdict with the triage level.
-- **Propose proactively**: when the user hands over indications that will govern future work, propose distilling them into a guide. A proposal, never a silent write, and never from model knowledge — a guide's whole value is that every claim traces to what the user actually provided.
-- Distill from user instructions into `ai_docs/reference/GUIDE_[topic].md`.
-
-## Mechanical Enforcement
-- `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
-- `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).
-- `scripts/sdlc_check.py check`: checks dirty closures and missing indexes.
+---
+name: kb-agentic
+version: 1.4.4
+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 and knowledge management.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+
+# KB Agentic
+
+**Why this skill exists:** to prevent *knowledge degradation and myopia* — acting from partial understanding, where new information contradicts un-indexed notes and hard-won knowledge evaporates between sessions. Triage, the Vision Gate, signal distillation, the documentation lifecycle, and operative guide routers are all one defense against that.
+
+This skill guides knowledge management and documentation with a Document-First process proportional to risk. It works fully even without devPNT. When devPNT is available and configured for the current project, the skill works in symbiosis with its governance: M-VISION, Master Plan, Action Plan and versioned artifacts become the authoritative frame for milestones and knowledge nodes.
+
+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.
+- `distillation.md`: from a source to claim rows — intake (content-addressed originals, stored canonical extraction, every provenance a real file), the claim table, extraction discipline, signal rules (symbiosis with `distill`).
+- `reconciliation.md`: what happens when two claims meet — five outcomes, detect-and-hold (the machine never decides), rulings with mandatory `basis:`, the claim state machine, the batched escalation form.
+- `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`, `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.
+
+## Knowledge Values
+
+- **Understand before writing/updating:** do not modify or create knowledge documents without checking root cause, user constraints, and existing notes — trust the primary sources and existing guides, not memory.
+- **Apply DRY and Single Source of Truth:** do not duplicate knowledge across files; extend existing notes (`ANALYSIS_[topic].md` or `GUIDE_[topic].md`).
+- **Signal & Distillation:** eliminate fluff, filler, and speculative statements; keep deterministic facts, constraints, decisions, and clear SOP steps (symbiosis with `distill`).
+- **Lifecycle & Freshness:** mark superseded knowledge (`status: SUPERSEDED` or `DEPRECATED`) so outdated information does not cause hallucination.
+- **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.
+
+## Rule Zero: Triage
+
+Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
+
+**Declare the level WITH the router verdict** (one line, for L2, L3 and Spike — L1 declares the level alone): the result of the guide-router lookup described under `## Operative Guides`, i.e. `Level: L2 · router: no match` or `Level: L3 · router: GUIDE_release_sop.md → read`. Name the guide you matched, or `no match`.
+
+| Level | Criteria | Required process |
+|---|---|---|
+| **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.
+- 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).
+
+## Write Triggers
+
+Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
+
+| Document | Write trigger | Phase |
+|---|---|---|
+| `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
+| `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
+| `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
+| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
+| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
+| `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
+| `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal accepted by user. | 4 / 5 |
+| `reference/GUIDE_[topic].md` (`source_kind: code`/`domain`) | Recognized high-complexity domain/concept with no CURRENT guide $\rightarrow$ duty to write autonomously. | 4 / 5 |
+| `audit/reviews/REVIEW_LOG.md` | Every completed review — recorded in log. | 3 / 5 |
+| ADR / Decision Log — `architecture/` or devPNT DB | A strategic decision was taken (pattern, policy, structural change): record before DONE. | 5 |
+| `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
+
+### Full Standalone
+Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
+- Source of truth: `ai_docs/` (`vision/`, `solutions/`, `reference/`, `audit/`, `strategic/`).
+
+### Hybrid in symbiosis with devPNT
+Use this mode when `devpnt_*` tools are available and point at the current project.
+- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
+- Local `ai_docs/` serves as readable context, Standalone fallback, local handoff, or shadow copy.
+
+## L3 Workflow
+
+### 1. Audit and Alignment
+- Read `ai_docs/audit/handoff.md` (workstream registry) to see active topics.
+- Read `ai_docs/README.md`, `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md` (the guide router) before exploring notes. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do.
+- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/` docs, `strategic/` docs, and `audit/audit_plan.md`, then run `sdlc_check.py index`.
+
+### 2. Vision Gate
+- Read `project_vision.md`, `roadmap.md`, `principles.md` (or devPNT `M-VISION`).
+- Verify request aligns with expected benefits, user goals, and success signals.
+
+### 3. Request Analysis & Taxonomy Pass
+- Run spec elicitation round (`elicitation.md`) before drafting analysis.
+- Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
+- Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
+- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
+
+### 4. Knowledge Processing & Distillation
+- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
+- Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
+- Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
+- **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
+- Handle conflicting or outdated information via **Reconciliation** (`reconciliation.md`). Mark obsolete files `status: SUPERSEDED`.
+
+### 5. Closure & Indexing
+- Run verification checks (`sdlc_check.py check --root <project_root>`).
+- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
+- Update `audit/handoff.md`.
+- Regenerate manifests: `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`.
+- Mark output clean and complete.
+
+## Operative Guides & Router
+Guides are consulted, created, and distilled per `guides.md`.
+- **Consult (before acting)**: check `ai_docs/reference/INDEX.md` — the guide router — and declare the verdict with the triage level.
+- **Propose proactively**: when the user hands over indications that will govern future work, propose distilling them into a guide. A proposal, never a silent write, and never from model knowledge — a guide's whole value is that every claim traces to what the user actually provided.
+- Distill from user instructions into `ai_docs/reference/GUIDE_[topic].md`.
+
+## Mechanical Enforcement
+- `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
+- `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).
+- `scripts/sdlc_check.py check`: checks dirty closures and missing indexes.

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

@@ -146,6 +146,19 @@ When you are the reviewer:
   which one is current. The rule bites hardest across domains, where the same slot
   ("threat model", "vision", "handoff") carries a different meaning under each lens and
   a copy looks like an independent second source.
+- **Use-case grounding (same reviews; the two-check gate whose owning definition
+  is the code lens's `templates.md` `## Use Cases / User Needs` comment — cite it,
+  never restate it).** On an L3 impact/solution analysis (Standalone) or `D-UC`
+  (Hybrid), two findings live here and nowhere else: **a product name in no
+  bucket** — the use-cases name a thing that neither EXISTS in the product (called
+  by the term the product itself uses; a renamed existing thing is a phantom), nor
+  is declared NEW in this change, nor is a pure METAPHOR kept out of the interface;
+  it invents system reality that is not there. And **a use-case that traces to no
+  Vision / M-VISION benefit** — a need the vision does not want, which is drift.
+  This gate checks the use-cases are GROUNDED and runs BEFORE the owner's own
+  review, never replacing it; coverage of each use-case by the Impact, and the
+  Actor it serves, stay the conformance-statement clause above. A lens whose
+  template defines no `## Use Cases` section never fires this clause.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
   that carries NO Capability Ledger is itself a finding** — the lens's capability
   pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left
@@ -168,6 +181,29 @@ When you are the reviewer:
   mark ANALYZED, with no searches named**, is the finding that matters most on a
   project the methodology arrived in recently — an unread map reported as an empty
   one is how a duplicate of the existing codebase gets designed.
+- **Interface Contract (same reviews; fires only in the lens whose template
+  defines the section — the code lens today).** When the change creates or
+  modifies an actor-facing surface (the trigger's owning definition is the code
+  lens's `templates.md` section comment — cite it, never restate it), **an
+  artifact carrying NO `## Interface Contract` is itself a finding** — "the
+  artifact does not have one" is what a skipped contract looks like, not a reason
+  to skip the check. When the contract is there, these findings live here: a
+  use-case with no named interaction flow realizing it; **a flow that is not
+  walkable at the responsibility level** — it jumps from the actor's action to
+  the outcome without naming the components it traverses; **a *how* inside the
+  contract** — a mechanism, algorithm, data structure, widget or file-level
+  design — which is Solution-leakage (the flow NAMES components as
+  responsibility-holders, it never designs them); **required feedback that omits
+  an error or intermediate state, or a software actor's return status** (feedback
+  is universal, not human-only); a design or diff element that alters a
+  contracted surface, flow or feedback with no explicit renegotiation note (after
+  design approval that is a scope change owed to the user, not a design detail);
+  a contracted flow the `## Test Strategy` does not cover; and a new interaction
+  idiom introduced where the contract's own as-is names an existing one, with no
+  declared reason. (The architectural constraints the surface must live with are
+  NOT checked here — architecture-awareness is the Capability Ledger / Impact
+  review's job; a clause for it would duplicate that.) A lens whose template
+  defines no such section (knowledge, marketing) never fires this clause.
 
 ## Anti-patterns
 

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

@@ -245,6 +245,7 @@ REQUIRED_CAPABILITIES = frozenset({
 # Listed here so "this distribution does not claim it" is a visible decision.
 OPTIONAL_CAPABILITIES = frozenset({
     "architect_pass",         # does the component already exist? (code overlay)
+    "interaction_contract",   # actor-facing surface spec between use cases and solution (code overlay)
     "taxonomy_pass",          # do the categories/topics already exist? (knowledge overlay)
     "comprehension_guides",   # source_kind: code maps of complex components
     "tdd",                    # test-first discipline
@@ -841,8 +842,11 @@ def registry_conversion_blockers(root):
     if not hand.is_file():
         return []
     text = read_text(hand)
-    if "GENERATED by sdlc_check.py index" in text:
-        return []                                   # already ours
+    # "Already ours" = written by ANY family entry point: the header is WRITTEN
+    # with entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+        return []
     blockers = []
     known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
     orphans = [r for r in parse_registry_rows(text) if r not in known]