@brunosps00/dev-workflow 2.1.0 → 2.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,78 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.2.0] — 2026-08-24
+
+Release driven by two operational failures observed on a real project, both of the
+same family: the pipeline was good at *starting* long work and silent about what
+happened next. Delegated runs gave no visibility until someone asked "any news?",
+and the worktrees those runs lived in were created by a hard rule and removed by
+nobody — 35 of them (33 already merged) were sitting on disk at 40 GB with the
+root filesystem at 95%. Both fixes are deterministic where prose had failed.
+
+### Added
+
+- **`/dw-report` — timestamped progress loop for long work.** Every 10 minutes
+  (`--every <N>m`) it emits a report with a real `date` timestamp saying what is
+  **done** (cumulative, new items marked `➕`, each with evidence: file, commit,
+  test count), what is **being done** (with a measurable figure — step counter,
+  files touched, running command and elapsed time — never a bare "in progress"),
+  and what is **left** (ordered, next milestone first, remaining gates included).
+  Reports go to the chat and are appended to `.dw/reports/YYYY-MM-DD.md`. The
+  cadence is the user's: it never stretches to "wait for the build"; a report
+  saying "nothing changed, ~4 min left" is the product while work runs. Silence is
+  reserved for the blocked/idle state (the transition to blocked reports once);
+  completion produces a final report immediately and disarms the loop. Vehicle is
+  the harness's native scheduled wake-up when available, a background `sleep`
+  timer otherwise, and never a system cron (which keeps firing for days after the
+  work ended). Auto-armed by `/dw-run`, `/dw-autopilot` (execution invocation), and
+  the `dw-cli-run` adapters; `DW_REPORT_AUTO=off` opts out and `DW_REPORT_BELL`
+  hooks a local sound or notification. `now`, `status`, `stop` modes.
+- **`/dw-worktree` — the lifecycle the runner adapters never had.** Backed by
+  `.dw/scripts/lib/worktree-gc.mjs` (Node, no dependencies), which resolves the
+  main checkout from anywhere in the repo. `list` gives every secondary worktree a
+  verdict — `REMOVABLE` (head is an ancestor of an integration branch, clean, no
+  process has its cwd inside, not locked), `KEEP:unmerged`, `KEEP:dirty`,
+  `KEEP:in-use`, `KEEP:locked`, `KEEP:recent`, `PRUNABLE` — with apparent size,
+  age, and dirty count; `--strict` exits 3 on leftovers. `clean` is a **dry-run by
+  default**; `--apply` removes only `REMOVABLE` entries, deletes their branches
+  (verified merged), and prunes. `create <slug>` enforces the `../<project>-<slug>`
+  convention and runs the install/build prep (lockfile-detected or
+  `.dw/config.json` `worktree.prep`) so a delegated agent never runs blind.
+  `merge <slug>` performs the safe order from the main checkout — ff-only merge →
+  remove → branch delete → prune — and aborts **before** the merge if the main
+  checkout is off the base branch or dirty, the worktree is dirty or in use, or
+  the merge is not a fast-forward. It never uses `--force` and never changes the
+  owner's active branch. Base resolution: `--base` → `DW_WORKTREE_BASE` →
+  `worktree.base` → `origin/HEAD` → `develop` → `main` → `master`.
+
+### Changed
+
+- **End of life is the same turn as the merge.** `dw-cli-run` pre-flight creates
+  missing worktrees through `/dw-worktree create`, and its Discipline section now
+  carries the hard rule: merged → `/dw-worktree merge` (or `clean --apply`) in
+  that same turn. The three adapters point their `<WORKTREE>` input at the same
+  commands. `/dw-pause` sweeps worktrees and treats every `REMOVABLE` entry as an
+  open loop to close now rather than record; `/dw-harness-audit` gained a
+  *Worktree hygiene* category scored from `list --strict`.
+- **git guardrails** (`scaffold/scripts/hooks/git-guardrails.mjs`) also block
+  `git worktree remove --force` / `-f`; plain `remove` and `prune` stay allowed.
+- `/dw-run` (all-tasks and `--resume`) and `/dw-autopilot` Step 8 arm the progress
+  loop before dispatching; `dw-help`, the agent-instructions trigger map, and the
+  README register both commands (41 commands, Tier 2 = 11, Tier 3 = 14).
+- `dw-cli-run` `context_limit` raised 19000 → 20500 to hold the two new sections.
+
+### Fixed
+
+- `init`/`update` now create `.dw/cli-run/.gitignore` (`*`, `!.gitignore`). The
+  adapters' durable audit logs, session sidecars, and last-message captures were
+  being committed and then checked out into every worktree (219 tracked files on
+  the project that motivated this release). Existing projects untrack them with
+  `git rm -r --cached .dw/cli-run`.
+- `init`/`update` create `.dw/reports/.gitignore` so the daily report logs and the
+  loop's `.active.json` stay machine-local while other reports (e.g.
+  `context-budget.md`) remain tracked.
+
 ## [2.1.0] — 2026-08-04
 
 Release driven by a skill-by-skill analysis of [mattpocock/skills](https://github.com/mattpocock/skills),

package/README.md

@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.1.0 ships **39 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v2.2.0 ships **41 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (4)
 
@@ -53,7 +53,7 @@ dev-workflow v2.1.0 ships **39 commands** organized into four tiers. Most users
 | **`/dw-triage [item]`** | An external bug report, feature request, or PR. Checks whether it already exists and whether it was rejected before, verifies the claim, then routes to `/dw-bugfix`, `/dw-plan prd`, or `/dw-brainstorm --mode=grill`. Local-first in `.dw/triage/`; works with no network and no `gh`. |
 | **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
 
-### Tier 2 — Pipeline granular (10)
+### Tier 2 — Pipeline granular (11)
 
 Use these when you want step-by-step control instead of `/dw-autopilot`.
 
@@ -67,10 +67,11 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (AI eval against reference dataset), `--uat` (human-in-the-loop walkthrough), `--bugfix <slug>` (QA a bugfix). |
 | **`/dw-pause`** | Consolidate the current session's mental state into `.dw/STATE.md` (Decisions, Blockers, Todos, Deferred, Lessons, Open Loops). Used before long breaks or context-window compactions. |
 | **`/dw-resume`** | Read `.dw/STATE.md`, present a TLDR of where work left off, and suggest the next `dw-*` command. Never auto-executes. |
+| **`/dw-report [--every <N>m]`** | Timestamped progress loop while long work runs: what is done (with evidence), what is being done (with measurable progress), what is left — every 10 minutes by default, appended to `.dw/reports/YYYY-MM-DD.md`. Silent while blocked, final report + auto-disarm when the work ends. `now`, `status`, `stop`. Auto-armed by `/dw-run`, `/dw-autopilot`, and the CLI runners; `DW_REPORT_AUTO=off` opts out, `DW_REPORT_BELL` hooks a local sound. |
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (13)
+### Tier 3 — Specialty (14)
 
 | Command | What |
 |---------|------|
@@ -82,6 +83,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
+| **`/dw-worktree <list\|create\|clean\|merge>`** | Lifecycle of delegation worktrees (`../<project>-<slug>`): `create` runs install/build prep so a delegate never works blind; `list` gives every worktree a verdict (`REMOVABLE`, `KEEP:unmerged`, `KEEP:dirty`, `KEEP:in-use`); `clean` removes only proven-merged-and-clean ones (dry-run by default, `--apply` to execute); `merge` does the safe order from the main checkout (ff-only → remove → branch delete → prune). Never `--force`. Backed by `.dw/scripts/lib/worktree-gc.mjs`; auto-used by the CLI runners, `/dw-pause`, and `/dw-harness-audit`. |
 | **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
 | **`/dw-new-project`** | Bootstrap a new project from an empty or docs-first directory while preserving existing documentation and prototypes. Stack interview includes Next.js + NestJS, Postgres, pg-boss, Mailpit, dev topology, and wraps official `create-*` tools before composing dev infrastructure, `.env`, scripts, CI, and `.dw/rules/`. |
 | **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
@@ -226,6 +228,7 @@ your-project/
 │   ├── spec/              # PRD directories — each contains tasks-validation.md
 │   ├── bugfixes/          # Persistent bugfix records: NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md} + review/, QA/
 │   ├── goals/             # Durable goal state used by /dw-goal and /dw-autopilot
+│   ├── reports/           # Progress-report loop (/dw-report): daily YYYY-MM-DD.md logs + .active.json, machine-local (gitignored)
 │   ├── secure-audit/      # Security Gate summaries and per-layer reports
 │   ├── subtasks/          # Local ephemeral subagent input packets and handoffs (pending/archive ignored by Git)
 │   └── STATE.md           # Session state: Decisions, Blockers, Todos, Open Loops, Deferred Ideas, Lessons, Preferences (managed by /dw-pause + /dw-resume)

package/lib/constants.js

@@ -29,6 +29,7 @@ const COMMANDS = {
     { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai / --uat). --fix enters the iterative QA + fix-retest loop. --bugfix <slug> targets a .dw/bugfixes/ entry.' },
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
     { name: 'dw-refactor', description: 'Audits a target for refactor opportunities using the refactor-audit protocol, Fowler smells, deep-modules analysis, and behavior-preserving test gates.' },
+    { name: 'dw-report', description: 'Trigger when user asks for periodic progress reports ("report every 10 minutes", "keep me posted while this runs"). Timestamped done / doing / remaining report at a fixed cadence (default 10m, --every <N>m), appended to .dw/reports/YYYY-MM-DD.md; silent while blocked, final report + auto-disarm when the work ends. Auto-armed by dw-run, dw-autopilot, and the dw-cli-run adapters.' },
     { name: 'dw-resume', description: 'Trigger when user says "resume work", "where did we stop?", or starts a session in a project with an existing .dw/STATE.md. Reads STATE.md, presents a TLDR, and suggests the next dw-* command.' },
     { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
@@ -38,6 +39,7 @@ const COMMANDS = {
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-triage', description: 'Local-first intake for external bug reports, feature requests, and PRs. Persists .dw/triage/ state, checks redundancy and prior rejections, verifies claims, then routes to /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, or no work.' },
+    { name: 'dw-worktree', description: 'Worktree lifecycle for delegated work: create prepared (../<project>-<slug> + install/build prep), list with verdicts (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), clean only what is proven merged and clean (dry-run by default), merge in the safe ff-only order and remove in the same turn. Never --force. Backed by .dw/scripts/lib/worktree-gc.mjs; used by the dw-*-run adapters, /dw-pause, and /dw-harness-audit.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
@@ -70,6 +72,7 @@ const COMMANDS = {
     { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai / --uat). --fix entra no loop iterativo QA + fix-retest. --bugfix <slug> aponta para uma entrada em .dw/bugfixes/.' },
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
     { name: 'dw-refactor', description: 'Audita um target por oportunidades de refactor usando o protocolo refactor-audit, smells Fowler, deep-modules e gates de teste preservando comportamento.' },
+    { name: 'dw-report', description: 'Trigger quando usuário pede report periódico de progresso ("report de 10 em 10 minutos", "me mantém informado enquanto isso roda"). Report carimbado com data/hora de feito / fazendo / falta em cadência fixa (default 10m, --every <N>m), anexado em .dw/reports/YYYY-MM-DD.md; silencioso enquanto bloqueado, report final + auto-desarme quando o trabalho termina. Auto-armado por dw-run, dw-autopilot e pelos adapters dw-cli-run.' },
     { name: 'dw-resume', description: 'Trigger quando usuario diz "retoma", "onde paramos?" ou comeca sessao num projeto com .dw/STATE.md existente. Le STATE.md, apresenta TLDR e sugere proximo comando dw-*.' },
     { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
@@ -79,6 +82,7 @@ const COMMANDS = {
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
     { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos. Persiste estado em .dw/triage/, checa redundância e rejeições anteriores, verifica alegações, e então roteia para /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, ou nenhum trabalho.' },
+    { name: 'dw-worktree', description: 'Ciclo de vida de worktrees de delegação: cria preparada (../<projeto>-<slug> + prep de install/build), lista com vereditos (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), limpa só o que está provadamente mergeado e limpo (dry-run por default), mergeia na ordem segura ff-only e remove no mesmo turno. Nunca --force. Apoiado em .dw/scripts/lib/worktree-gc.mjs; usado pelos adapters dw-*-run, /dw-pause e /dw-harness-audit.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/init.js

@@ -283,6 +283,32 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     touchedFiles.push(metricsGitignore);
   }
 
+  // 5.25b. Ensure .dw/reports/ + .gitignore (progress-report loop; the daily logs and
+  // the .active.json loop state are machine-local so they are gitignored, while other
+  // reports such as context-budget.md stay tracked). Created if missing on init and update.
+  {
+    const reportsDir = path.join(projectRoot, '.dw', 'reports');
+    ensureDir(reportsDir);
+    const reportsGitignore = path.join(reportsDir, '.gitignore');
+    const rStatus = writeFile(reportsGitignore, '????-??-??.md\n.active.json\n', false);
+    if (rStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(reportsGitignore);
+  }
+
+  // 5.25c. Ensure .dw/cli-run/ + .gitignore (durable audit logs, session sidecars and
+  // last-message captures of the dw-*-run adapters are machine-local; committing them
+  // bloats every worktree checkout). Created if missing on init and update.
+  {
+    const cliRunDir = path.join(projectRoot, '.dw', 'cli-run');
+    ensureDir(cliRunDir);
+    const cliRunGitignore = path.join(cliRunDir, '.gitignore');
+    const cStatus = writeFile(cliRunGitignore, '*\n!.gitignore\n', false);
+    if (cStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(cliRunGitignore);
+  }
+
   // 5.26. Ensure .dw/memory/instincts/ (durable learnings promoted by /dw-learn;
   // format in the dw-memory skill's references/instincts.md). Init only; preserved on update.
   if (!isUpdate) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/agent-instructions.md

@@ -37,6 +37,8 @@ Before picking a command from the Trigger Map, gauge the change's actual scope.
 | "Run this as a goal" / "durable goal" / "long-running objective" | `/dw-goal "<objective>"` |
 | "Continue where I left off" | `/dw-run --resume` |
 | "Pause work" / "End the session" / "Save where we are" | `/dw-pause` |
+| "Report every N minutes" / "Keep me posted while this runs" / "Give me status reports" | `/dw-report [--every <N>m]` |
+| "Create a worktree for X" / "Clean up the worktrees" / "Merge worktree X" / "How many worktrees are left?" | `/dw-worktree create <slug>` / `/dw-worktree clean --apply` / `/dw-worktree merge <slug>` / `/dw-worktree list` |
 | "Resume" / "Where did we stop?" / "Pick up where we left off" | `/dw-resume` |
 | "QA this feature" / "Run the test plan" | `/dw-qa` |
 | "Fix the QA bugs" | `/dw-qa --fix` |

package/scaffold/en/commands/dw-autopilot.md

@@ -143,6 +143,8 @@ After approval:
 
 ### Step 8: Durable Execution Goal
 
+First arm the progress loop: invoke `/dw-report` (auto-arm contract — idempotent, skipped when `DW_REPORT_AUTO=off`). It reports done / doing / remaining every 10 minutes through the goal, the Security Gate, commit, and PR, and disarms itself with a final report at the PR gate.
+
 When `autopilot-state.json status=plan_complete`, formally invoke:
 
 ```text

package/scaffold/en/commands/dw-claude-run.md

@@ -39,7 +39,7 @@ Because you pass `--session-id "$UUID"`, the id is **fixed and known** at dispat
 ## Input Variables
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
+| `<WORKTREE>` | dedicated git worktree (off main) — create with `/dw-worktree create <slug>` (prep included); after the gate and merge, remove in the same turn with `/dw-worktree merge <slug>` | `~/code/vizzita-billing-s10` |
 | `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
 | `<slug>` | task key for audit/session files | `prd-billing-integrador` |
 | `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |

package/scaffold/en/commands/dw-codex-run.md

@@ -40,7 +40,7 @@ gone: `codex exec resume --last` from the same worktree.
 ## Input Variables
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
+| `<WORKTREE>` | dedicated git worktree (off main) — create with `/dw-worktree create <slug>` (prep included); after the gate and merge, remove in the same turn with `/dw-worktree merge <slug>` | `~/code/vizzita-billing-s10` |
 | `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
 | `<slug>` | task key for audit/session files | `prd-billing-integrador` |
 | `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |

package/scaffold/en/commands/dw-copilot-run.md

@@ -37,7 +37,7 @@ Fallback if the sidecar is gone: `copilot --continue -p …` from the same workt
 ## Input Variables
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
+| `<WORKTREE>` | dedicated git worktree (off main) — create with `/dw-worktree create <slug>` (prep included); after the gate and merge, remove in the same turn with `/dw-worktree merge <slug>` | `~/code/vizzita-billing-s10` |
 | `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
 | `<slug>` | task key for audit/session files | `prd-billing-integrador` |
 | `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |

package/scaffold/en/commands/dw-harness-audit.md

@@ -22,7 +22,9 @@ You are the dev-workflow harness auditor.
    - Verification gates
    - Security gates
    - Context discipline
+   - Worktree hygiene
 3. For structured skill returns, inspect bundled skill `SKILL.md` files and require a `## Structured Return` contract with `Status`, `Evidence`, `Artifacts`, and `Next Step`.
+3b. For worktree hygiene, run `node .dw/scripts/lib/worktree-gc.mjs list --strict`. Exit 3 (any `REMOVABLE` or `PRUNABLE` worktree) caps the category at 3/10; cite each leftover with its size and verdict and recommend `/dw-worktree clean --apply`. `KEEP:*` entries are informational.
 4. Cite missing paths, broken references, stale managed files, and skills without a structured return.
 5. Recommend the top 3 fixes.
 

package/scaffold/en/commands/dw-help.md

@@ -23,7 +23,7 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-bugfix "description"` | A bug or error report. Surgical fix or PRD route. |
 | `/dw-help [keyword]` | This screen. Pass a keyword for shortcuts. `--advanced` reveals internal commands. |
 
-## Tier 2 — Pipeline granular (10)
+## Tier 2 — Pipeline granular (11)
 
 | Command | What |
 |---------|------|
@@ -35,10 +35,11 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-qa` | Mode-aware QA (UI / API auto-detect). Flags: `--fix`, `--api`, `--ai`, `--uat`, `--bugfix <slug>`. |
 | `/dw-pause` | Save session state, decisions, blockers, todos, and open loops into `.dw/STATE.md`. |
 | `/dw-resume` | Read `.dw/STATE.md`, show a TLDR, and suggest the next `dw-*` command. |
+| `/dw-report [--every <N>m]` | Timestamped done / doing / remaining report every 10 minutes while long work runs; appended to `.dw/reports/`. `now`, `status`, `stop`. Auto-armed by `/dw-run`, `/dw-autopilot`, and the CLI runners. |
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (12)
+## Tier 3 — Specialty (13)
 
 | Command | What |
 |---------|------|
@@ -50,6 +51,7 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
 | `/dw-harness-audit` | Score dev-workflow install health: wrappers, agents, MCPs, gates. |
 | `/dw-skill-health` | Audit skills and agents for bloat, duplication, and missing references. |
+| `/dw-worktree <list\|create\|clean\|merge>` | Worktree lifecycle: create prepared, list with verdicts, clean only proven-merged (dry-run default), ff-only merge + remove in the same turn. Never `--force`. |
 | `/dw-new-project` | Interview-driven bootstrap (stack + infra + docker-compose + CI). |
 | `/dw-dockerize` | Detect stack, propose Dockerfile + docker-compose for dev/prod. |
 | `/dw-install-azure-skills` | Opt-in Azure skills + Microsoft Learn MCP setup. Interactive category selection. |
@@ -103,6 +105,7 @@ Match the keyword and suggest:
 | `run`, `execute`, `implement` | `/dw-run` |
 | `goal`, `objective`, `long-running`, `resume autopilot` | `/dw-goal` or `/dw-autopilot` if `autopilot-state.json` exists |
 | `pause`, `save state`, `end session` | `/dw-pause` |
+| `report`, `progress`, `keep me posted`, `status every` | `/dw-report [--every <N>m]` |
 | `resume`, `continue`, `where did we stop` | `/dw-resume` |
 | `review`, `quality`, `audit code` | `/dw-review` |
 | `qa`, `test plan`, `e2e` | `/dw-qa` |
@@ -121,6 +124,7 @@ Match the keyword and suggest:
 | `design.md`, `design authority`, `concerns map` | `/dw-analyze-project` (also listed as a post-update action when missing) |
 | `subagent`, `subtask`, `handoff`, `delegate` | `/dw-subtask-start` or `/dw-subtask-resume` |
 | `skills`, `skill health`, `bloat` | `/dw-skill-health` |
+| `worktree`, `worktrees`, `disk`, `merge worktree`, `clean worktrees` | `/dw-worktree list` / `create <slug>` / `clean --apply` / `merge <slug>` |
 | `analyze`, `rules`, `conventions` | `/dw-analyze-project` |
 | `constitution`, `principles` | `/dw-analyze-project` (Step 8 generates the constitution) |
 | `security opportunities`, `hardening ideas`, `improve security` | `/dw-opportunities "security"` |

package/scaffold/en/commands/dw-pause.md

@@ -29,6 +29,7 @@ You are a session-handoff agent. Your job is to consolidate the current session'
 Read the conversation context and identify, **without inventing**:
 
 - **Open loops**: tasks/work started but not finished (e.g. "PRD `prd-foo` is at TechSpec stage, awaiting user approval"; "Task 3 of `prd-bar` failing on lint")
+- **Leftover worktrees**: run `node .dw/scripts/lib/worktree-gc.mjs list`. Every `REMOVABLE` entry is an open loop to close **now** with `/dw-worktree clean --apply` — not something to record; `KEEP:*` entries go under Open Loops with their verdict and reason.
 - **Decisions made**: choices the user and agent agreed on during the session that affect future work
 - **Blockers encountered**: things that stopped forward motion (waiting on input, broken tooling, knowledge gap)
 - **Todos** mentioned in passing that don't yet have a PRD or task file

package/scaffold/en/commands/dw-report.md

@@ -0,0 +1,169 @@
+<system_instructions>
+You are the progress-report loop. While long work is running in this session, you emit a detailed, timestamped report at a fixed cadence (default every 10 minutes) saying **what is already done, what is being done right now, and what is still left** — without the user having to ask "any news?". Each report goes to the chat AND is appended to a daily log under `.dw/reports/`. The loop disarms itself when the work is finished.
+
+## When to Use
+- Use when the user says "report every N minutes", "keep me posted while this runs", "give me status reports", "I want to know where we are every 10 minutes".
+- Auto-armed by `/dw-run` (all-tasks and `--resume` modes), by `/dw-autopilot` (execution invocation), and by the `dw-cli-run` adapters (`/dw-codex-run`, `/dw-claude-run`, `/dw-copilot-run`) when they dispatch long work. Auto-arm is idempotent and can be disabled with `DW_REPORT_AUTO=off`.
+- Do NOT use as a substitute for `/dw-pause` (mental-state handoff) or `/dw-goal status` (goal contract state). This is a heartbeat about work in flight, not durable project state.
+- Do NOT use to poll a background task the harness already notifies you about — the loop reports *around* those notifications; it never replaces them.
+
+## Pipeline Position
+**Predecessor:** any long-running command (`/dw-run`, `/dw-autopilot`, `/dw-goal`, `/dw-codex-run`, builds, deploys) | **Successor:** none — the loop ends with a final report; `/dw-pause` may consume the day's log.
+
+## Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-report` | Arm the loop at the default cadence (**10 minutes**). If already armed, print the current state and do nothing else. |
+| `/dw-report --every <N>m` | Arm (or re-arm) the loop at `N` minutes (`5m`, `10m`, `15m`, `30m`; `--every 600s` also accepted). Minimum `1m`. |
+| `/dw-report now` | Emit one report immediately, without touching the cadence. Works armed or not. |
+| `/dw-report status` | Show whether the loop is armed, the cadence, when it was armed, the last report time, how many reports were emitted, and the log path. |
+| `/dw-report stop` | Disarm. Emits a final report first if there is unreported progress. |
+
+## Inputs
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{EVERY}}` | Cadence. Optional; defaults to `10m`. | `--every 5m` |
+| `DW_REPORT_AUTO` | Env var. `off` disables auto-arm from other commands (manual `/dw-report` still works). | `DW_REPORT_AUTO=off` |
+| `DW_REPORT_BELL` | Env var. Optional shell command executed right before each report is written (local sound, desktop notification, etc.). Silent when unset. | `DW_REPORT_BELL="paplay /usr/share/sounds/freedesktop/stereo/message.oga"` |
+
+`report.bell` in `.dw/config.json` is the file-based equivalent of `DW_REPORT_BELL` (env var wins). Because the bell is machine-specific, prefer the env var over committing it.
+
+## State and Artifacts
+
+```
+.dw/reports/
+├── .gitignore        # ????-??-??.md and .active.json are machine-local (created by init/update)
+├── .active.json      # loop state — exists only while armed
+└── YYYY-MM-DD.md     # append-only daily log; one entry per emitted report
+```
+
+`.active.json` schema:
+
+```json
+{
+  "schema_version": "1.0",
+  "armed_at": "2026-08-24 15:10:02",
+  "every_seconds": 600,
+  "vehicle": "wakeup | background-bash",
+  "armed_by": "user | dw-run | dw-autopilot | dw-cli-run",
+  "seq": 3,
+  "last_report_at": "2026-08-24 15:40:12",
+  "last_state": "working | blocked | finished"
+}
+```
+
+Timestamps are **real** — always taken from `date '+%Y-%m-%d %H:%M:%S'`, never estimated.
+
+## Vehicle — how the loop stays alive
+
+<critical>The main thread never sleeps in the foreground. Pick ONE vehicle, record it in `.active.json`, and never claim "loop armed" unless that vehicle is actually scheduled.</critical>
+
+1. **Native wakeup (PREFERRED — Claude Code).** Use the harness's scheduled-wakeup facility (the same mechanism as `/loop` in self-paced mode): after every tick, schedule the next wake-up in `every_seconds`. Pass `noop: true` on a silent tick and `noop: false` on a tick that reported. The `reason` is `dw-report tick every <N>m`. The loop dies with the session — no orphan.
+2. **Background shell timer (FALLBACK — Codex, Copilot, OpenCode, or any harness without wakeups).** Run, in the background, `sleep <every_seconds>; date '+%Y-%m-%d %H:%M:%S'`. When its completion notification arrives, run the tick, then start the next timer. One timer at a time; never chain sleeps in the foreground.
+3. **Never a system cron.** A cron does not know when the work ended and keeps firing (and ringing the bell) for days. If the harness only offers cron-style scheduling, use it but treat `/dw-report stop` and the auto-disarm rule as mandatory cleanup.
+
+If the work changes vehicle mid-way (e.g. the session is resumed elsewhere), `/dw-report status` must say so honestly: `armed in state file, but no wake-up is scheduled in this session — run /dw-report to re-arm`.
+
+## Tick Protocol (every fire)
+
+1. **Timestamp.** `date '+%Y-%m-%d %H:%M:%S'`.
+2. **Assess from the session.** The source of truth is the session's own work — what you did, what you started, what came back. Use cheap observable checks as evidence, not as archaeology: `git log --oneline` since the last report, `git status --short | wc -l`, the tail of a log or stream this session started, the number of completed steps in a CLI stream (`grep -c '"type":"item.completed"' <stream>.jsonl`), a background task's last notification. Do NOT go mining `.dw/spec/`, `.dw/goals/`, or `STATE.md` to reconstruct history you were not part of.
+3. **Classify the moment.**
+   - **working** — something is in flight (a command, a subagent, a workflow, a CLI run, a build, a deploy) or you are actively implementing.
+   - **blocked** — nothing is running because the work is waiting on the user (a decision, an approval, a credential).
+   - **finished** — the work the loop was armed for is complete (or failed terminally) and nothing else is queued.
+4. **Decide whether to speak.**
+   - `working` → **REPORT**. Always. Even when nothing changed since the last tick ("build still at step 6/9, ~4 min left" is a valid, expected report).
+   - `blocked` → report **once** when the state changes to blocked (that is news); afterwards, on every tick where nothing changed, **stay silent**: no chat line, no log entry, no bell. The check happens; the output does not.
+   - `finished` → **FINAL REPORT immediately** (do not wait for the cadence when you notice completion outside a tick), then **disarm**: delete `.active.json`, cancel the pending wake-up/timer, and say so in the final report.
+5. **Bell (optional).** If `DW_REPORT_BELL` (or `report.bell`) is set, run it *before* writing. Never on a silent tick.
+6. **Write.** The report goes to the chat and is appended verbatim to `.dw/reports/YYYY-MM-DD.md` (create the file with a `# Reports — YYYY-MM-DD` heading if missing). Update `.active.json` (`seq`, `last_report_at`, `last_state`).
+7. **Re-arm** the vehicle — unless step 4 disarmed the loop.
+
+## Report Format — cumulative with delta highlighted
+
+The user asked for a **detailed** report. Detailed means: every item carries evidence, every in-flight item carries a measurable progress figure, and the remaining list is ordered with the next milestone first.
+
+```markdown
+📊 Report — 2026-08-24 15:40:12 (#3 · every 10m · armed 15:10)
+
+## ✅ Done (cumulative)
+- ➕ Task 3/7 — import parser handles quoted fields — `src/import/parser.ts`, commit `a1b2c3d`, 14 tests green
+- ➕ Task 2/7 — CSV schema validation — commit `9f8e7d6`, `npm test` 41/41
+- Task 1/7 — fixture set for imports — commit `1234abc`
+
+## 🔄 Doing
+- Task 4/7 — batch upsert endpoint — 6 files touched, last command `npm test -- import` (running 1m40s); codex stream: 23 steps completed, last `command_execution: pnpm build`
+
+## ⏳ Remaining
+1. Task 5/7 — error report download (next milestone, blocked on Task 4)
+2. Task 6/7 — UI wiring
+3. Task 7/7 — E2E for the happy path
+4. Level 2 review + QA + security gate
+
+## ⚠️ Blockers / decisions needed
+- none
+```
+
+Rules:
+- **`➕` marks items completed since the previous report.** Older items stay in the list without the marker, so each report is self-contained and still shows the pace.
+- **Evidence or it did not happen:** a file path, a commit SHA, a test count, a log line. "Implemented X" without evidence is not allowed.
+- **Measurable progress in Doing:** a step counter, a file count, a running command with its elapsed time, a percentage from a real progress line. Never a bare "in progress".
+- **Remaining is ordered:** the next milestone first, then the rest; include the pipeline gates that still lie ahead (review, QA, security audit, commit, PR) when they apply.
+- **Blockers section only when there is something to say** — otherwise write `- none` or omit it.
+- **Header counts are real:** `#n` is `seq`, the cadence and the arm time come from `.active.json`.
+- When the loop was armed by another command, the first report says so: `armed by /dw-run (all pending tasks)`.
+
+### Final report
+
+Same shape, with the header `📊 FINAL Report — <timestamp> (#n · loop disarmed)`, an explicit outcome line under Done (`Outcome: all 7 tasks committed, review APPROVED` or `Outcome: FAILED at task 4 — see blockers`), and `Remaining` listing what the user still has to do by hand (open the PR, approve the gate, merge).
+
+### Chat output for arm / status / stop
+
+```
+📊 Report loop armed — every 10m · vehicle: wakeup · log: .dw/reports/2026-08-24.md
+First report at ~15:20. Silent while blocked; final report + auto-disarm when the work ends. Stop with /dw-report stop.
+```
+
+```
+📊 Report loop — ARMED · every 10m · since 15:10 · 3 reports · last 15:40 · state: working · log: .dw/reports/2026-08-24.md
+```
+
+```
+📊 Report loop — NOT armed. Arm with /dw-report [--every <N>m].
+```
+
+## Cadence Discipline
+
+<critical>The cadence is the user's, not yours. Never stretch the interval to "wait for the build to finish" or "avoid noise" — a report that says "nothing changed, ~X min left" is the product while work is running. Change the interval only on an explicit user instruction (`--every`).</critical>
+
+<critical>Never claim the loop is active without a scheduled wake-up or a live background timer. `/dw-report status` reads `.active.json` AND checks the vehicle; if they disagree, say so.</critical>
+
+<critical>Silence is only for the blocked/idle state. Working state always reports; the transition to blocked reports once; completion reports immediately.</critical>
+
+## Auto-arm Contract (for the commands that call this)
+
+When `/dw-run` (Mode 2 / Mode 3), `/dw-autopilot` (execution invocation), or a `dw-cli-run` adapter starts long work, it invokes `/dw-report` **before** dispatching:
+
+- **Idempotent:** if `.dw/reports/.active.json` exists and the vehicle is live, do nothing (keep the existing cadence). If the file exists but the vehicle is dead, re-arm and say so.
+- **Respects opt-out:** if `DW_REPORT_AUTO=off`, skip silently (one line in the caller's output: `report loop: auto-arm disabled by DW_REPORT_AUTO`).
+- **Records the caller:** `armed_by` in `.active.json`, echoed in the first report.
+- **Ends with the caller's work:** the caller's completion (all tasks done + final review, goal complete + PR gate, CLI run gated) is the `finished` state — final report, then disarm. The caller does not need to call `/dw-report stop`.
+- **Never blocks the caller:** arming takes one tool call; if the vehicle is unavailable, the caller proceeds and prints `report loop: no wake-up vehicle available in this harness — run /dw-report manually if you want a background timer`.
+
+## Anti-patterns
+- Reporting "in progress" without a number, a command, or a file.
+- Inventing a timestamp, a commit SHA, or a test count.
+- Emitting `idle` / `no news` lines while nothing is running — that is exactly the noise this loop exists to prevent.
+- Stretching or skipping a tick while work is running.
+- Leaving a system cron behind after the work ended.
+- Reading `.dw/spec/` or `.dw/goals/` to narrate work this session did not do.
+- Ringing the bell on a silent tick.
+
+## Structured Return
+
+After arming, stopping, or each report, the command's own status is fully described by the chat line plus `.dw/reports/.active.json`. Other commands only need to know: **armed (bool), every_seconds, seq, last_state**.
+
+</system_instructions>

package/scaffold/en/commands/dw-run.md

@@ -93,6 +93,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
 
 ### Behavior
 
+0. **Arm the progress loop:** invoke `/dw-report` (auto-arm contract — idempotent when `.dw/reports/.active.json` is already live; skipped when `DW_REPORT_AUTO=off`). It reports done / doing / remaining every 10 minutes while the waves run and disarms itself with a final report after the final Level 2 review.
 1. **Plan check (via `dw-execute-phase/plan-checker` agent):**
    - 6-dimension goal-backward verification: are these tasks actually going to deliver what the PRD promises?
    - If FAIL on any dimension, STOP and report to user before any code is touched.
@@ -133,7 +134,7 @@ When available under `./.agents/skills/`, these skills are invoked per task:
 
 1. Read `active-session.md` to determine which task/wave the session stopped at.
 2. Surface to user: "Resuming from wave N, task X.0. Previously completed: <list>. Continue?"
-3. On confirmation, resume from the next pending task with the same Mode 2 behavior.
+3. On confirmation, resume from the next pending task with the same Mode 2 behavior (including step 0 — arm `/dw-report`).
 
 If `active-session.md` doesn't exist but uncompleted tasks remain, treat as Mode 2 fresh start.