wdi-method 0.5.13 → 0.6.0

package/kit/.constitution/method/document/srs-guide.md

@@ -1,147 +1,150 @@
----
-status: Accepted
----
-
-# SRS Guide
-
-**Loaded when:** writing, changing, or validating the SRS of a Product Component
-
-An SRS states how the system must **behave** for one Product Component. The PRD promised something to a
-user; this says what the system does so that promise holds. It MUST NOT say how the thing is built —
-that is `SDD-<pc>.md`.
-
-## Two skills write it, at two gates
-
-| Section | Written at | By |
-|---|---|---|
-| § Actor Register · § UC Catalogue | G3 Blueprint | `wdi-blueprint` intent `catalog` |
-| Everything below, per the component's `mode` | G4 Component | `wdi-component` intent `behaviour` |
-
-**The SRS therefore exists at `mode: catalog`.** It carries the actor list and the use case catalogue,
-because both are born at G3 and `mode` does not touch the blueprint. What does not exist at `catalog` is
-`04-usecases/UC-<n>-<slug>.md` — the step-by-step flow. Reading "no SRS at `catalog`" is wrong, and it
-was an artefact of an earlier table that showed only what varies.
-
-Depth is **read from `mode`**, never computed. Review lenses are **read from `risk_accepted`**, never from
-`mode`. Both fields are defined in `delivery-flow-guide.md` and MUST NOT be redefined here.
-
-## No BMad skill writes this
-
-`bmad-prd` writes the PRD, `bmad-architecture` writes the spine, `bmad-spec` writes SPEC. Nothing in BMad
-writes an SRS. Three consequences follow, and each MUST be handled deliberately:
-
-| Consequence | What follows |
-|---|---|
-| No `doc_standards` can fire | `bmad-review` MUST be invoked through `wdi-review`, with the lens set `risk_accepted` names |
-| No memlog is created | A decision taken while writing MUST land as a `DEC-` through `wdi-decision`, not as a parenthetical |
-| No template enforcement | The shape comes from `templates/srs.md`, applied by `wdi-init` intent `component` at birth |
-
-`bmad-advanced-elicitation` and `bmad-party-mode` MAY be used as thinking aids. They produce no artifact
-and MUST NOT be treated as authors.
-
-## Home and life cycle
-
-- `.what/<pc>/SRS-<pc>.md`, with slots `02-rules/` · `03-domain/` · `04-usecases/` · `05-scenarios/`.
-- **Living, amended forever.** An SRS MUST NOT be versioned, frozen, or superseded. A component does not
-  stop existing because a release shipped.
-- `01-requirements/` and `supplements/` are **repealed**. The first was permanently empty — `FR` live in
-  the PRD and the SRS cites them. The second existed for `ANX-`, and that concept is gone.
-
-## Writing order
-
-Binding, and each step is the input to the next. The first four happen at G3, the rest at G4:
-
-1. **Glossary** — every domain noun this component uses, into `.control/product-glossary.md`. Never
-   defined inline here.
-2. **UC Catalogue** — one line per use case: `UC-N` · title · actor · the `FR` it satisfies · `critical`
-   yes/no.
-3. **Actor Register**.
-4. **Domain Model** — entities, relations, columns. A business rule binding a second component goes to
-   `.what/business-rules.md`.
-5. **UC Specification** — full flows, per `mode`.
-6. **Local business rules**, then **State Lifecycle**, then **branch scenarios** — per `mode`.
-
-Writing these out of order produces use cases whose nouns nobody defined. When the pass covers several
-components, the order binds **within** each one, not across them.
-
-## Which use cases get a full flow
-
-| `mode` | Full flows |
-|---|---|
-| `catalog` | none — the catalogue line is the whole record |
-| `outline` · `guarded` | the use cases the component exists for, **at most 3** |
-| `deep` | every `critical` use case |
-
-A use case is `critical` when it touches **money, personal data, or an irreversible action**. That is the
-whole definition; `delivery-flow-guide.md` owns it, including the one-third sanity check.
-
-## Use cases at two altitudes
-
-The same `UC-N` MAY appear twice in the corpus, and the two MUST NOT be merged or made to duplicate each
-other:
-
-| | Here, in the SRS | There, in the SDD at `deep` |
-|---|---|---|
-| Written for | Someone who uses the product | Someone who builds it |
-| Basic Flow | **At most eight steps** | As long as the design needs |
-| May name | Actors, screens the user sees, domain nouns | Classes, endpoints, tables, transports |
-| Answers | What happens | How it happens |
-
-The eight-step cap is not style. A flow needing more steps is either two use cases, or it has started
-describing implementation — and the cap makes that visible while it is still cheap to fix.
-
-Branches MUST go to `05-scenarios/` rather than making the UC file fat, and only at `deep`.
-
-## Actor Register is the SSOT
-
-It MUST stay in the SRS kernel, never moved to a slot. The SDD MAY carry a **mirror** of it, and the mirror
-MUST NOT be edited on the SDD side. A `System` actor MAY be decomposed into the internal components that
-play it, but that decomposition belongs to the SDD.
-
-## Business rules — two homes, one test
-
-| Rule | Home | Born at |
-|---|---|---|
-| Binds more than one Product Component | `.what/business-rules.md` | G3 |
-| Binds only this component | `.what/<pc>/02-rules/rules-<pc>.md` | G4, from `outline` up |
-
-The test is not importance, it is **reach**. A rule written in one component that turns out to bind a
-second MUST be promoted, not copied. Two copies of one rule is how components start disagreeing about the
-same policy.
-
-## Sections the shape requires
-
-`templates/srs.md` carries the full list. Four MUST NOT be dropped even when they feel thin, because each
-is the one that is silently skipped:
-
-| Section | Why it MUST stay |
-|---|---|
-| **Constraints** | Inherited from the spine's `AD-N` and from the PRD. A constraint discovered at G4 costs a decision |
-| **Non-Goals** | What this component explicitly does not do. Absent, it will be assumed to do it |
-| **Prerequisite** | What MUST already exist before this component can behave as described |
-| **Assumptions, Risks, and To Be Confirmed** | Three separate lists. An assumption is something we decided to believe; a risk may go wrong; a to-be-confirmed is a question with an owner. Collapsing them loses the owner |
-
-Every unresolved to-be-confirmed MUST be filed through `wdi-question` before G3 opens — into
-`assumptions.md` by default, and into `blocking.md` only through the three tests that file states.
-
-## The boundary against solution shape
-
-Solution shape MUST NOT appear here. Concretely, the SRS MUST NOT name a framework, a database table, an
-HTTP endpoint, a class, a queue, or a file path. Robustness analysis belongs to the SDD, at `deep`.
-
-When writing behaviour surfaces a design decision that cannot wait, it goes to `wdi-decision` — not into
-this document as a parenthetical.
-
-The reverse also holds. When G4 or the build discovers behaviour nobody specified, it MUST come back here
-**before** the code that implements it; the change-control matrix in `delivery-flow-guide.md` says which
-artifacts move.
-
-## Passing the gate
-
-- At **G3**: the actor list, the UC catalogue, and the domain model complete for every component, and the
-  roll-up in `.control/generated/blueprint.md` regenerated. V1, V2, V6, and V15 green — V2 is the ★
-  question: every `FR` has at least one `UC`, unless it carries `no_uc:` with a stated reason.
-- At **G4**: whatever this component's `mode` requires, and nothing beyond it.
-- `wdi-review` MUST have run with the lens set `risk_accepted` names. The `reviewed:` trace is stamped only
-  on components at `risk_accepted` `low` or `medium` — V13.
-- A `UC` that exists but is wrong passes V2 and fails `wdi-reconcile`. Run it before the gate, not after.
+---
+status: Accepted
+---
+
+# SRS Guide
+
+**Loaded when:** writing, changing, or validating the SRS of a Product Component
+
+An SRS states how the system must **behave** for one Product Component. The PRD promised something to a
+user; this says what the system does so that promise holds. It MUST NOT say how the thing is built —
+that is `SDD-<pc>.md`.
+
+## Two skills write it, at two gates
+
+| Section | Written at | By |
+|---|---|---|
+| § Actor Register · § UC Catalogue | G3 Blueprint | `wdi-blueprint` intent `catalog` |
+| Everything below, per the component's `mode` | G4 Component | `wdi-component` intent `behaviour` |
+
+**The SRS therefore exists at `mode: catalog`.** It carries the actor list and the use case catalogue,
+because both are born at G3 and `mode` does not touch the blueprint. What does not exist at `catalog` is
+`04-usecases/UC-<n>-<slug>.md` — the step-by-step flow. Reading "no SRS at `catalog`" is wrong, and it
+was an artefact of an earlier table that showed only what varies.
+
+Depth is **read from `mode`**, never computed. Review lenses are **read from `risk_accepted`**, never from
+`mode`. Both fields are defined in `delivery-flow-guide.md` and MUST NOT be redefined here.
+
+## No BMad skill writes this
+
+`bmad-prd` writes the PRD, `bmad-architecture` writes the spine, `to-spec` writes the contract. Nothing in BMad
+writes an SRS. Three consequences follow, and each MUST be handled deliberately:
+
+| Consequence | What follows |
+|---|---|
+| No `doc_standards` can fire | `bmad-review` MUST be invoked through `wdi-review`, with the lens set `risk_accepted` names |
+| No memlog is created | A decision taken while writing MUST land as a `DEC-` through `wdi-decision`, not as a parenthetical |
+| No template enforcement | The shape comes from `templates/srs.md`, applied by `wdi-init` intent `component` at birth |
+
+`bmad-advanced-elicitation` and `bmad-party-mode` MAY be used as thinking aids. They produce no artifact
+and MUST NOT be treated as authors.
+
+## Home and life cycle
+
+- `.what/<pc>/SRS-<pc>.md`, with slots `02-rules/` · `03-domain/` · `04-usecases/` · `05-scenarios/`.
+- **Living, amended forever.** An SRS MUST NOT be versioned, frozen, or superseded. A component does not
+  stop existing because a release shipped.
+- `01-requirements/` and `supplements/` are **repealed**. The first was permanently empty — `FR` live in
+  the PRD and the SRS cites them. The second existed for `ANX-`, and that concept is gone.
+
+## Writing order
+
+Binding, and each step is the input to the next. The first four happen at G3, the rest at G4:
+
+1. **Glossary** — every domain noun this component uses, into `.control/product-glossary.md`. Never
+   defined inline here.
+2. **UC Catalogue** — one line per use case: `UC-N` · title · actor · the `FR` it satisfies · `critical`
+   yes/no.
+3. **Actor Register**.
+4. **Domain Model** — entities, relations, columns. A business rule binding a second component goes to
+   `.what/business-rules.md`.
+5. **UC Specification** — full flows, per `mode`.
+6. **Local business rules**, then **State Lifecycle**, then **branch scenarios** — per `mode`.
+
+Writing these out of order produces use cases whose nouns nobody defined. When the pass covers several
+components, the order binds **within** each one, not across them.
+
+## Which use cases get a full flow
+
+| `mode` | Full flows |
+|---|---|
+| `catalog` | none — the catalogue line is the whole record |
+| `outline` · `guarded` | the use cases the component exists for, **at most 3** |
+| `deep` | every `critical` use case |
+
+A use case is `critical` when it touches **money, personal data, or an irreversible action**. That is the
+whole definition; `delivery-flow-guide.md` owns it, including the one-third sanity check.
+
+## Use cases at two altitudes
+
+The same `UC-N` MAY appear twice in the corpus, and the two MUST NOT be merged or made to duplicate each
+other:
+
+| | Here, in the SRS | There, in the SDD at `deep` |
+|---|---|---|
+| Written for | Someone who uses the product | Someone who builds it |
+| Basic Flow | **At most eight steps** | As long as the design needs |
+| May name | Actors, screens the user sees, domain nouns | Classes, endpoints, tables, transports |
+| Answers | What happens | How it happens |
+
+The eight-step cap is not style. A flow needing more steps is either two use cases, or it has started
+describing implementation — and the cap makes that visible while it is still cheap to fix.
+
+Branches MUST go to `05-scenarios/` rather than making the UC file fat, and only at `deep`.
+
+## Actor Register is the SSOT
+
+It MUST stay in the SRS kernel, never moved to a slot. The SDD MUST NOT carry a copy of it — a mirror was
+once permitted with the rule "not edited on the SDD side", and nothing checked that rule. The rendered SDD
+shows the actors it needs from here. A `System` actor MAY be decomposed into the internal components that
+play it, but that decomposition belongs to the SDD, and it cites the actor, never restates it.
+
+## Business rules — two homes, one test
+
+| Rule | Home | Born at |
+|---|---|---|
+| Binds more than one Product Component | `.what/business-rules.md` | G3 |
+| Binds only this component | `.what/<pc>/02-rules/rules-<pc>.md` | G4, from `outline` up |
+
+The test is not importance, it is **reach**. A rule written in one component that turns out to bind a
+second MUST be promoted, not copied. Two copies of one rule is how components start disagreeing about the
+same policy.
+
+## Sections the shape requires
+
+`templates/srs.md` carries the full list. Four MUST NOT be dropped even when they feel thin, because each
+is the one that is silently skipped:
+
+| Section | Why it MUST stay |
+|---|---|
+| **Constraints** | Inherited from the spine's `AD-N` and from the PRD. A constraint discovered at G4 costs a decision |
+| **Non-Goals** | What this component explicitly does not do. Absent, it will be assumed to do it |
+| **Prerequisite** | What MUST already exist before this component can behave as described |
+| **Assumptions, Risks, and To Be Confirmed** | Three separate lists. An assumption is something we decided to believe; a risk may go wrong; a to-be-confirmed is a question with an owner. Collapsing them loses the owner |
+
+Every unresolved to-be-confirmed MUST be filed through `wdi-question` before G3 opens — into
+`assumptions.md` by default, and into `blocking.md` only through the three tests that file states.
+
+## The boundary against solution shape
+
+Solution shape MUST NOT appear here. Concretely, the SRS MUST NOT name a framework, a database table, an
+HTTP endpoint, a class, a queue, or a file path. Robustness analysis belongs to the SDD, at `deep`.
+
+When writing behaviour surfaces a design decision that cannot wait, it goes to `wdi-decision` — not into
+this document as a parenthetical.
+
+The reverse also holds. When G4 or the build discovers behaviour nobody specified, it MUST come back here
+**before** the code that implements it; the change-control matrix in `delivery-flow-guide.md` says which
+artifacts move.
+
+## Passing the gate
+
+- At **G3**: the actor list, the UC catalogue, and the domain model complete for every component, and the
+  roll-up in `.how-rendered/blueprint.md` regenerated. `goal-has-fr`, `fr-has-uc`, `refs-resolve`, and `chain-links` green — `fr-has-uc` is the ★
+  question: every `FR` has at least one `UC`, unless it carries `no_uc:` with a stated reason.
+- At **G4**: whatever this component's `mode` requires, and nothing beyond it.
+- `wdi-review` MUST have run with the lens set `risk_accepted` names for a **first** review or a review
+  opening this gate; a later re-review runs the lighter set, and `wdi-review` owns when. The `reviewed:`
+  trace is stamped only on components at `risk_accepted` `low` or `medium` — `review-trace`, where absence fails and
+  staleness is advisory between gates.
+- A `UC` that exists but is wrong passes `fr-has-uc` and fails `wdi-reconcile`. Run it before the gate, not after.

