refacil-sdd-ai 5.2.2 → 5.3.0

package/skills/stats/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: refacil:stats
+description: Show statistics for a change — token savings, review history, compact and CodeGraph telemetry; optional narrative interpretation
+user-invocable: true
+---
+
+# refacil:stats — Change Statistics
+
+This skill is a **read-only utility** that surfaces observability data for a given change. It is optional — it does not block or affect any existing flow. Run it at any point to understand how a change is progressing or has progressed.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md`.
+
+## Flow
+
+### Step 1: Resolve change name
+
+1. If `$ARGUMENTS` provides a change name, use it directly.
+2. If not, run `refacil-sdd-ai sdd list --json` and use the single active change if there is only one.
+2.5. If `sdd list --json` returns `[]` (no active changes), auto-select the most recent archived change:
+   - Run `refacil-sdd-ai sdd list --include-archived --json`.
+   - From the returned array, filter items where `archived` is `true`. Sort descending by `archivedDate` (tiebreak: name descending). Select the first item.
+   - If an archived change is found: inform the user ("No active changes found — showing stats for most recently archived change: `<name>`") and continue to Step 2 with that `changeName`.
+   - If no archived changes exist either: inform the user that there is no change history and stop.
+3. If there are multiple active changes and no argument, ask the user to specify the change name. Do not proceed with ambiguous scope.
+
+If the change name is given but not found in the active changes, do **not** suggest `/refacil:propose`. Instead:
+1. Run `refacil-sdd-ai sdd list --include-archived --json` to check for archived changes.
+2. If archived changes exist, show the list and ask the user to confirm which name they want to query (they may have misspelled or the change was already archived).
+3. Only if there are no active **and** no archived changes should you inform the user that there is no work history for the given name.
+
+### Step 2: Run the stats CLI command
+
+Execute:
+
+```bash
+refacil-sdd-ai sdd stats <changeName> --json
+```
+
+If the command exits with code 1 (change not found or invalid name), show the CLI error message. The step 1 fallback (archived lookup) should have already been applied before reaching here, so a code 1 at this point means the name is genuinely absent in both active and archived locations — inform the user and stop.
+
+### Step 3: Parse the JSON output
+
+Parse the JSON block returned by the CLI. Expected fields:
+
+```json
+{
+  "changeName": "<name>",
+  "isArchived": true | false,
+  "archivedDate": "<YYYY-MM-DD or null>",
+  "startDate": "<ISO timestamp or null>",
+  "memory": {
+    "testCommand": "<command or null>",
+    "lastStep": "<step or null>",
+    "criteriaRun": ["CA-01", "CR-01", ...]
+  },
+  "review": {
+    "passed": true | false,
+    "verdict": "<verdict or null>",
+    "date": "<ISO timestamp or null>",
+    "failCount": <int>
+  },
+  "compact": {
+    "eventsInPeriod": <int>,
+    "rewrites": <int>,
+    "estimatedTokensSavedByRewrites": <int>,
+    "alreadyCompact": <int>,
+    "estimatedTokensSavedAlreadyCompact": <int>
+  },
+  "codegraph": {
+    "eventsInPeriod": <int>,
+    "totalToolCalls": <int>,
+    "estimatedTokensSaved": <int>
+  }
+}
+```
+
+If any field is null or 0, treat it as "no data" — do not error.
+
+### Step 4: Show numbers (structured display)
+
+Present the data in a readable format. If `isArchived` is `true`, add `[archivado el <archivedDate>]` to the header:
+
+```
+=== Stats: <changeName> [archivado el <archivedDate>] ===   ← only when isArchived: true
+=== Stats: <changeName> ===                                 ← when isArchived: false
+
+Phase progress
+  Started:    <startDate or "unknown">
+  Last step:  <lastStep or "not recorded">
+  Criteria:   <criteriaRun list or "none">
+
+Review
+  Passed:     <yes/no>
+  Verdict:    <verdict or "pending">
+  Date:       <date or "—">
+  Fail count: <failCount>
+
+Token savings (change period)
+  Compact rewrites:       <rewrites> events — ~<estimatedTokensSavedByRewrites> tokens saved
+  Already compact:        <alreadyCompact> events — ~<estimatedTokensSavedAlreadyCompact> tokens (skill discipline)
+  CodeGraph tool calls:   <totalToolCalls> — ~<estimatedTokensSaved> tokens saved
+```
+
+### Step 5: Narrative interpretation (anomaly detection)
+
+After the numbers, add a brief narrative. Apply these heuristics:
+
+**Anomalous passes**: if `review.passed` is `true` but `memory.criteriaRun` is empty or `memory.lastStep` is `apply` (no test phase recorded) — flag this:
+```
+Note: the change was reviewed but no test phase is recorded in memory. Recommend running /refacil:test before archiving.
+```
+
+**Token concentration**: if `compact.estimatedTokensSavedByRewrites` is 0 and `codegraph.estimatedTokensSaved` is also 0 — flag this:
+```
+Note: no token savings recorded for this change. Compact and CodeGraph telemetry may not be active.
+```
+
+**Comparison with previous changes** (optional — only if data exists):
+- Read all other change directories under `refacil-sdd/changes/` that have `memory.yaml`.
+- If at least 2 other changes have `criteriaRun` data, compute the average criteria count and compare:
+  ```
+  This change ran <N> criteria vs. an average of <avg> in previous changes.
+  ```
+- If no other changes have sufficient data, skip this comparison silently.
+
+**No anomalies**: if none of the above apply, show:
+```
+No anomalies detected. The change looks healthy.
+```
+
+### Step 6: Next step (optional)
+
+**Skip this step entirely if `isArchived === true`** — archived changes have no actionable next steps.
+
+If `memory.lastStep` is `apply` (no test yet):
+```
+Recommended next step: /refacil:test
+```
+
+If `memory.lastStep` is `test` and `review.passed` is `false`:
+```
+Recommended next step: /refacil:verify
+```
+
+If `review.passed` is `true`:
+```
+The change is reviewed. Next step: /refacil:archive (if all tasks are done).
+```
+
+## Rules
+
+- **This skill is read-only** — it does not modify any file, branch, or memory.
+- **Does not block any flow** — absence of stats data is reported as zeros, not as an error.
+- **Non-existent change**: exit with code 1 and a clear message (CA-12).
+- **Missing data fields**: treat as zero or null — never throw; degrade gracefully.
+- Comparison with previous changes is **optional** — only if data exists. Never block on its absence.
+- This skill does not call any sub-agent — it is a direct CLI wrapper with narrative.

package/skills/test/SKILL.md

@@ -6,6 +6,10 @@ user-invocable: true
 
 # refacil:test — Test Generation Entrypoint
 
+This skill is the **canonical test phase** of the SDD flow: it generates tests, runs the change-scoped suite, and records results in `memory.yaml` for later phases. **`/refacil:verify`** and **`/refacil:review`** rely on that memory and do **not** re-run the full pipeline by default (**METHODOLOGY-CONTRACT.md §3.2**).
+
+**Role distinction — smoke vs. full-suite**: `/refacil:apply` runs a dynamic smoke command after editing (narrowed to touched files, no coverage). `/refacil:test` is responsible for the **full scoped run WITH coverage** on changed/new code (default `testScope: scoped`) or repo-wide suite with coverage (when `testScope: full`). This applies in both manual and autopilot flows — the tester MUST NOT skip coverage or delegate it back to apply.
+
 This skill is a **thin wrapper** that resolves the scope, extracts CA/CR criteria and the list of files to test, and delegates to the `refacil-tester` sub-agent with a **structured briefing**. The sub-agent starts with the criteria already extracted — it does not re-read specs from scratch.
 
 **Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + test command from `METHODOLOGY-CONTRACT.md §3` and **§3.1** (default: scoped tests **and** scoped coverage on changed/new code; full suite/coverage **on-demand** via explicit arguments).
@@ -18,7 +22,7 @@ This skill is a **thin wrapper** that resolves the scope, extracts CA/CR criteri
 
 - **Defaults**: `testScope: scoped`, `runCoverage: true` (coverage **narrowed** to `filesToTest` / the change — not repo-wide).
 
-- **`testScope: full`** only if the user **explicitly** asked for **whole-repo / whole-suite** tests (e.g. `full`, `all tests`, `whole suite`, `suite completa`, `todas`). This is heavier; use sparingly before merge or debugging.
+- **`testScope: full`** only if the user **explicitly** asked for a full suite (e.g. `full`, `all tests`, `whole suite`, `suite completa`, `todas`). Runs the full suite of **each affected component** (component-bounded per §3 — never all monorepo packages). Heavier; use sparingly before merge or debugging.
 
 - **`runCoverage: false`** if the user **explicitly** asked to skip coverage (e.g. `no coverage`, `nocoverage`, `skip coverage`, `sin cobertura`, `quick`, `solo tests`). Otherwise leave `runCoverage: true`.
 
@@ -33,13 +37,15 @@ This skill is a **thin wrapper** that resolves the scope, extracts CA/CR criteri
 - If there are multiple active folders, **stop** and ask the user to select which one to test.
 - If there are no active changes, inform to run `/refacil:propose` and stop.
 
+**Autopilot mode detection**: once `changeName` is set, try to read `refacil-sdd/.autopilot-active`. If the file exists and its `changeName` field matches the current `changeName` → set `autopilotMode = true`. Otherwise `autopilotMode = false` (normal mode, ask user as usual).
+
 ### Step 1: Build briefing (change mode only)
 
 Before invoking the sub-agent, extract the key context:
 
 1. **Criteria** — read the change specification (`refacil-sdd/changes/<changeName>/specs.md` and/or `specs/**/*.md` if they exist). Extract the list of acceptance criteria (CA-XX) and rejection criteria (CR-XX) with their descriptions.
 2. **Files to test** — read `refacil-sdd/changes/<changeName>/design.md`. Extract the list of created/modified files.
-3. **Test command (baseline)** — read `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3 (and `AGENTS.md` if it overrides). Extract the baseline command **without** automatically adding coverage flags.
+3. **Test command (baseline)** — read `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3 (and `AGENTS.md` if it overrides). Resolve the baseline command language-agnostically at the **affected component root** (nearest ancestor of changed files with a stack manifest — per §3 component principle). Extract the command without automatically adding coverage flags. If the change spans multiple components, extract a baseline per component; pass the primary one in `testCommand` and note extras in the briefing.
 4. **Test pattern** — find an existing relevant test file (1 example file, not multiple). If `testing-patterns.md` exists in this directory, include it.
 5. **Coverage command** — if `runCoverage: true`, detect the project coverage entrypoint per §3 (`test:cov`, `pytest --cov`, JaCoCo, `cargo llvm-cov`, etc.); otherwise set `coverageCommand: null`.
 
@@ -62,8 +68,11 @@ testScope: scoped | full
 runCoverage: true | false
 coverageCommand: <project coverage entrypoint or null>
 testPatternFile: <path of an existing test file as reference, or null>
+codegraphAvailable: true | false
 ```
 
