refacil-sdd-ai 5.2.3 → 5.3.1

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,38 @@ Parse the ` ```refacil-verify-result ` block from the sub-agent.
 
 #### If `result` is APPROVED:
 
-```
-RESULT: APPROVED
+Record that verification completed successfully:
 
-The next step is the quality review with the team checklist.
-Do you want me to continue with `/refacil:review`?
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state verified --actor verify-skill
 ```
 
-#### If `result` is REQUIRES_CORRECTIONS:
+If the command fails, continue silently — it must not block the flow.
 
-Present the issues and ask:
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  RESULT: APPROVED
 
-```
-RESULT: REQUIRES_CORRECTIONS
+  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.
 
-Required corrections:
-1. [CRITICAL/WARNING] [description] — [suggested fix]
-2. ...
+#### If `result` is REQUIRES_CORRECTIONS:
 
-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 = false` (normal): present the issues and ask:
+  ```
+  RESULT: REQUIRES_CORRECTIONS
+
+  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
+  ```
+- `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 +187,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 +209,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.