@ancleto/spec 0.6.26 → 0.6.27

package/README.md

@@ -201,6 +201,9 @@ ancleto upgrade           # Re-aplica templates y skills respetando tus personal
 
 ancleto check             # Verifica la integridad de la instalación (faltantes / huérfanos)
 
+ancleto specs check [--change <nombre>] [--json]
+                          # Valida keywords canónicos en aspec/specs y en los deltas de un change
+
 ancleto doctor            # Diagnostica el entorno (Node, node:sqlite, opencode.json)
 
 ancleto memory context [--scope <project|feature|task>] [--out <archivo>]

package/agents/documenter.md

@@ -105,12 +105,13 @@ Do not treat archive as a blind file move.
    - `tasks.md`
    - `specs/` when the change includes delta specs
 3. Determine whether the change includes spec deltas that must be reflected in `aspec/specs/`
-4. If needed, update the relevant source-of-truth specs so they reflect the completed change
-5. If the change is not ready for archive, stop and report the inconsistency clearly
-6. If the change is ready, archive it to `aspec/changes/archive/{YYYY-MM-DD}-{change-name}/`
-7. Remove the original active change directory from `aspec/changes/{change-name}/` after a successful archive
-8. If any files or folders remain in the original active change directory, report them as cleanup issues instead of leaving silent residue
-9. Return a short structured summary of the finalization and archive result
+4. When deltas exist, run `ancleto specs check --change {change-name} --json` before merging. If a delta spec or its target source-of-truth spec is non-canonical (translated keywords), stop and report it instead of merging into it
+5. If needed, update the relevant source-of-truth specs so they reflect the completed change
+6. If the change is not ready for archive, stop and report the inconsistency clearly
+7. If the change is ready, archive it to `aspec/changes/archive/{YYYY-MM-DD}-{change-name}/`
+8. Remove the original active change directory from `aspec/changes/{change-name}/` after a successful archive
+9. If any files or folders remain in the original active change directory, report them as cleanup issues instead of leaving silent residue
+10. Return a short structured summary of the finalization and archive result
 
 ## Source-of-Truth Rules
 

package/agents/spec-writer.md

@@ -44,8 +44,9 @@ using the `ancleto-workflow` skill and the conventions of:
    - `design.md`
    - `tasks.md`
    - `specs/{capability}/spec.md` as needed
-6. When the delegation says the context was produced without a technical seed, declare that in the generated artifacts.
-7. Return a brief summary with generated paths, scope, and open questions or risks
+6. Before returning, verify every generated spec uses the canonical keywords (`### Requirement:`, `#### Scenario:`, `**WHEN**`/`**THEN**`, `SHALL`); fix any translated heading or keyword in place — never leave a spec with translated keywords.
+7. When the delegation says the context was produced without a technical seed, declare that in the generated artifacts.
+8. Return a brief summary with generated paths, scope, and open questions or risks
 
 ## Change Naming
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.6.26",
+  "version": "0.6.27",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/skills/ancleto-archive/SKILL.md

@@ -31,6 +31,8 @@ Read `aspec/changes/<name>/tasks.md` (when present); count `- [ ]` (incomplete)
 
 Check for delta specs at `aspec/changes/<name>/specs/`; if none, proceed without a sync prompt.
 
+**Canonical keywords first:** when delta specs exist and the CLI is available, run `ancleto specs check --change <name> --json`. If a delta spec or its target source-of-truth spec is non-canonical (translated keywords), warn that requirement blocks cannot be matched reliably and ask whether to normalize the affected spec first or archive without syncing that capability. Never merge into a non-canonical spec silently.
+
 **If delta specs exist:**
 
 - Diff each delta against its main spec at `aspec/specs/<capability>/spec.md`; show a combined summary of adds/modifications/removals/renames.

package/skills/ancleto-verify/SKILL.md

@@ -26,6 +26,12 @@ Read under `aspec/changes/<name>/`: `tasks.md` (required), plus `proposal.md`, `
 
 **Tasks:** parse checkboxes (`- [ ]` incomplete vs `- [x]` complete) and count. Each incomplete → CRITICAL: "Complete task: `<description>`" or "Mark as done if already implemented".
 
+**Canonical spec keywords:** run `ancleto specs check --change <name> --json` when the CLI is available. For every reported file:
+- Delta spec (`aspec/changes/<name>/specs/...`) → CRITICAL: "Non-canonical spec: `<file>` (missing: `<keywords>`)" + "Normalize `<file>` to the canonical English keywords before archiving".
+- Source-of-truth spec (`aspec/specs/...`) → WARNING with the same recommendation.
+
+A non-canonical spec cannot be matched for coverage or merged reliably, so report it before the checks below.
+
 **Spec coverage:** for each `### Requirement:` in `specs/`, search the codebase for related keywords. Unimplemented → CRITICAL: "Requirement not found: `<requirement name>`" + "Implement requirement: `<description>`".
 
 ### 3. Correctness