+Detect CodeGraph availability before delegating: run `refacil-sdd-ai codegraph status --json` and set `codegraphAvailable: true` only if `installed === true` AND `initialized === true`. If the command fails or the index is not ready, set `false` and continue without interruption.
+
 The sub-agent (`refacil-tester`) applies **§3.1**: scoped tests by default; with `runCoverage: true`, runs **scoped** coverage (change-only) unless `testScope: full`.
 
 ### Step 2: Delegate to the refacil-tester sub-agent
@@ -79,6 +88,20 @@ The sub-agent will use the briefing to generate tests directly without re-readin
 
 Returns ONE single message with the report + JSON block fenced as ` ```refacil-test-result `.
 
+### Step 2.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 tester --has-graph <true|false> --tool-calls <N> --tokens <N>
+```
+
+- `--has-graph`: the `codegraphAvailable` value if it was passed to the sub-agent; otherwise `false`.
+- `--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 (~800–1500 per useful tool call; 0 if no graph or no calls).
+
+Estimate `--tool-calls` and `--tokens` from the sub-agent's `<usage>` block using the same criteria as `explore/SKILL.md` Step 1.5. If the command fails, ignore it; it must not block the flow.
+
 ### Step 3: Present the report and process result
 
 Show the user the **report** (everything before the `refacil-test-result` block). Do not show the JSON block — it is internal metadata.
@@ -86,7 +109,9 @@ Show the user the **report** (everything before the `refacil-test-result` block)
 If the sub-agent returned something out of format, inform the user: "The tester returned an unstructured report — review the tests manually." and stop.
 
 Parse the `refacil-test-result` block from the sub-agent:
-- **If `passed: false`** (tests failed): present the `issues` from the JSON and ask the user how to proceed. **Do not continue to Step 4** until the tests pass.
+- **If `passed: false`** (tests failed):
+  - `autopilotMode = false` (normal): present the `issues` from the JSON and ask the user how to proceed. **Do not continue to Step 4** until the tests pass.
+  - `autopilotMode = true`: attempt to fix the failing tests automatically (apply corrections to the test/source code — do NOT expand scope). Re-invoke the tester. **Maximum 3 rounds total.** If tests pass within those rounds → continue to Step 4. If still failing after round 3 → return phase failure to the autopilot pipeline (autopilot Step 6 handles Kapso notification). Do NOT ask the user at any point.
 - **If `passed: true`**: continue to Step 4.
 
 ### Step 3.5: Update cross-skill memory (memory.yaml)
@@ -108,12 +133,12 @@ This command merges into memory.yaml, preserving fields from other steps (e.g. `
 
 ### Step 4: Flow continuity (only if tests passed)
 
