refacil-sdd-ai 4.2.4 → 4.4.0

package/lib/methodology-migration-pending.js

@@ -1,136 +1,101 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Motor compartido con `refacil-sdd-ai migration-pending`, hooks `check-update` / `notify-update`
- * y la skill `refacil:update`. Si ninguna condicion aplica, no hace falta migrar metodologia.
- */
-const REQUIRED_OPENSPEC_SKILLS = new Set([
-  'openspec-propose',
-  'openspec-explore',
-  'openspec-apply-change',
-  'openspec-archive-change',
-  'openspec-verify-change',
-]);
-
-const REQUIRED_OPSX_CLAUDE = new Set([
-  'apply.md',
-  'archive.md',
-  'explore.md',
-  'propose.md',
-  'verify.md',
-]);
-
-const REQUIRED_OPSX_CURSOR = new Set([
-  'opsx-apply.md',
-  'opsx-archive.md',
-  'opsx-explore.md',
-  'opsx-propose.md',
-  'opsx-verify.md',
-]);
-
-function legacyIndexDoc(filePath) {
-  if (!fs.existsSync(filePath)) return false;
-  const content = fs.readFileSync(filePath, 'utf8');
-  const lines = content.split(/\r?\n/).length;
-  const pointsToAgents = /AGENTS\.md/i.test(content);
-  return lines > 5 || !pointsToAgents;
-}
-
-function collectExtraOpenspecSkills(root) {
-  const out = [];
-  for (const rel of ['.claude/skills', '.cursor/skills']) {
-    const full = path.join(root, rel);
-    if (!fs.existsSync(full)) continue;
-    let names;
-    try {
-      names = fs.readdirSync(full, { withFileTypes: true });
-    } catch (_) {
-      continue;
-    }
-    for (const d of names) {
-      if (!d.isDirectory()) continue;
-      const name = d.name;
-      if (!name.startsWith('openspec-')) continue;
-      if (REQUIRED_OPENSPEC_SKILLS.has(name)) continue;
-      out.push(path.join(rel, name));
-    }
-  }
-  return out;
-}
-
-function collectExtraOpsxClaude(root) {
-  const dir = path.join(root, '.claude', 'commands', 'opsx');
-  if (!fs.existsSync(dir)) return [];
-  let names;
-  try {
-    names = fs.readdirSync(dir);
-  } catch (_) {
-    return [];
-  }
-  const extra = [];
-  for (const name of names) {
-    if (!name.endsWith('.md')) continue;
-    if (REQUIRED_OPSX_CLAUDE.has(name)) continue;
-    extra.push(path.join('.claude/commands/opsx', name));
-  }
-  return extra;
-}
-
-function collectExtraOpsxCursor(root) {
-  const dir = path.join(root, '.cursor', 'commands');
-  if (!fs.existsSync(dir)) return [];
-  let names;
-  try {
-    names = fs.readdirSync(dir);
-  } catch (_) {
-    return [];
-  }
-  const extra = [];
-  for (const name of names) {
-    if (!name.startsWith('opsx-') || !name.endsWith('.md')) continue;
-    if (REQUIRED_OPSX_CURSOR.has(name)) continue;
-    extra.push(path.join('.cursor/commands', name));
-  }
-  return extra;
-}
-
-/**
- * @param {string} root - raíz del repo
- * @returns {{ pending: boolean, reasons: string[] }}
- */
-function methodologyMigrationPending(root) {
-  const reasons = [];
-
-  const agentsMd = path.join(root, 'AGENTS.md');
-  const agentsDir = path.join(root, '.agents');
-  if (fs.existsSync(agentsMd) && !fs.existsSync(agentsDir)) {
-    reasons.push('AGENTS.md existe sin carpeta .agents/');
-  }
-
-  const claudeMd = path.join(root, 'CLAUDE.md');
-  if (legacyIndexDoc(claudeMd)) {
-    reasons.push('CLAUDE.md requiere normalización (índice mínimo → AGENTS.md)');
-  }
-
-  const cursorRules = path.join(root, '.cursorrules');
-  if (legacyIndexDoc(cursorRules)) {
-    reasons.push('.cursorrules requiere normalización (índice mínimo → AGENTS.md)');
-  }
-
-  const extraSkills = collectExtraOpenspecSkills(root);
-  if (extraSkills.length) {
-    reasons.push(`skills OpenSpec sobrantes: ${extraSkills.join(', ')}`);
-  }
-
-  const extraOpsx = [...collectExtraOpsxClaude(root), ...collectExtraOpsxCursor(root)];
-  if (extraOpsx.length) {
-    reasons.push(`commands opsx sobrantes: ${extraOpsx.join(', ')}`);
-  }
-
-  return { pending: reasons.length > 0, reasons };
-}
-
-module.exports = { methodologyMigrationPending };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Motor compartido con `refacil-sdd-ai migration-pending`, hooks `check-update` / `notify-update`
+ * y la skill `refacil:update`. Si ninguna condicion aplica, no hace falta migrar metodologia.
+ */
+const REQUIRED_OPSX_CLAUDE = new Set([
+  'apply.md',
+  'archive.md',
+  'explore.md',
+  'propose.md',
+  'verify.md',
+]);
+
+const REQUIRED_OPSX_CURSOR = new Set([
+  'opsx-apply.md',
+  'opsx-archive.md',
+  'opsx-explore.md',
+  'opsx-propose.md',
+  'opsx-verify.md',
+]);
+
+function legacyIndexDoc(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split(/\r?\n/).length;
+  const pointsToAgents = /AGENTS\.md/i.test(content);
+  return lines > 5 || !pointsToAgents;
+}
+
+function collectExtraOpsxClaude(root) {
+  const dir = path.join(root, '.claude', 'commands', 'opsx');
+  if (!fs.existsSync(dir)) return [];
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const extra = [];
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    if (REQUIRED_OPSX_CLAUDE.has(name)) continue;
+    extra.push(path.join('.claude/commands/opsx', name));
+  }
+  return extra;
+}
+
+function collectExtraOpsxCursor(root) {
+  const dir = path.join(root, '.cursor', 'commands');
+  if (!fs.existsSync(dir)) return [];
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const extra = [];
+  for (const name of names) {
+    if (!name.startsWith('opsx-') || !name.endsWith('.md')) continue;
+    if (REQUIRED_OPSX_CURSOR.has(name)) continue;
+    extra.push(path.join('.cursor/commands', name));
+  }
+  return extra;
+}
+
+/**
+ * @param {string} root - raíz del repo
+ * @returns {{ pending: boolean, reasons: string[] }}
+ */
+function methodologyMigrationPending(root) {
+  const reasons = [];
+
+  const agentsMd = path.join(root, 'AGENTS.md');
+  const agentsDir = path.join(root, '.agents');
+  if (fs.existsSync(agentsMd) && !fs.existsSync(agentsDir)) {
+    reasons.push('AGENTS.md existe sin carpeta .agents/');
+  }
+
+  const claudeMd = path.join(root, 'CLAUDE.md');
+  if (legacyIndexDoc(claudeMd)) {
+    reasons.push('CLAUDE.md requiere normalización (índice mínimo → AGENTS.md)');
+  }
+
+  const cursorRules = path.join(root, '.cursorrules');
+  if (legacyIndexDoc(cursorRules)) {
+    reasons.push('.cursorrules requiere normalización (índice mínimo → AGENTS.md)');
+  }
+
+  const extraOpsx = [...collectExtraOpsxClaude(root), ...collectExtraOpsxCursor(root)];
+  if (extraOpsx.length) {
+    reasons.push(`commands opsx sobrantes: ${extraOpsx.join(', ')}`);
+  }
+
+  return { pending: reasons.length > 0, reasons };
+}
+
+module.exports = { methodologyMigrationPending };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.2.4",
-  "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
+  "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"
   },
