wdi-method 0.6.19 → 0.6.24

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

@@ -0,0 +1,155 @@
+---
+name: wdi-daily-what-to-build
+description: Turn raw manual-test notes into a triaged, reviewed spec/ticket ready for wdi-autopilot to pick up in a separate session. Invoke as `/wdi-daily-what-to-build [reviewer] <your raw notes>`.
+disable-model-invocation: true
+---
+
+# WDI Daily What-to-Build Triage
+
+Daily entry point for "I just tested something by hand, now what." Classifies the notes (new feature,
+fix, removal, or green), authors the resulting spec or ticket through this repo's own `wdi-build` flow,
+dispatches an independent second opinion grounded in the *original* notes, folds that feedback back in,
+then stops — this run never continues into `wdi-autopilot`, a commit, or a push.
+
+Spec lifecycle maintenance (archiving or pruning closed specs) belongs to `/wdi-prune-or-archive`;
+this skill remains 100% focused on triaging incoming test notes into actionable specs without administrative
+interruption.
+
+`/wdi-daily-what-to-build [reviewer] <notes>` — if the first word matches a known runner or a reviewer
+defined in `.control/custom-dispatch.yaml`, it picks the reviewer; otherwise all input is treated as
+the notes verbatim. Multi-line notes are accepted unedited; none of it gets summarized before review
+dispatch.
+
+## 0. Precondition
+
+Confirm `.control/registry/index.yaml` exists in the repo root. If it does not, this is not a WDI
+Method product repo and this skill has no corpus to write into — report that and stop.
+
+## 1. Keep the notes verbatim
+
+Hold the raw notes as given. They are forwarded unedited to the reviewer in step 4 — a paraphrase
+here would anchor the reviewer to your interpretation instead of the author's own words.
+
+## 2. Classify against the actual corpus, not the notes alone
+
+Search `.what/`, `.how/`, and `.control/` for the FR, UC, ticket, or SPEC the notes actually touch
+before deciding new vs. fix vs. removal vs. green. A classification made without checking what already
+exists there is a guess.
+
+- **Green** — behaviour already matches what is promised and built. Report that and stop; MUST NOT
+  open a spec or ticket for a non-finding.
+- **New / fix / removal** — continue to step 3.
+
+## 3. Author through wdi-build, not by hand
+
+This repo's Delivery Flow standing sequence (`AGENTS.md` § Delivery Flow) requires turning notes into
+a spec or ticket through `wdi-build`'s engines (`to-spec` / `to-tickets`) — MUST NOT hand-write a
+bespoke SPEC.md or ticket file instead.
+
+Invoke `wdi-build` Phase 1 (open spec and author tickets via `to-spec` / `to-tickets`) directly on the
+active development branch (`policy.development_branch`, default `main`), per the Delivery Flow standing
+exception.
+
+### 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
+`blocked_by` path in one direction between them. The path MAY be transitive: a direct edge is not required
+when an already-declared dependency chain orders the pair (e.g. `02` blocked by `01`, `03` blocked by `02`).
+This is the contract enforced by `parallel-tickets-blocked`.
+
+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.
+
+**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
+a separate, explicit ask, usually from a different chat session running `wdi-autopilot`.
+
+## 4. Package and dispatch an advisory second opinion
+
+Write the review packet to a scratch file first — `.work/wdi-daily-what-to-build/<slug>-second-opinion.md` —
+rather than inlining it into shell arguments:
+
+1. Path to the drafted spec or ticket from step 3.
+2. The original raw notes from step 1, unedited.
+3. Relevant component, subsystem, and ticket `touches` / `blocked_by` declarations, plus the preflight validator output.
+4. This standing mandate (strictly advisory / read-only):
+
+   > You are the independent advisory reviewer for this daily triage pass, not the implementer or author.
+   > Review the named draft against the verbatim notes and the cited corpus only. Return a structured written
+   > assessment in markdown:
+   > - **Verdict**: `accept` | `accept-with-changes` | `reject`
+   > - **Findings**: numbered; categorized as `blocking` vs `non-blocking`
+   > - **Notes vs Draft**: specific gaps, misinterpretations, or scope creep relative to raw notes
+   > - **Stamp Recommendation**: lenses to use (must include `edge-case-hunter`), readiness for trace stamping,
+   >   and blockers that must be resolved first
+   >
+   > You MUST NOT edit, create, delete, rename, or mutate any repository file. You MUST NOT invoke `wdi-review`,
+   > MUST NOT write `spec_reviewed` in `specs.yaml`, and MUST NOT modify frontmatter. Stamping is the
+   > coordinator's sole responsibility upon folding your feedback; this dispatch is advisory feedback only.
+
+Reviewer resolution:
+- If `review_policy.peer_review` is explicitly `false`, or if `roles.reviewer` in `.control/custom-dispatch.yaml` is set
+  to `none`, or if the command is invoked with `--no-review`, skip Step 4 and state in the report that peer review was skipped.
+- If `.control/custom-dispatch.yaml` exists in the repo root (or in the main repository root via `(git rev-parse --git-common-dir)/..` when running inside a linked git worktree): inspect `runners:` and `roles.reviewer`.
+  A runner definition specifies `type:` (`auto`, `in-session`, or `shell-out`):
+  - `auto` (recommended): Evaluates whether the runner's target model is reachable in-session from the active
+    session profile (per the caller's global agent collaboration rules). Dispatches in-session via the `Agent`
+    tool in read-only mode if reachable; falls back to shell-out using `command` if unreachable in-session.
+  - `in-session`: Dispatches strictly via the in-session `Agent` tool using a read-only subagent type.
+  - `shell-out`: Dispatches strictly via external shell `command` (single-string command, passing the review packet path).
+    A shell-out reviewer MUST be invoked with its read-only flag where supported (e.g. `--trust-tools=fs_read` for
+    `kiro-cli`, `--mode plan` for `cursor-agent`).
+  If the runner ID is missing from `runners:` or if `type: shell-out` lacks a nonempty `command` string,
+  stop and report immediately (fail-closed).
+- Dispatch execution & process discipline:
+  - Cap shell-out dispatch at a hard wall-clock limit (default 600s, or `timeout_s` if defined in `custom-dispatch.yaml`).
+  - Run backgrounded with polling or synchronous wait. If the timeout expires, or the process exits non-zero,
+    or the output file cannot be read: terminate the entire process tree by its PID (MUST NOT use process name-based
+    killing). Record in the final report: `peer review: fell back to coordinator self-review after timeout/failure`.
+    MUST NOT fabricate or synthesize unread reviewer output as if it were faithfully received.
+- In the absence of a custom runner file: follow the caller's configured agent collaboration setup
+  (e.g., in-session read-only subagent via the `Agent` tool if reachable, or the caller's configured CLI
+  environment).
+
+When the dispatched reviewer has no native Skill tool, instruct it to read and follow the target
+guide directly as plain markdown instructions.
+
+## 5. Coordinator fold-in, stamping, and validation
+
+The coordinator is the sole writer in this flow. Read the advisory assessment, revise the draft where it is
+correct, and report every material objection as `accepted`, `deferred` (with its recorded destination), or
+`disagreed` (with the reason). MUST NOT silently drop a reviewer objection.
+
+### Coordinator Stamping (`spec_reviewed`)
+Stamping is an official coordinator-owned event. Because the peer review was conducted live in this session
+under the coordinator's orchestration, the coordinator writes the `spec_reviewed` block directly to
+`.control/registry/specs.yaml` once the draft is accepted and amended:
+```yaml
+    spec_reviewed:
+      date: "<YYYY-MM-DD>"
+      sha: <git rev-parse HEAD>
+      lenses: [structure, prose, edge-case-hunter]
+```
+The coordinator MUST NOT delegate registry stamping to external shell-out processes.
+
+### Validation
+Run canonical validation using `uv`:
+```bash
+uv run .constitution/method/scripts/validate.py --generate --baseline
+```
+- Validation MUST be run via `uv run`, never bare `python` (which triggers Windows Python launcher shebang failures).
+- `--baseline` acknowledges the repository's established baseline in `.github/validate-baseline.txt`. It exits
+  zero only if current findings match that baseline exactly.
+- This skill MUST NOT expand or edit the baseline file. Any new RED finding outside the baseline represents an
+  unresolved issue and must be fixed before handoff.
+
+## 6. Stop and hand off
+
+Report what now exists (or that the notes were green) and its file path. State explicitly whether `spec_reviewed`
+was stamped or if peer review fell back to coordinator self-review. MUST NOT commit, push, or start `wdi-autopilot`
+in this same run — state that as the next step and wait for the maintainer to request it.

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

@@ -0,0 +1,127 @@
+---
+name: wdi-daily-what-to-test
+description: Sync to development branch, prune merged worktrees/branches, configure target application smoke environment, and build a test checklist from closed tickets. Invoke as `/wdi-daily-what-to-test [web <target>|mobile <target>|desktop]`.
+disable-model-invocation: true
+---
+
+# WDI Daily What-to-Test
+
+The post-merge daily verification step after a `wdi-autopilot` or ticket delivery run merges: lands
+back on the active development branch, safely prunes stale merged worktrees and task branches while
+strictly preserving protected branches, configures the application where it needs to be for platform
+verification, cleans temporary smoke logs, and presents a checklist of what changed — grounded in
+closed tickets and specs, never invented from memory.
+
+- `/wdi-daily-what-to-test` — sync + prune + checklist only, nothing deployed or launched.
+- `/wdi-daily-what-to-test web <target>` — sync + configure or deploy web target, then checklist.
+- `/wdi-daily-what-to-test mobile <target>` — sync + launch or install onto device or emulator, then
+  checklist.
+- `/wdi-daily-what-to-test desktop` — sync + launch application locally (current machine is target),
+  then checklist.
+
+## 0. Preconditions & Branch Policy Precheck
+
+1. Confirm `.control/registry/index.yaml` exists in the repo root. If it does not, this is not a WDI
+   Method product repo — report that and stop.
+2. Read branch policy from `.control/registry/index.yaml`:
+   - `primary_branch` (`policy.primary_branch`, default `main`).
+   - `development_branch` (`policy.development_branch`, default `main`).
+3. **Fail-Closed Branch Verification:** Verify that `development_branch` exists in local or remote
+   tracking references (`git rev-parse --verify refs/heads/<development_branch>` or
+   `git rev-parse --verify refs/remotes/origin/<development_branch>`). If neither resolves, stop
+   immediately and report to the maintainer; per `.constitution/method/branch-guide.md`, MUST NOT guess
+   or silently fall back to `main`.
+4. Verify the primary working tree is clean (`git status --porcelain`). If uncommitted changes exist,
+   stop and report without modifying git state.
+
+## 1. Sync (Fast-Forward Only)
+
+1. Save the pre-sync HEAD commit as `before_sync` (`git rev-parse HEAD`), or read the last sync cursor from `.work/smoke/last-sync` if present.
+2. Fetch remote updates and prune deleted tracking refs: `git fetch --prune origin`.
+3. Land on `development_branch` in the primary repository worktree using standard git operations
+   (`git checkout <development_branch>` or `git switch <development_branch>`).
+4. Pull remote updates strictly with fast-forward: `git pull --ff-only`.
+   If the branch has diverged or cannot be fast-forwarded, stop and report immediately; MUST NOT create
+   an automatic merge commit on `development_branch`.
+
+## 2. Prune Merged Task Branches & Worktrees (With Immunity Protections)
+
+Apply strict immunity per `.constitution/method/branch-guide.md` § Absolute branch immunity:
+- **Immune Branches:** `primary_branch` and `development_branch` **MUST NEVER be deleted**, locally or on any remote.
+- **Immune Checkouts:** The currently checked-out branch and the primary worktree root **MUST NEVER be removed**.
+- **Dirty Worktrees:** Any worktree with uncommitted changes (`git status --porcelain` non-empty) **MUST NOT be removed**.
+
+Pruning procedure:
+1. Enumerate candidates merged into `development_branch`: `git branch --merged <development_branch>`.
+2. Filter the candidate list to explicitly **exclude**:
+   - `primary_branch`
+   - `development_branch`
+   - the currently active branch (`HEAD`)
+3. Enumerate active worktrees: `git worktree list --porcelain`.
+4. For each remaining merged local task branch:
+   - If a worktree is linked to that branch: check whether the worktree has uncommitted changes. If clean,
+     remove the worktree first (`git worktree remove <worktree-path>`).
+   - Delete the merged local branch: `git branch -d <branch-name>`.
+5. Remote branch hygiene (fail-closed):
+   - For method-owned task branches (e.g. `autopilot/<mandate-id>`) merged into `development_branch`:
+     verify PR merge status (e.g. confirming its tip is an ancestor of `origin/<development_branch>`, or via `gh pr view <branch> --json state,mergedAt`).
+   - If confirmed merged and non-immune, delete the remote branch: `git push origin --delete <branch>`.
+   - If status cannot be verified, or if the toolchain is unavailable: do NOT delete; report as residual remote branch.
+6. If any candidate branch or worktree is ambiguous or has unmerged/dirty state, leave it untouched
+   and list it in the report.
+
+## 3. Configure Target Testing Environment
+
+When no platform argument is given, proceed directly to step 4 without launching any platform target.
+
+- **`desktop`**: Current machine is the target.
+  1. Inspect `.control/test-targets/desktop.md` (or `.constitution/project/codebase-stack-guide.md`) for build command, profile (default: `release` if verifying visual layout/performance, or `debug` for fast logic loops), target binary artifact path, and process executable name.
+  2. **Desktop Process Gate (File-Locking Prevention):** Before compiling or launching:
+     - Check whether an existing process is executing the target artifact binary (inspecting processes matching the binary path or application executable name).
+     - If an active process is found: check whether it was launched by a previous smoke run (recorded in `.work/smoke/runtime-desktop.yaml`). If recorded, attempt graceful shutdown and wait for exit.
+     - If the process is not from WDI smoke or cannot exit gracefully: **MUST NOT** force-kill blindly (`Stop-Process -Force` is prohibited without confirmation); report the PID, binary path, and file-lock hazard to the maintainer, and stop before rebuilding.
+  3. **Build Target:** Rebuild the binary if it is missing or older than the current `HEAD` commit, adhering to the project's build command and profile. If the binary already matches `HEAD`, skip rebuilding.
+  4. **Launch Application:** Launch the application locally using the documented launch command.
+  5. **Runtime Manifest:** Record `{ pid, started_at, artifact_path, profile, head }` to `.work/smoke/runtime-desktop.yaml` (ephemeral artifact under `.work/`, never committed).
+- **`web <target>`**: Inspect `.control/test-targets/web.md` if present. Follow deployment or serving
+  procedures documented in project guides or the devops repository for `<target>`.
+- **`mobile <target>`**: Inspect `.control/test-targets/mobile.md` if present. Use the `run` skill or
+  documented project mobile commands to target the named device or emulator `<target>`.
+
+## 4. Build Checklist from Closed Tickets (Delta-Scoped Retrieval)
+
+MUST NOT perform a full-file read or broad regex scan of the historical `specs.yaml`.
+Derive the verification checklist directly from the delivery delta:
+1. Define the delivery commit range: `before_sync..HEAD` (or fallback to `last-sync..HEAD`, or the recent merge commit on first-parent history if cursor is absent).
+2. Inspect paths touched within the delta:
+   - Identify closed specifications by matching `.scratch/*/SPEC.md` or `.control/memlog/autopilot-*.md` modified in the delta.
+   - Read the changed autopilot ledger (`.control/memlog/autopilot-<id>.md`) as an index of closed tickets and scope.
+3. For each candidate closed spec:
+   - Read candidate's `SPEC.md` and issues under `.scratch/<spec-folder>/` to extract acceptance criteria and hand-testable verification steps.
+   - Verify spec's `status: closed` selectively against `.control/registry/specs.yaml` (matching only that specific spec's block, never loading the entire file).
+4. Group hand-testable verification items by component or screen:
+
+```markdown
+Component & Issue / Screen
+  1. Feature Title
+     [ ] verification step 1
+     [ ] verification step 2
+```
+
+When a target was specified (`desktop`, `web`, or `mobile`), append the relevant template checklist
+items from `.control/test-targets/<target>.md`. If no closed spec is detected in the delta, report that
+no new closed tickets were merged in this sync.
+
+## 5. Clean Ephemeral Smoke Artifacts
+
+Clean up temporary smoke test logs and dumps under `.work/smoke/` created during the test run.
+Record the current sync commit hash to `.work/smoke/last-sync` to serve as a local non-authoritative
+cursor for subsequent runs. MUST NOT remove or modify permanent ledger files under `.control/memlog/`
+(they are permanent audit records).
+
+## 6. Report and Stop
+
+1. Display the generated checklist, target runtime info (artifact path, build profile, PID, SHA), report which merged task worktrees/branches were pruned, and note any preserved immune branches.
+2. **Post-Verification Housekeeping Notice:** Provide a non-blocking informational note:
+   *"Closed specification directories in `.scratch/` can be archived or pruned via `/wdi-prune-or-archive --spec <id> --archive` once hand-testing is complete."*
+3. Stop. MUST NOT continue into further coding, commits, or another autopilot run in the same turn.

