refacil-sdd-ai 5.2.2 → 5.3.0

package/skills/explore/SKILL.md

@@ -29,10 +29,42 @@ Before delegating, check the current session conversation context for a prior co
   Wait for the user's answer before proceeding.
 - **If there is no prior exploration** (or it is on a clearly different topic): continue to Step 1 without interruption.
 
+### Step 0.2: CodeGraph availability check
+
+Run `refacil-sdd-ai codegraph status --json` and parse the output. Set `codegraphAvailable`:
+- `true` if `installed === true` AND `initialized === true`
+- `false` otherwise
+
+**If `mode` is `enabled` or `per-repo` but `codegraphAvailable` is `false`**:
+
+---
+
+**[GATE — STOP AND WAIT: CodeGraph not indexed]**
+
+Do NOT proceed to Step 1. Do NOT delegate to the sub-agent. STOP and ask the user exactly this, then wait for their reply:
+
+```
+CodeGraph is enabled for this repo but not yet indexed (~30s to build).
+Without it, the exploration uses Grep/Read — slower and less precise for call-graph questions.
+
+Do you want me to run /refacil:update first to build the index?
+  yes → run /refacil:update then continue with the exploration
+  no  → continue with standard exploration now
+```
+
+Only after the user replies:
+- **"yes"** (or "si", "dale", "sí", "go", "ok"): immediately execute `/refacil:update`. Do not describe it in text.
+- **"no"** (or "skip", "continue", "continúa", "así"): set `codegraphAvailable: false` and proceed to Step 1.
+
+---
+
+**If `mode` is `disabled` or `null`**: set `codegraphAvailable: false` and continue to Step 1 without asking.
+
 ### Step 1: Delegate to the refacil-investigator sub-agent
 
 Invoke the `refacil-investigator` sub-agent passing it:
 - The user's question (`$ARGUMENTS`).
+- `codegraphAvailable: true | false` (from Step 0.2).
 - If the user explicitly requested detailed mode, indicate it (`mode: detailed`). Default: concise.
 
 The sub-agent:
@@ -41,6 +73,20 @@ The sub-agent:
 - Detects cross-repo dependencies and, if appropriate, consults the bus according to `refacil-prereqs/BUS-CROSS-REPO.md`.
 - Returns a report with architecture, flows, dependencies, and next-step recommendations.
 
+### Step 1.5: Log CodeGraph telemetry (silent)
+
+After the sub-agent completes, run **once** (do not mention it to the user unless it fails):
+
+```bash
+refacil-sdd-ai compact log-codegraph-event --skill investigator --has-graph <true|false> --tool-calls <N> --tokens <N>
+```
+
+- `--has-graph`: the `codegraphAvailable` value from Step 0.2.
+- `--tool-calls`: number of `codegraph_*` tool calls the sub-agent made (0 if it did not use the graph).
+- `--tokens`: conservative estimate of tokens saved vs. reading whole files (~800–1500 per useful tool call; 0 if no graph or no calls).
+
+If the command fails, ignore it; it must not block the flow.
+
 ### Step 2: Present the report
 
 Show the user the full report returned by the sub-agent. There are no artifacts to write — exploration is purely analytical.
@@ -60,7 +106,8 @@ The sub-agent already includes recommendations at the end of its report. Apply t
 - **Always delegate to the sub-agent**. Do not replicate the exploration logic here.
 - **Do not invoke without a question**. If `$ARGUMENTS` is empty, ask for the question first.
 - **Do not write files**. Exploration is read-only end-to-end.
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately invoke the **Skill tool** with the exact name resolved from the sub-agent's finding. Deterministic resolution:
+- **CodeGraph gate (Step 0.2)**: if `mode` is `enabled`/`per-repo` and `codegraphAvailable` is `false`, the GATE is **mandatory** — never skip it. If the user replies affirmatively ("yes", "si", "sí", "dale", "ok", "go"), immediately execute `/refacil:update` without any prior text. Do not describe it. Do not ask again. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately execute the resolved `/refacil:<skill>` command. Deterministic resolution:
 
   | Finding | Skill |
   |---------|-------|

package/skills/guide/SKILL.md

@@ -20,7 +20,9 @@ You are a **brief** guide: you choose the next command; the detail of each flow
 
 ## Menu
 
-1. New feature → `/refacil:propose` → `/refacil:apply` → `/refacil:test` → `/refacil:verify` → `/refacil:review` → `/refacil:archive` → `/refacil:up-code`
+1. New feature → `/refacil:propose` → *(optional)* `/refacil:read-spec` → then choose implementation:
+   - **Step-by-step (A):** `/refacil:apply` → `/refacil:test` (suite + coverage) → `/refacil:verify` (CA/CR; no full re-test by default) → `/refacil:review` (checklist; no suite) → `/refacil:archive` → `/refacil:up-code`
+   - **Autonomous (B):** `/refacil:autopilot` — chains apply → test → verify → review → archive in one invocation; up-code (push + PR) is optional and configured in pre-flight (the user chooses whether to end at archive or continue with up-code); optional WhatsApp via `refacil-sdd-ai kapso setup`
 2. Bug → `/refacil:bug` → `/refacil:review` → `/refacil:archive` → `/refacil:up-code`
 3. Explore → `/refacil:explore`
 4. Tests → `/refacil:test`
@@ -30,12 +32,23 @@ You are a **brief** guide: you choose the next command; the detail of each flow
 8. Configure repo → `refacil-sdd-ai init` (global + per repo) and `/refacil:setup`
 9. Migrate documentation to current pattern → `/refacil:update`
 10. Coordinate with other repos (without manual copy/paste) → see **Bus between agents** block below
