@brunosps00/dev-workflow 1.0.5 → 1.1.0

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

@@ -1,374 +1,257 @@
 <system_instructions>
-You are a full pipeline orchestrator. This command receives a user's wish and automatically executes the entire development flow, from research to commit, stopping only at critical gates.
-
-<critical>This command MUST execute ALL applicable pipeline steps. Do NOT skip any step. If a step is conditional, evaluate the condition and execute if applicable.</critical>
-<critical>The ONLY pause moments are the 3 gates defined below. Between gates, execute everything automatically without asking for confirmation.</critical>
-<critical>Each step MUST follow the complete instructions from the corresponding command in `.dw/commands/`. Read and execute the full command, not a summarized version.</critical>
-
-<critical>FORMAL EXECUTION IS MANDATORY — READ BEFORE STARTING:
-A step that invokes a `/dw-xxx` command is ONLY considered complete when the artifacts produced by that command exist on disk. Manual validations (running tests, opening Playwright ad-hoc, eyeballing the code, writing a short qa-report by hand) DO NOT replace formal execution of the command.
-- BEFORE each step: announce to the user `→ Invoking /dw-[name] — executing full instructions`.
-- DURING: follow the instructions in `.dw/commands/[name].md` in full, without summarizing or substituting.
-- AFTER: run `ls` on the artifact paths listed in that step and confirm they exist before updating `autopilot-state.json`. If any artifact is missing, the step did NOT run — re-execute the command formally.</critical>
-
-<critical>FORBIDDEN RATIONALIZATIONS — if you think any of these, STOP and execute the command formally:
-| Thought | Reality |
-|---------|---------|
-| "I already ran the tests manually" | The command produces structured artifacts. Run the command. |
-| "I validated via ad-hoc Playwright" | `/dw-qa` requires RF matrix, bugs.md, screenshots, scripts, logs, checklist. Run the command. |
-| "The implementation is obviously correct" | `/dw-review --coverage-only` requires a compliance matrix per RF/endpoint/task. Run the command. |
-| "A strong manual validation is enough" | NO. Technical equivalence DOES NOT replace formal execution. |
-| "I already checked build and lint, that's enough" | Build/lint DO NOT replace review nor QA. Run the commands. |
-| "I wrote a summarized qa-report.md by hand" | A loose file IS NOT execution of `/dw-qa`. The full `QA/` tree is mandatory. |
-| "The autopilot already advanced, I don't need to go back" | If the artifact doesn't exist, the step didn't run. Go back and execute. |
-| "I fixed bugs along the way, so QA is already ok" | Fixing bugs does not replace running formal QA. Run `/dw-qa`. |</critical>
+You are the full pipeline orchestrator. This command receives a user's wish and drives the PRD-to-PR workflow in two invocations:
+
+1. **Planning invocation:** research/brainstorm when needed, PRD, TechSpec, Tasks, then STOP.
+2. **Execution invocation:** resume from `autopilot-state.json`, run `/dw-goal --from-autopilot <prd-slug>`, then commit and PR gate.
+
+<critical>The first invocation MUST stop after the planning artifacts are complete. Do not run implementation, QA, review, commit, or PR in the first invocation.</critical>
+<critical>The second invocation MUST resume from the saved state and delegate Run → Review → QA/Fix → Review to `/dw-goal --from-autopilot <prd-slug>`.</critical>
+<critical>Each step that invokes a `/dw-*` command MUST follow the complete instructions from `.dw/commands/`. Read and execute the full command, not a summarized version.</critical>
 
 ## When to Use
-- Use when you want to go from an idea to a PR with minimal manual intervention
-- Use for complete features that go through the entire pipeline (research, planning, execution, quality)
-- Do NOT use for small, well-scoped one-off tasks — use `/dw-run` directly with a quick PRD instead
-- Do NOT use to fix bugs (use `/dw-bugfix`)
-- Do NOT use when you want manual control between each phase (use individual commands)
+- Use when you want to go from an idea to a PR with minimal manual intervention but a hard planning stop.
+- Use for complete features that require planning, execution, quality gates, and PR readiness.
+- Do NOT use for small, well-scoped one-off tasks; use `/dw-run` with an existing plan.
+- Do NOT use for surgical bug fixes; use `/dw-bugfix`.
+- Do NOT use when the user wants manual control between every phase; use individual commands.
 
 ## Pipeline Position
