@ancleto/spec 0.6.37 → 0.7.0

package/README.md

@@ -333,7 +333,7 @@ Funciona en tres piezas que comparten el mismo archivo:
 | `recordRule` | Guarda una regla o restricción permanente. |
 | `recordDecision` | Registra el *por qué* de una decisión. |
 
-Cada entrada tiene un `scope`: `project` (default, entra en `<ProjectMemoryRules>`), `feature` o `task`. El orquestador inyecta los bloques `<ProjectMemoryRules>` y `<ProjectTopology>` en el system prompt de tu agente desde el día cero —incluso sin reglas previas— para que no repita errores ya resueltos.
+Cada entrada tiene un `scope`: `project` (default), `feature` o `task`. Solo las **reglas** activas con scope `project` entran en `<ProjectMemoryRules>`; las **decisiones** con scope `project` se recuperan reactivamente con `searchMemory` y no se inyectan de forma proactiva. El orquestador inyecta los bloques `<ProjectMemoryRules>` y `<ProjectTopology>` en el system prompt de tu agente desde el día cero —incluso sin reglas previas— para que no repita errores ya resueltos.
 
 > El mismo motor se puede consultar a mano desde la terminal: `ancleto memory context --scope project`. El archivo `.ancleto/working-context.md` que lee el orquestador se regenera solo en `init`, `install --project` y `upgrade`.
 

package/agents/orchestrator.md

@@ -94,7 +94,7 @@ For `STALE`, delegate `regenerate` to `@technical-seed-writer` only after explic
 - **MUST STOP** after `@spec-writer` and wait for explicit user approval
 - **MUST REPORT** subagent failures and wait for instructions
 - **MUST STOP** if `@tester` reports failed verification
-- **MUST STOP** if `@reviewer` reports critical issues
+- **MUST STOP** if `@reviewer` reports critical issues (including a `GUARANTEE NOT SUSTAINED` finding) and do not advance toward archive while it is present
 - **MUST DELEGATE** all implementation to appropriate subagents
 
 ## Active Change Check
@@ -268,7 +268,7 @@ If the runtime is read-only or plan-only:
 3. **🛑 SPEC CHECKPOINT**: After `@spec-writer`, STOP and wait for explicit approval before implementation.
 4. **Implementation**: Delegate to **`@coder`** only - no direct implementation. Include the complete Resolved Context Envelope.
 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.
+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. When the change declares effect guarantees, additionally include, as separate fields, the guarantee extracted from the proposal, the protected state, and the affected capability
 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. Check the seed freshness before closing: delegate the read-only state check to **`@technical-discovery`** and, when the state is `STALE` with `impact: material`, warn and offer regeneration via **`@technical-seed-writer`** with explicit user approval — never automatic; with `impact: minor`, continue the archive normally and note the drift in the summary. 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.
@@ -306,7 +306,7 @@ For each validation command in the tester result, including format check and lin
 
 A subagent return is a payload to distill, not a message to forward. Before the next stage:
 
-- Extract only the fields the next stage needs: `task-owned files`, Validation Ledger entries, flags (`SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`), verdicts, blockers, and card context when relevant.
+- Extract only the fields the next stage needs: `task-owned files`, Validation Ledger entries, flags (`SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`, `GUARANTEE NOT SUSTAINED`), verdicts, blockers, and card context when relevant.
 - Never copy a subagent's raw return — prose, logs, diffs, or command output — into the next delegation or the final report; pass distilled fields only.
 - The caps declared in each agent's output section bound its return. If a return exceeds them, summarize it and keep the detail only for the current stage; offer the full detail only if the user asks.
 - Evidence survives as fields, not as text: `file:line` for code, ledger entries for commands, flags for decisions.
@@ -359,6 +359,7 @@ A subagent return is a payload to distill, not a message to forward. Before the
 - Warnings
 - Suggestions
 - `SPEC UPDATE RECOMMENDED` flag for `direct-implementation` changes that modified documented behavior, when applicable
