wdi-method 0.3.0

package/kit/.constitution/method/rationale.md

@@ -0,0 +1,246 @@
+---
+status: Reference
+---
+
+# Rationale — why the method is shaped like this
+
+**Opened when:** you are about to change a rule and need to know what you would break.
+
+This file **explains**. It does not bind — `document/*-guide.md` does, and where the two disagree the guide
+wins and the disagreement is a defect to report. **A rule MUST NOT be born here.** If this file notices a
+rule that should exist, it says so as a finding and the rule is written in its guide.
+
+## What happened, and what fixed it
+
+The previous version of this method was run in full on one real product as far as its third stage, then stopped by its
+owner: `.what` had jammed, `.how` was being skipped, and coding was running straight from a `.what` that was
+not finished. Six complaints, their causes, and where each is answered now:
+
+| Complaint | Cause | Answered in |
+|---|---|---|
+| Open questions in floods — ids reached `OQ-146`; one review produced 200 findings, then another produced 90 | Three rules combined into a generator: the `edge-case-hunter` lens mandatory over a whole SRS at once; no route for *"take the assumption, record it, continue"*; no budget and no severity class | `document/decision-guide.md`, `.control/questions/` |
+| Ceremony drift into the PRD; three corrections ended "reported but not fixed" | Correcting a *sentence* of an `FR` was treated as changing its *promise* — both had to go through the PRD skill | `document/prd-guide.md` |
+| Gates failing repeatedly over unanswered questions | No rule said that only a **blocking** question holds a gate | `.control/questions/blocking.md` |
+| The spine had to be updated every story | Invariants and inventories were mixed, and the tax was paid before the story, when the information was thinnest | `document/architecture-guide.md` |
+| A large PRD made `.what` over-think — 41 of 56 use cases marked `critical` (73%) | Not the PRD's length. The stage's scope was the whole corpus at once, plus a `critical` definition with two elastic criteria that passed everything | `document/delivery-flow-guide.md` |
+| Too slow for a small-to-medium application | A composite of the five above | all of it |
+
+One cause was **not** the method: **model choice.** A "find the gap" lens with no upper bound, run by the
+most careful model, produces the most gaps, and each gap became an open question. That is a policy question,
+and its answer is in `README.md`.
+
+## Six principles
+
+Every decision in this method traces to one of these. Anything that traced to none of them was left out.
+
+1. **The size of the application does not set the depth of the documents.** Size sets how many components
+   there are, not how deep each one goes.
+2. **Depth is set by the owner's preference, not by an objective threshold.** A preference is a legitimate
+   input and does not have to be justified.
+3. **Accepting risk must be cheap.** One recorded line, not a debate. If accepting risk is expensive, people
+   avoid it by writing documents they do not need.
+4. **Breadth once, depth per component.** The global portrait is born once and thin; depth is born when its
+   component is actually worked on.
+5. **What can be derived is not written by hand.** Inventories, structure maps, the decision index, the
+   global catalogue, story status.
+6. **Mandatory is a cost and must buy something.** A mandatory rule that prevents no concrete failure is
+   repealed, not loosened.
+
+## Why `mode` and `risk_accepted` are two fields
+
+The most important separation in the method, and the easiest to undo by accident.
+
+Documents and reviews are **two different mitigations.** Merging them makes one legitimate position
+impossible to state:
+
+> *"This part is risky, I know that, and I manage it with tests and review — not with prose."*
+
+If depth were controlled by `risk_accepted`, the only route to a thin document would be raising
+`risk_accepted` — which means **lying in the risk record** to buy the depth you wanted. And the entire reason
+that field exists is to record what was accepted.
+
+So a component may sit at `mode: catalog` and `risk_accepted: low` at the same time: thin on purpose, and
+reviewed the hardest precisely there. No matrix can hold that position, and it is a position people actually
+have.
+
+The control over it is **disclosure, not veto**. The agent does not judge; it reads the `FR` that fall to
+the component and names what is touched — money moving, personal data, an irreversible action, a contractual
+promise, an un-rollbackable integration — and only then proposes values. The owner may always choose fast.
+They may never choose it without knowing what is being staked.
+
+One hard floor is not negotiable against preference: when an outside party — a regulator, an auditor, a
+client through a contract — will demand the artifacts as a deliverable, the touched component goes to
+`mode: deep` and `risk_accepted: low`. There the risk is not the owner's alone to accept.
+
+## Why `mode` has no third scope
+
+`mode` cannot be overridden per wave or per `SPEC.md`. A wave MAY cross several components, so a per-wave
+override would give one component two different depths depending on which wave touched it — while the
+document is one, and living.
+
+> Depth belongs to the component, not to the work.
+
+## Why the blueprint is bounded to lists
+
+The most decisive boundary in the method. The previous run broke because "complete" was read as "fully
+specified".
+
+The blueprint carries **one line per thing**: one line per use case, per table, per endpoint, per screen.
+Plus the entities, the actors, the spine, C4, and the rules that cross components. What it does **not**
+carry is the flows, the failure behaviour, the contracts, the data dictionary — those are per component, at
+G4, and only as deep as that component's `mode`.
+
+Two consequences worth knowing:
+
+- **The order stops being circular.** Blueprint content is untouched by `mode`, and `mode` is first needed at
+  G4 — by which point it has existed since the tail of G2.
+- **Nobody needs a fifth mode.** The wish for one is almost always *"I need at minimum the use cases, the
+  API, and the database"*, and all three are in `catalog` already, because none of them is part of the knob.
+
+**G3 is written per component and gated once**, and that is not a compromise. Writing parallelises with the
+component as the key. The gate is one, because its whole value is seeing the picture entire before choosing
+which component to build — gating per component means approving seven times, each time seeing a seventh.
+
+What is reviewed at G3 is the **generated roll-up**, not seven files. The catalogue and the actor lists stay
+in their component kernels as their permanent home. One fact, one home, one view.
+
+## Why `critical` was narrowed to three words
+
+It used to mean: touches money, personal data, or an irreversible action; **or** is the reason the component
+exists; **or** is expensive to discover late. With the last two, every use case passed — 41 of 56, 73%.
+
+Both were repealed. What is left is the first clause, and the one-third sanity check that follows from it: if
+more than a third of a component's use cases are marked, the definition was misapplied.
+
+## Why decisions stopped being mandatory, and stopped being called ADRs
+
+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 discards exactly the decisions
+most worth keeping, the ones that sound small: *"the filter works like this"*.
+
+So the name is `DEC-`, and the test is memory rather than category:
+
+> If someone asks in three months why it is like this, is the answer readable from the code?
+
+Recording is **not mandatory**, with one exception: a decision that contradicts or changes an `AD-N`. And
+one sentence has to be said out loud or "not mandatory" gets read as "mandatory but allowed to be late":
+
+> A decision nobody recorded is normal, not negligence, and MUST NOT be logged as debt.
+
+Three more things changed, each closing a hole that already existed:
+
+- **`applied` became a status.** The old form already said that *applying* is what freezes a decision — but
+  there was no status for it, so "applied or not" was readable from nowhere.
+- **`layer:` was repealed.** It was a classification demanded before anything was known, and it was guessed
+  as often as derived. `touches:`, filled from what actually changed, replaces it.
+- **Finding a decision stopped going through the memlog.** A generated flat table does it. The memlog is a
+  run log again.
+
+## Why the folders stay `.what/` and `.how/`
+
+Naming folders after the gates — `.problem/`, `.product/`, `.blueprint/`, `.component/`, `.release/` — was
+weighed and **not taken**, for four reasons:
+
+| Reason | Concretely |
+|---|---|
+| Two folders for two files | `.problem/` would hold one brief; `.product/` would hold PRDs. That is ceremony, not clarity |
+| One folder with nothing in it | G5's output is code, tests, a PR, a green RTM — no document |
+| **Time would become a folder axis** | A gate is a moment. One SRS would split across two homes — half written at G3, half at G4. One living document, two folders, divided by the calendar |
+| **A mechanical guard would be lost** | Today a skill cannot write into a layer that is not its own, because the boundary is enforced **by path**. Put behaviour and mechanism in one folder and that boundary drops to prose |
+
+So "Blueprint" and "Component" name a **gate and a skill** — not a document, not a folder. The split between
+them is horizontal, not vertical: the blueprint holds the breadth of both layers, the component holds the
+depth of both.
+
+What actually answered the original complaint — that `.what`/`.how` feel abstract — is not a rename. It is
+**one table in `AGENTS.md`**: the thing in your hand → its folder. Nobody has to reason about the abstraction
+if the answer is already written where they are standing.
+
+## Why each skill exists, and why the merged ones merged
+
+Twenty-one skills became fifteen. Skills are named for the **gate they serve** rather than the artifact they
+write, so *"which skill do I run"* is answered by *"which gate am I at"*.
+
+| Gone | Merged into | Why |
+|---|---|---|
+| `wdi-product-brief` | `wdi-problem` | Renamed to its gate |
+| `wdi-analysis` | `wdi-blueprint` + `wdi-component` | It branched three ways in its own first step — the sign of two jobs in one skill. The split now falls exactly on the gate boundary |
+| `wdi-architecture` | `wdi-blueprint` intent `platform` | Spine, C4, and the inventories are all G3 output |
+| `wdi-design` | `wdi-component` intent `design` | Renamed to its gate |
+| `wdi-glossary` | `wdi-blueprint` | It was already the first step of the writing order |
+| `wdi-component` (old) | `wdi-init` intent `component` | Its work was a registry row and two skeletons. That is init |
+| `wdi-structure` | `wdi-init` intent `structure` | Its scope widened to everything that must exist before work starts |
+| `wdi-apply` | `wdi-decision` | Applying is part of a decision's life, and it is what writes `applied` |
+| `wdi-correct-course` | `wdi-decision` | A course correction **is** a decision |
+| `wdi-wave` · `wdi-ship-story` | `wdi-build` | One unit of work must not need four invocations, three of them bookkeeping |
+| `wdi-project-log` | `wdi-log`, with `wdi-meeting` | Both record a fact that came from outside the code |
+| — | **`wdi-product` was born** | `bmad-prd` was the only writer of a primary artifact with no wrapper, so nothing checked its position, verified its result, or landed its memlog |
+
+**`wdi-ux` stands alone and was deliberately not merged.** It is the one skill that straddles: its decision
+sits at G2 altitude — *how does this feel to use* — while its landing is per component. Merged into
+`wdi-product` its landing home would be wrong; merged into `wdi-component` its decision altitude would be.
+Left standing, it is more honest than either, and honesty beats the count.
+
+## Why fan-out has a rule
+
+> Parallel fan-out is only for output with a natural key. Output that is a shared list with no key must be
+> written by one agent that reads the whole input.
+
+Not theory. In the previous run, 41 cross-component business rules from seven parallel agents had to be
+merged and de-duplicated **serially**, because the target file had no key — and that merge was the most
+expensive part of the pass.
+
+Keys that exist: the Product Component, the inventory source, the endpoint number, the story, the wave.
+Things with no key: the glossary, the cross-component rules, the spine.
+
+## Why nine ceremonies were repealed
+
+Each cost something and bought nothing, and principle 6 says that is grounds for repeal rather than
+loosening:
+
+| Repealed | Because |
+|---|---|
+| The `ANX-` annex, its "referenced in ≥2 places" rule, and its `Verified` + SHA line | Zero annexes were ever born |
+| The `No-op` lane rule on flow diagrams | A heavy convention for a folder that had never carried a file |
+| `layer:` on a decision, and the whole `both`-versus-pair section | Replaced by `touches:`, filled from what happened |
+| The double proof of done — a business sentence plus a technical restatement | The business one stays; the technical form is the test name, checked mechanically |
+| The `SCP-` code | A course correction is a `DEC-`. No second code names the same thing |
+| The 400-line threshold for splitting a slot | Dropped from mandatory to advice |
+| Having to open a written decision at five different points | One is left: contradicting an `AD-N` |
+| 21 of the 35 gate-checklist questions, at `mode: catalog` | They remain in the guide as material. Asking them is never wrong; requiring them was |
+| Five of the eight story-closing items | They moved to **wave close**, where the information actually exists |
+
+Two of those were leaks of a different kind, and naming the kind matters more than the two instances: the
+`No-op` lane rule and the annex `Verified` line were both **how to do the work** written as **what binds**.
+The test that separates them:
+
+> If next year's model is twice as capable, does this rule still buy something? Yes → it belongs in a guide.
+> No → it belongs in a template comment.
+
+A guide carries the layer boundary, the required shape, the failure prevented, the acceptance test, and the
+ownership. A template comment carries the phrasing, the examples, and the heuristics — and template comments
+are already designed to be deleted, which makes them the right home for what ages.
+
+## Why a container is a runtime, not a folder
+
+Three places in this repo used the word "container" for three different things with zero overlap, and the
+argument that followed was not about which list was right. It was about a definition nobody had written, so
+each place had quietly invented one. `DEC-017` settled it: a container runs its own code or stores its own
+data, and can be replaced without rebuilding another. **Deploying two of them in one release does not merge
+them** — that is a deployment choice, and reading it as an architectural one is what collapses a browser
+bundle into "static assets of the web server", where it carries real behaviour with no owner and no NFR.
+
+The part worth carrying is not the definition but **why one rule could not be obeyed**. The old rule said
+every container heading in the codebase map must match the registry, and the next sentence said a container
+with no code of ours gets no section. A database satisfies the second and cannot satisfy the first. Read as
+symmetric, the rule demanded a section that would be empty or invented — and the way out was not an
+exception but a field: `built` says whether the implementation is ours, and the match became one-directional.
+
+**A definition left unwritten will be re-argued in the next corpus.** That is the general lesson, and it is
+why `built` is checked by V25 rather than merely described here: prose that nothing verifies is prose that
+gets contradicted by the first person in a hurry.
+
+## What is not here
+
+The change plan that produced this shape — which guides changed, which templates were born, which folders
+were deleted, in what order — was archaeology the moment the change landed. Its trace is in git.