package/src/cli/index.js

@@ -4,7 +4,7 @@ import { cp, mkdir, access, writeFile, readFile, readdir, rename } from 'node:fs
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline'
-import { join, dirname, resolve, basename } from 'node:path'
+import { join, dirname, resolve, basename, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, createReadonlyMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
@@ -40,6 +40,9 @@ Uso:
   ancleto discovery --check           Estado del seed (READY/STALE/PARTIAL/MISSING)
   ancleto discovery [--compress] [--include G] [--ignore G] [--token-budget N]
                                    Empaca el repo con Repomix y guarda estado
+  ancleto specs check [--change <name>] [--json]
+                                   Valida keywords canonicos (### Requirement:, WHEN, THEN)
+                                   en aspec/specs y, con --change, en los deltas del change
   ancleto memory context [--scope X] [--out file]
                                    Imprime/escribe el bloque <ProjectMemoryRules> (reglas activas)
   ancleto memory list [--type X] [--scope X] [--all] [--json]
@@ -980,6 +983,77 @@ async function checkTierOrphan(cwd) {
   return warnings
 }
 
+// Un spec es canonico cuando usa los keywords literales en ingles. Detecta specs
+// traducidos (p. ej. "#### RF1:" + "**Dado**/**Cuando**/**Entonces**"), que rompen
+// la cobertura por keywords y el merge de deltas.
+function specIssues(content) {
+  const missing = []
+  if (!/^###\s+Requirement:/m.test(content)) missing.push('### Requirement:')
+  if (/^####\s+Scenario:/m.test(content)) {
+    if (!/\bWHEN\b/.test(content)) missing.push('WHEN')
+    if (!/\bTHEN\b/.test(content)) missing.push('THEN')
+  }
+  const unexpected = []
+  const re = /^####\s+(.+)$/gm
+  let m
+  while ((m = re.exec(content)) !== null) {
+    if (!/^Scenario\b/.test(m[1])) unexpected.push(`#### ${m[1]}`)
+  }
+  return { missing, unexpected }
+}
+
+async function collectSpecFiles(dir) {
+  const out = []
+  if (!(await exists(dir))) return out
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) out.push(...(await collectSpecFiles(p)))
+    else if (e.name === 'spec.md') out.push(p)
+  }
+  return out
+}
+
+async function specsCheckCommand(args) {
+  const cwd = process.cwd()
+  const asJson = args.includes('--json')
+  const ci = args.indexOf('--change')
+  const change = ci >= 0 ? args[ci + 1] : null
+  const files = await collectSpecFiles(join(cwd, CHANGES_ROOT, 'specs'))
+  if (change) {
+    const changeDir = join(cwd, CHANGES_ROOT, 'changes', change)
+    if (!(await exists(changeDir))) {
+      console.error(`ancleto: no existe el change "${change}" en ${CHANGES_ROOT}/changes/`)
+      process.exit(1)
+    }
+    files.push(...(await collectSpecFiles(join(changeDir, 'specs'))))
+  }
+  const findings = []
+  for (const f of files) {
+    const { missing, unexpected } = specIssues(await readFile(f, 'utf8'))
+    if (missing.length || unexpected.length) {
+      findings.push({ file: relative(cwd, f).replace(/\\/g, '/'), missing, unexpected })
+    }
+  }
+  const ok = findings.length === 0
+  if (asJson) {
+    console.log(JSON.stringify({ ok, scanned: files.length, nonCanonical: findings }, null, 2))
+  } else if (files.length === 0) {
+    console.log('ancleto: no hay specs para revisar')
+  } else {
+    for (const f of files) {
+      const rel = relative(cwd, f).replace(/\\/g, '/')
+      const found = findings.find((x) => x.file === rel)
+      if (found) {
+        console.log(`  ✖ ${rel} (revisar: ${[...found.missing, ...found.unexpected].join(', ')})`)
+      } else {
+        console.log(`  ✔ ${rel}`)
+      }
+    }
+    console.log(ok ? `ancleto: ${files.length} spec(s) canonicos` : `ancleto: ${findings.length} de ${files.length} spec(s) sin keywords canonicos`)
+  }
+  process.exit(ok ? 0 : 1)
+}
+
 async function doctorCommand() {
   let fatal = false
 
@@ -1045,6 +1119,9 @@ switch (cmd) {
   case 'check':
     await checkCommand()
     break
+  case 'specs':
+    await specsCheckCommand(rest)
+    break
   case 'doctor':
     await doctorCommand()
     break