wdi-method 0.3.0

package/kit/.constitution/document/sdd-guide.md

@@ -0,0 +1,206 @@
+---
+status: Accepted
+---
+
+# SDD Guide
+
+**Loaded when:** writing, changing, or validating the SDD of a Product Component
+
+An SDD states how one Product Component is **built**. `SRS-<pc>.md` fixed the behaviour; this decides the
+shape that delivers it, and MUST NOT introduce behaviour — a promise appearing here first is a promise
+nobody agreed to.
+
+## Which sections exist, and when
+
+Every section names the **minimum `mode` that demands it**. Below that minimum it MUST NOT be written to
+fill a slot; above it, it is required.
+
+| Section | Minimum `mode` |
+|---|---|
+| § Decision Summary — what this component is built as, and the one or two most expensive choices reversed | `outline` |
+| § Structure — the `LC` list and the direction of their dependencies | `outline` |
+| § Inherited Constraints — every `AD-N` binding this component, **quoted** | `guarded` |
+| § Failure Behaviour — per boundary | `guarded` |
+| `03-integrations/<name>.md` | `guarded`, when the component has one |
+| § Robustness Analysis — ABCE | `deep` |
+| `02-contracts/` · `04-components/` · `05-model/data-model.md` · `06-flows/` | `deep` |
+| `01-ux/<screen>.md` | `deep`, or earlier through `wdi-ux` |
+
+At `mode: catalog` the SDD is a **skeleton** — frontmatter and headings, born from `templates/sdd.md` by
+`wdi-init` intent `component`. That is a finished state, not an unfinished one: G4 is skipped there, and the
+code is written from the blueprint.
+
+Review lenses are read from `risk_accepted`, never from `mode`. Both fields are defined in
+`delivery-flow-guide.md`.
+
+## No BMad skill writes this either
+
+The same three consequences as the SRS apply — no `doc_standards` fires, no memlog is created, no template
+enforces itself — and they are stated in `srs-guide.md` rather than repeated. `bmad-architecture` writes the
+**spine**, not this.
+
+## Home and life cycle
+
+- `.how/<pc>/SDD-<pc>.md`, with slots `01-ux/` … `06-flows/`.
+- Living and amended, exactly like its SRS. It MUST NOT be versioned or frozen.
+- The slot numbers are an **ABCE classification**, not a reading order — `corpus-guide.md` owns that rule.
+- `supplements/` is **repealed** along with the `ANX-` concept it existed for.
+
+## Inherited constraints
+
+From `guarded` up, every `AD-N` in `ARCHITECTURE-SPINE.md` that reaches this component MUST be listed under
+**Inherited Constraints**, quoted rather than paraphrased — a paraphrase drifts, and the drift is invisible
+because both texts read reasonably.
+
+A design that must deviate does not argue here. It goes through `wdi-decision`, and either the spine changes
+or the design does. An SDD contradicting an `AD-N` in prose is the failure the spine exists to prevent.
+
+## Failure Behaviour — it stands on its own
+
+**`Failure Behaviour` does not need ABCE**, and this is the change that makes `guarded` worth having. The
+boundary list already exists: `.how/_platform/inventory-api.md` names the endpoints and
+`inventory-screen.md` names the screens, each with an owning-component column. Nothing has to be derived
+again.
+
+For each boundary, state what happens when the thing on the other side is slow, absent, or lying: timeout,
+retry policy, what the user sees, what gets logged. "Returns an error" is not an answer.
+
+When a failure mode turns out to be a promise — a refund path, a partial save — it becomes a scenario on the
+`.what` side, and it MUST go to the SRS first.
+
+## Object identification — the ABCE pass, at `deep` only
+
+This is the Robustness Analysis. It MUST NOT have appeared in the SRS, and at `outline` and `guarded` it MUST
+NOT be written at all.
+
+| Class | What it is | Slot |
+|---|---|---|
+| **Boundary** | Where the component meets something outside it — screens, endpoints, adapters, file drops | `01-ux/` · `02-contracts/` · `03-integrations/` |
+| **Control** | What coordinates a use case from start to finish | `04-components/` |
+| **Entity** | The things that persist, and their shape | `05-model/` |
+| Behaviour | How the three move together, per use case | `06-flows/` |
+
+From `guarded` up, every Boundary object MUST correspond to an `LC` in `.control/registry/components.yaml`;
+at `deep`, Control objects too. Registration is checked **when the wave closes** — V12 — not before a story
+is `ready-for-dev`.
+
+Flows **into and out of** each boundary MUST be stated, not just the boundary. A boundary listed without its
+direction of call is a name, not a design.
+
+Flow diagrams in `06-flows/` are written only for a flow touching money, irreversible state, or a third
+party. The lane order is the project's to fix, once, in `codebase/conventions-guide.md`. **The `No-op` lane
+rule is repealed** — it was a heavy convention for a folder that had never carried a file, and it belongs to
+how a diagram is drawn rather than to what binds.
+
+## The three inventories are derived, not authored
+
+`.how/_platform/inventory-db.md`, `inventory-api.md`, and `inventory-screen.md` belong to `wdi-blueprint`,
+and they are born at G3. This document MUST NOT keep a second copy of any of them.
+
+| State | How the inventory comes to exist |
+|---|---|
+| No code yet | Written as a **plan** by `wdi-blueprint` intent `platform`. Nothing can be derived, because there is no source |
+| Code exists | **Derived** from the code first — migrations for tables, route registration for endpoints, pages for screens — then compared with the plan. The difference is a finding, not hand work |
+
+`.control/generated/` and `inventory.py` own the refresh. A discrepancy between plan and reality surfaces as
+a validator finding; it MUST NOT become hand work that someone can forget.
+
+`02-contracts/00-inventory.md` at `deep` is a different thing: the endpoints **this component** owns, with
+numbers stable enough to carry into filenames. A new endpoint takes the next number, never a renumber —
+renumbering renames every file after it and breaks every link.
+
+## Contracts and data model — `deep` only
+
+| Artifact | Where | Rule |
+|---|---|---|
+| API contract per endpoint | `02-contracts/` | One file per endpoint or per resource, never one for the whole surface |
+| External integration | `03-integrations/` | MUST name the owner outside the team, and what happens when they change it. Required from `guarded` |
+| Data model | `05-model/` | Diagram **and** a data dictionary — a diagram alone does not say what a column means |
+
+### The five lanes every contract answers
+
+Each contract spec MUST answer all five, and MUST say so explicitly when one does not apply:
+
+| Lane | States |
+|---|---|
+| Authentication | Who may call it, and what happens when they may not |
+| Validation | What is rejected before any work happens |
+| Error handling | Which failures are expected and which are exceptional |
+| **Rate limiting** | The limit, or `none` with a reason |
+| **Idempotency** | Whether a repeated call is safe, and what makes it so |
+
+The last two are the ones always skipped, and the two that hurt in production. `none` is an acceptable
+answer; silence is not — silence reads as "not considered".
+
+**One error envelope, referenced not repeated.** Its shape is defined once in
+`.how/_platform/cross-cutting.md`. Every contract MUST reference it rather than restate it, and MUST
+document 4xx and 5xx in that envelope — that is how a system ends up with four different error formats, each
+of which looked reasonable on its own page.
+
+## Evidence discipline
+
+Every technical claim about code that already exists MUST be traceable to something in the repository — a
+source file, a config, a schema, a manifest. Naming the file is the trace; "the service handles retries"
+without one is not design, it is rumour.
+
+This is not only a brownfield rule. **Raising a component's `mode` after its code runs** produces an
+as-built record, and the labels are mandatory there for the same reason.
+
+| Label | Meaning |
+|---|---|
+| `[ASSUMED]` | We decided to believe it; nothing was read that confirms it |
+| `[PARTIAL]` | Verified for part of the surface, not all of it |
+| `[NEEDS CONFIRMATION]` | A question with an owner, filed through `wdi-question` |
+| `[MISSING]` | **Checked, and the thing described is not there** |
+
+An unlabelled claim is read as verified. That is why the labels are mandatory and not a courtesy.
+
+### Status is raised, never assumed
+
+- A claim is raised to verified only after the evidence it names has actually been read. Reading the
+  controller does not verify the repository.
+- The raise MUST record **what was read**. "Verified against `src/internal/referral/pool.go` and its
+  integration test" is a raise; "verified" is not.
+- `[PARTIAL]` MUST state what is **not** covered. A partial that only says "partial" is an unlabelled claim
+  wearing a label.
+- A claim MUST NOT be raised because it has survived several readings. Familiarity is not evidence.
+
+### `[MISSING]` — negative knowledge, and why it MUST NOT be deleted
+
+The first three labels state a degree of **not knowing**; this one states the opposite — it was checked, and
+it is not there. `[ASSUMED]` means nobody looked.
+
+The instinct is to delete the sentence, and that MUST NOT be done. Deleting it throws away the fact that
+somebody once believed the thing existed, and that belief came from somewhere: a cancelled plan, a rename
+the document never followed, a feature removed without a trace.
+
+Each MUST be resolved into exactly one of three, with the disposition recorded beside it:
+
+| If | Then |
+|---|---|
+| The code should have it | A `BUG-` in `defects.yaml`, with `root_cause` set and `violates` naming what it breaks |
+| The document was wrong | Correct the claim, and say in the same pass what it used to assert |
+| It is real but not built yet | A planned line with an owner — a `CAP` or an `FR`, never a bare note |
+
+An unresolved `[MISSING]` MUST NOT pass G4.
+
+## The boundary against promising
+
+If a sentence here would surprise the Product Owner who approved the PRD, it is a promise and MUST travel
+back — PRD or SRS first, this document second. A technology choice a second component will have to follow
+belongs to the spine, as an `AD-N` through `wdi-decision`.
+
+## Passing G4
+
+Only what this component's `mode` demands, and nothing beyond it:
+
+- From `outline`: Decision Summary and the `LC` list present.
+- From `guarded`: Inherited Constraints complete, quoted, and contradicted nowhere in the document; Failure
+  Behaviour present for **every** boundary named in the API and screen inventories.
+- At `deep`: Robustness Analysis done; every `critical` use case mirrored at the technical altitude under
+  the same ids; contract specs answering all five lanes; the data dictionary present.
+- Always: unresolved `[NEEDS CONFIRMATION]` filed through `wdi-question`, no unresolved `[MISSING]`, and
+  `wdi-review` run with the lens set `risk_accepted` names.
+
+The spine comes first and `bmad-spec` comes last. An SDD written before the spine will be rewritten; a SPEC
+written before the SDD has nothing to project.

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

