@ancleto/spec 0.15.3 → 0.16.2

package/README.md

@@ -401,8 +401,14 @@ ancleto memory list [--type rule|decision] [--scope project|feature|task] [--all
                           # Lista los nodos de memoria (read-only: no toca la base)
 
 ancleto memory doctor [--rebuild]
-                          # Diagnostica la base de memoria, reconstruye el índice FTS5 y
-                          # fusiona el WAL en el .db (deja la base segura para copiar)
+                          # Diagnostica la base de memoria (read-only por defecto);
+                          # --rebuild es el único camino que escribe y reconstruye el índice FTS5
+
+ancleto memory snapshot --out <archivo.db> [--force] [--json]
+                          # Copia consistente de la base vía VACUUM INTO
+
+ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]
+                          # Fusiona nodos fuente en el target y supersede los sources
 
 ancleto mcp               # Servidor MCP de memoria propia (stdio): lo consume tu IDE
 
@@ -422,7 +428,7 @@ Funciona en tres piezas que comparten el mismo archivo:
 |---|---|
 | **Almacenamiento** | Reglas y decisiones con supersesión atómica por `memory_key` (una sola activa por clave). |
 | **Tools del LLM** (`ancleto mcp`) | Servidor MCP local, sin dependencias, que expone tres herramientas a tu IDE. |
-| **CLI** | `ancleto memory context` materializa el bloque `<ProjectMemoryRules>`, `ancleto memory list` permite inspeccionar los nodos sin escribir, y `ancleto memory doctor` verifica integridad, reconstruye el índice FTS5 y fusiona el WAL. |
+| **CLI** | `ancleto memory context` materializa el bloque `<ProjectMemoryRules>`, `ancleto memory list` permite inspeccionar los nodos sin escribir, y `ancleto memory doctor` verifica integridad (read-only por defecto; `--rebuild` reconstruye el índice FTS5). |
 
 | Herramienta | Función |
 |---|---|

package/agents/orchestrator.md

@@ -79,7 +79,7 @@ For `STALE`, delegate `regenerate` to `@technical-seed-writer` only after explic
 - **NEVER** execute `ancleto discovery --check`; delegate repository orientation to `@technical-discovery`
 - **NEVER** use `bash` for code implementation
 - **NEVER** create/modify implementation files
-- **NEVER** skip the User Checkpoint after `@spec-writer` when spec generation was required
+- **NEVER** skip the contract checkpoint after `@spec-writer` when spec generation was required
 - **NEVER** implement code directly - only delegate to @coder
 - **NEVER** auto-iterate between subagents without explicit user approval
 - **NEVER** continue to the next stage if a subagent reports blocking issues, ambiguity, or incomplete output
@@ -90,7 +90,7 @@ For `STALE`, delegate `regenerate` to `@technical-seed-writer` only after explic
 
 - **MUST STOP** and ask the user for clarification only when one concise question is still needed to classify safely
 - **MUST STOP** before implementation if the runtime indicates plan mode, read-only mode, or another no-write restriction
-- **MUST STOP** after `@spec-writer` and wait for explicit user approval
+- **MUST STOP** after `@spec-writer` and wait for explicit approval of the change contract
 - **MUST REPORT** subagent failures and wait for instructions
 - **MUST STOP** if `@tester` reports failed verification
 - **MUST STOP** if `@reviewer` reports critical issues (including a `GUARANTEE NOT SUSTAINED` finding) and do not advance toward archive while it is present
@@ -298,11 +298,27 @@ Ask at most one concise clarification question focused on the dominant ambiguity
 
 Before any write-capable stage, apply the **Runtime Safety** rule declared once in Enforcement Rules: if the runtime is plan-only or read-only, stop after analysis, clarification, or spec/planning work, delegate no write-capable stage, and report that implementation cannot continue until write-capable execution is available.
 
+### Contract Checkpoint
+
+After `@spec-writer` generates the artifacts of a change that required specification, STOP and present the **contract of the change**, not its documents. The presentation must fit in less than one screen and contain, in this order:
+
+- **Intention** — what the change does and why, in one or two lines
+- **Scope** — what is in, and what is explicitly out
+- **Requirement** — the new one, or the existing `spec:<capability>#<requirement>` cited as conformity
+- **Risks** — the ones that could change the decision, each with its mitigation
+- **Architecture decision** — only when the change takes one; state that none applies otherwise
+- **Planned validation** — only the commands the project declares
+- **Authorized paths** — the file set the implementation and its commit may touch
+
+Then wait for explicit approval. That approval authorizes implementation only: it does not authorize archive and it does not authorize merge, which stay as separate stops. Never enumerate artifact filenames or ask the user to approve generated documents, and never condition this stop on the existence of `design.md`.
+
+If scope, risk, or the architecture decision changes after approval, present the contract as an amendment and wait for a new explicit approval before continuing. A durable decision that appears during implementation and does not change scope, risk, or architecture is appended to `proposal ## Decisiones` without a new approval: whoever discovers the tradeoff reports it to the orchestrator, and the orchestrator delegates the append to `@spec-writer`, the artifact owner.
+
 ### Path A: Spec-Required Changes
 
 1. **Conditional Memory Recall**: Apply the Team Memory Recall rules. Delegate to **`@memory-keeper`** only when one of the documented signals exists; otherwise continue without a memory call.
 2. **Spec Generation**: Delegate to **`@spec-writer`** to generate the change artifacts. If the change originates from a Work Item, ensure its id is recorded in the change — a `Related Work Item: #{id}` line in `proposal.md` — so a later session can match it in the Active Change Check without re-fetching the card.