+11. Autonomous pipeline (after approved propose) → `/refacil:autopilot` — same chain as option 1 path B; use when you want autonomous execution ("autopilot", "modo autónomo", "termina solo el flujo"). During pre-flight you define whether up-code (push + PR) is included — the cycle adapts and can end at archive or continue with up-code.
+12. Listen to specs with voice (TTS) → `/refacil:read-spec` — on-device browser playback; post-propose option B in propose, or on-demand for active changes / archived specs (`refacil-sdd-ai read-spec --change <name>`)
+13. Change progress and metrics → `/refacil:stats` — task completion, review gate, test commands from `memory.yaml` (`refacil-sdd-ai sdd stats <changeName>`)
 
 > **Note**: `up-code` verifies `.review-passed` before push; see `METHODOLOGY-CONTRACT.md §5-6` for details.
 
+> **Skill parity**: 21 user-invocable skills (`user-invocable: true`, excluding internal `prereqs`) must appear in `SKILLS[]`, this menu, and the README "Available IDE Skills" table — including `read-spec` and `stats`.
+
+### After `/refacil:propose` is approved
+
+- **`/refacil:read-spec`** (optional): opens the change folder in the browser and reads proposal, design, tasks, and specs aloud in order — useful before choosing implementation.
+- **`/refacil:apply`** (path A): step-by-step; each phase pauses for confirmation.
+- **`/refacil:autopilot`** (path B): fully autonomous; path B is independent — it runs review, archive, and optionally up-code internally. During pre-flight the user configures whether up-code is included (cycle ends at archive or at a PR). Does not merge into path A.
+
 ## Bus between agents (refacil-bus)
 
-For when the dev has multiple Claude Code / Cursor windows open (one per repo) and needs agents to consult each other without the dev being the manual transcriber:
+For when the dev has multiple IDE sessions open (one per repo) and needs agents to consult each other without the dev being the manual transcriber:
 
 | Command | When to use |
 |---------|-------------|
@@ -58,22 +71,27 @@ Full detail in the refacil-sdd-ai README (section `refacil-bus`).
 
 ## Tips (one line per tool)
 
-- **Claude Code:** `/refacil:*` commands in the chat.
-- **Cursor:** `/refacil:*` commands in Composer; `@` for context files.
+- **IDE chat / composer:** `/refacil:*` commands in the chat or composer panel.
+- **Listen to specs:** `/refacil:read-spec` or `refacil-sdd-ai read-spec --change <changeName>` — local TTS only, no remote APIs.
+- **Hands-off implementation:** `/refacil:autopilot [changeName]` after propose is approved — in pre-flight you choose whether up-code (push + PR) is included. Configure Kapso once with `refacil-sdd-ai kapso setup` for WhatsApp notification on finish.
 
 ## Rules
 
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) to the continuity question in step 4 of Instructions, immediately invoke the **Skill tool** with the exact name resolved from the menu option you recommended. Deterministic resolution by Menu option:
-  - Option 1 (New feature) → `skill: "refacil:propose"`
-  - Option 2 (Bug) → `skill: "refacil:bug"`
-  - Option 3 (Explore) → `skill: "refacil:explore"`
-  - Option 4 (Tests) → `skill: "refacil:test"`
-  - Option 5 (Validate implementation) → `skill: "refacil:verify"`
-  - Option 6 (Quality review) → `skill: "refacil:review"`
-  - Option 7 (Push code and create PR) → `skill: "refacil:up-code"`
-  - Option 8 (Configure repo) → `skill: "refacil:setup"`
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) to the continuity question in step 4 of Instructions, immediately execute the resolved `/refacil:<skill>` command. Deterministic resolution by Menu option:
+  - Option 1 (New feature) → `/refacil:propose`
+  - Option 2 (Bug) → `/refacil:bug`
+  - Option 3 (Explore) → `/refacil:explore`
+  - Option 4 (Tests) → `/refacil:test`
+  - Option 5 (Validate implementation) → `/refacil:verify`
+  - Option 6 (Quality review) → `/refacil:review`
+  - Option 7 (Push code and create PR) → `/refacil:up-code`
+  - Option 8 (Configure repo) → `/refacil:setup`
   - Option 9 (Migrate documentation) → `skill: "refacil:update"`
   - Option 10 (Bus between agents) → `skill: "refacil:join"` (or another from the group `refacil:say`/`refacil:ask`/`refacil:reply`/`refacil:attend`/`refacil:inbox` depending on the expressed intent).
+  - Option 11 (Autonomous pipeline) → `/refacil:autopilot`
+  - Option 12 (Listen to specs) → `/refacil:read-spec`
+  - Option 13 (Change progress) → `/refacil:stats`
+  - Post-propose context with a single clear next step: if artifacts are approved and the user wants hands-off → `/refacil:autopilot`; if they want to hear specs first → `/refacil:read-spec`; if they want step-by-step → `/refacil:apply`.
   - If the intent does not map exactly to an option, do NOT invoke — list numbered options to the user and ask for explicit selection.
 
   Do not describe it in text or wait for the user to type the command. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/inbox/SKILL.md

@@ -31,6 +31,15 @@ The CLI prints the new messages (if any) with `from`, `kind`, text, and timestam
 
 Present the new messages clearly and, if applicable, propose the next step.
 
+## What appears in the inbox
+
+The inbox for this session shows **only**:
+
+1. **`ask` messages directed to this session** — sent by another session with `bus ask --to [this-session]` or `bus ask --to all`.
+2. **`reply` messages to your own `correlationId`** — responses to questions you sent with `bus ask`.
+
+**`say` (broadcast) messages from other sessions do NOT appear in this session's inbox.** `say` is a real-time broadcast only; sessions that were not connected when the `say` was sent will never see it in the inbox. For content that must be received and acted on, use `bus ask --to SESSION` instead.
+
 ## When to use `/refacil:inbox`
 
 - After a `/refacil:ask --wait N` expired without a response — to check if it arrived later.

