@ancleto/spec 0.6.23 → 0.6.25

package/README.md

@@ -228,6 +228,8 @@ Cada entrada tiene un `scope`: `project` (default, entra en `<ProjectMemoryRules
 
 > 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`.
 
+**Dos memorias, sin mezcla.** La memoria **del repositorio** (esta, `.ancleto/memory.db`) guarda reglas y decisiones del proyecto y se comparte con el equipo. Si el runtime expone además una memoria **del agente** (por ejemplo engram, habilitable con `--with-engram`), esa guarda notas de sesión, no del repo. **Una entrada vive en una sola**: si un futuro agente del equipo debería encontrarla, va al repo.
+
 ---
 
 ## Comandos del ciclo SDD en tu IDE

package/agents/coder.md

@@ -151,6 +151,8 @@ After implementation, return a short structured summary including:
 - whether escalation was required due to broader-than-approved impact
 - blockers, conflicts, or escalations if any
 
+**Output cap**: summary max 12 lines. At most 5 risky edges or test scenarios; offer the rest on request. Reference code as `file:line` instead of pasting code or logs.
+
 ## Important
 
 - Do NOT add features not defined in the approved request or aspec change

package/agents/context-resolver.md

@@ -93,6 +93,8 @@ Return the card as structured context for the orchestrator:
 
 The command already replaces HTML markup with whitespace and unwraps long lines; if any markup survives, replace it with whitespace rather than dropping it.
 
+**Output cap**: 3 lines plus the card payload — the description and acceptance criteria are the only unbounded fields and must stay complete; no commentary, analysis, or implementation advice.
+
 ## Failure handling
 
 - If no work item reference was provided, report "no work item to resolve" and fetch nothing.

package/agents/documenter.md

@@ -147,6 +147,8 @@ After completing the finalization step, return a short structured summary includ
 - whether the original active change directory was fully removed (`Change Archive` mode)
 - any blockers or missing inputs
 
+**Output cap**: summary max 10 lines; spec, archive, and artifact lists as paths only — never restate spec content.
+
 ## Important
 
 - Do not invent additional documentation requirements

package/agents/memory-keeper.md

@@ -20,6 +20,8 @@ You are the single owner of the repository's memory (`.ancleto/memory.db`, SQLit
 
 The memory is shared across sessions: what you write, someone else recalls months later, in another change, without today's context. A wrong or noisy entry is worse than no entry, because it is retrieved as precedent.
 
+**Boundary:** the repository memory (yours) is distinct from any *agent/session* memory service the runtime may expose (e.g. engram). Repo rules and decisions live here, never duplicated there; transient, personal session notes belong to that other service, not here. When in doubt, it goes here — this is the one that outlives the repo and is shared with the team. The frontier is documented for projects in `AGENTS.md`.
+
 ## Rule vs Decision
 
 Classify every candidate BEFORE choosing the tool:
@@ -137,6 +139,8 @@ Whoever recalls this in six months has no session to attach it to, so it reads a
 - User-Approved Record: the tool used, `memory_key`, the exact approved `content` as stored, and whether it superseded a previous entry
 - Any failure of the memory engine, reported plainly so `@orchestrator` can continue without memory
 
+**Output cap**: max 6 lines; the stored entry is the only unbounded field — everything else is one line.
+
 ## Important
 
 - You never modify code, specs, or repository state.

package/agents/orchestrator.md

@@ -291,6 +291,17 @@ Before advancing to the next stage, verify that each subagent returned a usable
 
 For each validation command in the tester result, including format check and lint, preserve a Validation Ledger entry with: command, outcome (`passed`, `task-regression`, `pre-existing-unrelated`, or `inconclusive`), and related files when it failed. Pass it unchanged to `@reviewer`. A confirmed `pre-existing-unrelated` result is reported once in the final status as a non-blocking residual limitation; do not stop, re-run it, or request a correction unless a later relevant change invalidates that classification.
 
+### Handling subagent returns
+
+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.
+- 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.
+
+**Output cap**: the final report to the user max 15 lines — status, changed paths, validation result, blockers; never paste subagent returns, logs, or diffs.
+
 ### Expected output from `@context-resolver`
 
 - The resolved card: id, title, work item type, and project

package/agents/reviewer.md

@@ -165,6 +165,8 @@ Return a short structured report with:
 - missing or inconclusive command evidence that requires focused verification by `@tester`, or "none"
 - overall review verdict
 
+**Output cap**: at most 5 findings per severity (`CRITICAL`, `WARNING`, `SUGGESTION`); if more exist, keep the 5 highest-impact and state the count of the rest, offering detail on request. `Summary` max 5 lines. Cite `file:line`; never paste diffs or code.
+
 Use this format:
 
 ```md

package/agents/spec-writer.md

@@ -96,6 +96,8 @@ After writing the artifacts, respond with a short structured summary including:
 - short scope summary
 - open questions, assumptions, or risks
 
+**Output cap**: summary max 10 lines; at most 5 open questions, assumptions, or risks combined (offer the rest on request); paths only — never restate artifact content.
+
 ## Important
 
 - Prefer the smallest correct aspec change that captures the intended behavior

package/agents/technical-discovery.md

@@ -132,3 +132,5 @@ When you were delegated, do not address the developer as if they had called you:
   include the required `SEED_ACTION_REQUIRED` marker.
 - When mentioning credentials, name the variable, key, or file and **never** reproduce its value.
 - Be concise: orientation the caller can act on, not an inventory.
+
+**Output cap**: prose max 15 lines; required state or check reports are payload and stay complete; cite paths instead of pasting content.

package/agents/technical-seed-writer.md

@@ -49,8 +49,13 @@ action was explicitly requested, run `ancleto discovery --check` once and read i
    `config.outputDir`, including `units/_map.md`. Use the same pack for any optional dossier.
 4. Run `ancleto discovery --check` once to validate the written seed. This is state-only: do
    not generate another pack after it.
-5. Return the output directory, files created or updated, the single pack path, final state,
-   and any evidence limitations recorded in `unknowns.md`.
+5. Return the result as specified in `## Output`.
 
 If the pack fails, writing fails, or the final state is not usable, report the exact blocker;
 do not claim the seed was generated.
+
+## Output
+
+- The output directory, the files created or updated, the single pack path, the final state, and any evidence limitations recorded in `unknowns.md`.
+
+**Output cap**: max 8 lines — paths only; never paste file contents or the pack.

package/agents/tester.md

@@ -167,6 +167,8 @@ After validation, return a short structured summary including:
 - failed verification items, if any
 - untested gaps or assumptions, if any
 
+**Output cap**: Validation Ledger entries are one line each — never paste command output; collapse repeated `passed` runs of the same command into one line with a count; keep at most 15 lines, preserving every failure and every task-owned test result. Summary max 10 lines; offer full detail on request.
+
 ## Important
 
 - Prefer the smallest useful test change that validates the approved behavior

package/package.json

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

package/src/cli/index.js

@@ -352,15 +352,40 @@ function mergeLocked(source, local, filename) {
   let result = local
   for (const [name, sourceBlock] of blocks) {
     const replaced = replaceLockedBlock(result, name, sourceBlock)
-    if (replaced === null) {
+    if (replaced !== null) {
+      result = replaced
+      continue
+    }
+    // Si el nombre del bloque aparece igual en el archivo (p. ej. tag de cierre faltante),
+    // esta mal formado: se avisa y NO se toca, para no duplicar contenido.
+    const nameSeen = new RegExp(`<!--\\s*LOCKED:\\s*${escapeRe(name)}\\s*-->`).test(result)
+    if (nameSeen) {
       console.warn(`ancleto: no se pudo actualizar el bloque LOCKED "${name}" en ${filename} (tags ausentes o mal formados)`)
+      continue
+    }
+    // El bloque es nuevo (feature agregada al template): se inserta sin tocar el resto.
+    const anchor = findInsertAnchor(result, source, name)
+    if (anchor === null) {
+      console.warn(`ancleto: no se pudo insertar el bloque LOCKED "${name}" en ${filename}`)
     } else {
-      result = replaced
+      result = result.slice(0, anchor) + sourceBlock + '\n\n' + result.slice(anchor)
     }
   }
   return result
 }
 
+// Punto de insercion para un bloque LOCKED nuevo: justo antes del bloque LOCKED
+// que lo sigue en el template, o al final del archivo si es el ultimo.
+function findInsertAnchor(local, source, name) {
+  const order = [...extractLockedBlocks(source).keys()]
+  const nextInSource = order[order.indexOf(name) + 1]
+  if (nextInSource && extractLockedBlocks(local).has(nextInSource)) {
+    const at = local.search(new RegExp(`<!--\\s*LOCKED:\\s*${escapeRe(nextInSource)}\\s*-->`))
+    if (at >= 0) return at
+  }
+  return local.length
+}
+
 async function copyTemplates(projectDir) {
   const dest = join(projectDir, '.opencode')
   await copyAssets(dest)

package/templates/AGENTS.md

@@ -50,6 +50,22 @@ conflicto, prevalece el diseño vigente.
 - Si la memoria contradice el estado actual del código o los guardrails de este archivo,
   reportá la discrepancia en lugar de aplicarla a ciegas.
 
+<!-- LOCKED: memory-boundary -->
+### Frontera: memoria del repo vs memoria del agente
+
+Hay **dos memorias distintas** y no se mezclan:
+
+| Memoria | Qué guarda | Dónde vive | Herramientas |
+|---|---|---|---|
+| **Del repositorio** | Reglas y decisiones **del proyecto**: convenciones, contratos, por qué se eligió algo | `.ancleto/memory.db` (versionable con el equipo) | `searchMemory`, `recordRule`, `recordDecision` |
+| **Del agente** (si está habilitada) | Notas **de sesión/agente**: observaciones transitorias, contexto entre compactaciones | Servicio externo del agente | Las de ese servicio (p. ej. engram) |
+
+Regla: **una entrada vive en una sola memoria, nunca en ambas.** Si es una decisión o regla
+que un futuro agente del equipo debería encontrar → memoria del repo. Si es una nota personal
+de la sesión → memoria del agente. Ante la duda, va al repo: es la que sobrevive al repo y se
+comparte.
+<!-- /LOCKED: memory-boundary -->
+
 ## Flujo Spec-Driven (aspec)
 
 - **Cambios con scope incierto / arquitectura**: Crear artifacts en `aspec/changes/<name>/`.