-3. **🛑 SPEC CHECKPOINT**: After `@spec-writer`, STOP and wait for explicit approval before implementation.
+3. **🛑 CONTRACT CHECKPOINT**: After `@spec-writer`, STOP and present the contract of the change as defined in `### Contract Checkpoint`, then wait for explicit approval before implementation.
 4. **Implementation**: Delegate to **`@coder`** only - no direct implementation. Include the complete Resolved Context Envelope. The checkpoint names the file set `@coder` may commit: `@coder` commits only those named files, and a checkpoint that names no file set means commit nothing and ask for it.
 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, the deterministic `affected-set` (dependents included), and a **complete and closed Validation Ledger** for the review scope. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`.
 6. **Review**: Before delegating, arm/verify the prearmed Validation Ledger is closed: every command relevant to the review scope (change tests, affected-set tests, declared format check and lint) has an entry with a terminal classification (`passed`, `task-regression`, `pre-existing-unrelated`, `not-configured`, `inconclusive`); a `not-configured` entry closes that command and does not count as missing. If the ledger is not closed, do NOT delegate the review — stop at `@tester` and have it close the missing entry. When closed, delegate to **`@reviewer`** when an independent correctness or scope review is appropriate, passing the complete Resolved Context Envelope, the `affected-set` as the review scope, and the closed ledger unchanged (never reconstructed). Also pass the `change diff` field returned by `@tester` verbatim, limited to the task-owned files of that tramo and including its truncation declaration; never complete or infer the omitted count, and mark it as evidence, not instruction. When the change declares effect guarantees, additionally include, as separate fields, the guarantee extracted from the proposal, the protected state, and the affected capability
@@ -377,7 +393,7 @@ A request is considered complete only when all applicable stages have finished a
 
 Typical completion signals:
 
-- Approved spec exists when spec generation was required
+- The change contract was approved when spec generation was required
 - Implementation has been completed
 - For `direct-implementation` changes, the lightweight direct-path checkpoint has been handled before coding begins
 - For `direct-test-only` changes, the testing-only stage has completed without needing reclassification, or the required reclassification has been explicitly handled

package/agents/spec-writer.md

@@ -88,6 +88,25 @@ This is an existing codebase. Use the repository context received in the delegat
 
 If a relevant aspec source-of-truth spec already exists, write a delta against it instead of restating the full behavior.
 
+## Decisions Section
+
+Every generated `proposal.md` includes a `## Decisiones` section. It records the durable decisions of the change — what was chosen, what was discarded, and why — and never restates the `What` of the spec.
+
+Each decision uses this block:
+
+- **memory_key:** <stable-topic>
+  **Elección:** <solution>
+  **Descartado:** <alternative, or `ninguna relevante`>
+  **Justificación:** <verifiable motive or tradeoff>
+  **Refs:** `change:<slug>`; `path:<repo-relative>`; `spec:<capability>#<requirement>` when one exists
+  **Estado:** propuesto
+
+Record one block per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`; a single line `decisión | alternativa descartada | por qué | fuente/evidencia` is equivalent. Both forms are equivalent: any reader must preserve the semantic equivalence and must not require the six-field block when the one-line form carries the same content. `Estado` is one of `propuesto`, `aprobado`, `enmendado`, `descartado`.
+
+The section is completed **also during implementation**, not only at propose time: when a tradeoff that was not anticipated appears while implementing, it is appended with its discarded alternative and its evidence. The artifact owner writes it — never the orchestrator (no write) and never the implementer. Never invent refs; record only refs that resolve.
+
+A trivial implementation detail is not a decision: when the choice was obvious or had no discarded alternative worth recording, it is not written in this section.
+
 ## Output Expectations
 
 After writing the artifacts, respond with a short structured summary including:

package/package.json

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

package/skills/ancleto-continue/SKILL.md

@@ -42,7 +42,7 @@ Read every present artifact — they constrain what you write. If `context.md` e
 
 Draft the missing artifact using the same templates as `ancleto-propose`:
 
-- **proposal.md** (first): problem statement, proposed change, scope, risks. With Work Item context, use its title/description as the problem statement, acceptance criteria as the requirements basis, and include `## Related Work Item`: `**#{id}** — {title} ({type}) · Project: {project}`.
+- **proposal.md** (first): problem statement, proposed change, scope, risks, and `## Decisiones` — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the single-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; reuse the shape defined in the Decisions section of `@spec-writer`. With Work Item context, use its title/description as the problem statement, acceptance criteria as the requirements basis, and include `## Related Work Item`: `**#{id}** — {title} ({type}) · Project: {project}`.
 - **specs/\<capability\>/spec.md**: one spec file per capability touched, with `## ADDED Requirements` / `#### Scenario:` blocks in WHEN/THEN form.
 - **design.md**: approach, architecture, validation.
 - **tasks.md**: phased `- [ ]` checklist.

