@antoneeo/kb-agentic-skill 1.0.0

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

@@ -0,0 +1,287 @@
+# Operative Guides — pipeline
+
+Support file for `ai_docs/reference/GUIDE_[topic].md`. Read this only when the
+trigger below fires; the template lives in `templates.md`.
+
+**The training model (what a guide IS).** A guide TRAINS the agent on a topic
+the user cares about, the way training works for a person: you study the
+material once, you carry a SYNTHESIS in your head, and you go back to the book
+when a task needs detail. Two levels, both produced by this pipeline:
+- **The guide = the synthesis** — compact and dense: core principles, decision
+  rules, the map of what exists, where people go wrong. Small enough that a
+  reader takes it in WHOLE before acting (that is the "preparation").
+- **The snapshot = the book** (`.sources/`, verbatim) — the details live here,
+  reachable on demand.
+- **The fidelity markers are the bridge**: `[source: <snapshot>#anchor]` both
+  proves provenance AND tells the reader where in the book the full detail is.
+A guide that restates the source at length is as wrong as a fragmented one:
+completeness is guaranteed by the book level, economy by the synthesis level.
+
+**Two source kinds.** A guide's `source_kind` is either `document` (the default —
+distilled from USER-PROVIDED indications; operative, "how to act") or `code`
+(distilled from the project's own code; a comprehension map of a complex component,
+"how it works"). Both are **source-faithful and snapshot-anchored** — the machinery
+below (snapshot, `source_hash`, fidelity markers, router, `stale`) is identical; only
+what is gathered into `.sources/` differs (a handed document vs verbatim code
+excerpts). Where a rule applies to only one kind, it says so.
+
+## 0. Consuming a guide (consult before acting)
+
+Guides only pay off if they reach the work they govern. **Before operative work,
+proportional to triage** — L1 is exempt; engaged for L2/L3 — ask: *does a guide
+already cover how to do this well?*
+
+- **Scan the router, not the guides.** Read the when-to-consult descriptions in
+  the guide router `ai_docs/reference/INDEX.md` **and** the agent-KB router
+  `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present). Match by topic.
+- **On a match, read that guide's synthesis whole** before acting (the snapshot
+  stays on demand via the section markers). No match → proceed normally.
+- **Targeted match, never blanket.** Open only the guide whose description fits
+  the task — never load every guide, which would reintroduce the exact token
+  cost the "point to them" model exists to avoid. The two-level model (compact
+  synthesis / verbatim snapshot) already bounds a single guide's cost.
+- **Declare the router verdict.** The lookup result travels with the triage
+  level (`SKILL.md` Rule Zero) as one line — `router: no match`, or
+  `router: GUIDE_x.md → read`. This is what makes the consult reliable: an
+  undeclared lookup is indistinguishable from a skipped one, to the user, to a
+  later reviewer, and to you in the next session. Declaring `no match` on a repo
+  with no matching guide is the correct, expected output — not noise.
+- **Three legal verdicts, not two.** `GUIDE_x.md → read`, `no match` (the router
+  was read; nothing fitted — including a project whose router is an empty stub,
+  which is the normal state before the first guide exists), and
+  `router: absent (no router file)` for the case where `ai_docs/reference/INDEX.md`
+  does not exist at all. That third value exists so the honest answer is always
+  available: a required declaration with no truthful value gets faked or dropped,
+  and it takes the rest of Rule Zero with it. Regenerate the router
+  (`sdlc_check.py index`) when you report `absent`.
+- **Never fake the verdict.** `no match` means the router was read and nothing
+  fitted. A verdict that is always `no match` certifies a lookup that did not
+  happen and is worse than silence; a verdict listing the catalogue means the
+  match was not targeted (T7). Two guides are legitimate only when they cover
+  distinct concerns — typically an operative guide plus the comprehension map of
+  the component being touched; three is a smell, not a thorough lookup.
+- **Under subagent dispatch** the consult happens at plan-authoring time (the
+  orchestrator populates each task's `guides` field); a context-free subagent
+  reads the pointers it was handed and does not run its own router lookup. See
+  `dispatch.md`.
+
+## 1. When to trigger
+
+Trigger test is origin + purpose, not content taxonomy (no "is this technical
+enough" judgement call):
+- **Origin**: the user hands you indications to follow — a document to adhere
+  to, a pasted policy, "do it this way", a style guide, a runbook.
+- **Purpose**: the material is meant to GOVERN how the agent operates, not
+  just inform a one-off answer.
+
+Both hold → this is guide material. Either is missing (e.g. the user pastes
+background context with no operative intent, or asks a one-off question) →
+this is not a guide; answer normally, do not create a file.
+
+Never manufacture a guide from model knowledge. If the user asks for "a guide
+on X" without handing over source material, ask for the source first — a
+guide with no `distilled_from` is not this pipeline's output.
+
+### Proactive trigger (after reusable success)
+
+The trigger above is reactive (the user hands material over). It has a proactive
+twin: **after completing work that was governed by user-provided indications and
+is plausibly reusable** — it would prepare a future task — **PROPOSE** distilling
+a guide.
+
+- It is a **proposal to the user**, routed into this same pipeline (§2 onward):
+  the user confirms topic/scope before any file is written.
+- **Never a silent write, never from model knowledge.** If the work was not
+  governed by user-provided material there is nothing to distill — do not invent
+  a guide from general knowledge (the `distilled_from` fidelity constraint, §3,
+  is absolute). This adds a moment to PROPOSE, not a new writer.
+
+### Comprehension trigger (code source, autonomous — a duty, not a proposal)
+
+The two triggers above are for `source_kind: document` (the user hands material
+over). There is a third, for `source_kind: code`: while doing L2/L3 work, when you
+recognize that a component / feature / abstraction layer is **high-complexity** and
+no CURRENT guide already covers it, it is your **duty to WRITE a comprehension
+guide** — autonomously, no proposal, no human gate. The next session (or another
+agent) must not have to re-derive the model you just paid to build, and then break
+the component from partial understanding.
+
+- **Why autonomous is allowed here** (it is NOT for `document` guides): a
+  comprehension guide is **additive, code-anchored and reversible** (git). It changes
+  no code, plan or governed artifact — so the skill-wide "propose, never a silent
+  write" rule is relaxed for THIS kind only. The anti-hallucination floor still holds:
+  §3 fidelity is absolute — every claim traces to a verbatim code excerpt in the
+  snapshot, never to your assumption about what the code does.
+- **Recognize "high-complexity" by concrete signals** (any strong combination, not a
+  vibe): you had to trace one behavior across several files/modules (summaries were
+  not enough); high fan-in / large blast radius (many consumers); non-obvious control
+  or data flow (state machine, async/eventing, DI/plugin indirection, metaprogramming,
+  cross-cutting invariants); the area was already broken once — or **repeatedly
+  across sessions** — from partial understanding (handoff / diary / git shows it);
+  the "why" is not reconstructable from a single file.
+- **Guard-rails (autonomous is not unconstrained).** Search first (§2.0 — one CURRENT
+  guide per topic, both routers). Honor the fidelity floor (§3). RECOMMEND the
+  independent guide-vs-source review (§5) — it matters more here, since no human gated
+  creation. Announce the autonomous write in the closure / handoff so it is visible.
+- **When it fires.** As soon as you recognize the signal, during the work. The
+  Phase-5 **Comprehension checkpoint** (`SKILL.md` §5) is the backstop that asks the
+  question out loud before closure — a safety net for a signal you noticed and did not
+  act on, never a licence to defer. Writing it at closure is still far better than not
+  writing it: the model you built is complete now and gone next session.
+
+## 2. Pipeline
+
+0. **Search before creating (DRY — one CURRENT guide per topic).** Before
+   proposing anything, read `ai_docs/reference/INDEX.md` and grep
+   `reference/GUIDE_*.md` for topic overlap with the new material. Never end
+   up with two CURRENT guides on the same topic. Search BOTH routers: project
+   `ai_docs/reference/INDEX.md` AND the agent KB router
+   `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present) — one CURRENT
+   guide per topic PER SCOPE; a project guide on a KB topic requires the
+   explicit `overrides:` declaration. On overlap, pick by provenance:
+   - **Same source, evolved** → UPDATE the existing guide in place: new
+     snapshot, new `source_hash`, same file (history lives in git).
+   - **Different source replacing the old one** → NEW guide + mark the old
+     one `status: SUPERSEDED` (its provenance chain must stay honest — do not
+     graft a new source onto a guide distilled from another).
+   - **Different source, partial overlap** → flag it to the user explicitly:
+     the current frontmatter binds ONE source per guide (`distilled_from`/
+     `source_hash` are singular), so a clean multi-source merge is not yet
+     supported — regenerate from the prevailing source and mark what the
+     merge drops, or keep the topics separate if they truly are.
+   Semantic overlap is NOT mechanically detectable: this step is agent
+   discipline plus the human reviewing the router — say what you found.
+   **Also verify the handed SOURCE itself is current**: check its lifecycle
+   (status/supersedes headers) and search the project for a newer version of
+   the same document before snapshotting. A user may hand you a path that a
+   migrated copy has since superseded — distilling from it produces a guide
+   that is born stale. If you find a newer version, surface it and distill
+   from that one. (Learned the hard way on first field use, 2026-07-02.)
+1. **Decompose into PREPARATION units — and weigh the fragmentation risk.**
+   A guide's goal is to PREPARE an agent for a situation: everything that
+   situation needs must arrive in ONE guide. The risk is asymmetric — extra
+   context injected costs tokens (cheap, recoverable); missing context makes
+   the agent invent or fail (the exact failure this pipeline exists to
+   prevent). Every split is a bet that no future task will cross the cut.
+   Therefore:
+   - **Default = one guide per source/domain.** Split ONLY when the resulting
+     guides would be consulted in DISJOINT situations — no plausible task
+     needs two of them at once.
+   - **Run the split test per proposed fragment and DECLARE it** in the
+     proposal: "which tasks consult this fragment, and would any of those
+     tasks also need another fragment?" Any overlap → merge, do not split.
+   - Heterogeneous sources (unrelated policies handed over together) are the
+     legitimate split case; a single coherent document about one subsystem
+     almost never is.
+   - **Also decide SCOPE per proposed guide**: project-scope
+     (`ai_docs/reference/`) or agent-scope (`~/.agentic-sdlc/ai_docs/reference/`,
+     governs the agent across ALL projects; origin+purpose test unchanged,
+     scope is a LOCATION decision by the user, never a content taxonomy; KB
+     created lazily with `.sources/` on the first agent-scope guide).
+2. **User confirms** the topic decomposition — including the fragmentation-risk
+   assessment and scope decision — before any file is written. **`source_kind: code`
+   skips this gate**: the comprehension guide is written autonomously (§1
+   comprehension trigger). Still run the fragmentation/scope judgement yourself — just
+   do not block on confirmation.
+3. **Snapshot each source verbatim** into
+   `ai_docs/reference/.sources/<slug>-<hash8>.md`:
+   - `slug` derives from the topic (lowercase, hyphenated).
+   - `hash8` = first 8 hex chars of the snapshot file's own SHA-256 (compute
+     the snapshot first, hash it, then name it — the hash is of the file you
+     just wrote, not of the original source).
+   - The hash is computed over LF-normalized content (CRLF → LF), exactly as
+     `sdlc_check.py` does in `sha256_file` — so recorded hashes survive
+     checkouts that rewrite line endings (e.g. Windows `core.autocrlf=true`).
+   - Recommended for consumer projects: add
+     `ai_docs/reference/.sources/** -text` to `.gitattributes` so git never
+     rewrites snapshot bytes at all (keeps snapshots byte-verbatim; the
+     normalized hash stays stable either way).
+   - The snapshot is verbatim: no paraphrasing, no reformatting beyond what is
+     needed to save it as markdown.
+   - **For `source_kind: code`** the snapshot is the verbatim CODE EXCERPTS the guide
+     explains — the specific functions / classes / regions of the real files, each
+     labelled with its `path:symbol` (or `path:startLine-endLine`) — assembled into
+     the one `.sources/<slug>-<hash8>.md` and hashed identically. Copy the code
+     verbatim (no paraphrase); include ONLY the regions the guide covers, not whole
+     files, so `stale` tracks the code that matters. `distilled_from` records those
+     code paths.
+4. **Source-anchored SYNTHESIS (not restatement).** Select and compress what
+   the source says into the operative essence — decision rules, invariants,
+   the "where people go wrong" list — and POINT INTO the snapshot for the
+   detail (`[source: <snapshot>#anchor]` doubles as the detail-lookup
+   pointer: "full checklist → snapshot §7"). Every claim must still trace to
+   a specific point in the snapshot; do not extract from memory of the
+   conversation — re-read the snapshot while writing each section. Selection
+   and compression are allowed and expected; ADDITION is not (that stays
+   summarize-and-expand, forbidden). A guide approaching the source's own
+   length is a paraphrase, not a synthesis — wrong output.
+5. **Render per template** (`templates.md` → `## ai_docs/reference/GUIDE_[topic].md`):
+   frontmatter with `source_kind` (`document` | `code`), `source`, `distilled_from`,
+   `source_hash` (the snapshot's SHA-256, matching what you just computed), optional
+   `source_version`; body sections chosen from the repertoire (a `code` guide uses the
+   comprehension repertoire — how it works / control & data flow / invariants / where
+   it breaks), each with a fidelity marker.
+   **Write for the two-level read**: the guide (synthesis) is small enough to
+   be read WHOLE before acting; the snapshot (book) is where size lives and
+   where readers grep/partial-read on demand, following the section markers.
+   Use the repertoire's stable, self-describing headings, keep one concern per
+   `##` section, and make the frontmatter `description` the "should I open
+   this file at all" answer. This is why one synthesis + one book beats
+   several fragments: the synthesis guarantees the whole picture, the book
+   guarantees the details, the markers connect them.
+6. **Run `sdlc_check.py index`** so both `ai_docs/INDEX.md` and
+   `ai_docs/reference/INDEX.md` (the guide router) regenerate.
+
+## 3. Fidelity rules (mandatory, the D5 constraint)
+
+"The source" below means the SNAPSHOT — a handed document for `source_kind: document`,
+verbatim code excerpts for `source_kind: code`. The constraint is identical for both:
+never from UNVERIFIED knowledge. A code guide's every claim traces to the actual code
+in the snapshot, never to your assumption about what the code does.
+
+- Only what the source supports goes in the guide. If the source is silent on
+  something a reader might expect, mark the section `[not covered by source]`
+  — never fill the gap from general knowledge.
+- Every `##` section body carries exactly one kind of marker: `[source:
+  <snapshot>#<anchor-or-line>]` for content traceable to the snapshot, or the
+  literal `[not covered by source]` for an acknowledged gap. A section with
+  neither is a validator warning.
+- `summarize-and-expand` is forbidden: do not take a short source note and
+  "helpfully" expand it into a longer procedure using inferred steps. If the
+  source says one sentence, the guide section says that one sentence
+  (source-anchored), not an elaborated version of it.
+- When in doubt about whether something is "supported" by the source, treat it
+  as not covered rather than stretching the marker to fit.
+
+## 4. Ingestion bound (T9)
+
+If a source document exceeds roughly 2000 lines, do not silently truncate or
+skim it. Stop and ask the user to either split it into smaller documents or
+select the specific sections relevant to the guide being built. Silent
+truncation produces a guide that looks complete but is missing unreviewed
+material — worse than asking.
+
+## 5. Review
+
+Before the guide is used operatively for the first time, recommend an
+independent guide-vs-source review (a fresh pass comparing the rendered guide
+against the snapshot, checking every marker) — process control per the
+threat model (P-TM). This is a recommendation to the user, not a hard gate:
+state it explicitly when handing off a newly created guide.
+
+## 6. Maintenance
+
+- **Source changed**: create a new snapshot (new hash), regenerate the guide
+  from it (new `source_hash`), and if the guide is replacing a prior guide
+  rather than updating in place, mark the old one `status: SUPERSEDED`.
+- **`stale` flags hash drift**: `sdlc_check.py stale` (also under `--hybrid`)
+  compares each guide's recorded `source_hash` against the live snapshot file
+  and reports `[stale]` when they diverge — that is the signal to regenerate,
+  not a manual freshness check.
+- **`source_kind: code` freshness**: `stale` works unchanged (the code-excerpt
+  snapshot drifts when the code changes → regenerate). ADDITIONALLY, when you modify
+  the code a comprehension guide describes, refresh that guide in the SAME closure
+  (docs travel with the code) — do not wait for `stale` to catch it. A stale
+  comprehension guide is a confident-wrong map, worse than none.
+- **Agent-global KB guides** use the same pipeline and validator via
+  `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

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

@@ -0,0 +1,79 @@
+# Reconciliation — what happens when two claims meet
+
+**For whom**: the agent that placed a new claim on a node already holding claims about
+the same subject.
+**Answers**: "is this new, corroborating, refining, coexisting or conflicting — and who
+resolves a conflict".
+**Does not answer**: how claims are extracted (`distillation.md`) or placed
+(`taxonomy.md`).
+
+**The principle, owner-set: the machine detects and holds; it never decides.** A
+conflict is resolved only by **new information** — a newer source, or a fact the
+practitioner knows that the corpus lacks. Silence is impossible by construction:
+both sides stay, marked, until information ends the disagreement.
+
+## 1. Five outcomes — the agent classifies, the machine verifies
+
+Subject-sameness is semantic judgement; no query performs it. Classify:
+
+| Outcome | When | Action |
+|---|---|---|
+| **new** | nothing on that subject | insert the row |
+| **corroboration** | same assertion, different source | append the source to the existing row (`;`-separated). **Never a second row.** The id keeps its first source |
+| **refinement** | strictly more precise, not contradictory ("Q1" → "15 March") | new row; the old one becomes `SUPERSEDED <new-id>`, its text intact |
+| **coexistence** | contradictory only if scopes overlapped — and by the half-open rule they do not | both rows stay `OK`. "12k until March" and "15k from March" are two truths, not a conflict |
+| **conflict** | contradictory, scopes overlap | **every** row in the set becomes `CONTESTED` listing all counterparts. Nothing is picked |
+
+The machine then verifies (the `graph` check): ids recompute, sources resolve and their
+spans exist, `CONTESTED` is **symmetric** (editing one cell to `OK` fails the check —
+the cheapest laundering), a `CONTESTED` pointer at a `SUPERSEDED` row is an error,
+dangling ids are errors, duplicates are errors.
+
+## 2. Resolution — only new information
+
+1. **A newer source arrives.** Ingest it normally; re-classify the set with it in view;
+   record what supersedes what.
+2. **The practitioner rules.** A ruling is a note in `corpus/notes/` whose mandatory
+   `basis:` states **the fact they know that the corpus lacks** ("client confirmed Q3 by
+   phone on 30 Jul"; "doc B is an unsigned draft"). The ruling enters the ledger as a
+   claim (`prov: RULING`, source = that note), and **every prior member of the set —
+   including the one it agrees with — becomes `SUPERSEDED <ruling-id>`**: the ruling row
+   is now the assertion, and no row lingers contested against rows that no longer
+   contest it.
+
+**No basis, no ruling.** A preference is not a fact; the validator refuses a ruling note
+without `basis:` exactly as it refuses a DERIVED note without `derived_from:`. If the
+practitioner knows nothing new, the set stays `CONTESTED` — a legitimate, permanent,
+honest state.
+
+**Rulings are challengeable.** A later source that contradicts a ruling opens a **new**
+contested set carrying the ruling's `basis:` beside the new evidence — the practitioner
+decides with both in view. Rule-once-forever would be wrong on this corpus's own
+premise: signed amendments arrive later.
+
+## 3. The state machine (claim-level, never node-level)
+
+| Event | Effect |
+|---|---|
+| conflict classified | all members → `CONTESTED <all counterparts>` (symmetric by construction) |
+| ruling recorded | ruling row `OK`; every prior member → `SUPERSEDED <ruling-id>` |
+| newer source vs a ruling | new set {new row, ruling row}; escalation shows the `basis:` |
+| member refined | the refining row inherits the member's contested relations (re-judged); counterparts rewritten to the new id |
+| corroboration of a contested member | source appended; the set untouched — more evidence is not new information, and the escalation form shows source counts |
+
+## 4. Escalation — batched, and in the legal form only
+
+Escalations are presented **once, at the end of a run** — the pipeline never stops
+mid-ingest to ask. Each escalation names: the claims in the set, each one's source
+(reopenable), date and provenance, and one line on why the machine cannot decide
+("same subject, overlapping validity, GIVEN vs GIVEN, no newer source"). **A question
+that cannot fill this form is not askable** — it is the symptom that the answer is in
+the corpus and was not searched. Generic confirmations are not questions.
+
+## 5. Document-level supersession (unchanged)
+
+Whole documents keep the family lifecycle: a superseding note or guide marks the old one
+`status: SUPERSEDED`; `supersedes:` in the new one's frontmatter links them. Claims and
+documents move independently — superseding a document does not silently resolve the
+claims extracted from it; the `corpus` check reports claims resting on superseded
+originals for re-verification.

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

@@ -0,0 +1,168 @@
+# Review Discipline
+
+The single definition of how to request, receive, and perform a review. Other
+places that need review behavior point here instead of restating it (DRY) —
+including devPNT's §4.5/§4.6 gates and any future review step.
+
+## When a review is due
+
+Two moments, and they review different things:
+
+| # | Moment | Object | Level |
+|---|---|---|---|
+| **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
+| **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+
+**Why the design review is its own moment, and not a nicety.** The closure review
+can only tell you the code matches the design; it cannot tell you the design was
+wrong. An omission in the design — an impacted file nobody listed, a threat with no
+answering requirement, a capability ruled EXISTS on an assumption — is *cheapest*
+to fix before code exists and most expensive after. And the author cannot catch it:
+a self-review runs in the context that produced the omission and is structurally
+blind to it, which is why independence, not effort, is what this gate buys.
+
+**Independence, best realization the client supports** — declare which one you used:
+
+1. **A fresh subagent** (Claude Code's Task tool, or the equivalent facility) with
+   its own context, given the artifacts below and nothing from this conversation.
+2. **A one-shot run of the client itself** (`gemini -p "…"`, `codex exec "…"`) with
+   a SELF-CONTAINED prompt — the reviewer session has no other context, which is
+   exactly what makes it independent.
+3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
+   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
+   exists**: on a client with a subagent facility or a one-shot CLI, descending to
+   it is choosing zero independence, which is the one thing this gate buys. When
+   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
+   facility on this client)` — not merely that you did. A rung named without its
+   reason is indistinguishable from a rung chosen for convenience.
+
+Rung 3 stays in the ladder deliberately: it is what keeps the methodology
+completable with no network, no account and no subagent facility. It is a floor,
+never a default.
+
+Use a different model from the author's where the client allows it.
+
+**Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
+after the third, stop and surface them to the user with the artifact — a gate that
+can block forever gets removed. **Log one row per completed review, PASS or FAIL**
+— a FAIL surfaced to the user is the highest-value outcome the gate produces, and
+logging only passes would erase exactly that evidence. The row goes in
+`ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
+`| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
+Hybrid project's devPNT gates write to the same file.
+The log is how the gate's value is measured over time; skipping it makes the gate
+unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
+
+**The reviewer is read-only and advisory.** It never edits, never commits, never
+marks anything DONE, and a PASS is not an approval to merge — the human owns that.
+
+## Requesting
+
+When you hand work to a reviewer (human or agent), give them:
+
+- **Scope**: what changed and why, in one or two lines.
+- **The authoritative design artifact**: the ANALYSIS, E-TDD, or equivalent
+  the change was built against — not a paraphrase of it.
+- **The actual diff**: the real changed files, not a description of them. (For a
+  **design** review there is no diff yet — that is the point; hand the artifact
+  plus the constraints below, and say the object under review is the design.)
+- **For an impact/solution-analysis review, the constraints it derives from**:
+  the **Vision**, including its `## Actors` (Hybrid: the `M-VISION`; Standalone:
+  `project_vision.md`/`roadmap.md` + the ANALYSIS Vision-Alignment), the
+  **use-cases / user-needs** (Hybrid: `D-UC`;
+  Standalone: the ANALYSIS `## Use Cases / User Needs`), and the **threat model**
+  (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`). Hand these
+  *in addition to* the design artifact — the reviewer checks the artifact **against**
+  them, not only for internal consistency.
+- **For a design review, the threat model too** (same sources as above). Why this
+  one and not the whole set: file coverage crosses the impact-analysis→design hop on
+  a mechanical gate (every impacted file needs a design block), so a dropped file is
+  caught; **threats have no such gate** — a threat answered in the impact analysis
+  can silently fail to become a security requirement in the design, and the later
+  code review only verifies the requirements that are there, never the ones that
+  should have been. The design reviewer checks that every threat surface the change
+  touches has a matching security requirement.
+
+Never ask a reviewer to "review my session" or "review what I just did"
+without the artifacts above — that forces them to reconstruct scope from
+conversation instead of reviewing the change itself. Say which finding
+classes you want covered (correctness, security, conformance to the design,
+test coverage) if the default scope is not obvious.
+
+## Receiving
+
+**MUST answer findings one by one — fix, or justify with evidence; why:
+silent drops turn review into theater** — a review whose findings are not
+tracked to a resolution gives the appearance of quality control without its
+substance.
+
+If you disagree with a finding, say so explicitly with your reasoning; never
+resolve a disagreement by rewording the finding until it goes away. When the
+project keeps a `REVIEW_LOG` (or equivalent), log the outcome of each
+finding there.
+
+## Reviewing
+
+When you are the reviewer:
+
+- Verify claims against the real source, not against the diff's own
+  description of itself.
+- Cite evidence as `file:line` for every finding — a finding without a
+  location is not actionable.
+- Keep severity honest: do not inflate a style preference to a blocker, and
+  do not soften a real correctness or security issue to a nit.
+- No praise padding. A review reports problems and their fixes, not a
+  summary of what looks fine.
+- **Conformance statement (impact/solution-analysis & design reviews only — not a
+  plain code-diff review).** When the artifact under review carries Vision / use-case
+  / threat-model constraints, your output MUST map each constraint to its evidence: for
+  every use-case/user-need (and the Actor it serves — a use-case with no defined Actor,
+  or an Actor UX expectation the solution does not meet, is a finding), every threat, and
+  every applicable Vision benefit/Non-Goal, state WHERE the artifact satisfies it (section
+  or `file:line`) or raise it as a finding. A PASS/approve is **not valid on "found nothing"** — the conformance
+  statement is the proof the check ran; an unfalsifiable "I checked" is the review
+  theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
+  silent-drop rule). Plain code reviews stay findings-only.
+- **Restated facts (cite, never copy).** Every governance slot has ONE owning document
+  per project. A fact restated in the artifact under review when another document owns
+  it is a **finding**: the fix is a citation naming the owner, not a better copy. This
+  binds the conformance statement too — where a constraint is satisfied by another
+  document, name that document as the evidence instead of repeating what it says. Two
+  copies of one fact diverge at the first edit, and the reader then has no way to tell
+  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.
+- **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
+  no record, and "the artifact does not have one" is what a skipped pass looks like,
+  not a reason to skip the check. (This half is load-bearing in Hybrid, where the
+  validator backstop reads Standalone ANALYSIS files only and this clause is the
+  sole check that the pass ran.) When the ledger is there, map each
+  ledger row to where the design or diff realizes it. Three findings live here and
+  nowhere else (the capability-pass file named above): a capability ruled MISSING but implemented inside
+  the feature's code path, with no component owning it; a component whose contract
+  names the feature (a second consumer would force it open); and a capability ruled
+  MISSING, not built, and absorbed by quietly reshaping the feature — that is a
+  scope change owed to the user, not a design detail. An EXISTS row with no named
+  path or symbol is itself a finding. A capability built in this change and absent
+  from the `## Component Map` (`strategic/architecture.md`, where the lens keeps one) is a finding too — and
+  so is **a component the pass merely DISCOVERED and did not write**, especially
+  when the change marks that area ANALYZED: the area now looks read, the map is
+  still silent, and the next feature may lawfully rule the capability MISSING and
+  build it twice. And a **MISSING row in an area `audit/audit_plan.md` does not
+  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.
+
+## Anti-patterns
+
+- **Batch-dismissal**: closing out a whole findings list with one blanket
+  reply instead of addressing each finding individually.
+- **Rewording instead of addressing**: editing the finding's text to look
+  resolved without changing the code or providing evidence it is a
+  non-issue.
+- **Scope-creep findings**: raising issues unrelated to the change under
+  review instead of filing them separately.

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

@@ -0,0 +1,100 @@
+# Domain Routing — which lens owns this unit of work
+
+The family ships as sibling skills built from one shared core: each lens carries its
+own **fidelity discipline** (what the work must be faithful to) and its own validation
+rules, over **one** `ai_docs/` tree. This file answers one question: *which lens's
+method governs THIS unit of work?* It does not decide where the resulting file is
+stored (step 5), and it never runs before the triage level is known — L1 never
+reaches it.
+
+## 0. Installed-lens detection — run first, fail open
+
+Look in the skills directory this skill was loaded from for sibling lenses of the
+family, identified by the `name:` in their `SKILL.md`:
+
+| Lens | Skill name | Faithful to |
+|---|---|---|
+| code | `agentic-sdlc` | this repository's code |
+| knowledge | `kb-agentic` | documents the user supplied |
+| marketing | `mkt-agentic-sdlc` | market evidence |
+
+- **No sibling installed, or the directory cannot be read** → the router does NOT run.
+  Work under the loaded lens; read no further. This is the normal single-lens case and
+  it costs nothing.
+- **At least one sibling installed** → run the router below, after the level test, on
+  every L2, L3 and Spike.
+
+Fail-open is deliberate: a detection that cannot answer must never block the work. A
+single-lens project that silently gains a router verdict it cannot act on is worse
+than no verdict at all.
+
+## 1. The router
+
+Run the steps in order. Stop at the first one that decides.
+
+1. **Fidelity / purpose.** What must the work be faithful to?
+   - *This repository's code* → provisional **code**; continue to step 2.
+   - *Documents the user supplied* → **knowledge**. Decided.
+   - *Market evidence* → **marketing**. Decided.
+   - *A deliverable whose purpose is market-facing persuasion* (copy, positioning,
+     campaign material) → **marketing regardless of source**. Decided. Without this
+     branch the marketing lens is reachable only when the *source* is market evidence,
+     never when the *purpose* is marketing — and the launch post written from the
+     release notes routes to code.
+
+2. **Deliverable class** — only on the provisional `code` branch. The predicate is on
+   the deliverable, not on its audience:
+   - *Part of this repository's own document set, shipping and maintained with the
+     code* (`ai_docs/`, README, CHANGELOG, comprehension guides, migration notes) →
+     **code**; continue to step 3.
+   - *A standalone knowledge deliverable whose fidelity extends beyond this repo's
+     code* (user documentation for an external audience, a distilled corpus) →
+     **knowledge**. Decided; step 3 is not reached.
+
+3. **Build-consumed override** — only on the provisional `code` branch, never
+   overriding a *marketing* or *supplied-documents* verdict. *Is the deliverable a
+   file the project's build or test toolchain consumes?* Executable or imported
+   source: yes. Committed Markdown: no. A yes confirms **code**.
+
+4. **Split rule.** A request whose work must be faithful to two sources is **two units
+   of work**, split before routing: the distillation (knowledge) and the design that
+   cites it (code) each route alone. The router returns one lens per unit; it never
+   returns two lenses for one unit.
+
+5. **Owning tree.** A straddling artifact keeps its lens for *method* and takes this
+   repository's tree and validator for *storage*. Lens and location are separate
+   answers — a marketing-lens document written in a code repository still lives in
+   that repository's `ai_docs/` and passes that project's validator.
+
+6. **Cross-check.** If the verdict contradicts an installed skill's `description`, the
+   descriptions are wrong: fix them. Never silently override the test with a
+   description.
+
+## 2. Worked verdicts
+
+| Request | 1 | 2 | 3 | Lens |
+|---|---|---|---|---|
+| "write the API reference docs" (hand-written, ships with the repo) | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "write user documentation for our customers' admins" | code | standalone knowledge deliverable → knowledge | n/a (left the code branch at 2) | **knowledge** |
+| "write the API reference docs" (generated — the work edits docstrings in source) | code | repo's own doc set → code | **build-consumed: yes → confirms code** | **code** |
+| "write a comprehension guide for the auth module" | code | repo's own doc set → code | not build-consumed → no flip | **code** |
+| "turn these vendor specs into a technical design" | split (step 4): spec = supplied docs; design = this repo | — | — | **knowledge** for the distillation; **code** for the design, citing it |
+| "write the pricing page copy from our market research" | **purpose: market-facing → marketing** | never reached | never reached | **marketing**; stored in this repo's tree (step 5) |
+| "write the launch blog post from the release notes" | purpose: market-facing → marketing | never reached | never reached | **marketing** |
+
+## 3. Acting on the verdict
+
+The verdict binds the **method and the validation rules**, not the storage:
+
+- **Verdict = the loaded lens** → continue; nothing changes.
+- **Verdict = a sibling lens** → say so, and work that unit under the sibling's method
+  and its rule set (its templates, its mandatory risk section — code
+  `## Security and Threat Model`, knowledge `## Sources and Verification`, marketing
+  `## Threat Map / Plan Risks`). The artifact is written with an explicit
+  `domain:` field so the answer survives the session, and it stays in this project's
+  `ai_docs/` tree (step 5).
+- **The unit was split** (step 4) → route and declare each half separately.
+
+Documents under `vision/` — the project vision, principles, the roadmap — sit **above**
+the domain split: they belong to no lens and are validated by the core's structural
+rules only. The router is not consulted for them.