package/skills/join/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refacil:join
-description: Join (or create) an agent bus room to communicate with Claude Code / Cursor sessions in other repos. Session name = repo folder name.
+description: Join (or create) an agent bus room to communicate with Claude Code, Cursor, OpenCode, or Codex sessions in other repos. Session name = repo folder name.
 user-invocable: true
 ---
 

package/skills/prereqs/BUS-CROSS-REPO.md

@@ -34,9 +34,9 @@ When the skill's trigger is met:
 
 1. **Verify active rooms**: run `refacil-sdd-ai bus rooms` to see the rooms and their members.
 2. **Evaluate preconditions**:
-   - **If there is an active room AND the repo you need to consult is already in it**: you can run `/refacil:ask @<repo-name> "..." --wait 180` directly. **Inform the user before sending** ("I'm going to ask @X in room Y: ..."). If the other repo is in `/refacil:attend` it responds automatically; if not, the dev goes to that window and runs `/refacil:inbox`.
+   - **If there is an active room AND the repo you need to consult is already in it**: you can run `/refacil:ask @[repo-name] "..." --wait 180` directly. **Inform the user before sending** ("I'm going to ask @X in room Y: ..."). If the other repo is in `/refacil:attend` it responds automatically; if not, the dev goes to that window and runs `/refacil:inbox`.
    - **If the `ask` is a change request** in the destination repo (not just an informational question), draft **concrete scope and criteria**; the destination session already operates under SDD-AI (joined with `/refacil:join`) and should channel the work with **`/refacil:propose`** there without you repeating the guide in the message. See `/refacil:ask` Step 1.5 and the "Room agreements" section below.
-   - **If there is no room, or the repo you need is not in any**: **do not create the room on your own**. Ask the user to run `/refacil:join <room-name>` in **this** session and also in the other repo's session (another IDE window). Both repos must be in the same room. Once confirmed, return to step 2.
+   - **If there is no room, or the repo you need is not in any**: **do not create the room on your own**. Ask the user to run `/refacil:join [room-name]` in **this** session and also in the other repo's session (another IDE window). Both repos must be in the same room. Once confirmed, return to step 2.
 
 If the user does not know the bus or does not know how to configure it, refer them to `/refacil:guide` (section "Bus between agents") before attempting the consultation.
 
@@ -53,24 +53,24 @@ Avoid vague requests like "check this integration". Prefer concrete contract que
 Recommended ask template (integration clarification):
 
 ```text
-integrationPoint: <endpoint/event/queue + direction>
-inputContract: <fields + validations>
-outputContract: <outputs/status/errors>
-compatibility: <version/constraints or unknown>
-sourceOfTruthRequest: <where to confirm in destination repo>
-question: <concrete doubt>
+integrationPoint: [endpoint/event/queue + direction]
+inputContract: [fields + validations]
+outputContract: [outputs/status/errors]
+compatibility: [version/constraints or unknown]
+sourceOfTruthRequest: [where to confirm in destination repo]
+question: [concrete doubt]
 ```
 
 Recommended reply template:
 
 ```text
-integrationPoint: <confirmed value>
-inputContract: <confirmed value>
-outputContract: <confirmed value>
-compatibility: <confirmed value or unknown>
-sourceOfTruth: <file/path/symbol in destination repo>
-confidence: <high|medium|low>
-openQuestions: <none | unresolved items>
+integrationPoint: [confirmed value]
+inputContract: [confirmed value]
+outputContract: [confirmed value]
+compatibility: [confirmed value or unknown]
+sourceOfTruth: [file/path/symbol in destination repo]
+confidence: [high|medium|low]
+openQuestions: [none | unresolved items]
 ```
 
 These templates support both first-pass clarification and retry loops.
@@ -97,10 +97,27 @@ If in the room (via `say` messages, `ask`/`reply` threads, or a mix) **agreement
 **Closing with the requester**: whoever **implements** here, upon finishing the agreed change (or reaching a clear state: done, PR, blocked, delegated), **must notify via bus** whoever originated the request or the room as appropriate:
 
 - If the work originated from an **`ask`** to this session and the context is still the same thread: **`/refacil:reply`** with the summary (the broker links `correlationId`).
-- If the agreement was via **`say`**, there are multiple interlocutors, or the same `ask` no longer applies: **`/refacil:ask @<requesting-session> "..."`** with the closing, or **`/refacil:say`** if the closing should be visible to the **entire** room.
+- If the agreement was via **`say`**, there are multiple interlocutors, or the same `ask` no longer applies: **`/refacil:ask @[requesting-session] "..."`** with the closing, or **`/refacil:say`** if the closing should be visible to the **entire** room.
 
 By default: **do not close silently** when another session was waiting for the result of the agreement.
 
+## Hard rule: `ask` + `reply` for contracts and agreements (never `say`)
+
+**Contract agreements, change requirements, bug reports, and any notification the recipient must process MUST be sent as `bus ask --to SESSION`, never as `bus say`.**
+
+Reasons:
+- `say` is a real-time broadcast. Sessions that join the room after the `say` was sent **will never see it** — it does not appear in the inbox.
+- `say` provides no delivery confirmation per recipient and cannot be part of a `correlationId` thread.
+- Only `ask` + `reply` guarantees that the message is stored in the recipient's inbox, linked by `correlationId`, and retrievable via `/refacil:inbox` at any time.
+
+Apply this rule to:
+- Any content the destination agent must act on (implement, review, confirm, fix)
+- Contract agreements between services
+- Close/done notifications for work items another session was waiting for
+- Bug reports that require work in another repo
+
+`say` remains valid for **optional real-time announcements** with no required response (e.g., "restarting the service", "finished my phase"). Do not use `say` as a substitute for `ask` when acknowledgment or action is required.
+
 ## What NOT to do
 
 - Do not assume the other repo's behavior without consulting.

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -5,10 +5,10 @@ This file centralizes cross-cutting rules to avoid duplication and inconsistenci
 ## §1 — Flow states (Definition of Ready / Done)
 
 - **READY_FOR_PROPOSE**: problem understood (objective, scope, constraints) and minimum repo context.
