refacil-sdd-ai 5.3.0 → 5.3.1

package/README.md

@@ -277,6 +277,7 @@ All invoked as `/refacil:<name>` in Claude Code, Cursor, OpenCode, or Codex.
 | `/refacil:bug` | Full bugfix flow with regression tests |
 | `/refacil:update` | Detect and apply pending methodology migrations to the current repo |
 | `/refacil:stats` | Show change progress, task status, review gate, and test commands from SDD artifacts |
+| `/refacil:status` | Show which phase of the SDD-AI cycle a change is in and the exact command to resume it |
 | `/refacil:read-spec` | Listen to change 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) is optional and configured in pre-flight. Optional WhatsApp notification via `~/.refacil-sdd-ai/kapso.env` |
 

package/agents/proposer.md

@@ -196,6 +196,16 @@ If the change involves a contract with another system (external API, event, queu
 
 If the input comes from a bus room agreement, still generate all artifacts in full according to the SDD-AI methodology. See `METHODOLOGY-CONTRACT.md` and `BUS-CROSS-REPO.md` (room agreements section).
 
+### Step 2.5: Record proposed state
+
+After writing all four artifacts, run:
+
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state proposed --actor proposer
+```
+
+This records the initial state in `memory.yaml` for cross-skill tracking. If the command fails (e.g. the change directory does not exist yet at that point), skip silently — it must not block the flow.
+
 ### Step 3: Report + JSON block
 
 Your final response MUST have this structure:

package/lib/commands/sdd.js

@@ -183,6 +183,88 @@ function serializeMemoryYaml(obj) {
   return lines.join('\n') + '\n';
 }
 
+// --- State tracking ---
+
+const VALID_STATES = [
+  'proposed',
+  'approved',
+  'apply-in-progress',
+  'applied',
+  'tested',
+  'verified',
+  'reviewed',
+  'archived',
+];
+
+/**
+ * Infers the current state of a change from its artifacts when no explicit
+ * currentState is stored in memory. Retrocompatible — never writes to disk.
+ *
+ * Priority (descending):
+ *  1. .review-passed exists                                   → 'reviewed'
+ *  2. lastStep === 'verify' or 'verified'                    → 'verified'
+ *  3. lastStep === 'test'                                     → 'tested'
+ *  4. lastStep === 'apply'                                    → 'applied'
+ *  5. tasks.md has at least one [x] and lastStep is absent   → 'apply-in-progress'
+ *  6. only proposal.md exists                                → 'proposed'
+ *  7. none of the above                                       → 'unknown'
+ *
+ * NOTE — 'approved' is intentionally absent from this table.
+ * There is no artifact signal that distinguishes an approved proposal from a
+ * merely proposed one: both have proposal.md, specs.md, design.md, tasks.md.
+ * 'approved' is set exclusively via `set-memory --state approved --actor propose-skill`
+ * when the human approves the artifacts in /refacil:propose Step 4.
+ * Inference can only detect 'proposed' (artifact exists but no explicit state recorded).
+ *
+ * @param {string} changeDir  Absolute path to the change directory.
+ * @param {object} memory     Parsed memory.yaml object (may be empty).
+ * @returns {{ currentState: string, inferred: boolean }}
+ */
+function inferCurrentState(changeDir, memory) {
+  // 1. .review-passed
+  if (fs.existsSync(path.join(changeDir, '.review-passed'))) {
+    return { currentState: 'reviewed', inferred: true };
+  }
+
+  const lastStep = memory.lastStep || null;
+
+  // 2. lastStep verify/verified
+  if (lastStep === 'verify' || lastStep === 'verified') {
+    return { currentState: 'verified', inferred: true };
+  }
+
+  // 3. lastStep test
+  if (lastStep === 'test') {
+    return { currentState: 'tested', inferred: true };
+  }
+
+  // 4. lastStep apply
+  if (lastStep === 'apply') {
+    return { currentState: 'applied', inferred: true };
+  }
+
+  // 5. tasks.md has at least one [x] and lastStep absent
+  const tasksPath = path.join(changeDir, 'tasks.md');
+  if (!lastStep && fs.existsSync(tasksPath)) {
+    try {
+      const tasksContent = fs.readFileSync(tasksPath, 'utf8');
+      if (/^- \[x\]/m.test(tasksContent)) {
+        return { currentState: 'apply-in-progress', inferred: true };
+      }
+    } catch (_) {
+      // Unexpected read error (e.g. permission denied): swallow and fall through
+      // to the proposal.md check so inference still produces a useful result.
+    }
+  }
+
+  // 6. only proposal.md exists (no design, tasks, specs)
+  if (fs.existsSync(path.join(changeDir, 'proposal.md'))) {
+    return { currentState: 'proposed', inferred: true };
+  }
+
+  return { currentState: 'unknown', inferred: true };
+}
+
 // --- Subcomandos ---
 
 function cmdValidateName(argv) {
@@ -320,7 +402,7 @@ function cmdSetMemory(argv, projectRoot) {
   const rawName = args._positional[0];
 
   if (!rawName) {
-    console.error('Uso: refacil-sdd-ai sdd set-memory <nombre-cambio> [--last-step <value>] [--stack-detected <value>] [--touched-files <csv>] [--commands-run <value>] [--criteria-run <csv>]');
+    console.error('Uso: refacil-sdd-ai sdd set-memory <nombre-cambio> [--last-step <value>] [--stack-detected <value>] [--touched-files <csv>] [--commands-run <value>] [--criteria-run <csv>] [--state <estado>] [--actor <nombre>]');
     process.exit(1);
   }
 
@@ -340,10 +422,30 @@ function cmdSetMemory(argv, projectRoot) {
     process.exit(1);
   }
 
+  // Validate --state before touching any file (CR-01: exit 1 without modifying file)
+  if (args['state'] !== undefined) {
+    const stateValue = args['state'];
+    // CR-02: empty string or bare flag (parsed as boolean true) → explicit empty-state error
+    if (stateValue === '' || stateValue === true) {
+      console.error('set-memory: el estado no puede estar vacío');
+      process.exit(1);
+    }
+    if (!VALID_STATES.includes(stateValue)) {
+      console.error(`set-memory: estado inválido '${stateValue}'. Estados válidos: ${VALID_STATES.join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  // Validate --actor: pipe character would corrupt the stateHistory pipe format
+  if (args['actor'] !== undefined && String(args['actor']).includes('|')) {
+    console.error("set-memory: --actor no puede contener el carácter '|'");
+    process.exit(1);
+  }
+
   // Require at least one field flag
-  const knownFlags = ['last-step', 'stack-detected', 'touched-files', 'commands-run', 'criteria-run'];
+  const knownFlags = ['last-step', 'stack-detected', 'touched-files', 'commands-run', 'criteria-run', 'state', 'actor'];
   if (!knownFlags.some((f) => args[f] !== undefined)) {
-    console.error('set-memory: debe especificar al menos un campo (--last-step, --stack-detected, --touched-files, --commands-run, --criteria-run)');
+    console.error('set-memory: debe especificar al menos un campo (--last-step, --stack-detected, --touched-files, --commands-run, --criteria-run, --state, --actor)');
     process.exit(1);
   }
 
@@ -370,6 +472,18 @@ function cmdSetMemory(argv, projectRoot) {
     existing['criteriaRun'] = args['criteria-run'].split(',').map((s) => s.trim()).filter(Boolean);
   }
 
+  // State tracking (T-01)
+  if (args['state'] !== undefined) {
+    const actor = args['actor'] !== undefined ? String(args['actor']) : 'cli';
+    existing['currentState'] = args['state'];
+    const iso = new Date().toISOString();
+    const entry = `${args['state']}|${iso}|${actor}`;
+    if (!Array.isArray(existing['stateHistory'])) {
+      existing['stateHistory'] = [];
+    }
+    existing['stateHistory'].push(entry);
+  }
+
   fs.writeFileSync(memoryPath, serializeMemoryYaml(existing), 'utf8');
   console.log(`memory.yaml actualizado para '${name}'`);
 }
@@ -607,12 +721,42 @@ function cmdStatus(argv, projectRoot) {
     forArchive: reviewPassed && taskStats.total > 0 && taskStats.pending === 0,
   };
 
+  // Read memory for currentState / lastStep / touchedFiles
+  const memoryPath = path.join(changeDir, 'memory.yaml');
+  let memory = {};
+  if (fs.existsSync(memoryPath)) {
+    try {
+      memory = parseYaml(fs.readFileSync(memoryPath, 'utf8')) || {};
+    } catch (_) {
+      memory = {};
+    }
+  }
+
+  // Resolve currentState: explicit from memory or inferred
+  let currentState = null;
+  let stateInferred = false;
+  if (memory.currentState) {
+    currentState = memory.currentState;
+    stateInferred = false;
+  } else {
+    const inferred = inferCurrentState(changeDir, memory);
+    currentState = inferred.currentState;
+    stateInferred = inferred.inferred;
+  }
+
+  const lastStep = memory.lastStep || null;
+  const touchedFiles = Array.isArray(memory.touchedFiles) ? memory.touchedFiles : [];
+
   const status = {
     name,
     artifacts,
     tasks: taskStats,
     reviewPassed,
     ready,
+    currentState,
+    stateInferred,
+    lastStep,
+    touchedFiles,
   };
 
   if (wantJson) {
@@ -632,6 +776,11 @@ function cmdStatus(argv, projectRoot) {
     console.log('');
     console.log(`  Review aprobado: ${reviewPassed ? 'Si' : 'No'}`);
     console.log('');
+    console.log('  Estado:');
+    console.log(`    currentState: ${currentState}${stateInferred ? ' (inferido)' : ''}`);
+    if (lastStep) console.log(`    lastStep:     ${lastStep}`);
+    if (touchedFiles.length > 0) console.log(`    touchedFiles: ${touchedFiles.join(', ')}`);
+    console.log('');
     console.log('  Listo para:');
     console.log(`    apply:   ${ready.forApply ? 'Si' : 'No'}`);
     console.log(`    archive: ${ready.forArchive ? 'Si' : 'No'}`);
@@ -948,6 +1097,18 @@ function cmdStats(argv, projectRoot) {
   const lastStep = memory.lastStep || null;
   const criteriaRun = Array.isArray(memory.criteriaRun) ? memory.criteriaRun : [];
 
+  // Resolve currentState for stats
+  let statsCurrentState = null;
+  let statsStateInferred = false;
+  if (memory.currentState) {
+    statsCurrentState = memory.currentState;
+    statsStateInferred = false;
+  } else {
+    const inferred = inferCurrentState(changeDir, memory);
+    statsCurrentState = inferred.currentState;
+    statsStateInferred = inferred.inferred;
+  }
+
   // --- Read .review-passed ---
   const reviewPassedPath = path.join(changeDir, '.review-passed');
   let reviewDate = null;
@@ -1026,6 +1187,8 @@ function cmdStats(argv, projectRoot) {
       testCommand: testCommand || null,
       lastStep: lastStep || null,
       criteriaRun,
+      currentState: statsCurrentState,
+      stateInferred: statsStateInferred,
     },
     review: {
       passed: reviewDate !== null,
@@ -1060,6 +1223,7 @@ function cmdStats(argv, projectRoot) {
   if (startDate) console.log(`  Inicio estimado:  ${startDate.toISOString().slice(0, 10)}`);
   console.log('');
   console.log('  Memory');
+  console.log(`    ${pad('currentState', 20)} ${statsCurrentState || noDataLabel}${statsStateInferred ? ' (inferido)' : ''}`);
   console.log(`    ${pad('lastStep', 20)} ${lastStep || noDataLabel}`);
   console.log(`    ${pad('criteriaRun', 20)} ${criteriaRun.length > 0 ? criteriaRun.join(', ') : noDataLabel}`);
   console.log(`    ${pad('testCommand', 20)} ${testCommand || noDataLabel}`);
@@ -1110,6 +1274,8 @@ function sddHelp() {
       [--touched-files <csv>]            Archivos modificados (separados por coma)
       [--commands-run <value>]           Comando de test ejecutado
       [--criteria-run <csv>]             Criterios CA/CR ejecutados (separados por coma)
+      [--state <estado>]                 Estado del ciclo SDD-AI (proposed, approved, apply-in-progress, applied, tested, verified, reviewed, archived)
+      [--actor <nombre>]                 Actor que origina el cambio de estado (default: cli)
     sdd get-memory <nombre>            Lee memory.yaml del cambio
       [--json]                           Salida en JSON (por defecto: YAML raw)
     sdd set-review-fails <nombre>      Escribe .review-last-fails.json con archivos fallidos
@@ -1124,8 +1290,8 @@ function sddHelp() {
       [--base-branch <branch>]           Rama base para nuevos cambios
       [--protected-branches <csv>]       Ramas protegidas (separadas por coma)
       [--artifact-language <language>]   Idioma para los artefactos SDD generados (english, spanish)
-    sdd stats <nombre> [--json]        Muestra estadísticas del cambio: memoria, review,
-                                         compact telemetry y CodeGraph en el periodo del cambio
+    sdd stats <nombre> [--json]        Muestra estadísticas del cambio: memoria (incluyendo currentState),
+                                         review, compact telemetry y CodeGraph en el periodo del cambio
     sdd test-scope                     Resolves scoped test files for the given source files
       --files <csv>                      Comma-separated source file paths to scope tests for
       [--stack <name>]                   Stack hint (node, python, go, rust, java, dotnet)
@@ -1214,4 +1380,6 @@ module.exports = {
   cmdWriteConfig,
   cmdStats,
   cmdTestScope,
+  VALID_STATES,
+  inferCurrentState,
 };

package/lib/installer.js

@@ -39,6 +39,7 @@ const SKILLS = [
   'attend',
   'update',
   'stats',
+  'status',
 ];
 
 const AGENTS = [

package/lib/kapso.js

@@ -66,6 +66,51 @@ function postMessage(creds, bodyText) {
   });
 }
 
+// ─── validation ────────────────────────────────────────────────────────────────
+
+// Unfilled template token left in the command, e.g. "<changeName>" or "<repoSlug>".
+const PLACEHOLDER_REGEX = /<[^>]+>/;
+
+function isBlankOrPlaceholder(value) {
+  if (value === null || value === undefined) return true;
+  const s = String(value).trim();
+  if (s === '') return true;
+  if (PLACEHOLDER_REGEX.test(s)) return true;
+  return false;
+}
+
+// Returns a list of human-readable problems with the notify payload.
+// Empty list ⇒ the payload is complete enough to send.
+//
+// This is the guard against the autopilot failure mode where the skill fires
+// `kapso notify` once with unfilled <placeholders>/empty flags (sending a junk
+// WhatsApp message) and again with the real values. We reject the incomplete
+// call so it never reaches postMessage().
+function validateNotifyOpts(type, opts) {
+  const problems = [];
+  const required =
+    type === 'success'
+      ? ['repo', 'change', 'branch', 'tasks']
+      : ['repo', 'change', 'branch', 'phase'];
+
+  for (const field of required) {
+    if (isBlankOrPlaceholder(opts[field])) {
+      problems.push(`--${field} faltante, vacío o sin rellenar`);
+    }
+  }
+
+  // tasks must look like "done/total" (e.g. "5/5"), not a placeholder or prose.
+  if (
+    type === 'success' &&
+    !isBlankOrPlaceholder(opts.tasks) &&
+    !/^\d+\/\d+$/.test(String(opts.tasks).trim())
+  ) {
+    problems.push(`--tasks con formato inválido (esperado "done/total"): "${opts.tasks}"`);
+  }
+
+  return problems;
+}
+
 // ─── log ─────────────────────────────────────────────────────────────────────
 
 function appendLog(msg) {
@@ -150,6 +195,23 @@ function preflight() {
 // kapso notify failure --repo <slug> --change <name> --branch <branch>
 //   --phase <phase> --last-commit "<commit>" --error "<summary>"
 async function notify(type, opts) {
+  if (type !== 'success' && type !== 'failure') {
+    console.error(`  Unknown notify type: "${type}". Use "success" or "failure".`);
+    process.exit(1);
+  }
+
+  // Reject incomplete/placeholder payloads BEFORE doing anything else so a junk
+  // notification is never sent. Throwing surfaces a clear, actionable error to
+  // the caller (autopilot) without ever hitting the WhatsApp API.
+  const problems = validateNotifyOpts(type, opts);
+  if (problems.length > 0) {
+    appendLog(`kapso notify ${type} REJECTED (datos inválidos): ${problems.join('; ')}`);
+    throw new Error(
+      `kapso notify ${type}: datos inválidos o incompletos — ${problems.join('; ')}. ` +
+        'No se envió la notificación. Reintenta con todos los flags requeridos rellenados con valores reales.',
+    );
+  }
+
   const creds = readCredentials();
   if (!creds) {
     appendLog('kapso notify skipped: no credentials');
@@ -218,9 +280,6 @@ async function notify(type, opts) {
       '',
       'El árbol de trabajo quedó en su estado actual para revisión.',
     ].join('\n');
-  } else {
-    console.error(`  Unknown notify type: "${type}". Use "success" or "failure".`);
-    process.exit(1);
   }
 
   try {
@@ -238,4 +297,12 @@ async function notify(type, opts) {
   }
 }
 
-module.exports = { setup, preflight, notify, readCredentials, PHONE_REGEX };
+module.exports = {
+  setup,
+  preflight,
+  notify,
+  readCredentials,
+  validateNotifyOpts,
+  isBlankOrPlaceholder,
+  PHONE_REGEX,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor, OpenCode and Codex",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "postinstall": "node ./bin/postinstall.js",
-    "test": "node --test --test-concurrency=1 test/global-paths.test.js test/opencode-global-path-windows.test.js test/opencode-migrate.test.js test/opencode-clean-global.test.js test/skills-parity.test.js test/multi-ide-parity-pass2.test.js test/repo-ide-sync.test.js test/global-install.test.js test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/test-scope.test.js test/config.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js test/project-root.test.js test/opencode-installer.test.js test/opencode-plugin.test.js test/check-review.test.js test/toml-converter.test.js test/testing-policy-sync.test.js test/session-repo-sync.test.js test/compact-guidance.test.js test/codegraph.test.js test/codegraph-telemetry.test.js test/compact-codegraph.test.js test/autopilot-skill-install.test.js test/read-spec-md-parser.test.js test/read-spec.test.js test/spec-sync.test.js test/kapso-init-session-removed.test.js test/kapso-preflight.test.js test/autopilot-ready-message.test.js test/stats-observability.test.js test/bus-from-env.test.js test/imp-scoped-test-execution.test.js test/broker-port-env.test.js"
+    "test": "node --test --test-concurrency=1 test/global-paths.test.js test/opencode-global-path-windows.test.js test/opencode-migrate.test.js test/opencode-clean-global.test.js test/skills-parity.test.js test/multi-ide-parity-pass2.test.js test/repo-ide-sync.test.js test/global-install.test.js test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/test-scope.test.js test/config.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js test/project-root.test.js test/opencode-installer.test.js test/opencode-plugin.test.js test/check-review.test.js test/toml-converter.test.js test/testing-policy-sync.test.js test/session-repo-sync.test.js test/compact-guidance.test.js test/codegraph.test.js test/codegraph-telemetry.test.js test/compact-codegraph.test.js test/autopilot-skill-install.test.js test/read-spec-md-parser.test.js test/read-spec.test.js test/spec-sync.test.js test/kapso-init-session-removed.test.js test/kapso-preflight.test.js test/autopilot-ready-message.test.js test/stats-observability.test.js test/bus-from-env.test.js test/imp-scoped-test-execution.test.js test/broker-port-env.test.js test/change-state-tracking.test.js"
   },
   "dependencies": {
     "smol-toml": "^1.6.1",

package/skills/apply/SKILL.md

@@ -113,6 +113,14 @@ specsNote: <"specs.md" | "specs/**/*.md" | "both — report contradictions in is
 
 ### Step 2: Delegate to the refacil-implementer sub-agent
 
+Before delegating, record that implementation has started:
+
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state apply-in-progress --actor apply-skill
+```
+
+If the command fails, continue silently — it must not block the flow.
+
 Invoke the `refacil-implementer` sub-agent passing it the BRIEFING from the previous step plus:
 - `changeName` (redundant with the briefing, but the guardrail needs it)
 - If the user requested detailed mode, indicate it. Default: concise.
@@ -130,7 +138,9 @@ Run:
 ```bash
 refacil-sdd-ai sdd set-memory <changeName> \
   --last-step apply \
-  --touched-files "<comma-separated list of modified files>"
+  --touched-files "<comma-separated list of modified files>" \
+  --state applied \
+  --actor apply-skill
 ```
 
 This command merges into memory.yaml at the repo root using `findProjectRoot()` — no manual path construction needed.

package/skills/archive/SKILL.md

@@ -174,10 +174,18 @@ Minimal bug fixes only contain `summary.md` (and optionally `.review-passed`) an
      ```
    - 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>` — sync-spec, preserves `memory.yaml` if present, then moves the complete change directory to `refacil-sdd/changes/archive/<date>-<changeName>/`.
-4. Verify the command completed successfully (exit 0) and the original folder no longer exists.
+3. **Record archived state** — run this command **while the change directory is still at its original path** (`refacil-sdd/changes/<changeName>/`), before the CLI move in step 4. After the move that path no longer exists and `set-memory` would fail to locate the change:
 
-5. Continue to **Step 3**.
+   ```bash
+   refacil-sdd-ai sdd set-memory <changeName> --state archived --actor archive-skill
+   ```
+
+   If the command fails, continue silently — it must not block the flow.
+
+4. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — sync-spec, preserves `memory.yaml` if present, then moves the complete change directory to `refacil-sdd/changes/archive/<date>-<changeName>/`.
+5. Verify the command completed successfully (exit 0) and the original folder no longer exists.
+
+6. Continue to **Step 3**.
 
 The goal is for `refacil-sdd/specs/` to document how the system works TODAY.
 

package/skills/autopilot/SKILL.md

@@ -354,9 +354,10 @@ When any phase fails:
    - `errorSummary`: 1-3 line summary.
    - `branchAtFailure`: `git branch --show-current`.
    - `lastCommit`: `git log -1 --oneline`.
-4. Delete the autopilot marker: `rm -f "refacil-sdd/.autopilot-active"`.
-5. Send the failure notification via Kapso only if `kapsoEnabled = true` (Step 7, failure template).
-6. Leave the working tree as-is so the user can inspect when they return. Normal recovery must never use destructive reset commands; preserve local edits and report the evidence needed for manual repair.
+4. Send the failure notification via Kapso only if `kapsoEnabled = true` (Step 7, failure template).
+5. Leave the working tree as-is so the user can inspect when they return. Normal recovery must never use destructive reset commands; preserve local edits and report the evidence needed for manual repair.
+
+> **Note**: do NOT delete `refacil-sdd/.autopilot-active` here. Step 8 deletes the marker unconditionally at the end of the cycle — this keeps the marker alive during Step 7 in both success and failure paths, so the CLI can compute the exact duration from `startedAt`.
 
 ### Step 7: Notify via Kapso
 
@@ -364,37 +365,65 @@ When any phase fails:
 
 All notification logic — credentials, message formatting, HTTP call, error logging — is handled by the CLI. Do NOT construct curl calls or read the env file directly.
 
+**Send the notification exactly ONCE, with every flag resolved to a real value — never a placeholder.** Before invoking `kapso notify`, confirm that `repoSlug`, `changeName`, `branchAtStart`/`branchAtFailure`, `tasks.done`/`tasks.total` (and `phase` on failure) are all filled with concrete values captured in Steps 0–6 — there must be no literal `<...>` token left in the command. Do NOT fire a first "probe" call and then a corrected one: a single notification per run. The CLI **rejects** any `notify` whose required flags are missing, empty, or still contain a `<placeholder>` (it exits non-zero without sending, and prints which flags are wrong). If you see that rejection, it means a value was not resolved — fill it in from the captured state and invoke once more; do not let an empty notification go out.
+
 **Success notification**:
 
+Required flags (validated by `validateNotifyOpts`; the CLI rejects the call if any is missing or contains a placeholder):
+- `--repo` — repository slug (e.g. `refacil-ia`)
+- `--change` — change name (e.g. `imp-session-timeout-redis`)
+- `--branch` — branch at start (e.g. `feature/imp-session-timeout-redis`)
+- `--tasks` — tasks in `done/total` format (e.g. `5/5`). Must match `^\d+/\d+$`.
+
+Optional flags (omit if not applicable):
+- `--pr` — PR link, empty string, or `"skipped"` (see rules below)
+- `--apply`, `--test`, `--review` — improvement counters (integer, default `0`)
+- `--warnings` — top 3 warning strings joined by `|` (omit or pass `""` if none)
+
+> **Duration**: the CLI computes the run duration automatically from the `startedAt` field written to `.autopilot-active` in Step 0.7. You do **not** need to pass `--duration` — omit it and the CLI reads `startedAt` from the marker. Only pass `--duration <minutes>` as a manual fallback if the marker was unavailable for some reason (this should never happen with the corrected Step 6 that no longer deletes the marker before Step 7).
+
 The `--pr` flag value depends on `includeUpCode`:
 - `includeUpCode = true` and push succeeded with PR → `--pr "<prLink>"`
 - `includeUpCode = true` and push succeeded without PR (`createPR = false`) → `--pr ""` (empty string)
 - `includeUpCode = false` → `--pr "skipped"`
 
+Example (all required flags filled with real values):
+
 ```bash
 refacil-sdd-ai kapso notify success \
-  --repo "<repoSlug>" \
-  --change "<changeName>" \
-  --branch "<branchAtStart>" \
-  --tasks "<tasks.done>/<tasks.total>" \
-  --duration "<minutes>" \
-  --pr "<prLink | empty string | skipped>" \
-  --apply "<improvementsApplied.apply>" \
-  --test "<improvementsApplied.test>" \
-  --review "<improvementsApplied.review>" \
-  --warnings "<top 3 warnings joined by | or empty>"
+  --repo "refacil-ia" \
+  --change "imp-session-timeout-redis" \
+  --branch "feature/imp-session-timeout-redis" \
+  --tasks "5/5" \
+  --pr "https://github.com/org/refacil-ia/pull/42" \
+  --apply "1" \
+  --test "0" \
+  --review "0" \
+  --warnings ""
 ```
 
 **Failure notification**:
 
+Required flags:
+- `--repo` — repository slug
+- `--change` — change name
+- `--branch` — branch at the moment of failure (`branchAtFailure`)
+- `--phase` — which phase failed (e.g. `verify`, `test`, `apply`, `review`, `archive`, `up-code`)
+
+Optional flags:
+- `--last-commit` — last commit hash + message from `git log -1 --oneline`
+- `--error` — 1-3 line error summary
+
+Example (all required flags filled with real values):
+
 ```bash
 refacil-sdd-ai kapso notify failure \
-  --repo "<repoSlug>" \
-  --change "<changeName>" \
-  --branch "<branchAtFailure>" \
-  --phase "<phase>" \
-  --last-commit "<lastCommit>" \
-  --error "<errorSummary>"
+  --repo "refacil-ia" \
+  --change "imp-session-timeout-redis" \
+  --branch "feature/imp-session-timeout-redis" \
+  --phase "verify" \
+  --last-commit "a1b2c3d feat: add session timeout to Redis store" \
+  --error "verify: 2 unresolved CRITICAL findings after 2 autofix rounds"
 ```
 
 The CLI reads credentials from `~/.refacil-sdd-ai/kapso.env` internally. If Kapso returns an error, it logs to `~/.refacil-sdd-ai/autopilot.log` and exits without crashing — the SDD work is intact.

package/skills/guide/SKILL.md

@@ -35,10 +35,13 @@ You are a **brief** guide: you choose the next command; the detail of each flow
 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>`)
+14. Current phase and resume → `/refacil:status` — which phase of the SDD-AI cycle a change is in and the exact command to resume it (`refacil-sdd-ai sdd status <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`.
+> **Skill parity**: 22 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`, `stats`, and `status`.
+
+> **stats vs status**: `/refacil:stats` shows **telemetry** (token savings, compact rewrites, CodeGraph calls, review history). `/refacil:status` shows **navigation** (current cycle phase, next skill to run, state history). Use status to navigate the flow; use stats for observability data.
 
 ### After `/refacil:propose` is approved
 
@@ -91,6 +94,7 @@ Full detail in the refacil-sdd-ai README (section `refacil-bus`).
   - Option 11 (Autonomous pipeline) → `/refacil:autopilot`
   - Option 12 (Listen to specs) → `/refacil:read-spec`
   - Option 13 (Change progress) → `/refacil:stats`
+  - Option 14 (Current phase and resume) → `/refacil:status`
   - 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.
 

package/skills/propose/SKILL.md

@@ -132,6 +132,14 @@ If the user requests limited adjustments (change a criterion, fix a path, adjust
 
 ### Step 4: Next step
 
+**Before presenting the menu**, record that the proposal has been approved by running:
+
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state approved --actor propose-skill
+```
+
+If the command fails, continue silently — it must not block the flow.
+
 **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.

package/skills/review/SKILL.md

@@ -167,6 +167,14 @@ Where the values are extracted from the sub-agent's `refacil-review-result` bloc
 - `changeName` is null.
 - The sub-agent returned `SCOPE_ERROR`.
 
+After writing `.review-passed` with an approved verdict, record the state:
+
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state reviewed --actor review-skill
+```
+
+If the command fails or `changeName` is null, continue silently — it must not block the flow.
+
 ### Step 3.5: Offer to apply corrections (only if REQUIERE CORRECCIONES)
 
 If `verdict` is `REQUIERE CORRECCIONES`:

package/skills/stats/SKILL.md

@@ -51,7 +51,9 @@ Parse the JSON block returned by the CLI. Expected fields:
   "memory": {
     "testCommand": "<command or null>",
     "lastStep": "<step or null>",
-    "criteriaRun": ["CA-01", "CR-01", ...]
+    "criteriaRun": ["CA-01", "CR-01", ...],
+    "currentState": "<state or null>",
+    "stateInferred": true | false
   },
   "review": {
     "passed": true | false,
@@ -86,6 +88,7 @@ Present the data in a readable format. If `isArchived` is `true`, add `[archivad
 
 Phase progress
   Started:    <startDate or "unknown">
+  Current state: <currentState or "unknown"> <(inferred) if stateInferred is true>
   Last step:  <lastStep or "not recorded">
   Criteria:   <criteriaRun list or "none">
 

package/skills/status/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: refacil:status
+description: Show which phase of the SDD-AI cycle a change is in and the exact command to resume it — use for "where am I?", "how is it going?", "status of the change", "resume", "where did I leave off". Distinct from /refacil:stats (which shows telemetry, token savings, and review metrics). Use /refacil:status to navigate the flow; use /refacil:stats for observability data.
+user-invocable: true
+---
+
+# refacil:status — Current Phase and Resume
+
+This skill answers: **"In which phase of the SDD-AI cycle is this change, and what command do I run next?"**
+
+It is distinct from `/refacil:stats`:
+- `/refacil:status` — **navigation**: current phase, next skill to run, resume a paused flow.
+- `/refacil:stats` — **telemetry**: token savings, compact rewrites, CodeGraph calls, review history.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md`.
+
+## Activation phrases
+
+Invoke this skill for expressions like: "¿en qué va?", "¿cómo voy?", "status del cambio", "retomar", "dónde quedé", "where did I leave off?", "resume", "what's the current state?", "what's next?".
+
+## Next-skill mapping
+
+The following table maps each state to the recommended next skill in the **normal flow** and in the **bug fix flow** (`fix-*`):
+
+| State             | Normal flow next skill   | Bug fix (fix-*) next skill |
+|-------------------|--------------------------|---------------------------|
+| `proposed`        | `/refacil:propose` (approve or adjust) | — |
+| `approved`        | `/refacil:apply`         | `/refacil:apply`          |
+| `apply-in-progress` | `/refacil:apply`       | `/refacil:apply`          |
+| `applied`         | `/refacil:test`          | `/refacil:test`           |
+| `tested`          | `/refacil:verify`        | `/refacil:review` (bugs omit verify) |
+| `verified`        | `/refacil:review`        | — (n/a: bugs never reach verified) |
+| `reviewed`        | `/refacil:archive`       | `/refacil:archive`        |
+| `archived`        | `/refacil:up-code`       | `/refacil:up-code`        |
+| `unknown`         | Run `/refacil:propose` to create artifacts | — |
+
+## Flow
+
+### Without argument — overview of all active changes
+
+1. Run `refacil-sdd-ai sdd list --json` to get all active changes.
+
+2. If the list is empty, inform the user:
+   ```
+   No active changes found. Run /refacil:propose to start a new change.
+   ```
+   Stop.
+
+3. For each active change, run `refacil-sdd-ai sdd status <changeName> --json` and collect:
+   - `currentState` and `stateInferred`
+   - `tasks.done` / `tasks.total`
+   - `reviewPassed`
+
+4. Present a summary table:
+
+   ```
+   === Active changes ===
+
+   Change                Phase                      Next command
+   ─────────────────────────────────────────────────────────────────
+   <changeName>          <currentState> (inferred?)  <next skill>
+   ...
+   ```
+
+   For each row, derive the next skill from the **next-skill mapping** above (use the normal flow unless the change name starts with `fix-`).
+
+   State history is shown only in the detail view — pass a change name as argument to see the full transition log.
+
+### With argument — detail for one change
+
+1. Use `$ARGUMENTS` as `changeName`.
+
+2. Run `refacil-sdd-ai sdd status <changeName> --json` and parse the output.
+
+3. If the command exits 1 (change not found), inform the user and stop.
+
+4. Resolve `currentState`:
+   - Use `status.currentState` from the JSON directly.
+   - If `stateInferred` is `true`, note it as `(inferred from artifacts)`.
+
+5. Parse `stateHistory` from memory (if available):
+   - Run `refacil-sdd-ai sdd get-memory <changeName> --json`.
+   - Read the `stateHistory` array. Each entry is a pipe-separated string `"<state>|<ISO>|<actor>"`.
+   - Parse each entry with `entry.split('|')` → `[state, iso, actor]`.
+   - Show the last 5 entries (most recent last) as a compact history.
+
+6. Determine the next skill from the **next-skill mapping** table above.
+
+7. Present:
+
+   ```
+   === Status: <changeName> ===
+
+   Current phase:  <currentState> <(inferred from artifacts)?>
+   Last step:      <lastStep or "not recorded">
+   Touched files:  <touchedFiles list or "none">
+
+   State history (last 5):
+     <date> — <state> (by <actor>)
+     ...
+
+   Next command:   <next skill>
+   ```
+
+   If the change is in `archived` state, add:
+   ```
+   This change is fully archived. Run /refacil:up-code to push and create the PR.
+   ```
+
+## Rules
+
+- **Read-only**: this skill does not modify any file, branch, or memory.
+- **Graceful degradation**: if `stateHistory` is absent or `get-memory` fails, show the current state without history. Do not error.
+- **Empty list behavior**: if `sdd list --json` returns `[]`, inform the user and stop without error.
+- **Bug fix detection**: if `changeName` starts with `fix-`, use the bug fix flow column in the next-skill table. The bug flow skips `/refacil:verify`: a `tested` fix goes straight to `/refacil:review`, and a fix never reaches the `verified` state.
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) after the status display and there is a single unambiguous next skill, immediately execute that skill. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/test/SKILL.md

@@ -124,7 +124,9 @@ Run:
 refacil-sdd-ai sdd set-memory <changeName> \
   --last-step test \
   --commands-run "<test command used>" \
-  --criteria-run "<comma-separated criteria IDs that were run>"
+  --criteria-run "<comma-separated criteria IDs that were run>" \
+  --state tested \
+  --actor test-skill
 ```
 
 If `stackDetected` is available, add `--stack-detected "<stack>"` to the command as well.

package/skills/verify/SKILL.md

@@ -148,6 +148,14 @@ Parse the ` ```refacil-verify-result ` block from the sub-agent.
 
 #### If `result` is APPROVED:
 
+Record that verification completed successfully:
+
+```bash
+refacil-sdd-ai sdd set-memory <changeName> --state verified --actor verify-skill
+```
+
+If the command fails, continue silently — it must not block the flow.
+
 - `autopilotMode = false` (normal): ask the user:
   ```
   RESULT: APPROVED