package/kit/skills/wdi-explain-to-me/SKILL.md

@@ -26,7 +26,7 @@ Four asks look alike from the outside and are four skills:
 | Source | What it answers |
 |---|---|
 | The topic argument | An id (`OQ-12`, `DEC-007`, a defect row, a validator name), a file path, or a sentence |
-| `.control/registry/*.yaml` · `.control/generated/status` | What the registry says holds today, and which validators are red |
+| `.control/registry/*.yaml` · `.control/generated/status.md` | What the registry says holds today, and which validators are red (also available as `status.yaml`) |
 | `.control/questions/` · `.control/decisions/` | Whether this was asked or decided before, and what is already settled |
 | The working documents in `.what/` and `.how/` | The promise and the mechanism the topic touches |
 | `validate.py` output · tests · git history · the code | What actually holds, as opposed to what a document claims |

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

@@ -1,6 +1,6 @@
 ---
 name: wdi-help
-description: Use when you need to know where the project stands in the delivery flow and which skill comes next. Answers from this project's five gates, not from BMad's phase column.
+description: Check project delivery status, open or pending specs and tickets, current gate progress, and determine what to build or which skill to invoke next. Answers from this project's status registry and five gates.
 ---
 
 # WDI Help
@@ -18,15 +18,16 @@ about BMad itself.
 
 | Source | What it answers |
 |---|---|