@@ -0,0 +1,147 @@
+---
+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.

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

@@ -0,0 +1,71 @@
+---
+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. -->

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

@@ -0,0 +1,100 @@
+---
+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)
+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. Diisi hanya setelah bmad-review benar-benar dijalankan
+  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
+---
+
+# Architecture Spine — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them; never emit a comment in the finished spine. This is a shape, not a script: keep only the sections this spine needs and cut the rest (no empty headers). A small intent may be just paradigm + a few ADs + conventions; a platform earns more. An inherited epic spine is usually mostly Inherited Invariants + a thin Deferred. Decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams; prose only where it must. -->
+
+## Design Paradigm
+
+<!-- Name the pattern (a known one loads a whole model for free) and map its layers to namespaces/directories. The smallest, most durable thing here. -->
+
+## Inherited Invariants
+
+<!-- Only when this spine inherits a higher-altitude parent. The parent's ADs/conventions/paradigm that bind here, by their ORIGINAL ids — read-only, never renumbered, not re-derived. A local decision that contradicts one is a conflict to surface, not an override. Cut this section otherwise. -->
+
+| Inherited | From parent | Binds here |
+| --- | --- | --- |
+| {AD-id / convention} | {parent spine} | {what it constrains in this scope} |
+
+## Invariants & Rules
+
+<!-- The durable heart: calls a future builder can't read off compliant code. One block per decision: stable ascending id (never reused/renumbered), Binds, Prevents (the divergence), Rule (enforceable). Tag [ADOPTED] when the user or existing reality settled it. Include a dependency-direction diagram (who may depend on whom) — it IS a rule; author it as valid mermaid, never an empty graph. -->
+
+### AD-1 — {decision}
+
+- **Binds:** {capability / unit ids / fr/nfr's, areas, or `all`}
+- **Prevents:** {the divergence this stops}
+- **Rule:** {the constraint downstream must follow}
+
+## Consistency Conventions
+
+<!-- Defaults that bind where independent builders would drift. Cut rows that don't apply; add rows the project needs. -->
+
+| Concern | Convention |
+| --- | --- |
+| Naming (entities, files, interfaces, events) | |
+| Data & formats (ids, dates, error shapes, envelopes) | |
+| State & cross-cutting (mutation, errors, logging, config, auth) | |
+
+## Stack
+
+<!-- SEED — verified current at authoring; the code owns this once it exists. Name + version only; the why lives in the memlog. One row per language, framework, key dependency, platform, or chain that's pinned. -->
+
+| Name | Version |
+| --- | --- |
+| {language / framework / key dep / platform / chain} | {pinned version} |
+
+## Structural Seed
+
+<!-- The shapes worth fixing at cold-start — not a fixed list. Include only what's non-obvious at this altitude, and use as many diagrams as convey it, each as VALID mermaid (never a placeholder or empty graph). Candidates: system/container/context view; DEPLOYMENT & ENVIRONMENTS and external provider/infra topology (cover the operational envelope here when this altitude owns it — don't let it fall through); core-entity ERD (names + relationships only; an attribute that's itself an invariant is an AD, not a diagram); a minimal source tree. The code owns the detail — this is scaffold, not a mirror to maintain. -->
+
+```text
+{root}/
+  {dir}/   # {what lives here}
+```
+
+## Capability → Architecture Map
+
+<!-- Present when a spec drove this run. Bridges the spec's capabilities to where they live + what governs them; the consistency auditor's checklist. Cut otherwise. -->
+
+| Capability / Area | Lives in | Governed by |
+| --- | --- | --- |
+| {CAP-id / area} | {component / module} | {AD-id, convention, paradigm} |
+
+## Deferred
+
+<!-- Decisions intentionally pushed down, each with the reason it can wait — including whole dimensions this altitude doesn't own yet. The half of the contract that keeps the spine lean. -->
+
+---
+
+## Project overrides — WDI
+
+- **Altitude.** This project authors the `initiative` spine only, at `.how/_platform/architecture/`.
+  Component-level design belongs to `SDD-<pc>.md`, written by `wdi-component`, not to a `feature`
+  spine.
+- **This is not an HLD.** The spine constrains; it does not describe. What the system consists of
+  belongs to `c4-l1-system-context.md` and `c4-l2-containers.md`. Deployment topology has no home
+  in this corpus at all — it lives in the devops repository and is referenced from C4 L2.
+- **`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
+  companion — never the reverse.
+- **Memlog.** Written to `.control/memlog/spine.md` via `--path`.

package/kit/.constitution/document/templates/brief.md

@@ -0,0 +1,110 @@
+# Product Brief Template
+
+A flexible starting structure for the executive product brief. Adapt aggressively to the product, the purpose, and the domain. Drop sections that do not earn their place, add sections the product needs, reorder freely. The brief serves the product's story, not the template's shape.
+
+## Default Structure
+
+```markdown
+# Product Brief: {Product Name}
+
+## Executive Summary
+
+[2-3 paragraph narrative: what this is, what problem it solves, why it matters, why now. Compelling enough to stand alone — if someone reads only this section, they should understand the vision.]
+
+## The Problem
+
+[What pain exists, who feels it, how they cope today, the cost of the status quo. Be specific: real scenarios, real frustrations, real consequences.]
+
+## The Solution
+
+[What is being built, how it solves the problem. Focus on the experience and the outcome, not the implementation.]
+
+## What Makes This Different
+
+[Key differentiators. Why this approach over alternatives, what is the unfair advantage. Be honest. If the moat is execution speed, say so. Do not fabricate technical moats.]
+
+## Who This Serves
+
+[Primary users — vivid but brief. Who they are, what they need, what success looks like for them. Secondary users if relevant.]
+
+| Role | Need | Tier |
+|---|---|---|
+| {role} | {what they need from this product} | **primary** |
+| {role} | {…} | secondary |
+| {role} | {…} | secondary |
+
+[Exactly one row MUST be `primary`. Every user and stakeholder who touches the product belongs in this table — including the ones who never open it, but pay for it, approve it, or are accountable for it. Shared goals that cut across roles go in a line under the table.]
+
+## Goals
+
+[What the product is trying to achieve, one line each. Number them `BG-1`, `BG-2`, … — `BG` is the first link of the traceability chain `BG → CAP → FR/NFR → UC → DEC → Story → Test`, so these IDs are cited downstream and MUST stay stable once written.]
+
+- **BG-1** — core value: [the goal that justifies the product existing at all]
+- **BG-2**: [...]
+
+[MUST NOT be numbered `G1`, `G2` — `G1`–`G5` already name the five gates.]
+
+## Success Criteria
+
+[How we know this is working. Mix of user success signals and business objectives. Measurable.]
+
+## Scope
+
+[Boundary document, not a feature list. Keep both lists tight.]
+
+### Scope In
+
+[What is in for the first version.]
+
+### Scope Out
+
+[What is explicitly out, written as items. MUST NOT be left to be inferred from absence — the value of this list is that it names what someone will otherwise assume is coming. Per-release MVP scope belongs in the PRD; this is the product boundary.]
+
+## Constraints
+
+[What is fixed before design starts and cannot be traded away: platform scope, integration boundary, regulatory limit, milestone boundary, a timeline that is genuinely immovable. One line each, and each MUST say what it forbids.]
+
+[Technical constraints that only shape implementation belong in `addendum.md`, not here. A constraint that emerges from a design decision becomes `AD-N` in the architecture spine — MUST NOT be appended to this list later.]
+
+## Assumptions
+
+[What is believed true but not verified, and that the brief would be wrong without. State each so it could be proven false.]
+
+[An assumption that starts to wobble MUST be promoted to a row in `.control/registry/risks.yaml` with an owner. An assumption nobody would act differently about is not worth listing.]
+
+## Prerequisites
+
+[What MUST exist or be granted before work can start: access, accounts, data, an upstream system, a decision someone else owns.]
+
+[Any prerequisite not yet satisfied MUST have a matching row in `.control/questions/external.md` naming who is being waited on and by when.]
+
+## Vision
+
+[Where this goes if it succeeds. What it becomes in 2-3 years. Inspiring but grounded.]
+```
+
+---
+
+## Project overrides — WDI
+
+- **Home.** `.what/_product-brief/brief.md`, with `addendum.md` beside it. Set through
+  `run_folder_pattern = "_product-brief"`; both filenames are fixed by the skill and MUST NOT be
+  expected to change.
+- **Singleton.** One brief per product, spanning every release. A second product MUST get its own
+  repository rather than a second brief.
+- **Decision Summary.** MUST name exactly one problem, one **primary** user, and one measure of
+  success. Secondary users and stakeholders are listed, not ranked away. If the primary cannot be
+  chosen, the discovery is not finished.
+- **Six sections above the BMad default.** `Who This Serves` carries a full stakeholder table;
+  `Scope` is split into In and Out; and `Goals`, `Constraints`, `Assumptions`, and `Prerequisites`
+  are added. The last three have no home anywhere else in the corpus.
+- **No Product Component list.** The slicing is born at the tail of G2 through `wdi-init` intent
+  `component`, which reads
+  the brief and every PRD once a domain model exists. A list guessed at G1 is a guess made before
+  there is anything to guess from.
+- **Raw material stays out.** Research, brainstorming, and pressure-test output live in
+  `_bmad-output/` and stay there. It MUST NOT be folded in, and MUST NOT be promoted into `.what/` —
+  a `DEC-` or the PRD cites it by path instead.
+- **Dying cheap is a pass.** A brief that concludes the idea is not worth building is a valid G1
+  outcome, and the most profitable one.
+- **Memlog.** Written to `.control/memlog/brief.md` via `--path`.