wdi-method 0.3.0

package/kit/.constitution/document/bmad-skill-register.md

@@ -0,0 +1,71 @@
+---
+status: Accepted
+---
+
+# BMad Skill Register
+
+**Loaded when:** deciding which BMad skill a piece of work needs, or checking what one writes
+
+This used to be the full catalogue of all 59 installed BMad skills. **That catalogue is retired.** It was a
+copy of somebody else's inventory, it went stale on every BMad update, and nothing in this method read more
+than a dozen of its rows. What binds is the division of labour below; for anything about a BMad skill this
+method does not invoke, ask `bmad-help`, which reads BMad's own documentation.
+
+## Who writes what
+
+| Artifact | Written by | Wrapped in |
+|---|---|---|
+| Product brief | `bmad-product-brief` | `wdi-problem` |
+| PRD | `bmad-prd` | `wdi-product` |
+| UX — `EXPERIENCE.md` + `DESIGN.md` | `bmad-ux` | `wdi-ux` |
+| Architecture spine + the C4 set | `bmad-architecture` | `wdi-blueprint` intent `platform` |
+| **UC catalogue · actors · entities · business rules** | **nothing in BMad** | `wdi-blueprint` writes it itself |
+| **SRS and all of `.what/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
+| **SDD and all of `.how/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
+| `SPEC.md` + `stories.yaml` | `bmad-spec` | `wdi-build` |
+| Code | `bmad-build` · `bmad-build-auto` | `wdi-build` |
+| Retrospective | `bmad-retrospective` | `wdi-build` |
+| Document review | `bmad-review` | `wdi-review` |
+| Course correction | `bmad-correct-course` | `wdi-decision` |
+
+**The three bold rows are why this method exists.** BMad stops at the promise and starts again at the
+mechanism, and every behaviour in between had no author. Three consequences attach to those artifacts and
+MUST be handled deliberately rather than discovered: no `doc_standards` fires a review, no memlog is born on
+its own, and no template enforces itself.
+
+## No BMad skill is invoked directly
+
+Every one above has a wrapper, and the wrapper is what checks position, verifies the result against the
+guide, and lands the memlog. Routing past it produces an artifact nothing verifies.
+
+**One exception, and it is narrow:** `bmad-build` MAY be invoked directly on the Fast Path. A Fast Path that
+turns out to touch an `FR` MUST stop and become a wave `S`, which puts it back inside `wdi-build`.
+
+## What is available but writes nothing
+
+| Skill | Use |
+|---|---|
+| `bmad-advanced-elicitation` · `bmad-party-mode` | Thinking aids. They produce no artifact and MUST NOT be treated as authors |
+| `bmad-deep-recon` | Research, before a brief rests on outside data. Its output stays in `_bmad-output/` permanently and MUST NOT be folded into the brief |
+| `bmad-code-review` | The two-reviewer panel over code, dispatched by `wdi-build`. Not for documents |
+| `bmad-help` | Questions about BMad itself. It MUST NOT be used to answer "where am I" — that is `wdi-help` |
+
+## What is NOT USED, and MUST NOT be
+
+| Skill | Why |
+|---|---|
+| `bmad-create-epics-and-stories` · `bmad-sprint-planning` · `bmad-sprint-status` | They belong to the sprint route, which keeps status in a hand-edited file. This method reads status from story-file frontmatter — `bmad-guide.md` owns the reasoning |
+| `bmad-create-story` · `bmad-dev-story` · `bmad-quick-dev` · `bmad-dev-auto` | Deprecated in BMad itself; `bmad-build` and `bmad-build-auto` replace them |
+| `bmad-editorial-review*` · `bmad-review-*` | Shims onto `bmad-review` lenses. Ask for the lens, not the shim |
+| `bmad-document-project` · `bmad-generate-project-context` | Forward to `bmad-project-context`. This repo's agent instructions are maintained by hand |
+| Any skill named as a **gate condition** | A gate is passed by its checklist and its validators, never by a skill having run |
+
+## The class that decides where output lands
+
+`bmad-guide.md` owns the class definitions; what matters here is that **class B** exists because some skills
+write several things at once that belong to different layers. `bmad-ux` is the case: `EXPERIENCE.md` is a
+promise and `DESIGN.md` is a build detail, and no configuration can send them to two places. Its output
+lands in a neutral folder first, and `wdi-ux` places it.
+
+Which skill lands which output is the ownership table in `corpus-guide.md`, and it MUST NOT be duplicated
+here.

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