-Add:
-
-```
-The next step is to validate the implementation against the specs.
-Do you want me to continue with /refacil:verify?
-```
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  The next step is to validate the implementation against the specs.
+  Do you want me to continue with /refacil:verify?
+  ```
+- `autopilotMode = true`: proceed to `/refacil:verify` immediately without asking.
 
 ## Rules
 
@@ -122,4 +147,4 @@ Do you want me to continue with /refacil:verify?
 - **Always delegate to the sub-agent**. Do not replicate stack detection or generation logic here.
 - **Do not invoke with ambiguous scope**. If there are multiple active changes, ask for selection first.
 - Test implementation is English-only (test file names, test cases/descriptions, identifiers, and comments), regardless of the SDD artifact language.
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question **and tests passed (`passed: true`)**, immediately invoke the **Skill tool** with `skill: "refacil:verify"`. Do not describe it in text or wait for the user to type `/refacil:verify`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question **and tests passed (`passed: true`)**, immediately execute `/refacil:verify`. Do not describe it in text or wait for the user to type it. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/up-code/SKILL.md

@@ -28,6 +28,8 @@ If the command fails or exits non-zero, use the default list: master, main.
   ```
 - If the branch is a working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continue.
 
+**Autopilot mode detection**: try to read `refacil-sdd/.autopilot-active`. If the file exists → `autopilotMode = true`, extract `baseBranch` and `createPR` from the file. Otherwise `autopilotMode = false` (normal mode, ask user as usual).
+
 ### Step 2: Verify review (mandatory)
 
 Before continuing, verify if there are active changes in `refacil-sdd/changes/` (exclude the `archive/` folder).
