@brunosps00/dev-workflow 2.3.0 → 2.5.0

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -10,6 +10,161 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.5.0] — 2026-09-28
+
+### Added
+
+- **`/dw-quality-gate` — a measured quality gate on new code.** SonarQube's "Clean as You
+  Code" idea without a server: the diff's new code is measured for complexity, duplication,
+  new lint issues and coverage of changed lines, and each changed file is compared with its
+  own merge-base version measured by the same engine. Only what the diff introduces or makes
+  worse blocks; pre-existing debt a diff merely touches is advisory. Verdicts are `APPROVED`,
+  `APPROVED WITH CAVEATS`, `REJECTED` and `UNMEASURED` (no complexity engine ran, which
+  blocks: complexity is the one required layer).
+  - Engines are layered like the Security Gate: qlty for cognitive complexity with lizard as
+    fallback, jscpd over the whole source tree for duplication, qlty check or the project's
+    own lint, and the project's own coverage report. A missing engine degrades one layer.
+  - A diff never configures its own gate: `.dw/quality/gate.json` (thresholds, `exclude`,
+    waivers), `.qlty/qlty.toml`, the linter's config and ignore files, `.jscpd.json`, and the
+    lint and coverage commands are read from the base branch (a changed file is swapped for
+    its base version during measurement and restored byte for byte), and a diff that loosens them alongside code is a blocking `config-loosening`
+    finding. A configuration-only PR (gate.json, qlty.toml, ADRs) is the sanctioned route:
+    its loosening is listed for the owner's review instead of blocking.
+  - Blanket or file-wide suppressions added by the diff block; a suppression that names the
+    rule and gives a checkable reason is advisory. Coverage exclusions follow the same rule
+    when a coverage threshold is set.
+  - Complexity is the one required layer. lizard (cyclomatic, blind to nesting) is only the
+    engine for languages qlty cannot parse; a qlty-supported file measured without qlty is
+    `UNMEASURED`.
+  - New code is measured against the working tree, including untracked files, so
+    uncommitted `/dw-run` output counts; duplication
+    scans every tracked source file with `--min-lines 0`, since jscpd otherwise drops dense
+    clones on fewer than five lines.
+  - Refutation can reject a blocking candidate only for named reasons (generated code, flat
+    enum switch, engine mis-parse, required boilerplate); an unsure refutation leaves the
+    finding standing. Waivers need a reason, an existing ADR for HIGH rules, and may cap the
+    value with `max`.
+  - Coverage never blocks without a project threshold (`coverage.newCode`); with one, a
+    missing report fails the layer instead of skipping it.
+- **`/dw-quality-gate --full`** — a complete, advisory project report: complexity
+  distribution, worst functions, duplication by language and directory, lint, coverage,
+  hotspots (churn × complexity), trend against the previous report and the baseline, and a
+  prioritized debt backlog routed to `/dw-refactor`, tests or lint fixes.
+  `--update-baseline` writes `.dw/quality/baseline.json` from the same measurement on the
+  base branch.
+- **`install-deps` installs the quality engines** instead of only printing instructions:
+  qlty from its pinned GitHub release with the SHA-256 verified, lizard into a private venv
+  (sidestepping PEP 668), and a warmed npx cache for jscpd — all under `~/.dw`, never inside
+  a project and without editing the shell profile.
+- **`/dw-analyze-project` Step 5.2** runs `/dw-quality-gate --full --no-write-config` (or
+  `--update-baseline` on the base branch), cites the measured values in the anti-patterns and
+  the concerns map, and records a `## Quality Baseline` in `.dw/rules/index.md`.
+  `--no-write-config` keeps that documentation-only command from writing `.qlty/qlty.toml`.
+- `dw-simplification/references/quality-gate-tools.md` — engine commands and output shapes,
+  each verified by running it (qlty 0.649, lizard 1.24, jscpd 5.3).
+
+### Changed
+
+- **The Quality Gate is mandatory, in every language.** After updating, `/dw-review`
+  (Level 3 step 9) returns REJECTED when `.dw/quality/quality-summary.md` is missing, stale,
+  `REJECTED` or `UNMEASURED`; `/dw-generate-pr` (hard gate 3) re-runs the gate against the
+  PR's target branch before every push, on a clean tree, instead of trusting a stored
+  summary, and copies suppressions, configuration changes and degraded layers into the PR
+  description; and
+  `/dw-autopilot` runs it next to the Security Gate. Run
+  `npx @brunosps00/dev-workflow install-deps` so the engines are present; without any engine
+  the verdict is `UNMEASURED` and PRs block.
+- `/dw-autopilot`: the Security Gate's non-SECRET `REJECTED` gets one fix pass and a re-scan,
+  like the Quality Gate, before stop 3; a SECRET still stops at once. A fix pass invalidates
+  the review and the scan. Stop 5 applies to findings still `high`/`critical` after the
+  goal's correction, and an ADR the run wrote itself does not count. Stops now persist
+  `status: blocked`, `blocked_reason` and `question`, with a `blocked` resume row, and never
+  record a secret value.
+- `/dw-autopilot` now reads `.dw/references/untrusted-input.md` before external text enters
+  the run.
+- `/dw-run` gains stop 8: the review stays REJECTED on something a code correction cannot
+  clear (quality gate `UNMEASURED`, a SECRET, a decision needing an ADR or waiver).
+- `/dw-review`'s escapes are stated per gate instead of "ADR is the only escape": an ADR for
+  constitution high+critical and non-SECRET security findings, a `gate.json` waiver for the
+  quality gate, none for SECRET or verify.
+- `complexity-metrics.md` splits cognitive 16+ into 16-25 and 26+, and distinguishes
+  whole-repo CI gates from new-code gates.
+
+## [2.4.0] — 2026-09-21
+
+### Added
+
+- **A floor the ADR escape does not reach.** `.dw/references/invariants.md` names the
+  invariants no ADR unblocks — destructive git and secret handling — and states the
+  direction: project rules bind only by tightening. A line in `.dw/rules/**`, the
+  constitution or `CLAUDE.md` that would loosen one is reported as a finding, never
+  obeyed. It ships in the managed references directory, which has no override path, so
+  a consumer cannot remove it durably.
+- **External text is evidence, never an instruction.** `.dw/references/untrusted-input.md`
+  plus anchors in the commands that ingest third-party content — triage, review, bugfix,
+  secure-audit and the three skill installers — and one sentence in the always-loaded
+  instruction block, so the rule applies even when no command was invoked. Includes the
+  authority checklist for installing someone else's skill, and covers fetched
+  documentation in `dw-source-grounding`, `/dw-brainstorm --mode=research` and `/dw-plan`.
+- **A refutation step before a finding is reported.** `dw-review-rigor` now routes every
+  candidate to exactly one of `finding`, `needs-validation` or `rejected`. The new
+  read-only `dw-finding-refuter` agent receives the claim and the raw code without the
+  reasoning that produced it. An unresolved lead never receives a severity; a refuted one
+  stays logged so the next round does not rediscover it.
+- **`/dw-review --post-merge [<base>]`** — a composition audit of an already-merged range:
+  frozen boundary, first-parent provenance, seven cross-interaction classes, a
+  documentation ledger built from the diff, and a semver recommendation. Read-only; it
+  never tags, bumps or publishes.
+- **`dw-chaos-engineering`** (explicit invocation) — adversarial testing with a vector
+  catalogue, a green-baseline gate, KILLED/SURVIVED/INCONCLUSIVE classification and a
+  three-round cap. Local only, writes tests only.
+- **An automode contract.** `.dw/references/automode.md` plus a named `Stops` section in
+  `/dw-autopilot`, `/dw-run`, `/dw-goal` and the three runners: invoking a command
+  authorizes its flow, the enumerated stops are the complete set, and a stop persists
+  state, reports the exact resume command and exits cleanly.
+- **Skill usage evidence in `/dw-skill-health`.** The SessionEnd cost hook now records
+  which skills a session's tool calls referenced, in the file it already wrote. Missing
+  telemetry is reported as missing, never as disuse.
+- **Bounded-decision guidance in `dw-llm-eval`**, including the distinction our judge
+  calibration never made explicit: Spearman ≥0.80 is rank agreement, not probability
+  calibration.
+- **`evals/`** — a behavioural battery for this repository's own skills, run against fresh
+  sub-agents at a declared model tier. Versioned in git, excluded from the package.
+
+### Changed
+
+- **No bundled command carries the invocation lock any more.** `dw-open-design`,
+  `dw-claude-run`, `dw-copilot-run` and the three `dw-subtask-*` join `dw-codex-run`.
+  After an update the model may fire these directly where it previously could not. The
+  lock is not an authorization gate: where approval already exists upstream it only made
+  the user retype a command they had authorized. The runners' real gates are unchanged —
+  dedicated worktree, never the main checkout, never a merge, dual evaluation and the STOP
+  at the gate.
+- `security-review`'s fp-check gains a third verdict: reachability that cannot be
+  established either way is `needs-validation`, with no severity, rather than drifting into
+  blocking or advisory.
+- A candidate whose deciding environment is unavailable stays unresolved instead of being
+  promoted or dropped.
+
+### Fixed
+
+- `dw-review-rigor` pointed prior-round awareness at `.dw/spec/prd-*/reviews/`, a directory
+  no command has ever written. Reviews live in `<target>/QA/` and `<target>/review/`.
+- `<AUDIT>` was referenced nine times across the runners without ever being resolved. It is
+  `.dw/cli-run`, which `init` has been creating all along.
+- `autopilot-state.json` had no directory anywhere in the repository. It is
+  `.dw/autopilot-state.json`.
+- The constitution installer printed "All 10 principles start at `severity: info`". The
+  template has eleven, and two ship at `high`.
+- `security-review` appeared twice in `/dw-review`'s complementary skills.
+- The git guardrails hook now also denies `filter-branch`, `reflog expire`, `gc --prune`,
+  `stash drop`, `stash clear`, `branch -M` and `update-ref -d`. `rebase` and
+  `commit --amend` are deliberately left out — routine on unpushed work, and a command line
+  cannot tell pushed from unpushed.
+- The ecosystem comparison's title and attribution chain: the adversarial-verification
+  model originates in `cloudflare/security-audit-skill` (MIT) and reached this project
+  through `akitaonrails/my-skills`.
+
 ## [2.3.0] — 2026-09-09
 
 ### Added