package/kit/.constitution/method-glossary.md

@@ -0,0 +1,169 @@
+---
+status: Accepted
+---
+
+# Method Glossary
+
+**Loaded when:** a method term is unclear, and before coining a new one.
+
+The words this method uses for **itself**. What the product is about belongs to
+`.control/product-glossary.md` instead. A term defined here MUST NOT be redefined there, and the
+reverse holds too. The test: would this term still apply on a different product? Yes → here.
+
+## Layers
+
+| Term | Means |
+|---|---|
+| **Corpus** | The four layers below. `_bmad-output/` is not part of it |
+| **`.constitution/`** | How we work. Rules. Rarely changes |
+| **`.control/`** | What currently holds and what has been decided. Facts. Changes often. Equals `{project_knowledge}` |
+| **`.what/`** | What was promised |
+| **`.how/`** | How it is built |
+| **Workspace** | `_bmad-output/` — work in progress, committed but not curated |
+| **Placement test** | Is this file still true after its wave has passed? Yes → corpus. No → workspace |
+
+## Units
+
+| Term | Means |
+|---|---|
+| **Product Component** (PC) | A domain slice — the box at C4 L3. Lives in `.what/<pc>/` and `.how/<pc>/`, and its `containers:` says where it runs |
+| **Logical Component** (LC) | One addressable unit of build. Registered in `components.yaml` with `type` · `container` · `owner` · `area` |
+| **Container** | Something that **runs its own code or stores its own data** and can be replaced without rebuilding another one. The C4 L2 term, and the value of an LC's `container` field. Two questions decide it and both MUST be yes — `architecture-guide.md` owns the test. Shipping two containers in one release does **not** merge them |
+| **`built`** | A container's one boolean. `true` when we write what is inside it, `false` when we deploy someone else's implementation. It decides whether the container gets an L3, an `LC`, and a heading in the codebase map — V25 checks all three |
+| **External system** | Something the product talks to whose **runtime we do not deploy**. It belongs at C4 L1, and MUST NOT be a container, an `LC`'s `container`, or a heading in the codebase map. What we lean on it for lives in `cross-cutting.md` or an integration contract |
+| **`_platform`** | **Not a component.** The home for what belongs to no Product Component: the spine, the C4 set, `cross-cutting.md`, the three inventories, and whatever it **owns**. A legitimate value in every position that asks which component owns something — `platform_owns`, an inventory row, an `LC`. Four kinds today: data · endpoint · job · screen. It carries no `mode`, no `risk_accepted`, and no G4 |
+| **Library** | An includable artifact — compiled into or imported by something else, never run on its own. Not a container |
+| **Slot** | A numbered sub-folder of a PC. `.what/<pc>/` 02–05 is reading order; `.how/<pc>/` 01–06 is ABCE classification. The two numberings do **not** mean the same thing |
+| **Kernel** | The `SRS-<pc>.md` or `SDD-<pc>.md` file itself. Content SHOULD stay in it until it grows past roughly 400 lines — a suggestion, not a threshold |
+
+A PC is not a container: a container runs, a PC is a domain. One container holds several PCs, and
+one PC may appear in more than one container. Because they cross, neither list implies the other, and
+the crossing MUST be written down rather than inferred — that is the PC × container matrix at C4 L2,
+rendered from each PC's `containers:`.
+
+## Flow
+
+There is no "stage". The five gates are the only flow vocabulary, and the word **area** is not used at all —
+there is only Product Component.
+
+| Term | Means |
+|---|---|
+| **Gate** | One of five decision points: G1 Problem · G2 Product · G3 Blueprint · G4 Component · G5 Release. Named after what is decided there, not after the work before it |
+| **`mode`** | The one knob for **document depth**, and nothing else. `catalog` · `outline` · `guarded` · `deep`, default `catalog`. Two scopes — global in `index.yaml`, per component in `components.yaml`, and the per-component one wins. **No third scope** |
+| **`risk_accepted`** | The one field for **review intensity**, and nothing else. `low` · `medium` · `high`. It MUST NOT be derived from `mode`, nor `mode` from it |
+| **Blueprint** | The whole-product portrait decided once at G3: one line per use case, table, endpoint, and screen, plus entities, actors, the spine, C4, and cross-component rules. It names a **gate and a skill**, never a document or a folder |
+| **Wave** | One unit of delivered work. Opens at G4 or G5, closes at G5, recorded in `waves.yaml` |
+| **Release** | What a PRD promises. One release MAY span several waves; the relation is data, never inferred from numbering |
+| **Wave size** | `S` ≤3 stories no new FR · `M` 4–12 · `L` >12 or a new container. MAY be raised mid-flight, MUST NOT be lowered. It does **not** choose which gates are active — that is `mode` |
+| **Fast Path** | A fix that skips all gates: ≤1 story, no FR/UC/`AD-N`/domain-model change, no money, personal data, or third-party integration |
+| **Step** | One of the five points inside `wdi-build`'s ship pipeline — plan · build · panel · publish · CI. It is **not** a gate and not a stage, and the word MUST NOT be used for anything at gate altitude |
+
+## Artifacts
+
+| Term | Means |
+|---|---|
+| **Brief** | One problem, one user, one measure. Singleton, spans releases |
+| **PRD** | What is promised for **one initiative**, across every release it touches. FR and NFR numbered from the registry |
+| **SRS** | Per PC: what the system must do. `.what/` — slices space, while the PRD slices initiative. It **exists at every `mode`**, carrying the actor list and the use case catalogue |
+| **SDD** | Per PC: how it is built. `.how/`. At `mode: catalog` it is a skeleton, and that is a finished state |
+| **Inventory** | One of three living registers at product level — tables, endpoints, screens. Written as a plan when there is no code, **derived** from code once there is |
+| **Architecture spine** | `ARCHITECTURE-SPINE.md` — invariants as `AD-N`, each carrying Binds · Prevents · Rule. It constrains; it does not describe |
+| **C4** | L1 system context · L2 containers · L3 components, one file per container. L1+L2 together are what other methods call the HLD |
+| **`DESIGN.md`** | UX per PC, in `.how/<pc>/01-ux/` |
+| **`EXPERIENCE.md`** | The user-facing journey, in `.what/<pc>/04-usecases/` |
+| **`DEC-`** | One decision worth remembering, numbered globally. Lives in `.control/decisions/`. Recording is **not mandatory**; it freezes at `applied`, not at `accepted` |
+| **SPEC** | The machine contract for **one wave**. A projection of `.what/` + `.how/`, and MUST NOT contain anything new. Not read by humans |
+| **Story** | One unit of build. Status is read from its own frontmatter, never copied elsewhere |
+| **Structure map** | `.control/structure-codebase.md` and `structure-document.md` — where things actually are today |
+| **Memlog** | The record of *why* while an artifact was written. Never copied into a document; a source when writing a `DEC-`. It is a **run log**, and it MUST NOT be searched as an index of decisions — `.control/generated/decisions.md` is that |
+
+## Identifiers
+
+| Code | For |
+|---|---|
+| `BG-` · `FR-` · `NFR-` · `UJ-` | Business goal · functional requirement · non-functional requirement · user journey |
+| `UC-` | Use case |
+| `AD-` | An invariant in the architecture spine |
+| `DEC-` | A decision |
+| `LC-` | A Logical Component |
+| `OQ-` | An open question |
+| `RTR-` | An archived retrospective, in `.control/reports/` |
+| `CAP-` | A capability — the planning unit |
+| `NT-` | A non-technical fact |
+| `BUG-` · `HOT-` | A defect · a hotfix |
+| `V1`–`V25` | Validators. `V10` fell and its number is not reused |
+
+IDs are allocated **globally** and never restart per document, per component, or per release. The chain
+that must hold end to end: `BG → FR → UC → story → test`.
+
+`ADR-` is **retired**. It was renamed to `DEC-` on 2026-08-18 with the numbers unchanged, so `ADR-004`
+inside a document frozen before that date is an alias for `DEC-004`, and those documents MUST NOT be
+rewritten for the prefix.
+
+## Registry and generated
+
+| Term | Means |
+|---|---|
+| **Registry** | `.control/registry/` — the source of truth for IDs and plans. Written through `wdi-*` skills |
+| **Generated** | `.control/generated/` — derived from the registry. Written by the generator only, by hand **never** |
+| **RTM** | Requirements traceability matrix. Generated, never hand-maintained |
+| **Validator** | A script that answers what can be counted. It does not replace a gate checklist, which answers what must be judged |
+
+## BMad terms
+
+BMad terms live in a WDI glossary because WDI runs on BMad. Each is defined **as WDI uses it**;
+where BMad's own meaning is wider, the narrower one here wins.
+
+| Term | Means |
+|---|---|
+| **Stories mode** | The route this method uses: SRS + SDD + PRD → `SPEC.md` + `stories.yaml` → build |
+| **Skill class** | `A` living document, straight to the corpus · `B` living but wrongly granular, lands neutral then is placed · `C` spent after its work · `D` no artifact |
+| **Companion** | A side file a BMad skill produces next to its main output. The lasting ones are promoted by the distillation table |
+| **Distillation** | Promoting what is durable out of `_bmad-output/` before a wave closes. What is not promoted dies with the folder |
+| **`persistent_facts`** | Files a skill always reads. Routing alone does not achieve this |
+| **`doc_standards`** | Rule files a skill checks its output against. Facts MUST NOT be installed here, and neither MUST anything at `status: Reference` |
+| **`{project_knowledge}`** | The config variable pointing at `.control/` |
+| **`_bmad/custom/`** | Where every BMad override lives. `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on update |
+
+## Retired — MUST NOT be used as current
+
+| Retired | Instead |
+|---|---|
+| `ADR-` | `DEC-` — same numbers, new prefix |
+| `ANX-`, and the annex concept | Nothing. Zero annexes were ever born |
+| `SCP-` | A `DEC-` of `type: course-correction` |
+| `layer:` on a decision | `touches:`, filled from what actually changed |
+| "Stage 1"…"Stage 5" as flow vocabulary | The five gates |
+| `epics.md` · `sprint-status.yaml` · `bmad-sprint-planning` · `bmad-create-epics-and-stories` | The stories route: `SPEC.md` + `stories.yaml`, status in story frontmatter |
+| Validator `V10` | Nothing. Its number is not reused |
+| `bmad-help` as the answer to "where am I" | `wdi-help` |
+| The skills `wdi-analysis` · `wdi-architecture` · `wdi-design` · `wdi-glossary` · `wdi-structure` · `wdi-apply` · `wdi-correct-course` · `wdi-wave` · `wdi-ship-story` · `wdi-product-brief` · `wdi-meeting` · `wdi-project-log` | The fifteen in `method/README.md`. `method/rationale.md` says which absorbed which, and why |
+| An Indonesian synonym for a `mode` value — *ringkas*, *terjaga*, *katalog* as prose | The English value, used as written: `catalog` · `outline` · `guarded` · `deep` |
+
+## Synonyms that MUST NOT be coined
+
+A synonym for a term that already has an entry is drift, and `wdi-reconcile` hunts for it.
+
+| Do not say | Say | Because |
+|---|---|---|
+| application · app · service, for a deployable | **container** | The term is already defined at C4 L2 and carried by every LC |
+| infrastructure · third-party · dependency, for something inside the boundary | **container** with `built: false` | Calling it something else is how a container ends up with no row, no owner, and no NFR |
+| container, for something whose runtime we do not deploy | **external system** | It has no `built`, no L3, and no heading. Registering it as a container promises a section of the codebase map that will never exist |
+| module · package, for a unit of build | **Logical Component** | `components.yaml` names it, and V12 resolves against that name |
+| epic · sprint, for a batch of work | **wave** | Both belong to the sprint route this method dropped |
+| area, for a domain slice | **Product Component** | The word "area" is not used anywhere in this method |
+| platform, for a Product Component | **`_platform`**, and only for what is not one | Registering `_platform` as a PC gives it a `mode`, an SRS, and a G4 it has no use for |
+| profile · tier · level, for document depth | **`mode`** | One knob, four values, and no matrix behind it |
+| feature, for a domain slice | **Product Component** | A feature is a promise; a PC is a folder pair with an owner |
+| requirements document | **PRD** or **SRS** | They cut different axes — time versus space — and merging the names merges the documents |
+
+## Rules
+
+- A new method term MUST be added here in the same pass it first appears, not defined where it is
+  used. Adding one is a change to the **method itself** — `wdi-blueprint` MAY propose it and MUST NOT
+  write it, because a method term binds every project the method is installed in.
+- One term MUST NOT have two entries. Two meanings mean two terms.
+- A domain term MUST go to `.control/product-glossary.md` instead. If it is unclear which, ask whether the
+  term would survive being applied to a different product: yes → here, no → there.
+- Common technical terms stay in English when the industry name is the one that matches the code,
+  the error message, or the reader's expectation.

package/kit/.constitution/project/README.md

@@ -0,0 +1,68 @@
+---
+status: Accepted
+scope: project-room
+---
+
+# `.constitution/project/` — this product's custom rules
+
+**This folder belongs to the product, not to the method.** It is seeded once at install, and after
+that `wdi-method update` **never** writes over a file in it. `wdi-method promote` **skips it entirely**,
+so nothing you write here can reach the public package.
+
+This README is the one exception: it is authored in the package and `promote` never carries it home.
+You MAY edit it, but the edit will not survive the next install elsewhere — so **your rules MUST be
+other files.**
+
+## What goes here
+
+Normative rules that hold **only in this product**, and are not code conventions:
+
+- a review policy a client requires
+- a process rule that came out of a contract
+- a naming or language policy that differs from the method default
+- a prohibition or obligation specific to this domain
+
+## What does not
+
+| The thing | Its home |
+|---|---|
+| Product or client name | `.control/registry/index.yaml` → `product:` |
+| Code conventions, stack, brownfield patterns | `.constitution/codebase/*-guide.md` — already protected once `Accepted` |
+| Scope, method ownership, repo checklist | `constitution.md` Articles 1, 2, 5 — already protected |
+| Agent instructions for this product | `AGENTS.md`, **outside** the marked `wdi-method` block |
+| BMad overrides for this product | `_bmad/custom/*.user.toml` |
+| State, promises, design | `.control/` · `.what/` · `.how/` |
+
+**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.
+
+## The shape of a file here
+
+Frontmatter is required, and `V27` checks it:
+
+```yaml
+---
+scope: project              # REQUIRED, and exactly this value
+purpose: ""                 # REQUIRED, one line: what this rule protects
+overrides: null             # optional: the kit file it narrows or contradicts
+decision: null              # REQUIRED when `overrides:` is set — the DEC- that decided it
+---
+```
+
+- A file here MAY **narrow** or **add to** a generic rule with no `overrides:` at all.
+- To **contradict** a generic rule it MUST name that rule in `overrides:` and carry `decision:`.
+  Without both, this room becomes the place where generic rules are broken with no trace — and that is
+  what stops a method being trustworthy in the next repo.
+- An `overrides:` pointing at a file that does not exist is a finding, not a typo: it means the rule
+  being contradicted is gone, and the contradiction may no longer have a reason.
+
+## Why whole files, and not marked blocks
+
+`AGENTS.md` uses a marked block because it is **one** file. `.constitution/` has fifty-odd, and marked
+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 forever.
+
+Whole files in their own room avoid both, and they keep a product's rules **readable in one place**
+instead of scattered inside fifty files that belong to somebody else.

package/kit/.constitution/repo-guide.md

@@ -0,0 +1,97 @@
+---
+status: Accepted
+---
+
+# Repo Guide
+
+**Loaded when:** adding a file that is neither code nor corpus, or unsure whether something may be
+kept in this repo
+
+Every other guide answers *where in the corpus does this go*. This one answers the question that
+comes before it: **does it belong in this repository at all?**
+
+## What this repository is
+
+One product, built for one owner. It holds what is needed to build and run that product, and
+nothing that merely relates to it commercially or organisationally.
+
+| MAY be here | MUST NOT be here |
+|---|---|
+| Application code, configuration, migrations, tests | Proposals, contracts, meeting notes with the client |
+| The corpus — `.constitution/` `.control/` `.what/` `.how/` | Contract values, pricing strategy, margins, rate cards |
+| Technical documentation, ADR, diagrams | Real customer data, production credentials, tokens |
+| Synthetic seed data | Anything whose leak would harm a bargaining position |
+| Built deliverables | An archive of commercial documents |
+
+The test is not "is it secret". It is **what changes when this file changes** — a commitment, or how
+the thing is built. Only the second belongs here.
+
+## Two failure modes, and why the second is worse
+
+The obvious one is a credential in a commit. It is loud, it is caught, and it has a known remedy.
+
+The quiet one is a **commercial fact restated as a technical one** — a limit that exists because of
+what was negotiated, written into an ADR as though it were an engineering constraint. It survives
+every scan, it is never noticed as a leak, and it teaches the next reader that the boundary is
+soft.
+
+When a technical decision genuinely follows from a commercial one, the ADR MUST state the technical
+fact and MUST NOT state the commercial one. *"Retention is 90 days"* is a technical fact.
+*"Retention is 90 days because the client would not pay for more"* is a commercial one wearing a
+technical coat.
+
+## `.work/` — scratch that is committed
+
+`.work/` holds work in progress that has no home yet: notes while reading an unfamiliar system,
+drafts, exploratory output, a working paper for a change spanning several sessions.
+
+It is **committed**, so that a session picked up on another machine finds it, and so a reviewer can
+see what a change was actually reasoning about.
+
+It is **ephemeral**, and the two together are what make its rules matter:
+
+- Any durable outcome MUST be moved out before the task closes — to the corpus if it is truth, to
+  `_bmad-output/` if it is a run's byproduct.
+- Obsolete scratch MUST be deleted when its task closes. `.work/` that only grows stops being
+  scratch and becomes a second, unindexed corpus that nobody trusts and nobody deletes.
+- Secrets and commercial figures MUST NOT be written here. Being scratch is not an exemption; it is
+  the reason people assume it is one.
+- Nothing MUST be read from `.work/` as authority. If something there is right, it belongs
+  somewhere with an owner.
+
+`.work/` MUST NOT be confused with `_bmad-output/`. That folder holds the output of skill runs, is
+never curated, and is cited by path. `.work/` holds what a human or agent wrote by hand while
+working, and is meant to empty out.
+
+## Referring to things outside this repository
+
+Engagement context — who the client is, what was agreed, what is due — lives elsewhere. This repo
+MUST work without it. An agent MUST be able to act on the rules stated here without opening any
+other repository.
+
+When an artifact genuinely needs external context:
+
+- MUST state the technical fact locally, in full.
+- MAY name the external source by **repository and path**, as provenance.
+- MUST NOT paste the external content in, and MUST NOT replace a technical statement with a pointer
+  to a commercial document.
+
+A pointer where a specification should be is the failure this rule exists to stop: the reader who
+cannot open that path is left with nothing, and the reader who can is reading the wrong kind of
+document.
+
+## How the method arrives
+
+Method files in `.constitution/` (except this product's Articles 1, 2, and 5, `codebase/*-guide.md`
+once `Accepted`, and any extra file this repo added), the `wdi-*` skills, and `_bmad/custom/*.toml`
+arrive from the public WDI Method package via `npx wdi-method install` / `update`.
+
+At **read time** this repo is self-contained: every file the rules need is here, readable with the
+repo alone. At **change time** the method has one published writer — the WDI Method package. Two
+rules follow:
+
+- A method file MUST NOT be invented or patched here to improve the method. If a rule is wrong, it
+  is fixed in the WDI Method package, then brought here with `update`.
+- A rule particular to this repo MUST be written out in full, and MUST NOT be replaced by a pointer
+  into another repository.
+