@@ -60,12 +62,14 @@ Run `git status` to verify if there are changes to push.
 ### Step 4: Commit changes
 
 1. Run `git status --short` and show the user the list of detected files.
-2. Ask for explicit confirmation before staging everything.
-3. If the user confirms global staging, use `git add -A`.
-4. If the user requests partial staging, add only the indicated paths.
-5. If the user provided a message as argument (`$ARGUMENTS`), use it as the commit message.
-6. If no message was provided, generate a descriptive one based on the detected changes with `git diff --staged --stat`.
-7. Run `git commit -m "[message]"`.
+2. **Stage**:
+   - `autopilotMode = false` (normal): ask the user for confirmation before staging:
+     - If confirmed → `git add -A`.
+     - If partial staging requested → add only the indicated paths.
+   - `autopilotMode = true`: run `git add -A` immediately — do NOT ask.
+3. If the user provided a message as argument (`$ARGUMENTS`), use it as the commit message.
+4. If no message was provided, generate a descriptive one based on the detected changes with `git diff --staged --stat`.
+5. Run `git commit -m "[message]"`.
 
 ### Step 5: Push to remote
 
@@ -81,13 +85,16 @@ Run `git push -u origin [current-branch]` to push the changes.
  Remote: origin/[branch-name]
 ```
 
-2. **Ask the user** which branch they want to create the PR to. Show the list of protected branches obtained from `sdd config --json` in Step 1 so the user can pick one:
-   ```
-   Which branch do you want to create the PR to?
-   Protected branches available: [list from sdd config --json]
-   ```
-
-  Verify the chosen branch exists on the remote by inspecting `git branch -r` output before generating the link. If it does not exist, inform the user and ask them to confirm or correct the name. If the user indicates a branch not in the protected branches list, warn them before proceeding.
+2. **Select target branch**:
+   - `autopilotMode = false` (normal): ask the user which branch to PR to, showing the protected branches list:
+     ```
+     Which branch do you want to create the PR to?
+     Protected branches available: [list from sdd config --json]
+     ```
+     Verify the chosen branch exists on the remote (`git branch -r`). If not, inform the user and ask to confirm or correct. Warn if not in the protected branches list.
+   - `autopilotMode = true`: use `baseBranch` from `refacil-sdd/.autopilot-active` as the target branch, and respect the `createPR` flag:
+     - `createPR = true` → generate the PR link against `baseBranch`.
+     - `createPR = false` → skip PR creation entirely. Do NOT generate a link.
 
 3. Get the remote repository URL with `git remote get-url origin` and detect the VCS hosting used by this repository to generate the correct PR/MR link:
    - **GitHub** (url contains `github.com`): `https://github.com/[owner]/[repo]/compare/[target-branch]...[current-branch]?expand=1`

package/skills/update/SKILL.md

@@ -10,9 +10,39 @@ Detects the current repo state and applies only what is pending. Does not repeat
 
 The `notify-update` hook uses the **same engine** as this command; do not manually re-evaluate the repo to decide if there is work to do.
 