-| `.control/generated/status` | Which spec is open, how many of its tickets are done, which validators are red |
+| `.control/generated/status.yaml` | Primary machine-readable status: which spec is open, tickets progress, red validators (or `status.md`) |
 | `.control/registry/index.yaml` | The global `mode`, and the gate map |
 | `.control/registry/components.yaml` | Per-component `mode`, `risk_accepted`, and `g4_passed` |
-| `.control/registry/specs.yaml` | Spec → release, size, `depends_on`, and its ticket index |
+| `.control/registry/specs.yaml` | Fallback only when status is absent/stale: spec → release, size, and ticket index (MUST query selectively) |
 | `.constitution/method/document/delivery-flow-guide.md` | The five gates and their checklists |
 | `.constitution/method/why/README.md` | The whole shape, when the caller has never seen the method |
 
-You MUST read `.control/generated/status` rather than counting files yourself. It is generated from the
-registry; hand-counting produces a second answer that will disagree.
+You MUST read `.control/generated/status.yaml` (or `status.md`) rather than counting files yourself. You
+MUST NOT open or inspect `.control/registry/specs.yaml` if the status file is present and answers which
+spec is open.
 
 ## What to answer
 
@@ -74,6 +75,11 @@ mis-route in this flow, because every other gate is the same for every component
 | An accepted `DEC-` has not reached its documents | `wdi-decision` intent `apply` |
 | A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, before any fix is proposed |
 | Numbers are wanted before the work is committed | `wdi-report` intent `estimate` |