package/skills/ancleto-ff/SKILL.md

@@ -45,7 +45,7 @@ Create `aspec/changes/<name>/` directly.
 
 Write each file directly, reading completed ones first:
 
-1. **`proposal.md`** — problem, proposed change, scope, risks. With Work Item context, use its title/description as the problem statement, acceptance criteria as the requirements basis, and include `## Related Work Item`: `**#{id}** — {title} ({type}) · Project: {project}`.
+1. **`proposal.md`** — problem, proposed change, scope, risks, and `## Decisiones` — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the single-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; the full shape lives in the Decisions section of `@spec-writer`. With Work Item context, use its title/description as the problem statement, acceptance criteria as the requirements basis, and include `## Related Work Item`: `**#{id}** — {title} ({type}) · Project: {project}`.
 2. **`specs/<capability>/spec.md`** — one file per capability touched, with `## ADDED Requirements` / `#### Scenario:` blocks in WHEN/THEN form. Skip only when the change specifies no behavior, and say why.
 3. **`design.md`** — approach, architecture, validation.
 4. **`tasks.md`** — phased `- [ ]` checklist of small, independently verifiable tasks.

package/skills/ancleto-new/SKILL.md

@@ -56,7 +56,7 @@ Report: "Change `<name>` created at `aspec/changes/<name>/`. 0/4 artifacts compl
 
 ### 5. Show the template for the first artifact
 
-Present the `proposal.md` template: `# Proposal: <title>`, then `## Problem`, `## Proposed change`, `## Scope` (In/Out), `## Risks` (`<risk>: <mitigation>`).
+Present the `proposal.md` template: `# Proposal: <title>`, then `## Problem`, `## Proposed change`, `## Scope` (In/Out), `## Risks` (`<risk>: <mitigation>`), and `## Decisiones` — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the one-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; the shape is owned by the Decisions section of `@spec-writer`.
 
 ### 6. STOP and wait for user direction
 

package/skills/ancleto-onboard/SKILL.md

@@ -69,7 +69,7 @@ Demo explore mode: read involved files, sketch diagrams. **PAUSE** for acknowled
 ## Phase 5: Proposal
 
 **EXPLAIN:** the proposal captures **why** and **what**.
-**DO:** draft (Why / What Changes / Capabilities / Impact), show it, **PAUSE** for approval, write `aspec/changes/<name>/proposal.md`.
+**DO:** draft (Why / What Changes / Capabilities / Impact), show it, **PAUSE** for approval, write `aspec/changes/<name>/proposal.md` including `## Decisiones` — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the single-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; follow the shape defined by `@spec-writer`.
 
 ## Phase 6: Specs
 

package/skills/ancleto-propose/SKILL.md

@@ -42,7 +42,7 @@ Create `aspec/changes/<name>/` if missing.
 
 Write each directly, reading each completed one before drafting the next.
 
-**4a. `proposal.md`** — what & why: `# Proposal: <title>`, then `## Problem`, `## Proposed change`, `## Scope` (In/Out of scope), `## Risks` (`<risk>: <mitigation>`).
+**4a. `proposal.md`** — what & why: `# Proposal: <title>`, then `## Problem`, `## Proposed change`, `## Scope` (In/Out of scope), `## Risks` (`<risk>: <mitigation>`), and `## Decisiones` — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the one-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; the full shape is defined in the Decisions section of the `@spec-writer` contract. The section is completed also during implementation when a tradeoff appears.
 
 **4b. `design.md`** — how: `# Design: <title>`, then `## Approach`, `## Architecture`, `## Validation`.
 

package/skills/ancleto-upgrade/references/templates.md

@@ -2,6 +2,8 @@
 
 ## proposal.md
 