-**Predecessor:** (user's wish) | **Successor:** (PR merge)
+**Predecessor:** user wish | **Successor:** `/dw-goal`, `/dw-commit`, `/dw-generate-pr`
 
-## Complementary Skills
+## Complementary Skills / Commands
 
-| Skill | Trigger |
-|-------|---------|
-| `dw-memory` | **ALWAYS** — the memory thread runs through every phase (brainstorm -> PRD -> techspec -> tasks -> execution -> QA -> review -> PR). Decisions at one gate feed context into the next. |
-| `dw-verify` | **ALWAYS** — invoked at each gate (PRD, Tasks, PR) before asking user approval; and before the final commit + push. |
+| Skill or command | Trigger |
+|------------------|---------|
+| `dw-memory` | ALWAYS — preserve decisions across planning, goal execution, QA, review, and PR. |
+| `dw-verify` | ALWAYS — invoked by gates and downstream commands before approval/commit/PR claims. |
+| `/dw-goal` | ALWAYS on the second invocation — durable execution-quality objective. |
 
 ## Input Variables
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{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>` |
+| `{{WISH}}` | Description of what the user wants to build in default mode. | `"push notification preferences"` |
+| `{{PRD_SLUG}}` | Existing PRD slug 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. |
+| `/dw-autopilot "<wish>"` | Planning invocation from scratch. Runs Codebase Intelligence → optional Research → Brainstorm → PRD → TechSpec → Tasks, writes state, then stops. |
+| `/dw-autopilot --from-prd <slug>` | Planning invocation from an existing PRD. Starts at PRD approval, then TechSpec → Tasks, writes state, then stops. |
+| `/dw-autopilot` on a PRD with `autopilot-state.json status=plan_complete` | Execution invocation. Runs `/dw-goal --from-autopilot <slug>`, then commit and PR gate. |
 
-## Approval Gates
+## Required Pause Points
 
-The autopilot stops ONLY at these 3 moments:
+Autopilot pauses at:
 
-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
+1. **PRD approval** before TechSpec.
+2. **Tasks approval** before marking planning complete.
+3. **Mandatory planning stop** after Tasks are approved and state is saved.
+4. **PR gate** after the execution goal and commit complete.
 
-## Session Resumption
+Between these points, execute automatically while still respecting blocking questions required by the underlying command.
 
-If this command is re-invoked on the same PRD after interruption:
-
-<critical>Read the `autopilot-state.json` file in the PRD directory. Skip ALL steps listed in `completed_steps`. Resume execution from `current_step`. Gates already passed (listed in `gates_passed`) MUST NOT be re-presented.</critical>
+## Session Resumption
 
-1. Read `.dw/spec/prd-[name]/autopilot-state.json`
-2. Report: "Resuming autopilot from step [N] ([name]). Steps 1-[N-1] already completed."
-3. Continue execution normally from the indicated step
+If this command is re-invoked on the same PRD:
 
-## Full Pipeline
+<critical>Read `.dw/spec/<prd-slug>/autopilot-state.json` first. If `status` is `plan_complete`, do not repeat planning. Start the execution invocation by formally invoking `/dw-goal --from-autopilot <prd-slug>`.</critical>
 
-### Step 0: Resolve invocation mode (MANDATORY first action)
+State meanings:
 
-Before Step 1, decide which mode is in effect:
+| Status | Action |
+|--------|--------|
+| missing state | Start normal planning invocation. |
+| `planning` | Resume from `current_step`, respecting completed/skipped steps. |
+| `plan_complete` | Start execution invocation via `/dw-goal --from-autopilot <prd-slug>`. |
+| `goal_active` | Continue `/dw-goal resume` or `/dw-goal --from-autopilot <prd-slug>` according to `.dw/goals/autopilot-<prd-slug>/status.json`. |
+| `goal_complete` | Continue to commit and PR gate. |
+| `completed` | Report already completed and show PR/commit summary if available. |
 
-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`.
+## Planning Invocation
 
-2. **Otherwise (default mode):**
-   - Set `mode: "autopilot"` and proceed to Step 1 normally.
+### Step 0: Resolve Invocation Mode
 
-<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>
+1. If `--from-prd <slug>` is present:
+   - Resolve to `.dw/spec/<slug>/`.
+   - Verify `prd.md` exists; otherwise STOP with: `--from-prd target .dw/spec/<slug>/prd.md not found. Run /dw-plan prd or fix the slug.`
+   - Create or update `autopilot-state.json` with `mode: "from-prd"`, `status: "planning"`, `skipped_steps: [1,2,3,4]`, and `skip_reasons["1-4"] = "from-prd-mode"`.
+   - Jump to PRD approval using the existing PRD.
+2. Otherwise:
+   - Create or update `autopilot-state.json` with `mode: "autopilot"`, `status: "planning"`, original wish, and `current_step: 1`.
 
 ### 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>
+<critical>If `.dw/intel/` exists, query it via `/dw-intel` before planning. Fall back to `.dw/rules/` and direct grep if absent.</critical>
 
-- Query `.dw/intel/` via `/dw-intel` to understand project context
-- Identify: tech stack, existing patterns, related features
-- If `.dw/intel/` is absent, suggest running `/dw-intel --build` first for richer downstream context
+- Identify tech stack, existing patterns, related features, and project constraints.
+- If `.dw/intel/` is absent, suggest `/dw-intel --build` for richer future context, but continue with `.dw/rules/` and direct inspection.
 
 ### Step 2: Research (Conditional)
 
-Evaluate whether the topic requires deep research:
-- **YES** (run `/dw-brainstorm --research`): new technology for the project, unknown domain, external API integrations, critical architectural decisions
-- **NO** (skip to step 3): simple feature in an already mapped domain, refactoring existing code, basic CRUD
-  - If skipping, DOCUMENT the reason in the progress block. E.g.: "Research skipped — domain already mapped in .dw/rules/[file].md". The user must see the justification.
-
-If executed, use `standard` mode by default. Incorporate findings into subsequent steps.
+Run `/dw-brainstorm --research` when the feature involves new technology, unknown domain, external APIs, regulation, or high-impact architecture. Otherwise skip and record the reason in `skip_reasons`.
 
 ### Step 3: Brainstorm (Interactive)
 
-Run `/dw-brainstorm` with accumulated context (intel + research).
-- Generate 3 directions
-- Present the 3 directions to the user with your recommendation highlighted and justified
-- Wait for user confirmation on which direction to follow before proceeding
-
-### Step 4: PRD (Interactive — 7+ Questions)
-
-<critical>The PRD MUST include an interactive interview with the user. Ask AT LEAST 7 clarification questions BEFORE writing the PRD. Do NOT answer questions automatically based on context — the user MUST respond.</critical>
-
-Run `/dw-plan prd` using brainstorm findings.
-- Follow ALL command instructions, especially the clarification questions section
-- Ask at least 7 questions about: problem, target users, critical features, scope, constraints, design, integration
-- In each question, present a recommendation grounded in brainstorm and deep-research findings (if executed). E.g.: "Based on the research, I recommend X because [evidence]. Do you agree or prefer a different direction?"
-- Wait for user responses to each question
-- This step is BLOCKING — the command STOPS until a response is received from the user for EACH question. If the user does not respond, do NOT proceed. Do NOT assume answers based on context.
-- Only after receiving all responses, write the complete PRD in `.dw/spec/prd-[name]/prd.md`
-
-### === GATE 1: PRD Approval ===
+Run `/dw-brainstorm` with accumulated context. Present three directions and wait for the user to choose one before continuing.
 
-**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).
+### Step 4: PRD
 
-Present to the user:
-- Summary of functional requirements
-- 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)
+Run `/dw-plan prd` using brainstorm/research findings.
 