+| Closed specs remain in `.scratch/`, or need archival/pruning | `wdi-prune-or-archive` — archives closed spec to `.archive/specs/` or prunes from disk |
+| Raw manual-test notes needing triage, review, and spec drafting | `wdi-daily-what-to-build` — classifies notes, drafts spec/tickets via `wdi-build`, gets second opinion |
+| Autonomous delivery loop with local runner and peer review | `wdi-daily-autopilot` — composes routine, resolves local runners, launches `/loop` unattended |
+| Merged autopilot run needing branch cleanup and physical test checklist | `wdi-daily-what-to-test` — syncs branch, prunes merged worktrees/branches, configures smoke target, provides delta-scoped checklist |
+| Cleaning up generated rendered duplicate files from git | Untrack via `git rm -r --cached .what-rendered/ .how-rendered/`, add to `.gitignore`, regenerate via `validate.py --generate` |
 
 A brief that exists but is thin is still a brief. You MUST NOT route back to `wdi-problem` because a
 section reads weakly — route there only when the brief is absent, when a change signal invalidates what
@@ -90,8 +96,16 @@ it claims, or when one of its eight required sections is missing outright.
   `wdi-blueprint`, `wdi-build`, `wdi-decision`, `wdi-review`, `wdi-ux`.
 - Only `.control/questions/blocking.md` holds a gate. `external.md` holds go-live and MUST NOT be reported
   as blocking a design gate; `assumptions.md` holds nothing.
