@antoneeo/agentic-sdlc-skill 1.17.0 → 1.20.2

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

@@ -14,12 +14,15 @@ Every durable canonical document opens with this frontmatter: it feeds the gener
 description: One line — what the document is and when to read it.
 status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
 supersedes: old_doc.md       # only if it replaces another canonical doc
+domain: code                 # optional — code | knowledge | marketing; omit in a single-domain project
 ---
 # Document Title
 ```
 
 When a doc replaces another: the new one declares `supersedes:`, the old one switches to `status: SUPERSEDED` (it stays as history, do not delete it). `sdlc_check.py validate` warns if `status` is missing or if a superseded doc is still `CURRENT`.
 
+**`domain:` — write it only when it says something.** It names the domain whose fidelity discipline the document was written under, and it *records* an answer the work already has; it never decides one. Omit it and the project default applies (`default_domain:` in `ai_docs/README.md`, absent → `code`), so a single-domain project never writes the field at all. Documents under `vision/` sit above the split and take no `domain:`. In a mixed project, a wrong or forgotten field surfaces as a validation error on the missing mandatory risk section — never as a silent pass.
+
 ## ai_docs/reference/GUIDE_[topic].md
 
 A guide is either OPERATIVE (`source_kind: document` — distilled from USER-PROVIDED
@@ -72,6 +75,9 @@ Section repertoire (pick what the source supports):
 Curated must-read index, by hand (it is NOT the generated manifest). Created at init, updated rarely, only for real must-reads.
 
 ```markdown
+---
+default_domain: code
+---
 # ai_docs — reading guide
 
 Must-reads for this project, in order. The full manifest of canonical docs is
@@ -87,6 +93,8 @@ feature catalog), `reference/` (operative guides), `solutions/` (per-feature
 analyses, discovery-by-grep), `audit/` (audit plan and handoff).
 ```
 
+`default_domain:` is the project's answer for every document that does not declare its own `domain:`. Whichever lens's `init` created the project seeds it; a later init never overwrites it, and an absent line resolves to `code` — so every project created before this field existed keeps behaving exactly as it did. It is written once, at project level, precisely so that the same tree gets **the same verdict from every installed lens**.
+
 ## ai_docs/vision/project_vision.md
 
 A Vision states **the benefit to be obtained while leaving the most degrees of
@@ -208,6 +216,8 @@ Only for features spanning multiple ANALYSIS documents or multiple milestones: o
 
 The frontmatter is the source of truth for the feature state (the `features_history.md` index is generated from it).
 
+`domain:` and `checks:` are optional and only earn their place in a project where more than one lens is installed (see the canonical-header note above for how an omitted `domain:` resolves). `checks:` names **portable checks** imported from another domain — e.g. `domain: knowledge` with `checks: [marketing.funnel]`. An imported check can only ADD findings, never relax what the owning domain requires, so importing one is always safe; naming a check this installation does not carry produces a visible warning, never a silent pass. `id:` is unique **within a domain**, and its prefix says which: `F-` code, `K-` knowledge, `M-` marketing. Projects that predate the prefixes keep their `F-` ids — uniqueness was already scoped to the one domain they have.
+
 ```markdown
 ---
 id: F-001
@@ -216,6 +226,8 @@ status: PLANNED
 level: L3
 start_date: 2026-06-11
 end_date:
+domain: code                    # optional — code | knowledge | marketing
+checks: [marketing.funnel]      # optional — extra portable checks to run on this document
 ---
 # Feature Analysis: [Name]
 
@@ -238,8 +250,27 @@ end_date:
      use-case = what they do. Derived from the elicitation round; the Impact below
      must cover each, and the closure review checks coverage + actor UX fit. -->
 
+## Capability Ledger
+<!-- the architect pass (`architect.md`), run BEFORE the Impact below. One row per
+     capability the feature requires the system to be able to DO — a verb over a
+     domain noun, naming no file. Verdict EXISTS (name the component and where) /
+     INADEQUATE (same, plus the gap) / MISSING (say what you searched). Every
+     INADEQUATE or MISSING row becomes a component with its own contract, stated
+     without naming this feature, and lands in the Impact below. Evidence is what
+     makes a verdict falsifiable: for EXISTS/INADEQUATE the one guarantee you
+     re-read to confirm it; for MISSING the terms, the tool and the areas searched
+     (and say "provisional" when the area is still PENDING in the audit plan).
+     A question, not a form: when every capability plainly exists, one line under
+     this heading answers it — still naming the component and where it lives. -->
+
+| Capability | Verdict | Component / gap | Evidence |
+|---|---|---|---|
+| persist an order | EXISTS | `path/to/store.py#OrderStore` | re-read `save()`: durable, returns the id |
+| notify the customer | MISSING | — | grep notify/alert/dispatch + send, over src/ and legacy/; no owner |
+
 ## Impact
