@antoneeo/agentic-sdlc-skill 1.17.0 → 1.20.2

package/skills/agentic-sdlc-skill/architect.md

@@ -0,0 +1,215 @@
+# The Architect Pass
+
+Applies at L3, in phase 3, AFTER the spec elicitation and BEFORE the Impact is
+drafted. It answers the one question the Impact cannot ask: *does the system
+already have the components and services this feature needs?*
+
+Why it exists: **a feature is not a unit of construction.** Left alone, an agent
+designs the feature and builds whatever it lacks inside the feature's own code
+path — so no component owns the capability, the next feature that needs it
+rebuilds it differently, and the platform accretes feature-shaped code nobody can
+reuse. That is myopia one level above the file: the change is complete, the tests
+pass, and the architecture is worse.
+
+## 1. State the feature as capabilities, not as files
+
+Write what the system must be able to DO for this feature to exist — "persist a
+draft across sessions", "notify a third party asynchronously", "authorize per
+tenant". A capability is a verb over a domain noun. It names no file, no class and
+no library: **that** is the decoupling. Files come later, in the Impact.
+
+Two or three capabilities is a normal feature. When the list has one obvious entry
+and it plainly exists, say so in one line **under the `## Capability Ledger`
+heading, still naming the component and where it lives**, and move on — this pass
+is a question to answer, not a form to fill. The heading is what makes a cheap
+answer distinguishable from a skipped pass; a bare "everything already exists"
+names nothing and is the **Paper ledger** anti-pattern, not the licence.
+
+## 2. Rule each capability against the platform
+
+One verdict per capability:
+
+| Verdict | Meaning | What the row must carry |
+|---|---|---|
+| **EXISTS** | a component already owns this capability and covers the need | the component, where it lives (path / symbol), and the one guarantee you re-read it to confirm |
+| **INADEQUATE** | a component owns it but does not cover the need | the same, plus the gap in one line |
+| **MISSING** | no component owns it | the terms you searched, the tool, and the areas covered |
+
+Read the **`## Component Map`** in `strategic/architecture.md` first — the project's
+inventory of what owns which capability, kept so this pass does not re-derive the
+platform from source every session.
+
+**The map is a cache of evidence somebody already paid for. It lowers the COST of a
+verdict, never the STANDARD of one.** Every verdict carries the same evidence
+whether the map answered it or not; a hit means the search is already written down,
+a miss means you pay full price. Reading a row does not excuse you from checking
+that it is still true — the map is the index, the code is the evidence.
+
+**Its silence is unread, not empty.** The map covers only the areas `audit/
+audit_plan.md` marks ANALYZED — and that state is a claim someone made, not a fact
+the tooling verified: marking asserts *the area was read closely enough to name the
+capabilities it owns*, so an area marked after two greps is a false ANALYZED and
+the person who wrote it owns the duplicate that follows. In an area still PENDING —
+or SKIPPED, or absent from the plan entirely — **the map can never ground a MISSING
+verdict.** Nothing there has been looked at yet, and "the inventory does not mention
+it" is the reasoning that builds a second copy of a component that already exists.
+
+**Searching for an owner** is text search first, symbol-graph second — in that
+order, because you are looking for a name you do not know yet, and a call-hierarchy
+tool needs a resolved symbol as *input*. Grep the repository (minus SKIPPED areas)
+for the domain noun, at least two plausible synonyms, and the verb; then use the
+symbol-graph tool to confirm or dismiss the candidates the search surfaced.
+
+**The floor for a MISSING** is about triage, not term count: every hit that lands in
+an unmapped area gets opened, or the MISSING is **provisional** and says so in its
+row. Record what you ran — terms, tool, areas — and stop when the terms are
+exhausted and no candidate remains unopened. A provisional MISSING is honest and
+cheap; an unfalsifiable one is the same defect as an EXISTS with no symbol named.
+
+**Understanding is never deferred; only WRITING the map is.** You may leave the rest
+of the repository unmapped and grow the inventory feature by feature — you may not
+leave unexamined anything this change touches or depends on. That blast zone is
+understood now, at full standard, mapped or not. The incremental licence is about
+the artifact, never about the comprehension.
+
+Ground every verdict. An EXISTS with no named symbol is an assumption wearing a
+verdict's clothes, and it is the row that breaks in implementation. A MISSING
+declared without a real search is how duplication enters — the component may be
+there under a name you did not guess. This is the DRY check at architecture level.
+
+## 3. Design what is missing as a component, not as feature internals
+
+INADEQUATE and MISSING produce design work of their own, governed by one rule:
+
+**The component's contract is stated in the component's own vocabulary. The feature
+is one consumer, never the owner.**
+
+The test is mechanical: write the contract — what it does, what it takes, what it
+guarantees — *without naming the feature*. If you cannot, the contract is
+feature-shaped, and the second consumer will force it open. **Renaming the
+feature's nouns is not stating the contract in the component's vocabulary**:
+`store(ConfirmationPayload) -> id` described as "stores records by id" still fails.
+The question the wording cannot dodge — *would a second plausible consumer have to
+change this signature?* If yes it is feature-shaped, however it is phrased.
+
+The opposite error is equally real: this is not a licence to build a framework.
+Build for the need you have, at the size you need. What the rule constrains is the
+contract's **vocabulary and ownership**, not its scope — a five-line component with
+a clean contract satisfies it in full.
+
+## 4. Decide the unit of change
+
+A capability that needs building becomes **its own ANALYSIS, its own branch and its
+own closure** when ANY of these holds:
+
+- it will have more than one consumer, now or in the declared roadmap;
+- **it can ship before this feature does** — merged and adopted on its own cadence,
+  with the feature still unfinished. (Not "buildable and testable on its own": §3
+  requires that of every component, so reading it that way makes the default branch
+  below unreachable and puts every five-line helper through its own L3.) IN: a
+  storage layer another team can adopt next sprint while this feature is still in
+  design. OUT: a helper nobody can use until the feature that motivated it lands;
+- it carries its own risk surface: security, a public contract, a data model, or a
+  new dependency.
+
+Otherwise it is a **phase inside this feature's plan** — the first phase, before the
+feature consumes it — and it is still a component: own contract, own tests, never
+inlined into the feature's code path. **The split rule decides the paperwork; it
+never decides whether the component exists.**
+
+When it does become its own unit, each document names the other: the feature's
+ANALYSIS points at the component's, and the component's lists its consumers.
+
+## 5. Order
+
+The component is designed before the feature that consumes it, and normally built
+and tested before it too. A feature blocked on a capability it does not have is not
+"in progress" — it is a component task wearing a feature's name.
+
+## Anti-patterns
+
+- **Inlining** — the capability is implemented inside the feature's code path and no
+  component owns it. Symptom: the next feature that needs it must copy it or
+  refactor yours. This is the failure the pass exists to prevent.
+- **Feature-shaped platform** — the component exists, but its contract speaks the
+  feature's vocabulary. Symptom: the second consumer forces a contract change.
+- **Silent degradation** — a capability comes out MISSING, nobody wants to build it,
+  so the feature is quietly reshaped around what exists and ships as less than what
+  was asked. The reduced benefit must be surfaced to the user as a scope change and
+  recorded in the ANALYSIS; absorbing it silently is the Vision-divergence rule
+  broken one level down.
+- **Speculative platform** — a general framework built for a single known need.
+- **Paper ledger** — every row EXISTS, nothing named. Unfalsifiable, exactly like a
+  review that reports "I checked".
+- **Empty-map MISSING** — ruling a capability MISSING because the Component Map is
+  silent about it, in an area nobody has analyzed yet. The map's silence is
+  *unread*, not *empty*. On a project the methodology has just arrived in, the map
+  is nearly all silence, and this is the anti-pattern that duplicates the existing
+  codebase one component at a time.
+
+## Where the output is recorded
+
+Standalone: the `## Capability Ledger` section of the ANALYSIS (`templates.md`),
+immediately before `## Impact`, which it feeds — every INADEQUATE or MISSING row
+lands there as files to create or change. The closure review maps the ledger row by
+row (`review.md`).
+
+**A component that gets built lands in the `## Component Map`** of
+`strategic/architecture.md`, in the same closure — capability owned, contract,
+where it lives. This is the loop that makes the pass repeatable instead of
+per-session: the ledger asks the map what exists, so a component the map never
+learned about is one the next feature rules MISSING and builds a second time. The
+trigger is the component's birth, not a stack change (Write Triggers).
+
+**So does a component you merely discovered.** When the pass searches an unmapped
+area and finds an existing owner, write that row too, then `sdlc_check.py mark` the
+area you covered — **in that order, and never the mark without the rows.** Marking
+an area ANALYZED while its owners stay unwritten is the worst of both states: the
+area now looks read, so the map's silence there becomes groundable, and the next
+feature rules MISSING and builds a duplicate — lawfully. What a mark asserts is
+exactly this: *the area was read closely enough to name the capabilities it owns.*
+The map then grows by the feature that needed the knowledge instead of by an
+up-front sweep — the understanding was paid for either way, and this is the step
+that stops the next session paying for it again.
+
+Hybrid: the ledger goes in the `E-ISP`, above its Impacted Components map. A
+capability split out as its own unit of change gets its own `E-ISP`/`E-TDD`, and the
+feature's `E-ISP` names it as a dependency.
+
+## Mechanical backstops
+
+Prose is not enforcement; these are the checks that notice when the pass did not
+run or its output rotted. Both are **advisories** — printed as `[note]`, never
+counted as warnings, and never failing a build, **not even under `--strict`**. That
+is deliberate: the ceremony budget accepted for this pass was a signal, and a
+warning that reddens a pipeline is a gate under another name.
+
+- **Skipped pass**: `validate` notes an L3 ANALYSIS started on/after 2026-07-28
+  that lacks `## Capability Ledger`. Grandfathered by `start_date` alone —
+  analyses born before the pass existed never nag — and deliberately NOT by
+  status: closure flips the ANALYSIS to COMPLETED *before* `check` runs, so a
+  status filter would silence the backstop at the exact moment the process
+  mandates the validator.
+- **Rotting map**: `validate` resolves every path-shaped ref in the Component
+  Map's `Where` column — a path that no longer exists, or a `#symbol` no longer
+  present as a whole word in the file, is flagged; so is a map whose rows carry
+  no checkable path at all, or whose header has no `Where` column (an inert check
+  reported as a clean one is the same defect as an unread map reported as empty).
+  This is the map's equivalent of the guides' `source_hash`, with the same honest
+  limit: it proves the ref resolves, never that the row still describes the
+  component correctly.
+- **A mark nobody paid for**: `validate` notes an area the audit plan marks
+  ANALYZED that owns no Component Map row. Marking is one cheap command and it is
+  what converts the map's silence into a groundable MISSING — so this is the other
+  half of the loop, the check that a mark asserted something real.
+- **Adherence** (non-gating, **skill development only** — `evals/` is not shipped
+  in the installed package): `architect_rules_before_impact.md` runs the pass
+  cold; `unmapped_never_grounds_missing.md` sets the brownfield trap — an existing
+  component in a PENDING area, where ruling MISSING from the map's silence is the
+  failure.
+
+## Below L3
+
+L1 and L2 do not run this pass. A capability discovered MISSING during L2 work is
+itself an escalation trigger: stop, reclassify to L3, declare it (Rule Zero). "The
+component was not there" is never a reason to build it inside an L2.