-- You MUST NOT invent progress. If `.control/generated/status` is missing or stale, say so and name
-  `validate.py --generate`.
+- You MUST NOT invent progress. If `.control/generated/status.yaml` (or `status.md`) is missing or stale,
+  say so, query `specs.yaml` selectively, and name `validate.py --generate`.
+- You MUST NOT call Read on the entire 1000+ line `.control/registry/specs.yaml` file into context. When
+  discovering active or open work as a fallback, query `specs.yaml` selectively (e.g. `Grep` for `status:\s*(open|ready-for-dev)`).
+- You MUST NOT run broad or recursive searches across `.scratch/` (e.g. searching `*` or `**/*`). When
+  inspecting candidate open specs or tickets, inspect only the candidate spec's folder using the `spec_folder:`
+  path resolved from `specs.yaml`.
+- You MUST treat `wdi-help` as a fast status and routing skill: if filesystem drift, orphaned folders, or
+  discrepancies between registry and disk are suspected, route to `wdi-reconcile` rather than conducting
+  a filesystem audit in this skill.
 - You MUST NOT route anyone to `/setup-matt-pocock-skills` to *finish an install*. The installer seeds
   `docs/agents/` pre-answered, and that interview's own defaults send every engineering skill looking for a
   root `CONTEXT.md` and `docs/adr/` — which Article 3 forbids and `wdi-reconcile` reports. It is for

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