+The emitted proposal includes a `## Decisiones` section — one entry per durable decision with `memory_key`, `Elección`, `Descartado`, `Justificación`, `Refs` and `Estado`, or the single-line form `decisión | alternativa descartada | por qué | fuente/evidencia`; the full shape is defined by the Decisions section of `@spec-writer`.
+
 ```markdown
 # Proposal: Migration to {LIBRARY} v{TARGET_VERSION}
 

package/src/cli/index.js

@@ -9,8 +9,9 @@ import { join, dirname, resolve, basename, relative, isAbsolute } from 'node:pat
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, createReadonlyMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
+import { snapshotDatabase } from '../core/memory/snapshot.js'
 import { adaptFrontmatter, parseFrontmatter } from '../core/adapters/frontmatter.js'
-import { writeWorkingContext, writeWorkingContextBlock, renderWorkingContextBlock, resolveMemoryProjectRoot, checkWorkingContextFreshness, refreshWorkingContextOnWrite } from '../core/memory/working-context.js'
+import { writeWorkingContext, writeWorkingContextBlock, workingContextPath, renderWorkingContextBlock, resolveMemoryProjectRoot, checkWorkingContextFreshness, refreshWorkingContextOnWrite } from '../core/memory/working-context.js'
 import { materializeMachineEnv, checkMachineEnvTracked } from '../core/machine-env.js'
 import { memoryDoctor } from '../core/memory/doctor.js'
 import { serveMemoryMcp } from '../core/memory/mcp-server.js'
@@ -91,6 +92,10 @@ ancleto memory doctor [--rebuild] Diagnostica .ancleto/memory.db (integridad, FT
   ancleto memory export [--out <archivo>]  Exporta nodos activos a JSON (stdout o archivo)
   ancleto memory import <archivo>          Importa nodos desde JSON (upsert por memory_key, idempotente)
   ancleto memory gc [--dry-run] [--days N] Purga superseded con antiguedad > N dias (default 30)
+  ancleto memory snapshot --out <archivo.db> [--force] [--json]
+                                   Copia consistente de la memoria (incluye historial; --force sobrescribe)
+  ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]
+                                   Supersede cada source activa hacia el target (sin crear nodos)
   ancleto mcp                           Servidor MCP de memoria propia (stdio) para tu IDE
                                         expone searchMemory, recordRule y recordDecision
   ancleto check                         Verifica integridad de archivos instalados vs manifiesto
@@ -2240,7 +2245,7 @@ async function memoryDoctorCmd(flags) {
   const { checks, healthy, rebuilt } = memoryDoctor(dbPath, { rebuild })
   if (rebuilt) console.log('ancleto: indice FTS5 reconstruido')
   for (const c of checks) {
-    console.log(`  ${c.ok ? '✔' : '✖'} ${c.name}: ${c.detail}`)
+    console.log(`  ${c.skipped ? '−' : c.ok ? '✔' : '✖'} ${c.name}: ${c.detail}`)
   }
   // Frescura del working-context: advisory, no afecta el exit code (que sigue midiendo
   // la integridad de la DB). Read-only: no reescribe el artefacto.
@@ -2393,6 +2398,103 @@ async function memoryGc(flags) {
   }
 }
 
+// `flagValue` devuelve el token siguiente sin mirar si es otro flag. En los
+// comandos con flags obligatorios, un valor vacio o que empieza con `--` cuenta
+// como flag faltante (sin cambiar el helper global que usan otros comandos).
+function requiredMemoryFlag(flags, flag) {
+  const value = flagValue(flags, flag)
+  return value && !value.startsWith('--') ? value : null
+}
+
+async function memorySnapshot(flags) {
+  const out = requiredMemoryFlag(flags, '--out')
+  if (!out) {
+    console.error('ancleto: uso: ancleto memory snapshot --out <archivo.db> [--force] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exitCode = 1
+    return
+  }
+  let result
+  try {
+    result = snapshotDatabase(dbPath, resolve(out), { overwrite: flags.includes('--force') })
+  } catch (err) {
+    console.error(`ancleto: no se pudo crear el snapshot: ${err.message}`)
+    process.exitCode = 1
+    return
+  }
+  if (flags.includes('--json')) {
+    console.log(JSON.stringify({ out: result.out, bytes: result.bytes }))
+  } else {
+    console.log(`ancleto: snapshot escrito en ${result.out} (${result.bytes} bytes)`)
+  }
+}
+
+async function memoryMerge(flags) {
+  const target = requiredMemoryFlag(flags, '--target')
+  const sourcesRaw = requiredMemoryFlag(flags, '--sources')
+  if (!target || !sourcesRaw) {
+    console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const sources = sourcesRaw.split(',').map((s) => s.trim()).filter(Boolean)
+  if (sources.length === 0) {
+    console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const dryRun = flags.includes('--dry-run')
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exitCode = 1
+    return
+  }
+  // `createMemoryEngine` aplica `PRAGMA journal_mode=WAL` y migraciones al abrir;
+  // un dry-run no debe escribir ni la base ni sus sidecars, asi que usa la
+  // conexion read-only (su `merge` solo acepta `dryRun: true`).
+  const engine = dryRun ? createReadonlyMemoryEngine(dbPath) : createMemoryEngine(dbPath)
+  try {
+    let result
+    try {
+      result = engine.merge({ target, sources, dryRun })
+    } catch (err) {
+      console.error(`ancleto: merge rechazado: ${err.message}`)
+      process.exitCode = 1
+      return
+    }
+    if (result.dryRun) {
+      if (flags.includes('--json')) console.log(JSON.stringify(result))
+      else console.log(`ancleto: merge --dry-run -> target ${result.target}; sources ${result.sources.join(', ')}; ${result.superseded} nodo(s) a superseder`)
+      return
+    }
+    // Mismo render que el refresh on-write de `import`; la raiz se deriva del
+    // directorio de la DB, no de process.cwd() (aisla fixtures en tmpdir).
+    const projectRoot = resolveMemoryProjectRoot(dbPath)
+    try {
+      refreshWorkingContextOnWrite(engine, projectRoot)
+    } catch (err) {
+      // El merge ya quedo commiteado en la base: no se revierte. Reportar exito
+      // sobre un bloque derivado desactualizado seria mentir; salir != 0 y decir
+      // exactamente que si se aplico, que quedo viejo y como regenerarlo.
+      const ctxPath = workingContextPath(projectRoot)
+      console.error(`ancleto: el merge SI se aplico en la base (${result.superseded} nodo(s) superseded hacia ${result.target}), pero el bloque derivado ${ctxPath} quedo desactualizado: ${err.message}`)
+      console.error(`ancleto: regenera el bloque con: ancleto memory context --out ${ctxPath}`)
+      process.exitCode = 1
+      return
+    }
+    if (flags.includes('--json')) console.log(JSON.stringify(result))
+    else console.log(`ancleto: merge OK -> ${result.superseded} nodo(s) superseded hacia ${result.target}`)
+  } finally {
+    engine.close()
+  }
+}
+
 async function memoryCmd(args) {
   const [sub, ...flags] = args
   if (sub === 'context') {
@@ -2419,6 +2521,14 @@ async function memoryCmd(args) {
     await memoryGc(flags)
     return
   }
+  if (sub === 'snapshot') {
+    await memorySnapshot(flags)
+    return
+  }
+  if (sub === 'merge') {
+    await memoryMerge(flags)
+    return
+  }
   console.error(`ancleto: subcomando de memory desconocido: ${sub || '(ninguno)'}`)
   console.error('ancleto: uso: ancleto memory context [--scope X] [--out file]')
   console.error('ancleto: uso: ancleto memory list [--type X] [--scope X] [--all] [--json]')
@@ -2426,6 +2536,8 @@ async function memoryCmd(args) {
   console.error('ancleto: uso: ancleto memory export [--out <archivo>]')
   console.error('ancleto: uso: ancleto memory import <archivo>')
   console.error('ancleto: uso: ancleto memory gc [--dry-run] [--days <n>]')
+  console.error('ancleto: uso: ancleto memory snapshot --out <archivo.db> [--force] [--json]')
+  console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
   process.exit(1)
 }
 

package/src/core/memory/doctor.js

@@ -1,15 +1,47 @@
+import { statSync } from 'node:fs'
 import { openDatabase, checkpointDatabase } from './database.js'
 
+// Estado observable del WAL sin ejecutar checkpoint ni ningun pragma mutante:
+// solo se mira el tamano del archivo `-wal` que ya existe en disco.
+function observeWal(dbPath) {
+  try {
+    return `-wal presente (${statSync(`${dbPath}-wal`).size} bytes)`
+  } catch {
+    return 'sin -wal'
+  }
+}
+
 export function memoryDoctor(dbPath, { rebuild = false } = {}) {
-  const db = openDatabase(dbPath, { migrate: false })
+  // Default estrictamente read-only: sin migraciones, sin pragmas mutantes y sin
+  // checkpoint. `--rebuild` es el unico camino que abre en escritura.
+  const db = openDatabase(dbPath, rebuild ? { migrate: false } : { migrate: false, readonly: true })
+  let rebuilt = false
   try {
     const checks = []
 
     const hasSchema = db.prepare(`SELECT count(*) AS n FROM sqlite_master WHERE name = 'memory_nodes'`).get().n > 0
     if (!hasSchema) {
-      return { checks: [{ name: 'Integridad DB', ok: false, detail: 'esquema no inicializado' }], healthy: false, rebuilt: false }
+      // Error path: los cuatro nombres se conservan y cada check no ejecutable
+      // se reporta como falla con su motivo (nunca se omite del array).
+      const detail = 'esquema no inicializado'
+      return {
+        checks: [
+          { name: 'Integridad DB', ok: false, detail },
+          { name: 'Indice FTS5', ok: false, detail: `no verificable: ${detail}` },
+          { name: 'Reglas activas (unicidad)', ok: false, detail: `no verificable: ${detail}` },
+          { name: 'Checkpoint WAL', ok: false, detail: `no verificable: ${detail}` }
+        ],
+        healthy: false,
+        rebuilt: false
+      }
     }
 
+    // La existencia del indice se verifica aparte del conteo: sin `memory_fts`
+    // la busqueda no funciona (esquema parcial/legacy) y no es un chequeo
+    // omitido. La tabla sombra `memory_fts_docsize` solo existe si FTS5 se creo
+    // con el default `columnsize=1`.
+    const hasFts = db.prepare(`SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'memory_fts'`).get().n > 0
+
     const quick = db.prepare('PRAGMA quick_check').get()
     const integrityOk = quick && quick.quick_check === 'ok'
     checks.push({
@@ -27,19 +59,45 @@ export function memoryDoctor(dbPath, { rebuild = false } = {}) {
       }
     }
 
-    let fts = runIntegrity()
-    let rebuilt = false
-    if (rebuild) {
-      db.exec(`INSERT INTO memory_fts(memory_fts) VALUES('rebuild')`)
-      rebuilt = true
-      const after = runIntegrity()
-      fts = { ok: after.ok, detail: after.ok ? 'indice reconstruido y consistente' : `reconstruccion sin exito: ${after.detail}` }
+    let fts
+    if (!hasFts) {
+      // Estado 1: el indice no existe. Aunque `memory_nodes` exista, la busqueda
+      // esta rota; se reporta como falla (nunca `skipped`) y baja `healthy`.
+      fts = { ok: false, detail: 'indice FTS5 ausente; la busqueda no funciona' }
+    } else if (rebuild) {
+      try {
+        db.exec(`INSERT INTO memory_fts(memory_fts) VALUES('rebuild')`)
+        rebuilt = true
+        const after = runIntegrity()
+        fts = { ok: after.ok, detail: after.ok ? 'indice reconstruido y consistente' : `reconstruccion sin exito: ${after.detail}` }
+      } catch (err) {
+        fts = { ok: false, detail: `reconstruccion fallo: ${err.message}` }
+      }
+    } else {
+      // Chequeo no mutante de alineacion. `count(*)` sobre `memory_fts` (external
+      // content) NO sirve: FTS5 lo resuelve contra `memory_nodes`, asi que un nodo
+      // sin indexar igual se cuenta. La tabla sombra `%_docsize` (default
+      // columnsize=1) tiene una fila por documento efectivamente indexado, y su
+      // conteo equivale a "filas indexadas". El integrity-check completo (INSERT
+      // de control) escribe y queda solo para `--rebuild`.
+      try {
+        const indexed = db.prepare('SELECT count(*) AS n FROM memory_fts_docsize').get().n
+        const total = db.prepare('SELECT count(*) AS n FROM memory_nodes').get().n
+        fts = indexed === total
+          ? { ok: true, detail: `${indexed} filas indexadas, coincide con memory_nodes (${total} nodos); integridad completa no verificable en read-only` }
+          : { ok: false, detail: `${indexed} filas indexadas vs ${total} nodos; indice desalineado, usar --rebuild` }
+      } catch (err) {
+        // No poder verificar no es una falla (D2): p. ej. un FTS5 creado con
+        // `columnsize=0` no materializa la tabla sombra `memory_fts_docsize`.
+        // El check se reporta omitido y no baja `healthy` ni el exit code.
+        fts = {
+          ok: true,
+          skipped: true,
+          detail: `omitido: alineacion de FTS no verificable (${err.message}); integridad completa no verificable en read-only`
+        }
+      }
     }
-    checks.push({
-      name: rebuilt ? 'Indice FTS5 (post-rebuild)' : 'Indice FTS5',
-      ok: fts.ok,
-      detail: fts.detail
-    })
+    checks.push({ name: 'Indice FTS5', ok: fts.ok, ...(fts.skipped ? { skipped: true } : {}), detail: fts.detail })
 
     const dups = db.prepare(`SELECT memory_key, COUNT(*) AS n FROM memory_nodes
       WHERE status = 'active' GROUP BY memory_key HAVING n > 1`).all()
@@ -49,13 +107,21 @@ export function memoryDoctor(dbPath, { rebuild = false } = {}) {
       detail: dups.length === 0 ? 'una sola activa por memory_key' : dups.map((d) => `${d.memory_key} x${d.n}`).join(', ')
     })
 
-    // Deja el WAL fusionado en el .db: una copia del archivo no pierde datos.
-    const checkpointed = checkpointDatabase(db)
-    checks.push({
-      name: 'Checkpoint WAL',
-      ok: checkpointed,
-      detail: checkpointed ? 'WAL fusionado en el .db (seguro para copiar)' : 'no se pudo checkpointear (DB en uso por otro proceso)'
-    })
+    if (rebuild) {
+      const checkpointed = checkpointDatabase(db)
+      checks.push({
+        name: 'Checkpoint WAL',
+        ok: checkpointed,
+        detail: checkpointed ? 'WAL fusionado en el .db (seguro para copiar)' : 'no se pudo checkpointear (DB en uso por otro proceso)'
+      })
+    } else {
+      checks.push({
+        name: 'Checkpoint WAL',
+        ok: true,
+        skipped: true,
+        detail: `omitido: no verificable en modo read-only; ${observeWal(dbPath)}`
+      })
+    }
 
     return { checks, healthy: checks.every((c) => c.ok), rebuilt }
   } finally {

package/src/core/memory/engine.js

@@ -91,13 +91,28 @@ export function createMemoryEngine(dbPath = defaultMemoryDbPath()) {
 // Apertura read-only: sin migraciones ni escrituras. Pensada para inspeccionar
 // la memoria sin tocar el WAL ni modificar archivos.
 export function createReadonlyMemoryEngine(dbPath = defaultMemoryDbPath()) {
-  return buildEngine(openDatabase(dbPath, { migrate: false, readonly: true }))
+  return buildReadonlyEngine(openDatabase(dbPath, { migrate: false, readonly: true }))
+}
+
+// Misma superficie que el engine de escritura. `merge` solo puede planificar:
+// una corrida real se rechaza antes de tocar la conexion read-only, y el plan
+// sale de la validacion compartida (`validateMerge`), identico al de escritura.
+function buildReadonlyEngine(db) {
+  const engine = buildEngine(db)
+  return {
+    ...engine,
+    merge({ target, sources, dryRun = false } = {}) {
+      if (!dryRun) throw new Error('merge: la conexion es read-only')
+      return engine.merge({ target, sources, dryRun: true })
+    }
+  }
 }
 
 function buildEngine(db) {
 
-  const findActive = db.prepare(`SELECT id FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const findActive = db.prepare(`SELECT id, type FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
   const findActiveRow = db.prepare(`SELECT id, created_at FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const findLatestStatus = db.prepare(`SELECT status FROM memory_nodes WHERE memory_key = ? ORDER BY rowid DESC LIMIT 1`)
   const countSuperseded = db.prepare(`SELECT COUNT(*) AS c FROM memory_nodes WHERE memory_key = ? AND status = 'superseded'`)
   const supersede = db.prepare(`UPDATE memory_nodes SET status = 'superseded', superseded_by = ? WHERE id = ? AND status = 'active'`)
   const insertNode = db.prepare(
@@ -372,9 +387,82 @@ function buildEngine(db) {
     return checkpointDatabase(db)
   }
 
+  // Validacion compartida por el engine de escritura y el read-only: deja el
+  // plan listo y falla cerrado (target activo, sources activas, sin repetidas y
+  // con `type` identico) antes de abrir cualquier transaccion.
+  function validateMerge({ target, sources } = {}) {
+    const targetKey = String(target || '').trim()
+    if (!targetKey) throw new Error('merge: target es obligatorio')
+    if (!Array.isArray(sources) || sources.length === 0) throw new Error('merge: sources debe ser una lista no vacia')
+
+    const sourceKeys = sources.map((s) => String(s || '').trim())
+    const seen = new Set()
+    for (const key of sourceKeys) {
+      if (!key) throw new Error('merge: memory_key vacia en sources')
+      if (seen.has(key)) throw new Error(`merge: source repetida: ${key}`)
+      seen.add(key)
+    }
+
+    const targetRow = findActive.get(targetKey)
+    if (!targetRow) throw new Error(`merge: target "${targetKey}" no es un nodo activo existente`)
+
+    const sourceIds = []
+    for (const key of sourceKeys) {
+      if (key === targetKey) throw new Error(`merge: source "${key}" es igual al target`)
+      const row = findActive.get(key)
+      if (!row) {
+        const latest = findLatestStatus.get(key)
+        if (latest) throw new Error(`merge: source "${key}" no esta activa (status: ${latest.status})`)
+        throw new Error(`merge: source "${key}" no existe`)
+      }
+      if (row.type !== targetRow.type) {
+        throw new Error(`merge: type incompatible entre target "${targetKey}" (${targetRow.type}) y source "${key}" (${row.type})`)
+      }
+      sourceIds.push(row.id)
+    }
+
+    return { targetKey, sourceKeys, sourceIds }
+  }
+
+  // Consolida duplicados supersediendo cada source activa hacia un target activo,
+  // sin insertar nodos ni aceptar contenido. Valida todo antes de escribir y usa
+  // una unica transaccion: cualquier violacion deja la base intacta. `dryRun` no
+  // abre transaccion ni escribe.
+  function merge({ target, sources, dryRun = false } = {}) {
+    const { targetKey, sourceKeys, sourceIds } = validateMerge({ target, sources })
+    const plan = { target: targetKey, sources: sourceKeys, superseded: sourceIds.length }
+    if (dryRun) return { dryRun: true, ...plan }
+
+    db.exec('BEGIN IMMEDIATE')
+    let superseded = 0
+    try {
+      // Revalidacion bajo lock: el target pudo quedar superseded entre la
+      // validacion previa y la transaccion, y las sources quedarian enlazadas a
+      // un nodo inactivo.
+      const lockedTarget = findActive.get(targetKey)
+      if (!lockedTarget) {
+        throw new Error(`merge: el target "${targetKey}" dejo de estar activo durante la transaccion`)
+      }
+      for (const id of sourceIds) {
+        const result = supersede.run(lockedTarget.id, id)
+        superseded += Number(result.changes || 0)
+      }
+      // Si una source dejo de estar activa entre la validacion y el UPDATE,
+      // `changes` es 0: se aborta y se revierte todo.
+      if (superseded !== sourceIds.length) {
+        throw new Error('merge: una source dejo de estar activa durante la transaccion')
+      }
+      db.exec('COMMIT')
+    } catch (err) {
+      db.exec('ROLLBACK')
+      throw err
+    }
+    return { dryRun: false, ...plan }
+  }
+
   function close() {
     db.close()
   }
 
-  return { buildWorkingContext, searchMemory, recordNode, listNodes, exportActive, importNodes, gcSuperseded, checkpoint, close }
+  return { buildWorkingContext, searchMemory, recordNode, listNodes, exportActive, importNodes, gcSuperseded, merge, checkpoint, close }
 }

package/src/core/memory/snapshot.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { basename, dirname, join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+// Copia consistente de la base de memoria con historial (incluye superseded y
+// superseded_by, a diferencia de `memory export`). No usa `openDatabase`: ese
+// helper fija `PRAGMA journal_mode=WAL` y mutaria la fuente. Se abre una conexion
+// directa read-only, sin pragmas ni migraciones: `VACUUM INTO` lee el estado
+// commiteado (incluido el WAL) sin escribir la fuente.
+// Identidad de archivo, no identidad de string: `path.resolve()` no normaliza
+// mayusculas en Windows ni resuelve symlinks/junctions. Para una ruta que todavia
+// no existe se resuelve el ancestro existente mas cercano y se recompone el resto.
+function realpathish(p) {
+  const abs = resolve(p)
+  if (existsSync(abs)) return realpathSync.native(abs)
+  const tail = []
+  let cur = abs
+  for (;;) {
+    const parent = dirname(cur)
+    if (parent === cur) return abs
+    if (existsSync(parent)) {
+      return join(realpathSync.native(parent), basename(cur), ...tail.reverse())
+    }
+    tail.push(basename(cur))
+    cur = parent
+  }
+}
+
+function sameFile(a, b) {
+  let ca = realpathish(a)
+  let cb = realpathish(b)
+  if (process.platform === 'win32') {
+    ca = ca.toLowerCase()
+    cb = cb.toLowerCase()
+  }
+  return ca === cb
+}
+
+function vacuumInto(sourcePath, targetPath) {
+  const db = new DatabaseSync(sourcePath, { readOnly: true })
+  try {
+    // `VACUUM INTO` acepta una expresion SQL: el destino viaja como parametro
+    // vinculado, sin interpolar la ruta en el texto de la sentencia.
+    db.prepare('VACUUM INTO ?').run(targetPath)
+  } catch (err) {
+    throw new Error(`snapshot: VACUUM INTO fallo sobre la fuente read-only: ${err.message}`)
+  } finally {
+    db.close()
+  }
+}
+
+function verifySnapshot(targetPath) {
+  const check = new DatabaseSync(targetPath, { readOnly: true })
+  try {
+    const row = check.prepare('PRAGMA quick_check').get()
+    if (!row || row.quick_check !== 'ok') {
+      throw new Error(`snapshot: la verificacion quick_check fallo para ${targetPath}`)
+    }
+  } finally {
+    check.close()
+  }
+}
+
+// Reemplaza el destino recien despues de tener una copia verificada en el
+// temporal (mismo directorio = mismo volumen). En Windows `rename` no reemplaza
+// un destino existente: se aparta el viejo a un backup, se mueve la copia nueva
+// y solo entonces se borra el backup. Si el movimiento final falla, se restaura
+// el backup: en ningun camino de error se pierden a la vez el destino previo y
+// la copia nueva.
+function replaceDestination(tempPath, targetPath) {
+  if (!existsSync(targetPath)) {
+    renameSync(tempPath, targetPath)
+    return
+  }
+  const backup = `${targetPath}.bak-${randomUUID()}`
+  renameSync(targetPath, backup)
+  try {
+    renameSync(tempPath, targetPath)
+  } catch (err) {
+    try {
+      renameSync(backup, targetPath)
+    } catch {
+      // restauracion best-effort: se propaga el error original
+    }
+    throw err
+  }
+  try {
+    rmSync(backup, { force: true })
+  } catch {
+    // el snapshot ya quedo en su lugar: un .bak remanente no invalida la copia
+  }
+}
+
+export function snapshotDatabase(dbPath, outPath, { overwrite = false } = {}) {
+  if (!dbPath || !outPath) throw new Error('snapshot: se requieren la base fuente y la ruta destino')
+  const source = resolve(dbPath)
+  const out = resolve(outPath)
+  if (sameFile(source, out)) {
+    throw new Error(`snapshot: el destino no puede ser la fuente (${out})`)
+  }
+  if (!existsSync(source)) {
+    throw new Error(`snapshot: no existe la base fuente (${source})`)
+  }
+  if (existsSync(out) && !overwrite) {
+    throw new Error(`snapshot: el destino ya existe (${out}); usar overwrite/--force para reemplazarlo`)
+  }
+
+  mkdirSync(dirname(out), { recursive: true })
+  const temp = join(dirname(out), `.${basename(out)}.${process.pid}-${randomUUID()}.tmp`)
+  try {
+    vacuumInto(source, temp)
+    verifySnapshot(temp)
+    replaceDestination(temp, out)
+    return { out, bytes: statSync(out).size }
+  } catch (err) {
+    // La limpieza del temporal nunca debe reemplazar el error original. SQLite
+    // puede haber creado sidecars para el archivo temporal: se borran los tres.
+    try {
+      for (const file of [temp, `${temp}-wal`, `${temp}-shm`]) rmSync(file, { force: true })
+    } catch {
+      // best effort: el temporal queda huerfano pero el error original se propaga
+    }
+    throw err
+  }
+}