package/kit/.constitution/method/document/templates/addendum.md

@@ -1,71 +1,70 @@
----
-type: addendum
-parent: '{brief | prd}'  # which document this sits beside
-initiative: '{slug}'     # omit when parent: brief
-status: draft            # draft · reviewed · locked · superseded
-created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
----
-
-# Addendum — {product brief | PRD: initiative}
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     Two homes, one shape:
-       .what/_product-brief/addendum.md          beside the brief, born at G1
-       .what/_prd/<initiative>/addendum.md       beside a PRD, born at G2
-
-     Both already existed in this corpus and both were born without a template, which is why the one
-     rule that governs them lived only in prd-guide.md prose.
-
-     THAT RULE, STATED WHERE IT BELONGS: an addendum is NOT a change log. Revision History in the
-     parent document is the change log. This holds depth that earned its place but does not fit the
-     narrative — and putting a change record here means the client-facing document stops carrying its
-     own history.
-
-     WHAT GOES HERE: rejected-alternative rationale · options matrices · mechanism and transport
-     thinking · technical how · in-depth personas · sizing data · anything the owner volunteered that
-     would derail the narrative.
-
-     WHAT MUST NOT: audit and override information — that is the memlog. A commercial fact — that is
-     refused outright, per repo-guide.md. A promise — a promise stated only here is a promise nobody
-     approved, because the gate reads the parent document.
-
-     CAPTURED DURING THE CONVERSATION, not swept here at Finalize. Content moved here at the end is
-     content nobody will find, because the reader was already told the parent was complete.
-
-     WHAT BINDS LATER MOVES OUT. Something in here that turns out to bind a downstream document MUST
-     be written into that document by the skill owning its layer, rather than cited from here forever.
-     A citation into an addendum is a dependency on a file that was explicitly not gated. -->
-
-## Rejected alternatives
-
-<!-- One per subsection or one row each, and each MUST say why it lost. "We considered X" with no
-     reason preserves nothing — the reason is the part memory loses first, and it is why the same
-     option gets proposed again next quarter.
-
-     A rejection that is expensive to revisit is a DEC-, not a row here. -->
-
-| Option | Why it lost |
-| --- | --- |
-
-## Options weighed
-
-<!-- Matrices, comparisons, and scoring that would swamp the parent document. State the criteria
-     before the scores; a matrix whose criteria appeared after the winner is a justification. -->
-
-## Mechanism and transport
-
-<!-- Technical thinking that surfaced while deciding a promise. It is not a design — the SDD owns
-     that — and it MUST NOT be cited as one. If a builder would be right to follow it, it belongs in
-     .how/ and it has to get there through the skill that owns the layer. -->
-
-## Sizing
-
-<!-- Numbers behind an estimate: counts, throughput assumptions, mandays reasoning. Each MUST name
-     where the figure came from. An unsourced number here reappears as a commitment somewhere else. -->
-
-## Personas and research detail
-
-<!-- Depth beyond what the parent needs. Raw research output MUST NOT be folded in — it stays in
-     _bmad-output/ and is cited by path, which is stable because that folder is committed. -->
+---
+type: addendum
+parent: '{brief | prd}'  # which document this sits beside
+initiative: '{slug}'     # omit when parent: brief
+status: draft            # draft · reviewed · locked · superseded
+created: '{YYYY-MM-DD}'
+---
+
+# Addendum — {product brief | PRD: initiative}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     Two homes, one shape:
+       .what/_product-brief/addendum.md          beside the brief, born at G1
+       .what/_prd/<initiative>/addendum.md       beside a PRD, born at G2
+
+     Both already existed in this corpus and both were born without a template, which is why the one
+     rule that governs them lived only in prd-guide.md prose.
+
+     THAT RULE, STATED WHERE IT BELONGS: an addendum is NOT a change log. Revision History in the
+     parent document is the change log. This holds depth that earned its place but does not fit the
+     narrative — and putting a change record here means the client-facing document stops carrying its
+     own history.
+
+     WHAT GOES HERE: rejected-alternative rationale · options matrices · mechanism and transport
+     thinking · technical how · in-depth personas · sizing data · anything the owner volunteered that
+     would derail the narrative.
+
+     WHAT MUST NOT: audit and override information — that is the memlog. A commercial fact — that is
+     refused outright, per repo-guide.md. A promise — a promise stated only here is a promise nobody
+     approved, because the gate reads the parent document.
+
+     CAPTURED DURING THE CONVERSATION, not swept here at Finalize. Content moved here at the end is
+     content nobody will find, because the reader was already told the parent was complete.
+
+     WHAT BINDS LATER MOVES OUT. Something in here that turns out to bind a downstream document MUST
+     be written into that document by the skill owning its layer, rather than cited from here forever.
+     A citation into an addendum is a dependency on a file that was explicitly not gated. -->
+
+## Rejected alternatives
+
+<!-- One per subsection or one row each, and each MUST say why it lost. "We considered X" with no
+     reason preserves nothing — the reason is the part memory loses first, and it is why the same
+     option gets proposed again next quarter.
+
+     A rejection that is expensive to revisit is a DEC-, not a row here. -->
+
+| Option | Why it lost |
+| --- | --- |
+
+## Options weighed
+
+<!-- Matrices, comparisons, and scoring that would swamp the parent document. State the criteria
+     before the scores; a matrix whose criteria appeared after the winner is a justification. -->
+
+## Mechanism and transport
+
+<!-- Technical thinking that surfaced while deciding a promise. It is not a design — the SDD owns
+     that — and it MUST NOT be cited as one. If a builder would be right to follow it, it belongs in
+     .how/ and it has to get there through the skill that owns the layer. -->
+
+## Sizing
+
+<!-- Numbers behind an estimate: counts, throughput assumptions, mandays reasoning. Each MUST name
+     where the figure came from. An unsourced number here reappears as a commitment somewhere else. -->
+
+## Personas and research detail
+
+<!-- Depth beyond what the parent needs. Raw research output MUST NOT be folded in — it stays in
+     _bmad-output/ and is cited by path, which is stable because that folder is committed. -->