+- `GUARANTEE NOT SUSTAINED` flag when the proposal's guarantee does not hold under the real model (`aspec Change` mode only), naming the guarantee, the falsifying operation, and the protected state
 - A concrete, plausible lesson for the team memory that could save future investigation, including a command alternative, runtime constraint, verified workaround, or confirmed assumption — or explicitly none with the reason automatic storage is not recommended after reviewing warnings, suggestions, and validation results
 - Overall review verdict
 - Any missing or inconclusive command evidence that requires a focused `@tester` verification

package/agents/reviewer.md

@@ -62,10 +62,39 @@ If `@orchestrator` classified the task as `direct-test-only`, review against:
 
 Do not assume an aspec change exists for this mode. Do not raise `SPEC UPDATE RECOMMENDED` for test-only work.
 
+## Guarantee Verification Under the Real Model
+
+This section applies **only** in `aspec Change` mode. Do not run it for `direct-implementation` or `direct-test-only` work.
+
+### Mandate
+
+For a change that declares guarantees about the effects of operations on state, verify that the proposal's guarantee holds under the **real model**: the set of operations that can mutate the protected state, **including the operations the change does NOT introduce** (supersession of the same identity, operations in other modules, indirect effects). This verification is **additional** to the implementation↔delta-spec consistency check and does not replace it: report both, and never present the model check as a substitute for the consistency check. Conclude explicitly whether the guarantee holds under the real model.
+
+### Applicability signal: `S1 ∧ S2`
+
+Run the model analysis only when both hold:
+
+- **`S1` (claim text):** the proposal names an identifiable operation (function, command, MCP tool, or lifecycle step) and carries a universal or negative quantifier ("does not require", "never", "only", "always", "no change").
+- **`S2` (technical context):** that operation writes or acts by an identity **not bounded** to the shape of what is written (`memory_key`, path, row) on a store whose read-model is a filtered or ordered projection.
+
+`S1` alone over-fires and is **not** sufficient. Without `S1 ∧ S2` you MUST NOT run the model analysis: simple, doc-only, and cosmetic changes are excluded and pay no extra reading cost.
+
+### Reading beyond the diff
+
+When `S1 ∧ S2` holds, read the source of the operations that can mutate the protected state. This reading is **not limited** to the diff or to the `task-owned files`.
+
+### Output
+
+When the guarantee does not hold under the real model, emit the explicit flag `GUARANTEE NOT SUSTAINED` at severity `CRITICAL`. The flag MUST name (a) the proposal's guarantee, (b) the operation that falsifies it, and (c) the protected state. Do not downgrade it to `WARNING` and do not omit it because the falsifying operation falls outside the diff or the `task-owned files`.
+
+### Unresolvable context
+
+If the received context is not enough to resolve the write surface or the read-model, report the missing context to `@orchestrator` and do **not** conclude that the guarantee holds.
+
 ## Required Workflow
 
 1. Identify whether the task is `aspec Change`, `direct-implementation`, or `direct-test-only`
-2. Read only the minimum relevant approved inputs and changed implementation files
+2. Read only the minimum relevant approved inputs and changed implementation files. When the change signals a guarantee (`S1 ∧ S2`, `aspec Change` mode only), that minimum additionally includes the source of the operations that can mutate the protected state, even beyond the diff
 3. Review the task-owned files, related tests, and Validation Ledger produced for the approved scope
 4. Check for correctness issues, missing coverage, convention violations, and scope creep
 5. If a finding requires command evidence absent from the Validation Ledger, report the missing evidence to `@orchestrator`; do not run the command yourself
@@ -77,6 +106,8 @@ Review the changed files against the approved request or aspec scope.
 
 Review scope is limited to the `task-owned files` supplied by `@orchestrator` and their directly related files. Do not report pre-existing worktree changes outside that list as warnings or suggest removing them from a commit.
 
+This scope limit does not apply to a `GUARANTEE NOT SUSTAINED` finding: a guarantee can be falsified by an operation outside the `task-owned files` and outside the diff, and the finding is not discarded or downgraded for that reason. See "Guarantee Verification Under the Real Model".
+
 Focus on these questions:
 
 - are the modified files consistent with the approved behavior or implementation scope?
@@ -161,6 +192,7 @@ Return a short structured report with:
 - `WARNING` issues
 - `SUGGESTION` items
 - `SPEC UPDATE RECOMMENDED` flag when a `direct-implementation` change modified documented behavior
