refacil-sdd-ai 4.3.0 → 4.4.0

package/agents/auditor.md

@@ -157,10 +157,17 @@ Next step: [/refacil:archive | /refacil:verify]
   "summary": "<1-line summary>",
   "failCount": <integer count of FAILs in NEW code>,
   "preexistingCount": <integer count of pre-existing FAILs found>,
-  "blockers": <true|false — new code only>
+  "blockers": <true|false — new code only>,
+  "failedFiles": ["path/to/file-1.ts", "path/to/file-2.ts"]
 }
 ```
 
+**`failedFiles` rules**:
+- On `REQUIERE CORRECCIONES`: list the relative paths (from repo root) of every file in the **blocking scope** (`changedFiles`) that had at least one CRITICAL or HIGH FAIL.
+- On `APROBADO` or `APROBADO CON OBSERVACIONES`: emit `"failedFiles": []`.
+- Files with only MEDIUM/LOW findings do NOT appear in `failedFiles`.
+- Pre-existing context files do NOT appear in `failedFiles` — only blocking scope.
+
 **IMPORTANT about the JSON block**:
 - Use the literal fence ` ```refacil-review-result ` (not ` ```json `).
 - Emit it ALWAYS, even if the verdict is `REQUIERE CORRECCIONES`.

package/agents/proposer.md

@@ -2,7 +2,7 @@
 name: refacil-proposer
 description: Generates SDD-AI planning artifacts (proposal, specs, design, tasks) for any codebase. Delegated by /refacil:propose — do not invoke directly.
 tools: Read, Grep, Glob, Bash, Edit, Write
-model: opusplan
+model: sonnet
 ---
 
 # refacil-proposer — Planning Artifact Generator

package/lib/commands/sdd.js

@@ -3,7 +3,21 @@
 const fs = require('fs');
 const path = require('path');
 
-const projectRoot = process.cwd();
+function findProjectRoot() {
+  let dir = process.cwd();
+  const { root } = path.parse(dir);
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, 'refacil-sdd')) || fs.existsSync(path.join(dir, '.git'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const projectRoot = findProjectRoot();
 
 // --- Helpers ---
 

package/lib/installer.js

@@ -71,10 +71,12 @@ function installSkills(packageRoot, projectRoot) {
 // Claude Code: tools allowlist granular, model: sonnet|opus|haiku
 // Cursor: readonly: true|false (booleano), model: inherit (default)
 function transformFrontmatterForCursor(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) return content;
 
   const [, frontmatterRaw, body] = match;
+  // work with normalized content from here on
   const lines = frontmatterRaw.split('\n');
   const out = [];
   let toolsLine = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code and Cursor",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/apply/SKILL.md

@@ -99,6 +99,23 @@ The sub-agent will use the briefing as the primary guide and will only read the
 
 Returns ONE single message with the report + JSON block fenced as ` ```refacil-apply-result `.
 
+### Step 2.5: Write memory.yaml (CA-16 — cross-skill state)
+
+After parsing the `refacil-apply-result` block:
+- Extract `touchedFiles` from the result (list of files actually created/modified by the implementer).
+- Write or update `refacil-sdd/changes/<changeName>/memory.yaml` preserving any existing fields:
+
+```yaml
+lastStep: apply
+touchedFiles:
+  - path/file-1.ts
+  - path/file-2.ts
+```
+
+If the file already exists, merge: update `lastStep` and `touchedFiles`; do not remove fields set by other steps (e.g. `commandsRun` from test).
+
+If `result` is `"FAILED"`, skip the write and wait for user instructions.
+
 ### Step 3: Present result and next step
 
 Show the user the **report** (everything before the `refacil-apply-result` block). Do not show the JSON block — it is internal metadata.

package/skills/archive/SKILL.md

@@ -65,6 +65,8 @@ Depending on the type, follow the corresponding step:
 
 Bug fixes only contain `summary.md` (and optionally `.review-passed`); they are not full proposal/spec/design/task trees. Archive them with **git mv** / **mv** per the steps below — **do not** use `refacil-sdd-ai sdd archive` for these folders.
 
+0. **Delete memory.yaml if present** (CA-18): run `rm -f "refacil-sdd/changes/[fix-name]/memory.yaml"` before moving the folder.
+
 1. **Move to archive (move operation, not copy)**: transfer the full fix folder from `refacil-sdd/changes/[fix-name]/` to `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/`. The source folder **must be eliminated** when done.
 
    Recommended execution order (deterministic and cross-platform):
@@ -140,10 +142,12 @@ The spec and review evidence are written **before** running the CLI archive comm
      ```
    - If `review.yaml` already exists, update only the fields that changed without removing others.
 
-3. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — this moves the change to `refacil-sdd/changes/archive/<date>-<changeName>/`.
-4. Verify the command completed successfully (exit 0) and the original folder no longer exists.
+3. **Delete memory.yaml if present** (CA-18): before running the CLI archive, delete `refacil-sdd/changes/<changeName>/memory.yaml` if it exists — run `rm -f "refacil-sdd/changes/<changeName>/memory.yaml"`. This is part of the archive cleanup.
+
+4. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — this moves the change to `refacil-sdd/changes/archive/<date>-<changeName>/`.
+5. Verify the command completed successfully (exit 0) and the original folder no longer exists.
 
-5. Continue to **Step 3**.
+6. Continue to **Step 3**.
 
 The goal is for `refacil-sdd/specs/` to document how the system works TODAY.
 

package/skills/explore/SKILL.md

@@ -17,6 +17,18 @@ This skill is a **thin wrapper** that delegates the investigation to the `refaci
 - If `$ARGUMENTS` is empty, ask the user for the question or topic to explore BEFORE invoking the sub-agent.
 - If there is a question, continue.
 
+### Step 0.1: Duplicate exploration guard (CA-11)
+
+Before delegating, check the current session conversation context for a prior complete exploration report with overlapping scope (same modules, files, or question topic):
+
+- **If a prior complete exploration exists for the same or highly overlapping topic**: summarize the already-known context in 2-3 sentences and ask:
+  ```
+  I already explored [topic] earlier in this session. The key findings were: [summary].
+  Do you want me to run a targeted follow-up on a specific aspect, or proceed with a new full exploration?
+  ```
+  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 1: Delegate to the refacil-investigator sub-agent
 
 Invoke the `refacil-investigator` sub-agent passing it:

package/skills/propose/SKILL.md

@@ -12,6 +12,18 @@ This skill is a **wrapper** that prepares the scope, delegates SDD artifact gene
 
 ## Flow
 
+### Step 0.5: Duplicate exploration guard (CA-11)
+
+Before gathering context or delegating, check the current session conversation for a prior complete exploration report with overlapping scope (same modules, files, or described topic):
+
+- **If a prior complete exploration exists for the same or highly overlapping topic**: summarize the already-known context in 2-3 sentences and ask:
+  ```
+  I already explored [topic] earlier in this session. The key findings were: [summary].
+  Do you want me to run a targeted follow-up, or proceed with the full exploration for this proposal?
+  ```
+  Wait for the user's answer. If they confirm "proceed", continue to Step 1 — do not re-invoke a full exploration automatically.
+- **If there is no prior exploration** for this topic: continue to Step 1 without interruption.
+
 ### Step 1: Understand the change
 
 If the user did NOT provide sufficient context in `$ARGUMENTS`, ask:

package/skills/review/SKILL.md

@@ -43,11 +43,21 @@ If you already have a `changeName`, run `refacil-sdd-ai sdd status <changeName>
    The change [name] already has an approved review ([verdict] — [date]) and there are no subsequent changes.
    ```
 
+### Step 0.4: Incremental scope (CA-07 — only if re-running after REQUIERE CORRECCIONES)
+
+If `changeName` is not null, check whether `refacil-sdd/changes/<changeName>/.review-last-fails.json` exists (read by explicit path — it is NOT a dotfile but may be hidden in listings):
+
+- **If the file EXISTS**: read `failedFiles` from it. Compute:
+  `incrementalScope = failedFiles ∪ changedFilesUnion`
+  - If `incrementalScope` is empty (CR-02): fall back to `changedFilesUnion` and add a comment in the briefing: `"# warning: incremental scope was empty — using full changedFilesUnion"`.
+  - Use `incrementalScope` as `changedFiles` in the briefing (Step 0.5), instead of the full `changedFilesUnion`.
+- **If the file does NOT exist**: use `changedFilesUnion` as `changedFiles` normally.
+
 ### Step 0.5: Build briefing for the sub-agent (reduces auditor tool calls)
 
 Before invoking the sub-agent, extract the context that the auditor would otherwise calculate on its own:
 
-1. **Changed files** — use **`changedFilesUnion` from Step 0.3** as the blocking scope. Do not run `git diff` or `git status` again.
+1. **Changed files** — use the scope resolved in Step 0.4 (`incrementalScope` if available, otherwise `changedFilesUnion`). Do not run `git diff` or `git status` again.
 
 2. **Project type** — read `package.json` (if it exists) and inspect the dependencies:
    - Backend indicators: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
@@ -56,6 +66,10 @@ Before invoking the sub-agent, extract the context that the auditor would otherw
 
 3. **Change objective** (only if there is an active change in `refacil-sdd/changes/`) — read the first section of `proposal.md`. Extract the objective in 1-2 sentences. If the scope is `git-diff` without an active change → `null`.
 
+4. **Cross-skill memory** — if `changeName` is not null and `refacil-sdd/changes/<changeName>/memory.yaml` exists, read it and extract `stackDetected`, `touchedFiles`. Include them in the briefing so the auditor skips re-discovery. If the file does not exist, omit — do not block (CR-04).
+
+5. **Mode** — default `concise`. If re-running after a prior `REQUIERE CORRECCIONES` (i.e., `.review-last-fails.json` was found with non-empty `failedFiles` in Step 0.4): set `mode: focused` — the auditor re-evaluates only the failing checklist items on the `failedFiles` (CR-05: focused mode still reads those files). Otherwise keep `concise`.
+
 Build the BRIEFING block:
 
 ```
@@ -64,7 +78,9 @@ scope: <changeName | "git-diff">
 changedFiles: [path/file-1.ts, path/file-2.ts, ...]
 projectType: backend | frontend | fullstack | library
 changeObjective: <objective in 1-2 sentences, or null>
-mode: concise | detailed
+mode: concise | detailed | focused
+stackDetected: <from memory.yaml, or omit>
+touchedFiles: [...]                   # from memory.yaml — omit if not present
 ```
 
 ### Step 1: Delegate to the refacil-auditor sub-agent
@@ -85,6 +101,18 @@ Show the user the **concise report** (everything before the `refacil-review-resu
 
 **If the sub-agent returned `SCOPE_ERROR: <reason>`**: propagate the error to the user and ask for clarification. Do not write a marker.
 
+### Step 2.5: Persist or clean incremental-scope state (CA-06/CA-08/CA-09/CR-01)
+
+Parse the `refacil-review-result` block from the sub-agent.
+
+**If `verdict` is `REQUIERE CORRECCIONES`**:
+- Only if `changeName` is not null (CR-01) AND the block includes a `failedFiles` field (CA-09 backward compat):
+  - Write `refacil-sdd/changes/<changeName>/.review-last-fails.json` with content: `{ "failedFiles": [...] }` using the `failedFiles` array from the JSON block.
+- If `changeName` is null or `failedFiles` is absent: skip silently — existing behavior unchanged.
+
+**If `verdict` is `APROBADO` or `APROBADO CON OBSERVACIONES`**:
+- If `refacil-sdd/changes/<changeName>/.review-last-fails.json` exists: delete it (CA-08) — run `rm -f "refacil-sdd/changes/<changeName>/.review-last-fails.json"`.
+
 ### Step 3: Create `.review-passed` marker (if applicable)
 
 Parse the ` ```refacil-review-result ` block from the sub-agent. If `verdict` is **APROBADO** or **APROBADO CON OBSERVACIONES** and `changeName` is not null:

package/skills/test/SKILL.md

@@ -69,6 +69,24 @@ 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: true`**: continue to Step 4.
 
+### Step 3.5: Write memory.yaml (CA-16 — cross-skill state)
+
+After parsing the `refacil-test-result` block and only if `passed: true`:
+- Extract from the result or from the briefing: `commandsRun` (list of test commands executed), `criteriaRun` (list of CA-XX/CR-XX covered by tests), `stackDetected` (if the tester identified the stack).
+- Write or update `refacil-sdd/changes/<changeName>/memory.yaml` preserving any existing fields:
+
+```yaml
+lastStep: test
+stackDetected: <detected stack or omit>
+commandsRun:
+  - <test command used>
+criteriaRun:
+  - CA-01
+  - CR-01
+```
+
+If the file already exists, merge: update `lastStep`, `stackDetected`, `commandsRun`, `criteriaRun`; preserve fields from other steps (e.g. `touchedFiles` from apply).
+
 ### Step 4: Flow continuity (only if tests passed)
 
 Add:

package/skills/verify/SKILL.md

@@ -27,6 +27,16 @@ If you already have a `changeName`, run `refacil-sdd-ai sdd status <changeName>
 
 If **this session** inspects the change directory before or after delegating, apply **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §8**.
 
+### Step 0.6: Verify validator agent is installed (blocking — CA-12)
+
+Before doing anything else, check that `.claude/agents/refacil-validator.md` exists (read by explicit path or `ls -la .claude/agents/refacil-validator.md`).
+
+**If the file does NOT exist**, stop immediately:
+```
+El agente `refacil-validator` no está instalado. Ejecuta `/refacil:update` y reinicia la sesión antes de volver a correr `/refacil:verify`.
+```
+Do not continue and do not escalate to any other agent.
+
 ### Step 1: Build briefing for the sub-agent (reduces validator tool calls)
 
 Before invoking the sub-agent, extract the context that the validator would otherwise calculate on its own:
@@ -40,6 +50,11 @@ Before invoking the sub-agent, extract the context that the validator would othe
 
 3. **Scope files** — run `git diff --name-only HEAD` to get the files modified in this change.
 
+4. **Cross-skill memory** — if `changeName` is not null and `refacil-sdd/changes/<changeName>/memory.yaml` exists, read it and extract:
+   - `commandsRun` — the test command(s) already executed by the tester. Include in the briefing so the validator uses the same command without re-discovering it.
+   - `criteriaRun` — the CA-XX/CR-XX already tested. Include in the briefing so the validator can skip re-reading specs for those criteria.
+   If the file does not exist, omit these fields — do not block (CR-04).
+
 Build the BRIEFING block:
 
 ```
@@ -54,6 +69,8 @@ criteria:
     - CR-01: <description>
 changedFiles: [path/file-1.ts, ...]
 mode: concise | detailed
+commandsRun: [<command>, ...]          # from memory.yaml — omit if not present
+criteriaRun: [CA-01, CR-01, ...]       # from memory.yaml — omit if not present
 ```
 
 ### Step 2: Delegate to the refacil-validator sub-agent
@@ -73,7 +90,18 @@ The sub-agent:
 
 Show the user the **combined report** (everything before the `refacil-verify-result` block). Do not show the JSON block — it is internal metadata.
 
-**If the sub-agent returned a scope error** (without JSON block): propagate to the user and ask for clarification.
+**If the sub-agent failed to load** (tool error, agent type not found, or no response at all): stop immediately and do NOT escalate to any other agent:
+```
+The validator sub-agent could not be loaded — retry or run `/refacil:verify` again.
+```
+
+**If the sub-agent responded but without a `refacil-verify-result` block** (unstructured output): show the raw report and stop:
+```
+The validator returned an unstructured report — continue manually.
+```
+Do not re-invoke a different agent.
+
+**If the sub-agent returned a scope error** (`SCOPE_ERROR: <reason>`, without JSON block): propagate to the user and ask for clarification. This is NOT the CA-01 failsafe — the agent loaded correctly but found an ambiguous scope.
 
 ### Step 4: Process the result
 
@@ -124,5 +152,8 @@ Do you want me to apply these corrections? (yes/no)
 - **Corrections are ONLY applied by this wrapper** (Step 5), after explicit approval.
 - **Corrections must be surgical**: only what is necessary to resolve the reported issues.
 - Maximum 2 rounds of automatic correction before escalating to manual.
-- If the sub-agent returned something out of format, inform: "The validator returned an unstructured report — continue manually."
+- **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.
+- **Agent missing (CA-12)**: checked in Step 0.6 — stop before delegating if `.claude/agents/refacil-validator.md` is absent.
 - **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`.)