@ancleto/spec 0.6.25 → 0.6.27

package/README.md

@@ -23,6 +23,7 @@
 - [Características principales](#características-principales)
 - [Requisitos](#requisitos)
 - [Instalación](#instalación)
+- [Guía de .gitignore](#guía-de-gitignore)
 - [Configuración y tiers de costo](#configuración-y-tiers-de-costo)
 - [Uso rápido](#uso-rápido)
 - [Referencia de comandos CLI](#referencia-de-comandos-cli)
@@ -121,6 +122,20 @@ Cómo bajarlo:
 
 ---
 
+## Guía de .gitignore
+
+El framework **no gestiona tu `.gitignore`**: es una decisión del proyecto. Como referencia, esta es la combinación que funciona bien con Ancleto:
+
+| Ruta | Recomendación | Por qué |
+|---|---|---|
+| `aspec/` | **Versionar** | Es la fuente-de-verdad: specs y el historial de changes archivados. Si se ignora, el equipo pierde el por qué de las decisiones y los agentes no tienen contexto estable. |
+| `.ancleto/` | **Ignorar** | Base SQLite local (memoria del repo y working-context). Es de tu máquina; cada integrante la regenera. |
+| `.ancletorc` | **Decisión del equipo** | Versionarlo alinea la configuración del proyecto (agente, tier, discovery). Ignoralo si cada integrante lo personaliza. |
+
+> Error común: gitignorear `aspec/` junto con `.ancleto/`. La memoria local es descartable; la fuente-de-verdad, no.
+
+---
+
 ## Configuración y tiers de costo
 
 En la primera ejecución, un **wizard interactivo** te guía por los pasos de configuración (agente/IDE y nivel de gasto). También podés pasarlos por flags:
@@ -186,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/orchestrator.md

@@ -259,7 +259,7 @@ If the runtime is read-only or plan-only:
 5. **Testing**: Delegate to **`@tester`** to create or update unit tests and perform final validation against the approved scope, including a non-writing format check and one lint pass after all edits. Include the complete Resolved Context Envelope, the coder's task-owned files, and its reported risks. `@tester` returns the final union of task-owned files and the Validation Ledger. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`.
 6. **Review**: Delegate to **`@reviewer`** when an independent correctness or scope review is appropriate. Include the complete Resolved Context Envelope, the tester's final task-owned file union, and the full Validation Ledger.
 7. **🛑 FINAL ARCHIVE CHECKPOINT**: If implementation, validation, and any required review are complete with no blocking issues, stop and explicitly ask the user whether to keep iterating on the same change or finalize and archive it
-8. **Finalization / Archive**: Before archiving, verify the delta specs reflect the final implementation — if iteration changed behavior or scope, re-delegate to **`@spec-writer`** to update the delta specs first, so the merge to source-of-truth is accurate. Then delegate to **`@documenter`** only after explicit user approval to archive
+8. **Finalization / Archive**: Before archiving, verify the delta specs reflect the final implementation — if iteration changed behavior or scope, re-delegate to **`@spec-writer`** to update the delta specs first, so the merge to source-of-truth is accurate. Check the seed freshness before closing: delegate the read-only state check to **`@technical-discovery`** and, when the state is `STALE`, warn and offer regeneration via **`@technical-seed-writer`** with explicit user approval — never automatic; if the user declines, continue the archive normally. This closure check protects future sessions from a silently aging seed. Then delegate to **`@documenter`** only after explicit user approval to archive
 9. **Memory Record**: After a successful archive, delegate to **`@memory-keeper`** in Automatic Record mode when a concrete, plausible candidate exists, with the factual completed-work summary and validation evidence supporting it. If no candidate exists, delegate Optional Draft with the factual completed-work summary, `no-automatic-candidate` classification, and the reason no candidate was identified. When Automatic Record returns `no-entry-warranted`, use its draft or delegate Optional Draft with that classification and reason if it could not provide one. Before asking, show the final work summary, classification, reason, and exact draft, then stop for explicit user approval. If no safe draft is available, report that outcome and finish without asking or storing. On approval, delegate User-Approved Record with the unchanged draft, the factual summary and validation evidence used to compose it, archived change name, and card context. On rejection, do not store.
 10. **Report**: Return final status or blocking findings to the user after automatic storage, an explicit decline, or User-Approved Record completes.
 

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.25",
+  "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.
@@ -42,14 +44,24 @@ Check for delta specs at `aspec/changes/<name>/specs/`; if none, proceed without
   - `## RENAMED Requirements` → rename using the `FROM:`/`TO:` pair.
 - Proceed to archive regardless of the choice.
 
-### 3. Perform the archive
+### 3. Check technical seed freshness
+
+If the `ancleto` CLI is available in this project, run `ancleto discovery --check` (read-only) and read its JSON `state`.
+
+- **`STALE`**: warn that the technical seed is out of date for the current code, and offer to regenerate it now (follow the `ancleto-technical-discovery` skill) or to continue archiving with the stale seed.
+- **Any other state**: continue without comment.
+- Never regenerate automatically — regenerate only with the user's explicit approval.
+- If the user declines, continue the archive normally and record the stale seed in the summary.
+- If the CLI is unavailable, skip this step.
+
+### 4. Perform the archive
 
 Create `aspec/changes/archive/` if absent. Target: `YYYY-MM-DD-<change-name>` (current date).
 
 - **Target exists**: fail, suggesting a rename or different date.
 - **Otherwise**: delete scaffold-only files (e.g., `aspec/changes/<name>/context.md` — never preserved), then move the change directory to `aspec/changes/archive/YYYY-MM-DD-<name>/`.
 
-### 4. Capture lessons into persistent memory
+### 5. Capture lessons into persistent memory
 
 Record what this change taught:
 
@@ -64,7 +76,7 @@ Record what this change taught:
 
 Record only durable lessons — decisions whose reasons aren't visible in the result, constraints, verified workarounds. Never workflow meta. If nothing meets the bar, record nothing and say so.
 
-### 5. Display summary
+### 6. Display summary
 
 ```
 ## Archive Complete
@@ -75,12 +87,15 @@ Record only durable lessons — decisions whose reasons aren't visible in the re
 **Memories recorded:** <list, or "None">
 ```
 
-If warnings applied (incomplete tasks, skipped sync), show an "Archive Complete (with warnings)" variant listing them.
+When the seed was `STALE`, add a `**Seed:**` line: `Regenerated` or `Stale — regeneration declined`.
+
+If warnings applied (incomplete tasks, skipped sync, stale seed), show an "Archive Complete (with warnings)" variant listing them.
 
 ## Guardrails
 
 - Always prompt for change selection if not provided.
 - Don't block archiving on warnings — inform and confirm.
+- Never regenerate the technical seed automatically: offer it, and continue the archive if the user declines.
 - If the target archive directory exists, fail instead of overwriting.
 - Delete scaffold-only files (`context.md`) before moving; never archive them.
 - `recordRule`/`recordDecision` accept only `memory_key`, `content`, `justification`, `scope`. Never send `source`, `confidence`, `status` or `id` — the runtime manages those.

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