wdi-method 0.6.25 → 0.6.26

package/CHANGELOG.md

@@ -10,6 +10,19 @@ version contains every fix below it.
 
 ---
 
+## [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/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,10 @@ 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.
 
 ## Referring to things outside this repository
 

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

@@ -973,6 +973,53 @@ 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})")
+
+
 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 +1951,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, 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,7 +139,8 @@ 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

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/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,10 @@ 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.
 
 ## Referring to things outside this repository
 

package/package.json

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