@@ -11,7 +11,6 @@
     "skills/",
     "agents/",
     "templates/",
-    "config/",
     "README.md",
     "refacil-bus-diagrams.md"
   ],
@@ -19,7 +18,6 @@
     "ai",
     "development",
     "methodology",
-    "openspec",
     "claude-code",
     "cursor",
     "sdd",
@@ -34,10 +32,10 @@
     "url": ""
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js"
+    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.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"
   },
   "dependencies": {
     "ws": "^8.18.0"

package/skills/apply/SKILL.md

@@ -1,120 +1,139 @@
----
-name: refacil:apply
-description: Implementar las tasks de un cambio propuesto — verifica artefactos y rama de trabajo, construye un briefing estructurado y delega al sub-agente refacil-implementer para ejecutar la implementacion en contexto aislado
-user-invocable: true
----
-
-# refacil:apply — Entrypoint de Implementacion
-
-Este skill es un **wrapper** que verifica las precondiciones criticas (artefactos SDD y rama de trabajo), construye un **briefing estructurado** con el contexto clave ya extraido, y delega la implementacion al sub-agente `refacil-implementer`. El briefing evita que el sub-agente redescubra desde cero — arranca implementando, no explorando.
-
-**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
-
-## Flujo
-
-### Paso 0: Verificar que existan artefactos SDD (bloqueante)
-
-Por cada carpeta bajo `openspec/changes/` (excluye `archive/` si aplica), comprueba:
-
-| Artefacto | Requisito |
-|-----------|-----------|
-| `proposal.md` | Obligatorio en la raiz del cambio |
-| `design.md` | Obligatorio en la raiz del cambio |
-| `tasks.md` | Obligatorio en la raiz del cambio |
-| **Especificacion** | **`specs.md` en la raiz** **O** al menos un `.md` bajo `specs/` del cambio (recursivo) |
-
-OpenSpec a veces solo genera el arbol `specs/**/*.md`; eso **cumple** la fila de especificacion. Ver `OPENSPEC-DELTAS.md` (seccion **Specs: archivo unico vs arbol**).
-
-- **Si `openspec/changes/` no existe o no hay cambios activos**: informa que ejecute `/refacil:propose` y **detente**.
-
-- **Si falta proposal, design o tasks**, o **no hay ni `specs.md` ni ningun `.md` bajo `specs/`**:
-  ```
-  El cambio en openspec/changes/[nombre]/ esta incompleto.
-  Faltan: [lista]
-  Ejecuta: /refacil:propose para completar los artefactos antes de implementar.
-  ```
-  **Detente.**
-
-- **Multiples cambios activos**: lista carpetas y pregunta cual implementar. No invoques al sub-agente con scope ambiguo.
-
-**IMPORTANTE**: Este comando NUNCA genera artefactos SDD. Si no existen, el usuario debe usar `/refacil:propose`.
-
-### Paso 1: Validar rama de trabajo (bloqueante — antes de delegar)
-
-Ejecuta `git branch --show-current` para obtener la rama actual.
-
-Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
-
-- **Si la rama actual es protegida**: ejecutar el protocolo completo de creacion de rama **antes de continuar**. No delegar al sub-agente hasta estar en una rama de trabajo.
-- Para `refacil:apply`, el prefijo sugerido de rama es `feature/`.
-- Si la rama actual ya es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continuar sin interrumpir.
-- Si el usuario no aprueba la creacion/cambio de rama, **detener**. No continuar con la implementacion.
-
-### Paso 1.5: Construir briefing estructurado (reduce tool calls del sub-agente)
-
-Antes de invocar al sub-agente, extrae el contexto clave leyendo los artefactos. Esto evita que el sub-agente los redescubra desde cero.
-
-1. **Objetivo** — lee la primera seccion de `openspec/changes/<changeName>/proposal.md`. Extrae el objetivo en 1-2 oraciones.
-2. **Scope de archivos** — lee `openspec/changes/<changeName>/design.md`. Extrae:
-   - Lista de archivos a **crear** (rutas completas)
-   - Lista de archivos a **modificar** (rutas completas)
-3. **Tasks** — lee `openspec/changes/<changeName>/tasks.md`. Extrae la lista numerada completa.
-4. **Comando de test** — lee `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3. Extrae el comando exacto.
-5. **Contexto de arquitectura** — lee `.agents/stack.md` si existe; si no, `.agents/architecture.md`; si no existe ninguno, lee solo las primeras 60 lineas de `AGENTS.md`. **No leas la carpeta completa `.agents/`**.
-
-Construye el bloque BRIEFING que incluiras literalmente en el prompt de delegacion:
-
-```
-BRIEFING:
-changeName: <nombre>
-objective: <objetivo en 1-2 oraciones del proposal>
-scope:
-  create: [ruta/archivo-nuevo-1.ts, ruta/archivo-nuevo-2.ts, ...]
-  modify: [ruta/existente-1.ts, ruta/existente-2.ts, ...]
-  doNotTouch: [openspec/, .claude/, .cursor/, AGENTS.md, package-lock.json]
-tasks:
-  1. <task 1>
-  2. <task 2>
-  ...
-testCommand: <comando exacto>
-architectureContext: |
-  <extracto de stack.md o primeras lineas de AGENTS.md>
-specsNote: <"specs.md" | "specs/**/*.md" | "ambos — reportar contradicciones en issues">
-```
-
-### Paso 2: Delegar al sub-agente refacil-implementer
-
-Invoca al sub-agente `refacil-implementer` pasandole el BRIEFING del paso anterior mas:
-- `changeName` (redundante con el briefing, pero lo necesita el guardrail)
-- Si el usuario pidio modo detallado, indicaselo. Default: conciso.
-
-El sub-agente usara el briefing como guia primaria y solo leera los archivos en `scope.modify` para entender interfaces existentes — no re-leera los artefactos ya extraidos.
-
-Retorna UN solo mensaje con el reporte + bloque JSON fenced como ` ```refacil-apply-result `.
-
-### Paso 3: Presentar resultado y siguiente paso
-
-Muestra al usuario el **reporte** (todo lo anterior al bloque `refacil-apply-result`). No muestres el bloque JSON — es metadata interna.
-
-Despues del reporte agrega:
-
-```
-El siguiente paso es generar/ajustar tests unitarios.
-Quieres que continue con /refacil:test?
-(Luego el flujo sigue con /refacil:verify)
-```
-
-Si el sub-agente retorno `result: "PARCIAL"` o `"FALLO"`, presenta los `issues` al usuario y pide instrucciones antes de continuar.
-
-## Reglas
-
-- NUNCA generar artefactos SDD desde este comando — eso es responsabilidad exclusiva de `/refacil:propose`.
-- Cumplir las precondiciones del Paso 0 (artefactos completos) y del Paso 1 (rama de trabajo valida) **antes de delegar**.
-- **Siempre construye el briefing (Paso 1.5) antes de delegar** — es la pieza clave que reduce el costo del sub-agente.
-- **Siempre delega la implementacion al sub-agente**. No repliques aqui la logica de implementacion ni de lectura de OpenSpec apply.
-- **No muestres el bloque JSON al usuario**. Es solo metadata interna.
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 3, invocar inmediatamente el **Skill tool** con `skill: "refacil:test"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:test`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-implementer.md` (fuente: `refacil-sdd-ai/agents/implementer.md`)
+---
+name: refacil:apply
+description: Implement the tasks of a proposed change — verifies artifacts and working branch, builds a structured briefing, and delegates to the refacil-implementer sub-agent to execute the implementation in isolated context
+user-invocable: true
+---
+
+# refacil:apply — Implementation Entrypoint
+
+This skill is a **wrapper** that verifies the critical preconditions (SDD artifacts and working branch), builds a **structured briefing** with the key context already extracted, and delegates the implementation to the `refacil-implementer` sub-agent. The briefing prevents the sub-agent from rediscovering from scratch — it starts implementing, not exploring.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
+
+## Flow
+
+### Step 0: Verify SDD artifacts exist (blocking)
+
+Run `refacil-sdd-ai sdd list --json` to get the active changes.
+
+- **If there are no active changes**: inform to run `/refacil:propose` and **stop**.
+- **If there is a single active change**: use that `changeName`.
+- **If there are multiple active changes**: list the names and ask which one to implement. Do not invoke the sub-agent with ambiguous scope.
+
+With the selected `changeName`, run `refacil-sdd-ai sdd status <changeName> --json` and parse the JSON:
+
+```json
+{
+  "name": "...",
+  "artifacts": { "proposal": bool, "design": bool, "tasks": bool, "specs": bool },
+  "tasks": { "total": N, "done": N, "pending": N },
+  "reviewPassed": bool,
+  "ready": { "forApply": bool, "forArchive": bool }
+}
+```
+
+Validations:
+- If `artifacts.proposal` is `false` or `artifacts.tasks` is `false` or `artifacts.specs` is `false`:
+  ```
+  The change at refacil-sdd/changes/[name]/ is incomplete.
+  Missing: [list of artifacts with false]
+  Run: /refacil:propose to complete the artifacts before implementing.
+  ```
+  **Stop.**
+- If `ready.forApply` is `false` for the same reason: same message above.
+
+Note: `specs` is `true` if `specs.md` exists in the root **OR** at least one `.md` under the change's `specs/` folder.
+
+**IMPORTANT**: This command NEVER generates SDD artifacts. If they do not exist, the user must use `/refacil:propose`.
+
+### Step 1: Validate working branch (blocking — before delegating)
+
+Run `git branch --show-current` to get the current branch.
+
+Apply the **Protected branch policy and branch creation** defined in `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
+
+- **If the current branch is protected**: execute the full branch creation protocol **before continuing**. Do not delegate to the sub-agent until on a working branch.
+- For `refacil:apply`, the suggested branch prefix is `feature/`.
+- If the current branch is already a working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continue without interruption.
+- If the user does not approve the branch creation/change, **stop**. Do not continue with implementation.
+
+### Step 1.5: Build structured briefing (reduces sub-agent tool calls)
+
+Before invoking the sub-agent, extract the key context by reading the artifacts. This prevents the sub-agent from rediscovering them from scratch.
+
+1. **Objective** — read the first section of `refacil-sdd/changes/<changeName>/proposal.md`. Extract the objective in 1-2 sentences.
+2. **File scope** — read `refacil-sdd/changes/<changeName>/design.md`. Extract:
+   - List of files to **create** (full paths)
+   - List of files to **modify** (full paths)
+3. **Tasks** — read `refacil-sdd/changes/<changeName>/tasks.md`. Extract the full numbered list.
+4. **Test command** — read `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3. Extract the exact command.
+5. **Architecture context** — read `.agents/stack.md` if it exists; if not, `.agents/architecture.md`; if neither exists, read only the first 60 lines of `AGENTS.md`. **Do not read the entire `.agents/` folder**.
+
+Build the BRIEFING block that you will include literally in the delegation prompt:
+
+```
+BRIEFING:
+changeName: <name>
+objective: <objective in 1-2 sentences from the proposal>
+scope:
+  create: [path/new-file-1.ts, path/new-file-2.ts, ...]
+  modify: [path/existing-1.ts, path/existing-2.ts, ...]
+  doNotTouch: [refacil-sdd/, .claude/, .cursor/, AGENTS.md, package-lock.json]
+tasks:
+  1. <task 1>
+  2. <task 2>
+  ...
+testCommand: <exact command>
+architectureContext: |
+  <extract from stack.md or first lines of AGENTS.md>
+specsNote: <"specs.md" | "specs/**/*.md" | "both — report contradictions in issues">
+```
+
+### Step 2: Delegate to the refacil-implementer sub-agent
+
+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.
+
+The sub-agent will use the briefing as the primary guide and will only read the files in `scope.modify` to understand existing interfaces — it will not re-read the already-extracted artifacts.
+
+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.
+
+After the report add:
+
+```
+The next step is to generate/adjust unit tests.
+Do you want me to continue with /refacil:test?
+(The flow then continues with /refacil:verify)
+```
+
+If the sub-agent returned `result: "PARTIAL"` or `"FAILED"`, present the `issues` to the user and ask for instructions before continuing.
+
+## Rules
+
+- NEVER generate SDD artifacts from this command — that is exclusively `/refacil:propose`'s responsibility.
+- Meet the preconditions of Step 0 (complete artifacts) and Step 1 (valid working branch) **before delegating**.
+- **Always build the briefing (Step 1.5) before delegating** — it is the key piece that reduces the sub-agent cost.
+- **Always delegate implementation to the sub-agent**. Do not replicate implementation logic or SDD artifact-apply logic here.
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately invoke the **Skill tool** with `skill: "refacil:test"`. Do not describe it in text or wait for the user to type `/refacil:test`. (See `METHODOLOGY-CONTRACT.md §5`.)