@ancleto/spec 0.6.24 → 0.6.26

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:

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

@@ -139,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

@@ -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.
 
@@ -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.24",
+  "version": "0.6.26",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/skills/ancleto-archive/SKILL.md

@@ -42,14 +42,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 +74,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 +85,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.