-- **READY_FOR_APPLY**: complete SDD artifacts (`proposal.md`, `design.md`, `tasks.md`, specification in `specs.md` and/or `specs/**/*.md`) and explicit user approval.
-- **READY_FOR_VERIFY**: implementation finished, no changes outside scope.
-- **READY_FOR_REVIEW**: for regular changes (propose), verify executed and critical issues resolved or accepted by the user. For bug fixes, the implementation and regression tests are complete (bugs do not go through verify).
-- **READY_FOR_ARCHIVE**: review approved (`.review-passed` exists), tasks complete or exceptions approved, change functionally closed.
+- **READY_FOR_APPLY**: complete SDD artifacts (`proposal.md`, `design.md`, `tasks.md`, specification in `specs.md` and/or recursive `specs/**/*.md`) and explicit user approval. Empty `specs/` folders do not count as specs.
+- **READY_FOR_VERIFY**: implementation finished, no changes outside scope; **`/refacil:test`** should have run (or user accepts running verify without test memory — see §3.2 CR-01).
+- **READY_FOR_REVIEW**: for regular changes (propose), verify executed (CA/CR validation; tests delegated to test phase by default per §3.2) and critical issues resolved or accepted by the user. For bug fixes, the implementation and regression tests are complete (bugs do not go through verify).
+- **READY_FOR_ARCHIVE**: review approved (`.review-passed` exists), tasks complete or approved `fix-*` exception, current `/refacil:test` evidence available unless explicitly accepted in normal mode, change functionally closed.
 - **READY_FOR_MERGE**: review approved (`.review-passed` exists) and integration ready: PR created for the target branch. `/refacil:up-code` automatically verifies the review before push — if missing, it runs it.
 - If multiple active changes exist without review, the target change must be explicitly selected before running review/push.
 
@@ -17,26 +17,30 @@ This file centralizes cross-cutting rules to avoid duplication and inconsistenci
 - If a skill requires the `sdd` profile: `AGENTS.md` is mandatory (if missing, stop and redirect to `/refacil:setup`).
 - If a skill requires the `agents` profile: if `AGENTS.md` is missing, continue with a generic baseline and report the limitation to the user.
 
-## §3 — Test command resolution (multi-stack)
+## §3 — Test command resolution (multi-stack, component-bounded)
 
-Do not hardcode `npm test` unless it is genuinely the project's command.
+**Component principle (language-agnostic)**: a *component* is the nearest independent unit with its own test setup — the closest ancestor directory (walking up from each changed file, bounded by the repo root) that contains a stack manifest (`package.json`, `go.mod`, `pyproject.toml`/`setup.py`/`pytest.ini`, `Cargo.toml`, `pom.xml`/`build.gradle`(.kts), `global.json`/`Directory.Build.props`, etc.). The `refacil-sdd-ai sdd test-scope` tool (`affectedComponents()`) exposes this automatically.
 
-Detection order:
-1. If `AGENTS.md` defines the official test command, use that.
-2. If a package manager script exists (e.g. `npm test`, `pnpm test`, `yarn test`, `bun test`), use the corresponding one.
+**All test execution is component-bounded**: no phase ever runs tests across the entire monorepo. `testScope: scoped` runs the narrowed tests of the affected component(s); `testScope: full` runs the full suite of each affected component (never all packages). The component root is the working directory for test commands in that component.
+
+Do not hardcode any specific runner (e.g. `npm test`) unless it is genuinely the project's command. Resolve the command language-agnostically:
+
+Detection order (applied at the **component root**, not the monorepo root):
+1. If `AGENTS.md` defines the official test command for this component, use that.
+2. If a package manager script exists at the component root (e.g. `npm test`, `pnpm test`, `yarn test`, `bun test`, `poetry run pytest`, etc.), use the corresponding one.
 3. If Python: `pytest`.
 4. If Go: `go test ./...`.
 5. If Rust: `cargo test`.
 6. If Java/Gradle: `./gradlew test` or `gradle test`.
 7. If Java/Maven: `mvn test`.
 
-Coverage (if applicable): detect the project command (`test:cov`, `coverage`, `pytest --cov`, etc.). If it does not exist, report N/A with justification.
+Coverage (if applicable): detect the project command at the component root (`test:cov`, `coverage`, `pytest --cov`, etc.). If it does not exist, report N/A with justification.
 
-### §3.1 — Scoped test execution (default for `/refacil:test`, `/refacil:verify`, `/refacil:apply`, and debugger fix mode)
+### §3.1 — Scoped test execution (default for `/refacil:test`, `/refacil:apply`, and debugger fix mode; optional in `/refacil:verify` per §3.2)
 
 **Goal**: avoid high RAM/CPU from **full-repo** suites and **repo-wide** coverage on every SDD step. Defaults exercise **tests + coverage only for what the change touches**; full regression stays **on-demand** (explicit skill arguments or unavoidable fallback).
 