package/README.md

@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.3.0 ships **41 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v2.3.0 ships **42 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (4)
 
@@ -63,7 +63,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-brainstorm "idea"`** | Refine a concrete idea before PRD. Flags: `--onepager` (durable artifact), `--council` (multi-advisor debate), `--research` (multi-source cited research). |
 | **`/dw-plan "feature"`** | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. Mandatory clarification questions, source-grounding, constitution gate, final consistency check. |
 | **`/dw-run [task-id]`** | Execute tasks. Default: all pending in dependency order with wave-based parallel dispatch. Single-task: pass an ID. `--resume` continues an interrupted plan. |
-| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`), `--since <ref>` (ad-hoc review from a verified comparison point). |
+| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Every candidate finding passes a refutation step before it is reported; an unresolved lead becomes `needs-validation` with no severity, and a refuted one stays logged. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`), `--since <ref>` (ad-hoc review from a verified comparison point), `--post-merge [<base>]` (composition audit of an already-merged range — cross-PR interaction, documentation ledger, semver recommendation; never tags or publishes). |
 | **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (AI eval against reference dataset), `--uat` (human-in-the-loop walkthrough), `--bugfix <slug>` (QA a bugfix). |
 | **`/dw-pause`** | Consolidate the current session's mental state into `.dw/STATE.md` (Decisions, Blockers, Todos, Deferred, Lessons, Open Loops). Used before long breaks or context-window compactions. |
 | **`/dw-resume`** | Read `.dw/STATE.md`, present a TLDR of where work left off, and suggest the next `dw-*` command. Never auto-executes. |
@@ -82,7 +82,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/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. |
+| **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references, plus usage evidence: which installed skills have not fired inside a declared, observed window. Missing telemetry is reported as missing, never as disuse. |
 | **`/dw-worktree <list\|create\|clean\|merge>`** | Lifecycle of delegation worktrees (`../<project>-<slug>`): `create` runs install/build prep so a delegate never works blind; `list` gives every worktree a verdict (`REMOVABLE`, `KEEP:unmerged`, `KEEP:dirty`, `KEEP:in-use`); `clean` removes only proven-merged-and-clean ones (dry-run by default, `--apply` to execute); `merge` does the safe order from the main checkout (ff-only → remove → branch delete → prune). Never `--force`. Backed by `.dw/scripts/lib/worktree-gc.mjs`; auto-used by the CLI runners, `/dw-pause`, and `/dw-harness-audit`. |
 | **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
 | **`/dw-new-project`** | Bootstrap a new project from an empty or docs-first directory while preserving existing documentation and prototypes. Stack interview includes Next.js + NestJS, Postgres, pg-boss, Mailpit, dev topology, and wraps official `create-*` tools before composing dev infrastructure, `.env`, scripts, CI, and `.dw/rules/`. |
@@ -90,7 +90,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-install-azure-skills`** | **Opt-in.** Clones curated Azure skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0) into `.agents/skills/azure/` and registers the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP, no-auth). Interactive category selection (Compute / Data & Storage / AI & ML / Networking / Identity & Security / DevOps / Observability / Integration / Architecture / All). Re-run to refresh from upstream. Also available as CLI: `npx @brunosps00/dev-workflow install-azure-skills`. |
 | **`/dw-install-aws-skills`** | **Opt-in.** Clones curated AWS skills from [`aws/agent-toolkit-for-aws`](https://github.com/aws/agent-toolkit-for-aws) (Apache 2.0) into `.agents/skills/aws/` and registers the unified [AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/) (stdio via `uvx mcp-proxy-for-aws@latest`). **Requires `uv`, `aws cli ≥ 2.32.0`, and AWS credentials.** Interactive category selection (Core / Analytics / Database / EC2 / Migration / Networking / Operations / Security / Serverless / Storage / All). The agent gains `aws___call_aws` (executes 15,000+ AWS APIs) and `aws___run_script` (Python sandboxed) — review `.dw/references/aws-mcp-instructions.md` for the destructive-operations protocol. Also available as CLI: `npx @brunosps00/dev-workflow install-aws-skills [--region=<aws-region>]`. |
 
-### Tier 4 — Hidden/Internal (12)
+### Tier 4 — Hidden/Internal (13)
 
 These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help --advanced`.
 
@@ -99,10 +99,11 @@ 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`** | **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-quality-gate`** | **Quality Gate** (measured, SonarQube-style "Clean as You Code" without a server): complexity, duplication, new lint issues and coverage of the diff's new code, each changed file compared with its merge-base version; thresholds come from the base branch, so a PR cannot loosen its own gate. qlty (or lizard) for complexity, jscpd for duplication; no complexity engine = `UNMEASURED`, which blocks. Pre-existing debt never blocks. `--full` writes a complete project report (distributions, hotspots, trend, prioritized debt backlog). Flags: `--since`, `--full`, `--update-baseline`, `--scan-only`. | `/dw-review`, `/dw-autopilot` (next to the Security Gate), 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-claude-run`** | Fire `claude -p` (headless) in a dedicated git worktree to implement a prepared prompt/spec. Claude adapter over the `dw-cli-run` protocol: durable audit log, resumable session via `--session-id`, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | manual delegation step |
-| **`/dw-codex-run`** | Fire `codex exec` in a dedicated git worktree to implement a prepared prompt/spec. Codex adapter over the `dw-cli-run` protocol: durable audit log, resumable per-task session, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | manual delegation step |
-| **`/dw-copilot-run`** | Fire `copilot -p` (GitHub Copilot CLI) in a dedicated git worktree to implement a prepared prompt/spec. Copilot adapter over the `dw-cli-run` protocol: durable audit log, resumable session, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | manual delegation step |
+| **`/dw-claude-run`** | Fire `claude -p` (headless) in a dedicated git worktree to implement a prepared prompt/spec. Claude adapter over the `dw-cli-run` protocol: durable audit log, resumable session via `--session-id`, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
+| **`/dw-codex-run`** | Fire `codex exec` in a dedicated git worktree to implement a prepared prompt/spec. Codex adapter over the `dw-cli-run` protocol: durable audit log, resumable per-task session, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
+| **`/dw-copilot-run`** | Fire `copilot -p` (GitHub Copilot CLI) in a dedicated git worktree to implement a prepared prompt/spec. Copilot adapter over the `dw-cli-run` protocol: durable audit log, resumable session, 0–10 dual evaluation, STOP for the gate. Never the main checkout; never merges. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
 | **`/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 |
 | **`/dw-subtask-start`** | Creates a minimal input packet for a subagent without injecting the parent transcript. | parent agent before delegation |
@@ -113,17 +114,17 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 
 ```
 /dw-autopilot "wish"  ------>  PRD → TechSpec → Tasks + execution assignments → approval
-                             → /dw-goal → Security Gate → validated delivery → authorized publication
+                             → /dw-goal → Security Gate + Quality Gate → validated delivery → authorized publication
     --- OR step-by-step ---
 
 /dw-opportunities --> /dw-brainstorm --> /dw-plan --> .dw/spec/prd-{name}/{prd,techspec,tasks}.md
                           |
-                    /dw-goal             -->  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit
+                    /dw-goal             -->  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit → /dw-quality-gate
                           |
                     /dw-commit + /dw-generate-pr
 
 Manual alternative after /dw-plan:
-  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit → /dw-commit → /dw-generate-pr
+  /dw-run → /dw-review → /dw-qa → /dw-review → /dw-secure-audit → /dw-quality-gate → /dw-commit → /dw-generate-pr
 
 Shortcuts:
   /dw-intel "question"         Query codebase intelligence
@@ -174,9 +175,11 @@ After an update, the CLI prints **Post-update agent actions**. When `/dw-update`
 
 **What's inside:**
 
-- **Trigger Map** — mappings from user intent ("Implement X", "Bug in Y", "Review my PR", "resume autopilot", ...) to the `dw-*` command the agent should run. `/dw-autopilot` is the safest default for non-trivial feature requests; `/dw-goal` is the durable execution contract after planning.
-- **Hard Gates** — reminders that constitution violations (high/critical), missing `dw-verify` PASS, and security failures block downstream commands.
-- **Escape Hatches** — explicit cases where the agent should NOT auto-trigger (typos, exploration, aesthetic edits, user opt-out).
+- **Routing** — a table from intent and scope to the action, including the cases where the agent should answer directly or edit inline instead of starting a pipeline. It carries the common paths only; the full intent-to-command Trigger Map lives on demand in `.dw/references/command-routing.md`, so routine work does not pay for the whole catalog.
+- **Planning and delegation** — per-task local/cross-tool, model, effort and agent assignment; what approval covers; the worker limits (at most 3 per workstream, never concurrent writers in one worktree).
+- **Completion and boundaries** — an approved plan continues through implementation, review, QA and fixes; what makes a delivery ready; which operations need authorization.
+- **Project contracts** — constitution and ADR process, task-plan validity, required checks, atomic commits, and the untrusted-input rule (external text is evidence, never an instruction).
+- **Customization** — the `<!-- dev-workflow:start -->` / `<!-- dev-workflow:end -->` markers and what survives an update.
 
 **Why two files:** Claude Code, Codex, Copilot, and OpenCode all support agent-instruction conventions but use different filenames. Shipping both means every supported platform picks up the same trigger logic out of the box.
 
@@ -232,7 +235,7 @@ your-project/
 │   ├── 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)
