@antoneeo/agentic-sdlc-skill 1.15.0 → 1.19.0

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/dispatch.md

@@ -38,7 +38,9 @@ consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrat
 runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
 router) when populating `guides`. A dispatched context-free subagent does **NOT**
 run its own router consult — it reads the guide pointers handed to it in the
-brief. (Proactive guide-creation stays at closure — the same broad final pass
+brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (Proactive guide-creation stays at closure — the same broad final pass
 below — so it needs no separate dispatch hook.)
 
 ## Model tiers (client-relative, no provider names)

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

@@ -8,13 +8,24 @@ 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.
 
+Unattended path: when the user is not reachable (a scheduled or autonomous run,
+and a bootstrap Vision is `DRAFT` by mandate, so the skip path above cannot
+apply on a project's first L3), do not stall and do not invent consensus. Write
+the six 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 round
 
 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:
 
-1. **Goal / benefit** — what problem this closes and why now.
+1. **Goal / benefit** — what problem this closes and why now. The answer must
+   name what the actor *obtains*, not a mechanism: "a dashboard" is not an
+   answer to "never lose the thread" — ask again until it is a benefit
+   (`vision.md`: the Vision is the distilled benefit; solutions and preferences
+   are what gets filtered out).
 2. **Actors** — who interacts with this: their role, primary goal, and what
    "good UX" means to them. These become the Vision's `## Actors`; each
    use-case below attaches to one (actor = who they are, use-case = what

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

@@ -40,6 +40,26 @@ already cover how to do this well?*
   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
@@ -103,6 +123,11 @@ the component from partial understanding.
   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
 

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
@@ -22,6 +76,14 @@ When you hand work to a reviewer (human or agent), give them:
   (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
@@ -63,6 +125,27 @@ 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.
+- **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
+  that carries NO Capability Ledger is itself a finding** — the architect pass 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 (`architect.md`): 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`) 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