wdi-method 0.3.0

package/kit/.constitution/README.md

@@ -0,0 +1,66 @@
+---
+status: Reference
+---
+
+# `.constitution/` — index
+
+Method files arrive from the public WDI Method package via `npx wdi-method install`
+or `update`. Load [`constitution.md`](constitution.md) before acting. 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 added (one that is not in the snapshot) stays here across `update` and MUST be
+listed from `constitution.md` Article 2 or from `AGENTS.md` routing — this index is overwritten on
+every update.
+
+## `method/` — 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 |
+|---|---|
+| [`method/README.md`](method/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
+| [`method/artifact-map.md`](method/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
+| [`method/rationale.md`](method/rationale.md) | Before changing a rule, to know what you would break |
+| [`method/portability.md`](method/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 |
+
+## `codebase/` — code rules
+
+All three are written by the **project**, not the kit. While `Draft`, their contents MAY be read as
+guidance but MUST NOT be used to reject a change.
+
+[`stack-guide.md`](codebase/stack-guide.md) · [`conventions-guide.md`](codebase/conventions-guide.md) · [`brownfield-guide.md`](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/codebase/brownfield-guide.md

@@ -0,0 +1,18 @@
+---
+status: Draft            # Article 4: Draft MAY be read as guidance, MUST NOT reject a change
+ratified_by: null        # the commit whose content ratifies this file
+---
+
+# brownfield — codebase guide
+
+**Loaded when:** writing or reviewing code.
+
+> **Born empty on purpose.** This file is filled by the first wave's distillation — `bmad-spec`'s
+> `brownfield.md` companion is promoted here before the wave closes.
+>
+> Writing it up front means guessing at a convention no code has yet. It MUST NOT be filled before
+> code exists that ratifies it.
+
+> **Status.** While `draft`, its contents MAY be read as guidance but MUST NOT be used to reject a
+> change. It rises to `accepted` when the first wave's distillation fills it from real code, and
+> `ratified_by` MUST then carry the commit holding that code.

package/kit/.constitution/codebase/conventions-guide.md

@@ -0,0 +1,18 @@
+---
+status: Draft            # Article 4: Draft MAY be read as guidance, MUST NOT reject a change
+ratified_by: null        # the commit whose content ratifies this file
+---
+
+# conventions — codebase guide
+
+**Loaded when:** writing or reviewing code.
+
+> **Born empty on purpose.** This file is filled by the first wave's distillation — `bmad-spec`'s
+> `conventions.md` companion is promoted here before the wave closes.
+>
+> Writing it up front means guessing at a convention no code has yet. It MUST NOT be filled before
+> code exists that ratifies it.
+
+> **Status.** While `draft`, its contents MAY be read as guidance but MUST NOT be used to reject a
+> change. It rises to `accepted` when the first wave's distillation fills it from real code, and
+> `ratified_by` MUST then carry the commit holding that code.

package/kit/.constitution/codebase/stack-guide.md

@@ -0,0 +1,18 @@
+---
+status: Draft            # Article 4: Draft MAY be read as guidance, MUST NOT reject a change
+ratified_by: null        # the commit whose content ratifies this file
+---
+
+# stack — codebase guide
+
+**Loaded when:** writing or reviewing code.
+
+> **Born empty on purpose.** This file is filled by the first wave's distillation — `bmad-spec`'s
+> `stack.md` companion is promoted here before the wave closes.
+>
+> Writing it up front means guessing at a convention no code has yet. It MUST NOT be filled before
+> code exists that ratifies it.
+
+> **Status.** While `draft`, its contents MAY be read as guidance but MUST NOT be used to reject a
+> change. It rises to `accepted` when the first wave's distillation fills it from real code, and
+> `ratified_by` MUST then carry the commit holding that code.

package/kit/.constitution/constitution.md

@@ -0,0 +1,135 @@
+---
+status: Accepted
+---
+
+# Constitution — {product}
+
+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.
+
+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.
+
+## Article 3 — Layers
+
+The repo layout is governed by `corpus-guide.md` and mapped by
+`.control/structure-document.md`. What MUST be known before opening either:
+
+| Path | Role |
+|---|---|
+| `.constitution/` | Rules — how we work. `method/` holds the non-binding explanation of them |
+| `.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 |
+
+The method does not use a `docs/` layer for corpus or rules. A leftover `docs/`
+folder is inventory to sort, not a second home.
+
+## Article 4 — Lifecycle
+
+Every `.constitution/` file MUST carry a `status:` frontmatter, and it MUST be one of five:
+
+| Status | Means |
+|---|---|
+| `Accepted` | **Binds.** It MAY be cited as the reason to reject a change |
+| `Reference` | **Explains, does not bind.** It MUST NOT be cited as the reason to reject a change, and MUST NOT be installed as `doc_standards` or `persistent_facts` |
+| `Draft` | Not settled. Its contents MAY be read as guidance but MUST NOT be used to reject a change |
+| `Superseded` | Replaced. It MUST name its replacement |
+| `Cancelled` | Withdrawn without a replacement, and kept so nobody rewrites it |
+
+**One exception, by construction:** a file in `document/templates/` MUST NOT carry a `status:` of its own.
+A template's frontmatter is the *artifact's* frontmatter — it is copied into what the template produces —
+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`
+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
+recorded at all, global numbering, the `draft → accepted → applied` status ladder, and supersession
+are governed by [`document/decision-guide.md`](document/decision-guide.md). Decisions live in
+`.control/decisions/` and are registered in `.control/registry/decisions.yaml`.
+
+Recording a decision is **not mandatory**, and one case is: a decision that contradicts or changes an
+`AD-N`. The guide owns both halves and they MUST NOT be restated here.
+
+The name ADR is retired, along with `layer:` and `component:` on a decision. `ADR-NNN` appearing in a
+document frozen before that date is a retired alias for `DEC-NNN`, and those documents MUST NOT be
+rewritten for the prefix. A course correction is a `DEC-` of `type: course-correction`.
+
+## Article 7 — Non-technical facts
+
+A non-technical fact that constrains what may be built, used, or promised — a domain now held, a
+third-party account now active, the legal entity a screen must name, a date that locks scope — MUST
+be recorded in `.control/project-non-technical-log.md`, and MUST NOT be scattered into a `DEC-`, a
+PRD, or a code comment as though it were an engineering constraint.
+
+That file states its own entry shape, its closed category list, and which facts belong to another
+home instead. It MUST be written through the skill `wdi-log` intent `fact`, never by hand.
+
+Two boundaries hold over it and MUST NOT be relaxed there:
+
+- The content boundary in [`repo-guide.md`](repo-guide.md). This file is not an exemption from it;
+  a commercial fact does not become admissible by being called non-technical.
+- Article 2's ban on `3p.md`. Operational engagement memory stays outside this repo, and the log
+  MUST NOT grow into a substitute for it.
+
+It is control, not chronology. What happened on a given day is recovered from git by `wdi-report`;
+what is recorded here is what still holds.

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

@@ -0,0 +1,209 @@
+---
+status: Accepted
+---
+
+# Architecture Guide
+
+**Loaded when:** writing or changing the architecture spine, an `AD-N`, or the C4 set
+
+The spine holds the invariants that stop separately built components from diverging. It is not a design
+document — one component's design is its `SDD-<pc>.md`. If a statement only affects one component, it does
+not belong here.
+
+The spine, the C4 set, `cross-cutting.md`, and the three inventories are all **G3 Blueprint** output, written
+by `wdi-blueprint` intent `platform`. All of them exist at every `mode`, including `catalog`: they belong to
+the blueprint, and the blueprint is not touched by the depth knob.
+
+## Home
+
+`.how/_platform/ARCHITECTURE-SPINE.md` — a file directly in `_platform/`. The `architecture/` sub-folder is
+**repealed**; one file does not earn a folder, and the extra level made the spine harder to find than the
+things it constrains.
+
+## Invariants only
+
+An entry earns a place when breaking it in one component would break another. Everything else is a **seed**:
+useful as a starting point, not binding.
+
+| Kind of statement | Spine? |
+|---|---|
+| "Every service authenticates through the same token format" | Yes — invariant |
+| "Money is stored as integer minor units, never float" | Yes — invariant |
+| "We use MariaDB 11 and Go 1.23" | No — seed. It informs, it does not forbid |
+| "The repo is laid out as `src/` and `web/`" | No — seed, and `structure-codebase.md` describes it |
+| "The member portal caches its dashboard for 60 seconds" | No — one component's design |
+
+Stack, tree shape, and data shapes are seeds and MUST be marked as such. Writing them as contracts makes the
+spine wrong the first time anything is upgraded, and a spine that is wrong in a visible place stops being
+read in the places where it is right.
+
+## Every `AD-N` carries three things
+
+| Field | States |
+|---|---|
+| **Binds** | Which components or containers this holds for. "All" is a valid answer and MUST be written, not left blank |
+| **Prevents** | The concrete failure this exists to stop. Written as the thing going wrong, not as a principle |
+| **Rule** | One sentence, quotable, checkable. If a reviewer cannot tell whether code obeys it, it is not a rule yet |
+
+An `AD-N` with no **Prevents** is a preference. Preferences belong in
+`.constitution/codebase/conventions-guide.md`, where nothing has to justify itself.
+
+## The spine stops being touched every story
+
+This is the change that ends the tax that was being paid before the information existed.
+
+- **The spine holds invariants and nothing else.** It changes only when an `AD-N` is born or reversed, and
+  both are decision events. For a mid-sized product: once at the start, around 6–10 `AD-N`, then almost
+  never.
+- **A story MUST NOT touch the spine.** A story that contradicts an `AD-N` **stops** and opens a `DEC-` —
+  the one case where recording a decision is still mandatory.
+- **Editing an `AD-N` MUST NOT quietly reverse it.** A reversal is a decision, and it goes through
+  `wdi-decision` first.
+- **An inventory is not the spine.** The three inventories are living registers, derived from code once code
+  exists. A plan-versus-reality difference is a validator finding, not a spine amendment.
+
+## `AD-N` versus `DEC-NNN`
+
+`AD-N` is a **living rule**, edited in place as understanding improves. `DEC-NNN` is a **decision event**,
+never edited once `applied`, only superseded.
+
+An `AD-N` usually has a `DEC-` behind it: the invariant is what people obey, the decision record is why it
+exists and what it cost. The full comparison is in `decision-guide.md` and MUST NOT be restated here.
+
+The spine MUST NOT name a decision's alternatives or its cost. Those live in the `DEC-` behind it; repeating
+them here creates a second version that will drift.
+
+## The C4 set, and what else a run produces
+
+`bmad-architecture` runs at **initiative** altitude for the spine. Anything else the run produces at feature
+altitude — a deck, a fuller solution document — is a **rendering**, not the spine, and the two MUST NOT be
+confused:
+
+| Rendering | Has a slot | What follows |
+|---|---|---|
+| The **C4 set** — L1, L2, and one L3 per `built: true` container **holding more than one Product Component** | Yes: `.how/_platform/c4-l1-system-context.md` · `c4-l2-containers.md` · `c4-l3-<container>.md` | `wdi-blueprint` lands it, amending rather than overwriting. Once landed it is corpus, and `c4-l2-containers.md` **owns** the container list. The next section owns what a container *is* |
+| Deck, solution document, anything else | No | Stays in the run folder, cited by path, never promoted |
+
+**Placement is what makes a C4 binding, and only for what its level owns.** Before placement it is one run's
+drawing; after, it is the corpus's description of the system. The spine still wins on any invariant, because
+the C4 set describes and the spine forbids. A C4 file MUST NOT be used to justify a rule; a rule that matters
+belongs in an `AD-N`.
+
+The C4 set is **living**. It is amended when a container is added or changed — it MUST NOT be regenerated from
+scratch, which would drop the annotations three waves of amendment put there.
+
+## What counts as a container, and what does not
+
+Two questions, and **both MUST be yes**:
+
+1. **Does it run its own code or store its own data?** Its own process, its own browser page, its own
+   engine — not a folder inside another container's process.
+2. **Can it be replaced without rebuilding another container?** It has its own build or publish path.
+
+**Shipping two containers in one release does not merge them.** One atomic deploy swapping a binary and
+two browser bundles together is a deployment choice, and a deployment choice MUST NOT be read as an
+architectural one. The failure this guards against is the quiet one: a browser bundle with its own
+JavaScript filed as "static assets" of the web server, carrying real behaviour with no row, no owner, and
+no NFR. Handwritten HTML that runs **no** code of its own is content the web server delivers; the moment
+it carries a script, it passes question 1.
+
+### `built` — the one boolean, and its four consequences
+
+A container is inside the boundary whether or not we wrote it. `built:` records which:
+
+| | `built: true` | `built: false` |
+|---|---|---|
+| An L3 | Yes, where it holds more than one PC | **Never.** No box inside it is ours to draw |
+| An `LC` naming it as `container` | Yes | **Never** |
+| A heading in `structure-codebase.md` | **Required** | **Never** — no code of ours lives there |
+| Listed in a PC's `containers:` | Yes | **Never** — see the matrix below |
+
+V25 checks all four. This is what makes the class settled rather than re-argued: a database and a web
+server are containers, they carry NFRs, and they still produce no design artifact of ours.
+
+**What IS ours about a `built: false` container MUST have a home outside the C4 set** — its configuration
+and any invariant it enforces belong in an `AD-N` or in `cross-cutting.md`. A rule surviving only as a
+note beside a C4 box is a rule nobody can find.
+
+### External system — outside the boundary
+
+**The line is who deploys the runtime.** We deploy it, whoever wrote it → container. Someone else
+runs it and we call it or configure it through their control plane → external system.
+
+An external system appears at **C4 L1 and nowhere else**. It MUST NOT be registered in `containers`,
+MUST NOT be an `LC`'s `container`, and MUST NOT get a heading in the codebase map. What the product
+depends on it for lives in `cross-cutting.md` or an integration contract.
+
+### The PC × container matrix
+
+A PC and a container cross, so neither list implies the other — and the crossing is what a builder needs
+first: *which container does this promise live in, and is it more than one?*
+
+- The **SSOT is each PC's `containers:`** in `components.yaml`; C4 L2 renders it, and V25 fails when the
+  two disagree.
+- Complete at **G3** for every PC. It is blueprint content, so `mode` does not touch it.
+- A PC MUST list every `built: true` container it lives in. Listing only the main one is the error the
+  matrix exists to catch.
+
+### Which C4 files exist, and when
+
+`artifact-map.md` owns the schedule: all three at **G3**, at every `mode`. Two conditions belong here.
+
+**L2 MUST be complete** — every container, plus the matrix. **L3 exists once per `built: true` container
+holding more than one PC**; a one-PC container needs none because the matrix already places it.
+
+**Not one of the three waits for a wave.** Which container a PC lives in cannot be discovered by a wave,
+because a wave picks its stories from that answer — a wave forced to invent it answers a G3 question with
+a fraction of G3's information.
+
+## Cross-cutting
+
+`.how/_platform/cross-cutting.md` holds what is defined once for the whole product, the error envelope first
+among them. Every contract references it rather than restating it.
+
+A rule that belongs there MUST NOT also be written as an `AD-N` unless breaking it in one component breaks
+another. One fact, one home.
+
+**The platform MAY own things, and owning one costs a row here.** `_platform` is a legitimate owner in every
+position that asks which component owns something — a domain entity through `platform_owns`, an inventory row,
+an `LC`. Whatever it owns MUST be described under `## Milik platform` in this file: what it is, its kind, why
+no component's promise explains it, who touches it, and the shape every toucher obeys. V21 checks that second
+half, because a platform that owns something without documenting it has taken ownership without taking
+responsibility.
+
+Four kinds qualify today — data, endpoint, job, screen — and the list is open. What is **not** open is the
+test, and `corpus-guide.md` owns it: no single component's promise explains it, **and** more than one
+component depends on it. Failing either half, it belongs to a component.
+
+`_platform` is **not** a Product Component — `corpus-guide.md` owns that distinction and the test for when an
+entity legitimately belongs here. It has no `mode` and no `risk_accepted`: the documents in this folder exist
+at every mode.
+
+## Binding order
+
+Spine first, then the SDD, then `bmad-spec`. An `SDD-<pc>.md` written before the spine will be rewritten,
+because the constraints it was supposed to inherit did not exist yet. A `SPEC.md` written before the SDD has
+nothing to project. `bmad-spec` MUST keep `AD` ids stable so downstream artifacts can cite them.
+
+## Inheritance downward
+
+From `mode: guarded` up, every `AD-N` that reaches a component MUST appear in that component's SDD under
+**Inherited Constraints**, quoted rather than paraphrased. Below `guarded` the quoting is not written, and the
+spine still binds — an invariant does not stop holding because a document is thin.
+
+## Review is manual here
+
+`bmad-architecture` excludes the spine from `doc_standards` deliberately — the spine is terse by design and
+prose polish softens rules that need to stay rigid. Two consequences:
+
+- This guide is installed as `persistent_facts`, not `doc_standards`.
+- `bmad-review` over the spine MUST be invoked through `wdi-review` before G3 closes.
+
+## Rules
+
+- The spine MUST stay short enough to be read in one sitting. An `AD-N` nobody remembers is not an invariant,
+  it is a document.
+- An `AD-N` MUST NOT be added because something feels important. The test is only ever: does breaking this in
+  one place break another?
+- Structure statements MUST be marked as seeds, and MUST NOT be checked as if they were rules.
+- Memlog goes to `.control/memlog/spine.md` via `--path`, never beside the spine.

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

@@ -0,0 +1,151 @@
+---
+status: Accepted
+---
+
+# BMad Guide
+
+**Loaded when:** invoking any BMad skill, or placing its output
+
+BMad supplies the skills; this method supplies the corpus they write into. This guide states which
+route we run, where each skill's output belongs, and the places where BMad's defaults would put a
+file somewhere this method cannot use.
+
+The per-skill read/write map lives in `bmad-skill-register.md` and MUST NOT be duplicated here.
+
+## Stories mode only
+
+BMad offers two routes. We run one.
+
+| | Sprint route | **Stories route — ours** |
+|---|---|---|
+| Planning artifact | `epics.md` | `.what/<pc>/SRS-<pc>.md` + `SPEC.md` + `stories.yaml` |
+| Status home | `sprint-status.yaml` | Story-file frontmatter |
+| Produced by | `bmad-create-epics-and-stories` · `bmad-sprint-planning` | `bmad-spec` |
+
+`bmad-create-epics-and-stories` and `bmad-sprint-planning` are **NOT USED**. Neither MUST be invoked,
+and neither MUST be named as a gate condition.
+
+The sprint route was dropped because it keeps status in a hand-edited file. Two workers running in
+parallel then contend for one file, and status becomes something a worker declares about itself.
+Reading status from story-file frontmatter removes both problems — V18 checks it.
+
+## Skill classes
+
+The criterion is **lifetime**, not importance:
+
+| Class | Criterion | Output home |
+|---|---|---|
+| **A** | A living document, still correct after the wave | Straight into `.what/` or `.how/` |
+| **B** | Living, but its granularity is not configurable | Neutral `_bmad-output/` → the owner in `corpus-guide.md` lands it |
+| **C** | Ends when its work does | `_bmad-output/`, committed, not curated |
+| **D** | No artifact at all | — |
+
+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.
+
+Which skill lands which class-B output is the ownership table in `corpus-guide.md`. A skill MUST NOT
+write into a layer it does not own.
+
+## `_bmad-output/` is committed but not curated
+
+Committing it makes citation by path stable, so a `DEC-` or a PRD MAY point into it. Two rules follow:
+
+- Nothing there is promoted into the corpus. Research, brainstorming, forge, and PRFAQ output stays
+  where it lands, permanently.
+- A run folder MUST NOT be deleted. The `update` intents re-read the original inputs in place, and
+  `bmad-deep-recon` refresh operates on the existing folder.
+
+## `_bmad/custom/*.toml` are live rules, not documentation
+
+The `persistent_facts` inside them are **injected into every BMad run from activation onward**. A skill
+name that has been deleted, or a folder that no longer exists, left sitting in there is not merely
+stale — it is a live instruction that a worker will carry out.
+
+So every time a `wdi-*` skill is renamed or merged, a folder is deleted, or a document code is
+repealed, `_bmad/custom/*.toml` MUST be swept **in the same pass**. No validator guards it — no `V`
+reads TOML — so the only things guarding it are this rule and a sweep that includes it.
+
+This lesson was paid for: the consistency sweep of 2026-08-18 used a path list that did not include
+`_bmad/custom/`, and five TOML files went on telling workers to land `SCP-` into
+`.control/supplements/` through `wdi-correct-course` — three things that no longer exist. **A
+verification path list MUST be treated as a minimum, never as a boundary.**
+
+`.claude/skills/bmad-*/customize.toml` is a different thing and MUST NOT be edited — it is overwritten
+on every BMad update. What gets swept is `_bmad/custom/`.
+
+## Memlog
+
+**A memlog follows its artifact. What lands in the corpus leaves its memlog in `.control/memlog/`,
+because a memlog is not a deliverable.**
+
+```text
+.control/memlog/    brief.md · prd-<slug>.md · spine.md · ux.md      class A and B only
+```
+
+`memlog.py` accepts `--workspace DIR` (the memlog is always `{DIR}/.memlog.md`) and `--path FILE`.
+BMad skills call `--workspace` by default; the class-A home is reached by installing a `--path`
+instruction as a `persistent_fact`.
+
+- A class-A or class-B skill MUST use `--path`. `--workspace` MUST NOT be used — it would leave a
+  `.memlog.md` inside `.what/` or `.how/`, which V16 rejects.
+- Class-C memlogs stay beside their output in `_bmad-output/`.
+- Every memlog MUST carry `artifact:` in its frontmatter, pointing at a file that exists.
+
+## Configuration
+
+Overrides live in `_bmad/custom/*.toml`, installed by `bmad-customize` so the merge is verified.
+
+| Merge behaviour | Applies to |
+|---|---|
+| Scalar — override wins | `*_output_path`, `run_folder_pattern`, `*_template` |
+| Array — **append**, base entries cannot be removed | `persistent_facts`, `doc_standards`, `activation_steps_*`, `external_*` |
+| String — replaces the base entirely | `implementation_handoff` |
+
+Two placement rules that are easy to get wrong:
+
+- **`doc_standards` MUST NOT be chosen just because the file is a guide.** Each skill declares what
+  its polish pass applies to, and that declaration MUST be read first. `bmad-architecture` excludes
+  the spine — *"never to the spine"* — so `architecture-guide.md` installed there would only ever
+  polish renderings. A guide governing an artifact outside the polish target MUST be a
+  `persistent_fact`.
+- **Facts MUST NOT be installed as `doc_standards`.** The two structure maps in `.control/` are
+  facts; treating them as standards makes an agent read today's state as a rule.
+
+`config.toml` sets `project_knowledge` to `.control/`. Personal files — `config.user.toml` — belong
+to whoever runs the repo and MUST NOT be copied between projects.
+
+## Only five skills review themselves
+
+`doc_standards` exists on `bmad-product-brief`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, and
+`bmad-deep-recon`, and it runs two lenses: `structure` and `prose`.
+
+Everything else MUST be reviewed by invoking `wdi-review` explicitly — the spine, every SRS, every
+SDD, and every `SPEC.md`. Three lenses never fire on their own anywhere: `adversarial`,
+`edge-case-hunter`, and `verification-gap`.
+
+**Code review does not use `bmad-review`.** `bmad-code-review` reads its lenses from a bundled copy
+under `review-prompts/`, and each layer ends with an instruction not to invoke any skill. An override
+placed on `bmad-review` is therefore **invisible** to code review. Getting the current lenses onto a
+diff requires calling `bmad-review` by hand.
+
+## Renamed and retired
+
+| Old name | Now |
+|---|---|
+| `bmad-create-prd` · `bmad-edit-prd` · `bmad-validate-prd` | Shims over `bmad-prd` — use the intent, not the shim |
+| `bmad-create-architecture` | `bmad-architecture` |
+| `bmad-create-epics-and-stories` · `bmad-sprint-planning` | **Not used** — sprint route |
+
+Roughly a third of the installed skills are deprecated aliases. `bmad-skill-register.md` is the
+authority on which is which, and it MUST be consulted rather than guessed from a name that looks
+plausible.
+
+## Rules
+
+- A `wdi-*` wrapper, where one exists, MUST be called instead of the skill it wraps. The wrapper
+  carries the position and content checks; going around it produces an artifact nothing verifies.
+- `bmad-help` MUST NOT be used to answer "where am I". Its progress detection globs paths this method
+  redirects, and it names gates this route never produces. Use `wdi-help`.
+- Any output with no home in the distillation table MUST be reported as a gap in the method, not
+  filed somewhere plausible.