refacil-sdd-ai 5.1.0 → 5.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 **SDD-AI** (Specification-Driven Development with AI) packaged as a CLI.
 
-Installs **skills** and **sub-agents** for **Claude Code**, **Cursor**, and **OpenCode** that guide the developer through a structured AI-assisted development workflow, using **`refacil-sdd/`** as the specification store, plus a **local bus** so agents across different repos can communicate with each other.
+Installs **skills** and **sub-agents** for **Claude Code**, **Cursor**, **OpenCode**, and **Codex** that guide the developer through a structured AI-assisted development workflow, using **`refacil-sdd/`** as the specification store, plus a **local bus** so agents across different repos can communicate with each other.
 
 ---
 
@@ -11,9 +11,9 @@ Installs **skills** and **sub-agents** for **Claude Code**, **Cursor**, and **Op
 ## Requirements
 
 - **Node.js >= 20.0.0**
-- One or more supported IDEs: **Claude Code >= 2.1.89**, **Cursor**, or **OpenCode**
+- One or more supported IDEs: **Claude Code >= 2.1.89**, **Cursor**, **OpenCode**, or **Codex**
 
-`refacil-sdd-ai init` checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but `compact-bash` will have no effect (Claude Code only — OpenCode and Cursor have their own hook delivery mechanisms).
+`refacil-sdd-ai init` checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but `compact-bash` will have no effect (Claude Code only — Cursor, OpenCode, and Codex have their own hook delivery mechanisms).
 
 ---
 
@@ -33,8 +33,8 @@ refacil-sdd-ai init
 
 `init` installs skills, sub-agents, and hooks into your IDE's **global user directories** (`~/.claude/`, `~/.cursor/`, `~/.config/opencode/`). Skills are available in all your repos from this point — no need to re-run `init` when you open a new repo.
 
-- Interactive IDE selector (Claude Code / Cursor / OpenCode) — pre-selects installed IDEs.  
-  Use `--all` to install for all three without prompting.
+- Interactive IDE selector (Claude Code / Cursor / OpenCode / Codex) — pre-selects installed IDEs.  
+  Use `--all` to install for all four without prompting.
 - Your IDE selection is saved to `~/.refacil-sdd-ai/selected-ides.json` and reused on every `update`.
 - Also prompts for global branch config (`baseBranch`, `protectedBranches`, `artifactLanguage`)  
   stored in `~/.refacil-sdd-ai/config.yaml`. Skip with `--yes` or `--defaults`.
@@ -89,10 +89,10 @@ npm uninstall -g refacil-sdd-ai
 
 | Command | Description |
 |---|---|
-| `refacil-sdd-ai init` | Install skills and hooks in the current repo |
-| `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version |
+| `refacil-sdd-ai init` | Install skills and hooks into global IDE user directories |
+| `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version (global) |
 | `refacil-sdd-ai migration-pending [--json]` | Same detection as hooks/`notify-update`; exit 1 if migration is pending; on exit 0 also deletes obsolete `.refacil-pending-update` (same as at the start of `check-update`) |
-| `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from the repo |
+| `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from global IDE user directories |
 | `refacil-sdd-ai help` | Show help |
 
 ### Internal hooks (invoked automatically — not for manual use)
@@ -184,13 +184,13 @@ refacil-sdd-ai sdd config --json
 
 > The `join/leave/say/ask/reply/attend/inbox` subcommands also exist as **IDE skills** (`/refacil:join`, etc.). In most cases use the skills; the CLI commands are for scripting or debugging.
 >
-> **Cross-repo coordination** (ask requests, room agreements, `/refacil:propose`, closing to the requester): after `init`, the file **`BUS-CROSS-REPO.md`** is available in `.claude/skills/refacil-prereqs/` and `.cursor/skills/refacil-prereqs/`.
+> **Cross-repo coordination** (ask requests, room agreements, `/refacil:propose`, closing to the requester): after `init`, the file **`BUS-CROSS-REPO.md`** is available in `~/.claude/skills/refacil-prereqs/` and `~/.cursor/skills/refacil-prereqs/`.
 
 ---
 
 ## Available IDE Skills
 
-All invoked as `/refacil:<name>` in Claude Code, Cursor, or OpenCode.
+All invoked as `/refacil:<name>` in Claude Code, Cursor, OpenCode, or Codex.
 
 ### SDD cycle
 
@@ -227,7 +227,7 @@ Some skills delegate their heavy work to **sub-agents** that run in isolated con
 
 **Model**: `refacil-proposer` runs with `model: opusplan` (uses Opus during plan mode for highest-stakes planning, then switches to Sonnet for execution). Other sub-agents use `model: sonnet` by default for Claude Code, others use inherit model.
 
