wdi-method 0.6.26 → 0.6.27

package/CHANGELOG.md

@@ -10,6 +10,20 @@ 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

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

@@ -73,6 +73,11 @@ skill runs, is never curated, and is cited by path. `.scratch/` holds active spe
 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
 
 Engagement context — who the client is, what was agreed, what is due — lives elsewhere. This repo

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

@@ -1020,6 +1020,66 @@ def spec_folder_location(c: Corpus, r: Result) -> None:
                    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
@@ -1951,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, spec_folder_location, 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

@@ -145,6 +145,10 @@ is here and name the prior art.
   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-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

@@ -73,6 +73,11 @@ skill runs, is never curated, and is cited by path. `.scratch/` holds active spe
 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
 
 Engagement context — who the client is, what was agreed, what is due — lives elsewhere. This repo

package/package.json

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