+## Step 0.5: CodeGraph setup (if needed)
+
+Run `refacil-sdd-ai codegraph status --json` and parse the output.
+
+**If `mode` is `disabled` or `null`**: skip this step entirely.
+
+**If `mode` is `enabled` or `per-repo`**:
+
+1. **CLI not installed** (`installed: false`): inform the user and ask for confirmation **before running anything**:
+
+   ```
+   CodeGraph is enabled but the CLI (@colbymchenry/codegraph) is not installed.
+   Installing it will run: npm install -g @colbymchenry/codegraph (~20 s)
+   Proceed? (yes / no)
+   ```
+
+   - **If yes**: run `refacil-sdd-ai codegraph setup` and **show its full output** to the user. This command installs the package, then builds the index **synchronously** — it blocks until `.codegraph/` is fully ready. Wait for it to complete before continuing. After it finishes, inform:
+     ```
+     CodeGraph: installed and index complete. .codegraph/ is ready.
+     Future /refacil:explore, /refacil:propose, and /refacil:bug sessions will use it automatically.
+     ```
+   - **If no**: skip CodeGraph for this session. Inform: "You can install it later with `npm install -g @colbymchenry/codegraph`, then run `/refacil:update` again."
+
+2. **CLI installed but repo not indexed** (`installed: true`, `initialized: false`): run `refacil-sdd-ai codegraph setup` and **show its full output**. This command blocks until the index is fully built — wait for it to finish before continuing. Inform:
+   ```
+   CodeGraph: index complete. .codegraph/ is ready.
+   ```
+
+3. **CLI installed and repo indexed** (`installed: true`, `initialized: true`): skip — nothing to do.
+
 ## Step 1: Validate with the CLI (mandatory)
 
