wdi-method 0.6.15 → 0.6.19

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

@@ -43,6 +43,7 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 | [`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/` |
+| [`ci-guide.md`](ci-guide.md) | Writing or changing a CI workflow; when a push may start a cloud run, and what MUST NOT |
 
 ## `document/` — document rules
 

package/kit/.constitution/method/ci-guide.md

@@ -0,0 +1,150 @@
+---
+status: Accepted
+---
+
+# CI Guide
+
+**Loaded when:** writing or changing a GitHub Actions workflow, or deciding whether a push may start a
+cloud run
+
+Cloud runners are **metered**, and the meter is not flat: a Windows runner bills at **2×** the minutes it
+uses and macOS at **10×**, and on a private repository every one of those minutes comes out of a monthly
+allowance. One real run of `wdi-autopilot` over fifteen tickets pushed often enough to start CI dozens of
+times and spent most of a month's allowance in two days.
+
+**The fix is not fewer commits.** Commits stay granular — one per ticket, plus the memlog and registry
+writes — because that is what makes a run reviewable and resumable. What changes is **what a push
+triggers**.
+
+## One unit of work, one cloud run
+
+| | Runs where | When |
+|---|---|---|
+| Build, typecheck, the full suite **during** the work | **Locally**, on the machine doing the work | Every ticket — `wdi-build` Phase 3 Step 2 already requires it, and it is free |
+| The cloud workflow | GitHub Actions | **Once**, when the work is offered for review |
+
+- A workflow MUST be configured so that an intermediate push — a ticket commit, a memlog rewrite, a
+  registry catch-up, a spec close — starts **nothing**.
+- The cloud run MUST happen before the work is merged. Green CI on the **pushed head SHA** is still the
+  release evidence; what moves is how many times it is collected, not whether it is.
+- Under a mandate the unit of work is the whole run, so the one cloud run belongs at `wdi-autopilot`
+  § Finish. That skill owns the sequence and this guide MUST NOT restate it.
+- Where the repo's workflow cannot be changed — a shared org template, a workflow another team owns —
+  the run MUST keep intermediate work off the remote instead: hold the push, or make the pushed head
+  commit carry `[skip ci]`, which GitHub honours for `push` and `pull_request` events.
+
+## Trigger shape
+
+| Event | Use it | Why |
+|---|---|---|
+| `workflow_dispatch` | **MUST** be present | The manual re-run. Without it, a red run can only be retried by pushing again |
+| `pull_request:` `types: [ready_for_review]` | The one automatic trigger | A draft PR is work in progress; marking it ready is the moment somebody is asking for the verdict |
+| `push:` `branches: [main]` | MAY | One run per merge, as the record of trunk health. Drop it where the allowance is tight |
+| bare `on: push` | **MUST NOT** | Every branch, every commit, no filter. This is the setting that spends an allowance |
+
+Two consequences worth stating, because both surprise people:
+
+- With `types: [ready_for_review]` and no `synchronize`, a push **after** the PR is ready does not
+  re-run CI. Re-run it with `workflow_dispatch`, or convert the PR back to draft and mark it ready
+  again. That is the intended trade: the re-run is a decision, not a reflex.
+- `concurrency` with `cancel-in-progress: true` stops two runs of the same ref from billing at once.
+  Every workflow below sets it.
+
+## What MUST NOT start a build
+
+A change that touches only prose or only the corpus cannot break the code, so it MUST NOT start the
+product's build. `paths-ignore` carries that: `**.md`, `.scratch/**`, and the method's own layers —
+`.control/**`, `.what/**`, `.how/**`, `.constitution/**`, `_bmad-output/**`, `.work/**`.
+
+The corpus workflow is the **mirror image** of that list and MUST stay a separate workflow: it runs the
+validators, on Ubuntu, only when the corpus changed. Keeping the two apart is what lets the expensive one
+be ignored while the cheap one still guards the registry.
+
+## Template — `.github/workflows/ci.yml`
+
+The product's build and test. This is the expensive one; the `runs-on` and the two `run:` lines are the
+product's, and they come from `.constitution/project/codebase-stack-guide.md`.
+
+```yaml
+name: ci
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [ready_for_review]
+    paths-ignore:
+      - '**.md'
+      - '.scratch/**'
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+      - '_bmad-output/**'
+      - '.work/**'
+  # One run per merge, as the record of trunk health. Delete this block where the allowance is tight.
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '.scratch/**'
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+      - '_bmad-output/**'
+      - '.work/**'
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    # A Windows runner bills 2× and macOS 10×. Name only the platforms the product actually ships on.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Replace both lines with this product's build and test commands.
+      - run: echo "build command from codebase-stack-guide.md"
+      - run: echo "test command from codebase-stack-guide.md"
+```
+
+## Template — `.github/workflows/korpus.yml`
+
+The corpus validators. Cheap, Ubuntu, and it runs only when the corpus moved — so it MAY keep the
+default `pull_request` trigger, which gives a verdict on the registry while the expensive workflow stays
+quiet. `korpus.yml` validates the corpus and **not** the code: a green run here is never build evidence.
+
+```yaml
+name: korpus
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.control/**'
+      - '.what/**'
+      - '.how/**'
+      - '.constitution/**'
+
+concurrency:
+  group: korpus-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # The three scripts declare their dependencies inline (PEP 723); uv is what runs them.
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run .constitution/method/scripts/validate.py
+```
+
+## Red flags
+
+- `on: push` with no branch filter, in a repo whose runners are metered
+- The product's build and the corpus validators in one workflow — the cheap half then cannot run alone
+- A cloud run started to find out whether the code compiles, when the local suite answers that for free
+- CI watched per ticket under a mandate, instead of once at § Finish
+- A green `korpus.yml` read as a passing build

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

@@ -63,6 +63,12 @@ decision or a PRD MAY point into it. Research, brainstorming, forge, and PRFAQ r
 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.
 
+**What git ignores is not corpus.** A vendored upstream checkout kept for reading, a scratch download, a
+build cache — if the product excludes it from git it is in no clone, nobody curates it, and the validators
+do not read it. The other half of that rule is `corpus-in-git`: a folder the method itself keeps MUST NOT be
+excluded, and the two lock together — material is either in git and checked, or ignored and not corpus. What
+`.gitignore` MUST NOT be used for is quieting a finding about a file that really is this product's.
+
 ### A withdrawn promise STAYS in the registry
 
 A `BG` · `CAP` · `FR` · `NFR` · `UC` the product stops promising is marked, never deleted:

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

@@ -1,208 +1,216 @@
----
-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"*.
-
-## A decision's first home is the document it governs
-
-**Changing a document NEVER requires a `DEC-`.** A `DEC-` is not permission to edit, not a record that
-an edit happened, and not a step between deciding and writing. Where the answer has a home in a design
-document — an `FR` in the PRD, a rule in `business-rules.md`, a boundary in an SDD, a line in the brief —
-**it is written there and nowhere else**, and there is nothing further to do.
-
-A `DEC-` is what you write for a decision with **no such home**. That is the whole of its job, plus the
-one mandatory case below.
-
-| The answer is about | Where it goes |
-|---|---|
-| What the product promises, does, or forbids | The design document that carries it |
-| How this repo builds — a convention, a stack choice | `.constitution/project/`, once code ratifies it |
-| Accepting a risk, cutting a scope, choosing between two paths **that no document holds** | A `DEC-` |
-| Contradicting an `AD-N` | A `DEC-`, mandatory |
-
-This matters most **early**. At G1 a brief is still being formed and at G2 a PRD is still being written;
-almost nothing there is homeless, so almost nothing there is a `DEC-`. Demanding one before the artifact
-it would govern even exists is ceremony at the moment the project can least afford it.
-
-## Then one test decides whether to record it at all
-
-> **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.
-
-**A `DEC-` records a state, never an event.** It answers *why is it like this* for someone about to
-change it — forward-looking, present tense. It is not a record that something changed, not a record that
-a document used to say otherwise, and not a record that a review found a conflict. Those are document
-history, and `corpus-guide.md` § The corpus is written in the present tense says they go nowhere.
-
-The practical form of the test: **would this file save the next person from a mistake they were about to
-make?** If the honest answer is *"no, but it explains what happened"*, there is no file.
-
-**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".
-
-**No case is mandatory any more, and one guard survives all of them.** Three rules used to demand a
-`DEC-` file. Each was protecting something real, and in each the protection was the **stop**, never the
-document:
-
-| Was | Is now |
-|---|---|
-| Contradicting an `AD-N` demanded a `DEC-` | It **stops and reaches the owner**. Nobody narrows an invariant silently. The record is the edited `AD-N`, present tense, plus the commit — a `DEC-` only if the reason cannot be read from the spine |
-| `risk_accepted: high` on a sensitive component demanded a risk-acceptance `DEC-` | `risk_accepted_by` names **a person and a date**, in `components.yaml` where the risk is set. `high-risk-named` checks it, and still resolves a `DEC-` id if one is given |
-| Cancelling >30% of a spec's tickets demanded a `DEC-` | The spec is **re-cut** rather than patched. `specs.yaml` is the record |
-
-What each of those bought was that a human made the call. That is preserved. What each of them also
-cost — a file, written at the moment the work was blocked — is not.
-
-An `AD-N` change stopping is the one that MUST NOT be softened further: it is what stops an architecture
-being narrowed twice by two passes neither of which thought it was doing anything.
-
-**Nothing else stops the work at all.** Where a change contradicts an `FR`, a `UC`, a business rule,
-or a document's wording, the agent states the consequence once and the owner decides. If they proceed the
-documents are edited to match — `delivery-flow-guide.md` § When something settled has to change owns the
-matrix, and the survey behind that warning is spent the moment the owner answers.
-
-## `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/`.
-
-**One page, and that is a bound, not a target.** A `DEC-` records **what was chosen and what it cost** —
-not how the answer was reached, not the transcript of the reasoning, not every reading of every clause
-that was weighed on the way. One real decision reached **124 lines** to record that one invariant does not
-reach one artifact; the sentence that mattered was one line and the cost was two.
-
-Three things MUST NOT appear in a `DEC-`, and each of them is the derivation leaking in:
-
-- The search that found the answer — which files were grepped, which clause was read first.
-- A meta-note about the decision itself: whether it should have been a `DEC-` at all, whether some other
-  mechanism was considered and rejected. If that reasoning matters it is the **Why**; usually it does not
-  matter and it is nothing.
-- A correction of an earlier draft of the same decision. Drafts are git's.
-
-`Alternatives` is the one place a rejected option belongs, it is a **line each**, and it is required only
-where the section table above says so.
-
-## 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`. One value has a fixed shape: `mandate`, opened by `wdi-autopilot`, whose parameters live under `mandate:` on the registry row and nowhere else |
-| `accepted_by` | Who raised it to `accepted`. A person and a date, the way `risk_accepted_by` is written — or the `DEC-` of a `type: mandate` that delegated the acceptance. `mandate-accept` checks the second form |
-| `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, and **the correction is not recorded anywhere** — the file now reads
-correctly and git holds the change. Logging it would be a second home for a fact git already has, and a
-piece of document history that would save nobody.
-
-An agent MUST NOT accept its own `DEC-`. When work is blocked waiting on one, the block is reported,
-never resolved by self-approval.
-
-**The one exception is a delegation the owner made in person.** A `DEC-` of `type: mandate`, accepted by
-the owner with a name and a date and carrying an `expires`, lets `wdi-autopilot` accept decisions taken
-under it — `accepted_by: DEC-<mandate>`. What each of the three guards above protected — *a human made
-the call* — still holds: the human made one call, and it is on the record, dated, and ending. The mandate
-itself MUST NOT be accepted by delegation, and `mandate-accept` refuses one that is, one with no
-`expires`, and any decision dated after its mandate lapsed.
-
-## 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 ticket contradicts an `AD-N` | The ticket stops. This is the one mandatory case |
-| `wdi-reconcile` found two documents disagreeing with no clear winner | That is a decision, not drift |
-| `wdi-autopilot` took a decision with no home in any design document | A `DEC-`, accepted under the mandate. The ledger records every decision it took; only the homeless ones become a `DEC-` |
-
-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.
-- `applied-dec-touches` 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.
+---
+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"*.
+
+## A decision's first home is the document it governs
+
+**Changing a document NEVER requires a `DEC-`.** A `DEC-` is not permission to edit, not a record that
+an edit happened, and not a step between deciding and writing. Where the answer has a home in a design
+document — an `FR` in the PRD, a rule in `business-rules.md`, a boundary in an SDD, a line in the brief —
+**it is written there and nowhere else**, and there is nothing further to do.
+
+A `DEC-` is what you write for a decision with **no such home**. That is the whole of its job, plus the
+one mandatory case below.
+
+| The answer is about | Where it goes |
+|---|---|
+| What the product promises, does, or forbids | The design document that carries it |
+| How this repo builds — a convention, a stack choice | `.constitution/project/`, once code ratifies it |
+| Accepting a risk, cutting a scope, choosing between two paths **that no document holds** | A `DEC-` |
+| Contradicting an `AD-N` | A `DEC-`, mandatory |
+
+This matters most **early**. At G1 a brief is still being formed and at G2 a PRD is still being written;
+almost nothing there is homeless, so almost nothing there is a `DEC-`. Demanding one before the artifact
+it would govern even exists is ceremony at the moment the project can least afford it.
+
+## Then one test decides whether to record it at all
+
+> **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.
+
+**A `DEC-` records a state, never an event.** It answers *why is it like this* for someone about to
+change it — forward-looking, present tense. It is not a record that something changed, not a record that
+a document used to say otherwise, and not a record that a review found a conflict. Those are document
+history, and `corpus-guide.md` § The corpus is written in the present tense says they go nowhere.
+
+The practical form of the test: **would this file save the next person from a mistake they were about to
+make?** If the honest answer is *"no, but it explains what happened"*, there is no file.
+
+**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".
+
+**No case is mandatory any more, and one guard survives all of them.** Three rules used to demand a
+`DEC-` file. Each was protecting something real, and in each the protection was the **stop**, never the
+document:
+
+| Was | Is now |
+|---|---|
+| Contradicting an `AD-N` demanded a `DEC-` | It **stops and reaches the owner**. Nobody narrows an invariant silently. The record is the edited `AD-N`, present tense, plus the commit — a `DEC-` only if the reason cannot be read from the spine |
+| `risk_accepted: high` on a sensitive component demanded a risk-acceptance `DEC-` | `risk_accepted_by` names **a person and a date**, in `components.yaml` where the risk is set. `high-risk-named` checks it, and still resolves a `DEC-` id if one is given |
+| Cancelling >30% of a spec's tickets demanded a `DEC-` | The spec is **re-cut** rather than patched. `specs.yaml` is the record |
+
+What each of those bought was that a human made the call. That is preserved. What each of them also
+cost — a file, written at the moment the work was blocked — is not.
+
+An `AD-N` change stopping is the one that MUST NOT be softened further: it is what stops an architecture
+being narrowed twice by two passes neither of which thought it was doing anything.
+
+**Nothing else stops the work at all.** Where a change contradicts an `FR`, a `UC`, a business rule,
+or a document's wording, the agent states the consequence once and the owner decides. If they proceed the
+documents are edited to match — `delivery-flow-guide.md` § When something settled has to change owns the
+matrix, and the survey behind that warning is spent the moment the owner answers.
+
+## `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/`.
+
+**One page, and that is a bound, not a target.** A `DEC-` records **what was chosen and what it cost** —
+not how the answer was reached, not the transcript of the reasoning, not every reading of every clause
+that was weighed on the way. One real decision reached **124 lines** to record that one invariant does not
+reach one artifact; the sentence that mattered was one line and the cost was two.
+
+Three things MUST NOT appear in a `DEC-`, and each of them is the derivation leaking in:
+
+- The search that found the answer — which files were grepped, which clause was read first.
+- A meta-note about the decision itself: whether it should have been a `DEC-` at all, whether some other
+  mechanism was considered and rejected. If that reasoning matters it is the **Why**; usually it does not
+  matter and it is nothing.
+- A correction of an earlier draft of the same decision. Drafts are git's.
+
+`Alternatives` is the one place a rejected option belongs, it is a **line each**, and it is required only
+where the section table above says so.
+
+## 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`. One value has a fixed shape: `mandate`, opened by `wdi-autopilot`, whose parameters live under `mandate:` on the registry row and nowhere else |
+| `accepted_by` | Who raised it to `accepted`. A person and a date, the way `risk_accepted_by` is written — or the `DEC-` of a `type: mandate` that delegated the acceptance. `mandate-accept` checks the second form |
+| `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, and **the correction is not recorded anywhere** — the file now reads
+correctly and git holds the change. Logging it would be a second home for a fact git already has, and a
+piece of document history that would save nobody.
+
+An agent MUST NOT accept its own `DEC-`. When work is blocked waiting on one, the block is reported,
+never resolved by self-approval.
+
+**The one exception is a delegation the owner made in person.** A `DEC-` of `type: mandate`, accepted by
+the owner with a name and a date and carrying an `expires`, lets `wdi-autopilot` accept decisions taken
+under it — `accepted_by: DEC-<mandate>`. What each of the three guards above protected — *a human made
+the call* — still holds: the human made one call, and it is on the record, dated, and ending. The mandate
+itself MUST NOT be accepted by delegation, and `mandate-accept` refuses one that is, one with no
+`expires`, and any decision dated after its mandate had ended.
+
+**A mandate ends twice over, and the earlier end is the one that counts:** its `expires` passes, or it
+is superseded. Superseding a mandate revokes the delegation from the day of the decision that replaced
+it — which is why a superseded mandate that delegated anything MUST carry `superseded_by`, and why
+recording that pointer is the one edit an `applied` decision allows. What supersession does NOT do is
+reach backwards: the decisions taken under the mandate while it stood remain accepted, their
+`accepted_by` still names it, and the ledger it owes is still owed. A retired mandate is a mandate that
+ended, never one that was never granted.
+
+## 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 ticket contradicts an `AD-N` | The ticket stops. This is the one mandatory case |
+| `wdi-reconcile` found two documents disagreeing with no clear winner | That is a decision, not drift |
+| `wdi-autopilot` took a decision with no home in any design document | A `DEC-`, accepted under the mandate. The ledger records every decision it took; only the homeless ones become a `DEC-` |
+
+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.
+- `applied-dec-touches` 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.