wdi-method 0.6.25 → 0.6.27

package/CHANGELOG.md

@@ -10,6 +10,33 @@ version contains every fix below it.
 
 ---
 
+## [0.6.27] - 2026-09-20
+
+### Added
+
+- **Validation Rule `scratch-hygiene` in `validate.py`:** Added strict structural hygiene enforcement for the specification workspace root (`.scratch/`). Active specs live exclusively inside registered `.scratch/<spec-id>-<slug>/` directories. Loose files directly under `.scratch/` root (e.g. `prompt-*.txt`, `output-*.txt`, logs, transcripts) and unregistered child directories immediately fail validation with finding `scratch-hygiene`. Additionally, verifies that `.work/` contains no `SPEC.md` files.
+- **Defensive Scratch Dumps `.gitignore` Scaffolding in `bin/wdi-method.js`:** Expanded `ensureGitignoreScratchDumps()` during install and update to automatically add defensive ignore rules to consumer `.gitignore`: `.scratch/*.txt`, `.scratch/*.log`, `.scratch/*-review-output.md`, `.scratch/*-second-opinion.md`, and `.scratch/tmp/`, preventing accidental execution transport dumps from polluting git status.
+
+### Changed
+
+- **Spec Workspace vs Execution Scratch Boundaries in `repo-guide.md` & `AGENTS.md`:** Clarified that `.scratch/` is strictly a registered spec workspace (authoritative and git-tracked), NOT an informal scratchpad. Loose files and ad-hoc folders are forbidden. All subagent transport packets, raw CLI redirection dumps, and review transcripts MUST be written to `.work/<skill>/` and deleted upon completion.
+- **Skill Transport Discipline in `wdi-build`:** Explicitly added transport guardrails forbidding placing execution scratch, prompt handoffs, or tool logs in `.scratch/`.
+
+**What a repo that already has the method installed does about it.** Run `npx wdi-method@latest update`. It updates `validate.py`, the build skills, and automatically appends defensive ignore patterns to `.gitignore`. Any loose files in `.scratch/` should be deleted or moved to `.work/`.
+
+## [0.6.26] - 2026-09-20
+
+### Added
+
+- **Validation Rule `spec-folder-location` in `validate.py`:** Added upfront validation that every spec in `specs.yaml` has a valid `spec_folder`. For active specs, `spec_folder` MUST be within `.scratch/<spec-id>-<slug>/` (or legacy `_bmad-output/specs/`). Specs placed inside `.work/` or other unauthorized roots (such as `docs/` or repo root) fail immediately with finding `spec-folder-location`, preventing misplaced specs from progressing through implementation before failing during lifecycle archival.
+
+### Changed
+
+- **Non-Authoritative Execution Scratch Taxonomy in `repo-guide.md`:** Clarified section heading to `## .work/ — non-authoritative execution scratch` and added explicit normative rules: `.work/` is execution scratch only and MUST NOT contain `SPEC.md`, ticket files, or any `spec_folder` target. Active specifications and ticket efforts MUST live under `.scratch/<spec-id>-<slug>/`.
+- **Deterministic Spec Location in `wdi-daily-what-to-build` & `wdi-build`:** Added explicit target contracts in `wdi-daily-what-to-build` (Step 3) and `wdi-build` (Phase 1 & Phase 2), mandating `.scratch/<spec-id>-<slug>/` and forbidding `.work/` or `docs/`. Preflight check instructs immediate correction if `spec-folder-location` fails.
+
+**What a repo that already has the method installed does about it.** Run `npx wdi-method@latest update`. It updates `validate.py`, the repo guide, and the build skills. Active specs mistakenly authored in `.work/` should be moved to `.scratch/<spec-id>-<slug>/` with `spec_folder` updated in `specs.yaml`.
+
 ## [0.6.25] - 2026-09-19
 
 ### Changed

package/README.id.md

@@ -1,6 +1,7 @@
 # WDI Method
 
-[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)  
+[Changelog](CHANGELOG.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE) | [Security](SECURITY.md) | [Privacy](PRIVACY.md)
 
 **Lapisan tinjauan yang melengkapi BMad — spesifikasi terverifikasi yang dibaca manusia untuk memeriksa keputusan teknis sebelum kode ditulis, disesuaikan dengan skala perubahan nyata.**
 

package/README.ja.md

@@ -1,6 +1,7 @@
 # WDI Method
 
-[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)  
+[Changelog](CHANGELOG.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE) | [Security](SECURITY.md) | [Privacy](PRIVACY.md)
 
 **BMadが薄く残したレビュー層 — コードを書く前に技術的な決定を人間が検証するための仕様書フレームワーク。変更規模に応じて適切な粒度を提供します。**
 

