@brunosps00/dev-workflow 1.0.1 → 1.0.2

package/README.md

@@ -26,13 +26,13 @@ npx @brunosps00/dev-workflow install-deps
 
 ## Commands
 
-dev-workflow v1.0.0 ships **20 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.0.2 ships **22 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
 | Command | When |
 |---------|------|
-| **`/dw-autopilot "wish"`** | Default entry point. Full pipeline (PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR) with 3 approval gates. |
+| **`/dw-autopilot "wish"`** | Default entry point. Full pipeline (PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR) with 3 approval gates. Use `--from-prd <slug>` to resume from an existing PRD (e.g., after a `/dw-bugfix` safety-valve escalation): skips Steps 1–4 and starts at GATE 1. |
 | **`/dw-bugfix "description"`** | A bug report or pasted error. Triages bug-vs-feature-vs-scope, surgical fix or routes to a PRD. |
 | **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
 
@@ -45,8 +45,10 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-brainstorm "idea"`** | Refine an idea before PRD. Flags: `--onepager` (durable artifact), `--council` (multi-advisor debate), `--research` (multi-source cited research), `--refactor` (Fowler code-smell catalog). |
 | **`/dw-plan "feature"`** | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. Mandatory clarification questions, source-grounding, constitution gate, final consistency check. |
 | **`/dw-run [task-id]`** | Execute tasks. Default: all pending in dependency order with wave-based parallel dispatch. Single-task: pass an ID. `--resume` continues an interrupted plan. |
-| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`. |
-| **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (run AI eval against reference dataset). |
+| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`). |
+| **`/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-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. |
 
@@ -54,7 +56,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 
 | Command | What |
 |---------|------|
-| **`/dw-analyze-project`** | Scans the repo, writes `.dw/rules/` (per-module conventions, anti-patterns, naming). Step 8 offers to generate `.dw/constitution.md` (declarative principles the team commits to). Run once per project; refresh after major refactors. |
+| **`/dw-analyze-project`** | Scans the repo, writes `.dw/rules/` (per-module conventions, anti-patterns, naming). Step 8 offers to generate `.dw/constitution.md` (declarative principles the team commits to). Step 9 generates `.dw/rules/concerns.md` (risk map: hot spots, fragile integrations, hostile code, bug history). Run once per project; refresh after major refactors. |
 | **`/dw-redesign-ui "target"`** | Audits a frontend page, runs the `dw-ui-discipline` 4-question grounding, proposes 2-3 design directions, ships the redesign. WCAG 2.2 AA accessibility floor is non-negotiable. |
 | **`/dw-functional-doc`** | Maps screens + user flows into a functional doc, validated end-to-end with Playwright. |
 | **`/dw-new-project`** | Bootstrap a new project from empty directory. Stack interview, wraps official `create-*` tools, composes docker-compose for dev, seeds `.env`, scripts, CI, `.dw/rules/`. |