-**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.
+<critical>The PRD stage must use the structured interview tool when available. If unavailable, ask the required questions in chat and record the fallback. The user must answer; do not infer answers.</critical>
 
-### Step 5: TechSpec (Interactive — 7+ Questions)
+After `prd.md` exists, present PRD summary and wait for explicit approval. If the user requests edits, update and re-present.
 
-<critical>The TechSpec MUST include an interactive interview with the user. Ask AT LEAST 7 technical clarification questions BEFORE writing the TechSpec. Do NOT answer questions automatically — the user MUST respond.</critical>
+### Step 5: TechSpec
 
 Run `/dw-plan techspec` from the approved PRD.
-- Follow ALL command instructions, especially the clarification questions section
-- Ask at least 7 questions about: preferred architecture, existing vs new libs, testing strategy, integration with existing systems, infrastructure constraints, performance, security
-- In each question, present a technical recommendation grounded in brainstorm, deep-research, and approved PRD findings. E.g.: "Research indicated lib X has better performance for this case [source]. Want to use X or have another preference?"
-- Wait for user responses to each question
-- This step is BLOCKING — the command STOPS until a response is received from the user for EACH question. If the user does not respond, do NOT proceed. Do NOT assume answers based on context.
-- Only after receiving all responses, generate in `.dw/spec/prd-[name]/techspec.md`
-
-### Step 6: Tasks
-
-Run `/dw-plan tasks` from PRD + TechSpec.
-- Follow all command instructions
-- Generate individual tasks in `.dw/spec/prd-[name]/`
-
-### === GATE 2: Tasks Approval ===
-
-Present to the user:
-- Task list with brief descriptions
-- Dependencies between tasks
-- Total effort estimate
-
-**Wait for explicit approval.** If the user requests changes, adjust and re-present.
-
-### Step 7: Design Contract (Conditional)
-
-Evaluate whether tasks involve frontend:
-- **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `dw-ui-discipline` skill is available
-  - Generate the design contract in `.dw/spec/prd-[name]/design-contract.md`
-  - Present a summary of the design contract to the user (palette, typography, mobile/desktop layout) as a visual checkpoint before proceeding
-- **NO** (skip to step 8): purely backend/infra tasks
-
-### Step 8: Execution
-
-Run `/dw-run` with the PRD path.
-- Follow ALL command instructions, including the native plan-checker gate (PASS required) and wave-based parallel execution via the bundled `dw-execute-phase` skill agents
-- Each task follows `/dw-run` with Level 1 validation
 