-<!-- existing files touched, APIs/contracts, performance, new dependencies -->
+<!-- existing files touched, APIs/contracts, performance, new dependencies.
+     Derived from the ledger above: every INADEQUATE/MISSING row appears here. -->
 
 ## Security and Threat Model
 <!-- ALWAYS mandatory, also in Standalone.
@@ -368,6 +399,39 @@ Date: 2026-06-11 (UTC)
 <!-- one or two lines: release pending, environment quirks that affect everyone -->
 ```
 
+## ai_docs/audit/reviews/REVIEW_LOG.md
+
+One row per completed review (`review.md` §When a review is due). Append-only; it
+is the record that the gate ran and what it was worth. **One schema for both
+modes** — a Hybrid project's devPNT gates write to this same file, so Standalone
+adds values to the existing columns rather than a second table.
+
+```markdown
+# Independent Review Log
+
+| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
+|---|---|---|---|---|---|---|---|
+| 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS | 1 |
+
+## Notes
+<!-- One short paragraph per review that found something worth remembering: what
+     the findings actually were, and what changed because of them. The table
+     answers "was it reviewed and by what"; this answers "what did it find" —
+     which is where `review.md`'s per-finding outcomes live. Omit for a clean
+     review; a row with 0 findings needs no note. -->
+```
+
+`tier` is the moment plus, in Hybrid, the reviewer weight: `design`, `design (late)`
+and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT gates
+and the Vision blind check). The validator reads this column by its header name, so
+extra or reordered columns are fine — but the header must say `tier`. `reviewer`
+records the realization actually used — fresh subagent, one-shot client run, or a
+**declared** self-pass. Writing `self-pass` where independence was unavailable is
+honest; writing nothing, or implying independence you did not have, is the failure
+this column exists to prevent. `findings_real` is how many raised findings survived
+triage: over time it is the only evidence of whether the gate earns its cost.
+
 ## ai_docs/audit/HANDOFF_[feature].md — volatile resume logistics (ephemeral)
 
 **Resume logistics ONLY; the ANALYSIS Diary keeps the durable narrative (DRY).**
@@ -399,12 +463,39 @@ Canonical docs: they open with the header (`description:`/`status:`) so they ent
 
 ```markdown
 ---
-description: Stack, directory structure and architectural patterns of the project.
+description: Stack, directory structure, component map and architectural patterns of the project.
 status: CURRENT
 ---
 # Project Architecture
 ## Technology Stack
 ## Directory Structure
+## Component Map
+<!-- The inventory the architect pass reads BEFORE searching the code
+     (`architect.md` §2). One row per component that OWNS a capability:
+     Capability = what it lets the system DO (a verb over a domain noun, naming
+     no file). Contract = what it guarantees its consumers, in one line, stated
+     without naming any single consumer. Where = a path, or `path#symbol` when
+     the component is smaller than its file.
+     Seeded at bootstrap; a row is added or corrected in the SAME closure that
+     builds — or merely discovers — a component, and the area is marked ANALYZED.
+     A directory is not a component: rows name what owns a capability, not where
+     files sit (that is ## Directory Structure above). An absent or stale map is
+     why the next feature rules the same capability MISSING a second time and
+     builds it again. -->
+
+Coverage: whatever `audit/audit_plan.md` marks ANALYZED — **read it, do not trust a
+list restated here** (a hand-copied list is a cache with no invalidation). Outside
+those areas this map is **unread, not empty**: it can never ground a MISSING
+verdict, and the code is searched instead (`architect.md` §2).
+
+| Component | Capability it owns | Contract | Where |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+<!-- Where is `path/to/file.py#Symbol`. Leave the placeholder row untouched until
+     the map has a real component: the validator skips an all-`...` row, so a
+     freshly seeded project is never nagged about a table nobody has filled in. -->
+
 ## Architectural Patterns
 ```