package/README.md

@@ -1,6 +1,7 @@
 # WDI Method
 
-[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)  
+[Changelog](CHANGELOG.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE) | [Security](SECURITY.md) | [Privacy](PRIVACY.md)
 
 **The review layer BMad leaves thin — verifiable specifications a human reads to check technical decisions before code is written, sized to what the change actually deserves.**
 

package/README.zh.md

@@ -1,6 +1,7 @@
 # WDI Method
 
-[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+[English](README.md) | [Bahasa Indonesia](README.id.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)  
+[Changelog](CHANGELOG.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE) | [Security](SECURITY.md) | [Privacy](PRIVACY.md)
 
 **BMad 所精简保留的审查层 —— 供人类在编写代码前验证技术决策的规范说明框架，根据实际变更规模匹配相应的文档粒度。**
 

package/bin/wdi-method.js

@@ -919,7 +919,16 @@ function ensureGitignoreSmoke(target) {
 
 function ensureGitignoreScratchDumps(target) {
   const gitignorePath = path.join(target, ".gitignore");
-  const rules = [".work/*.txt", ".work/*.log", ".work/tmp/"];
+  const rules = [
+    ".work/*.txt",
+    ".work/*.log",
+    ".work/tmp/",
+    ".scratch/*.txt",
+    ".scratch/*.log",
+    ".scratch/*-review-output.md",
+    ".scratch/*-second-opinion.md",
+    ".scratch/tmp/",
+  ];
   if (fs.existsSync(gitignorePath)) {
     const content = fs.readFileSync(gitignorePath, "utf8");
     const lines = content.split(/\r?\n/).map((l) => l.trim());

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

@@ -40,10 +40,11 @@ fact and MUST NOT state the commercial one. *"Retention is 90 days"* is a techni
 *"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/` — non-authoritative execution scratch
 
-`.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.
+`.work/` holds execution scratch and work in progress that has no home yet: notes while reading
+an unfamiliar system, exploratory output, disposable reviewer transport, 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.
@@ -55,6 +56,9 @@ pattern that drops the folder is not, because it leaves the material on one mach
 
 It is **ephemeral**, and the two together are what make its rules matter:
 
+- `.work/` is execution scratch only. It MUST NOT contain `SPEC.md`, ticket files, or any `spec_folder`
+  target. Active specification workspaces MUST live at `.scratch/<spec-id>-<slug>/` where `wdi-build`
+  and the registry track them.
 - 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
@@ -64,9 +68,15 @@ It is **ephemeral**, and the two together are what make its rules matter:
 - 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.
+`.work/` MUST NOT be confused with `_bmad-output/` or `.scratch/`. `_bmad-output/` holds the output of
+skill runs, is never curated, and is cited by path. `.scratch/` holds active specifications and tickets
+tracked in `specs.yaml`. `.work/` holds disposable execution scratch written by hand or during triage
+(such as `.work/wdi-daily-what-to-build/`), and is meant to empty out.
+
+`.scratch/` is **strictly for registered spec workspaces**. It MUST NOT be used as an informal scratchpad:
+- Loose files (such as prompt dumps, tool stdout/stderr, review packets, script logs) MUST NOT be written directly under `.scratch/`.
+- Unregistered directories MUST NOT be created under `.scratch/`. Every child directory MUST match an active or unarchived `spec_folder` in `.control/registry/specs.yaml`.
+- All temporary subagent transport files, raw reviewer outputs, and intermediate scratch MUST be written under `.work/<skill>/` and deleted once folded into the spec. `scratch-hygiene` enforces these boundaries.
 
 ## Referring to things outside this repository
 

package/kit/.constitution/method/scripts/validate.py

@@ -973,6 +973,113 @@ def archived_spec_closed(c: Corpus, r: Result) -> None:
                        "only closed specs may be archived")
 
 
+def spec_folder_location(c: Corpus, r: Result) -> None:
+    """A spec's `spec_folder` MUST be within an allowed root.
+
+    Active specs MUST live at `.scratch/<spec-id>-<slug>/` (or legacy `_bmad-output/specs/`).
+    Closed specs may remain in `.scratch/` or be archived under `.archive/specs/<spec-id>-<slug>/`.
+    `.work/` is execution scratch only and MUST NOT be used for `spec_folder`.
+    """
+    for spec in c.spec_list:
+        sid = str(spec.get("id") or "").strip()
+        folder = str(spec.get("spec_folder") or "").strip()
+        if not folder:
+            for t in spec.get("tickets") or []:
+                if isinstance(t, dict) and str(t.get("spec_folder") or "").strip():
+                    folder = str(t.get("spec_folder")).strip()
+                    break
+        if not folder:
+            continue
+        clean = folder.replace("\\", "/").strip()
+        while clean.startswith("./"):
+            clean = clean[2:]
+        if clean.startswith("/"):
+            clean = clean.lstrip("/")
+        clean = clean.rstrip("/")
+        norm = os.path.normpath(clean).replace("\\", "/") if clean else ""
+
+        # Check for forbidden .work/ root
+        if clean == ".work" or clean.startswith(".work/") or norm == ".work" or norm.startswith(".work/"):
+            r.fail("spec-folder-location", sid,
+                   f"spec_folder `{folder}` is inside `.work/` — `.work/` is execution scratch only; "
+                   f"active specs MUST live at `.scratch/{sid}-<slug>/`")
+            continue
+
+        status = str(spec.get("status") or "").strip()
+        is_closed = status == "closed"
+
+        allowed_roots = [".scratch", "_bmad-output/specs"]
+        if is_closed:
+            allowed_roots.append(".archive/specs")
+
+        is_allowed = any(clean == a or clean.startswith(f"{a}/") or norm == a or norm.startswith(f"{a}/")
+                         for a in allowed_roots)
+        if not is_allowed:
+            allowed_desc = ", ".join(f"`{a}/`" for a in allowed_roots)
+            r.fail("spec-folder-location", sid,
+                   f"spec_folder `{folder}` is outside allowed roots ({allowed_desc})")
+
+
+def scratch_workspace_hygiene(c: Corpus, r: Result) -> None:
+    """The spec workspace root (.scratch/) MUST NOT contain loose files or unregistered directories.
+
+    Active specs live at `.scratch/<spec-id>-<slug>/` where tickets and SPEC.md are tracked.
+    Ephemeral execution scratch, tool dumps, and prompt/review logs MUST live in `.work/`
+    and MUST NOT be placed in `.scratch/`.
+    """
+    scratch_dir = c.root / ".scratch"
+    if scratch_dir.is_dir():
+        registered_names: set[str] = set()
+        for spec in c.spec_list:
+            folder = str(spec.get("spec_folder") or "").strip()
+            if not folder:
+                for t in spec.get("tickets") or []:
+                    if isinstance(t, dict) and str(t.get("spec_folder") or "").strip():
+                        folder = str(t.get("spec_folder")).strip()
+                        break
+            if not folder:
+                continue
+            clean = folder.replace("\\", "/").strip()
+            while clean.startswith("./"):
+                clean = clean[2:]
+            clean = clean.strip("/")
+            if clean == ".scratch" or clean.startswith(".scratch/"):
+                parts = clean.split("/")
+                if len(parts) >= 2:
+                    registered_names.add(parts[1])
+
+        allowable_files = {".gitkeep", "wdi-probe.md"}
+
+        try:
+            entries = sorted(scratch_dir.iterdir(), key=lambda p: p.name)
+        except OSError:
+            entries = []
+
+        for entry in entries:
+            if entry.is_file():
+                if entry.name in allowable_files:
+                    continue
+                r.fail("scratch-hygiene", f".scratch/{entry.name}",
+                       f"loose file `{entry.name}` in `.scratch/` root — execution scratch MUST live in "
+                       f"`.work/<skill>/` and MUST NOT be placed in `.scratch/`")
+            elif entry.is_dir():
+                if entry.name not in registered_names:
+                    r.fail("scratch-hygiene", f".scratch/{entry.name}",
+                           f"directory `.scratch/{entry.name}` is not registered as a `spec_folder` in "
+                           f"`.control/registry/specs.yaml` — execution scratch MUST live in `.work/<skill>/`")
+
+    work_dir = c.root / ".work"
+    if work_dir.is_dir():
+        for spec_file in work_dir.rglob("SPEC.md"):
+            try:
+                rel = spec_file.relative_to(c.root).as_posix()
+            except ValueError:
+                rel = str(spec_file)
+            r.fail("scratch-hygiene", rel,
+                   f"found `{rel}` inside `.work/` — `.work/` is execution scratch only; "
+                   f"specification files MUST NOT be placed in `.work/`")
+
+
 PLATFORM = "_platform"
 CROSS_CUTTING = ".how/_platform/cross-cutting.md"
 # The section heading entity-one-writer looks for. A heading a SCRIPT matches is a machine-facing key, and
@@ -1904,7 +2011,7 @@ def run_checks(c: Corpus, asof: dt.date) -> Result:
     # no two copies left to compare.
     # V19 is REPEALED. It checked one line item — an `RTR-` file in .control/reports/ — and the
     # retrospective it archived was the only thing spec size `L` ever decided. Both went together.
-    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, archived_spec_closed, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, withdrawn_recorded, id_allocated_once):
+    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, archived_spec_closed, spec_folder_location, scratch_workspace_hygiene, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, withdrawn_recorded, id_allocated_once):
         fn(c, r)
     plan_dates(c, r, asof)
     return r

package/kit/skills/wdi-build/SKILL.md

@@ -85,7 +85,7 @@ that is where they are born.
 | `fr` | The `FR` this spec satisfies. Ideally one — an `FR` is human-testable from birth |
 | `size` | `S` · `M` · `L`. MAY be raised mid-flight; MUST NOT be lowered |
 | `depends_on` | At **spec** level. A spec declaring none runs in parallel with its neighbours |
-| `spec_folder` | One per spec, not one per spec × component |
+| `spec_folder` | MUST be `.scratch/<spec-id>-<slug>/` (one per spec, not one per spec × component). MUST NOT use `.work/` or `docs/` |
 | `tickets` | Flat, one row per ticket: `id` · `component` · `satisfies: [UC]` · `blocked_by` · `touches` · test names |
 | a ticket `id` | `<spec-id>-<NN>` — `SPEC-3-01`. The engine numbers its files from `01` per feature, which is unique only inside one spec; the RTM needs a key that is unique across the corpus |
 
@@ -139,11 +139,16 @@ is here and name the prior art.
   sequenced expand → migrate in batches → contract; `delivery-flow-guide.md` owns that rule.
 - **Ticket files land under `spec_folder`, and `spec_folder` is `.scratch/<spec-id>-<slug>/`.** Their
   **shape** is the engine's — one file per ticket, numbered in dependency order, blocking edges declared
-  — and the location is ours, written in `docs/agents/issue-tracker.md` where the engines read it. The
+  — and the location is ours, written in `docs/agents/issue-tracker.md` where the engines read it. MUST
+  NOT use `.work/` or `docs/` (`spec-folder-location` enforces this). The
   id in front of the slug is not decoration: four live repos wrote that leaf four different ways, one of
   them all four inside a single repo, and a folder nothing can trace back to a row in `specs.yaml` is
   how a spec goes missing. A ticket at the repo root, or under `docs/`, or in a `.scratch/` directory
   with no row in `specs.yaml`, is drift.
+- **Execution scratch, prompt handoffs, and tool logs MUST NOT be placed in `.scratch/`.** Any raw model
+  output, multi-agent dispatch transcripts, or debug dumps MUST be written to `.work/<skill>/` and
+  deleted after distillation. The root of `.scratch/` MUST NOT contain loose files, and unregistered
+  directories MUST NOT be created there (`scratch-hygiene` enforces this).
 
 `SPEC.md` and ticket files **are not read by humans.** Both are machine contracts, and no review burden MAY be
 moved onto them. `wdi-review` MAY still be dispatched over the contract; its trace lands on the spec in

package/kit/skills/wdi-daily-what-to-build/SKILL.md

@@ -50,6 +50,13 @@ Invoke `wdi-build` Phase 1 (open spec and author tickets via `to-spec` / `to-tic
 active development branch (`policy.development_branch`, default `main`), per the Delivery Flow standing
 exception.
 
+### Spec Location & Target Contract (`spec-folder-location`)
+The specification and its ticket files MUST land under `.scratch/<spec-id>-<slug>/` and `spec_folder`
+in `.control/registry/specs.yaml` MUST name that exact path.
+- MUST NOT place `SPEC.md` or ticket files in `.work/` or `docs/`.
+- `.work/` is reserved strictly for ephemeral execution scratch (such as `.work/wdi-daily-what-to-build/`);
+  a spec in `.work/` violates `spec-folder-location` and fails lifecycle archiving.
+
 ### Ticket Dependency Contract (Upfront `parallel-tickets-blocked`)
 Author `touches` and `blocked_by` together; do NOT defer dependency relationships until validation.
 For every pair of tickets in the same spec whose `touches` lists intersect, there MUST be a directed
@@ -61,9 +68,11 @@ Before leaving Step 3, run validator preflight:
 ```bash
 uv run .constitution/method/scripts/validate.py --check --baseline
 ```
-If `parallel-tickets-blocked` reports unsequenced tickets, add the missing `blocked_by` edge to an upstream
-ticket immediately. Findings already matching `.github/validate-baseline.txt` are pre-existing debt, not new
-blockers; only new RED findings must be repaired before dispatching review.
+If `spec-folder-location` reports an invalid `spec_folder` (e.g. under `.work/`), move the folder to
+`.scratch/<spec-id>-<slug>/` and update `specs.yaml` immediately. If `parallel-tickets-blocked` reports
+unsequenced tickets, add the missing `blocked_by` edge to an upstream ticket immediately. Findings already
+matching `.github/validate-baseline.txt` are pre-existing debt, not new blockers; only new RED findings must
+be repaired before dispatching review.
 
 **Stop at the boundary of Phase 1.** Once the spec and ticket files exist on disk, do NOT proceed into
 Phase 2 (worktree isolation and ticket implementation) or Phase 3 (closing the spec) — each of those is

package/kit-overlay/AGENTS.md

@@ -99,9 +99,10 @@ Read this instead of reasoning about what `.what/` and `.how/` mean.
 | The explanation of a rule, never a rule itself | `.constitution/method/why/` |
 | A decision, an open question, a registry, a structure map, minutes | `.control/` |
 | The brief, a PRD, a use case, a business rule — what is promised | `.what/` |
-| The spine, C4, an inventory, an SDD, a contract — how it is built | `.how/` |
+| A spine, C4, an inventory, an SDD, a contract — how it is built | `.how/` |
+| Active spec workspaces and tickets tracked in `specs.yaml` | `.scratch/<spec-id>-<slug>/` |
 | A skill run's working output, and documents that predate the method | `_bmad-output/` |
-| Scratch that empties when the task closes | `.work/` |
+| Scratch that empties when the task closes (prompt packets, tool dumps) | `.work/` |
 | The application | named under `## Code` below |
 
 ## Layer boundaries
@@ -184,6 +185,9 @@ verifies the result, and lands the memlog.
   `.control/generated/` (`status.yaml`) instead.
 - `.scratch/` MUST NOT be searched with broad or recursive wildcard patterns (`*` or `**`) to discover
   specs — inspect only the candidate spec's folder using `spec_folder:` from `status.yaml` or `specs.yaml`.
+- Loose files (prompt dumps, tool outputs, transcripts, script logs) MUST NOT be written into `.scratch/`
+  root, and unregistered folders MUST NOT be created there. All execution scratch MUST live in
+  `.work/<skill>/` and MUST be cleaned up before committing (`scratch-hygiene` enforces this).
 
 ## Routing — load a guide when the task matches
 

package/kit-overlay/repo-guide.md

@@ -40,10 +40,11 @@ fact and MUST NOT state the commercial one. *"Retention is 90 days"* is a techni
 *"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/` — non-authoritative execution scratch
 
-`.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.
+`.work/` holds execution scratch and work in progress that has no home yet: notes while reading
+an unfamiliar system, exploratory output, disposable reviewer transport, 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.
@@ -55,6 +56,9 @@ pattern that drops the folder is not, because it leaves the material on one mach
 
 It is **ephemeral**, and the two together are what make its rules matter:
 
+- `.work/` is execution scratch only. It MUST NOT contain `SPEC.md`, ticket files, or any `spec_folder`
+  target. Active specification workspaces MUST live at `.scratch/<spec-id>-<slug>/` where `wdi-build`
+  and the registry track them.
 - 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
@@ -64,9 +68,15 @@ It is **ephemeral**, and the two together are what make its rules matter:
 - 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.
+`.work/` MUST NOT be confused with `_bmad-output/` or `.scratch/`. `_bmad-output/` holds the output of
+skill runs, is never curated, and is cited by path. `.scratch/` holds active specifications and tickets
+tracked in `specs.yaml`. `.work/` holds disposable execution scratch written by hand or during triage
+(such as `.work/wdi-daily-what-to-build/`), and is meant to empty out.
+
+`.scratch/` is **strictly for registered spec workspaces**. It MUST NOT be used as an informal scratchpad:
+- Loose files (such as prompt dumps, tool stdout/stderr, review packets, script logs) MUST NOT be written directly under `.scratch/`.
+- Unregistered directories MUST NOT be created under `.scratch/`. Every child directory MUST match an active or unarchived `spec_folder` in `.control/registry/specs.yaml`.
+- All temporary subagent transport files, raw reviewer outputs, and intermediate scratch MUST be written under `.work/<skill>/` and deleted once folded into the spec. `scratch-hygiene` enforces these boundaries.
 
 ## Referring to things outside this repository
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdi-method",
-  "version": "0.6.25",
+  "version": "0.6.27",
   "description": "WDI Method — software delivery method that wraps BMad",
   "type": "module",
   "bin": {