@brunosps00/dev-workflow 1.0.6 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ This will:
 
 > **Compozy-inspired disciplines.** Since 0.5.0, dev-workflow bundles three primitives — `dw-verify`, `dw-memory`, `dw-review-rigor` — adapted from the [Compozy](https://github.com/compozy/compozy) project and invoked internally by existing commands. See [docs/compozy-integration.md](docs/compozy-integration.md) for what was ported and what was not.
 
-Optional dependencies (Playwright browsers, react-doctor, Trivy, Docker):
+Optional dependencies (Playwright browsers, react-doctor, Trivy, Semgrep, gitleaks, Docker):
 ```bash
 npx @brunosps00/dev-workflow install-deps
 ```
@@ -75,7 +75,7 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 |---------|------|------------|
 | **`/dw-adr "decision"`** | Records an Architecture Decision Record at `.dw/spec/<prd>/adrs/`. | `/dw-plan techspec --council`; deviations from constitution |
 | **`/dw-intel "question"`** | Query codebase intelligence (`.dw/intel/`). `--build` (re)creates the index. | `/dw-plan`, `/dw-review`, `/dw-bugfix` |
-| **`/dw-secure-audit`** | Unified security: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain check. Hard gate. Flags: `--scan-only`, `--plan`, `--execute`. | `/dw-review`, `/dw-generate-pr` (for TS/Python/C#/Rust) |
+| **`/dw-secure-audit`** | **Security Gate** (phase after review/QA, before commit/PR): OWASP + Semgrep SAST (diff/generated code) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block (secrets have no ADR escape). Flags: `--scan-only`, `--plan`, `--execute`. See [docs/security-gate.md](docs/security-gate.md). | `/dw-autopilot` (explicit step), enforced by `/dw-generate-pr` |
 | **`/dw-goal "<objective>"`** | Durable objective contract. Uses Codex native `/goal` when available and `.dw/goals/` everywhere for Codex, Copilot, Claude Code, and OpenCode. | `/dw-autopilot` after planning |
 | **`/dw-find-skills "query"`** | Searches `npx skills` ecosystem, vets, installs. | manual when extending the bundle |
 | **`/dw-update`** | Updates dev-workflow to latest npm release with rollback snapshot. | manual maintenance |

package/bin/dev-workflow.js

@@ -5,6 +5,7 @@ const installDeps = require('../lib/install-deps');
 const installAzureSkills = require('../lib/install-azure-skills');
 const installAwsSkills = require('../lib/install-aws-skills');
 const uninstall = require('../lib/uninstall');
+const setupWslBrowser = require('../lib/setup-wsl-browser');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -45,6 +46,7 @@ const HELP_TEXT = `
     repair                 Reconcile managed files using the recorded install state
     subtask                Create, complete, consume, and list local subagent handoffs
     install-deps           Install system dependencies (Playwright browsers, MCP servers)
+    setup-wsl-browser      (WSL) Build the CDP relay on Windows + add the Hyper-V firewall rule so flows can drive the real Windows browser
     install-azure-skills   Opt-in: clone curated Azure skills from MicrosoftDocs/Agent-Skills
                            into .agents/skills/azure/ and register the Microsoft Learn MCP
                            server (HTTP, no-auth). Interactive category selection.
@@ -95,6 +97,9 @@ async function main() {
     case 'install-deps':
       installDeps.run();
       break;
+    case 'setup-wsl-browser':
+      setupWslBrowser.run();
+      break;
     case 'install-azure-skills':
       await installAzureSkills.run();
       break;

package/lib/constants.js

@@ -25,7 +25,7 @@ const COMMANDS = {
     { 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-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block. Auto-invoked by /dw-review and /dw-generate-pr, explicit phase in /dw-autopilot, and runnable standalone.' },
     { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
     { name: 'dw-subtask-start', description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
     { name: 'dw-subtask-complete', description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
@@ -58,7 +58,7 @@ const COMMANDS = {
     { 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-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH bloqueiam. Auto-invocado por /dw-review e /dw-generate-pr, fase explicita no /dw-autopilot, e executavel standalone.' },
     { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
     { name: 'dw-subtask-start', description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
     { name: 'dw-subtask-complete', description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },

package/lib/install-deps.js

@@ -6,9 +6,9 @@ function run() {
 
   const deps = [
     {
-      name: 'Playwright browsers',
+      name: 'Playwright browsers (Chromium + deps)',
       check: 'npx playwright --version',
-      install: 'npx playwright install --with-deps',
+      install: 'npx playwright install --with-deps chromium',
     },
     {
       name: 'Context7 MCP',
@@ -31,7 +31,44 @@ function run() {
         '  Windows:  choco install trivy   (or: scoop install trivy)',
         '  Docker:   docker pull aquasec/trivy:latest   (use via alias or wrapper)',
         '',
-        'Once installed, /dw-security-check will use it for CVE, secret, and IaC scanning.',
+        'Once installed, /dw-secure-audit will use it for CVE, secret, and IaC scanning.',
+      ],
+    },
+    {
+      name: 'Semgrep (SAST)',
+      check: 'semgrep --version',
+      install: null,
+      instructions: [
+        'Semgrep powers the SAST layer of /dw-secure-audit (semantic analysis of generated code).',
+        '  pipx:     pipx install semgrep   (recommended — isolated)',
+        '  pip:      python3 -m pip install --user semgrep',
+        '  macOS:    brew install semgrep',
+        '  Docker:   docker pull semgrep/semgrep:latest   (use via alias or wrapper)',
+        '',
+        'The gate runs pinned rulesets (p/security-audit, p/owasp-top-ten, p/secrets) on the diff.',
+      ],
+    },
+    {
+      name: 'gitleaks (secret scanner)',
+      check: 'gitleaks version',
+      install: null,
+      instructions: [
+        'gitleaks is the dedicated secret scanner for /dw-secure-audit (any hit blocks the gate).',
+        '  macOS:    brew install gitleaks',
+        '  Linux:    download from https://github.com/gitleaks/gitleaks/releases (or: go install github.com/gitleaks/gitleaks/v8@latest)',
+        '  Windows:  scoop install gitleaks   (or: choco install gitleaks)',
+        '  Docker:   docker pull zricethezav/gitleaks:latest',
+      ],
+    },
+    {
+      name: 'syft (SBOM, optional)',
+      check: 'syft version',
+      install: null,
+      instructions: [
+        'syft generates the SBOM for the advisory SBOM/license layer of /dw-secure-audit (optional, non-blocking).',
+        '  macOS:    brew install syft',
+        '  Linux:    curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin',
+        '  Windows:  scoop install syft',
       ],
     },
     {
@@ -93,6 +130,54 @@ function run() {
   if (failed) parts.push(`${failed} failed`);
   console.log(`  Done! ${parts.join(', ')}`);
   console.log();
+
+  checkPlaywrightVersion();
+  printBrowserGuidance();
+}
+
+// page.screencast (used by /dw-functional-doc to record video, including over CDP) needs
+// Playwright >= 1.60. Warn if the installed version is older.
+function checkPlaywrightVersion() {
+  try {
+    const raw = execSync('npx playwright --version', { stdio: 'pipe', timeout: 15000 }).toString();
+    const match = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return;
+    const [, major, minor] = match.map(Number);
+    if (major < 1 || (major === 1 && minor < 60)) {
+      console.log(`  \x1b[33m⚠ Playwright ${match[0]} detected.\x1b[0m /dw-functional-doc video needs >= 1.60 (page.screencast).`);
+      console.log('    Upgrade in your project:  npm i -D @playwright/test@latest');
+      console.log();
+    }
+  } catch {
+    // playwright not resolvable here; the flow runner reports it at runtime
+  }
+}
+
+function isWsl() {
+  if (process.env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft/i.test(require('fs').readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function printBrowserGuidance() {
+  if (!isWsl()) return;
+  const mirrored = require('fs').existsSync('/sys/class/net/loopback0');
+  console.log('  Browser automation on WSL (dw-qa / dw-functional-doc / dw-redesign-ui):');
+  console.log('    Default: full headless Chromium (desktop-faithful, no WSLg) — works out of the box.');
+  console.log('    To drive the real Windows browser, set BROWSER_TEST to its exe path, e.g.');
+  console.log('    BROWSER_TEST="/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe".');
+  if (mirrored) {
+    console.log('    Mirrored networking detected — connects to the Windows browser on 127.0.0.1 directly.');
+  } else {
+    console.log('    NAT networking — run `npx @brunosps00/dev-workflow setup-wsl-browser` once to build the');
+    console.log('    cdp-relay.exe (needs Rust on Windows) and add the Hyper-V firewall rule. Otherwise flows');
+    console.log('    fall back to the local headless Chromium (faithful video, no Windows browser).');
+  }
+  console.log('    Details: .dw/skills/dw-testing-discipline/references/playwright-recipes.md ("Browser on WSL").');
+  console.log();
 }
 
 module.exports = { run };

package/lib/setup-wsl-browser.js

@@ -0,0 +1,149 @@
+const { execSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Builds the Rust CDP relay (cdp-relay.exe) on Windows and adds the one-time Hyper-V firewall
+// rule so WSL (NAT networking) can drive the real Windows browser over CDP. Idempotent.
+//
+// Why: Chromium binds its debug port to Windows loopback only, and the WSL Hyper-V firewall
+// defaults inbound to Block. A fixed-port relay + one Hyper-V allow rule bridges WSL -> browser.
+// The relay is a tiny static .exe — no Node/Python/PowerShell runtime dependency at run time.
+
+const RELAY_PORT = 39222;
+const WSL_VM_CREATOR_ID = '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'; // standard WSL VM creator id
+const RULE_NAME = 'dw-cdp-relay';
+
+function isWsl() {
+  if (process.env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft/i.test(fs.readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function winEnv(name) {
+  try {
+    const out = execSync(`cmd.exe /c "echo %${name}%"`, { stdio: 'pipe' }).toString().split(/\r?\n/)[0].trim();
+    return /^[A-Za-z]:\\/.test(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function findWindowsCargo() {
+  try {
+    const line = execSync('cmd.exe /c where cargo', { stdio: 'pipe' })
+      .toString()
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .find((s) => /cargo\.exe$/i.test(s));
+    if (!line) return null;
+    const wsl = execSync(`wslpath -u "${line}"`, { stdio: 'pipe' }).toString().trim();
+    return fs.existsSync(wsl) ? { winPath: line, wslPath: wsl } : null;
+  } catch {
+    return null;
+  }
+}
+
+function copyCrate(srcDir, destWslDir) {
+  fs.mkdirSync(path.join(destWslDir, 'src'), { recursive: true });
+  fs.copyFileSync(path.join(srcDir, 'Cargo.toml'), path.join(destWslDir, 'Cargo.toml'));
+  fs.copyFileSync(path.join(srcDir, 'src', 'main.rs'), path.join(destWslDir, 'src', 'main.rs'));
+}
+
+function run() {
+  console.log('\n  dev-workflow setup-wsl-browser');
+  console.log(`  ${'='.repeat(40)}\n`);
+
+  if (!isWsl()) {
+    console.log('  This command is only needed on WSL. On native Windows/macOS/Linux, flows use the local browser directly.');
+    return;
+  }
+
+  const localAppData = winEnv('LOCALAPPDATA');
+  if (!localAppData) {
+    console.log('  \x1b[31m✗\x1b[0m Could not resolve %LOCALAPPDATA% on Windows. Is Windows interop enabled?');
+    return;
+  }
+  const destWin = `${localAppData}\\dev-workflow`;
+  const destWsl = execSync(`wslpath -u "${destWin}"`, { stdio: 'pipe' }).toString().trim();
+  const srcWslDir = `${destWsl}/cdp-relay-src`;
+  const srcWinDir = `${destWin}\\cdp-relay-src`;
+
+  // 1) Build the relay with the Windows Rust toolchain.
+  const cargo = findWindowsCargo();
+  if (!cargo) {
+    console.log('  \x1b[33m—\x1b[0m No Windows `cargo` found (where cargo). Install Rust on Windows: https://rustup.rs');
+    console.log('    Without the relay, WSL flows fall back to the local headless Chromium (faithful, no Windows browser).');
+    return;
+  }
+
+  const crateSrc = path.join(__dirname, '..', 'scaffold', 'scripts', 'cdp-relay');
+  if (!fs.existsSync(path.join(crateSrc, 'Cargo.toml'))) {
+    console.log(`  \x1b[31m✗\x1b[0m Relay crate source not found at ${crateSrc}`);
+    return;
+  }
+
+  process.stdout.write('  Building cdp-relay.exe (Windows cargo, release)...');
+  try {
+    fs.mkdirSync(destWsl, { recursive: true });
+    copyCrate(crateSrc, srcWslDir);
+    execSync(`"${cargo.wslPath}" build --release --manifest-path "${srcWinDir}\\Cargo.toml"`, {
+      stdio: 'pipe',
+      timeout: 180000,
+    });
+    fs.copyFileSync(path.join(srcWslDir, 'target', 'release', 'cdp-relay.exe'), path.join(destWsl, 'cdp-relay.exe'));
+    console.log(' \x1b[32m✓\x1b[0m');
+    console.log(`    ${destWin}\\cdp-relay.exe`);
+  } catch (err) {
+    console.log(' \x1b[31m✗\x1b[0m');
+    console.log(`    ${String(err.message).split('\n')[0]}`);
+    return;
+  }
+
+  // 2) Add the Hyper-V firewall inbound rule (one-time, elevated -> UAC prompt).
+  console.log(`\n  Adding Hyper-V firewall rule for TCP ${RELAY_PORT} (a UAC prompt will appear — accept it)...`);
+  const inner = [
+    `Remove-NetFirewallHyperVRule -Name '${RULE_NAME}' -ErrorAction SilentlyContinue;`,
+    `New-NetFirewallHyperVRule -Name '${RULE_NAME}' -DisplayName 'dev-workflow cdp-relay'`,
+    `-Direction Inbound -Action Allow -VMCreatorId '${WSL_VM_CREATOR_ID}' -Protocol TCP -LocalPorts ${RELAY_PORT}`,
+  ].join(' ');
+  try {
+    execSync(
+      `powershell.exe -NoProfile -Command "Start-Process powershell -Verb RunAs -WindowStyle Hidden -ArgumentList '-NoProfile','-Command',\\"${inner}\\""`,
+      { stdio: 'pipe', timeout: 60000 },
+    );
+  } catch {
+    // Start-Process returns before the elevated process finishes; verify below regardless.
+  }
+
+  // 3) Verify.
+  let ok = false;
+  for (let i = 0; i < 10 && !ok; i += 1) {
+    try {
+      const out = execSync(
+        `powershell.exe -NoProfile -c "Get-NetFirewallHyperVRule -Name '${RULE_NAME}' -ErrorAction SilentlyContinue | Select-Object -Expand Action"`,
+        { stdio: 'pipe', timeout: 15000 },
+      ).toString();
+      ok = /Allow/i.test(out);
+    } catch {
+      ok = false;
+    }
+    if (!ok) execSync('sleep 1');
+  }
+
+  console.log(`  ${'='.repeat(40)}`);
+  if (ok) {
+    console.log('  \x1b[32m✓ Done.\x1b[0m The Windows browser is reachable from WSL over CDP.');
+    console.log(`    Set BROWSER_TEST to a Windows browser exe to use it, e.g.`);
+    console.log('    BROWSER_TEST="/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"');
+  } else {
+    console.log('  \x1b[33m⚠ Hyper-V firewall rule not confirmed.\x1b[0m UAC may have been declined, or this Windows lacks');
+    console.log('    Hyper-V firewall cmdlets. Flows will fall back to the local headless Chromium (faithful video, no');
+    console.log('    Windows browser). You can also enable mirrored networking instead. Re-run to retry.');
+  }
+  console.log();
+}
+
+module.exports = { run, RELAY_PORT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.0.6",
+  "version": "1.1.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/commands/dw-analyze-project.md

@@ -827,6 +827,27 @@ If after the heuristics nothing crosses the bar (small codebase, low churn, no i
 
 **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.
 
+### Step 10: Design authority (DESIGN.md) — frontend projects only
+
+Run this when a frontend was detected (React/Vue/Angular/Svelte/Tailwind/CSS) so `dw-ui-discipline`'s
+grounding question 1 ("where do design decisions come from?") has a project authority to defer to. This
+closes the loop the grounding only *reads* today.
+
+1. **Check for an existing authority first.** If `DESIGN.md`, `BRAND.md`, or `STYLE_GUIDE.md` already
+   exists at the project (or a frontend module) root, do NOT overwrite — note its location and stop.
+2. **Detect design tokens** in priority order: Tailwind `theme`/`@theme` (colors, fontFamily, spacing,
+   radius), CSS custom properties in `globals.css`/`theme.css`/`tokens.css`, MUI/Chakra theme exports,
+   shadcn `components.json`, Storybook theme. Read the real values — do not invent.
+3. **If tokens exist:** synthesize `DESIGN.md` at the frontend root capturing what the project ALREADY
+   uses — palette (with the actual hex/oklch values and token names), typography (families, scale,
+   weights), spacing/radius scale, and any component conventions observed. Head it with:
+   `> Generated by /dw-analyze-project from existing tokens on <date>. Curate before treating as canon.`
+4. **If no tokens exist:** do NOT fabricate a palette. Recommend bootstrapping from
+   `dw-ui-discipline/references/curated-defaults.md` and record that recommendation in the rules index.
+5. Reference the new `DESIGN.md` from `.dw/rules/<frontend-module>.md` so downstream commands find it.
+
+This step is additive and reversible; it never edits component code, only documents what is there.
+
 ## Quality Checklist
 
 Before declaring the analysis complete, verify:
@@ -850,6 +871,7 @@ Before declaring the analysis complete, verify:
 - [ ] 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)
+- [ ] Step 10 (design authority) ran for frontend projects: existing authority respected, or `DESIGN.md` generated from real tokens, or curated-defaults bootstrap recommended
 - [ ] 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

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

@@ -152,10 +152,11 @@ When `autopilot-state.json status=plan_complete`, formally invoke:
 The goal owns this sequence:
 
 1. `/dw-run <prd-path>`
-2. `/dw-review <prd-path>` (full review: coverage, quality, conventions, security, constitution, verify)
+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.
 
 <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>
 
@@ -175,6 +176,7 @@ 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.
 
 If anything is missing, STOP and re-run the missing formal command. Do not commit partial work.

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
 

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

@@ -83,7 +83,7 @@ When available under `./.agents/skills/`, these are invoked operationally:
 
 1. **Pre-flight**: confirm the project dev server can run. Confirm `.dw/spec/<prd>/` has the PRD + TechSpec + tasks.
 2. **Map FRs to test plan**: for each FR, identify the user-facing flow that exercises it.
-3. **Drive Playwright MCP** (or fallback to local Playwright per `dw-testing-discipline/references/playwright-recipes.md`):
+3. **Drive Playwright MCP** (if unavailable or blocked — common on WSL — fall back to the WSL-resilient local capture `node .dw/scripts/lib/capture-screenshots.mjs`, which picks the browser via `.dw/scripts/lib/resolve-browser.mjs`; see the "Browser on WSL" section of `dw-testing-discipline/references/playwright-recipes.md`):
    - Happy paths for each FR.
    - Edge cases (boundary inputs, network failure, validation errors).
    - Negative flows (unauthorized actions, malformed input).

package/scaffold/en/commands/dw-redesign-ui.md

@@ -56,12 +56,12 @@ Use diagnostic tools based on the project's framework:
 ## Required Behavior
 
 1. Identify the target: page, component, or route to be redesigned.
-2. **AUDIT**: read the current implementation, identify the CSS stack (Tailwind, CSS Modules, styled-components, etc.), capture screenshot using `dw-testing-discipline`/playwright-recipes if available, run react-doctor if React project.
+2. **AUDIT**: read the current implementation, identify the CSS stack (Tailwind, CSS Modules, styled-components, etc.), capture the before-state screenshot (Playwright MCP, or `node .dw/scripts/lib/capture-screenshots.mjs` as the WSL-resilient fallback), run react-doctor if React project.
 3. Ask 3 to 5 questions about redesign goals: style direction, brand constraints, inspirations, target audience, priority devices.
 4. **PROPOSE**: present 2 to 3 design directions after passing the `dw-ui-discipline` hard-gate (brand authorities or curated defaults selected; surface job sentence written; state matrix enumerated; scene sentence written). Each direction lists color palette, typography pairing, layout style, and rationale. Self-check each direction against the 14 anti-slop patterns. For EACH direction, explicitly describe the mobile layout (<=768px) and desktop layout (>=1024px), including how elements reorganize, stack, or hide between breakpoints.
 5. Wait for explicit user approval before implementing.
 6. **IMPLEMENT**: apply the chosen design with a mobile-first approach — implement the mobile layout first, then add media queries/breakpoints for tablet and desktop. Respect the existing stack. Use `vercel-react-best-practices` for React/Next.js. Maintain the project's CSS methodology.
-7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility against `dw-ui-discipline/references/accessibility-floor.md` (WCAG 2.2 AA — non-negotiable: contrast, focus-visible, keyboard nav, ARIA, no traps), run react-doctor `--diff` if React. Use `dw-testing-discipline/references/playwright-recipes.md` to capture screenshots at 375px viewport (mobile) and 1440px viewport (desktop).
+7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility against `dw-ui-discipline/references/accessibility-floor.md` (WCAG 2.2 AA — non-negotiable: contrast, focus-visible, keyboard nav, ARIA, no traps), run react-doctor `--diff` if React. Capture screenshots at 375px (mobile) and 1440px (desktop) — `node .dw/scripts/lib/capture-screenshots.mjs --url <url> --widths 375,1440` is the WSL-resilient path; see the "Browser on WSL" section of `dw-testing-discipline/references/playwright-recipes.md`.
 8. **PERSIST CONTRACT**: if the user approved a direction, generate `design-contract.md` in the PRD directory (`.dw/spec/prd-[name]/design-contract.md`) with: approved direction, color palette, typography pairing, layout rules, accessibility rules, and component rules. This contract will be read by `dw-run-task` and `dw-run-plan` to ensure visual consistency.
 
 ## Codebase Intelligence

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

@@ -44,9 +44,10 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 
 - `dw-review-rigor`: **ALWAYS** — applies de-duplication (same pattern in N files = 1 finding), severity ordering (critical → high → medium → low), verify-before-flag, skip-what-linter-catches, and signal-over-volume. The "Issues Found" table follows this discipline.
 - `dw-verify`: **ALWAYS** — invoked before emitting `APPROVED` or `APPROVED WITH CAVEATS`. Without a VERIFICATION REPORT PASS (test + lint + build), verdict cannot be APPROVED.
-- `dw-secure-audit`: **ALWAYS for TS/Python/C#/Rust projects** — security gate. If the project uses a supported language and a recent `secure-audit.md` is missing OR has REJECTED status, the verdict is **REJECTED** — no exception.
+- `dw-secure-audit` (**Security Gate**): **ALWAYS for TS/Python/C#/Rust projects** — triggered here and the verdict is enforced. If the project's language is supported and a fresh `.dw/secure-audit/audit-summary.md` is missing OR has REJECTED status, the review verdict is **REJECTED** — no exception. The same gate is also a standalone command (`/dw-secure-audit`) and an explicit phase in `/dw-autopilot`. It now adds Semgrep SAST (diff) + gitleaks secrets on top of OWASP/Trivy/SCA.
+- `security-review`: the OWASP diff-level skill the gate uses (injection, authz, secrets, SSRF, crypto — HIGH CONFIDENCE only).
 - `dw-simplification`: use when the diff touches dense or twisty code — applies Chesterton's Fence, behavior-preserving refactor protocol, complexity metrics.
-- `dw-ui-discipline`: use when the diff touches UI — runs the 14 visual-slop patterns + accessibility floor checks.
+- `dw-ui-discipline`: use when the diff touches UI — runs the 14 visual-slop patterns + accessibility floor checks. For a deterministic gate, also run `node .dw/scripts/lib/ui-slop-detect.mjs <changed-ui-paths> --fail-on error` (a wrapper over the impeccable detector); treat blocking findings as **REJECTED** and surface warnings in the report.
 - `dw-testing-discipline`: use when the diff touches tests — applies the 25 anti-patterns catalog + 6 agent guardrails (when tests were agent-authored).
 - `dw-llm-eval`: **REQUIRED when the diff touches AI/LLM feature code paths**. Reference dataset + ≥2 oracle rungs + judge calibration (if rung 4 used) + eval run results MUST be in the PR. Missing → REJECTED.
 - `security-review`: use when the diff touches auth, authorization, external input, upload, SQL, secrets, SSRF, XSS, or sensitive surfaces.
@@ -161,9 +162,10 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
    - Run dw-verify to produce a VERIFICATION REPORT (test + lint + build all GREEN).
    - Without PASS, verdict cannot be APPROVED.
 
-8. **Security Layer (`dw-secure-audit` for TS/Python/C#/Rust):**
-   - Run `/dw-secure-audit` against the PR. Latest scan must be present and not REJECTED.
-   - If language is supported and audit is missing OR REJECTED → verdict **REJECTED**.
+8. **Security Gate (`dw-secure-audit` for TS/Python/C#/Rust):**
+   - Trigger `/dw-secure-audit` against the diff (OWASP + Semgrep SAST + gitleaks + Trivy/SCA + supply-chain). It produces/refreshes `.dw/secure-audit/audit-summary.md`.
+   - Latest scan must be present, fresh (post-last-edit), and not REJECTED. If language is supported and the audit is missing OR REJECTED → review verdict **REJECTED**. SECRET findings always block (no ADR escape).
+   - The same gate is also runnable standalone (`/dw-secure-audit`) and is an explicit phase in `/dw-autopilot`; `/dw-generate-pr` re-enforces the verdict before the PR.
 
 ### Output