@@ -196,6 +196,22 @@ it to make the output quiet.
 The rows themselves are **not** yours to land. This intent produces the reader; `wdi-blueprint` intent
 `platform` owns the three inventories, and a plan-versus-code gap is its finding to route.
 
+## Rendered Files Hygiene & Gitignore (Optional)
+
+The `.what-rendered/` and `.how-rendered/` directories contain generated human-facing presentations
+derived from canonical files in `.what/` and `.how/`. The method validator deliberately excludes them
+from `COMMITTED_DIRS`, allowing products to choose whether to commit them.
+
+If the maintainer prefers to keep the git tree clean of generated presentation files:
+1. Untrack them from git: `git rm -r --cached .what-rendered/ .how-rendered/`
+2. Add both folders to `.gitignore`:
+   ```gitignore
+   .what-rendered/
+   .how-rendered/
+   ```
+3. Whenever a human-readable rendered view is needed, regenerate on demand:
+   `uv run .constitution/method/scripts/validate.py --generate`
+
 ## Rules
 
 - You MUST NOT write `.what/` or `.how/` content beyond a skeleton and its frontmatter. Behaviour is

package/kit/skills/wdi-prune-or-archive/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: wdi-prune-or-archive
+description: Clean up completed closed specs by archiving to `.archive/specs/` or pruning from disk, wrapping lifecycle.py with fail-closed safety. Invoke as `/wdi-prune-or-archive [--spec <id>|--all-closed] [--archive|--prune] [--dry-run]` or bare `/wdi-prune-or-archive` for interactive selection.
+disable-model-invocation: true
+---
+
+# WDI Prune or Archive
+
+Standalone housekeeping skill for closed specifications. Moves completed spec directories to
+`.archive/specs/<spec-folder>/` or prunes completed tickets from disk using `lifecycle.py`, while
+strictly preserving requirement traceability and RTM metadata in `.control/registry/specs.yaml`.
+
+- `/wdi-prune-or-archive` — interactive mode: discovers closed specs in `.scratch/`, presents options,
+  and confirms before execution.
+- `/wdi-prune-or-archive --spec <id> --archive` — archives `<id>` to `.archive/specs/<spec-folder>/`.
+- `/wdi-prune-or-archive --spec <id> --prune` — removes completed `<id>` folder from disk and git.
+- `/wdi-prune-or-archive --all-closed --archive` — archives all closed specs in `.scratch/`.
+- `/wdi-prune-or-archive --all-closed --prune` — prunes all closed specs in `.scratch/`.
+- Add `--dry-run` to any command to simulate without modifying files or git index.
+
+## 0. Preconditions
+
+1. Confirm `.control/registry/index.yaml` exists in the repo root. If it does not, this is not a WDI
+   Method product repo — report that and stop.
+2. Verify git working tree is clean (`git status --porcelain`). If uncommitted changes exist, stop and
+   instruct the maintainer to commit or stash changes before running real archive/prune operations.
+   (Exception: `--dry-run` permits an uncommitted tree with an advisory note).
+
+## 1. Discovery & Mode Selection
+
+### A. Interactive Mode (invoked bare: `/wdi-prune-or-archive`)
+
+1. Find closed candidate specs: inspect `.scratch/` directly or run `python .constitution/method/scripts/lifecycle.py --dry-run`
+   (or grep `specs.yaml` for `status:\s*closed` — MUST NOT dump the entire historical `specs.yaml` into context).
+2. Find all specs with `status: closed` whose directory currently resides under `.scratch/`:
+   - If no closed specs reside in `.scratch/`: report that `.scratch/` is already clean of closed specs
+     and stop.
+   - If closed specs are found: list each candidate with its ID, title/release, and folder path.
+3. Present the three housekeeping choices to the maintainer:
+   - **Archive:** Moves the directory to `.archive/specs/<spec-folder>/` via `git mv` and updates
+     `spec_folder` in `specs.yaml`. Preserves full historical audit provenance.
+   - **Prune:** Removes the directory via `git rm -r` while keeping the spec row and ticket index
+     intact in `specs.yaml`. Recommended when git commit history is sufficient.
+   - **Defer:** Leave the directories untouched and exit.
+4. Ask whether to apply the action to all eligible specs (`--all-closed`) or a specific `--spec <id>`.
+5. Display the exact command that will be executed and request confirmation.
+
+### B. Direct Flag Mode
+
+Parse arguments and map them directly to `lifecycle.py` flags:
+- If a positional spec ID is supplied (e.g. `/wdi-prune-or-archive SPEC-1 --archive`), map it to `--spec SPEC-1`.
+- Ensure exactly one action is specified: `--archive` OR `--prune`.
+- Ensure exactly one scope is specified: `--spec <id>` OR `--all-closed`.
+- Pass `--dry-run` if specified.
+
+## 2. Execution via Lifecycle Script
+
+All physical git and filesystem operations **MUST** be executed through `lifecycle.py` to guarantee
+atomicity, validation, and rollback:
+
+```powershell
+uv run .constitution/method/scripts/lifecycle.py [arguments]
+```
+
+`lifecycle.py` enforces authoritative preflights:
+- Rejects open or active specs (`status: closed` required).
+- Rejects paths outside authorized spec roots.
+- Rejects folders currently checked out by active git worktrees.
+- Rejects folders cited by active or permanent `.control/memlog/` artifact records.
+- Runs post-operation validation (`validate.py --check`) and automatically rolls back all staged and
+  worktree changes if validation fails.
+
+## 3. Report and Stop
+
+Display the result of the lifecycle operation verbatim, report updated `spec_folder` paths or pruned
+directories, and stop. MUST NOT proceed into further coding, commits, or other skill invocations.

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