+- `GUARANTEE NOT SUSTAINED` flag when the proposal's guarantee does not hold under the real model (`aspec Change` mode only), naming the guarantee, the falsifying operation, and the protected state
 - `MEMORY CANDIDATE`: one lesson worth keeping in the team memory, or "none" with the reason automatic storage is not recommended
 - missing or inconclusive command evidence that requires focused verification by `@tester`, or "none"
 - overall review verdict
@@ -188,6 +220,10 @@ Use this format:
 
 - {affected spec file and what documented behavior changed, or "none"}
 
+### GUARANTEE NOT SUSTAINED
+
+- {the proposal's guarantee, the operation that falsifies it, and the protected state, or "none"}
+
 ### MEMORY CANDIDATE
 
 - {one concrete, self-contained lesson in Spanish that could save future investigation: a command or flag that fails and its alternative, a runtime/test/CI/browser/platform constraint, a verified workaround, a confirmed or refuted assumption, or a decision whose reason or consequence is not obvious. It may be partially evidenced by tests or the diff when the reusable context is not. Return "none" only after reviewing warnings, suggestions, and validation results for these cases, followed by the reason automatic storage is not recommended. `@memory-keeper` decides whether it is stored; you only propose it.}

package/package.json

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

package/src/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs'
-import { cp, mkdir, access, writeFile, readFile, readdir, rename } from 'node:fs/promises'
+import { cp, mkdir, access, writeFile, readFile, readdir } from 'node:fs/promises'
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline'
@@ -9,6 +9,7 @@ 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'
+import { writeWorkingContext } from '../core/memory/working-context.js'
 import { memoryDoctor } from '../core/memory/doctor.js'
 import { serveMemoryMcp } from '../core/memory/mcp-server.js'
 import { writeDiscoveryMap } from '../core/discovery.js'
@@ -775,6 +776,39 @@ async function scaffoldAspec(projectDir) {
   }
 }
 