-### Step 9: Implementation Review (Loop)
+<critical>The TechSpec stage must use the structured interview tool when available. If unavailable, ask the required questions in chat and record the fallback. The user must answer; do not infer answers.</critical>
 
-<critical>BEFORE the PRD compliance review, run the project's build and lint. If they fail, fix and re-run until they pass. The implementation review CANNOT start with broken build or lint.</critical>
+After `techspec.md` exists, present TechSpec summary and wait for explicit approval.
 
-Run the project's build and lint:
-1. Identify build and lint commands in `package.json` (scripts `build`, `lint`, `lint:fix`, `type-check`, etc.)
-2. Run lint with `--fix` enabled (e.g., `npm run lint -- --fix` or `npx eslint . --fix`) to auto-correct what's possible
-3. Run build (e.g., `npm run build` or `npx tsc --noEmit`)
-4. If any fail after `--fix`: analyze errors, fix manually, and re-run
-5. Repeat until both build AND lint pass without errors
-6. Only then proceed to the review
-
-Run `/dw-review --coverage-only` to verify PRD compliance (Level 2).
-- If gaps found: fix automatically and re-run the review
-- Maximum 3 correction cycles
-- Do NOT advance to QA until the review passes
-
-<critical>Required artifacts for this step (verify BEFORE marking complete):
-- Formatted output with compliance matrix shown to the user in the session
-- Explicit verdict (PASS / GAP / FAIL) for EACH RF in the PRD, EACH endpoint in the TechSpec, and EACH task
-- If gaps: correction commits before re-running the review
-A short text review, a "looks good", or a conclusion "implementation is correct" WITHOUT the structured RF-by-RF matrix DOES NOT count. A mental or eyeball review DOES NOT count. If the matrix didn't appear in the output, the command didn't run — re-execute.</critical>
-
-### Step 10: Visual QA
-
-Run `/dw-qa` with Playwright MCP.
-- Test happy paths, edge cases, negative flows, accessibility
-- Document bugs with screenshots
-
-<critical>Required artifacts for this step (run `ls` on EACH path BEFORE marking complete):
-- `{{PRD_PATH}}/QA/qa-report.md` — exists and contains a per-RF section with PASS/FAIL
-- `{{PRD_PATH}}/QA/bugs.md` — exists (may be empty if no bugs, but the file must exist)
-- `{{PRD_PATH}}/QA/checklist.md` — exists and fully covered
-- `{{PRD_PATH}}/QA/screenshots/` — directory exists and contains at least 1 PNG per RF tested (format `RF-XX-[slug]-PASS.png` or `-FAIL.png`)
-- `{{PRD_PATH}}/QA/scripts/` — directory exists and contains Playwright `.spec.ts`/`.spec.js` scripts per RF
-- `{{PRD_PATH}}/QA/logs/` — directory exists with captured console/network logs
-Running Playwright ad-hoc, taking a few loose screenshots, or writing a short qa-report.md by hand DOES NOT replace this structure. If any artifact is missing or incomplete, the command did NOT run — invoke `/dw-qa` formally and follow its flow to completion.</critical>
-
-### Step 11: Fix QA (Conditional)
-
-If QA found bugs:
-- Run `/dw-qa --fix` to fix and retest
-- Loop until stable (maximum 5 cycles). After 5 cycles, STOP and ask the user how to proceed.
-
-### Step 12: Implementation Review (Post-QA)
+### Step 6: Tasks
 