package/kit/.constitution/method/document/templates/architecture-spine.md

@@ -3,18 +3,20 @@ name: '{name}'
 type: architecture-spine
 purpose: build-substrate    # build-substrate (default) · discussion · report · deck
 altitude: feature           # initiative (keeps features) · feature (keeps epics) · epic (keeps stories)
+                            # bmad-architecture's OWN vocabulary — not this method's `spec`/`ticket`, and not ours to rename
 paradigm: '{named design pattern, e.g. hexagonal, layered, pipes-and-filters, actor}'
 scope: '{what this spine governs}'
 status: draft               # draft · final
 created: '{date}'
-updated: '{date}'
 binds: []                   # capability / unit IDs governed (from the driving spec; at epic altitude, also the inherited parent AD ids)
 sources: []
 companions: []
-reviewed:                # V13. Filled only after wdi-review has actually run
+reviewed:                # `review-trace`. Filled only after wdi-review has actually run
   date: ''               # '{YYYY-MM-DD}'
   sha: ''                # commit it was reviewed at; without the SHA, staleness cannot be measured
-  lenses: []             # structure · prose · edge-case-hunter · adversarial · verification-gap
+  lenses: []             # what ACTUALLY ran at this sha: structure · prose · edge-case-hunter ·
+                         # adversarial · verification-gap. Heavy lenses belong to a first or
+                         # gate-opening review; a re-review runs the lighter set over the delta
 ---
 
 # Architecture Spine — {name}
@@ -95,6 +97,6 @@ reviewed:                # V13. Filled only after wdi-review has actually run
 - **`AD-N` versus `DEC-NNN`.** An `AD-N` here is a living rule, edited in place. A `DEC-NNN` in
   `.control/decisions/` is one decision event, never edited and replaced by a `superseded` pointer.
   The two MUST NOT be interchanged.
-- **Ordering.** The spine is authored before `bmad-spec` runs, and `bmad-spec` adopts it as a
+- **Ordering.** The spine is authored before the contract is cut, and the contract adopts it as a
   companion — never the reverse.
 - **Memlog.** Written to `.control/memlog/spine.md` via `--path`.