-**Triple-platform**: `.claude/agents/refacil-*.md` uses `tools:` (granular allowlist). `.cursor/agents/refacil-*.md` is auto-generated: `readonly: true` for agents without `Edit`/`Write`, `readonly: false` for those that have them; always `model: inherit`. `.opencode/agents/refacil-*.md` is auto-generated via `transformFrontmatterForOpenCode()`: converts `tools:` to a `permission:` block (`edit: allow/deny`, `bash: allow/deny`, `webfetch: deny`), adds `mode: subagent`, adds `hidden: true` for internal agents, and removes `model:`. The installer transforms the frontmatter automatically for all three IDEs.
+**Multi-platform**: `.claude/agents/refacil-*.md` uses `tools:` (granular allowlist). `.cursor/agents/refacil-*.md` is auto-generated: `readonly: true` for agents without `Edit`/`Write`, `readonly: false` for those that have them; always `model: inherit`. `.opencode/agents/refacil-*.md` is auto-generated via `transformFrontmatterForOpenCode()`: converts `tools:` to a `permission:` block (`edit: allow/deny`, `bash: allow/deny`, `webfetch: deny`), adds `mode: subagent`, adds `hidden: true` for internal agents, and removes `model:`. `.codex/agents/refacil-*.toml` is auto-generated via `convertAgentToToml()`: extracts `name` and `description` from the YAML frontmatter and places the Markdown body in `developer_instructions = """..."""`. The installer transforms the frontmatter automatically for all four IDEs.
 
 **Two-pass `refacil:bug` flow**: the wrapper first invokes the sub-agent in `investigation` mode (writes nothing) → the user confirms the hypothesis and approves the fix → the wrapper validates the working branch → invokes the sub-agent in `fix` mode to implement.
 
@@ -316,14 +316,14 @@ From there, the full cycle is:
 
 ## Automatic Hooks
 
-Installed during `init` / `update` for each selected IDE. The same four behaviors are active in Claude Code, Cursor, and OpenCode — each through its own delivery mechanism.
+Installed during `init` / `update` for each selected IDE. The same four behaviors are active in Claude Code, Cursor, OpenCode, and Codex — each through its own delivery mechanism.
 
-| Behavior | Claude Code | Cursor | OpenCode |
-|---|---|---|---|
-| **check-update** | `SessionStart` hook in `.claude/settings.json` | `SessionStart` hook in `.cursor/settings.json` | `session.created` handler in `.opencode/plugins/refacil-hooks.js` |
-| **notify-update** | `UserPromptSubmit` hook | `beforeSubmitPrompt` hook | `tui.prompt.append` handler |
-| **compact-bash** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool |
-| **check-review** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool |
+| Behavior | Claude Code | Cursor | OpenCode | Codex |
+|---|---|---|---|---|
+| **check-update** | `SessionStart` hook in `~/.claude/settings.json` | `SessionStart` hook in `~/.cursor/hooks.json` | `session.created` handler in the global OpenCode plugin | `sessionStart` hook in `~/.codex/config.toml` |
+| **notify-update** | `UserPromptSubmit` hook | `beforeSubmitPrompt` hook | `tui.prompt.append` handler | `userPromptSubmit` hook in `~/.codex/config.toml` |
+| **compact-bash** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool | `preToolUse` hook (Bash matcher) in `~/.codex/config.toml` |
+| **check-review** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool | `preToolUse` hook (Bash matcher) in `~/.codex/config.toml` |
 
 | Behavior | What it does |
 |---|---|
@@ -332,7 +332,9 @@ Installed during `init` / `update` for each selected IDE. The same four behavior
 | `compact-bash` | Silently rewrites bare Bash commands. No extra turns, the IDE does not see the change. Requires Claude Code >= 2.1.89 for the `updatedInput` path. |
 | `check-review` | Intercepts `git push` and blocks if `.review-passed` is missing in any active change. |
 
-> **OpenCode plugin**: a single file (`.opencode/plugins/refacil-hooks.js`) implements all four behaviors. It loads `lib/compact/rules.js` from the package to reuse the same rewrite rules — no duplicated logic. If the rules file is not resolvable, compact-bash is disabled gracefully with a warning to stderr; the plugin never crashes the session.
+> **OpenCode plugin**: a single file installed in the global OpenCode plugins directory implements all four behaviors. It loads `lib/compact/rules.js` from the package to reuse the same rewrite rules — no duplicated logic. If the rules file is not resolvable, compact-bash is disabled gracefully with a warning to stderr; the plugin never crashes the session.
+
+> **Codex hooks**: injected into `~/.codex/config.toml` under `[hooks]` with `[features] codex_hooks = true`. Each SDD-AI hook entry carries a boolean marker (`_sdd`, `_sdd_compact`, `_sdd_review`, `_sdd_notify`) for clean removal on `clean`. User-defined hooks outside these entries are preserved.
 
 > **Why two hooks for updates?** `SessionStart` does the silent sync when opening the session without user interaction. `notify-update` on `UserPromptSubmit` / `beforeSubmitPrompt` injects the instruction just before the agent processes the next user message, ensuring it is not ignored.
 