-**Also applies**: `/refacil:apply` (implementer verification step) and `/refacil:bug` (debugger `mode=fix`) — wrappers pass `testScope` and a **`testCommand` already narrowed** when `scoped`, same rules as rows in the table below.
+**Also applies**: `/refacil:apply` (implementer verification step) and `/refacil:bug` (debugger `mode=fix`) — wrappers pass `testScope` plus the raw §3 baseline command. The write-capable sub-agent derives the scoped smoke after editing from the files it actually touched; the wrapper must not precompute a stale narrowed command.
 
 | Briefing field | Values | Default |
 |----------------|--------|---------|
@@ -46,12 +50,13 @@ Coverage (if applicable): detect the project command (`test:cov`, `coverage`, `p
 **Rules**
 
 1. **`testScope: scoped`** (default): sub-agents run tests **only** for artifacts tied to the current change — never invoke the §3 baseline in **full-repo / full-suite** form without narrowing (paths, packages, filters, patterns), except the explicit fallbacks below.
-2. **`testScope: full`**: **on-demand only** — user explicitly requests whole-suite regression in **`/refacil:test`** (or `/refacil:verify`) arguments (e.g. `full`, `all tests`, `whole suite`, `suite completa`). Then use the §3 baseline test command **without** path narrowing and, if coverage runs, use the project’s **normal** coverage entrypoint without narrowing collection to the diff (unless `AGENTS.md` defines otherwise).
+2. **`testScope: full`**: **on-demand only** — user explicitly requests whole-suite regression in **`/refacil:test`** (or `/refacil:verify`) arguments (e.g. `full`, `all tests`, `whole suite`, `suite completa`). Resolve the §3 baseline command language-agnostically at each **affected component root** and run it from that component dir (`cd <component> && <baseline>`). Never run all monorepo packages — only the component(s) whose files changed. If multiple components are affected, run each in sequence. Coverage = component-wide (not repo-wide).
 3. **`runCoverage: true`** (default): after scoped tests pass, run coverage **narrowed to the change** — instrument/collect only for **`filesToTest`**, **`changedFiles`**, and companion test/spec paths tied to those modules (examples: `--cov=pkg/sub`, Jest `--collectCoverageFrom` globs limited to touched trees, Gradle/JaCoCo scoped modules). If the toolchain cannot narrow, report **N/A** plus a WARNING; do **not** silently widen to repo-wide coverage while `testScope` remains `scoped`.
 4. **`runCoverage: false`**: skip coverage entirely — only when the user **explicitly** opts out (`no coverage`, `nocoverage`, `skip coverage`, `sin cobertura`, etc.) or the project defines **no** coverage command under §3.
 5. **`runCoverage: true` + `testScope: full`**: run the project coverage command **after** the full suite passes, using the repo’s usual global/module coverage behavior (heavy — intended only when the user requested `full`).
-6. **`/refacil:apply` / implementer**: the apply wrapper supplies `testScope` (default `scoped`) and **`testCommand`**. Implementer runs **only** `testCommand` for Step verification — no repo-wide substitution. Coverage is optional in that step unless the briefing adds an explicit coverage command (unusual; defer to `/refacil:test`).
+6. **`/refacil:apply` / implementer**: the apply wrapper supplies `testScope` (default `scoped`) and **`testBaselineCommand`**. After editing, the implementer runs `refacil-sdd-ai sdd test-scope --files <touched-files-csv> --baseline "<testBaselineCommand>"` and executes the returned smoke command. The implementer **NEVER runs the full repo/package baseline** as the apply verification step — the "unreliable scope → run baseline once" escape hatch in §3.1 Scoped command patterns does NOT apply here. Fallback behaviour: if `test-scope` returns `fallback: true`, fails, or there are no touched files, run only the touched files that are themselves test files; if none exist, **SKIP verification** and add a LOW `issues` entry deferring to `/refacil:test`. Also applies: the wrapper must not precompute a stale narrowed command. Coverage is optional in that step unless the briefing adds an explicit coverage command (unusual; defer to `/refacil:test`).
 7. **`/refacil:bug` / debugger `mode=fix`**: debugger defaults to **`scoped`**, narrows §3 baseline to **`filesModified` ∪ new/updated regression test files** unless the wrapper passed **`testScope: full`**.
+8. **Re-run / fix-loop (pass-2)**: when iterating on failing tests, run **only the previously-failing test files** — not the entire component suite. This keeps fix loops fast and bounded.
 
 **Scoped command patterns** (language-agnostic — sub-agent reads `AGENTS.md`, build config, and tool docs; run from the correct module/root):
 
@@ -60,7 +65,78 @@ Coverage (if applicable): detect the project command (`test:cov`, `coverage`, `p
 - **Scoped coverage**: combine the same narrowing with coverage flags/includes that limit **report collection** to touched sources (runner-specific); exclude unrelated packages by default when `testScope: scoped`.
 - **Unreliable scope**: if narrowing cannot be done safely, run the baseline §3 command **once**, report a brief WARNING that the run may be heavy, and suggest CI or **`/refacil:test ... full`** for full regression.
 
-**Verify**: Prefer `commandsRun` from `get-memory` (same invocation as `/refacil:test` when present). Else derive scoped targets from `changedFiles` and/or `git diff --name-only`, using **project test naming and layout** (`AGENTS.md`, test config): e.g. co-located `*Spec.*` / `*Test.*`, `tests/`, language-specific suffices — not a fixed extension.
+**Verify (when `testExecution: full`)**: Prefer `commandsRun` from `get-memory` as reference only when re-running; else derive scoped targets from `changedFiles` and/or `git diff --name-only`, using **project test naming and layout** (`AGENTS.md`, test config): e.g. co-located `*Spec.*` / `*Test.*`, `tests/`, language-specific suffices — not a fixed extension.
+
+### §3.2 — Phase ownership (test execution)
+
+**Goal**: run the **full** scoped (or full-suite) test + coverage pipeline **once per cycle** in `/refacil:test`. Later phases validate specs and quality **without** repeating that pipeline unless the user explicitly requests it or test memory is missing.
+
+| Phase | Runs tests? | Coverage? | Writes `memory.commandsRun`? |
+|-------|-------------|-----------|--------------------------------|
+| `/refacil:apply` | Scoped post-implementation check only (pre-test) | Unusual; defer to test | No |
+| `/refacil:test` | **Yes** — canonical suite for the change | **Yes** (scoped by default) | **Yes** |
+| `/refacil:verify` | **No by default** (`testExecution: none`) | No | No (reads memory) |
+| `/refacil:review` | **No** (checklist + file reads) | No | No |
+| Corrections after verify/review | **Smoke only** or defer to `/refacil:test` | No | No |
+
+**Briefing field `testExecution`** (verify wrapper → validator):
+
+| Value | When | Validator behavior |
+|-------|------|-------------------|
+| `none` | Default if `memory.lastStep` is `test` (or later) and `commandsRun` is non-empty; user did not force re-run | **Do not** run `testCommand` or `coverageCommand`. Tests section = **delegated to test phase**; cite last `commandsRun`. |
+| `smoke` | After surgical corrections in verify Step 5 (or rare review fix) | Run **only** companion test files for `correctionTouchedFiles`. **No** `coverageCommand`. |
+| `full` | User tokens (`full`, `re-run tests`, `run tests`, …) **or** CR-01 (no test memory) | Same as §3.1: `testCommand` + optional narrowed/full coverage per `testScope` / `runCoverage`. |
+
+**Smoke definition**: the smallest test invocation that exercises files touched by a **correction** (not the whole change). Derive companion paths from project layout (`*Spec*`, `*Test*`, `tests/`, etc.). Smoke **does not** satisfy coverage gates or replace `/refacil:test`.
+
+**After corrections** (verify Step 5 or review Step 3.5): prefer `testExecution: none` + tell the user to run **`/refacil:test`** before the next full verify; or `smoke` once on correction files. **Never** use `full` in autofix re-verify unless the user explicitly requested it in the same invocation.
+
+**Review checklist “tests pass”**: PASS when test files exist for the diff, `memory.criteriaRun` covers relevant CA/CR, and static review finds no obvious breakage — **without** running the §3 baseline via Bash unless the user explicitly asked.
+
+## §3C — 3C Criterion: Completeness, Correctness, Coherence
+
+The **3C criterion** is the authoritative framework for evaluating implementations. It is applied by the `refacil-validator` sub-agent during `/refacil:verify` and referenced by the `refacil-auditor` during `/refacil:review`. All three dimensions must be assessed; missing one dimension is itself a WARNING.
+
+### Dimension 1 — Completeness (is everything implemented?)
+
+**Question**: Does the implementation cover all tasks and all scope files listed in the briefing?
+
+Operational checks:
+- Every task in `tasks.md` (or the briefing's task list) has a corresponding code artifact.
+- Every file in `scope.create` exists and has substantive content coherent with the objective.
+- Every file in `scope.modify` was actually modified with changes relevant to the task.
+- No mandatory scope file is missing or is an empty scaffold.
+
+### Dimension 2 — Correctness (is it correctly implemented?)
+
+**Question**: Does each implemented artifact satisfy the CA/CR criteria from the specs?
+
+Operational checks:
+- For each CA-XX: verify the implementation satisfies the criterion by reading the relevant scope files.
+- For each CR-XX: verify that edge cases and rejection conditions are handled.
+- Behavior matches the spec intent — not just surface text.
+
+### Dimension 3 — Coherence (is it consistent with the architecture?)
+
+**Question**: Do the new or modified files fit the established patterns without introducing inconsistencies?
+
+Operational checks:
+- New files follow naming, structure, and module conventions from `architectureContext` (or `AGENTS.md`).
+- No files outside `scope.doNotTouch` were modified.
+- Patterns introduced are consistent with existing ones in the same module or layer.
+- If `codegraphAvailable: true` in the briefing: use `codegraph_context` or `codegraph_search` on `changedFiles` to verify architectural coherence. If not available, continue with direct file reading.
+
+### Severity table
+
+| Severity | Completeness | Correctness | Coherence |
+|----------|-------------|-------------|-----------|
+| CRITICAL | Mandatory task or `scope.create` file missing entirely | Mandatory CA not met; spec contract broken | Files in `scope.doNotTouch` modified |
+| WARNING | Partial implementation of a task; `scope.modify` file unchanged | Regression risk; CR edge case not handled | Pattern deviation; naming inconsistency |
+| SUGGESTION | Optional improvement not covered | Improvable edge case handling | Better alignment opportunity |
+
+### Graceful degradation rule
+
+If the briefing does not include `criteria` (CA/CR list), infer the criteria by reading `refacil-sdd/changes/<changeName>/specs.md` or `specs/**/*.md`. If there are no specs either, apply **only Dimension 1 (Completeness)** and document the limitation as a WARNING in the report. Never block verification entirely due to missing specs — degrade gracefully.
 
 ## §4 — Protected branch policy and branch creation
 
@@ -149,7 +225,7 @@ If the user does not request detail, use concise mode.
 - When there are **multiple valid next steps** (real branching), list numbered options and ask for explicit selection.
 - If the current step is **terminal** (end of flow, e.g. PR created), close without asking for the next skill.
 
-**Operative rule (mandatory)**: if the user confirms affirmatively ("yes", "ok", "go", "continue", "sure", etc.) to the continuity question, **directly invoke the next skill via the Skill tool** in the same turn. Do not ask the user to type `/refacil:X` or repeat the context — the session must continue without friction.
+**Operative rule (mandatory)**: if the user confirms affirmatively ("yes", "ok", "go", "continue", "sure", etc.) to the continuity question, **directly execute the next `/refacil:<skill>` command** in the same turn. Do not ask the user to type it or repeat the context — the session must continue without friction.
 
 ## §6 — Review and push scope
 
@@ -160,6 +236,9 @@ If the user does not request detail, use concise mode.
 ## §7 — Review evidence persistence
 
 - `archive` requires `.review-passed` as a blocking precondition (verify existence according to **§8**).
+- Regular changes require the proposal artifact set before apply/archive readiness: `proposal.md`, `design.md`, `tasks.md`, and specs from non-empty `specs.md` and/or recursive non-empty `specs/**/*.md`. The same source set must be used by `sdd status`, `sync-spec`, test/verify criteria extraction, and archive.
+- Operational bug fixes created by `/refacil:bug` are the exception: `fix-*` changes may archive without proposal artifacts when they include `summary.md`, regression test evidence, and `.review-passed`. Archive must document the resulting behavior under `refacil-sdd/specs/` with `review.yaml`.
+- Archive must use current `/refacil:test` evidence from `memory.yaml` instead of re-running tests by default. If evidence is missing or stale, normal mode asks the user to run `/refacil:test` or explicitly continue; autopilot mode aborts to preserve the contract without hidden broad test execution.
 - When archiving regular changes (proposal-driven flow), the `.review-passed` metadata must be persisted in `refacil-sdd/specs/`.
 - `archive` must request and persist at least one task reference for traceability. Accepted formats: URL, ticket/issue identifier, or short task name.
 - The recommended field in `review.yaml` is `taskReferences` (YAML list). Do not enforce provider-specific fields such as `jiraTasks`.
@@ -174,7 +253,7 @@ If the user does not request detail, use concise mode.
 
 ## §9 — Folder identifier under `refacil-sdd/changes/<change>/`
 
-- The **folder name** of the active change is the identifier used by the refacil-sdd CLI (`refacil-sdd status --change`, archive flows, etc.).
+- The **folder name** of the active change is the identifier used by the refacil-sdd CLI (`refacil-sdd-ai sdd status <change>`, archive flows, etc.).
 - **Must start with an ASCII letter** `[a-zA-Z]`. If the first character is a digit or other symbol, the CLI rejects the name (e.g. `Invalid change name: Change name must start with a letter`).
 
 ## §10 — Language policy

package/skills/prereqs/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 # SDD-AI Prerequisites
 
-Identical methodology in Claude Code (`.claude/skills/refacil-*`) and Cursor (`.cursor/skills/refacil-*`). Use the path of the open IDE.
+Identical methodology in all four supported IDEs: Claude Code (`~/.claude/skills/refacil-*`), Cursor (`~/.cursor/skills/refacil-*`), OpenCode (`~/.config/opencode/skills/refacil-*`), and Codex (`~/.codex/skills/refacil-*`). Skills install globally — not into the project repo. Use the path of the open IDE.
 
 Cross-cutting rules (states, branches, tests, output): `METHODOLOGY-CONTRACT.md` in this same folder.
 

package/skills/propose/SKILL.md

@@ -45,14 +45,42 @@ Communicate the final agreed slug to the user before generating.
 
 ### Step 2: Delegate to the refacil-proposer sub-agent
 
-Before delegating, resolve the artifact language:
+Before delegating, resolve language and CodeGraph availability in a single call:
 
-Run `refacil-sdd-ai sdd config --json` and read the `artifactLanguage` field. If the command fails or the field is missing/unknown, use `english`.
+Run `refacil-sdd-ai sdd config --json` and read `artifactLanguage`. If the command fails or the field is missing/unknown, use `english`.
+
+Run `refacil-sdd-ai codegraph status --json` and set `codegraphAvailable`:
+- `true` if `installed === true` AND `initialized === true`
+- `false` otherwise
+
+**If `mode` is `enabled` or `per-repo` but `codegraphAvailable` is `false`**:
+
+---
+
+**[GATE — STOP AND WAIT: CodeGraph not indexed]**
+
+Do NOT continue. Do NOT delegate to the sub-agent. STOP and ask the user exactly this, then wait for their reply:
+
+```
+CodeGraph is enabled for this repo but not yet indexed (~30s to build).
+The proposer sub-agent will explore the codebase less efficiently without it.
+
+Do you want me to run /refacil:update first to build the index?
+  yes → run /refacil:update then continue with the proposal
+  no  → continue with standard exploration now
+```
+
+Only after the user replies:
+- **"yes"** (or "si", "dale", "sí", "go", "ok"): immediately execute `/refacil:update`.
+- **"no"** (or "skip", "continue", "continúa"): set `codegraphAvailable: false` and continue.
+
+---
 
 Invoke the `refacil-proposer` sub-agent passing it:
 - `changeName`: the valid slug agreed in Step 1.5.
 - `description`: complete description of the change (from Step 1 or from `$ARGUMENTS`).
 - `artifactLanguage`: the resolved language (e.g. `english` or `spanish`). Pass it explicitly so the sub-agent uses it immediately, before it reads AGENTS.md.
+- `codegraphAvailable: true | false` (from above).
 
 The sub-agent:
 - Explores the codebase (reads `AGENTS.md`, detects relevant files and conventions) before generating.
@@ -62,6 +90,14 @@ The sub-agent:
 
 If the change arises from a **bus room agreement** (`refacil-bus`), indicate it to the sub-agent in the description so it takes it into account when generating the artifacts. Do not shorten the methodology flow. See `refacil-prereqs/BUS-CROSS-REPO.md` (room agreements section).
 
+After the sub-agent completes, log telemetry silently (must not block the flow):
+
+```bash
+refacil-sdd-ai compact log-codegraph-event --skill proposer --has-graph <true|false> --tool-calls <N> --tokens <N>
+```
+
+Use the same estimation criteria as `explore/SKILL.md` Step 1.5.
+
 ### Step 3: Developer review (Human-in-the-Loop — MANDATORY)
 
 Parse the `refacil-propose-result` block from the sub-agent to get the real artifact paths. Present a clear summary to the user for their review:
@@ -71,34 +107,46 @@ Parse the `refacil-propose-result` block from the sub-agent to get the real arti
 3. **Design**: files to create/modify and patterns to use.
 4. **Tasks**: task list — verify the breakdown is correct and complete.
 
-Ask explicitly:
+**Immediately after the summary, show this menu and WAIT for the user's reply — do NOT continue automatically:**
 
 ```
 === Review required ===
-The artifacts are ready for your review:
- - refacil-sdd/changes/[name]/proposal.md
- - [real spec paths]
- - refacil-sdd/changes/[name]/design.md
- - refacil-sdd/changes/[name]/tasks.md
-
-Please review the artifacts and confirm:
- 1. Are the acceptance criteria correct?
- 2. Does the design align with the project architecture?
- 3. Do the tasks cover the full scope?
-
-Reply "OK" to continue, or indicate what adjustments you need.
+Artifacts are ready at refacil-sdd/changes/[changeName]/
+
+  A) Approve — proceed to implementation
+  B) Listen to the spec aloud (opens all artifacts in the browser, auto-advancing)
+  C) Adjustments — describe what you want to change
 ```
 
 **DO NOT continue to Step 4 until the user explicitly approves.**
 
+- **"A"** (or "ok", "approve", "listo", "aprobado", "looks good", unambiguous approval): go to Step 4.
+- **"B"** (or "listen", "audio", "voice", "read", "escuchar", "voz"): run the following CLI command exactly as written — **do NOT use `--file`, do NOT open a single spec file**:
+  ```bash
+  refacil-sdd-ai read-spec --change <changeName>
+  ```
+  Where `<changeName>` is the slug agreed in Step 1.5 (e.g. `feat-my-feature`). This opens the **full change folder** in the browser (proposal → design → tasks → specs, auto-advancing between files). After running it, re-present the review menu so the user can approve or request adjustments.
+- **"C"** or any adjustment request: apply limited changes directly to the files or re-invoke the sub-agent if the scope changed, then re-present the review menu.
+
 If the user requests limited adjustments (change a criterion, fix a path, adjust a task), apply them directly to the corresponding files and present the summary again. If the adjustments are broad (changing the objective or the full scope), re-invoke the sub-agent with the updated description.
 
 ### Step 4: Next step
 
+**Always present this menu as a new message** immediately after Step 3 confirms approval. Never skip it or reuse the "OK" from Step 3 as a selection here — that "OK" means "the artifacts are approved", not "choose option A".
+
+Before presenting the menu, run `refacil-sdd-ai kapso preflight` (exits 0, prints JSON) and read `kapsoEnabled` from the output. If `kapsoEnabled = true`, append the WhatsApp note to option B. If `kapsoEnabled = false`, omit it.
+
 ```
-Proposal approved at: refacil-sdd/changes/[name]/
-The next step is to implement the tasks.
-Do you want me to continue with /refacil:apply?
+Proposal approved: refacil-sdd/changes/[name]/
+
+How do you want to continue? Reply A or B:
+
+  A) /refacil:apply — step-by-step (pauses for confirmation at each phase)
+  B) /refacil:autopilot — run the full cycle autonomously
+     (apply → test → verify → review → archive → up-code)
+     and notify you when done (recommended if you are stepping away)
+     [if kapsoEnabled = true: ⚠️ WhatsApp 24h window: make sure you have sent a message
+      to your notification number in the last 24h, otherwise the final alert may not arrive.]
 ```
 
 ## Rules
@@ -106,4 +154,11 @@ Do you want me to continue with /refacil:apply?
 - **Change folder name**: always validate with `refacil-sdd-ai sdd validate-name <slug>` before delegating. Do not proceed if it exits 1.
 - **Always delegate generation to the sub-agent**. Do not replicate the codebase exploration or artifact generation logic here.
 - `artifactLanguage` affects **only SDD artifacts**. Any code snippets, file/folder names, identifiers, and technical comments that may appear during proposal work must stay in **English**.
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 4, immediately invoke the **Skill tool** with `skill: "refacil:apply"`. Do not describe it in text or wait for the user to type `/refacil:apply`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **CodeGraph gate (Step 2)**: if `mode` is `enabled`/`per-repo` and `codegraphAvailable` is `false`, the GATE is **mandatory** — never skip it. If the user replies affirmatively ("yes", "si", "sí", "dale", "ok", "go"), immediately execute `/refacil:update` without any prior text. Do not describe it. Do not ask again. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity (Step 4)**:
+  - **Always show the A/B menu first.** An "OK", "yes", "go", or "continue" from Step 3 (artifact approval) is NOT a valid selection for Step 4 — show the menu and wait for the user's reply.
+  - Only execute after the user explicitly replies to the Step 4 menu:
+    - "apply" or "A" → immediately execute `/refacil:apply`. Do not describe it in text.
+    - "autopilot", "B", "auto", or "modo autónomo" → immediately execute `/refacil:autopilot`. Do not describe it in text.
+    - An ambiguous affirmative ("ok", "yes", "go", "continue") received **after the menu has been shown** → execute `/refacil:apply`.
+  - (See `METHODOLOGY-CONTRACT.md §5`.)