package/skills/agentic-sdlc-skill/elicitation.md

@@ -1,15 +1,130 @@
 # Spec Elicitation
 
-Applies when an L3 request enters phase 3 (Request Analysis), BEFORE
-drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP (Hybrid).
+`## The question discipline` below governs EVERY question to the user — any
+phase, any level, inside or outside the round. The rest of the file is the spec
+elicitation round: it applies when an L3 request enters phase 3 (Request
+Analysis), BEFORE drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP
+(Hybrid).
 
-Skip path: if the spec is already complete — an approved Vision or explicit
-user requirements already answer goal, scope, and constraints — skip the
-round and add a one-line note in the analysis stating why it was skipped.
-Do not run the round as a formality when the answers are already on record.
+Skip path: if the spec is already complete — an approved Vision or explicit user
+requirements already answer goal, scope, and constraints, or the remainder is
+derivable from the repo, `ai_docs/` and the conversation — skip the round and add
+a one-line note in the analysis stating why it was skipped and naming the
+sources. Do not run the round as a formality when the answers are already on
+record.
+
+Unattended path: when the user is not reachable (a scheduled or autonomous run)
+and the skip path does not answer all six, do not stall and do not invent
+consensus. Write the missing answers as **declared assumptions** in
+`## Objective`, mark the ANALYSIS `BLOCKED on the user`, and stop before
+implementation. An assumption on the record is reviewable; a guess folded
+silently into a design is not.
+
+## The question discipline
+
+A question to the user spends their attention and stalls the work; the round
+below is the only place the process *plans* that cost. Everywhere, a question is
+legal only when BOTH hold:
+
+1. **Searched first, and the search is named — with its result.** The answer is
+   not on record and not derivable from the repo, `ai_docs/`, the Vision or the
+   conversation — and the question states the terms, tools and areas you searched
+   **and what they returned**. Same standard as a router verdict or an
+   architect-pass MISSING, and it carries their floors, not only their vocabulary
+   (`architect.md`, `guides.md`): a search whose scope does not cover the question
+   is not a search; a hit you did not open does not narrow anything; and **never
+   fake the search** — "I looked and found nothing" that names no terms and no
+   areas is a search not run. A question the repo can answer is a search
+   outsourced to the user.
+2. **It names what is blocked.** The question states the specific decision or
+   fact that cannot be resolved without the reply — what you will do differently
+   depending on the answer. If nothing downstream changes with the answer, there
+   is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is this OK?". The process
+  authorizes proceeding; if a real risk motivates the ask, name the risk and the
+  fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the user to pick among options that are
+  equivalent **in their effect on the benefit** and already decided by the
+  project's conventions. Cheapness to undo is NOT the test: nearly everything is
+  reversible under version control, and "it is reversible" as a licence to stop
+  asking is the silence-side evasion this clause must not fund.
+- **Re-asking the record** — goal, scope or constraints that an APPROVED Vision,
+  an earlier reply, or the request itself already states.
+
+What questions are FOR — what the user uniquely owns: the benefit, priorities
+between conflicting goods, non-goals, acceptance, and the approvals doctrine
+reserves to them (Vision promotion and amendment, scope changes, proposal
+acceptance, merge decisions). Facts about intent come from the user; facts about
+the system come from search. (The marketing sibling states the same rule as "ask
+only what the user uniquely owns"; this is its code-domain form.)
+
+**Precedence, because both halves can fire at once:** this paragraph wins over
+the "never legal" list above it. A choice the user uniquely owns is never
+preference-fishing, however cheap it is to undo; the list reaches choices that
+are *not* theirs.
+
+**Default non-blocking.** An unknown on which no fork of the work depends: write
+it as a **declared assumption** in the artifact it touches — the same mechanism
+the unattended path uses — proceed, and present the open points **batched**, with
+the round for spec questions or with the deliverable otherwise, answered by
+exception.
+
+This is the path most work takes, so it carries the SAME evidence duty as a
+question, not a lighter one — otherwise "assume it" becomes the way to skip the
+standard. Each declared assumption states **what it is taken from** ("I take X
+from Y" — the same shape the round uses) and **the alternative it excludes**, and
+**every declared assumption reaches the batch**: an assumption nobody is shown is
+not an open point, it is a silent decision. That pairing is what the kb family's
+escalation rule actually does — keep BOTH sides with their sources and surface
+them, never silently pick one — and this branch, not the blocking one, is where
+it structurally belongs. An assumption recorded with its source and its rejected
+alternative is reviewable; one recorded alone is a decision wearing an
+assumption's clothes, and a session stalled on a question that could have been
+an assumption is the waste this section exists to prevent.
+
+**Blocking is reserved** for three cases: proceeding under ANY assumption would
+waste the work (the forks diverge at once, and the wrong branch is rework of the
+whole unit); the doctrine reserves the decision to the user (the approvals
+above); or the doctrine itself mandates the stop — and a mandated stop is legal
+by mandate, never re-argued here.
+
+**Exactly two mandating files prescribe their own hand-over, and there the form
+below does not apply** (two forms over one moment is the duplicate `review.md`
+§Reviewing forbids): `debugging.md`'s circuit breaker — the minimal reproduction,
+what was ruled out, the current best hypothesis; and `review.md`'s round cap —
+the artifact plus the open findings. That list is closed. **Every other mandated
+stop carries the form**, including one that names only its options and not its
+evidence (`SKILL.md`'s Vision-Gate conflict names the two choices — the evidence
+is still owed, and for a Vision conflict the quoted line IS the substance) and
+one that prescribes nothing (`guides.md`'s guide proposal and its ingestion
+bound). "The file mentions the moment" is not a prescription; only a stated
+hand-over is.
+
+A blocking question carries a mandatory form — surface both sides with their
+evidence, never silently pick one:
+
+- the fork: the concrete options and what each implies for the work;
+- the evidence: what you searched, read or tried, and what it leaves undecided;
+- why no assumption survives — what work is discarded if you assume and are
+  wrong. This is what makes case (a) falsifiable: without it, "this is a fork"
+  is an agent's assertion about its own convenience, and case (a) becomes the
+  licence for exactly the question this section forbids. Cases (b) and (c) answer
+  it by citing the approval or the mandate instead;
+- why it is the user's call — what makes the remainder intent, priority or
+  approval rather than a derivable fact;
+- what stays blocked until answered.
 
 ## The round
 
+**Derive before asking.** Answer each of the six from the record first — the
+Vision, `ai_docs/`, the conversation, the code. Ask only the residue, and carry
+the derived answers into the round as declared assumptions corrected by
+exception ("I take X from Y; the questions below are what no source answers"),
+not re-confirmed one by one.
+
 Ask ONE structured set of questions, not a drip of follow-ups. Keep each
 question short and numbered; offer concrete options where a real choice
 exists (this narrows the reply and speeds up the round). Cover:
@@ -46,8 +161,9 @@ run a second round to double-check answers that were already clear.
 
 - **Interrogation**: an endless list of questions, or drip-feeding one
   question at a time across many turns instead of one structured round.
-- **Asking what the approved vision already answers**: re-asking goal or
-  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
 - **Collecting answers without folding them in**: getting replies in chat
   and proceeding to design without writing them into the analysis document —
   the next reader has no record of why the scope is what it is.
+
+(The illegal question forms — generic confirmation, preference-fishing,
+re-asking the record — are defined once, in `## The question discipline`.)

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

@@ -46,6 +46,14 @@ already cover how to do this well?*
   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

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

@@ -1,10 +1,62 @@
-# Code Review Discipline
+# Review Discipline
 
-Applies at closure of L2/L3 work, and to any independent review slot in this
-skill or in a connected governance layer — devPNT's §4.5/§4.6 review gates,
-and any future review step added to the workflow. This is 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).
+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
 
@@ -13,7 +65,9 @@ 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.
+- **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
@@ -71,6 +125,37 @@ When you are the reviewer:
   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
 

package/skills/agentic-sdlc-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.