+const LEGACY_OPENSPEC_DIR = 'openspec'
+const MIGRATION_MARKER = '.migrated-from-openspec'
+
+// "Contenido real" = al menos una entrada bajo changes/ o specs/. Un config.yaml
+// solo (o el scaffold vacio) no cuenta como real: no bloquea la migracion.
+async function hasRealContent(aspecDir) {
+  for (const sub of ['changes', 'specs']) {
+    try {
+      if ((await readdir(join(aspecDir, sub))).length > 0) return true
+    } catch {
+      // subcarpeta inexistente o ilegible: no aporta contenido real
+    }
+  }
+  return false
+}
+
+// Migra la carpeta legacy openspec/ a aspec/ por copia recursiva (no destructiva).
+// Unico dueno del invariante: la invocan init y upgrade antes del scaffold.
+async function migrateLegacyOpenspec(projectDir) {
+  const legacyDir = join(projectDir, LEGACY_OPENSPEC_DIR)
+  if (!(await exists(legacyDir))) return // sin legacy: no-op silencioso
+  const aspecDir = join(projectDir, CHANGES_ROOT)
+  const marker = join(aspecDir, MIGRATION_MARKER)
+  if (await exists(marker)) return // ya migrada: no-op silencioso
+  if (await hasRealContent(aspecDir)) {
+    console.warn('ancleto: aspec/ ya tiene contenido real — no se migro openspec/ (revisar manualmente; openspec/ se conserva)')
+    return
+  }
+  await cp(legacyDir, aspecDir, { recursive: true, force: false })
+  await writeFile(marker, '# Generado por ancleto: esta aspec/ ya fue migrada desde openspec/\n')
+  console.log('ancleto: contenido migrado de openspec/ a aspec/ (openspec/ se conserva como backup)')
+}
+
 function extractLockedBlocks(content) {
   const blocks = new Map()
   const re = /<!--\s*LOCKED:\s*([\w-]+)\s*-->([\s\S]*?)<!--\s*\/LOCKED:\s*\1\s*-->/g
@@ -982,14 +1016,7 @@ async function upgradeCmd(args) {
     console.error("Error: No se encontro .ancletorc. Ejecuta 'ancleto init' primero.")
     process.exit(1)
   }
-  const legacyChanges = join(projectDir, 'openspec')
-  const changesRoot = join(projectDir, CHANGES_ROOT)
-  if ((await exists(legacyChanges)) && !(await exists(changesRoot))) {
-    await rename(legacyChanges, changesRoot)
-    console.log('ancleto: changes migrados de openspec/ a aspec/')
-  } else if ((await exists(legacyChanges)) && (await exists(changesRoot))) {
-    console.warn('ancleto: existen openspec/ y aspec/ — no se migro nada (revisar manualmente)')
-  }
+  await migrateLegacyOpenspec(projectDir)
   const agent = await resolveAgent(args, rc.agent)
   await copyTemplates(projectDir)
   const agentSkillsDir = await installAgentSkills(projectDir, agent)
@@ -1083,6 +1110,7 @@ async function initProject(args) {
   if (tier) {
     await applyTier(join(projectDir, '.opencode', 'agents'), tier, tierModels(tier, TIERS, gratisModelChoice))
   }
+  await migrateLegacyOpenspec(projectDir)
   await scaffoldAspec(projectDir)
   await refreshWorkingContext(projectDir)
   await registerProject(projectDir, { agent, tier: tier || null })
@@ -1419,16 +1447,11 @@ async function refreshWorkingContext(projectDir, scope = 'project') {
   const dbPath = defaultMemoryDbPath(projectDir)
   if (!(await exists(dbPath))) return null
   const engine = createMemoryEngine(dbPath)
-  let block
   try {
-    block = engine.buildWorkingContext(scope)
+    return writeWorkingContext(engine, projectDir, scope)
   } finally {
     engine.close()
   }
-  const out = join(projectDir, '.ancleto', 'working-context.md')
-  await mkdir(dirname(out), { recursive: true })
-  await writeFile(out, block === null ? '' : block + '\n')
-  return block === null ? null : out
 }
 
 async function memoryContext(flags) {

package/src/core/memory/engine.js

@@ -130,8 +130,8 @@ function buildEngine(db) {
        WHERE memory_fts MATCH ? AND n.status = 'active'`
     const run = (match, loose) => {
       const sql = type
-        ? db.prepare(`${base} AND n.type = ? ORDER BY rank LIMIT ?`)
-        : db.prepare(`${base} ORDER BY rank LIMIT ?`)
+        ? db.prepare(`${base} AND n.type = ? ORDER BY rank, n.rowid LIMIT ?`)
+        : db.prepare(`${base} ORDER BY rank, n.rowid LIMIT ?`)
       // FTS5 no acepta parametros en ORDER BY rank; el prefijo '*' va dentro del MATCH.
       try {
         return type ? sql.all(match, type, lim) : sql.all(match, lim)

package/src/core/memory/mcp-server.js

@@ -1,5 +1,6 @@
 import { createMemoryEngine, defaultMemoryDbPath } from './engine.js'
 import { memoryTools, createMemoryToolHandlers } from './tools.js'
+import { resolveMemoryProjectRoot } from './working-context.js'
 
 const PROTOCOL_VERSION = '2024-11-05'
 const SERVER_INFO = { name: 'ancleto-memory', version: '1.0.0' }
@@ -7,11 +8,12 @@ const SERVER_INFO = { name: 'ancleto-memory', version: '1.0.0' }
 export function createMemoryServer({ dbPath = defaultMemoryDbPath() } = {}) {
   let engine = null
   let handlers = null
+  const projectRoot = resolveMemoryProjectRoot(dbPath)
 
   function toolkit() {
     if (!engine) {
       engine = createMemoryEngine(dbPath)
-      handlers = createMemoryToolHandlers(engine, { source: 'mcp:ancleto-memory' })
+      handlers = createMemoryToolHandlers(engine, { source: 'mcp:ancleto-memory', projectRoot })
     }
     return handlers
   }

package/src/core/memory/tools.js

@@ -1,11 +1,12 @@
 import { createMemoryEngine } from './engine.js'
+import { shouldRefreshWorkingContext, writeWorkingContext } from './working-context.js'
 
 const KEY_DESCRIPTION = 'Clave conceptual estable (ej. "api-error-format"). Reusala para actualizar: la nueva version supersede automaticamente la anterior.'
 
 const SCOPE_SCHEMA = {
   type: 'string',
   enum: ['project', 'feature', 'task'],
-  description: 'Ambito: project (default, entra en <ProjectMemoryRules>), feature o task para algo mas acotado.'
+  description: 'Ambito: project (default; las reglas con scope project entran en <ProjectMemoryRules>, las decisiones se recuperan reactivamente con searchMemory), feature o task para algo mas acotado.'
 }
 
 const SEARCH_SCHEMA = {
@@ -62,10 +63,23 @@ export const memoryTools = [
 ]
 
 export function createMemoryToolHandlers(engine, runtimeContext = {}) {
+  function record(args, type, defaultSource) {
+    const result = engine.recordNode({ ...args, type }, { ...runtimeContext, source: runtimeContext.source || defaultSource })
+    if (runtimeContext.projectRoot && shouldRefreshWorkingContext(result)) {
+      try {
+        writeWorkingContext(engine, runtimeContext.projectRoot)
+      } catch (err) {
+        // stderr: stdout es el canal JSON-RPC del server MCP.
+        console.warn(`ancleto: no se pudo refrescar el working-context: ${err.message}`)
+      }
+    }
+    return result
+  }
+
   return {
     searchMemory: (args) => engine.searchMemory(args),
-    recordRule: (args) => engine.recordNode({ ...args, type: 'rule' }, { ...runtimeContext, source: runtimeContext.source || 'tool:recordRule' }),
-    recordDecision: (args) => engine.recordNode({ ...args, type: 'decision' }, { ...runtimeContext, source: runtimeContext.source || 'tool:recordDecision' })
+    recordRule: (args) => record(args, 'rule', 'tool:recordRule'),
+    recordDecision: (args) => record(args, 'decision', 'tool:recordDecision')
   }
 }
 

package/src/core/memory/working-context.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+// Invariante "memoria activa -> working-context.md": render desde el engine vivo
+// (una sola conexion, sin reabrir la DB) y persistencia del artefacto derivado.
+
+export function workingContextPath(projectRoot) {
+  return join(projectRoot, '.ancleto', 'working-context.md')
+}
+
+// Trigger del refresh sobre el resultado completo de `recordNode` `{ node, superseded }`:
+// (a) contribucion directa: el nodo entrante es rule + project (alimenta el bloque);
+// (b) efecto por supersesion: `memory_key` es identidad transversal (supersede sin filtrar
+//     type/scope), asi que cualquier supersesion pudo retirar del bloque una rule de scope project.
+// El over-refresh (supersesion que no altera el bloque) es intencional: el engine solo expone
+// `{ node, superseded }` y el unico consumidor lee el archivo una vez por sesion.
+export function shouldRefreshWorkingContext(result) {
+  return !!result && ((result.node.type === 'rule' && result.node.scope === 'project') || result.superseded > 0)
+}
+
+// Deriva la raiz del proyecto desde la ubicacion de la DB (no desde el cwd del proceso).
+// Prioriza el primer ancestro con `.ancletorc`; si no hay, usa el candidato derivado de
+// `dbPath` mientras exista el layout `.ancleto/`; si no, no hay raiz (refresh best-effort).
+export function resolveMemoryProjectRoot(dbPath) {
+  if (!dbPath) return null
+  const candidate = dirname(dirname(dbPath))
+  for (let dir = candidate; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, '.ancletorc'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+  }
+  if (existsSync(join(candidate, '.ancleto'))) return candidate
+  return null
+}
+
+// Render desde el engine vivo con la raiz explicita (topologia + salida) y escritura
+// sincrona del archivo: paridad con `block + '\n'` y `''` cuando el bloque es null.
+// Retorna el path escrito o null si no hay bloque/raiz.
+export function writeWorkingContext(engine, projectRoot, scope = 'project') {
+  if (!projectRoot) return null
+  const block = engine.buildWorkingContext(scope, undefined, projectRoot)
+  const out = workingContextPath(projectRoot)
+  mkdirSync(dirname(out), { recursive: true })
+  writeFileSync(out, block === null ? '' : block + '\n')
+  return block === null ? null : out
+}