wdi-method 0.4.6 → 0.5.2

package/kit/.constitution/method/README.md

@@ -1,169 +1,73 @@
----
-status: Reference
----
-
-# The WDI Method — orientation
-
-**Opened when:** you have never seen this method before, or you have and want the shape back in one reading.
-
-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.
-
-Five minutes. Three files in this folder: this one for orientation, `artifact-map.md` for *"where does this
-file go"*, `rationale.md` for *"why is it like this"* — open that one before changing a rule, so you know
-what you are about to break.
-
-## What the method is
-
-Two methods joined. **WDI** owns the flow, the gates, and the artifacts nobody else writes. **BMad** owns
-the writing skills where it has one. Every BMad skill is invoked through a WDI wrapper, never directly: the
-wrapper is what checks position, verifies the result against the guide, and lands the memlog.
-
-The whole thing rests on one sentence:
-
-> Owner time is spent at five points. Between them, the agents work alone.
-
-## Five gates
-
-A gate is named for **what is decided there**, never for the work before it.
-
-| Gate | Decides | How often | Budget |
-|---|---|---|---|
-| **G1 Problem** | What the problem is, whose it is, why it earns work | once | 20' |
-| **G2 Product** | What is built, and how it feels to use | once per PRD | 45' |
-| **G3 Blueprint** | The whole portrait: which use cases, their entities, tables, endpoints, screens, and the invariants binding them | once per **product** | 45' |
-| **G4 Component** | How one Product Component is built, and what the choice costs | once per **component** | 20–30' |
-| **G5 Release** | Whether it is done and proven | once per wave | 10' |
-
-**Only G4 changes shape.** The other four are always the same, whatever the settings — and that is what lets
-the whole system be held in one head.
-
-## Two settings, and they control different things
-
-| Setting | Where | Controls |
-|---|---|---|
-| `mode` | globally in `index.yaml`, per component in `components.yaml` | **Document depth**, and only that |
-| `risk_accepted` | per component | **Review intensity**, and only that |
-
-`mode` takes `catalog` · `outline` · `guarded` · `deep`, and the default is `catalog`. A component at
-`catalog` **skips G4 entirely** — its control moved to G3, where its use cases, tables, endpoints, screens,
-domain model, and C4 were all approved.
-
-`risk_accepted` takes `low` · `medium` · `high`, and its direction reads off the name: `high` means *"I
-accept a lot of risk here"*, so its review is the lightest.
-
-Keeping them apart is what lets one component be **thin on purpose and reviewed the hardest**. Why that
-matters is in `rationale.md`; what each value demands is in `document/delivery-flow-guide.md`.
-
-## The run, first time through
-
-| # | Step | Run | Gate |
-|---|---|---|---|
-| 0 | Set up | `wdi-init` intent `setup` — registry scaffolded, global `mode` set, existing documents reported, structure maps derived | — |
-| 1 | Discovery and brief | `wdi-problem` | **G1** |
-| 2 | PRD, one per initiative | `wdi-product` intent `prd` | **G2** |
-| 2b | UX — only when the interface is a large part of the promise | `wdi-ux` | with G2 |
-| 3 | Birth the components, set `mode` and `risk_accepted` | `wdi-init` intent `component` | — (tail of G2) |
-| 4 | Blueprint | `wdi-blueprint` intent `catalog`, then `platform` | **G3** |
-| 5 | One component's depth | `wdi-component` — as deep as its `mode`; **skipped at `catalog`** | **G4** |
-| 6 | Build | `wdi-build` — opens the wave, runs `bmad-spec`, ships each story, closes the wave | **G5** |
-
-After step 6 the next component enters at **step 5**, not at the beginning. Steps 0–4 happen once in the
-life of the product.
-
-`SPEC.md` and story files are **not read by humans**. The human review surface stops at the PRD, `.what/`,
-and `.how/`.
-
-## The run, every time after
-
-| Situation | Run |
-|---|---|
-| The next component is being taken on | `wdi-init` intent `mode` or `risk` if either needs changing → `wdi-component` → **G4** → `wdi-build` → **G5** |
-| That component is at `mode: catalog` | straight to `wdi-build`. G4 is skipped |
-| A promise changes where a PRD already exists | `wdi-product` intent `update` — never a second PRD for the same area |
-| A new initiative with a different reader | `wdi-product` intent `prd` → `wdi-init` intent `component` if it births components |
-| A small fix touching no `FR`, `UC`, `AD-N`, or domain model | Fast Path: `bmad-build` directly. It **stops and becomes a wave `S`** the moment an `FR` is touched |
-| A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, **before** any fix is proposed |
-| A planning assumption turned out void | `wdi-decision` — it wraps `bmad-correct-course`, proposes, and changes nothing itself |
-| An estimate or a task list is needed | `wdi-report` intent `estimate` |
-| You do not know where you are | `wdi-help` |
-
-## Fifteen skills
-
-Named for the **gate they serve**, so *"which skill do I run"* is answered by *"which gate am I at"*.
-
-**Moment-bound** — running them outside their point is wrong:
-
-| Skill | Its moment |
-|---|---|
-| `wdi-init` intent `setup` | before G1, once per project |
-| `wdi-problem` | G1 |
-| `wdi-product` | G2 |
-| `wdi-init` intent `component` | tail of G2, and whenever a new PRD births a component |
-| `wdi-blueprint` | G3 |
-| `wdi-component` | G4 |
-| `wdi-build` | G5, one wave per run |
-
-**Anytime** — run the moment the trigger appears, without waiting for a gate:
-
-| Skill | Its trigger |
-|---|---|
-| `wdi-decision` | A decision worth remembering · a void assumption · an accepted decision to carry into documents |
-| `wdi-question` | Something that cannot be decided now |
-| `wdi-log` | A meeting finished, or a non-technical fact now binds |
-| `wdi-help` | "Where am I, what next" |
-| `wdi-reconcile` | Any time. Read-only — it reports, it never edits |
-| `wdi-review` | Over any document, any time |
-| `wdi-systematic-debugging` | A bug, a failed test, a failed build, unexpected behaviour |
-| `wdi-report` | An estimate at the start · progress periodically · before a client update |
-| `wdi-init` intents `mode` · `risk` · `structure` | Any time |
-| `wdi-ux` | Any time after a PRD exists, if UX is being used |
-
-## Who writes what — WDI and BMad
-
-| Artifact | Written by | Wrapped in |
-|---|---|---|
-| Product brief | `bmad-product-brief` | `wdi-problem` |
-| PRD | `bmad-prd` | `wdi-product` |
-| UX | `bmad-ux` | `wdi-ux` |
-| Spine + C4 | `bmad-architecture` | `wdi-blueprint` |
-| **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 | `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 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 stick to those artifacts and are handled
-deliberately: no `doc_standards` fires a review, no memlog is born on its own, and no template enforces
-itself.
-
-## Where things live
-
-| The thing in your hand | Its folder |
-|---|---|
-| How we work — a rule, a guide, a template | `.constitution/` |
-| What currently holds — a decision, a question, a registry, a map | `.control/` |
-| What is promised — the brief, a PRD, a use case, a business rule | `.what/` |
-| How it is built — the spine, C4, an inventory, an SDD, a contract | `.how/` |
-| A skill run's working output | `_bmad-output/` |
-| Scratch that empties when the task closes | `.work/` |
-| The application | `src/` · `web/` |
-
-The test that settles anything ambiguous: **is this file still correct after its wave has passed?** Yes →
-the corpus. No → `_bmad-output/`. In doubt, `document/corpus-guide.md`.
-
-## Model choice
-
-| Point | Model |
-|---|---|
-| Decisions — proposing a slicing, wording a `DEC-`, preparing a gate | `opus@high` |
-| Writing, derivation, a review-fix pass | `sonnet@high` |
-| Code review panel | Two different CLI families, and never the family that wrote the code |
-
-In a derivation pass, quality comes from the input rather than the model. Running a "find the gap" lens with
-the most careful model produces the most gaps, and each one becomes an open question — a cost nobody sees
-until the question list has stopped being readable.
+---
+status: Reference
+---
+
+# `.constitution/method/` — index
+
+`.constitution/` holds **exactly two folders**, and the folder is what says who owns a file:
+
+| Folder | Owner | `update` | `promote` |
+|---|---|---|---|
+| `method/` — you are in it | the method | **overwritten** in full | carries it into the package |
+| [`../project/`](../project/) | this product | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
+
+Load [`constitution.md`](constitution.md) and [`../project/constitution.md`](../project/constitution.md)
+before acting: Articles 3, 4, 6, 7 are here, Articles 1, 2, 5 are yours. Guides are loaded **lazily** —
+only when the task matches, and every guide states when on its own **Loaded when:** line.
+
+Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
+`Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
+own, because its frontmatter belongs to the artifact it produces.
+
+**A file this product adds MUST go in [`../project/`](../project/), not here** — anything in `method/`
+is replaced on the next update, without warning, because that is what `method/` means. This index is
+overwritten too.
+
+## `why/` — the explanation, `status: Reference`
+
+Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
+
+| File | Opened when |
+|---|---|
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
+| [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
+| [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |
+| [`why/portability.md`](why/portability.md) | Which files are the method and which are the product; how promote and install move them |
+
+## Cross-domain
+
+| File | Loaded when |
+|---|---|
+| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
+| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
+| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
+| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
+
+## `document/` — document rules
+
+| File | Governs |
+|---|---|
+| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
+| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
+| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
+| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
+| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
+| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
+| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
+| [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
+| [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
+
+## Code rules — in the room, not here
+
+All three are written by the **product**, so they live in [`../project/`](../project/) and no update
+touches them at any `status:`. While `Draft`, their contents MAY be read as guidance but MUST NOT be
+used to reject a change.
+
+[`stack-guide.md`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
+
+## `scripts/`
+
+`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
+dimension from git history. `inventory.py` — derives the three inventories from code and reports the
+difference against the plan; it MUST NOT patch either side into agreement. All three run through
+`uv run`.

package/kit/.constitution/{constitution.md → method/constitution.md}

@@ -2,39 +2,15 @@
 status: Accepted
 ---
 
-# Constitution — {product}
+# Constitution — the method's articles
 
-Rewrite Articles 2 and 5 for the product this repo is. Article 1 cites
-`.control/registry/index.yaml` — replace `{product}` there at G1, not here.
-Articles 3, 4, 6, and 7 are the method and travel unchanged.
+Articles 3, 4, 6, and 7. They are the **method's** and arrive from the WDI Method package —
+`update` overwrites this file, so it MUST NOT be edited here.
 
-An agent working here MUST be able to act on the contents of this repo alone.
-
-## Article 1 — Scope
-
-This repo covers the product named at `product.name` in
-`.control/registry/index.yaml`. One product, one repo. A second product MUST
-get a repo of its own.
-
-`product.client` in the same file names the client if there is one, and stays
-empty if there is not. The product brief at G1 uses `product.name` as its
-title. Neither this file nor the brief is a second source of the name.
-
-An agent working here MUST NOT demand that sibling organisation repositories
-be open in the same session.
-
-## Article 2 — Content boundary, `.work/`, and cross-repo references
-
-All three are governed by [`repo-guide.md`](repo-guide.md). Its rules MUST NOT be
-repeated here — one rule, one place.
-
-What is particular to this repo, and therefore lives here:
-
-- Name any extra boundary this product has (a public-repo rule, a ban on `3p.md`,
-  a `.work/` resting state). If there is none, delete this bullet list and the
-  sentence above it.
-- `3p.md` MUST NOT be created in a product repo. Operational engagement memory
-  lives outside.
+This product's own articles — 1 Scope, 2 Content boundary, 5 Method ownership — live in
+[`../project/constitution.md`](../project/constitution.md), which `update` never touches. The
+numbering is shared across the two files and has gaps in each; the numbers are **not** reassigned,
+because a frozen record that cites one MUST NOT be rewritten.
 
 ## Article 3 — Layers
 
@@ -43,13 +19,13 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 
 | Path | Role |
 |---|---|
-| `.constitution/` | Rules — how we work. `method/` holds the non-binding explanation of them |
+| `.constitution/` | Rules — how we work. Exactly two folders: `method/` is the method's and is overwritten by `update`, `project/` is this product's and is never touched. `method/why/` holds the non-binding explanation of the rules |
 | `.control/` | Control — what currently holds and what has been decided |
 | `.what/` | What is promised |
 | `.how/` | How it is built |
 | `_bmad-output/` | Run workspace; committed, not curated |
 | `.work/` | Scratch; committed, emptied when a task closes |
-| *(application roots)* | Application code — name them in this row |
+| *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |
 
 The method does not use a `docs/` layer for corpus or rules. A leftover `docs/`
 folder is inventory to sort, not a second home.
@@ -73,33 +49,11 @@ so a status there would land in the artifact and mean something else entirely.
 A missing header anywhere else is a **finding**, not an implicit anything.
 
 `Reference` exists so that the *explanation* of a rule can live beside the rule without competing with it —
-`method/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
+`method/why/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
 one wins, and the disagreement MUST be reported as a defect rather than resolved by preferring whichever was
 opened first. A rule MUST NOT be born in a `Reference` file; when one is noticed there, it is stated as a
 finding and written in the guide that owns it.
 
-## Article 5 — The method arrives from WDI Method
-
-This is the **consumer** article. Use it in every product repo.
-
-`.constitution/` guides and templates (except this file's Articles 1, 2, and 5,
-`codebase/*-guide.md`, 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`.
-
-- 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`.
-- `wdi-method update` MUST overwrite method files and MUST NOT touch `.what/`,
-  `.how/`, `.control/` product state, this file's Articles 1–2 and 5,
-  `codebase/*-guide.md` once `Accepted`, extra constitution files this repo
-  added, or `_bmad/custom/*.user.toml`.
-- A rule particular to this repo MUST be written out in full in this file or a
-  sibling, and MUST NOT be replaced by a pointer into another repository.
-
-A prefix in `.claude/skills/` names the **method**, not the owner: `bmad-*` is
-BMad's, `wdi-*` is this method's.
-
 ## Article 6 — Decisions
 
 A decision worth remembering is a `DEC-NNN`. Its shape, the one test that decides whether it is