refacil-sdd-ai 5.1.1 → 5.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Refacil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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`.
@@ -51,7 +51,14 @@ In each repo where you want to use the methodology, open the IDE and run:
 /refacil:setup
 ```
 
-This generates `AGENTS.md` and the `.agents/` project index for that repo. It is the only step required per repo. Skills will prompt you to run it if it has not been done yet.
+`/refacil:setup`:
+
+1. Scaffolds **`AGENTS.md`**, **`.agents/`**, **`refacil-sdd/changes/`**, and project branch configuration (everything the methodology needs for **this codebase**).
+2. Runs **`refacil-sdd-ai sync-repo-ide`** from the **repository root** so per-repo stubs and excludes match **your IDE selection from `init`** (`~/.refacil-sdd-ai/selected-ides.json`): **`CLAUDE.md`**, **`.cursorrules`**, **`.claudeignore`**, **`.cursorignore`**, **`.opencodeignore`**, plus **`compact-guidance`** / **`testing-policy`** markers when **`AGENTS.md`** / **`.agents/testing.md`** exist (same logic as **`init`** / **`update`** for those files).
+
+You can run **`refacil-sdd-ai sync-repo-ide`** manually anytime from the repo root (e.g. after changing IDE selection). It does **not** reinstall global skills — only repo-local files driven by **`selected-ides.json`** (with the same fallback detection as **`update`** when that file is missing).
+
+Skills will prompt you to run `/refacil:setup` if the repo index is missing.
 
 ### Adding a new IDE to an existing installation
 
@@ -91,6 +98,7 @@ npm uninstall -g refacil-sdd-ai
 |---|---|
 | `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 sync-repo-ide` | Repo-only: `CLAUDE.md`, `.cursorrules`, ignore files, compact-guidance + testing-policy markers — IDE list from `selected-ides.json` (same as `/refacil:setup` Step 4b–5). No global reinstall |
 | `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 global IDE user directories |
 | `refacil-sdd-ai help` | Show help |
@@ -190,13 +198,13 @@ refacil-sdd-ai sdd config --json
 
 ## 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
 
 | Skill | Usage |
 |---|---|
-| `/refacil:setup` | Generate AGENTS.md and the `.agents/` project index |
+| `/refacil:setup` | Generate AGENTS.md, `.agents/`, `refacil-sdd/changes/`, branch config; **`sync-repo-ide`** (stubs, ignores, session markers for IDEs chosen in **`init`**) |
 | `/refacil:guide` | Interactive guide on which command to use |
 | `/refacil:explore` | Explore the codebase without modifying anything |
 | `/refacil:propose` | Create a change proposal: proposal + specs + design + tasks |
@@ -227,7 +235,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 +324,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/hooks.json` | `session.created` handler in the global OpenCode plugin |
-| **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 |
 |---|---|
@@ -334,6 +342,8 @@ Installed during `init` / `update` for each selected IDE. The same four behavior
 
 > **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.
 
 ### Review gate on push
@@ -493,6 +503,11 @@ Skills, sub-agents, and hooks are installed into the user's global IDE directori
 ~/.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
@@ -502,15 +517,15 @@ Skills, sub-agents, and hooks are installed into the user's global IDE directori
 
 ### 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.
+The per-repo step is **`/refacil:setup`** once per project. It generates the **project index** (**`AGENTS.md`**, **`.agents/`**, **`refacil-sdd/changes/`**) and invokes **`refacil-sdd-ai sync-repo-ide`**, which writes **stub + ignore files** according to **`~/.refacil-sdd-ai/selected-ides.json`** (no need for `.claude/` / `.cursor/` folders in the repo). **Skills and hooks remain global**, not copied into the project.
 
 ```
-# Shared (IDE-agnostic)
-CLAUDE.md                    # Minimal index → points to AGENTS.md
-.cursorrules                 # Cursor format equivalent of CLAUDE.md
-.claudeignore                # Base exclusions (node_modules, dist, .env, *.key, etc.)
-.cursorignore                # Same content as .claudeignore
-.opencodeignore              # Same content as .claudeignore
+# Shared — project index from /refacil:setup; stubs + ignores from sync-repo-ide / selected IDE list
+CLAUDE.md                    # Minimal index → AGENTS.md (if Claude Code is in your IDE selection)
+.cursorrules                 # Same role for Cursor if Cursor is selected
+.claudeignore                # Base exclusions (node_modules, dist, .env, …) when Claude is selected
+.cursorignore                # Same template as .claudeignore when Cursor is selected
+.opencodeignore              # Same when OpenCode is selected
 AGENTS.md                    # Project index → generated by /refacil:setup
                              # Points to .agents/ + includes auto-managed blocks
                              # (compact-guidance and bus presentation)
@@ -532,6 +547,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