-In the **repo root** (where `AGENTS.md` or `.claude/` is), run with `Bash`:
+In the **repo root** (where `AGENTS.md` is), run with `Bash`:
 
 ```bash
 refacil-sdd-ai migration-pending
@@ -34,6 +64,7 @@ The implementation lives in `lib/methodology-migration-pending.js` of the packag
 | 1 | `AGENTS.md` exists and `.agents/` folder does not | Restructure into `.agents/` + rewrite as index |
 | 2 | `CLAUDE.md` has more than 5 lines or does not point to `AGENTS.md` | Replace with minimal index |
 | 3 | `.cursorrules` has more than 5 lines or does not point to `AGENTS.md` | Replace with minimal index |
+| 4 | CodeGraph CLI not installed and mode is `enabled`/`per-repo` | Step 0.5: `refacil-sdd-ai codegraph setup` |
 
 ## Step 2: Confirm with the user
 

package/skills/verify/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: true
 
 This skill is a **wrapper** that builds a **structured briefing** with the test command and criteria already extracted, delegates the analysis to the `refacil-validator` sub-agent, and handles the interaction with the user to apply corrections.
 
-**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md` (including **§3.1** — default scoped tests **and** scoped coverage; full regression on explicit request).
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md` (including **§3.2** — `/refacil:test` owns full test+coverage; verify defaults to **no re-run** when test memory exists).
 
 ## Flow
 
@@ -19,15 +19,18 @@ Determine the scope before invoking the sub-agent. Prioritize in this order:
 2. Active change in `refacil-sdd/changes/`.
 3. If there are multiple active changes and no `$ARGUMENTS`, **stop** and ask the user to explicitly select which change to validate.
 
-**Test intent** — align with **`/refacil:test`** (same tokens):
+**Autopilot mode detection**: once `changeName` is resolved, try to read `refacil-sdd/.autopilot-active`. If the file exists and its `changeName` field matches → `autopilotMode = true`. Otherwise `autopilotMode = false` (normal mode, ask user as usual).
 
-- **Defaults**: `testScope: scoped`, `runCoverage: true` (coverage **narrowed** to diff / changed files).
+**Test execution intent** — see **§3.2**:
 
-- **`testScope: full`** only if the user explicitly asked (`full`, `all tests`, `whole suite`, `suite completa`, `todas`).
+- **Default**: `testExecution: none` when `get-memory` has `commandsRun` and `lastStep` is `test` (or later) — verify validates CA/CR **without** re-running the test pipeline.
 
-- **`runCoverage: false`** if the user explicitly asked to skip coverage (`no coverage`, `nocoverage`, `skip coverage`, `sin cobertura`, `quick`, `solo tests`). Otherwise leave `runCoverage: true`.
+- **`testExecution: full`** if the user explicitly asked to re-run tests (`full`, `all tests`, `re-run`, `run tests`, `ejecutar tests`, `whole suite`, `suite completa`, `todas`) — then also set `testScope` / `runCoverage` like **`/refacil:test`**:
+  - **`testScope: full`** for whole-suite tokens above.
+  - **`runCoverage: false`** for `no coverage`, `nocoverage`, `skip coverage`, `sin cobertura`, `quick`, `solo tests`.
+  - **`full` + `no coverage`**: `testScope: full`, `runCoverage: false`.
 
-- **`full` + `no coverage`**: full tests only (`testScope: full`, `runCoverage: false`).
+- **No test memory** (`commandsRun` empty): emit WARNING, set `testExecution: full` (CR-01) unless only `changedFiles` allow a minimal scoped run.
 
 Do not invoke the sub-agent with ambiguous scope.
 
@@ -41,19 +44,28 @@ If **this session** inspects the change directory before or after delegating, ap
 
 Before invoking the sub-agent, extract the context that the validator would otherwise calculate on its own:
 
+0. **CodeGraph detection** — run `refacil-sdd-ai codegraph status --json` and extract:
+   - `codegraphAvailable = true` if `installed === true` AND `initialized === true`
+   - `codegraphAvailable = false` otherwise
+   - Include `codegraphAvailable` as a field in the briefing so the validator can use CodeGraph for Dimension 3 (Coherence) analysis when available (see `METHODOLOGY-CONTRACT.md §3C`).
+
 1. **Scope files** — run `git diff --name-only HEAD` to populate `changedFiles`.
 
-2. **Cross-skill memory** — when `changeName` is known, run `refacil-sdd-ai sdd get-memory <changeName> --json`. Parse `commandsRun` and `criteriaRun`. If the output is `{}` or the command fails, omit those fields — do not block verification (CR-04).
+2. **Cross-skill memory** — when `changeName` is known, run `refacil-sdd-ai sdd get-memory <changeName> --json`. Parse `commandsRun`, `criteriaRun`, and `lastStep`. If the output is `{}` or the command fails, omit those fields — do not block verification (CR-04).
+
+3. **Resolve `testExecution`** (§3.2) from Step 0 and memory:
+   - User forced re-run → `testExecution: full`.
+   - `commandsRun` non-empty and `lastStep` is `test` (or `verify`/`review` after test) and user did **not** force re-run → `testExecution: none`.
+   - Otherwise → `testExecution: full` with WARNING (no test phase recorded).
 
-3. **Test command** — follow `METHODOLOGY-CONTRACT.md` §3.1. Set `testScope` and `runCoverage` from Step 0 (`scoped` / `runCoverage: true` by default).
-   - If the user requested `testScope: full`, set `testCommand` to the baseline §3 command (no narrowing).
-   - Else if `commandsRun` from memory is non-empty and the user did **not** force `full`, prefer the **last** entry in `commandsRun` as `testCommand` (same invocation as `/refacil:test` when memory was updated).
-   - Else build a **scoped** `testCommand` from `changedFiles`: include paths that are already test artifacts; for touched sources, infer companion tests from **project convention** (`AGENTS.md`, test config — co-located `*Test*` / `*Spec*`, `tests/`, language-specific layouts), not from a single language suffix.
-   - If you cannot build any scoped command, fall back to baseline §3 and add a one-line WARNING in the handoff that the run may be heavy.
+4. **Test commands** — only when `testExecution` is `full` or `smoke`:
+   - **`full`**: follow §3.1 — set `testScope` and `runCoverage` from Step 0; build `testCommand` (scoped from `changedFiles` or baseline if `full`); set `coverageCommand` when `runCoverage: true`.
+   - **`smoke`**: build `smokeTestCommand` for companion tests of `correctionTouchedFiles` only; `runCoverage: false`, `coverageCommand: null`.
+   - **`none`**: omit `testCommand` and `coverageCommand`; set `testsDelegatedFrom: test` and include `commandsRun` for the report.
 
-4. **Coverage command** — detect per §3 when `runCoverage: true`; otherwise set `coverageCommand: null`. When `testScope` is `scoped` and `runCoverage: true`, instruct the validator to **narrow coverage collection** to `changedFiles` / companion tests only (same as §3.1).
+5. **Coverage command** — only when `testExecution: full` and `runCoverage: true`; otherwise `coverageCommand: null`.
 
-5. **CA/CR criteria** — if there is an active change, read the specification in `refacil-sdd/changes/<changeName>/`:
+6. **CA/CR criteria** — if there is an active change, read the specification in `refacil-sdd/changes/<changeName>/`:
    - `specs.md` if it exists, and/or files under `specs/` (recursively).
    - Extract the list of CA-XX (acceptance criteria) and CR-XX (rejection criteria) with their descriptions.
    - If there are no specs or the scope is `git-diff`, omit this field.
@@ -63,10 +75,14 @@ Build the BRIEFING block:
 ```
 BRIEFING:
 changeName: <name or null if scope=git-diff>
-testCommand: <exact command line the validator must run — scoped by default>
+testExecution: none | smoke | full
+testCommand: <required when full; omit when none>
+smokeTestCommand: <required when smoke; omit otherwise>
 testScope: scoped | full
 runCoverage: true | false
-coverageCommand: <project coverage entrypoint or null>
+coverageCommand: <project coverage entrypoint or null when full+runCoverage>
+testsDelegatedFrom: test | null
+correctionTouchedFiles: [...]   # only on re-verify after Step 5 corrections
 criteria:
   acceptance:
     - CA-01: <description>
@@ -75,6 +91,7 @@ criteria:
     - CR-01: <description>
 changedFiles: [path/file-1, ...]
 mode: concise | detailed