@@ -0,0 +1,94 @@
+---
+status: Accepted
+---
+
+# Brief Guide
+
+**Loaded when:** writing, updating, or validating the product brief
+
+The brief is the G1 artifact. It answers WHY — what problem exists, whose it is, and why it is worth
+building. Its shape lives in `templates/brief.md`; the rules that shape MUST obey live here.
+
+## Home and life cycle
+
+- The brief MUST live at `.what/_product-brief/brief.md`, with `addendum.md` beside it. Both
+  filenames are fixed by `bmad-product-brief` and MUST NOT be expected to change; only the folder is
+  configurable.
+- One brief per product, spanning every release. A second product MUST get its own repository — the
+  singleton is what makes "what did we set out to solve" answerable at all.
+- The brief is amended, never re-run into a second folder. `run_folder_pattern` is a constant for
+  exactly this reason.
+- The memlog MUST be written to `.control/memlog/brief.md` via `memlog.py --path`. `--workspace`
+  MUST NOT be used — it would drop a `.memlog.md` inside `.what/`, and no memlog belongs in the
+  corpus.
+
+## Required sections
+
+`templates/brief.md` carries the shape. Its preamble invites dropping sections that do not earn
+their place; that invitation MUST NOT be applied to the eight below. Everything else in the template
+MAY be dropped.
+
+| Section | Why it cannot be dropped |
+|---|---|
+| The Problem | The gate decides on this. Without it there is nothing to approve |
+| Who This Serves | Names who the problem belongs to |
+| Goals | `BG-N` is the first link of the traceability chain; without it the chain has no root |
+| Success Criteria | The measure that makes "done" checkable |
+| Scope In / Scope Out | The boundary the PRD is later held against |
+| Constraints | What design MUST NOT trade away |
+| Assumptions | What the brief would be wrong without |
+| Prerequisites | What blocks work before it starts |
+
+## Decision rules
+
+- The brief MUST name exactly one problem, one **primary** user, and one measure of success. Other
+  users and stakeholders are listed as secondary, not ranked away. If the primary cannot be chosen,
+  discovery is not finished and the gate MUST NOT open.
+- Every user and stakeholder who touches the product MUST appear in the table, including those who
+  never open it — whoever pays for it, approves it, or is accountable for it.
+- Goals MUST be numbered `BG-1`, `BG-2`, … and MUST NOT be numbered `G1`, `G2` — `G1`–`G5` name the
+  five gates. `BG` IDs are cited downstream and MUST stay stable once written.
+- Scope Out MUST be written as items. Leaving it to be inferred from absence defeats its only
+  purpose, which is naming what someone will otherwise assume is coming.
+- Per-release MVP scope belongs to the PRD, not here. This section states the product boundary.
+
+## The three product-level sections
+
+BMad has no home for these; they exist because of that gap, and each has a rule about where it goes
+when it stops being a statement.
+
+| Section | Boundary | When it moves |
+|---|---|---|
+| Constraints | What is fixed before design starts. Technical constraints that only shape implementation belong in `addendum.md` | A constraint that emerges from a design decision becomes `AD-N` in the spine and MUST NOT be appended here later |
+| Assumptions | What is believed but unverified, stated so it could be proven false | An assumption that starts to wobble MUST become a row in `.control/registry/risks.yaml` with an owner |
+| Prerequisites | What MUST exist or be granted before work can start | Any prerequisite not yet satisfied MUST have a row in `.control/questions/external.md` naming who is being waited on and by when |
+
+An assumption nobody would act differently about is not worth listing.
+
+## No Product Component list
+
+The brief MUST NOT carry one, and MUST NOT fill `product_components`. The slicing is born at the
+**tail of G2** through `wdi-init` intent `component`, which reads the brief and every PRD and
+registers what the owner accepts. A list written at G1 is guessed before there is anything to guess
+from, and every later gate inherits the guess.
+
+## Raw material
+
+- Research, brainstorming, forge, and PRFAQ output MUST stay in `_bmad-output/`. It MUST NOT be
+  folded into the brief, and MUST NOT be promoted into `.what/`.
+- A `DEC-` or the PRD cites it by path instead. `_bmad-output/` is committed, so the path is stable.
+- Those run folders MUST NOT be deleted **while an `update` intent still needs them** — it re-reads the
+  original inputs. Once what they were read for is written down, they are retired under the three conditions
+  in `corpus-guide.md`, and that retirement is a `DEC-`. "Never deleted" was never the rule; needing them
+  was.
+
+## Passing G1
+
+- Dying cheap is a pass. A brief concluding the idea is not worth building is a valid G1 outcome,
+  and the most profitable one.
+- The brief MUST have been through `bmad-review` lenses structure + prose before it reaches the
+  gate. Gate time is for deciding, not for catching mistakes. This one fires on its own — it is the
+  *Polish* step of `bmad-product-brief`, driven by `doc_standards`, and nobody invokes it. Verifying
+  that it actually ran is check 9 in `wdi-problem`.
+- Invoke through `wdi-problem`, not `bmad-product-brief` directly — the wrapper is what checks the
+  rules on this page.

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