@@ -163,15 +165,18 @@ All wrappers point to `.dw/commands/` as the single source of truth.
 ```
 your-project/
 ├── .dw/
-│   ├── commands/          # 20 workflow command files (v1.0.0)
-│   ├── templates/         # Document templates (PRD, TechSpec, etc.)
+│   ├── commands/          # 22 workflow command files (v1.0.2)
+│   ├── templates/         # Document templates (PRD, TechSpec, state, concerns, bugfix-summary, etc.)
 │   │   └── overrides/     # Project-local template customizations (override > core)
 │   ├── rules/             # Project-specific rules (run /dw-analyze-project)
+│   │   └── concerns.md    # Risk map: hot spots, fragile integrations, bug history (Step 9 of /dw-analyze-project)
 │   ├── constitution.md    # Declarative principles (auto-installed when missing)
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
-│   └── spec/              # PRD directories — each contains tasks-validation.md
-├── CLAUDE.md              # Auto-trigger decision tree for Claude Code (merge-aware)
+│   ├── spec/              # PRD directories — each contains tasks-validation.md
+│   ├── bugfixes/          # Persistent bugfix records: NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md} + review/, QA/
+│   └── STATE.md           # Session state: Decisions, Blockers, Todos, Open Loops, Deferred Ideas, Lessons, Preferences (managed by /dw-pause + /dw-resume)
+├── CLAUDE.md              # Auto-trigger decision tree for Claude Code (merge-aware, includes Auto-Sizing Matrix)
 ├── AGENTS.md              # Same content for Codex / Copilot / OpenCode
 ├── .claude/
 │   ├── skills/            # Claude Code wrappers
@@ -262,6 +267,8 @@ Incident response (`dw-incident-response`) adapted from [`wilsto/claude-code-sta
 
 LLM evaluation (`dw-llm-eval`) trajectory-match modes (strict / unordered / subset / superset) and tool-argument matching strategies adapted from [`langchain-ai/agentevals`](https://github.com/langchain-ai/agentevals) (MIT). The broader oracle-ladder framing, judge-calibration discipline, and reference-dataset principle are distilled from the open evaluations literature (OpenAI evals cookbook, Anthropic evals guidance, the academic eval-of-LLM body of work) and rewritten in our voice.
 
+Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex) formalized in `CLAUDE.md`/`AGENTS.md` above the Trigger Map; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
+
 Four patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding new commands or skills** — instead they fold into the existing surface as internal modes and inline guidance: (1) **grill-with-docs** → `/dw-brainstorm` `grill` mode (interview discipline that stress-tests plan vocabulary against `.dw/rules/`); (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same release also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
 
 ## Migration from v0.x (1.0.0 is a consolidation release)

package/lib/constants.js

@@ -2,7 +2,7 @@ const COMMANDS = {
   en: [
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
-    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. Runs full PRD-to-PR pipeline with three gates.' },
+    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. Runs full PRD-to-PR pipeline with three gates. Use --from-prd <slug> to resume from an existing PRD (e.g., after a /dw-bugfix safety-valve escalation), skipping Steps 1-4 and starting at GATE 1.' },
     { name: 'dw-brainstorm', description: 'Refine an idea against the product\'s existing features. Modes: default ideation, --research (multi-source cited research), --refactor (Fowler code-smell catalog), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
@@ -13,10 +13,12 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lists primary commands and the flows that connect them. Pass --advanced to see internal/hidden commands.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
+    { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
     { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
-    { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai). --fix enters the iterative QA + fix-retest loop.' },
+    { 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-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.' },
+    { 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>.' },
     { 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.' },
     { name: 'dw-secure-audit', description: 'Unified security audit: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise check. Hidden; auto-invoked by /dw-review and /dw-generate-pr.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
@@ -24,7 +26,7 @@ const COMMANDS = {
   'pt-br': [
     { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
-    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Roda pipeline completo PRD-ao-PR com tres gates.' },
+    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Roda pipeline completo PRD-ao-PR com tres gates. Use --from-prd <slug> para retomar de um PRD existente (ex: apos escalacao do safety valve do /dw-bugfix), pulando Etapas 1-4 e comecando no GATE 1.' },
     { name: 'dw-brainstorm', description: 'Refina uma ideia contra features existentes do produto. Modos: ideacao default, --research (research multi-fonte citada), --refactor (catalogo de code smells Fowler), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
@@ -35,10 +37,12 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lista comandos primarios e fluxos que os conectam. Passe --advanced para ver comandos internos/escondidos.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
+    { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
     { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },
-    { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai). --fix entra no loop iterativo QA + fix-retest.' },
+    { 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-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only.' },
+    { 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 usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug>.' },
     { 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.' },
     { name: 'dw-secure-audit', description: 'Audit unificado de seguranca: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise. Hidden; auto-invocado por /dw-review e /dw-generate-pr.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },

package/lib/init.js

@@ -132,6 +132,34 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     ensureDir(path.join(projectRoot, '.dw', 'spec'));
   }
 
+  // 5.1. Seed .dw/STATE.md from template (init only; never overwritten on update)
+  if (!isUpdate) {
+    console.log('  Session state:');
+    const stateTemplatePath = path.join(langDir, 'templates', 'state-template.md');
+    const stateDestPath = path.join(projectRoot, '.dw', 'STATE.md');
+    if (require('fs').existsSync(stateTemplatePath)) {
+      const stateStatus = writeFile(
+        stateDestPath,
+        require('fs').readFileSync(stateTemplatePath, 'utf-8'),
+        false
+      );
+      log(stateStatus, stateDestPath);
+      if (stateStatus === 'created') totalCreated++;
+      else totalSkipped++;
+    }
+    console.log();
+  }
+
+  // 5.2. Create .dw/bugfixes/ with .gitkeep (init only; preserved on update)
+  if (!isUpdate) {
+    const bugfixesDir = path.join(projectRoot, '.dw', 'bugfixes');
+    ensureDir(bugfixesDir);
+    const gitkeepPath = path.join(bugfixesDir, '.gitkeep');
+    const gitkeepStatus = writeFile(gitkeepPath, '', false);
+    if (gitkeepStatus === 'created') totalCreated++;
+    else totalSkipped++;
+  }
+
   // 5.5. Copy bundled skills to .agents/skills/
   const skillsSrcDir = path.join(SCAFFOLD_DIR, 'skills');
   if (require('fs').existsSync(skillsSrcDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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

@@ -5,11 +5,27 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 
 **The whole point of this file:** when the user states an intent that matches the Trigger Map below, run the matching `dw-*` command **without asking permission first** — unless the change is genuinely trivial (see Escape Hatches).
 
+## Auto-Sizing Matrix
+
+Before picking a command from the Trigger Map, gauge the change's actual scope. The same intent ("fix this", "add this") can mean very different amounts of work; the matrix names four sizes and routes each to a different entry point. **Pick the smallest one that fits — under-routing wastes ceremony, over-routing hides scope.**
+
+| Size | What it looks like | Route to |
+|------|---------------------|----------|
+| **Small** | ≤3 files, no migration, no new endpoint, can be summarized in one sentence. Examples: typo, log message, single-line config, dependency bump, version pin. | Just do it inline. No `dw-*` command. |
+| **Medium** | Clear feature or bug, <10 numbered tasks expected, single component or single service, no architectural decisions. Examples: add a form field with validation, fix a regression in a known module, wire a new API endpoint into an existing handler. | `/dw-bugfix` (for bugs) or `/dw-plan` (for features) — straight, not via `/dw-autopilot`. |
+| **Large** | Multi-component feature, ≥10 tasks expected, touches multiple modules, has user-visible UX surface AND backend. Examples: add a new entity end-to-end (model + migration + API + UI), introduce a third-party integration, redesign a flow. | `/dw-autopilot "<wish>"` — full PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR pipeline with three gates. |
+| **Complex** | New domain, ambiguous requirements, architectural decision required, regulatory or compliance surface, or scope that spans multiple PRDs. Examples: introduce event sourcing, rebuild auth, multi-tenancy, a new product line. | `/dw-brainstorm "<idea>"` first (auto-dispatches research/council modes), then `/dw-plan --council` so the techspec stage runs the multi-advisor debate. |
+
+**Safety valve:** if you start in Small or Medium but the work reveals it's actually Large (the inline listing exceeds 5 steps, or `/dw-bugfix` triggers its `Step 5.0` valve), STOP and escalate. There is no flag to bypass. Escalation is the correct outcome.
+
+**Adapted from** [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0). The four-size matrix is theirs; the mapping to `dw-*` commands is dev-workflow-specific.
+
 ## Trigger Map
 
 | User intent (literal or paraphrased) | Auto-trigger |
 |--------------------------------------|--------------|
 | "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
+| "Autopilot this PRD" / "Take this PRD to PR" / continue a bugfix escalation autonomously | `/dw-autopilot --from-prd <slug>` (existing PRD at `.dw/spec/<slug>/`) |
 | Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
 | "Plan this feature" / "Write a PRD + techspec + tasks" | `/dw-plan "X"` |
 | "Write a PRD for X" / "Spec out Y" | `/dw-plan prd "X"` |
@@ -18,9 +34,14 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 | "Run this task" (with task ID) | `/dw-run <ID>` |
 | "Run all pending tasks" / "Execute the plan" | `/dw-run` |
 | "Continue where I left off" | `/dw-run --resume` |
+| "Pause work" / "End the session" / "Save where we are" | `/dw-pause` |
+| "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` |
 | "Evaluate the AI feature" / "Test the RAG / classifier" | `/dw-qa --ai` |
+| "Walk me through this feature" / "UAT this with me" / "Let's do a manual run-through" | `/dw-qa --uat` |
+| "Review this bugfix" / "Code-review fix `<slug>`" | `/dw-review --bugfix <slug>` |
+| "QA this bugfix" / "Validate fix `<slug>`" | `/dw-qa --bugfix <slug>` |
 | "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-review` |
 | "Just the PRD coverage check" | `/dw-review --coverage-only` |
 | "Just the code quality review" | `/dw-review --code-only` |

package/scaffold/en/commands/dw-analyze-project.md

@@ -766,6 +766,67 @@ Three options:
 - Never write `.dw/constitution.md` without explicit user approval (option A) or explicit choice (options B/C).
 - Constitution file is committed to the repository like any other project artifact — never gitignored.
 
+### Step 9: Concerns Map Generation (Risk Map)
+
+After the constitution step, generate `.dw/rules/concerns.md` — the project's **risk map**. While `.dw/rules/` describes how the code IS and `.dw/constitution.md` describes what it SHOULD BE, the concerns map answers a third question: **where is it dangerous to mess around?**
+
+**Difference from the other two:**
+- `.dw/rules/*.md` — analytical (observed patterns).
+- `.dw/constitution.md` — declarative (committed principles).
+- `.dw/rules/concerns.md` — operational risk (load-bearing fragility, hot spots, hostile code).
+
+**Behavior:**
+
+If `.dw/rules/concerns.md` already exists with hand-edited entries between `<!-- preserved:start -->` and `<!-- preserved:end -->` markers, preserve those entries. Refresh the auto-generated sections (Hot Spots churn data, Known Bug History from `.dw/bugfixes/`).
+
+Otherwise (first run), build the file from scratch using `.dw/templates/concerns-template.md` as the base.
+
+**Data to collect:**
+
+1. **Hot Spots — churn analysis.** For each module discovered in Step 5, compute the count of commits touching files in that module over the last 90 days (`git log --since="90 days ago" --name-only -- <module-path> | wc -l`). Modules in the top 20% by churn are candidates. Cross-reference with `.dw/bugfixes/` (next item) — modules that also appear there are confirmed Hot Spots; the rest are flagged "high churn — verify with team."
+
+2. **Known Bug History — bugfix aggregation.** If `.dw/bugfixes/` exists, scan every `SUMMARY.md` in it. For each, parse the `Files Touched` table; aggregate file paths by their top-level module (e.g. `src/auth/session.ts` -> `src/auth/`). Any module with `>= 2` historical fixes lands in the Known Bug History section with the count and the recent bugfix slugs.
+
+3. **Fragile Integrations.** Look for telltale patterns in code and config:
+   - External SDK clients with retry/backoff scaffolding (suggests prior failures).
+   - Comments like `// FIXME: vendor returns 200 with empty body sometimes`, `// HACK: legacy API workaround`, `// TODO: handle vendor X edge case`.
+   - Hand-rolled retry loops around fetch/axios/HTTP clients.
+   - `.dw/incidents/` directory — every incident postmortem that names an external system goes in here.
+   List these candidates. Don't fabricate — only what you observe.
+
+4. **Hostile Code.** Heuristics for code that needs full understanding before modification:
+   - Regex literals longer than 80 characters with no explanatory comment.
+   - Functions over 100 lines with cyclomatic complexity that resists quick reading (rough heuristic: lots of nested `if`/`switch`/loops).
+   - Manual transaction/locking code outside an ORM's idiomatic layer.
+   - Custom serializers/parsers (e.g. hand-written JSON, CSV, binary formats) without a corresponding test file.
+   Flag candidates and let the user confirm.
+
+5. **Tech Debt — Acknowledged.** Scan README, CONTRIBUTING, docs/, and code comments for `TODO`, `FIXME`, `XXX`, `HACK`, `DEPRECATED` markers older than 90 days (use `git blame` to date them). Cluster by area. Present as candidates; the user decides which deserve acknowledgement (some are stale comments, some are real debt).
+
+**Procedure:**
+
+1. **Show candidates in chat first** (do NOT write the file yet). Format as a markdown table per section with a count and the strongest evidence for each entry. Cap each section at 10 entries — if more, list "+N more (see full analysis)" and let the user request expansion.
+
+2. Ask: "Approve as-is, drop specific entries (give the row labels), or skip this step entirely?" Wait for explicit response.
+
+3. On approval, write `.dw/rules/concerns.md` using `.dw/templates/concerns-template.md`. Fill in:
+   - Frontmatter `last_refreshed: <today's ISO date>`.
+   - Hot Spots table.
+   - Fragile Integrations table.
+   - Hostile Code table.
+   - Known Bug History table.
+   - Tech Debt — Acknowledged table.
+
+4. If a `<!-- preserved:start --> ... <!-- preserved:end -->` block existed in a prior version, append it back at the end of the file (the team's hand-curated entries).
+
+5. Print: "Wrote `.dw/rules/concerns.md`. Loaded on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix` when their target touches a listed area. Never blocks — it informs, surfaces, and suggests an ADR for deviations."
+
+**Special case — no signals found:**
+
+If after the heuristics nothing crosses the bar (small codebase, low churn, no incidents, no bugfix history), write a minimal `concerns.md` with all sections empty (just headers) and a note: "No risk signals at this time. Re-run after the project accumulates more history."
+
+**Refresh cadence:** users re-run `/dw-analyze-project` whenever rules drift. Step 9 refreshes auto sections while keeping preserved entries. There is no separate refresh-only command.
+
 ## Quality Checklist
 
 Before declaring the analysis complete, verify:
@@ -787,6 +848,9 @@ Before declaring the analysis complete, verify:
 - [ ] Generated one `.dw/rules/{project}.md` per leaf project discovered
 - [ ] Generated `.dw/rules/integrations.md` (if 2+ projects)
 - [ ] All file paths in rules reference real, existing files
+- [ ] Step 8 (constitution) offered and resolved (A/B/C)
+- [ ] Step 9 (concerns map) presented candidates, awaited approval, wrote `.dw/rules/concerns.md` (or noted no signals)
+- [ ] Preserved-marker blocks in concerns.md kept verbatim on refresh
 - [ ] Topology analysis completed (god nodes, coupling metrics, dependency graph)
 - [ ] Critical nodes table generated with Ca, Ce, instability
 - [ ] Circular dependencies identified and documented

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

@@ -44,13 +44,22 @@ A step that invokes a `/dw-xxx` command is ONLY considered complete when the art
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{WISH}}` | Description of what the user wants to build | "push notification system with per-channel preferences" |
+| `{{WISH}}` | Description of what the user wants to build (default mode) | "push notification system with per-channel preferences" |
+| `{{PRD_SLUG}}` | Existing PRD slug to autopilot from (when `--from-prd` is used) | `prd-bugfix-stripe-webhook-retry` |
+| `{{MODE}}` | Optional invocation flag | `--from-prd <slug>` |
+
+## Invocation Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-autopilot "<wish>"` | **Default.** Full pipeline from scratch: Codebase Intelligence → Research → Brainstorm → PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR. |
+| `/dw-autopilot --from-prd <slug>` | **Resume-from-PRD mode.** Skips Steps 1–4 (Intel, Research, Brainstorm, PRD). Starts at GATE 1 (presents the existing PRD for approval), then continues through TechSpec → Tasks → Run → QA → Review → Commit → PR. Used when `/dw-bugfix` has escalated via its safety valve and written a PRD to `.dw/spec/<slug>/`, or when the user previously authored a PRD by hand and wants the rest automated. |
 
 ## Approval Gates
 
 The autopilot stops ONLY at these 3 moments:
 
-1. **GATE 1 — PRD**: Presents the generated PRD and awaits user approval before generating techspec/tasks
+1. **GATE 1 — PRD**: Presents the generated PRD (default mode) or the existing PRD (--from-prd mode) and awaits user approval before generating techspec/tasks
 2. **GATE 2 — Tasks**: Presents the task list and awaits approval before starting execution
 3. **GATE 3 — PR**: After automatic commit, asks if the user wants to generate the Pull Request
 
@@ -66,6 +75,22 @@ If this command is re-invoked on the same PRD after interruption:
 
 ## Full Pipeline
 
+### Step 0: Resolve invocation mode (MANDATORY first action)
+
+Before Step 1, decide which mode is in effect:
+
+1. **If `--from-prd <slug>` is present in the invocation:**
+   - Resolve `{{PRD_SLUG}}` to `.dw/spec/<slug>/`.
+   - Verify the directory exists and contains a `prd.md`. If either is missing, STOP and report: `--from-prd target .dw/spec/<slug>/prd.md not found. Run /dw-plan prd or fix the slug.`
+   - Check whether `.dw/bugfixes/*/escalated.md` references this slug. If yes, note in the progress block: `Resuming from bugfix escalation: <NNN-bugfix-slug> → <slug>`.
+   - Set `mode: "from-prd"` in `autopilot-state.json` and `skipped_steps: [1, 2, 3, 4]` with `skip_reason: "from-prd-mode"`.
+   - Jump directly to **GATE 1** (PRD approval) using the existing `prd.md`.
+
+2. **Otherwise (default mode):**
+   - Set `mode: "autopilot"` and proceed to Step 1 normally.
+
+<critical>In `--from-prd` mode, Steps 1–4 MUST be marked as `skipped_steps` with `skip_reason: "from-prd-mode"`. The pre-commit audit (Step 14) MUST honor this — a skipped step is not the same as a missing step.</critical>
+
 ### Step 1: Codebase Intelligence
 
 <critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before starting. Falls back to `.dw/rules/` and direct grep if absent.</critical>
@@ -104,12 +129,15 @@ Run `/dw-plan prd` using brainstorm findings.
 
 ### === GATE 1: PRD Approval ===
 
+**In default mode:** the PRD was just written in Step 4.
+**In `--from-prd` mode:** the PRD already existed on disk before this autopilot run started (typically authored by `/dw-bugfix --analysis` or by a safety-valve escalation, or hand-edited).
+
 Present to the user:
 - Summary of functional requirements
-- Decisions made automatically
+- Decisions made automatically (default mode) OR origin note: "PRD authored by /dw-bugfix escalation on <date>" / "PRD pre-existing on disk" (--from-prd mode)
 - Open questions (if any)
 
-**Wait for explicit approval.** If the user requests changes, adjust and re-present.
+**Wait for explicit approval.** If the user requests changes, adjust and re-present. In `--from-prd` mode, edits go directly into the existing `.dw/spec/<slug>/prd.md` — there is no separate draft.
 
 ### Step 5: TechSpec (Interactive — 7+ Questions)
 
@@ -216,6 +244,34 @@ Run `/dw-review --coverage-only` again to confirm QA fixes did not break PRD com
 Run `/dw-review --code-only` (Level 3) for formal review.
 - Generate persisted report
 
+### Step 13.5: Close the bugfix loop (Conditional)
+
+<critical>This step runs only when `mode == "from-prd"` AND the `prd_path` matches `.dw/spec/prd-bugfix-*`. Otherwise skip with `skip_reason: "not a bugfix escalation"`.</critical>
+
+When the autopilot is finishing a bugfix that was escalated by `/dw-bugfix`, the index entry in `.dw/bugfixes/NNN-<slug>/` still has only `TASK.md` and `escalated.md` — no `SUMMARY.md` was written because the surgical bugfix flow never reached step 5.5 (the spec-driven flow did the work instead). Without `SUMMARY.md`, `/dw-intel --build` skips this bugfix forever, so `bugfix-history` queries never surface the lesson learned.
+
+This step closes that loop **before** Step 14 (Commit) so the SUMMARY lands in the same commit as the fix.
+
+**Procedure:**
+
+1. **Find the index entry.** Glob `.dw/bugfixes/*/escalated.md`. For each, read the one-line content and check whether it references the current PRD slug (e.g., `→ see .dw/spec/prd-bugfix-stripe-webhook-retry/` matches the active PRD `prd-bugfix-stripe-webhook-retry`). The match is the target `NNN-<slug>/` directory.
+2. **If no match is found:** the bugfix index doesn't expect a back-write. Skip silently and continue to Step 14.
+3. **If `SUMMARY.md` already exists in the matched directory:** do not overwrite. Continue to Step 14 — the human or a previous run already closed the loop.
+4. **Otherwise, write `SUMMARY.md`** using `.dw/templates/bugfix-summary-template.md`. Source fields from:
+   - **Symptom (verbatim):** the `Symptom` section of `<prd_path>/prd.md`, or the first paragraph of the original `TASK.md` if the PRD doesn't carry it.
+   - **Root Cause:** the original `TASK.md` Root Cause section.
+   - **Resolution (2–4 bullets):** distilled from `<prd_path>/techspec.md` decisions + actual `git diff <base>...HEAD --stat` summary.
+   - **Files Touched:** parsed from `git diff <base>...HEAD --name-only` (exclude `.dw/` paths). If >5 files, that's expected for an escalated bugfix — list them all and add a note "escalated from bugfix because of scope".
+   - **Verification:** point to `<prd_path>/QA/qa-report.md` and the verify report referenced in Step 9's session output.
+   - **Related — Concerns touched:** copy from the corresponding entries in `.dw/rules/concerns.md` if any rows reference modules in `Files Touched`.
+   - **Frontmatter:** `slug: NNN-<slug>`, `created: <today's ISO date>`, `status: Fixed`, `severity: <inferred from PRD priority or default Medium>`, `related_concerns: [list from above]`.
+5. **Append a final-line note** to `escalated.md`: `Closed by /dw-autopilot --from-prd on <YYYY-MM-DD>; SUMMARY.md written.` Preserve the original escalation line above it.
+6. **Record the artifact** in `autopilot-state.json` `step_artifacts["13.5"] = [".dw/bugfixes/NNN-<slug>/SUMMARY.md", ".dw/bugfixes/NNN-<slug>/escalated.md"]`.
+
+<critical>NEVER fabricate verification evidence. If the QA report is empty or the diff is empty, do not invent files in `Files Touched`. Write the SUMMARY.md sections that are grounded and mark the rest as `_(not available — see <prd_path>/QA/ for details)_`.</critical>
+
+After this step, the bugfix becomes visible to `/dw-intel "bugfix history in <module>"` on the next `/dw-intel --build` run.
+
 ### Step 14: Commit
 
 <critical>MANDATORY PRE-COMMIT AUDIT — execute BEFORE invoking `/dw-commit`:
@@ -230,7 +286,7 @@ Run `ls` on each path below and confirm existence. If ANY is missing, DO NOT com
 - Evidence of the last `/dw-review --coverage-only` run with RF-by-RF matrix (session output or reference in `autopilot-state.json`)
 
 Also verify `autopilot-state.json`:
-- Every step 1 through 13 that is NOT in `skipped_steps` must be in `completed_steps`
+- Every step 1 through 13 (and 13.5 when in `--from-prd` mode against a `prd-bugfix-*` PRD) that is NOT in `skipped_steps` must be in `completed_steps`
 - Each completed step must have its artifacts listed in `step_artifacts`
 
 If any artifact or step is missing: STOP immediately. Report to the user: `Step N did not produce artifact X — re-running /dw-[command]`. Re-execute the command. Verify again. Only then proceed to `/dw-commit`.
@@ -263,9 +319,11 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
   "mode": "autopilot",
   "wish": "original user description",
   "prd_path": ".dw/spec/prd-[name]",
+  "from_prd_slug": null,
   "current_step": 8,
   "completed_steps": [1, 2, 3, 4, 5, 6, 7],
   "skipped_steps": [2],
+  "skip_reasons": {"2": "domain already mapped in .dw/rules/auth.md"},
   "gates_passed": ["prd", "tasks"],
   "step_artifacts": {
     "9": ["review-matrix-shown-in-session"],
@@ -288,6 +346,7 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
 - A step ONLY moves to `completed_steps` after verifying its artifacts exist on disk
 - If the session drops, re-invoke `/dw-autopilot` on the same PRD; the command reads `autopilot-state.json` and continues from the correct step, revalidating artifacts before trusting `completed_steps`
 - When the pipeline finishes (after commit or PR), remove the file or mark `"status": "completed"`
+- In `--from-prd` mode, set `from_prd_slug: "<slug>"`, `mode: "from-prd"`, and include steps 1–4 in `skipped_steps` with `skip_reason: "from-prd-mode"` — this is what the pre-commit audit checks against (Step 14 verifies that every step NOT in `skipped_steps` is in `completed_steps`)
 
 <critical>After EACH completed step, display the updated progress block to the user. This is MANDATORY — the user MUST see what was done and what comes next. If a step was skipped, the reason MUST appear in the progress block.</critical>