-<critical>BEFORE the post-QA review, run build and lint again with --fix. QA fixes may have introduced new issues.</critical>
+Run `/dw-plan tasks` from PRD + TechSpec. Verify:
+- `tasks.md` exists.
+- per-task files exist.
+- `tasks-validation.md` exists and passes or has an explicit user override.
 
-Run the project's build and lint (same sequence as Step 9):
-1. Lint with `--fix` enabled
-2. Build
-3. If any fail: fix and re-run until they pass
+### Step 7: Tasks Approval and Mandatory Stop
 
-Run `/dw-review --coverage-only` again to confirm QA fixes did not break PRD compliance.
-- If gaps found: fix and re-run
-- Maximum 3 cycles
+Present task summary, dependencies, and total effort. Wait for explicit approval.
 
-<critical>Required artifacts (same rules as Step 9): explicit RF-by-RF matrix in the output. No matrix = command didn't run = re-execute.</critical>
+After approval:
 
-### Step 13: Code Review
+1. Save `.dw/spec/<prd-slug>/autopilot-state.json` with:
 
-Run `/dw-review --code-only` (Level 3) for formal review.
-- Generate persisted report
+```json
+{
+  "status": "plan_complete",
+  "current_step": "goal",
+  "next_command": "/dw-goal --from-autopilot <prd-slug>"
+}
+```
 
-### Step 13.5: Close the bugfix loop (Conditional)
+2. Include `completed_steps` for all completed planning steps and `step_artifacts` for `prd.md`, `techspec.md`, `tasks.md`, per-task files, and `tasks-validation.md`.
+3. STOP and tell the user the planning phase is complete. Do not run implementation in this invocation.
 
-<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>
+## Execution Invocation
 
-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.
+### Step 8: Durable Execution Goal
 
-This step closes that loop **before** Step 14 (Commit) so the SUMMARY lands in the same commit as the fix.
+When `autopilot-state.json status=plan_complete`, formally invoke:
 
-**Procedure:**
+```text
+/dw-goal --from-autopilot <prd-slug>
+```
 
-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"]`.
+The goal owns this sequence:
 
-<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>
+1. `/dw-run <prd-path>`
+2. `/dw-review <prd-path>` (full review: coverage, quality, conventions, constitution, verify)
+3. `/dw-qa <prd-path>`
+4. `/dw-qa --fix <prd-path>` if QA found Open bugs
+5. `/dw-review <prd-path>` again after QA/fixes
+6. **Security Gate** — the post-QA `/dw-review` (step 5) triggers `/dw-secure-audit`, producing a fresh `.dw/secure-audit/audit-summary.md`. This step **ensures** that verdict is APPROVED: if it is missing/stale/REJECTED, run `/dw-secure-audit <prd-path>` standalone, then loop back to `/dw-bugfix` per finding and re-check. SECRET findings always block (no ADR escape). Do not force a second full scan when a fresh APPROVED summary already exists.
 
-After this step, the bugfix becomes visible to `/dw-intel "bugfix history in <module>"` on the next `/dw-intel --build` run.
+<critical>Do not substitute `/dw-review --coverage-only` for the goal reviews. The autopilot quality goal requires full `/dw-review` before QA and after QA fixes.</critical>
 
