@brunosps00/dev-workflow 2.5.0 → 2.7.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.5.0",
+  "version": "2.7.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,107 @@ 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.7.0] — 2026-11-09
+
+### Added
+
+- **Content stress in `dw-ui-discipline`.** New `references/content-stress.md`: a catalog of
+  realistic worst-case values (long and one-letter names, unbreakable emails, `1 members`,
+  1,000+ rows, RTL, emoji-first names), failure signatures with their CSS cause and fix, and
+  a per-field truncate/wrap/clamp rule. `/dw-qa` runs it in UI mode — worst-case data injected
+  at the data boundary (the project's mocks, or `page.route()`, never by editing the
+  component), checked at the real container width, 320px, 200% zoom and dark/RTL — and
+  `/dw-redesign-ui` runs it at validation. Adapted from `break-ui` in
+  [`emilkowalski/skills`](https://github.com/emilkowalski/skills) (MIT).
+- **Mobile platform fixes** in `responsive.md`: hover gated by `(hover: hover) and
+  (pointer: fine)`, `100dvh`/`100svh`, 16px inputs instead of disabling zoom,
+  `touch-action: manipulation`, `overscroll-behavior`, `viewport-fit=cover` for safe areas,
+  `theme-color` per scheme, and the rule that none of it is verified in device emulation.
+- **Command usage telemetry.** The `session-cost` hook records a `commands` object (reads of
+  `.dw/commands/<name>.md`, or a Skill call naming a command) beside `skills`.
+  `/dw-skill-health` reports per-command usage and classifies five command families as
+  `MERGE CANDIDATE`, `KEEP SEPARATE` or `TOO EARLY` (20 sessions or 30 days of window).
+- `/dw-review` checks motion changes against the escalation triggers in `motion.md` and
+  data-rendering changes against the content-stress static signals.
+- `/dw-redesign-ui` directions must diverge on a named axis (layout, density, personality,
+  motion, interaction model) and are named for it, never "Option A/B".
+- **Eval-first in `dw-llm-eval`**, from LangChain's eval-driven development post: a four-line
+  behavior spec (when / does / must not / keeps working) and a baseline run on the current code
+  before the change, where new-behavior cases must fail; a `holdout` split (~20%) never tuned
+  against; and drift compared case by case — a case that passed and now fails blocks, whatever
+  the average says. `/dw-plan` orders the Eval Plan subtask before implementation; `/dw-qa --ai`
+  lists pass → fail flips and reports `holdout` apart from `dev`.
+- **Eval runs are recorded** in `evals/runs/` and compared scenario by scenario; a change that
+  adds a dangerous surface adds its eval in the same change. New eval 7 covers deletion in
+  `update` and `uninstall`.
+
+### Changed
+
+- **Bundled skills install to `.dw/skills/`** instead of `.agents/skills/`. Codex, Copilot and
+  OpenCode all scan `.agents/skills/`, so each listed the 27 bundled skills as model-invocable
+  next to the command wrappers; commands load them by path, and the tool indexes now hold only
+  the `dw-*` entry points. `update` retires a legacy copy from `.agents/skills/` only when it is
+  a dev-workflow copy — its `SKILL.md` carries the Structured Return contract and, when the
+  previous install state tracked files, is one of them — and leaves a same-named skill
+  installed from elsewhere in place, printed as `[kept]`; `uninstall` follows the same rule and
+  `doctor` warns about leftovers. Commands, agent instructions and the `/dw-update` snapshot
+  point at the new location.
+- **`update` and `uninstall` no longer delete what they retire.** Legacy skill copies, removed
+  skills, orphan `dw-*` wrappers and removed command sources are moved to
+  `.dw/.migrated/<timestamp>/` with their relative paths, and files the team added inside a
+  retired copy are named in the output. A terminal `npx … update` takes no snapshot, so this is
+  the copy those users keep. The migration now runs after the new skills are copied, so an
+  interrupted update leaves the old copies in place.
+- **`motion.md` rewritten.** Frequency decides before easing (keyboard-triggered and 100+/day
+  actions do not animate); `ease-in` is never used on UI, exits included (the previous rule
+  said exits ease in); no `scale(0)`, no `transition: all`; trigger-anchored
+  `transform-origin`; transitions over keyframes for rapid triggers; property cost tiers;
+  `will-change` only after a measured problem; a removal gate with its hazards. Springs are
+  allowed only for gesture-driven motion. Adapted from `emilkowalski/skills` (MIT).
+- Reduced motion means fewer and gentler animations, not zero; the accessibility floor adds
+  item 11 (zoom is never disabled; content survives 200% zoom).
+
+### Fixed
+
+- `/dw-update --rollback` copied the `.agents/skills` snapshot into the existing folder,
+  nesting it as `.agents/skills/agents-skills` instead of restoring it.
+- A command wrapper under `.claude/skills/` was counted as a skill use in `costs.jsonl`.
+- `/dw-update --rollback` merged the snapshot over the current files, so files added by the
+  newer release survived it; managed `.dw/` folders are now replaced, and the snapshot also
+  saves and restores `.dw/install-state.json`. `/dw-update` checks the installed version
+  against the CLI's `Installed version` line instead of accepting the old state file.
+- `uninstall` removed `.codex/skills/` wholesale; it now removes only `dw-*` entries and
+  dev-workflow skill copies there.
+
+## [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

package/README.md

@@ -13,10 +13,10 @@ This will:
 2. Create `.dw/commands/` with workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
 4. Create `.dw/rules/` (populated by `/dw-analyze-project`) + a curated `.dw/rules-library/` declarative baseline per stack (loaded lazily via `.dw/config/stack-mappings.json`)
-5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
+5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.dw/skills/` — outside every agent's skill index; commands load them by path
 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.
 
@@ -226,6 +226,7 @@ your-project/
 │   │   └── concerns.md    # Risk map: hot spots, fragile integrations, bug history (Step 9 of /dw-analyze-project)
 │   ├── constitution.md    # Declarative principles (auto-installed when missing)
 │   ├── skill-registry.json # Local skill taxonomy, triggers, owners, load policy, and context limits
+│   ├── skills/            # Bundled skills, loaded by path from commands (not listed in any agent's skill index)
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
 │   ├── spec/              # PRD directories — each contains tasks-validation.md
@@ -241,7 +242,7 @@ your-project/
 │   ├── skills/            # Claude Code wrappers
 │   ├── agents/            # Claude Code project agents
 │   └── settings.json      # MCP servers (Context7, Playwright)
-├── .agents/skills/        # Codex/Copilot wrappers + bundled skills
+├── .agents/skills/        # Codex/Copilot wrappers (bundled skills live in .dw/skills/)
 ├── .agents/agents/        # Codex/Copilot fallback agent definitions
 ├── .github/agents/        # GitHub Copilot custom agents
 ├── .opencode/commands/    # OpenCode wrappers
@@ -274,7 +275,7 @@ npx @brunosps00/dev-workflow subtask list
 
 ## Bundled Skills
 
-Skills installed to `.agents/skills/` for use by all commands. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, context limit, invocation control (`model` vs `explicit`), and à-la-carte `exportable` flag.
+Skills installed to `.dw/skills/` for use by all commands. They sit outside the directories Codex, Copilot, OpenCode and Claude Code scan for model-invocable skills (`.agents/skills/`, `.claude/skills/`, `.github/skills/`, `.opencode/skills/`), so each tool's skill index lists only the `dw-*` command entry points; commands read the skills they need by path. Releases up to 2.6.0 installed them under `.agents/skills/`; `update` retires those copies once the new ones are in place, moving them to `.dw/.migrated/<timestamp>/` rather than deleting them, and leaves a same-named skill you installed from elsewhere where it is. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, context limit, invocation control (`model` vs `explicit`), and à-la-carte `exportable` flag.
 
 Skill kinds:
 
@@ -378,6 +379,8 @@ Spec-Driven Development patterns — declarative constitution (`.dw/constitution
 
 UI discipline (`dw-ui-discipline`) and testing doctrine (`dw-testing-discipline`) are original works in this repository. Earlier dev-workflow versions (≤0.13.x) drew on `pedronauck/skills` `ui-craft` and `testing-boss` as inspiration, but in v0.14.0 those skills were rewritten clean-room after a license audit confirmed that the upstream repo has no explicit LICENSE file at root — the README's MIT claim is unverified. The underlying ideas (grounding before design; behavior over mocks; mutation over coverage) are widely-documented general software engineering principles available in many sources (Beck, Fowler, Meszaros, Feathers, Google SRE Book, WCAG specifications). Browser-DevTools patterns from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) live inside `dw-testing-discipline/references/` (`security-boundary.md`, `three-workflow-patterns.md`).
 
+The motion, mobile-web and content-stress references in `dw-ui-discipline` (`motion.md`, the "Mobile platform fixes" section of `responsive.md`, `content-stress.md`) adapt rules from [`emilkowalski/skills`](https://github.com/emilkowalski/skills) by Emil Kowalski (MIT): `emil-design-eng`, `review-animations`, `animation-performance`, `remove-animations`, `mobile-native` and `break-ui`. See [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md), section 15.
+
 Minimalism discipline (`dw-minimalism`), per-skill invocation control (`disable-model-invocation` on hidden/internal command wrappers), the git-guardrails enforcement hook, and à-la-carte plugin distribution were adapted from [`DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail) (MIT — the "lazy senior" decision ladder, intensity modes, and statusline) and [`mattpocock/skills`](https://github.com/mattpocock/skills) (MIT — user-vs-model invocation and `git-guardrails-claude-code`). See [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md) for the full gap analysis and what was and was not adopted.
 
 Incident response (`dw-incident-response`) adapted from [`wilsto/claude-code-starter-kit/incident-response`](https://github.com/wilsto/claude-code-starter-kit) (MIT). The 5-phase workflow structure and runbook templates come from there. wilsto credits the upstream `wshobson/agents` plugin `incident-response` (v1.3.0); attribution chain preserved. Additional reading cited in the skill: Google SRE Book, Etsy Debriefing Facilitation Guide, PagerDuty Incident Response Documentation.
@@ -431,7 +434,7 @@ v1.0.0 consolidated the legacy command surface into the current `dw-*` pipeline.
 On the next `npx @brunosps00/dev-workflow update`, the following happens automatically:
 
 1. The 15 renamed commands' wrappers are detected as orphans (their names no longer exist in `lib/constants.js`) and removed from `.claude/skills/`, `.agents/skills/`, and `.opencode/commands/`.
-2. The migrator prints each removal with the friendly "old → new" mapping (e.g., `[orphan] Removing wrapper .agents/skills/dw-create-prd (replaced in v1.0.0 by 'dw-plan prd')`).
+2. The migrator prints each removal with the friendly "old → new" mapping (e.g., `[orphan] Retiring wrapper .agents/skills/dw-create-prd (replaced in v1.0.0 by 'dw-plan prd')`).
 3. The current command wrappers are installed for the consolidated commands.
 4. The bundled skills are refreshed.
 

package/lib/doctor.js

@@ -9,8 +9,15 @@ const {
   AGENT_TARGETS,
 } = 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 {
+  validateSkillRegistry,
+  readSkillRegistry,
+  validateSkillStructuredReturn,
+  BUNDLED_SKILLS_REL,
+  LEGACY_BUNDLED_SKILLS_REL,
+} = require('./skill-registry');
+const { isDevWorkflowSkillCopy } = require('./migrate-skills');
+const { GIT_GUARDRAILS_SCRIPT, GIT_GUARDRAILS_CMD, STATUSLINE_CMD, HOOKS_DIR_MARKER, CODEX_HOOKS_FILE } = require('./hooks');
 const removedCommands = require('./removed-commands');
 
 function run() {
@@ -177,12 +184,20 @@ function checkSkillRegistry(projectRoot, issues, warnings) {
   const registry = readSkillRegistry();
   for (const entry of registry.skills) {
     if (!entry.bundled) continue;
-    const skillPath = path.join(projectRoot, '.agents', 'skills', entry.name, 'SKILL.md');
+    const skillPath = path.join(projectRoot, BUNDLED_SKILLS_REL, entry.name, 'SKILL.md');
     if (!fs.existsSync(skillPath)) {
       issues.push(`Missing bundled skill: ${path.relative(projectRoot, skillPath)}`);
     } else {
       validateSkillStructuredReturn(entry.name, skillPath, issues, `Installed bundled skill ${entry.name}`);
     }
+    // A copy left under .agents/skills/ by a release up to 2.6.0 is still listed
+    // as model-invocable by Codex, Copilot and OpenCode. `update` removes it.
+    const legacySkillPath = path.join(projectRoot, LEGACY_BUNDLED_SKILLS_REL, entry.name, 'SKILL.md');
+    if (isDevWorkflowSkillCopy(path.dirname(legacySkillPath))) {
+      warnings.push(
+        `Legacy bundled skill copy at ${path.relative(projectRoot, path.dirname(legacySkillPath))} is still in agent skill indexes; run update to move it to ${BUNDLED_SKILLS_REL}/`
+      );
+    }
   }
 }
 
@@ -212,6 +227,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 +239,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 +297,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');
@@ -12,6 +12,7 @@ const { hasExistingInstall, readInstallState, writeInstallState, listManagedFile
 const { resolveInstallSelection } = require('./profiles');
 const { ensureSubtaskLayout } = require('./subtasks');
 const { printPostUpdateActions } = require('./post-update');
+const { BUNDLED_SKILLS_REL } = require('./skill-registry');
 
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
@@ -33,11 +34,10 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     console.log('  Existing dev-workflow install detected; reconciling managed files.\n');
   }
 
-  // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected)
-  // 0.1. Skill migration: removed bundled skills + orphan dw-* wrappers (idempotent)
+  // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected).
+  // The skill migration runs later (5.55), once the new copies exist.
   if (shouldReconcile) {
     migrateGsd(projectRoot);
-    migrateSkills(projectRoot);
   }
 
   // 1. Select language
@@ -332,22 +332,32 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   ensureSubtaskLayout(projectRoot);
   touchedFiles.push(path.join(projectRoot, '.dw', 'subtasks', '.gitignore'));
 
-  // 5.5. Copy bundled skills to .agents/skills/
+  // 5.5. Copy bundled skills to .dw/skills/ — outside every agent CLI's skill
+  // index; commands load them by path. Legacy copies under .agents/skills/ are
+  // retired by migrateSkills() (step 5.55) on update/repair/re-init.
   const skillsSrcDir = path.join(SCAFFOLD_DIR, 'skills');
   if (require('fs').existsSync(skillsSrcDir)) {
     console.log('  Bundled skills:');
     const skillsResults = copyDir(
       skillsSrcDir,
-      path.join(projectRoot, '.agents', 'skills'),
+      path.join(projectRoot, BUNDLED_SKILLS_REL),
       managedForce
     );
     totalCreated += skillsResults.created;
     totalSkipped += skillsResults.skipped;
     totalOverwritten += skillsResults.overwritten;
-    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.agents', 'skills')));
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, BUNDLED_SKILLS_REL)));
     console.log(`    ${skillsResults.created} created, ${skillsResults.skipped} skipped, ${skillsResults.overwritten} overwritten\n`);
   }
 
+  // 5.55. Skill migration: removed bundled skills, legacy .agents/skills copies,
+  // orphan dw-* wrappers and removed command sources. Runs after the copy above
+  // so an interrupted update never leaves neither copy, and moves what it retires
+  // to .dw/.migrated/<ts>/ instead of deleting it (idempotent).
+  if (shouldReconcile) {
+    migrateSkills(projectRoot, { priorState });
+  }
+
   // 5.6. Generate platform-native/fallback agents from the selected modules.
   console.log('  Agents:');
   const agentResults = generateAgents(projectRoot, selection.modules, managedForce);
@@ -408,13 +418,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.