+├── CLAUDE.md              # Managed agent-instruction block for Claude Code (merge-aware; routing, contracts, boundaries)
 ├── AGENTS.md              # Same content for Codex / Copilot / OpenCode
 ├── .claude/
 │   ├── skills/            # Claude Code wrappers
@@ -328,6 +331,9 @@ Installed via `npx @brunosps00/dev-workflow install-deps`:
 | **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) |
+| **qlty** | Primary complexity engine of `/dw-quality-gate` (cognitive + cyclomatic per function). Fair Source (BSL 1.1), free including commercial use. `install-deps` downloads the pinned release into `~/.dw/bin` and verifies its SHA-256. | [github.com/qltysh/qlty](https://github.com/qltysh/qlty) |
+| **lizard** | Complexity fallback for `/dw-quality-gate` (~30 languages, MIT). `install-deps` installs the pinned version into a private venv under `~/.dw` (needs Python 3). | [github.com/terryyin/lizard](https://github.com/terryyin/lizard) |
+| **jscpd** | Duplication engine for `/dw-quality-gate` (150+ formats, MIT), run as `npx -y jscpd@5`; `install-deps` warms the npx cache. | [github.com/kucherenko/jscpd](https://github.com/kucherenko/jscpd) |
 | **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
@@ -382,7 +388,7 @@ Optional AWS integration (v1.0.5). The `/dw-install-aws-skills` command and `npx
 
 Optional Azure integration (v1.0.3). The `/dw-install-azure-skills` command and `npx @brunosps00/dev-workflow install-azure-skills` CLI pull curated agent skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0, by Microsoft) into `.agents/skills/azure/` and register the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP endpoint, no authentication required) into `.claude/settings.json`. The MCP server exposes three tools — `microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search` — that give the agent live access to Microsoft Learn documentation. **Not installed by default**: `init` and `update` do not touch `.agents/skills/azure/` or register the MCP. Users explicitly invoke the command when they begin Azure-focused work. The 10 categories (Compute, Data & Storage, AI & ML, Networking, Identity & Security, DevOps, Observability, Integration, Architecture, All) are dev-workflow's curated grouping over the 200+ skills in the upstream repo; the `--products=<csv>` flag lets advanced users pick individual services. Re-running the command refreshes from upstream; `dev-workflow update` deliberately does not touch these external skills so the Microsoft upstream release cadence is decoupled from the dev-workflow npm release cadence. Skills are copied verbatim from the upstream repo (CC-BY-4.0 permits this with attribution); the agent-facing `.dw/references/azure-mcp-instructions.md` is a clean-room adaptation of Microsoft's "Set instructions" guidance.
 
-Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex) formalized in `CLAUDE.md`/`AGENTS.md` above the Trigger Map; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
+Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex), formalized in `CLAUDE.md`/`AGENTS.md` at the time and **since removed** — the managed block now routes on intent and scope instead of a size bracket, and the fixed matrix was dropped when the block was compacted; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
 
 Patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding any new public command** (the public command count is unchanged): (1) **grill** — a native, stateful alignment session reimplemented (clean-room, no upstream prose copied) from [`skills/engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md), [`skills/productivity/grilling`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), and [`skills/engineering/domain-modeling`](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md). It is the `/dw-brainstorm` `grill` mode, backed by two **internal, non-exported** bundled skills — `dw-grilling` (dependency-ordered decision-tree interview, one decision per turn with a recommended answer, facts looked up rather than asked, shared-understanding gate) and `dw-domain-modeling` (canonical glossary, fuzzy/overloaded-term challenge, rare ADRs). Intentional `.dw/` differences: the curated glossary lives in **`.dw/domain/**`** (not upstream's root `CONTEXT.md`, and not our auto-generated `.dw/rules/`); Grill requires **one explicit authorization** before it writes and is mutually exclusive with the option matrix; alignment emits an idea one-pager at **schema `1.1`** consumed by `/dw-plan` without re-asking; and ADR creation is gated on the 3-criteria test and routed via `/dw-adr --scope=repo|prd`. (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same line of work also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
 
@@ -435,7 +441,7 @@ On the next `npx @brunosps00/dev-workflow update`, the following happens automat
 
 ### CLAUDE.md / AGENTS.md updates
 
-The Trigger Map block (between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->`) refreshes automatically on update with the v1.0.0 command surface. Your edits outside the markers are preserved.
+The managed instruction block (between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->`) refreshes automatically on update with the v1.0.0 command surface. Your edits outside the markers are preserved.
 
 ### Skill conventions
 

package/bin/dev-workflow.js

@@ -46,7 +46,7 @@ const HELP_TEXT = `
     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)
+    install-deps           Install system dependencies (Playwright browsers, MCP servers, quality-gate engines)
     setup-wsl-browser      (WSL) Install the optional user-level CDP fallback relay for the real Windows browser without admin
     install-azure-skills   Opt-in: clone curated Azure skills from MicrosoftDocs/Agent-Skills
                            into .agents/skills/azure/ and register the Microsoft Learn MCP

package/lib/constants.js

@@ -5,10 +5,10 @@ const COMMANDS = {
     { name: 'dw-autopilot', description: 'Plan a multi-component implementation, approve task execution assignments, then continue through implementation, review and validation.' },
     { name: 'dw-brainstorm', description: 'Explore unresolved product or architecture choices for a concrete idea; use grill for stateful alignment, research for unknowns, or council for competing approaches.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Run an approved task through Claude CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Run an approved task through Codex CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
+    { name: 'dw-claude-run', description: 'Run an approved task through Claude CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
+    { name: 'dw-codex-run', description: 'Run an approved task through Codex CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Run an approved task through Copilot CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
+    { name: 'dw-copilot-run', description: 'Run an approved task through Copilot CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-dockerize', description: 'Reads a project, detects the stack and runtime deps, then proposes Dockerfile and docker-compose for dev and prod with explicit trade-offs.' },
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
@@ -22,22 +22,23 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Generate or iterate Open Design HTML prototypes through the od CLI, including screenshot-based redesign and visual verification.' },
+    { name: 'dw-open-design', description: 'Generate or iterate Open Design HTML prototypes through the od CLI, including screenshot-based redesign and visual verification.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
     { name: 'dw-plan', description: 'Produce PRD, architecture and tasks, with local/cross-tool executor, model, effort and agent proposals by task complexity.' },
     { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai / --uat). --fix enters the iterative QA + fix-retest loop. --bugfix <slug> targets a .dw/bugfixes/ entry.' },
+    { name: 'dw-quality-gate', description: 'Measure the new code of a diff (complexity, duplication, lint, coverage) with local engines against a versioned baseline; block what the diff introduces or worsens.' },
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
     { name: 'dw-refactor', description: 'Audits a target for refactor opportunities using the refactor-audit protocol, Fowler smells, deep-modules analysis, and behavior-preserving test gates.' },
     { name: 'dw-report', description: 'Report progress periodically during authorized long-running work; persist updates and stop reporting when the work ends.' },
     { name: 'dw-resume', description: 'Trigger when user says "resume work", "where did we stop?", or starts a session in a project with an existing .dw/STATE.md. Reads STATE.md, presents a TLDR, and suggests the next dw-* command.' },
-    { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
+    { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref> / --post-merge <base>.' },
     { 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: 'Audit relevant code and dependencies for security findings using available scanners; validate exploitability and enforce blocking findings.' },
-    { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
-    { name: 'dw-subtask-start', userInvoked: true, description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
-    { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
-    { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
+    { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale modules; reports usage evidence so an idle skill is named with its observed window, never guessed.' },
+    { 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.' },
+    { name: 'dw-subtask-resume', description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-triage', description: 'Local-first intake for external bug reports, feature requests, and PRs. Persists .dw/triage/ state, checks redundancy and prior rejections, verifies claims, then routes to /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, or no work.' },
     { name: 'dw-worktree', description: 'Create prepared worktrees, inspect their state, clean safely merged worktrees, or integrate an explicitly authorized branch.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
@@ -48,10 +49,10 @@ const COMMANDS = {
     { name: 'dw-autopilot', description: 'Planeja implementação multicomponente, aprova escolhas de execução por task e continua por implementação, review e validação.' },
     { name: 'dw-brainstorm', description: 'Explora escolhas pendentes de produto ou arquitetura; grill para alinhamento com estado, pesquisa para lacunas e council para alternativas concorrentes.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Executa task aprovada pela CLI Claude em worktree dedicado; retorna sessão durável e evidências ao parent.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Executa task aprovada pela CLI Codex em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-claude-run', description: 'Executa task aprovada pela CLI Claude em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-codex-run', description: 'Executa task aprovada pela CLI Codex em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Executa task aprovada pela CLI Copilot em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-copilot-run', description: 'Executa task aprovada pela CLI Copilot em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-dockerize', description: 'Le um projeto, detecta stack e deps de runtime, e propoe Dockerfile e docker-compose para dev e prod com trade-offs explicitos.' },
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
@@ -65,22 +66,23 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Gera ou itera protótipos HTML Open Design pela CLI od, incluindo redesign por screenshots e verificação visual.' },
+    { name: 'dw-open-design', description: 'Gera ou itera protótipos HTML Open Design pela CLI od, incluindo redesign por screenshots e verificação visual.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
     { name: 'dw-plan', description: 'Produz PRD, arquitetura e tasks com propostas de executor local/cruzado, modelo, esforço e agentes por complexidade.' },
     { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai / --uat). --fix entra no loop iterativo QA + fix-retest. --bugfix <slug> aponta para uma entrada em .dw/bugfixes/.' },
+    { name: 'dw-quality-gate', description: 'Mede o código novo de um diff (complexidade, duplicação, lint, cobertura) com engines locais contra um baseline versionado; bloqueia o que o diff introduz ou piora.' },
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
     { name: 'dw-refactor', description: 'Audita um target por oportunidades de refactor usando o protocolo refactor-audit, smells Fowler, deep-modules e gates de teste preservando comportamento.' },
     { name: 'dw-report', description: 'Reporta progresso periódico durante trabalho longo autorizado; persiste atualizações e encerra quando o trabalho termina.' },
     { name: 'dw-resume', description: 'Trigger quando usuario diz "retoma", "onde paramos?" ou comeca sessao num projeto com .dw/STATE.md existente. Le STATE.md, apresenta TLDR e sugere proximo comando dw-*.' },
-    { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
+    { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref> / --post-merge <base>.' },
     { 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: 'Audita código e dependências relevantes com scanners disponíveis; valida explorabilidade e aplica achados bloqueantes.' },
-    { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
-    { name: 'dw-subtask-start', userInvoked: true, description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
-    { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
-    { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
+    { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos velhos; reporta evidencia de uso, nomeando skill ociosa com a janela observada em vez de chutar.' },
+    { 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.' },
+    { name: 'dw-subtask-resume', description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
     { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos.' },
     { name: 'dw-worktree', description: 'Cria worktrees preparados, inspeciona estado, limpa worktrees integrados com segurança ou integra branch explicitamente autorizada.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
@@ -91,8 +93,11 @@ const PLATFORMS = {
   claude: {
     dir: '.claude/skills',
     // opts.userInvoked → emit disable-model-invocation: true so Claude Code never
-    // auto-fires hidden/internal commands (e.g. the worktree runners); the user
-    // still invokes them explicitly with /<name>.
+    // auto-fires that command; the user invokes it explicitly with /<name>.
+    // No bundled command sets this today (see docs/skills-ecosystem-comparison.md §2:
+    // the lock is not a substitute for an authorization gate). It is kept for a
+    // consumer's own commands, and test/wrappers.test.js exercises it directly so the
+    // path cannot rot unnoticed while unused.
     wrapperTemplate: (name, description, opts = {}) => `---
 name: ${name}
 description: "${description.replace(/"/g, '\\"')}"${opts.userInvoked ? '\ndisable-model-invocation: true' : ''}

package/lib/doctor.js

@@ -207,7 +207,7 @@ function checkMcp(projectRoot, issues) {
 
 function checkHooks(projectRoot, issues, warnings) {
   // Hook scripts (copied from scaffold/scripts/ into .dw/scripts/).
-  for (const script of ['git-guardrails.mjs', 'statusline.mjs']) {
+  for (const script of ['git-guardrails.mjs', 'statusline.mjs', 'session-cost.mjs']) {
     const file = path.join(projectRoot, '.dw', 'scripts', 'hooks', script);
     if (!fs.existsSync(file)) issues.push(`Missing hook script: ${path.relative(projectRoot, file)}`);
   }

package/lib/install-deps.js

@@ -1,5 +1,6 @@
 const { execSync } = require('child_process');
 const openDesign = require('./install-open-design');
+const qualityTools = require('./install-quality-tools');
 
 function run() {
   console.log('\n  dev-workflow install-deps');
@@ -72,6 +73,7 @@ function run() {
         '  Windows:  scoop install syft',
       ],
     },
+    ...qualityTools.deps,
     {
       name: 'Docker + Docker Compose',
       check: 'docker --version && (docker compose version || docker-compose --version)',
@@ -154,6 +156,7 @@ function run() {
   if (failed) parts.push(`${failed} failed`);
   console.log(`  Done! ${parts.join(', ')}`);
   console.log();
+  for (const line of qualityTools.pathHint()) console.log(`  ${line}`);
 
   checkPlaywrightVersion();
   printBrowserGuidance();