@@ -0,0 +1,341 @@
+---
+status: Accepted
+---
+
+# Corpus Guide
+
+**Loaded when:** deciding where a file lives, or creating a new file in the corpus
+
+Four layers and one workspace. Every other guide describes one document; this one answers the question that
+comes before all of them — **where does this belong?**
+
+The quick answer for the thing actually in your hand is the "benda di tangan → folder" table in `AGENTS.md`.
+It is deliberately there rather than here: it is needed at the moment someone would otherwise have to reason
+about what `.what/` and `.how/` mean, and that moment comes before anyone thinks to open a guide. It MUST NOT
+be copied into this file.
+
+## The four layers
+
+| Layer | Answers | Lifetime | Written by |
+|---|---|---|---|
+| `.constitution/` | How we work | Living, rarely changes | Us |
+| `.control/` | What currently holds, and what has been decided | Living, changes often | Us + generators |
+| `.what/` | What is promised | Living, amended | BMad class A + us |
+| `.how/` | How it is built | Living, amended | BMad class A + us |
+| `_bmad-output/` | Work in progress | Ends when the work does | BMad class B and C |
+
+`.control/` is the value of `{project_knowledge}` in BMad's configuration. There is no `docs/`.
+
+## The placement test
+
+One question decides everything: **is this file still correct after its wave has passed?**
+
+Yes → the corpus. No → `_bmad-output/`.
+
+`_bmad-output/` is committed but **not curated**. Committing it is what makes citation by path stable, so a
+decision or a PRD MAY point into it. Research, brainstorming, forge, and PRFAQ reports are never promoted.
+
+A run folder MUST NOT be deleted **while anything still needs it** — the `update` intents re-read the original
+inputs in place. "Never deleted" is not the rule; the rule is a **retirement condition**, and it is below.
+
+## Who lands what
+
+There is no separate placement skill. A skill lands the output of the layer **it owns**, and the landing is
+part of producing it — never a follow-up someone else performs.
+
+| Output | Permanent home | Owner |
+|---|---|---|
+| The spine | `.how/_platform/ARCHITECTURE-SPINE.md` | `wdi-blueprint` |
+| C4 L1 · L2 · one L3 per container holding more than one PC | `.how/_platform/c4-l1-system-context.md` · `c4-l2-containers.md` · `c4-l3-<container>.md` | `wdi-blueprint` |
+| each container in C4 L2 | a `container` entry in `components.yaml` | `wdi-blueprint` |
+| **The three inventories** | `.how/_platform/inventory-db.md` · `inventory-api.md` · `inventory-screen.md` | `wdi-blueprint` |
+| The error envelope, and anything else defined once for the product | `.how/_platform/cross-cutting.md` | `wdi-blueprint` |
+| UC catalogue · Actor Register · domain model | `.what/<pc>/SRS-<pc>.md` · `03-domain/domain-model.md` | `wdi-blueprint` |
+| Business rules binding more than one PC | `.what/business-rules.md` | `wdi-blueprint` |
+| A domain term | `.control/product-glossary.md` | `wdi-blueprint` |
+| Full UC flows · local rules · state machines · scenarios | `.what/<pc>/` slots `02`–`05` | `wdi-component` intent `behaviour` |
+| The SDD and its slots `02`–`06` | `.how/<pc>/` | `wdi-component` intent `design` |
+| each Boundary and Control object drawn | an `LC` in `components.yaml` | `wdi-component` intent `design` |
+| `EXPERIENCE.md` | `.what/<pc>/04-usecases/` | `wdi-ux` |
+| `DESIGN.md` | `.how/<pc>/01-ux/` | `wdi-ux` |
+| tokens and base components | `.how/_platform/design-system.md` | `wdi-ux` |
+| each screen in `DESIGN.md` | an `LC` of type `ui-screen` in `components.yaml` | `wdi-ux` |
+| `RETROSPECTIVE.md` | `RTR-<wave>.md` in `.control/reports/` | `wdi-build`, at wave close |
+| `test-summary.md` | test names → `waves.yaml` | `wdi-build` |
+| `stack.md` · `conventions.md` · `brownfield.md` | merged into `.constitution/codebase/*-guide.md` | `wdi-build`, at wave close |
+| A sprint change proposal | a `DEC-` of `type: course-correction` | `wdi-decision` |
+| The registry rows and skeletons a new PC needs | `components.yaml` · `.what/<pc>/` · `.how/<pc>/` | `wdi-init` intent `component` |
+| `platform_owns` — an entity no component's promise explains | `components.yaml`, plus its description in `cross-cutting.md` | `wdi-blueprint` |
+| The two structure maps | `.control/structure-codebase.md` · `structure-document.md` | `wdi-init` intent `structure` |
+| An open question | `.control/questions/` — one of four files | `wdi-question` |
+| A decision | `.control/decisions/DEC-NNN-<slug>.md` | `wdi-decision` |
+| Minutes · a non-technical fact | `.control/meetings/` · `.control/project-non-technical-log.md` | `wdi-log` |
+
+- A skill MUST NOT write into a layer it does not own.
+- Registry conversion is part of landing, not a follow-up. A screen that lands in `01-ux/` without its
+  `components.yaml` entry has been half-landed, and V12 catches it **at wave close** — which is the
+  right moment to be caught, and a bad moment to be surprised.
+- Content MUST NOT be edited while it is being landed. If it has to change to fit its new home, that is a
+  separate act — say so and stop. Splitting one output across the homes its row names is not editing.
+- The C4 set's target files already exist and are **living**. Their owner MUST amend, MUST NOT overwrite; when
+  the incoming set contradicts an annotation already there, it MUST stop and report the finding.
+- Nothing MAY be landed into a wave that is already closed. The wave is reopened through `wdi-build`, or the
+  gap is recorded as an open question.
+- An output with **no row** in this table MUST NOT be given a guessed home. It stays in `_bmad-output/`, and
+  `wdi-reconcile` reports it — an output with no home is a gap in the method, and MUST surface as one.
+
+## Landing that MUST be confirmed first
+
+Most landings are mechanical and MAY be done without asking. Some change what other people already agreed to,
+and those MUST be put to the owner before the file is written — not reported afterwards. The line is drawn by
+**what the landing can invalidate**, never by how much text moves:
+
+| | Light — act, then report | Heavy — confirm, then act |
+|---|---|---|
+| Layer | Stays inside the layer the skill owns | Crosses into another layer's consequences |
+| ID chain | No `BG`/`CAP`/`FR`/`NFR`/`UC`/`LC` id is born, renamed, or retired | Any of them is |
+| Depth and risk | `mode` and `risk_accepted` unchanged | Either would have to change |
+| Existing text | Adds, or replaces content the same skill wrote | Overwrites or contradicts what another skill or a human wrote |
+| Registry | Adds the entry its own output requires | Removes or re-points an entry something else already cites |
+
+Any one heavy row makes the whole landing heavy. When confirmation cannot be obtained now, the landing MUST
+NOT be split into a light half that goes ahead — half-landed output looks distributed and is worse than output
+that waited.
+
+A skill MUST NOT lighten a landing by narrowing what it writes. Dropping the contentious half to stay under
+the bar is the same change, made invisible.
+
+## Product Component — the naming and proposal rule
+
+This rule lives here, beside the definition, and **not inside a skill**. If it lived in one skill, the second
+skill that needed it would copy it, and the two copies would drift.
+
+> The name of a Product Component MUST be a surface a user could name. A name that states a layer, a service,
+> or a pattern MUST be rejected at proposal time, not corrected later. Additions, changes, and removals MUST
+> be presented separately, each with the `FR` behind it.
+
+A PC MUST NOT be created because a folder would look tidy. A PC that no `FR` points at is a folder with
+nothing inside it.
+
+Birthing is cheap and retiring is not: retiring or renaming a PC that already carries an SRS goes through
+`wdi-decision`, never through the skill that births one.
+
+## Product Component, Logical Component, container, `_platform`
+
+Four words that are easy to blur and MUST NOT be:
+
+| Term | Is | Registered in |
+|---|---|---|
+| **Product Component** | A surface a user can name — what they came to do | `product_components` |
+| **Logical Component** | A unit inside the build — a screen, a service, an adapter, an entity | `logical_components` |
+| **Container** | Something that runs or ships on its own | `containers` |
+| **`_platform`** | **Not a component at all** — the home for what belongs to no Product Component | `platform_owns`, and the `_platform/` folder |
+
+PC and container are **crossing axes**, not a hierarchy: one PC MAY be delivered by several containers, and one
+container MAY serve several PCs. An `LC` names its container in a `container:` field, which is what lets
+`structure-codebase.md` be checked against the registry rather than trusted.
+
+## `_platform` — what belongs to no Product Component
+
+`_platform` is **not a Product Component**, and it MUST NOT be registered as one. It fails the naming test on
+purpose: nobody came to the product to use "the platform". It therefore carries **no `mode`, no
+`risk_accepted`, no SRS, no SDD, and no G4** — its documents are the spine, the C4 set, `cross-cutting.md`,
+and the three inventories, and all of those exist at every `mode`.
+
+What it does carry is **ownership**. `_platform` is a legitimate value in **every** position that asks
+*"which component owns this"* — the `platform_owns:` list for domain entities, the owning-component column
+of any inventory row, an `LC`'s `component:` field, and any such column a later artifact adds. One test,
+one cost, everywhere; there is no per-artifact special case to negotiate, and a new kind of thing arriving
+next year needs no new discussion.
+
+The test, and both halves MUST hold:
+
+> Something belongs to `_platform` when **no single Product Component's promise is the reason it exists**,
+> *and* more than one component reads, writes, or depends on it.
+
+Four kinds qualify today and the list is open: **data** (a product-wide setting, the trace of a shared
+outbound channel) · **endpoint** (`/health`, `robots.txt` — plumbing no `FR` promises and none should) ·
+**job** (a scheduled cleaner whose data belongs to a component but whose machinery does not) · **screen**
+(none yet).
+
+Failing either half, it belongs to a Product Component — and the component is found by asking which `FR`
+would have to be withdrawn for the entity to stop being needed. Two examples of the trap, both real:
+
+| Entity | Looks platform-shaped | Actually |
+|---|---|---|
+| `member_activity_events` | member-wide telemetry, several components write it | **`referral`** — `FR-65` promises a Sponsor sees the login and click counts of their downline. One `FR` explains it |
+| `email_logs` | one component sends first | **`_platform`** — it is the trace of one outbound channel that order notifications and password recovery both use, and neither promise is why the channel exists |
+
+**One guard, and it is what stops this becoming a drawer:** everything `_platform` owns — in any position —
+MUST be described under `## Milik platform` in `cross-cutting.md`, with its kind and the shape every toucher
+obeys. A platform that owns something documents it. V21 checks it, and skips only while that section has not
+been born at G3.
+
+That guard is the whole reason `_platform` can be a general answer rather than an escape hatch: reaching for
+it costs a row somebody has to write, so it stays cheaper to find the real owner when one exists.
+
+`_platform` has no `FR`, so an `FR` that writes something platform-owned has nothing to point `defers_to` at,
+and MUST NOT be asked for one. What replaces "one writer" there is **one documented shape**: it is written the
+way `cross-cutting.md` says, and a component wanting it written differently is proposing a change to that file.
+
+Platform ownership sits with `wdi-blueprint` intent `platform`, beside the rest of `_platform/`. `wdi-init`
+intent `component` MAY name a candidate and MUST NOT claim one.
+
+**A decision the pattern cannot derive lives in the artifact it governs.** An inventory row owned by
+`_platform`, and a route that is a *state* of another screen rather than a screen of its own, are both
+judgements — so both are declared in that inventory's own frontmatter (`platform_rows:` and `states:`) and
+survive every re-derivation. Putting either outside the file means the next derivation silently deletes the
+owner's decision.
+
+## Two axes inside `.what/`
+
+| | `_prd/<initiative>/` | `<pc>/` |
+|---|---|---|
+| Slices by | **Initiative** — one functional area | **Space** — one Product Component |
+| Answers | What is promised to a user | What this component can do |
+| Written for | Outside readers — client, sponsor | People building the system |
+
+Both are living. What separates them is **promise versus behaviour**, not lifetime. One functional area MAY
+span several components, and one component MAY serve several PRDs, so neither can absorb the other.
+
+**Time is not a folder axis.** Release lives in `CAP.target_release` and in `waves.yaml`.
+
+## Slot numbering means two different things
+
+| Layer | Slots | The number means |
+|---|---|---|
+| `.what/<pc>/` | `02-rules` · `03-domain` · `04-usecases` · `05-scenarios` | **Reading order** — its rules → the things → how it is used → its branches |
+| `.how/<pc>/` | `01-ux` … `06-flows` | **ABCE classification** — Boundary, Control, Entity, behaviour. Not a reading order |
+
+Reading one as the other is the most common misfiling in this corpus, and it is silent: the file lands in a
+plausible-looking folder and is simply never found again.
+
+`.what/<pc>/01-requirements/` is **repealed** — permanently empty, because `FR` live in the PRD and the SRS
+cites them. `supplements/` beside either kernel is repealed with the `ANX-` concept.
+
+## Splitting slots
+
+- A slot MAY stay empty. Content SHOULD stay in the kernel until that file grows past roughly 400 lines — a
+  suggestion, not a threshold, and a file that is clearer split earlier MAY be split earlier.
+- The first slot to be split SHOULD be `04-usecases/` — it is always the largest part.
+- One use case with many branches MUST put its branches in `05-scenarios/` rather than growing its own file.
+- The `Actor Register` MUST stay in the SRS kernel. It is the SSOT the SDD mirrors, and it is short.
+
+## Document codes
+
+| Code | Is |
+|---|---|
+| `BG-` `CAP-` `FR-` `NFR-` `UJ-` `UC-` | The traceability chain, allocated from `requirements.yaml` and `usecases.yaml` |
+| `AD-` | An invariant in the architecture spine — a living rule, edited in place |
+| `DEC-` | A decision — an event, frozen when `applied`, only superseded |
+| `LC-` | A Logical Component |
+| `OQ-` `RTR-` | An open question · an archived retrospective |
+| `BUG-` `HOT-` | A defect · a hotfix |
+| `NT-` | A non-technical fact |
+
+**Retired, and MUST NOT be coined again:** `ADR-` (renamed to `DEC-` on 2026-08-18; the old prefix inside a
+document frozen before that date is an alias for the same number) · `ANX-` (zero annexes were ever born) ·
+`SCP-` (a course correction is a `DEC-`) · `BRS-`, `PFQ-`, `RES-` (exploration output is never promoted).
+
+IDs are allocated **globally** and never restart per document, per component, or per release.
+
+### A record of the past MUST NOT be rewritten to match the present
+
+A retired name appearing in a document that **records what happened** is a fact about the past, not
+drift, and a sweep MUST NOT rename it. Four kinds, and all four are legitimate:
+
+| Where | What it says | Why it stays |
+|---|---|---|
+| `.control/decisions/DEC-*.md` — `Applied to`, `Temuan` | *"`wdi-apply` applied this on 2026-08-17"* | It did. Renaming it to today's skill claims a skill that did not exist then did the work |
+| `.control/memlog/*.md` | Which skill ran, and what it decided while running | A run log. Rewriting it destroys the only account of how an artifact got that way |
+| `.control/questions/answered.md` · `project-non-technical-log.md` | An answer, with its date and who gave it | Closed in place by rule; the wording is part of the record |
+| `.what/` and `.how/` frozen before a rename | Prose that cites the old name | Frozen by decision. `ADR-NNN` there is a retired alias for `DEC-NNN` with the same number |
+
+The test is one question: **does this sentence describe what happened, or state what holds?** Describes
+→ leave it. States → sweep it.
+
+That distinction is why a sweep can be run repeatedly without churn. Without it, every pass rewrites
+the same three dozen historical files and the diff stops carrying information.
+
+File naming that must survive every OS is governed by `structure-guide.md` and MUST NOT be restated here.
+
+## `.constitution/project/` — this product's custom rules
+
+The rest of `.constitution/` **belongs to the method**: it ships in the `wdi-method` package and is
+**overwritten** on every `update`. This folder is the only one that is not. `update` seeds it once and
+never writes over it again, and `promote` **skips it**, so a rule that names a client cannot reach the
+public package.
+
+| Goes here | Does not, and its home |
+|---|---|
+| A review policy a client requires | product / client name → `index.yaml` `product:` |
+| A process rule that came from a contract | code conventions → `codebase/*-guide.md` |
+| A policy that differs from the method default | scope and ownership → `constitution.md` Art. 1, 2, 5 |
+| A prohibition specific to this domain | agent instructions → `AGENTS.md`, outside the marked block |
+
+**A generic rule MUST NOT be moved here.** If it holds in any project it belongs to the package — fix
+it there, then `promote`. Using this room to bypass the package is how a method stops being generic
+with nobody deciding it, and **an empty room is a valid state**: filling it so that it gets used is the
+very failure this rule prevents.
+
+Frontmatter is required and **V27** checks it: `scope: project` · a one-line `purpose:`. A file MAY
+narrow or add with nothing further; to **contradict** a generic rule it MUST name that rule in
+`overrides:` and carry `decision:` naming the `DEC-` that decided it. A method that can be contradicted
+without a decision stops being trustworthy in the next repo.
+
+**Whole files, not marked blocks.** `AGENTS.md` uses a marked block because it is one file;
+`.constitution/` has fifty-odd, and blocks inside them would make `update` perform surgery in every
+file — one broken marker and either the product's rule is erased or the generic rule freezes.
+
+## Documents that predate the method
+
+A repository that already had documentation keeps it in `_bmad-output/prior-knowledge/`. It follows the same
+rules as the rest of `_bmad-output/`: committed, never curated, cited by path, never deleted.
+
+The sorting happens once, at install, and the test is a single question: **is this file already the artifact
+one corpus slot asks for, one file for one slot?** Yes → straight into that slot, carrying a provenance line
+naming the gate that ratifies it. No → `prior-knowledge/`.
+
+**A file in `prior-knowledge/` MUST NOT be copied into `.what/` or `.how/` afterwards.** It enters the corpus
+only through the skill that owns the slot, which reads it as input. This is the rule the whole arrangement
+exists for: moving a file is always cheaper than running the stage that should have produced it, so without a
+rule the move always wins — and what lands then has no author, no input trail, and no gate behind it.
+
+### Retiring `prior-knowledge/`, and the condition that makes it safe
+
+A prior document is **input**, and input stops being needed once what it was read for is written down. Three
+conditions, and **all three MUST hold** before the folder is deleted:
+
+1. **Every promise it carried is mapped.** The old numbering has a complete old → new table, and that table
+   lives in the `addendum.md` beside the PRD it maps into — **not** in `prior-knowledge/`, precisely so the
+   source can be retired without taking the map with it.
+2. **Every live citation into it has been re-pointed or dropped.** A glossary entry, a `risk_note`, an
+   `enforced_by` — anything that *states what holds*. Where the fact has a home in code or in `.control/`, the
+   citation points there instead.
+3. **The retirement is recorded as a `DEC-`.** Deleting source material is expensive to reverse, and the
+   answer to *why is it gone* is not readable from the code.
+
+**A citation left inside a record of the past is not condition 2's business.** A `DEC-`'s Trace naming the
+document it was derived from, or a memlog naming what a run read, describes what happened — and the rule above
+on records of the past applies. Those citations dangle by design, and `wdi-reconcile`'s Evidence check MUST NOT
+report them: what makes it harmless is that the substance is already written into the document doing the
+citing, so the path is provenance rather than a dependency.
+
+The same three conditions govern `.work/`, with one difference: nothing there was ever authority, so condition
+1 is usually already met.
+
+Two consequences that MUST be expected rather than discovered:
+
+- Internal numbering inside a prior document — `FR-3`, `§7` — is **not** a corpus ID. A mapping table MAY be
+  written once, and it lives in `prior-knowledge/`, never in `.control/`.
+- A file placed straight into a slot MUST lose any claim of authority it makes about itself. In the corpus,
+  authority comes from the layer and the gate.
+
+## Rules
+
+- A file MUST NOT be moved between layers by a skill that owns neither end. Anything else is a misplacement,
+  and MUST be reported rather than fixed.
+- A fact MUST have exactly one home. When two documents state the same thing, one of them MUST become a
+  reference — and the copy being replaced MUST be deleted, not left as a courtesy.
+- Solution shape MUST NOT appear in `.what/`. Promises MUST NOT appear first in `.how/`.
+- Superseded artifacts are not deleted. Their status becomes `superseded` and points at the replacement.

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