@@ -470,31 +472,46 @@ Local bus (WebSocket over `127.0.0.1`) so agents across different repos can comm
 
 ---
 
-## What Gets Installed in Your Repo
+## What Gets Installed
 
-Only the IDEs selected during `init` (or detected during `update`) receive files. The three IDE targets are independent — selecting only `.opencode` does not create `.claude/` or `.cursor/` directories.
+### Global user directories (once, shared across all repos)
+
+Skills, sub-agents, and hooks are installed into the user's global IDE directories — not into any project repo. Only the IDEs selected during `init` receive files.
 
 ```
 # Claude Code (if selected)
-.claude/skills/refacil-*/    # Skills (includes refacil-prereqs: METHODOLOGY-CONTRACT.md, BUS-CROSS-REPO.md, …)
-.claude/agents/refacil-*.md  # Read-only sub-agents: auditor, investigator, validator
-                             # Write sub-agents: tester, implementer, debugger, proposer
-.claude/settings.json        # Hooks: check-update + notify-update + check-review + compact-bash
-.claude/.sdd-version         # Installed methodology version (used by check-update)
+~/.claude/skills/refacil-*/    # Skills (includes refacil-prereqs: METHODOLOGY-CONTRACT.md, BUS-CROSS-REPO.md, …)
+~/.claude/agents/refacil-*.md  # Read-only sub-agents: auditor, investigator, validator
+                               # Write sub-agents: tester, implementer, debugger, proposer
+~/.claude/settings.json        # SDD hooks merged in: check-update, notify-update, check-review, compact-bash
 
 # Cursor (if selected)
-.cursor/skills/refacil-*/    # Cursor skills (equivalent)
-.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit, auto-generated)
-.cursor/settings.json        # Hooks: check-update + notify-update + check-review + compact-bash
-.cursor/.sdd-version         # Installed methodology version
-
-# OpenCode (if selected)
-.opencode/skills/refacil-*/       # OpenCode skills (byte-for-byte copy — same spec as Claude Code)
-.opencode/agents/refacil-*.md    # OpenCode sub-agents (permission block + mode:subagent, auto-generated)
-.opencode/plugins/refacil-hooks.js  # Embedded plugin: session.created + tui.prompt.append + tool.execute.before
-.opencode/opencode.json          # Created/merged with $schema (user keys preserved)
-.opencode/.sdd-version           # Installed methodology version
+~/.cursor/skills/refacil-*/    # Cursor skills (auto-transformed frontmatter: readonly + model:inherit)
+~/.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit, auto-generated)
+~/.cursor/hooks.json           # SDD hooks merged in (same four behaviors)
+
+# OpenCode (if selected)  — macOS/Linux: ~/.config/opencode/   Windows: %APPDATA%\opencode
+~/.config/opencode/skills/refacil-*/    # OpenCode skills
+~/.config/opencode/agents/refacil-*.md  # OpenCode sub-agents (permission block + mode:subagent)
+~/.config/opencode/plugins/refacil-hooks.js  # Plugin: session.created + tui.prompt.append + tool.execute.before
+
+# Codex (if selected)
+~/.codex/skills/refacil-*/             # Codex skills (same content as Claude Code)
+~/.codex/agents/refacil-*.toml         # Codex sub-agents (TOML: name + description + developer_instructions)
+~/.codex/config.toml                   # SDD hooks merged in under [hooks] with [features] codex_hooks = true
+
+# refacil-sdd-ai state
+~/.refacil-sdd-ai/
+  selected-ides.json           # IDE selection saved on init, reused by update
+  config.yaml                  # Global config: baseBranch, protectedBranches, artifactLanguage
+  sdd-version                  # Installed methodology version (used by check-update)
+```
 
+### Per repo (generated by `/refacil:setup`)
+
+The only per-repo step is running `/refacil:setup` once per project. It generates the project index — no IDE skills or hooks are written to the repo.
+
+```
 # Shared (IDE-agnostic)
 CLAUDE.md                    # Minimal index → points to AGENTS.md
 .cursorrules                 # Cursor format equivalent of CLAUDE.md
@@ -512,6 +529,8 @@ refacil-sdd/                 # SDD artifacts store
   specs/                     # Persistent specifications synced from archived changes
 ```
 
+> **Migration from project-level installs**: the `check-update` hook (SessionStart) automatically detects and removes any leftover project-level `refacil-*` skills, agents, hooks, and empty IDE directories from older versions.
+
 ---
 
 ## Technologies