-### Step 14: Commit
+After `/dw-goal` completes, verify `.dw/goals/autopilot-<prd-slug>/status.json` has `status: "complete"`, then set `autopilot-state.json status: "goal_complete"`.
 
-<critical>MANDATORY PRE-COMMIT AUDIT — execute BEFORE invoking `/dw-commit`:
+### Step 9: Bugfix Loop Close (Conditional)
 
-Run `ls` on each path below and confirm existence. If ANY is missing, DO NOT commit:
-- `{{PRD_PATH}}/QA/qa-report.md`
-- `{{PRD_PATH}}/QA/bugs.md`
-- `{{PRD_PATH}}/QA/checklist.md`
-- `{{PRD_PATH}}/QA/screenshots/` (non-empty)
-- `{{PRD_PATH}}/QA/scripts/` (non-empty with `.spec.*` files)
-- `{{PRD_PATH}}/QA/logs/`
-- Evidence of the last `/dw-review --coverage-only` run with RF-by-RF matrix (session output or reference in `autopilot-state.json`)
+If `mode == "from-prd"` and the PRD slug matches `prd-bugfix-*`, close the bugfix index before commit:
+- Find `.dw/bugfixes/*/escalated.md` that references the PRD slug.
+- If `SUMMARY.md` is missing, write it from available PRD, TechSpec, QA, and diff evidence using `.dw/templates/bugfix-summary-template.md`.
+- Never fabricate verification evidence.
+- Record artifacts in `autopilot-state.json`.
 
-Also verify `autopilot-state.json`:
-- 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`
+### Step 10: Pre-Commit Audit
 
-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`.
+Before `/dw-commit`, verify:
+- `.dw/goals/autopilot-<prd-slug>/status.json` is complete.
+- `<prd-path>/QA/review-consolidated.md` exists from the final post-QA review.
+- `<prd-path>/QA/qa-report.md` and `<prd-path>/QA/bugs.md` exist.
+- **Security Gate passed:** `.dw/secure-audit/audit-summary.md` exists, is fresh (post-last-edit), and status is APPROVED. If missing/stale/REJECTED → STOP (do not commit).
+- `autopilot-state.json` records planning artifacts and the completed goal.
 
-DO NOT make a partial commit. DO NOT justify the absence with manual validation. DO NOT mark a step as complete without the formal artifact.</critical>
+If anything is missing, STOP and re-run the missing formal command. Do not commit partial work.
 
-Run `/dw-commit` automatically.
-- Semantic commits following Conventional Commits
-- Do NOT wait for approval
+### Step 11: Commit
 
-### === GATE 3: Pull Request ===
+Run `/dw-commit` automatically. Do not wait for approval after the goal is complete.
 
-Ask the user: **"Commits completed. Do you want to generate the Pull Request?"**
+### Step 12: Pull Request Gate
 
-- **YES**: run `/dw-generate-pr` with the target branch
-- **NO**: inform that commits are ready and the user can generate the PR manually later
+Ask: **"Commits completed. Do you want to generate the Pull Request?"**
 
-## Native Engine
+- YES: run `/dw-generate-pr`.
+- NO: report that commits are ready and PR can be generated later.
 
-The autopilot relies on dev-workflow-native infrastructure for codebase intelligence (`/dw-intel --build` + `/dw-intel`) and bundled phase execution agents (plan-checker + executor in `.agents/skills/dw-execute-phase/agents/`). All bundled and require no external dependencies. See the `dw-codebase-intel` and `dw-execute-phase` bundled skills under `.agents/skills/` for details.
+Mark `autopilot-state.json status: "completed"` after commit, and include PR link if generated.
 
 ## State Persistence
 