@@ -188,7 +188,10 @@ reviewed:
   `EXPERIENCE.md`, and research MAY be reviewed on request; the finding report is the whole output,
   and no `reviewed:` block is written.
 - You MUST NOT stamp on behalf of a review someone else ran earlier. Re-run it; the run is cheap and
-  the claim is not.
+  the claim is not. A live peer or second-opinion review dispatched and evaluated within the same coordinating
+  session (as in `wdi-daily-what-to-build`) satisfies this requirement; the coordinator, as sole writer, writes
+  the trace based on that live session evaluation without needing to independently re-derive the findings from
+  scratch. Stale reviews from prior sessions or unverified third-party claims remain strictly prohibited.
 - When the artifact changed **materially** after the review, the trace is stale and you MUST re-run
   rather than bump the date. A wording-only change is the one exception, and §*When a review has to run
   again* owns it.

package/kit-overlay/AGENTS.md

@@ -27,7 +27,7 @@ npx wdi-method update --yes
 ```
 
 BMad: https://github.com/bmad-code-org/BMAD-METHOD
-WDI Method: https://github.com/wiradigitalid/wdi-method
+WDI Method: https://github.com/wiradeltaid/wdi-method
 
 A method file MUST NOT be invented here. If a rule is wrong, fix it in the WDI
 Method package, then update.
@@ -66,6 +66,28 @@ under `.constitution/`. They are agent instructions, and they travel to every re
 **A corpus written before these settings existed MUST NOT be migrated for them.** The readers accept more
 than one language, so existing documents keep working and only new writing follows the setting.
 
+## Branches
+
+**Two branch settings live in `.control/registry/index.yaml` under `policy:`, both defaulting to `main`:**
+
+| Setting | Governs | Default |
+|---|---|---|
+| `primary_branch` | Production / release trunk | `main` |
+| `development_branch` | Active development branch for specs, worktrees, and PR targets | `main` |
+
+- **Immunity:** Agents MUST NOT delete, overwrite, force-push, or rename `primary_branch` or `development_branch`.
+- **Branch protection:** Agents MUST NOT commit application code directly to `primary_branch` or `development_branch`. Code changes MUST arrive via isolated task branches/worktrees and pull requests. In single-branch mode, direct commits to the shared branch are permitted strictly for Phase 1 & 2 planning documents in `.scratch/` and `.control/registry/specs.yaml`.
+- **Target branch:** All worktrees and PRs MUST target `development_branch`. Agents MUST verify the branch exists locally or on remote (`refs/heads/<branch>` or `refs/remotes/origin/<branch>`) and MUST NOT guess or silently fall back to `main`.
+- `.constitution/method/branch-guide.md` binds branch rules.
+
+## Delivery flow
+
+Applies to all feature specification, ticket creation, and code delivery in this repo:
+
+1. Turning notes, a task, or test results into a spec and tickets MUST go through `wdi-build`'s engines (`to-spec` / `to-tickets`, `mattpocock/skills`) — agents MUST NOT invent a bespoke spec or ticket format.
+2. Standing exception to `wdi-build`'s isolated worktree precondition: the spec authoring step (opening the spec, writing `SPEC.md` and ticket files in `.scratch/`, with no application code changes) happens directly on the active development branch (`policy.development_branch`, default `main`). The worktree requirement binds ticket implementation onward and `wdi-autopilot`.
+3. During or after spec and ticket authoring, an agent MUST NOT auto-continue into implementing code, committing, pushing, launching `wdi-autopilot`, merging a PR, cleaning up a worktree, or deploying without explicit confirmation from the maintainer. When explicitly commanded to build a ticket (`wdi-build`), committing and pushing to the task branch are permitted, but auto-merging PRs or auto-deploying remain strictly prohibited.
+
 ## The thing in your hand → its folder
 
 Read this instead of reasoning about what `.what/` and `.how/` mean.
@@ -157,6 +179,11 @@ verifies the result, and lands the memlog.
 - `CONTEXT.md`, `CONTEXT-MAP.md`, and `docs/adr/` MUST NOT be created. `docs/agents/domain.md` is the
   engines' config and says so too: the vocabulary is `.control/product-glossary.md`, domain knowledge is
   `.what/`, design is `.how/`, and a decision is a `DEC-` — never an ADR. Article 3 owns the rule.
+- `.control/registry/specs.yaml` MUST NOT be read in full (1000+ lines) into context to check project
+  status or open work — invoke skill `wdi-help` or read the generated status projection in
+  `.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`.
 
 ## Routing — load a guide when the task matches
 
@@ -171,7 +198,7 @@ verifies the result, and lands the memlog.
 | Unsure about a domain term | `.control/product-glossary.md` |
 | Looking for a non-technical fact — a domain, an account, a legal entity, a locked date | `.control/project-non-technical-log.md` |
 | Naming anything — a code identifier, a file, a database column | `.constitution/method/language-guide.md` |
-| Asking "which gate now, what next" | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-help` |
+| Asking "which gate now, what next", project status, or open/pending specs | skill `wdi-help` (MUST invoke `wdi-help` or read generated `status.yaml`) |
 | Having to decide something, and wanting the reading done first | skill `wdi-explain-to-me` — it briefs, and changes nothing |
 | Wanting every `FR` delivered without being asked in between | skill `wdi-autopilot` — preflight, one mandate, then the loop |
 | Setting or changing `mode` or `risk_accepted` | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-init` |
@@ -185,6 +212,7 @@ verifies the result, and lands the memlog.
 | Opening, accepting, or applying a `DEC-` | `.constitution/method/document/decision-guide.md` |
 | Writing or reading a structure map | `.constitution/method/structure-guide.md` |
 | Writing or changing a CI workflow, or deciding whether a push may start a cloud run | `.constitution/method/ci-guide.md` |
+| Branching rules, protected branches, or PR target policy | `.constitution/method/branch-guide.md` |
 | Looking for where code lives, or placing new code | `.control/structure-codebase.md` |
 | Looking for where a document lives | `.control/structure-document.md` |
 | Writing or reviewing code | `.constitution/project/codebase-stack-guide.md` · `.constitution/project/codebase-conventions-guide.md` · `.constitution/project/codebase-brownfield-guide.md` |
@@ -215,9 +243,13 @@ MUST anything in `.constitution/method/why/`; `status: Reference` forbids it. A
 
 - A skill MUST NOT be invoked automatically. Name the one that fits and wait for the owner's
   go-ahead — this holds even when the skill's own description says it must be used. Reading a
-  skill as reference is fine. The one exception is `wdi-autopilot` under a `DEC-` of `type: mandate`
+  skill as reference is fine. The exceptions are: (1) `wdi-autopilot` under a `DEC-` of `type: mandate`
   at `status: accepted` that has not expired: the mandate **is** the go-ahead, for every skill it
-  needs, until it lapses.
+  needs, until it lapses; (2) when the owner explicitly invokes an autonomous daily tier skill
+  (`/wdi-daily-*`), the owner's invocation authorizes the bounded orchestration steps specified in that skill;
+  (3) read-only status, open specs, and routing inquiries (`wdi-help`): the model MUST invoke
+  `wdi-help` (or read the generated status projection in `.control/generated/`) automatically to
+  inspect current gate progress, open work, or determine the next skill without modifying project state.
 - `.work/` is not production code. It MUST NOT be imported by the application, and MUST be
   excluded when searching for code.
 <!-- END:wdi-method -->

package/kit-overlay/constitution.md

@@ -26,6 +26,7 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 | `.what-rendered/` · `.how-rendered/` | The two above, assembled for a human to read — one page per gate, at the mirror path. Regenerated by `validate.py`, never edited, never read by a skill |
 | `_bmad-output/` | Run workspace; MUST be in git, not curated |
 | `.scratch/` | One directory per effort: a spec's `SPEC.md` and its ticket files, and ad hoc work that has no `FR` yet. MUST be in git — the corpus cites into it by path |
+| `.archive/` | Archived records — closed specs and historical provenance moved from `.scratch/`. MUST be in git |
 | `.work/` | Scratch; MUST be in git, emptied when a task closes |
 | *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |