@brunosps00/dev-workflow 1.0.6 → 1.1.1

package/README.md

@@ -19,24 +19,24 @@ 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, syft, Docker):
 ```bash
 npx @brunosps00/dev-workflow install-deps
 ```
 
 ## Commands
 
-dev-workflow v1.0.6 ships **31 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.1.1 ships **31 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 in two invocations. First run completes PRD → TechSpec → Tasks and stops. Second run resumes from state, executes `/dw-goal --from-autopilot <slug>` for Run → Review → QA/Fix → Review, then Commit → PR. |
+| **`/dw-autopilot "wish"`** | Default entry point in two invocations. First run completes PRD → TechSpec → Tasks and stops. Second run resumes from state, executes `/dw-goal --from-autopilot <slug>` for Run → Review → QA/Fix → Review, then Security Gate → Commit → PR. |
 | **`/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. |
 
-### Tier 2 — Pipeline granular (7)
+### Tier 2 — Pipeline granular (9)
 
 Use these when you want step-by-step control instead of `/dw-autopilot`.
 
@@ -52,13 +52,13 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (8)
+### Tier 3 — Specialty (10)
 
 | 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). 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-analyze-project`** | Scans the repo, writes `.dw/rules/` (per-module conventions, anti-patterns, naming). Step 8 offers `.dw/constitution.md`; Step 9 writes `.dw/rules/concerns.md`; Step 10 can synthesize a frontend `DESIGN.md` from existing tokens. 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; UI diffs can also run the deterministic impeccable slop detector. |
+| **`/dw-functional-doc`** | Maps screens + user flows into a functional doc, validated end-to-end with Playwright. Uses the WSL-resilient browser resolver and can capture guided functional video evidence. |
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
@@ -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-review`, `/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 |
@@ -87,17 +87,17 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 
 ```
 /dw-autopilot "wish"  ------>  First invocation: PRD → TechSpec → Tasks → STOP
-/dw-autopilot          ------>  Second invocation: /dw-goal → Commit → PR
+/dw-autopilot          ------>  Second invocation: /dw-goal → Security Gate → Commit → PR
     --- OR step-by-step ---
 
 /dw-brainstorm  -->  /dw-plan           -->  .dw/spec/prd-{name}/{prd,techspec,tasks}.md
                           |
-                    /dw-goal             -->  /dw-run → /dw-review → /dw-qa → /dw-review
+                    /dw-goal             -->  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit
                           |
                     /dw-commit + /dw-generate-pr
 
 Manual alternative after /dw-plan:
-  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-commit → /dw-generate-pr
+  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit → /dw-commit → /dw-generate-pr
 
 Shortcuts:
   /dw-intel "question"         Query codebase intelligence
@@ -116,19 +116,30 @@ A **constitution** is a declarative list of principles your team commits to (e.g
 **How it works:**
 
 - `/dw-analyze-project` offers three paths: synthesize from observed patterns (with your approval), install canonical defaults, or skip.
-- If `/dw-create-prd`, `/dw-create-techspec`, or `/dw-code-review` run **without** a constitution, they auto-install the defaults template (10 canonical principles at `severity: info`), notify in chat, and continue. Ausência nunca bloqueia.
+- If `/dw-plan` or `/dw-review` run **without** a constitution, they auto-install the defaults template (10 canonical principles at `severity: info`), notify in chat, and continue. Ausência nunca bloqueia.
 - Once principles exist:
   - `severity: info` → reported, never blocks.
   - `severity: high` → blocks PR/techspec when violated, unless an ADR justifies the deviation.
   - `severity: critical` → blocks plus requires reviewer sign-off in the ADR.
 - Defaults start at `info`; you promote severities as your team trusts enforcement.
 
-**Tasks consistency check.** At the end of `/dw-create-tasks`, a 5-dimension consistency check validates PRD ↔ TechSpec ↔ Tasks alignment (FR coverage, task grounding, test coverage, dependency DAG, constitution alignment) and writes `.dw/spec/prd-<feature>/tasks-validation.md`. Any FAIL blocks user approval until resolved or explicitly overridden.
+**Tasks consistency check.** At the end of `/dw-plan tasks`, a 5-dimension consistency check validates PRD ↔ TechSpec ↔ Tasks alignment (FR coverage, task grounding, test coverage, dependency DAG, constitution alignment) and writes `.dw/spec/prd-<feature>/tasks-validation.md`. Any FAIL blocks user approval until resolved or explicitly overridden.
 
 ## Template Overrides
 
 Customize templates locally without losing dev-workflow updates. Drop a file at `.dw/templates/overrides/<name>.md`; the override is used in place of the bundled core template on every `update`. Subdirectories work too (e.g., `.dw/templates/overrides/functional-doc/e2e-runbook.md`). See `.dw/templates/overrides/README.md` (created on init) for the workflow and `diff` cadence guidance.
 
+## Post-Update Actions
+
+`dev-workflow update` refreshes managed files only: commands, templates, references, scripts, bundled skills, wrappers, agents, and MCP config. It does **not** overwrite project-derived docs such as `.dw/rules/`, `.dw/constitution.md`, `.dw/rules/concerns.md`, `.dw/intel/`, or frontend `DESIGN.md`.
+
+After an update, the CLI prints **Post-update agent actions**. When `/dw-update` runs inside an agent, it should execute the listed commands in order:
+
+1. `/dw-analyze-project` when project-derived docs are missing or need refresh; this owns `.dw/rules/`, constitution, concerns map, and frontend `DESIGN.md`.
+2. `/dw-intel --build` when the codebase index is missing or stale.
+3. `/dw-harness-audit` to validate the install after managed files changed.
+4. `/dw-skill-health` to inspect refreshed skills and agents.
+
 ## Auto-Trigger (CLAUDE.md / AGENTS.md)
 
 `dev-workflow init` seeds two files at the project root with the same content: `CLAUDE.md` (read by Claude Code) and `AGENTS.md` (read by Codex CLI, Copilot CLI, and OpenCode). Together they tell the agent **when to invoke each `dw-*` command without being explicitly asked**.
@@ -188,6 +199,8 @@ your-project/
 │   ├── scripts/           # Utility scripts
 │   ├── spec/              # PRD directories — each contains tasks-validation.md
 │   ├── bugfixes/          # Persistent bugfix records: NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md} + review/, QA/
+│   ├── goals/             # Durable goal state used by /dw-goal and /dw-autopilot
+│   ├── secure-audit/      # Security Gate summaries and per-layer reports
 │   ├── subtasks/          # Local ephemeral subagent input packets and handoffs (pending/archive ignored by Git)
 │   └── STATE.md           # Session state: Decisions, Blockers, Todos, Open Loops, Deferred Ideas, Lessons, Preferences (managed by /dw-pause + /dw-resume)
 ├── CLAUDE.md              # Auto-trigger decision tree for Claude Code (merge-aware, includes Auto-Sizing Matrix)
@@ -224,6 +237,7 @@ Subagent handoffs use local packets under `.dw/subtasks/`:
 npx @brunosps00/dev-workflow subtask create --agent=dw-code-explorer --goal="Map the auth flow"
 npx @brunosps00/dev-workflow subtask complete --slug=<slug> --file=<handoff.md>
 npx @brunosps00/dev-workflow subtask consume
+npx @brunosps00/dev-workflow subtask list
 ```
 
 ## Bundled Skills
@@ -245,15 +259,15 @@ These are not slash commands — they are primitives other commands call to enfo
 
 | Skill | Description | Invoked by | Inspired by |
 |-------|-------------|------------|-------------|
-| **dw-verify** | Enforces fresh verification evidence before any completion, commit, or PR claim — with Iron Law, gate function, and Verification Report template | `dw-run-task`, `dw-run-plan`, `dw-fix-qa`, `dw-bugfix`, `dw-code-review`, `dw-generate-pr` | [Compozy](https://github.com/compozy/compozy) `cy-final-verify` |
-| **dw-memory** | Two-tier workflow memory (shared `MEMORY.md` + per-task `<N>_memory.md`) with promotion test and compaction rules, so cross-task context persists cleanly | `dw-run-task`, `dw-run-plan`, `dw-autopilot` | [Compozy](https://github.com/compozy/compozy) `cy-workflow-memory` |
-| **dw-review-rigor** | Review discipline: de-duplication, severity ordering, verify-intent-before-flagging, skip-linter-issues, signal-over-volume | `dw-code-review`, `dw-review-implementation`, `dw-refactoring-analysis` | [Compozy](https://github.com/compozy/compozy) `cy-review-round` |
-| **dw-council** | Multi-advisor debate (3-5 archetypes) with steel-manning, concession tracking, and dissent-preserving synthesis. Opt-in only. | `dw-brainstorm --council`, `dw-create-techspec --council` | [Compozy](https://github.com/compozy/compozy) `cy-idea-factory` |
-| **dw-codebase-intel** | Codebase intelligence (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`) with incremental updates and query patterns. Cross-cutting reference: `api-design-discipline` (Hyrum's Law, contract-first, error semantics) used when techspecs design API endpoints. | `/dw-intel`, `/dw-map-codebase`, `dw-create-techspec` | [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (MIT) + [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
-| **dw-execute-phase** | Goal-backward 6-dimension plan verification (`plan-checker`) and wave-based parallel task execution (`executor`) with atomic commit, deviation handling, and checkpoint recovery | `dw-run-plan`, `dw-autopilot` | [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (MIT) |
-| **dw-source-grounding** | Detect → Fetch → Implement → Cite protocol with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` citations. Strict source-priority hierarchy (Tier 1 official docs > Tier 2 maintainer blogs > Tier 3 Stack Overflow as discovery only). | `dw-create-techspec`, `dw-deps-audit`, `dw-deep-research` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
-| **dw-simplification** | Chesterton's Fence (understand WHY before changing), behavior-preserving refactor protocol (test gate before/after), complexity metrics (cyclomatic, cognitive, depth, fan-out), Rule of 500 for large refactors | `dw-code-review`, `dw-refactoring-analysis` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
-| **dw-debug-protocol** | Stop-the-line discipline plus six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Error categorization matrix; instrument-first non-reproducible-bug strategy. | `dw-bugfix`, `dw-fix-qa` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
+| **dw-verify** | Enforces fresh verification evidence before any completion, commit, or PR claim — with Iron Law, gate function, and Verification Report template | `/dw-run`, `/dw-goal`, `/dw-qa --fix`, `/dw-bugfix`, `/dw-review`, `/dw-generate-pr` | [Compozy](https://github.com/compozy/compozy) `cy-final-verify` |
+| **dw-memory** | Two-tier workflow memory (shared `MEMORY.md` + per-task `<N>_memory.md`) with promotion test and compaction rules, so cross-task context persists cleanly | `/dw-run`, `/dw-goal`, `/dw-autopilot`, `/dw-pause`, `/dw-resume` | [Compozy](https://github.com/compozy/compozy) `cy-workflow-memory` |
+| **dw-review-rigor** | Review discipline: de-duplication, severity ordering, verify-intent-before-flagging, skip-linter-issues, signal-over-volume | `/dw-review`, `/dw-brainstorm --refactor` | [Compozy](https://github.com/compozy/compozy) `cy-review-round` |
+| **dw-council** | Multi-advisor debate (3-5 archetypes) with steel-manning, concession tracking, and dissent-preserving synthesis. Opt-in only. | `/dw-brainstorm --council`, `/dw-plan techspec --council` | [Compozy](https://github.com/compozy/compozy) `cy-idea-factory` |
+| **dw-codebase-intel** | Codebase intelligence (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`) with incremental updates and query patterns. Cross-cutting reference: `api-design-discipline` (Hyrum's Law, contract-first, error semantics) used when techspecs design API endpoints. | `/dw-intel`, `/dw-intel --build`, `/dw-plan techspec` | [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (MIT) + [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
+| **dw-execute-phase** | Goal-backward 6-dimension plan verification (`plan-checker`) and wave-based parallel task execution (`executor`) with atomic commit, deviation handling, and checkpoint recovery | `/dw-run`, `/dw-goal`, `/dw-autopilot` | [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (MIT) |
+| **dw-source-grounding** | Detect → Fetch → Implement → Cite protocol with `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` citations. Strict source-priority hierarchy (Tier 1 official docs > Tier 2 maintainer blogs > Tier 3 Stack Overflow as discovery only). | `/dw-plan techspec`, `/dw-secure-audit --plan`, `/dw-brainstorm --research` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
+| **dw-simplification** | Chesterton's Fence (understand WHY before changing), behavior-preserving refactor protocol (test gate before/after), complexity metrics (cyclomatic, cognitive, depth, fan-out), Rule of 500 for large refactors | `/dw-review`, `/dw-brainstorm --refactor` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
+| **dw-debug-protocol** | Stop-the-line discipline plus six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Error categorization matrix; instrument-first non-reproducible-bug strategy. | `/dw-bugfix`, `/dw-qa --fix` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
 | **dw-git-discipline** | Trunk-based pattern (1-3 day branches, daily rebase, feature flags), atomic commit discipline (one intent per commit; refactor separate from feature), Conventional Commits, branch hygiene | `dw-commit`, `dw-generate-pr` | [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) |
 
 ### Domain expertise
@@ -278,7 +292,10 @@ Installed via `npx @brunosps00/dev-workflow install-deps`:
 | **Playwright** | Browser automation for QA, E2E tests, and visual validation | [playwright.dev](https://playwright.dev/) |
 | **Context7 MCP** | Contextual documentation lookup for AI assistants | [upstash/context7-mcp](https://github.com/upstash/context7-mcp) |
 | **react-doctor** | Health score and diagnostics for React projects | [react.doctor](https://www.react.doctor/) |
-| **Trivy** | Native binary scanner used by `/dw-security-check` for CVE, secret, and IaC scanning. `install-deps` detects presence and prints OS-specific install instructions (brew / curl script / choco / Docker) — does not install automatically. | [aquasecurity.github.io/trivy](https://aquasecurity.github.io/trivy/) |
+| **Trivy** | Native binary scanner used by `/dw-secure-audit` for CVE, secret, and IaC scanning. `install-deps` detects presence and prints OS-specific install instructions (brew / curl script / choco / Docker) — does not install automatically. | [aquasecurity.github.io/trivy](https://aquasecurity.github.io/trivy/) |
+| **Semgrep** | SAST layer for `/dw-secure-audit`, focused on generated-code diffs with pinned security rulesets. `install-deps` detects presence and prints OS-specific install instructions. | [semgrep.dev](https://semgrep.dev/) |
+| **gitleaks** | Dedicated secret scanner for `/dw-secure-audit`; any confirmed secret blocks without ADR exception. `install-deps` detects presence and prints OS-specific install instructions. | [github.com/gitleaks/gitleaks](https://github.com/gitleaks/gitleaks) |
+| **syft** | Optional SBOM/license inventory layer for `/dw-secure-audit`; advisory and non-blocking. `install-deps` detects presence and prints OS-specific install instructions. | [github.com/anchore/syft](https://github.com/anchore/syft) |
 | **Docker + Docker Compose** | Required by `/dw-new-project` and `/dw-dockerize` for dev dependency seeding and image generation. `install-deps` detects presence and prints OS-specific install instructions — does not install automatically. | [docs.docker.com](https://docs.docker.com/engine/install/) |
 
 ## Options
@@ -288,12 +305,17 @@ npx @brunosps00/dev-workflow init                          # Interactive languag
 npx @brunosps00/dev-workflow init --lang=en                # English, skip prompt
 npx @brunosps00/dev-workflow init --lang=pt-br             # Portuguese, skip prompt
 npx @brunosps00/dev-workflow init --force                  # Overwrite existing files
-npx @brunosps00/dev-workflow update                        # Update commands/templates only
-npx @brunosps00/dev-workflow install-deps                  # Install Playwright, react-doctor; check Trivy, Docker
+npx @brunosps00/dev-workflow update                        # Update managed files + print post-update agent actions
+npx @brunosps00/dev-workflow list-installed                # Show managed install state
+npx @brunosps00/dev-workflow doctor                        # Check wrappers, agents, skills, MCPs, gates
+npx @brunosps00/dev-workflow repair                        # Reconcile managed files from recorded install state
+npx @brunosps00/dev-workflow install-deps                  # Install Playwright, react-doctor; check security scanners + Docker
+npx @brunosps00/dev-workflow setup-wsl-browser             # WSL NAT: build CDP relay + add Hyper-V firewall rule
 npx @brunosps00/dev-workflow install-azure-skills          # Opt-in: Azure skills + Microsoft Learn MCP
 npx @brunosps00/dev-workflow install-azure-skills --products=azure-aks,azure-openai  # Subset override
 npx @brunosps00/dev-workflow install-aws-skills            # Opt-in: AWS skills + AWS MCP Server (needs uv + aws cli + creds)
 npx @brunosps00/dev-workflow install-aws-skills --region=eu-central-1  # Region override
+npx @brunosps00/dev-workflow uninstall                     # Remove managed files while preserving user data
 npx @brunosps00/dev-workflow help                          # Show help
 ```
 
@@ -304,12 +326,12 @@ After running `npx @brunosps00/dev-workflow init`:
 1. **Run `/dw-analyze-project`** in your AI assistant to generate project rules
 2. **Run `/dw-brainstorm`** to start planning a new feature
 3. **Run `/dw-help`** to see all available commands and workflows
-4. **(Optional) Run `npx @brunosps00/dev-workflow install-deps`** to install Playwright + react-doctor and check Trivy + Docker
-5. **Run `/dw-map-codebase`** once your project has source files to build the queryable index in `.dw/intel/`
+4. **(Optional) Run `npx @brunosps00/dev-workflow install-deps`** to install Playwright + react-doctor and check Trivy/Semgrep/gitleaks/syft + Docker
+5. **Run `/dw-intel --build`** once your project has source files to build the queryable index in `.dw/intel/`
 
 ## Acknowledgements
 
-Codebase intelligence (`/dw-intel`, `/dw-map-codebase`, the `dw-codebase-intel` bundled skill) and phase execution patterns (the `dw-execute-phase` bundled skill, with its `plan-checker` and `executor` agents) were adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) by gsd-build (MIT). Schemas (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`), the goal-backward verification protocol, and the wave-based parallel execution pattern come from there. dev-workflow specifics: `.dw/` namespace instead of `.planning/`, agent-driven runtime instead of `gsd-sdk` CLI, integration with the rest of the `dw-*` command surface.
+Codebase intelligence (`/dw-intel`, `/dw-intel --build`, the `dw-codebase-intel` bundled skill) and phase execution patterns (the `dw-execute-phase` bundled skill, with its `plan-checker` and `executor` agents) were adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) by gsd-build (MIT). Schemas (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`), the goal-backward verification protocol, and the wave-based parallel execution pattern come from there. dev-workflow specifics: `.dw/` namespace instead of `.planning/`, agent-driven runtime instead of `gsd-sdk` CLI, integration with the rest of the `dw-*` command surface.
 
 Source-driven development, code simplification, debugging discipline, and git workflow patterns adapted from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT) into the bundled `dw-source-grounding`, `dw-simplification`, `dw-debug-protocol`, and `dw-git-discipline` skills. Performance-optimization workflow (`vercel-react-best-practices/references/perf-discipline.md`) and API-design discipline (`dw-codebase-intel/references/api-design-discipline.md`) also incorporated as enhancements to existing bundled skills. Browser security-boundary and three-workflow-patterns (originally from `addyosmani/agent-skills/browser-devtools`) now live inside `dw-testing-discipline/references/`.
 

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];
@@ -39,12 +40,14 @@ const HELP_TEXT = `
   Commands:
     init                   Scaffold .dw/ (commands, templates, references, scripts, skills, rules, MCPs)
     update                 Update managed files (commands, templates, references, scripts, skills, wrappers, MCPs)
+                           and print post-update agent actions for project-derived docs/health checks
                            Preserves: .dw/rules/, .dw/spec/, .dw/bugfixes/, .dw/STATE.md, .agents/skills/azure/, user data
     list-installed         Show dev-workflow install state for this project
     doctor                 Check managed files, wrappers, agents, and MCP configuration
     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 +98,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/init.js

@@ -10,6 +10,7 @@ const { migrate: migrateSkills } = require('./migrate-skills');
 const { hasExistingInstall, readInstallState, writeInstallState, listManagedFiles } = require('./install-state');
 const { resolveInstallSelection } = require('./profiles');
 const { ensureSubtaskLayout } = require('./subtasks');
+const { printPostUpdateActions } = require('./post-update');
 
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
@@ -315,10 +316,19 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   console.log(`  ${'='.repeat(40)}`);
   console.log(`  Done! ${totalCreated} created, ${totalSkipped} skipped, ${totalOverwritten} overwritten`);
   console.log();
+  if (isUpdate) {
+    printPostUpdateActions(projectRoot);
+  }
   console.log('  Next steps:');
-  console.log('    1. Run /dw-analyze-project to generate project rules');
-  console.log('    2. Run /dw-brainstorm to start a new feature');
-  console.log('    3. Run /dw-help to see all available commands');
+  if (isUpdate) {
+    console.log('    1. If running inside an agent, run the post-update actions now');
+    console.log('    2. Otherwise reload/restart the agent session before invoking them');
+    console.log('    3. Run /dw-help to see all available commands');
+  } else {
+    console.log('    1. Run /dw-analyze-project to generate project rules');
+    console.log('    2. Run /dw-brainstorm to start a new feature');
+    console.log('    3. Run /dw-help to see all available commands');
+  }
   console.log();
 }
 

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/migrate-gsd.js

@@ -124,7 +124,7 @@ function migrate(projectRoot) {
   if (stats.agents_removed) console.log(`    - .claude/agents/gsd-*.md      (${stats.agents_removed} files removed; native dw-* agents bundled in skills)`);
   if (stats.hooks_removed) console.log(`    - .claude/hooks/gsd-*.js       (${stats.hooks_removed} files removed; not used by dev-workflow)`);
   if (stats.manifest_removed) console.log('    - .claude/gsd-file-manifest.json (removed)');
-  console.log('  Done. Native /dw-intel, /dw-map-codebase, /dw-run-plan (with bundled phase-execution agents) now provide what GSD provided.');
+  console.log('  Done. Native /dw-intel, /dw-intel --build, and /dw-run (with bundled phase-execution agents) now provide what GSD provided.');
   console.log();
 
   return stats;

package/lib/post-update.js

@@ -0,0 +1,153 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKIP_DIRS = new Set([
+  '.git',
+  '.dw',
+  '.agents',
+  '.claude',
+  '.codex',
+  '.github',
+  '.opencode',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  'out',
+]);
+
+const FRONTEND_DEPS = [
+  '@angular/core',
+  '@remix-run/react',
+  'astro',
+  'next',
+  'nuxt',
+  'react',
+  'solid-js',
+  'svelte',
+  'vue',
+];
+
+function listPostUpdateActions(projectRoot) {
+  const actions = [];
+  const analysisReasons = [];
+
+  if (!exists(projectRoot, '.dw/rules/index.md')) {
+    analysisReasons.push('missing .dw/rules/index.md');
+  }
+  if (!exists(projectRoot, '.dw/rules/concerns.md')) {
+    analysisReasons.push('missing .dw/rules/concerns.md');
+  }
+  if (!exists(projectRoot, '.dw/constitution.md')) {
+    analysisReasons.push('missing .dw/constitution.md');
+  }
+
+  const frontendProjects = findFrontendProjects(projectRoot);
+  const missingDesignAuthority = frontendProjects.filter((dir) => !hasDesignAuthority(dir));
+  if (missingDesignAuthority.length) {
+    analysisReasons.push(
+      `frontend design authority missing for ${formatPaths(projectRoot, missingDesignAuthority)}`,
+    );
+  }
+
+  if (analysisReasons.length) {
+    actions.push({
+      command: '/dw-analyze-project',
+      reason: `refresh project-derived docs (${analysisReasons.join('; ')})`,
+    });
+  }
+
+  if (!hasCodebaseIntel(projectRoot)) {
+    actions.push({
+      command: '/dw-intel --build',
+      reason: 'build .dw/intel/ codebase index for the refreshed command surface',
+    });
+  }
+
+  actions.push({
+    command: '/dw-harness-audit',
+    reason: 'validate commands, wrappers, agents, MCPs, and gates after update',
+  });
+  actions.push({
+    command: '/dw-skill-health',
+    reason: 'audit refreshed bundled skills and agents for bloat, duplication, and stale references',
+  });
+
+  return actions;
+}
+
+function printPostUpdateActions(projectRoot) {
+  const actions = listPostUpdateActions(projectRoot);
+  console.log('  Post-update agent actions:');
+  console.log('    The CLI refreshed managed files. Project-derived docs require the agent to run commands:');
+  for (const action of actions) {
+    console.log(`    - ${action.command} - ${action.reason}`);
+  }
+  console.log('    /dw-update consumes this list and runs the applicable commands after the update.');
+  console.log();
+}
+
+function hasCodebaseIntel(projectRoot) {
+  return ['.dw/intel/stack.json', '.dw/intel/files.json', '.dw/intel/arch.md'].every((rel) =>
+    exists(projectRoot, rel),
+  );
+}
+
+function findFrontendProjects(projectRoot) {
+  const projects = [];
+  walk(projectRoot, (dir) => {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {}),
+      };
+      if (FRONTEND_DEPS.some((dep) => Object.prototype.hasOwnProperty.call(deps, dep))) {
+        projects.push(dir);
+      }
+    } catch {
+      // Ignore malformed package.json here; doctor handles managed-file validation.
+    }
+  });
+  return projects;
+}
+
+function walk(dir, visit) {
+  if (!fs.existsSync(dir)) return;
+  visit(dir);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+    walk(path.join(dir, entry.name), visit);
+  }
+}
+
+function hasDesignAuthority(projectDir) {
+  return ['DESIGN.md', 'BRAND.md', 'STYLE_GUIDE.md'].some((name) =>
+    fs.existsSync(path.join(projectDir, name)),
+  );
+}
+
+function exists(projectRoot, relativePath) {
+  return fs.existsSync(path.join(projectRoot, relativePath));
+}
+
+function formatPaths(projectRoot, dirs) {
+  const formatted = dirs.slice(0, 3).map((dir) => path.relative(projectRoot, dir) || '.');
+  if (dirs.length > formatted.length) formatted.push(`+${dirs.length - formatted.length} more`);
+  return formatted.join(', ');
+}
+
+module.exports = {
+  listPostUpdateActions,
+  printPostUpdateActions,
+};