-<critical>The autopilot MUST save its state after each completed step to allow re-invocation on the same PRD after interruption.</critical>
-
-Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following format:
+`autopilot-state.json` must include:
 
 ```json
 {
   "mode": "autopilot",
+  "status": "planning",
   "wish": "original user description",
-  "prd_path": ".dw/spec/prd-[name]",
+  "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"],
-    "10": [
-      ".dw/spec/prd-[name]/QA/qa-report.md",
-      ".dw/spec/prd-[name]/QA/bugs.md",
-      ".dw/spec/prd-[name]/QA/checklist.md",
-      ".dw/spec/prd-[name]/QA/screenshots/",
-      ".dw/spec/prd-[name]/QA/scripts/",
-      ".dw/spec/prd-[name]/QA/logs/"
-    ],
-    "12": ["review-matrix-post-qa-shown-in-session"]
-  },
-  "started_at": "2026-04-10T14:30:00Z",
-  "last_updated": "2026-04-10T15:45:00Z"
+  "current_step": 1,
+  "completed_steps": [],
+  "skipped_steps": [],
+  "skip_reasons": {},
+  "gates_passed": [],
+  "step_artifacts": {},
+  "goal_slug": null,
+  "next_command": null,
+  "started_at": "2026-05-20T00:00:00Z",
+  "last_updated": "2026-05-20T00:00:00Z"
 }
 ```
 
-- Update `current_step`, `completed_steps`, and `step_artifacts` BEFORE moving to the next step
-- 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>
+Update state after each completed or skipped step. A step is complete only after required artifacts exist.
 
 ## Progress Format
 
-During execution, report progress in this format:
+Report progress after each step:
 
+```text
+=== AUTOPILOT =====================================
+  OK [1] Codebase Intelligence
+  OK [2] Research (skipped — known domain)
+  OK [3] Brainstorm
+  OK [4] PRD
+  OK [5] TechSpec
+  OK [6] Tasks
+  STOP [PLAN COMPLETE] Next: /dw-goal --from-autopilot prd-name
+===================================================
 ```
+
+During execution invocation:
+
+```text
 === AUTOPILOT =====================================
-  OK [1/14] Codebase Intelligence
-  OK [2/14] Research (skipped — known domain)
-  OK [3/14] Brainstorm
-  OK [4/14] PRD
-  PAUSE [GATE 1] Awaiting PRD approval...
+  OK [PLAN] Already complete
+  RUN [GOAL] /dw-goal --from-autopilot prd-name
+  NEXT [COMMIT] after goal status=complete
 ===================================================
 ```
 
-## Closing
+## Anti-patterns
 
-At the end, present:
-- PR link (if generated)
-- Summary: steps executed, steps skipped, estimated time saved
-- Suggested next steps (merge, deploy, etc.)
+- Do not continue into implementation during the first invocation.
+- Do not skip `/dw-goal` during the second invocation.
+- Do not replace full `/dw-review` with a narrower review in the execution goal.
+- Do not mark state complete from manual validation alone.
+- Do not re-run planning when `status=plan_complete`; resume the goal.
 
 </system_instructions>

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

@@ -326,7 +326,7 @@
 
     Next — pick one:
       - Manual chain: `/dw-plan techspec prd-bugfix-<slug>` → `/dw-plan tasks prd-bugfix-<slug>` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`.
-      - Hand off to autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — picks up at GATE 1 (PRD approval) and runs the rest automatically with the usual three gates.
+      - Hand off to autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — runs the planning phase from the existing PRD, stops after Tasks, then a later autopilot invocation resumes through `/dw-goal`.
     ```
 
     5. Stop this command. Do not proceed to step 5. The user (or autopilot) invokes `/dw-plan` or `/dw-autopilot --from-prd` next.
@@ -424,7 +424,8 @@
 
     Option B (hand off to autopilot):
     1. Run: `/dw-autopilot --from-prd prd-bugfix-<slug>`