+codegraphAvailable: true | false       # from CodeGraph detection in Step 1.0
 commandsRun: [<command>, ...]          # from memory.yaml — omit if not present
 criteriaRun: [CA-01, CR-01, ...]       # from memory.yaml — omit if not present
 ```
@@ -84,15 +101,29 @@ criteriaRun: [CA-01, CR-01, ...]       # from memory.yaml — omit if not presen
 Invoke `refacil-validator` passing it the BRIEFING from the previous step.
 
 The sub-agent:
-- Uses `testCommand` from the briefing directly (without looking it up in METHODOLOGY-CONTRACT.md).
-- Applies **§3.1**: `testScope` and `runCoverage` from the briefing (defaults scoped + scoped coverage).
+- Applies **`testExecution`** from the briefing (§3.2) — **does not** run tests when `none`.
+- When `full`, uses `testCommand` / coverage per §3.1; when `smoke`, runs only `smokeTestCommand` (no coverage).
 - Uses `criteria` from the briefing for verification (without re-reading specs from scratch).
 - Uses `changedFiles` to focus the 3D verification on those files.
-- Applies the 3D framework (Completeness/Correctness/Coherence) directly.
-- Runs tests then coverage per briefing (`runCoverage: true` by default → **narrowed** coverage unless `testScope: full`).
+- Applies the **3D framework (Completeness/Correctness/Coherence)** per **`METHODOLOGY-CONTRACT.md §3C — 3C Criterion`** — including the severity table and graceful degradation rule.
+- If `codegraphAvailable: true` is in the briefing, uses CodeGraph on `changedFiles` for Dimension 3 (Coherence) analysis.
 - Optionally consults the bus cross-repo for ambiguities.
 - Returns combined report + JSON block fenced as ` ```refacil-verify-result `.
 
+### Step 2.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 validator --has-graph <true|false> --tool-calls <N> --tokens <N>
+```
+
+- `--has-graph`: the `codegraphAvailable` value from Step 1.0 of this skill.
+- `--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 (~800–1500 per useful tool call; 0 if no graph or no calls).
+
+Estimate `--tool-calls` and `--tokens` from the sub-agent's `<usage>` block using the same criteria as `explore/SKILL.md` Step 1.5. If the command fails, ignore it; it must not block the flow.
+
 ### Step 3: Present the report
 
 Show the user the **combined report** (everything before the `refacil-verify-result` block). Do not show the JSON block — it is internal metadata.
@@ -117,28 +148,30 @@ Parse the ` ```refacil-verify-result ` block from the sub-agent.
 
 #### If `result` is APPROVED:
 
-```
-RESULT: APPROVED
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  RESULT: APPROVED
 
-The next step is the quality review with the team checklist.
-Do you want me to continue with `/refacil:review`?
-```
+  The next step is the quality review with the team checklist.
+  Do you want me to continue with `/refacil:review`?
+  ```
+- `autopilotMode = true`: proceed to `/refacil:review` immediately without asking.
 
 #### If `result` is REQUIRES_CORRECTIONS:
 
-Present the issues and ask:
+- `autopilotMode = false` (normal): present the issues and ask:
+  ```
+  RESULT: REQUIRES_CORRECTIONS
 
-```
-RESULT: REQUIRES_CORRECTIONS
-
-Required corrections:
-1. [CRITICAL/WARNING] [description] — [suggested fix]
-2. ...
+  Required corrections:
+  1. [CRITICAL/WARNING] [description] — [suggested fix]
+  2. ...
 
-Do you want me to apply these corrections? (yes/no)
-- Yes: I will apply the fixes and automatically re-verify
-- No: you can fix them manually and then continue with /refacil:verify
-```
+  Do you want me to apply these corrections? (yes/no)
+  - Yes: I will apply the fixes and automatically re-verify
+  - No: you can fix them manually and then continue with /refacil:verify
+  ```
+- `autopilotMode = true`: apply corrections automatically (yes internally) without asking, then re-verify. If still failing after 2 rounds → abort (return failure to the autopilot pipeline without asking the user).
 
 ### Step 5: Apply corrections (if the user accepts)
 
@@ -146,16 +179,20 @@ Do you want me to apply these corrections? (yes/no)
 
 1. Apply ONLY the listed corrections — do not add new functionality, do not refactor unrelated code.
 2. If there are tests that need adjustment, adjust them as well.
-3. Show summary of modified files.
-4. **Automatically re-run from Step 2** (re-invoke the sub-agent with the same briefing) to confirm the corrections resolved the issues.
+3. Show summary of modified files; record paths in `correctionTouchedFiles`.
+4. **Re-verify** (max 2 rounds): rebuild briefing with `testExecution: smoke` on companion tests of `correctionTouchedFiles`, **or** `testExecution: none` and tell the user:
+   ```
+   Corrections applied. Run /refacil:test before the next full verify to refresh the test suite.
+   ```
+   **Never** set `testExecution: full` in autofix re-verify unless the user explicitly requested re-run in this invocation.
 5. Maximum **2 rounds** of automatic correction. If issues persist, list them for manual correction.
 