@@ -0,0 +1,134 @@
+---
+status: Accepted
+---
+
+# Decision Guide
+
+**Loaded when:** opening, accepting, or applying a `DEC-`
+
+A `DEC-` records a decision worth remembering. The old name was ADR — *Architecture Decision Record*
+— and the word "Architecture" forced the wrong question at the moment of writing: *"is this
+architectural?"*. That question throws away the decisions most worth keeping, the ones that sound
+small: *"the filter works like this"*, *"this list is sorted that way"*.
+
+## One test decides whether to record
+
+> **If someone asks in three months why it is like this, is the answer readable from the code?**
+
+Yes → it MUST NOT be recorded. No → it is recorded.
+
+**Recording is not mandatory, and a decision nobody recorded is normal rather than negligence.** It
+MUST NOT be logged as debt, raised as a finding, or backfilled later from memory. Without this
+sentence, "not mandatory" is read as "mandatory but allowed to be late".
+
+One case remains mandatory: a decision that **contradicts or changes an `AD-N`** MUST be recorded
+before the work that depends on it. That is the only one.
+
+## `AD-N` and `DEC-NNN` are not the same thing
+
+| | `AD-N` | `DEC-NNN` |
+|---|---|---|
+| Is | A **living rule** in `ARCHITECTURE-SPINE.md` | A **decision event** |
+| Lives in | The spine | `.control/decisions/` |
+| Changes by | Being edited in place | Never, once `applied` — a new `DEC-` supersedes it |
+| Answers | What is forbidden from now on | What was chosen, and what it cost |
+
+An `AD-N` usually has a `DEC-` behind it. Neither MUST be written in place of the other, and one MUST
+NOT be converted into the other.
+
+## Shape — three sections, and no more required
+
+| Section | States | Required |
+|---|---|---|
+| **Decision** | One sentence, present tense, quotable into a rule | always |
+| **Why** | The context that forced it, in a few lines | always |
+| **Cost** | What becomes harder. A decision with only benefits was not thought through | always |
+| Alternatives | What else was considered, and why each lost | see below |
+| Reversal trigger | The observable condition that makes revisiting this correct | see below |
+| Trace | Where it came from, and what it landed in | see below |
+
+The last three MUST be present when the decision reaches a Product Component whose `risk_accepted`
+is `low` in `components.yaml`. Everywhere else they are optional, and an empty one MUST be dropped
+rather than left as a heading with nothing under it.
+
+**A `DEC-` MUST NOT hold an open question.** Those belong to `.control/questions/`.
+
+## Frontmatter
+
+| Field | Rule |
+|---|---|
+| `id` | `DEC-NNN`, allocated from `.control/registry/decisions.yaml`, globally. MUST NOT restart per component or per release |
+| `status` | `draft` · `accepted` · `applied` · `superseded` · `rejected` |
+| `touches` | Empty at `draft`. Filled **when the decision is applied**, with the files it actually changed |
+| `type` | Free text, and optional. Written when it is useful — `risk-acceptance`, `course-correction` |
+| `supersedes` · `superseded_by` | Both sides of a supersession MUST exist |
+
+**There is no `layer:` and no `component:`.** Both were classifications demanded before anything was
+known, and both were guessed as often as they were derived. `touches:` replaces them, and it is filled
+from what happened rather than from what was predicted.
+
+The filename is `DEC-NNN-<slug>.md`. It MUST NOT carry a component name — a decision that turns out to
+reach a second component would otherwise need renaming, and the rename breaks every link to it.
+Filenames MUST obey the cross-OS naming rules in `structure-guide.md`.
+
+## Status — and why `applied` exists
+
+`draft` → `accepted` → `applied`. A change of mind after that produces a **new** `DEC-`.
+
+| Status | Means |
+|---|---|
+| `draft` | Being argued. It changes nothing, and that is the point — proposing is cheap |
+| `accepted` | Ratified by the Product Owner. MAY still be corrected in place |
+| `applied` | The documents it governs now say it. **Frozen from here** |
+| `superseded` | Replaced. Names its replacement, and the replacement names it |
+| `rejected` | Seriously considered and turned down. A real status, and it MUST be used — it is what stops the same argument being had twice |
+
+**Applying is what freezes a decision, not accepting.** From `applied` onward nothing in the file MUST
+be touched — not the Decision, not the Cost, not a typo in the Why. Documents cite it, and editing it
+destroys the only evidence of what they were changed to match.
+
+Before that, an `accepted` `DEC-` MAY be corrected in place. Nothing has been built on it, so there is
+no divergent record to preserve. The correction MUST be recorded in the memlog.
+
+An agent MUST NOT accept its own `DEC-`. When work is blocked waiting on one, the block is reported,
+never resolved by self-approval.
+
+## Finding a decision
+
+`.control/generated/decisions.md` carries a flat table of every `DEC-` with its status and what it
+touches. It is generated, and MUST NOT be written by hand.
+
+Searching the memlog for decisions is **retired**. The memlog is a run log again — the record of *why*
+while an artifact was written, and a source when writing a `DEC-`, never an index of them.
+
+## Where decisions come from
+
+| Trigger | Route |
+|---|---|
+| A meeting reached one | `wdi-log` intent `meeting` writes the minutes; the decision still needs its own `DEC-` |
+| An open question was answered | `wdi-question` closes it; the answer becomes a `DEC-` when it binds |
+| `wdi-systematic-debugging` found a root cause in the design | A `DEC-`. It MUST NOT be absorbed as a code patch |
+| A planning assumption turned out to be void | `wdi-decision`, which wraps `bmad-correct-course`. The result is a `DEC-` of `type: course-correction` |
+| A story contradicts an `AD-N` | The story stops. This is the one mandatory case |
+| `wdi-reconcile` found two documents disagreeing with no clear winner | That is a decision, not drift |
+
+Minutes MUST NOT be treated as a decision record. They say what was discussed; a `DEC-` says what was
+chosen and what it cost.
+
+**`SCP-` is retired.** A course correction is a decision, and it is a `DEC-` with
+`type: course-correction`. No second code names the same thing.
+
+## Rules
+
+- A `DEC-` MUST be opened **before** the code that depends on it, never written afterwards to explain
+  code that already exists.
+- The applying pass MUST NOT improvise. When an `accepted` `DEC-` does not say clearly what a document
+  has to change, the decision is incomplete and is sent back.
+- Applying MUST NOT widen beyond what the decision says. A neighbouring paragraph that now looks wrong
+  is a finding to report.
+- V8 checks that every `applied` `DEC-` names a non-empty `touches`. It MUST NOT check that a decision
+  serves an `FR` or `NFR` — *"the filter works like this"* serves none, and it is exactly the kind of
+  decision this guide exists to keep.
+- `ADR-NNN` written inside a document frozen before 2026-08-18 is a **retired alias** for `DEC-NNN`
+  with the same number. It MUST NOT be read as a second, missing record, and those documents MUST NOT
+  be rewritten to change the prefix.