-    2. Autopilot picks up at GATE 1 (PRD approval) and runs TechSpec, Tasks, Run, QA, Review, Commit, PR with the usual three gates.
+    2. Autopilot runs PRD approval, TechSpec, and Tasks, then stops with `status: plan_complete`.
+    3. A later autopilot invocation resumes via `/dw-goal --from-autopilot prd-bugfix-<slug>` for Run, full Review, QA/Fix, and post-QA full Review before commit/PR.
 
     The bugfix index entry stays queryable via `/dw-intel "bugfix history in <module>"`. Downstream `/dw-review --bugfix <slug>` and `/dw-qa --bugfix <slug>` still target `.dw/bugfixes/NNN-<slug>/` when you want a focused review of just the eventual surgical patch.
     ```

package/scaffold/en/commands/dw-functional-doc.md

@@ -114,7 +114,7 @@ Minimum files:
 - `case-matrix.md`
 - `e2e-runbook.md`
 - `manifest.json`
-- `scripts/*.spec.ts`
+- `scripts/*.flow.mjs`
 - `captions/*.srt`
 
 If there is execution:
@@ -291,8 +291,16 @@ If a previous flow in the workspace already has a working shell script (e.g., `r
 ## Utility Scripts
 
 Use the workspace utilities when appropriate:
-- `node .dw/scripts/dw-functional-doc/generate-dossier.mjs --target <URL> [--lang en|pt-br] [--project <name>] [--base-url <url>]`
-- `node .dw/scripts/dw-functional-doc/run-playwright-flow.mjs --flow-dir <path> [--browser-name chromium|firefox] [--video-resolution fullhd|1920x1080]`
+- `node .dw/scripts/functional-doc/generate-dossier.mjs --target <URL> [--lang en|pt-br] [--project <name>] [--base-url <url>]`
+- `node .dw/scripts/functional-doc/run-playwright-flow.mjs --flow-dir <path> [--video-resolution fullhd|1920x1080] [--list-only]`
+
+The runner drives Playwright via the Node API and records video with `page.screencast` (the only
+mechanism that works over CDP). It generates `scripts/<slug>.flow.mjs` — a plain ESM module exporting
+`async function flow({ page, context, expect, baseURL, step, shot })` — not a `@playwright/test` spec,
+so it needs no project `playwright.config.*`. The browser is chosen by `.dw/scripts/lib/resolve-browser.mjs`
+(WSL-resilient: full headless Chromium by default; set `BROWSER_TEST` to a Windows browser exe to drive it over CDP — in NAT run `npx @brunosps00/dev-workflow setup-wsl-browser` once for the cdp-relay.exe + Hyper-V rule, mirrored networking works directly);
+see the "Browser on WSL" section of `dw-testing-discipline/references/playwright-recipes.md`. Chromium
+only — `screencast`/CDP do not support Firefox/WebKit.
 
 ## Completion Criteria
 

package/scaffold/en/commands/dw-generate-pr.md

@@ -15,11 +15,11 @@ You are an assistant specialized in creating well-documented Pull Requests. Your
 |-------|---------|
 | `dw-verify` | **ALWAYS** — invoked before `git push`. Without a VERIFICATION REPORT PASS in the current session AFTER the last code edit, the PR **CANNOT** be created. |
 | `dw-git-discipline` | **ALWAYS** — validates branch naming (`<type>/<scope>` kebab-case), atomic-commit history (each commit single-intent, conventional message), branch lifetime (flag if >7 days old), and PR scope (suggest split if diff > ~400 lines). PR description follows summary + test plan structure, not a `git log` dump. |
-| `/dw-secure-audit` | **ALWAYS for TS/Python/C#/Rust projects** — `security-check.md` with status ≠ REJECTED is required for supported-language projects. |
+| `/dw-secure-audit` | **ALWAYS for TS/Python/C#/Rust projects** — a fresh `.dw/secure-audit/audit-summary.md` with status ≠ REJECTED is required for supported-language projects. |
 
 <critical>Hard gate 1 (verify): if the current session has no VERIFICATION REPORT PASS from `dw-verify` produced AFTER the last edit/commit, STOP and invoke `dw-verify` before proceeding. A PR is a permanent artifact — it demands the highest verification standard.</critical>
 
-<critical>Hard gate 2 (security): for TS/Python/C#/Rust projects, if `{{PRD_PATH}}/security-check.md` is missing OR has REJECTED status, STOP and invoke `/dw-secure-audit` before proceeding. HIGH/CRITICAL vulnerabilities CANNOT reach the PR. For other languages (Go, Java, etc.), this gate is skipped with a note.</critical>
+<critical>Hard gate 2 (security): for TS/Python/C#/Rust projects, if `.dw/secure-audit/audit-summary.md` is missing, stale (predates the last edit), OR has REJECTED status, STOP and invoke `/dw-secure-audit` before proceeding. SECRET findings and HIGH/CRITICAL vulnerabilities CANNOT reach the PR. For other languages (Go, Java, etc.), this gate is skipped with a note.</critical>
 
 ## Usage