-**If the user does not accept:** list the issues for manual correction. Suggest `/refacil:verify` again.
+**If the user does not accept:** list the issues for manual correction. Suggest `/refacil:test` then `/refacil:verify`.
 
 ## Rules
 
 - **Always build the briefing (Step 1) before delegating** — reduces the sub-agent tool calls.
-- **Defaults**: `testScope: scoped`, `runCoverage: true` (change-only coverage). **`testScope: full`** or **no coverage** only when Step 0 tokens say so.
+- **Defaults**: `testExecution: none` when test memory exists; **`testExecution: full`** only when Step 0 forces re-run or CR-01 applies. Smoke only after corrections; never full suite in autofix rounds.
 - **Always delegate to the sub-agent** for the analysis. Do not replicate spec reading or test execution logic here.
 - **Dotfiles in `refacil-sdd/changes/`**: never assert absence of `.review-passed` without `-a`; see §8.
 - **Corrections are ONLY applied by this wrapper** (Step 5), after explicit approval.
@@ -164,4 +201,4 @@ Do you want me to apply these corrections? (yes/no)
 - **Sub-agent failsafe (CA-01)**: if the validator fails to load (tool error) or returns no response — stop and inform the user. Do NOT escalate to any other agent.
 - **Unstructured output (CA-02)**: if the validator responds but without a `refacil-verify-result` block — show the raw report and stop. Do NOT re-invoke another agent.
 - **SCOPE_ERROR (CR-03)**: if the validator returns `SCOPE_ERROR: <reason>` — propagate and ask for clarification. CA-01 does NOT apply here.
-- **Flow continuity**: if the result is APPROVED and the user confirms affirmatively, immediately invoke the **Skill tool** with `skill: "refacil:review"`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the result is APPROVED and the user confirms affirmatively, immediately execute `/refacil:review`. (See `METHODOLOGY-CONTRACT.md §5`.)

package/templates/compact-guidance.md

@@ -41,5 +41,15 @@ Rules to minimize context consumption when working in this repository.
 - `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"`.
 - `docker logs --tail 100` always; never full logs.
 
+**CodeGraph (when available)**
+When `codegraph_*` MCP tools are present in the session, prefer them over `Grep`, `Read`, and `Glob` for all structural queries:
+- Symbol lookup → `codegraph_search` before `Grep`
+- Tracing flows → `codegraph_callers` / `codegraph_callees`
+- Module context → `codegraph_context` (replaces reading multiple files)
+- Impact analysis → `codegraph_impact` before touching shared code
+- Fall back to native tools only for literal text search or when CodeGraph returns empty results.
+
+If the session context contains a `[refacil-sdd-ai] CodeGraph` message (CLI not installed or repo not indexed): relay it to the user in the first response and offer to run `/refacil:update`.
+
 **General rule**
 When in doubt between verbosity and conciseness, choose conciseness. The user can request detail on demand.

package/templates/methodology-guide.md

@@ -18,9 +18,14 @@ Skills are identical in `.claude/skills/refacil-*/` (Claude Code) and `.cursor/s
 | `/refacil:up-code` | Push code and create PR |
 | `/refacil:bug` | Guided bugfix flow |
 | `/refacil:update` | Apply pending **methodology** migrations (same engine as `notify-update`; e.g. `AGENTS.md` → `.agents/` index pattern) |
+| `/refacil:stats` | Show change progress, task status, review gate, and test commands from SDD artifacts |
+| `/refacil:read-spec` | Listen to a change's specs in the browser with on-device TTS |
+| `/refacil:autopilot` | Autonomous pipeline: chains `apply → test → verify → review → archive` in one invocation; `up-code` (push + PR) optional via pre-flight. Optional WhatsApp notification via Kapso |
 
 **Typical feature flow:** `setup` → `explore` (optional) → `propose` → `apply` → `test` → `verify` → `review` → `archive` → `up-code`.
 
+**Autonomous alternative:** after `propose` is approved, `/refacil:autopilot` chains `apply → test → verify → review → archive` (and optionally `up-code`) in a single invocation instead of running each step manually.
+
 **Bug flow:** `bug` replaces `propose`/`apply` for the fix path; then `test` / `review` / `archive` / `up-code` as appropriate (see skill `refacil:bug`).
 
 **Legacy layout:** if the repo still has **`openspec/changes/`**, run any **`refacil-sdd-ai sdd …`** command or open a session ( **`check-update`** ) to migrate into **`refacil-sdd/`**; then remove **`openspec/`** when no longer referenced. Optional OpenSpec CLI (**`opsx:*`**) may coexist; SDD-AI uses **`refacil-sdd/`** and **`/refacil:*`** as the primary interface.