@@ -520,6 +539,7 @@ refacil-sdd/                 # SDD artifacts store
 - [Claude Code](https://claude.ai/code) — Anthropic CLI
 - [Cursor](https://cursor.sh) — AI IDE
 - [OpenCode](https://opencode.ai) — open-source AI development agent
+- [Codex](https://github.com/openai/codex) — OpenAI CLI agent
 
 ## License
 

package/agents/debugger.md

@@ -11,7 +11,7 @@ You are a debugging agent operating in two modes. In investigation mode you rece
 
 Reject weak hypotheses. If the evidence does not support a root cause, say so. Do not propose a fix until the cause is clear.
 
-**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
+**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + rules from **`METHODOLOGY-CONTRACT.md` (§3, §3.1 — verification defaults to scoped in fix mode)**.
 
 ## Guardrail: direct invocation detection
 
@@ -29,6 +29,7 @@ If you prefer to continue here, provide:
   - mode: investigation (only analyze and propose hypotheses) or fix (implement with already-confirmed hypothesis)
   - description: <full bug description>
   - hypothesis: <confirmed root cause> (only for mode=fix)
+  - testScope: scoped \| full (only for mode=fix; default scoped)
 ```
 
 **Do not proceed with reads or implementation until the scope is clear.**
@@ -124,7 +125,7 @@ Proposed fix for hypothesis #1:
 
 ## Fix mode
 
-The main agent passes you: `mode: fix` + `description` + `hypothesis` (root cause confirmed by the user).
+The main agent passes you: `mode: fix` + `description` + `hypothesis` (root cause confirmed by the user) + optional **`testScope`** (`scoped` \| `full`, default **`scoped`**).
 
 ### Step 1: Implement the fix
 
@@ -139,7 +140,7 @@ Detect the project's testing stack and framework: read `METHODOLOGY-CONTRACT.md
 Generate tests that:
 1. **Reproduce the bug**: a test that fails WITHOUT the fix (verifies the test is valid).
 2. **Verify the fix**: the same test passes WITH the fix.
-3. **Verify no regression**: normal flow tests still pass.
+3. **Guardrails**: extend with normal/control-path assertions when they fit the bug surface (Step 4 **scoped** run targets those files/packages — **not** the entire repo suite).
 
 Each test must cover:
 - `should [correct behavior] when [condition that previously failed]`
@@ -164,9 +165,14 @@ Create `refacil-sdd/changes/<fix-name>/summary.md`:
 
 This file is mandatory for traceability and allows the `check-review` hook to detect the active change. The `.review-passed` will be created by `/refacil:review` upon approval.
 
-### Step 4: Run all tests
+### Step 4: Verify tests (`METHODOLOGY-CONTRACT.md` §3.1)
 
-Resolve and run the test command according to `METHODOLOGY-CONTRACT.md §3`. All tests must pass.
+1. Read **`testScope`** from wrapper (default **`scoped`** if omitted).
+2. **`testScope: full`**: Resolve baseline from **`METHODOLOGY-CONTRACT.md §3`**, run **once unparsed** — **all tests** emitted by that command must pass.
+3. **`testScope: scoped`** (default): Collect **`verificationTargets`** — every production/test file **you edited or added** during fix mode (**including** regression tests created this session).
+   - Build **`scopedCommand`** by narrowing baseline §3 to cover only those roots (directories, `-p`/`-pl`, `--`/path suffixes — follow stack docs + **`AGENTS.md` / `.agents/testing.md`** when present — see §3.1 **Scoped command patterns**).
+   - Run **`scopedCommand`**; everything it selects must pass. **Do not** upgrade to repo-wide invocation while `scoped` unless §3.1 says narrowing is unreliable — then run baseline **once**, prepend report line **WARN: scoped narrowing unavailable → full-suite fallback (heavy)**.
+4. **`testsResult.command`** in JSON must quote the **literal** executed shell string (`scopedCommand` or baseline).
 
 ### Report + JSON block (fix)
 
@@ -208,4 +214,5 @@ Resolve and run the test command according to `METHODOLOGY-CONTRACT.md §3`. All
 - In mode=investigation: follow diagnose loop discipline (reproduce, minimize, hypothesize, validate evidence) before proposing a fix.
 - In mode=fix: the fix must be MINIMAL. Never over-refactor.
 - Regression tests are MANDATORY in mode=fix.
+- **Scoped verification**: default **`testScope: scoped`** from wrapper — narrowed command in Step 4, not wholesale “run entire repo suite” unless `full`.
 - Use **concise** output mode by default.

package/agents/implementer.md

@@ -11,7 +11,7 @@ You are an implementation agent. You receive a structured briefing (objective, s
 
 If the briefing is ambiguous or a task cannot be completed safely, report it — do not silently skip or guess.
 
-**Prerequisites**: rules from `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
+**Prerequisites**: rules from `refacil-prereqs/METHODOLOGY-CONTRACT.md` (**§3**, **§3.1** — default verification is **scoped**).
 
 ## Guardrail: direct invocation detection
 
@@ -72,7 +72,9 @@ Read from the prompt the `BRIEFING:` sections passed by the wrapper:
 - `scope.modify` — existing files to modify
 - `scope.doNotTouch` — files out of scope
 - `tasks` — numbered task list
-- `testCommand` — verification command
+- `testScope` — `scoped` \| `full` (default **`scoped`** if absent — treat missing as scoped)
+- `testCommand` — **exact shell command** to execute for verification (narrowed when `scoped`)
+- `verificationWarning` — optional hint from wrapper (often explains fallback-to-baseline)
 - `architectureContext` — already-extracted architecture context
 - `specsNote` — if there are specs, where they are and whether there are possible contradictions
 
@@ -82,7 +84,7 @@ If the briefing is **not present** (direct invocation without briefing):
 3. Read `refacil-sdd/changes/<changeName>/tasks.md` (tasks)
 4. Read `AGENTS.md` (architecture)
 5. Read the change specs
-6. Read `METHODOLOGY-CONTRACT.md §3` (test command)
+6. Read `METHODOLOGY-CONTRACT.md` §3 and §3.1 (narrow **before** invoking the runner unless you explicitly widen)
 
 ### Step 2: Read existing interfaces (scope.modify only)
 
@@ -103,7 +105,12 @@ If a task requires touching a file outside the scope: note it in `issues` as pot
 
 ### Step 4: Verify
 
-Run the `testCommand` from the briefing (or from `METHODOLOGY-CONTRACT.md §3` if not in the briefing).
+Follow **`METHODOLOGY-CONTRACT.md §3.1`**:
+
+1. Run **exactly** the **`testCommand`** supplied in the briefing.
+2. If **`testCommand` is missing**, resolve baseline from **`METHODOLOGY-CONTRACT.md §3`** and **narrow** it yourself using `scope.create` ∪ `scope.modify` plus the §3.1 **Scoped command patterns**. If narrowing is unsafe, run the baseline **once**, add **`issues`** entry severity **MEDIUM** explaining full-suite fallback, and cite `verificationWarning` pattern if analogous.
+3. **Do not** broaden the briefing’s `testCommand` into a fuller suite when `testScope` is **`scoped`** (or omitted). Repo-wide regression belongs in CI or an explicit **`/refacil:test … full`**.
+4. If `verificationWarning` is present in the briefing, mirror a short note in **`issues`** (severity **LOW**) so the wrapper/user sees CPU/RAM risk was intentional.
 
 ### Step 5: Report + JSON block
 

package/bin/cli.js

@@ -1,14 +1,13 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const {
-  syncCompactGuidance,
-  removeCompactGuidance,
-} = require('../lib/compact-guidance');
+const { removeCompactGuidance } = require('../lib/compact-guidance');
+const { removeTestingPolicyBlock } = require('../lib/testing-policy-sync');
+const { syncRepoSessionMarkers } = require('../lib/session-repo-sync');
 const compactBash = require('../lib/compact/bash');
 const {
   installSkills,
@@ -17,6 +16,7 @@ const {
   removeSkills,
   removeGlobalSkills,
   removeOpenCodeArtifacts,
+  removeCodexArtifacts,
   removeOpenspecLegacyAssets,
   removeProjectLevelArtifacts,
   createClaudeMd,
@@ -30,7 +30,7 @@ const {
   checkClaudeCodeVersion,
 } = require('../lib/installer');
 const { installHooks, uninstallHooks, cleanLegacySettingsHooks, installOpenCodePlugin, uninstallOpenCodePlugin, removeProjectLevelHooks } = require('../lib/hooks');
-const { globalClaudeDir, globalCursorDir, globalOpenCodeDir, readSelectedIDEs, writeSelectedIDEs } = require('../lib/global-paths');
+const { globalClaudeDir, globalCursorDir, globalOpenCodeDir, globalCodexDir, readSelectedIDEs, writeSelectedIDEs } = require('../lib/global-paths');
 const { detectInstalledIDEs } = require('../lib/ide-detection');
 const { handleCompact } = require('../lib/commands/compact');
 const { handleBus } = require('../lib/commands/bus');
@@ -131,7 +131,8 @@ function repoIsInitialized() {
   if (
     fs.existsSync(path.join(globalClaudeDir(home), 'skills')) ||
     fs.existsSync(path.join(globalCursorDir(home), 'skills')) ||
-    fs.existsSync(path.join(globalOpenCodeDir(home), 'skills'))
+    fs.existsSync(path.join(globalOpenCodeDir(home), 'skills')) ||
+    fs.existsSync(path.join(globalCodexDir(home), 'skills'))
   ) {
     return true;
   }
@@ -204,9 +205,9 @@ function readlineMultiSelect(options) {
  */
 async function selectIDEs() {
   const allFlag = process.argv.includes('--all');
-  const allIDEs = ['.claude', '.cursor', '.opencode'];
+  const allIDEs = ['.claude', '.cursor', '.opencode', '.codex'];
 
-  // --all or non-TTY: install all three
+  // --all or non-TTY: install all four
   if (allFlag || !process.stdout.isTTY) {
     return allIDEs;
   }
@@ -226,11 +227,15 @@ async function selectIDEs() {
   const openCodeSelected = hasSaved
     ? savedSelection.includes('.opencode')
     : detectedIds.includes('opencode') || fs.existsSync(path.join(projectRoot, '.opencode'));
+  const codexSelected = hasSaved
+    ? savedSelection.includes('.codex')
+    : detectedIds.includes('codex');
 
   const options = [
     { label: 'Claude Code (~/.claude/)', value: '.claude', selected: claudeSelected },
     { label: 'Cursor (~/.cursor/)', value: '.cursor', selected: cursorSelected },
     { label: 'OpenCode (global config dir)', value: '.opencode', selected: openCodeSelected },
+    { label: 'Codex (~/.codex/)', value: '.codex', selected: codexSelected },
   ];
 
   // Try @clack/prompts first, fall back to inline readline
@@ -337,7 +342,8 @@ function checkUpdate() {
     const globalActive =
       fs.existsSync(path.join(globalClaudeDir(home), 'skills')) ||
       fs.existsSync(path.join(globalCursorDir(home), 'skills')) ||
-      fs.existsSync(path.join(globalOpenCodeDir(home), 'skills'));
+      fs.existsSync(path.join(globalOpenCodeDir(home), 'skills')) ||
+      fs.existsSync(path.join(globalCodexDir(home), 'skills'));
 
     if (globalActive) {
       const cleaned = removeProjectLevelArtifacts(projectRoot);
@@ -354,9 +360,23 @@ function checkUpdate() {
   let localVersion = getPackageVersion(packageRoot);
 
   try {
-    syncCompactGuidance(projectRoot, packageRoot);
+    const syncOut = syncRepoSessionMarkers(projectRoot, packageRoot);
+    if (!syncOut.ok) {
+      process.stderr.write(`[refacil-sdd-ai] session repo sync: ${syncOut.reason}\n`);
+    } else {
+      if (syncOut.compact.status === 'error') {
+        process.stderr.write(`[refacil-sdd-ai] Could not sync compact-guidance: ${syncOut.compact.message}\n`);
+      }
+      if (syncOut.testing.status === 'error') {
+        process.stderr.write(`[refacil-sdd-ai] Could not sync testing-policy block: ${syncOut.testing.message}\n`);
+      } else if (
+        ['created-file', 'appended', 'replaced', 'written-empty'].includes(syncOut.testing.status)
+      ) {
+        process.stdout.write(`[refacil-sdd-ai] testing-policy: ${syncOut.testing.status} (.agents/testing.md)\n`);
+      }
+    }
   } catch (err) {
-    process.stderr.write(`[refacil-sdd-ai] Could not sync compact-guidance: ${err.message}\n`);
+    process.stderr.write(`[refacil-sdd-ai] session repo sync: ${err.message}\n`);
   }
 
   cleanLegacySettingsHooks(projectRoot);
@@ -616,6 +636,7 @@ async function init() {
   const installClaude = selectedIDEs.includes('.claude');
   const installCursor = selectedIDEs.includes('.cursor');
   const installOpenCode = selectedIDEs.includes('.opencode');
+  const installCodex = selectedIDEs.includes('.codex');
   const homeDir = os.homedir();
 
   // Migration step: remove project-level artifacts (now global) — silent, non-destructive
@@ -630,6 +651,7 @@ async function init() {
   const ideList = selectedIDEs.map((d) => {
     if (d === '.claude') return `~/.claude/skills/`;
     if (d === '.cursor') return `~/.cursor/skills/`;
+    if (d === '.codex') return `~/.codex/skills/`;
     return `(opencode-global)/skills/`;
   }).join(', ');
   console.log(`  ${count} skills installed in ${ideList}`);
@@ -639,6 +661,7 @@ async function init() {
     const agentList = selectedIDEs.map((d) => {
       if (d === '.claude') return `~/.claude/agents/`;
       if (d === '.cursor') return `~/.cursor/agents/`;
+      if (d === '.codex') return `~/.codex/agents/`;
       return `(opencode-global)/agents/`;
     }).join(', ');
     console.log(`  ${agentsCount} sub-agents installed in ${agentList}`);
@@ -666,6 +689,12 @@ async function init() {
     }
   }
 
+  if (installCodex) {
+    if (installHooks('.codex', homeDir)) {
+      console.log('  Hook check-update added to ~/.codex/config.toml');
+    }
+  }
+
   try {
     const IDE_TO_IGNORE = { '.claude': '.claudeignore', '.cursor': '.cursorignore', '.opencode': '.opencodeignore' };
     const ignoreResult = syncIgnoreFiles(projectRoot, selectedIDEs);
@@ -683,14 +712,29 @@ async function init() {
   }
 
   try {
-    const result = syncCompactGuidance(projectRoot, packageRoot);
-    if (result.status === 'appended') {
-      console.log('  compact-guidance block added to AGENTS.md');
-    } else if (result.status === 'replaced') {
-      console.log('  compact-guidance block updated in AGENTS.md');
+    const syncOut = syncRepoSessionMarkers(projectRoot, packageRoot);
+    if (!syncOut.ok) {
+      console.error(`  Warning: session repo sync: ${syncOut.reason}`);
+    } else {
+      if (syncOut.compact.status === 'error') {
+        console.error(`  Warning: could not sync compact-guidance: ${syncOut.compact.message}`);
+      } else if (syncOut.compact.status === 'appended') {
+        console.log('  compact-guidance block added to AGENTS.md');
+      } else if (syncOut.compact.status === 'replaced') {
+        console.log('  compact-guidance block updated in AGENTS.md');
+      }
+      if (syncOut.testing.status === 'error') {
+        console.error(`  Warning: could not sync testing-policy: ${syncOut.testing.message}`);
+      } else if (syncOut.testing.status === 'created-file') {
+        console.log('  testing-policy: created .agents/testing.md');
+      } else if (syncOut.testing.status === 'appended' || syncOut.testing.status === 'written-empty') {
+        console.log('  testing-policy block added to .agents/testing.md');
+      } else if (syncOut.testing.status === 'replaced') {
+        console.log('  testing-policy block updated in .agents/testing.md');
+      }
     }
   } catch (err) {
-    console.error(`  Warning: could not sync compact-guidance: ${err.message}`);
+    console.error(`  Warning: session repo sync: ${err.message}`);
   }
 
   console.log('\n  Next steps:\n');
@@ -721,10 +765,13 @@ function update() {
     const hasOpenCodeDir = detectedIds.includes('opencode') ||
       fs.existsSync(path.join(globalOpenCodeDir(homeDir), 'skills')) ||
       fs.existsSync(path.join(projectRoot, '.opencode'));
+    const hasCodexFallback = detectedIds.includes('codex') ||
+      fs.existsSync(path.join(globalCodexDir(homeDir), 'skills'));
     selectedIDEs = [
       hasClaudeDir && '.claude',
       hasCursorDir && '.cursor',
       hasOpenCodeDir && '.opencode',
+      hasCodexFallback && '.codex',
     ].filter(Boolean);
     // Persist for future runs so detection only happens once
     if (selectedIDEs.length > 0) writeSelectedIDEs(selectedIDEs);
@@ -733,6 +780,7 @@ function update() {
   const hasClaudeDir = selectedIDEs.includes('.claude');
   const hasCursorDir = selectedIDEs.includes('.cursor');
   const hasOpenCodeDir = selectedIDEs.includes('.opencode');
+  const hasCodexDir = selectedIDEs.includes('.codex');
   const detectedIDEs = selectedIDEs;
 
   // Migration step: remove project-level artifacts — silent, non-destructive
@@ -745,6 +793,7 @@ function update() {
   const installedDirs = detectedIDEs.map((d) => {
     if (d === '.claude') return '~/.claude/skills/';
     if (d === '.cursor') return '~/.cursor/skills/';
+    if (d === '.codex') return '~/.codex/skills/';
     return '(opencode-global)/skills/';
   });
   console.log(`  ${count} skills updated in ${installedDirs.join(', ') || '(none detected)'}`);
@@ -755,6 +804,7 @@ function update() {
       hasClaudeDir && '~/.claude/agents/',
       hasCursorDir && '~/.cursor/agents/',
       hasOpenCodeDir && '(opencode-global)/agents/',
+      hasCodexDir && '~/.codex/agents/',
     ].filter(Boolean);
     console.log(`  ${agentsCount} sub-agents updated in ${agentDirs.join(', ')}`);
   }
@@ -789,6 +839,12 @@ function update() {
     }
   }
 
+  if (hasCodexDir) {
+    if (installHooks('.codex', homeDir)) {
+      console.log('  Hook check-update updated in ~/.codex/config.toml');
+    }
+  }
+
   try {
     const IDE_TO_IGNORE = { '.claude': '.claudeignore', '.cursor': '.cursorignore', '.opencode': '.opencodeignore' };
     const ignoreResult = syncIgnoreFiles(projectRoot, detectedIDEs);
@@ -806,14 +862,29 @@ function update() {
   }
 
   try {
-    const result = syncCompactGuidance(projectRoot, packageRoot);
-    if (result.status === 'appended') {
-      console.log('  compact-guidance block added to AGENTS.md');
-    } else if (result.status === 'replaced') {
-      console.log('  compact-guidance block updated in AGENTS.md');
+    const syncOut = syncRepoSessionMarkers(projectRoot, packageRoot);
+    if (!syncOut.ok) {
+      console.error(`  Warning: session repo sync: ${syncOut.reason}`);
+    } else {
+      if (syncOut.compact.status === 'error') {
+        console.error(`  Warning: could not sync compact-guidance: ${syncOut.compact.message}`);
+      } else if (syncOut.compact.status === 'appended') {
+        console.log('  compact-guidance block added to AGENTS.md');
+      } else if (syncOut.compact.status === 'replaced') {
+        console.log('  compact-guidance block updated in AGENTS.md');
+      }
+      if (syncOut.testing.status === 'error') {
+        console.error(`  Warning: could not sync testing-policy: ${syncOut.testing.message}`);
+      } else if (syncOut.testing.status === 'created-file') {
+        console.log('  testing-policy: created .agents/testing.md');
+      } else if (syncOut.testing.status === 'appended' || syncOut.testing.status === 'written-empty') {
+        console.log('  testing-policy block added to .agents/testing.md');
+      } else if (syncOut.testing.status === 'replaced') {
+        console.log('  testing-policy block updated in .agents/testing.md');
+      }
     }
   } catch (err) {
-    console.error(`  Warning: could not sync compact-guidance: ${err.message}`);
+    console.error(`  Warning: session repo sync: ${err.message}`);
   }
 
   console.log('\n  RESTART your IDE session to apply the changes.\n');
@@ -853,6 +924,17 @@ function clean() {
     console.error(`  Warning: could not remove OpenCode plugin: ${err.message}`);
   }
 
+  // Remove Codex global artifacts (skills + agents) and hooks
+  try {
+    removeCodexArtifacts(homeDir);
+    console.log('  Codex skills and agents removed from ~/.codex/');
+  } catch (err) {
+    console.error(`  Warning: could not remove Codex artifacts: ${err.message}`);
+  }
+  if (uninstallHooks('.codex', homeDir)) {
+    console.log('  SDD-AI hooks removed from ~/.codex/config.toml');
+  }
+
   // Clean project-level OpenCode artifacts if .opencode/ directory is present
   if (fs.existsSync(path.join(projectRoot, '.opencode'))) {
     try {
@@ -872,6 +954,15 @@ function clean() {
     console.error(`  Warning: could not clean compact-guidance: ${err.message}`);
   }
 
+  try {
+    const tp = removeTestingPolicyBlock(projectRoot);
+    if (tp.status === 'removed') {
+      console.log('  testing-policy block removed from .agents/testing.md');
+    }
+  } catch (err) {
+    console.error(`  Warning: could not clean testing-policy: ${err.message}`);
+  }
+
   console.log('  AGENTS.md, CLAUDE.md and .cursorrules were not removed.');
   console.log('\n  Note: if you have openspec/ in the repo, migrate first with: refacil-sdd-ai sdd status');
   console.log('  (the openspec/ → refacil-sdd/ migration is automatic on any sdd subcommand)');
@@ -883,19 +974,20 @@ function help() {
   const claudePath = globalClaudeDir(home);
   const cursorPath = globalCursorDir(home);
   const opencodePath = globalOpenCodeDir(home);
+  const codexPath = globalCodexDir(home);
 
   console.log(`
   refacil-sdd-ai — SDD-AI Methodology
 
   Commands:
-    init          Install skills globally for Claude Code, Cursor and/or OpenCode (interactive IDE selector).
-                  Use --all to install for all three IDEs without prompting.
+    init          Install skills globally for Claude Code, Cursor, OpenCode and/or Codex (interactive IDE selector).
+                  Use --all to install for all four IDEs without prompting.
                   Use --yes or --defaults to skip interactive branch config prompts.
                   Creates CLAUDE.md, .cursorrules and .opencode/opencode.json as appropriate.
                   Migrates any project-level artifacts to global dirs automatically.
     update        Re-copy skills for all detected IDEs to global user dirs
     migration-pending  Same validation as hooks/notify-update: list migrations (exit 1 if any; --json)
-    check-update   Sync skills and compact-guidance at session start (SessionStart hook)
+    check-update   Sync skills, compact-guidance (AGENTS.md), and testing-policy block (.agents/testing.md) at session start
     notify-update  Notify methodology migration only if applicable (UserPromptSubmit hook)
     check-review   Verify that review has been completed (used by PreToolUse hook)
     compact-bash  Rewrite bare Bash commands to reduce tokens (used by PreToolUse hook)
@@ -940,7 +1032,7 @@ function help() {
   Full flow:
     1. npm install -g refacil-sdd-ai
     2. refacil-sdd-ai init
-    3. RESTART your IDE session (Claude Code, Cursor, or OpenCode)
+    3. RESTART your IDE session (Claude Code, Cursor, OpenCode, or Codex)
     4. Run: /refacil:setup (generates AGENTS.md for your project)
 
   Global installation paths (this machine):
@@ -950,6 +1042,8 @@ function help() {
                    ${cursorPath}/hooks.json (hooks)
     - OpenCode:    ${opencodePath}/skills/, ${opencodePath}/agents/
                    ${opencodePath}/plugins/refacil-hooks.js
+    - Codex:       ${codexPath}/skills/, ${codexPath}/agents/
+                   ${codexPath}/config.toml (hooks)
 
   Requirements:
     - Node.js >= 20.0.0