@brunosps00/dev-workflow 2.4.0 → 2.6.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.4.0",
+  "version": "2.6.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,115 @@ 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.6.0] — 2026-10-07
+
+### Added
+
+- **Git guardrails under Codex.** `init` and `update` also write the git-guardrails
+  `PreToolUse` hook to `.codex/hooks.json` — same payload and deny contract as Claude Code,
+  matcher `Bash`. It is the only hook Codex gets: the session-cost tracker parses Claude Code
+  transcripts and Codex has no statusLine command. Codex runs project hooks only after the
+  project and the hook are trusted. Merge-aware like the Claude side: a malformed
+  `.codex/hooks.json` is left untouched, and `uninstall` removes only our entry, deleting the
+  file when nothing else is left. `doctor` warns when the Codex guardrail is missing or
+  outdated.
+
+### Fixed
+
+- **Hooks stopped running whenever the shell left the project root.** The hook and statusLine
+  commands were cwd-relative (`node .dw/scripts/hooks/…`). Claude Code runs hooks in the
+  session's current directory, which follows every `cd`, so from any subdirectory they failed
+  with `Cannot find module` — and a failing `PreToolUse` hook is non-blocking, so Bash ran with
+  no git guardrail at all. In one real session, 843 of 1,243 Bash calls ran unguarded this way.
+  Commands now resolve `${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel || pwd)}`:
+  Claude Code exports the variable to hooks, and Codex, which exports none, gets the git root.
+  `update` rewrites the old entries in place, and `doctor` reports a cwd-relative guardrail as
+  an issue.
+- The statusline read `.dw/` state (active spec, minimalism mode, today's spend) from the
+  current directory. It now reads it from the payload's `workspace.project_dir`.
+- The guardrail's deny message pointed only at `.claude/settings.json`; it now names
+  `.codex/hooks.json` too, as does the invariants floor.
+
+## [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

package/README.md

@@ -16,7 +16,7 @@ This will:
 5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
 6. Generate skill wrappers and project agents for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
-8. Install enforcement hooks (git guardrails + a `SessionEnd` token-cost tracker → `.dw/metrics/costs.jsonl`) + a statusline (branch · active spec · minimalism mode · today's estimated spend) into `.claude/settings.json` (merge-aware — your own hooks/statusline are never overwritten)
+8. Install enforcement hooks (git guardrails + a `SessionEnd` token-cost tracker → `.dw/metrics/costs.jsonl`) + a statusline (branch · active spec · minimalism mode · today's estimated spend) into `.claude/settings.json`, and the git guardrails into `.codex/hooks.json` for Codex (merge-aware — your own hooks/statusline are never overwritten; Codex runs project hooks only after you trust them)
 
 > **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.
 
@@ -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)
 
@@ -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,6 +99,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`** | **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. | `/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 |
@@ -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
@@ -330,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

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

@@ -27,6 +27,7 @@ const COMMANDS = {
     { 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.' },
@@ -70,6 +71,7 @@ const COMMANDS = {
     { 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.' },

package/lib/doctor.js

@@ -10,7 +10,7 @@ const {
 } = require('./agents');
 const { readInstallState, STATE_RELATIVE_PATH } = require('./install-state');
 const { validateSkillRegistry, readSkillRegistry, validateSkillStructuredReturn } = require('./skill-registry');
-const { GIT_GUARDRAILS_CMD, STATUSLINE_CMD, HOOKS_DIR_MARKER } = require('./hooks');
+const { GIT_GUARDRAILS_SCRIPT, GIT_GUARDRAILS_CMD, STATUSLINE_CMD, HOOKS_DIR_MARKER, CODEX_HOOKS_FILE } = require('./hooks');
 const removedCommands = require('./removed-commands');
 
 function run() {
@@ -212,6 +212,8 @@ function checkHooks(projectRoot, issues, warnings) {
     if (!fs.existsSync(file)) issues.push(`Missing hook script: ${path.relative(projectRoot, file)}`);
   }
 
+  checkCodexHooks(projectRoot, warnings);
+
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
   if (!fs.existsSync(settingsPath)) return; // checkMcp already reports this
 
@@ -222,17 +224,52 @@ function checkHooks(projectRoot, issues, warnings) {
     return; // checkMcp already reports malformed settings
   }
 
-  const preToolUse = (settings.hooks && settings.hooks.PreToolUse) || [];
-  const guardrailWired = preToolUse.some(
-    (g) => g && Array.isArray(g.hooks) && g.hooks.some((h) => h && h.command === GIT_GUARDRAILS_CMD),
-  );
-  if (!guardrailWired) issues.push('Missing git-guardrails PreToolUse hook in .claude/settings.json');
+  const guardrailCommands = guardrailCommandsOf(settings);
+  if (guardrailCommands.length === 0) {
+    issues.push('Missing git-guardrails PreToolUse hook in .claude/settings.json');
+  } else if (!guardrailCommands.includes(GIT_GUARDRAILS_CMD)) {
+    // Pre-2.5.1 installs wired a cwd-relative path: it fails (non-blocking) and stops
+    // guarding as soon as the shell leaves the project root.
+    issues.push('Outdated git-guardrails PreToolUse hook in .claude/settings.json. Run `dev-workflow update`.');
+  }
 
   const statusLine = settings.statusLine;
+  const statusCommand = String((statusLine && statusLine.command) || '');
   if (!statusLine) {
     issues.push('Missing statusLine in .claude/settings.json');
-  } else if (statusLine.command !== STATUSLINE_CMD && !String(statusLine.command || '').includes(HOOKS_DIR_MARKER)) {
-    warnings.push('Custom statusLine set; dev-workflow statusline is not active (add `node .dw/scripts/hooks/statusline.mjs`).');
+  } else if (!statusCommand.includes(HOOKS_DIR_MARKER)) {
+    warnings.push(`Custom statusLine set; dev-workflow statusline is not active (add \`${STATUSLINE_CMD}\`).`);
+  } else if (statusCommand !== STATUSLINE_CMD) {
+    warnings.push('Outdated dev-workflow statusLine in .claude/settings.json. Run `dev-workflow update`.');
+  }
+}
+
+function guardrailCommandsOf(config) {
+  const preToolUse = (config && config.hooks && config.hooks.PreToolUse) || [];
+  return preToolUse.flatMap((g) =>
+    g && Array.isArray(g.hooks)
+      ? g.hooks.map((h) => h && h.command).filter((c) => typeof c === 'string' && c.includes(GIT_GUARDRAILS_SCRIPT))
+      : [],
+  );
+}
+
+// Codex is one of several supported agents, so a missing Codex guardrail is a
+// warning rather than an issue.
+function checkCodexHooks(projectRoot, warnings) {
+  const file = path.join(projectRoot, CODEX_HOOKS_FILE);
+  let commands = [];
+  if (fs.existsSync(file)) {
+    try {
+      commands = guardrailCommandsOf(JSON.parse(fs.readFileSync(file, 'utf-8')));
+    } catch {
+      warnings.push(`Malformed ${CODEX_HOOKS_FILE}; Codex cannot load the git guardrail.`);
+      return;
+    }
+  }
+  if (commands.length === 0) {
+    warnings.push(`Missing git-guardrails hook in ${CODEX_HOOKS_FILE} (Bash under Codex is unguarded). Run \`dev-workflow update\`.`);
+  } else if (!commands.includes(GIT_GUARDRAILS_CMD)) {
+    warnings.push(`Outdated git-guardrails hook in ${CODEX_HOOKS_FILE}. Run \`dev-workflow update\`.`);
   }
 }
 
@@ -245,4 +282,4 @@ function checkLegacyCommands(projectRoot, warnings) {
   }
 }
 
-module.exports = { run };
+module.exports = { run, checkHooks };

package/lib/hooks.js

@@ -1,14 +1,33 @@
+const fs = require('fs');
+const path = require('path');
 const { readSettings, writeSettings } = require('./mcp');
 
 // dev-workflow-owned hook/statusline scripts live under this path. The substring
-// is the marker used to identify OUR entries in .claude/settings.json so we can
-// add/refresh them on update without ever touching the user's own hooks.
+// is the marker used to identify OUR entries in .claude/settings.json and
+// .codex/hooks.json so we can add/refresh them on update without ever touching
+// the user's own hooks.
 const HOOKS_DIR_MARKER = '.dw/scripts/hooks/';
-const GIT_GUARDRAILS_CMD = 'node .dw/scripts/hooks/git-guardrails.mjs';
-const STATUSLINE_CMD = 'node .dw/scripts/hooks/statusline.mjs';
+
+// Hooks run in the session's *current* directory, which in Claude Code follows
+// every `cd` in the Bash tool. A cwd-relative `node .dw/...` breaks with "Cannot
+// find module" as soon as the shell sits in a subdirectory, and a failing
+// PreToolUse hook is non-blocking: the command runs unguarded. Claude Code exports
+// $CLAUDE_PROJECT_DIR to hooks; Codex exports no project variable, so fall back to
+// the git root (a worktree's own root), then to the cwd. The fallback is only
+// evaluated when the variable is unset.
+const PROJECT_ROOT = '${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}';
+const hookCommand = (script) => `node "${PROJECT_ROOT}/${HOOKS_DIR_MARKER}${script}"`;
+
+// Codex reads project hooks from .codex/hooks.json (same shape as Claude Code's
+// "hooks" block; PreToolUse matches tool_name "Bash"). It only runs them once the
+// project's .codex/ layer and the hook itself are trusted in Codex.
+const CODEX_HOOKS_FILE = path.join('.codex', 'hooks.json');
+
 const GIT_GUARDRAILS_SCRIPT = 'git-guardrails.mjs';
-const SESSION_COST_CMD = 'node .dw/scripts/hooks/session-cost.mjs';
+const GIT_GUARDRAILS_CMD = hookCommand(GIT_GUARDRAILS_SCRIPT);
+const STATUSLINE_CMD = hookCommand('statusline.mjs');
 const SESSION_COST_SCRIPT = 'session-cost.mjs';
+const SESSION_COST_CMD = hookCommand(SESSION_COST_SCRIPT);
 
 function isOurs(command) {
   return typeof command === 'string' && command.includes(HOOKS_DIR_MARKER);
@@ -25,8 +44,11 @@ function isOurs(command) {
  *  - leaves a user-defined statusLine untouched (reports it so the caller can
  *    surface a post-update note).
  *
- * Returns { hooks, statusLine } where each is 'added' | 'updated' | 'unchanged'
- * (statusLine may also be 'skipped-user').
+ * Also reconciles the git guardrail into .codex/hooks.json (see installCodexHooks).
+ *
+ * Returns { hooks, sessionCost, statusLine, codex } where each is 'added' |
+ * 'updated' | 'unchanged' (statusLine may also be 'skipped-user', codex
+ * 'skipped-malformed').
  */
 function installHooks(projectRoot) {
   const settings = readSettings(projectRoot);
@@ -40,7 +62,44 @@ function installHooks(projectRoot) {
     writeSettings(projectRoot, settings);
   }
 
-  return { hooks: hooksResult, sessionCost: sessionCostResult, statusLine: statusLineResult };
+  return {
+    hooks: hooksResult,
+    sessionCost: sessionCostResult,
+    statusLine: statusLineResult,
+    codex: installCodexHooks(projectRoot),
+  };
+}
+
+function readCodexHooks(projectRoot) {
+  const file = path.join(projectRoot, CODEX_HOOKS_FILE);
+  if (!fs.existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCodexHooks(projectRoot, config) {
+  const file = path.join(projectRoot, CODEX_HOOKS_FILE);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Reconcile the git guardrail into .codex/hooks.json — the only dev-workflow hook
+ * Codex gets: session-cost parses Claude Code transcripts and Codex has no
+ * statusLine command. Same marker-based contract as the Claude side.
+ * Returns 'added' | 'updated' | 'unchanged' | 'skipped-malformed'.
+ */
+function installCodexHooks(projectRoot) {
+  const config = readCodexHooks(projectRoot);
+  if (config === null) return 'skipped-malformed';
+  const before = JSON.stringify(config);
+  const result = reconcilePreToolUseGitGuardrails(config);
+  if (JSON.stringify(config) !== before) writeCodexHooks(projectRoot, config);
+  return result;
 }
 
 /**
@@ -135,30 +194,14 @@ function reconcileStatusLine(settings) {
 }
 
 /**
- * Remove ONLY dev-workflow-owned hook + statusLine entries (used by uninstall).
- * Returns the number of entries removed.
+ * Remove ONLY dev-workflow-owned hook + statusLine entries from .claude/settings.json
+ * and .codex/hooks.json (used by uninstall). Returns the number of entries removed.
  */
 function removeHooks(projectRoot) {
   const settings = readSettings(projectRoot);
-  let removed = 0;
-
   // Remove OUR hook entries from every event (PreToolUse, SessionEnd, PostToolUse, …),
   // identified by the .dw/scripts/hooks/ marker; never touch user-added hooks.
-  if (settings.hooks && typeof settings.hooks === 'object') {
-    for (const event of Object.keys(settings.hooks)) {
-      const groups = settings.hooks[event];
-      if (!Array.isArray(groups)) continue;
-      for (const group of groups) {
-        if (!group || !Array.isArray(group.hooks)) continue;
-        const kept = group.hooks.filter((h) => !(h && isOurs(h.command)));
-        removed += group.hooks.length - kept.length;
-        group.hooks = kept;
-      }
-      settings.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
-      if (settings.hooks[event].length === 0) delete settings.hooks[event];
-    }
-    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-  }
+  let removed = removeOurHookEntries(settings);
 
   if (settings.statusLine && isOurs(settings.statusLine.command)) {
     delete settings.statusLine;
@@ -166,6 +209,46 @@ function removeHooks(projectRoot) {
   }
 
   if (removed > 0) writeSettings(projectRoot, settings);
+  return removed + removeCodexHooks(projectRoot);
+}
+
+function removeOurHookEntries(config) {
+  let removed = 0;
+  if (!config.hooks || typeof config.hooks !== 'object') return 0;
+  for (const event of Object.keys(config.hooks)) {
+    const groups = config.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const kept = group.hooks.filter((h) => !(h && isOurs(h.command)));
+      removed += group.hooks.length - kept.length;
+      group.hooks = kept;
+    }
+    config.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+    if (config.hooks[event].length === 0) delete config.hooks[event];
+  }
+  if (Object.keys(config.hooks).length === 0) delete config.hooks;
+  return removed;
+}
+
+// Remove OUR entries from .codex/hooks.json; delete the file only when nothing
+// of the user's is left in it.
+function removeCodexHooks(projectRoot) {
+  const config = readCodexHooks(projectRoot);
+  if (!config) return 0;
+  const removed = removeOurHookEntries(config);
+  if (removed === 0) return 0;
+  const file = path.join(projectRoot, CODEX_HOOKS_FILE);
+  if (Object.keys(config).length === 0) {
+    fs.rmSync(file);
+    try {
+      fs.rmdirSync(path.dirname(file));
+    } catch {
+      /* .codex/ still holds other files */
+    }
+  } else {
+    writeCodexHooks(projectRoot, config);
+  }
   return removed;
 }
 
@@ -173,6 +256,8 @@ module.exports = {
   installHooks,
   removeHooks,
   HOOKS_DIR_MARKER,
+  CODEX_HOOKS_FILE,
+  GIT_GUARDRAILS_SCRIPT,
   GIT_GUARDRAILS_CMD,
   STATUSLINE_CMD,
   SESSION_COST_CMD,

package/lib/init.js

@@ -4,7 +4,7 @@ const { ensureDir, copyDir, writeFile, upsertDelimitedBlock, log, listFilesRecur
 const { selectLanguage } = require('./prompts');
 const { generateWrappers } = require('./wrappers');
 const { installMCPs } = require('./mcp');
-const { installHooks } = require('./hooks');
+const { installHooks, STATUSLINE_CMD } = require('./hooks');
 const { generateAgents } = require('./agents');
 const { migrate: migrateGsd } = require('./migrate-gsd');
 const { migrate: migrateSkills } = require('./migrate-skills');
@@ -408,13 +408,19 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   const mcpResults = installMCPs(projectRoot);
   console.log(`    ${mcpResults.added} configured, ${mcpResults.skipped} already present\n`);
 
-  // 9.2. Reconcile dev-workflow hooks + statusline (marker-based, merge-aware:
-  // refreshes our entries, never touches user-defined hooks/statusLine).
+  // 9.2. Reconcile dev-workflow hooks + statusline into .claude/settings.json and the
+  // git guardrail into .codex/hooks.json (marker-based, merge-aware: refreshes our
+  // entries, never touches user-defined hooks/statusLine).
   console.log('  Hooks & statusline:');
   const hookResults = installHooks(projectRoot);
-  console.log(`    git-guardrails: ${hookResults.hooks}, session-cost: ${hookResults.sessionCost}, statusline: ${hookResults.statusLine}\n`);
+  console.log(`    git-guardrails: ${hookResults.hooks}, session-cost: ${hookResults.sessionCost}, statusline: ${hookResults.statusLine}, codex git-guardrails: ${hookResults.codex}\n`);
+  if (hookResults.codex === 'skipped-malformed') {
+    console.log('    Note: .codex/hooks.json is not valid JSON; the Codex git guardrail was not installed.\n');
+  } else if (hookResults.codex !== 'unchanged') {
+    console.log('    Note: Codex runs .codex/hooks.json only after you trust the project and review the hook in Codex.\n');
+  }
   if (hookResults.statusLine === 'skipped-user') {
-    console.log('    Note: a custom statusLine is set; to show dev-workflow state add `node .dw/scripts/hooks/statusline.mjs`.\n');
+    console.log(`    Note: a custom statusLine is set; to show dev-workflow state add \`${STATUSLINE_CMD}\`.\n`);
   }
 
   // 9.5. Persist install state for diagnostics and repair.

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();