@ancleto/spec 0.9.0 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Argañarás, Lucas Bonch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,7 @@
 
 **Orquestador SDD (Spec-Driven Development) y toolkit personal asistido por IA**
 
-[![Version](https://img.shields.io/npm/v/@ancleto/spec?style=flat-square&label=version&color=4f46e5)](https://www.npmjs.com/package/@ancleto/spec)
+[![Version](https://img.shields.io/npm/v/%40ancleto/spec?style=flat-square&label=version&color=4f46e5)](https://www.npmjs.com/package/@ancleto/spec)
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A5%2024-43853D?style=flat-square&logo=node.js&logoColor=white)](#requisitos)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-0d9488?style=flat-square)](#requisitos)
 [![Agents](https://img.shields.io/badge/agents-10-334155?style=flat-square)](#caracter%C3%ADsticas-principales)
@@ -23,6 +23,7 @@
 - [Características principales](#características-principales)
 - [Requisitos](#requisitos)
 - [Instalación](#instalación)
+- [Instalación manual (sin npm)](docs/instalacion-manual.md)
 - [Hosts soportados y layouts por agente](#hosts-soportados-y-layouts-por-agente)
 - [Guía de .gitignore](#guía-de-gitignore)
 - [Configuración y tiers de costo](#configuración-y-tiers-de-costo)
@@ -165,10 +166,11 @@ verificados de Antigravity (`read`→`view_file`, `edit`→`replace_file_content
 tool de opencode sin id verificado se **omite con aviso** (`skip tool '<k>': no verified Antigravity id
 for agent '<n>'`): un id inexistente cuelga el subagent. Los ids que sólo existen en el SDK
 (`find_file`, `edit_file`, `search_web`, `read_url_content`, …), los de comunidad (`write_to_file`,
-`call_mcp_tool`, `multi_replace_file_content`, …) y los de delegación (`invoke_subagent`,
-`start_subagent`, `define_subagent`) **no** se emiten; el uso de MCP se expresa por
-`mcpServers`/`.agents/mcp_config.json`, nunca como tool id. El campo `skill` no es una tool: se cubre
-con el surfaceo automático de skills de Antigravity.
+`multi_replace_file_content`, …) y los de delegación (`invoke_subagent`, `start_subagent`,
+`define_subagent`) **no** se emiten. Las claves de MCP declaradas dentro de `tools` (`mcpServers`,
+`mcp_*`, `call_mcp_tool`) caen en **omisión con aviso** y `call_mcp_tool` queda **prohibido**; el uso
+de MCP se expresa por `mcpServers`/`.agents/mcp_config.json`, nunca como tool id. El campo `skill` no
+es una tool: se cubre con el surfaceo automático de skills de Antigravity.
 
 Los assets que un host no soporta (por ejemplo `agents`/`commands` de `cursor` y `roo`)
 **no se escriben** y el instalador avisa por `stderr`
@@ -308,6 +310,8 @@ ancleto init              # Crea .ancletorc, aspec/, AGENTS.md y PRODUCT.md
 
 `init` **no pisa** lo que ya existe: si tu repo tiene su propio `AGENTS.md` o `PRODUCT.md`, los respeta (solo fusiona los bloques `<!-- LOCKED -->` del template). Además materializa `.ancleto/working-context.md` con tus reglas activas cuando hay memoria — es el bloque que el orquestador inyecta al arrancar.
 
+Si el repo trae una carpeta legacy `openspec/`, `init`, `install --project` y `upgrade` la detectan y migran su contenido a `aspec/` **por copia**, sin prompts, cuando `aspec/` no existe o sólo tiene el scaffold: conservan `openspec/` como backup y escriben el marcador `aspec/.migrated-from-openspec`. Si `aspec/` ya tiene contenido real propio no fusionan las carpetas y avisan para revisión manual, y si el marcador ya existe la corrida es un no-op silencioso.
+
 > ¿Querés que el proyecto lleve **su propia** copia de agents/skills (sin depender de la instalación global)? Sumá `ancleto install --project .`.
 
 ### 2. Descubrir contexto técnico
@@ -409,7 +413,7 @@ Funciona en tres piezas que comparten el mismo archivo:
 
 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`.
+> 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 en los lifecycle points (`init`, `install --project`, `upgrade` y `memory context --out`) y también **on-write**, cuando una escritura MCP lo altera: al registrar una `rule` con scope `project` o al superseder una `memory_key` existente (sin importar `type` ni `scope`).
 
 **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.
 
@@ -425,7 +429,8 @@ Una vez instalado, tu IDE expone el ciclo de vida completo como comandos barra:
 | `/cleto-propose` | Proponer el diseño técnico. |
 | `/cleto-ff` | Avanzar rápido con el contexto ya recuperado. |
 | `/cleto-apply` | Aplicar el código del change. |
-| `/cleto-verify` | Verificar reglas, tests y memoria antes de cerrar. |
+| `/cleto-verify` | Verificar reglas, tests y memoria antes de cerrar. En modo `aspec Change`, cuando el proposal declara garantías de efecto sobre estado, verifica además que se sostengan bajo el modelo real; si no, emite `GUARANTEE NOT SUSTAINED` (`CRITICAL`) y el orquestador bloquea el archive. |
+| `/cleto-review` | Revisar código del scope por duplicación, redundancia, mala ubicación y código sin uso. |
 | `/cleto-security` | Realizar una auditoría de seguridad integral en el proyecto o change. |
 | `/cleto-sync` | Sincronizar las specs con el estado del repositorio. |
 | `/cleto-archive` | Archivar el change y registrar aprendizajes. |

package/commands/cleto-review.md

@@ -0,0 +1,9 @@
+---
+description: Review scoped code for duplication, redundancy, misplacement and dead code
+---
+
+Invoke the `ancleto-review` skill with the Skill tool and follow it exactly; do not improvise steps.
+
+**Input**: The argument after `/cleto-review` is the scope to review: a ticket reference (e.g. `#123`, resolved to commits whose message contains it), a git range (e.g. `main..HEAD`), or paths/directories. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available scopes.
+
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.

package/package.json

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

package/skills/ancleto-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: ancleto-review
+description: Review user-scoped code for duplication, redundancy, misplacement and dead code. Reports findings with file:line refs without modifying code. No external binaries required.
+license: MIT
+compatibility: No external binaries required. Works with any agent runtime.
+metadata:
+  author: ancleto
+  version: '1.0'
+---
+
+# aspec Review
+
+Review code quality inside a user-declared scope. Read-only: never write or edit code.
+
+**Input**: the scope to review — free text after `/cleto-review`. Forms (first match wins): `#<n>` (commits whose message contains `#<n>`), an explicit git range (`A..B`, `HEAD~n`), existing paths/directories, or empty (infer from context). If ambiguous, list candidate scopes and ask. Never guess.
+
+**IMPORTANT**: Do NOT guess or auto-select a scope when ambiguous. Always let the user choose. Work Item grounding (when the request references a Work Item) is owned by `@context-resolver` — treat a resolved item as `#<n>`.
+
+## Steps
+
+### 1. Resolve the scope
+
+- `#<n>` → `git log --grep="#<n>" --format=%H`, then the diff of each commit (`H^ H`). Only code introduced there is in scope.
+- Range (`A..B`, `HEAD~n`) → `git diff` of that range.
+- Paths → worktree diff filtered to those paths.
+- Nothing usable → list `aspec/changes/` dirs with `tasks.md` and recent `git log` subjects as candidates, and ask.
+
+The result is a concrete file:line list. Report ONLY on that list.
+
+### 2. Collect evidence (reading outside the scope is allowed)
+
+Read outside the diff solely as comparison evidence: twin definitions (redundancy), call/import references (dead code), and the project map (`PRODUCT.md`, directory structure, `aspec/specs/`) for placement. Never report findings outside the scope.
+
+### 3. Run the four detectors
+
+**Duplicated code:** twin blocks inside the scope doing the same logic → CRITICAL: "Duplicated block: `<file:line>` and `<file:line>`" + "Extract to a shared helper".
+
+**Redundant method:** scope logic already implemented outside the diff → WARNING: "Redundant with `<external-file:line>`" + "Reuse `<name>` instead of duplicating". If the difference is subtle or uncertain, downgrade to SUGGESTION.
+
+**Misplaced code:** scope code contradicting the project map (e.g. business logic in a handler, stray util in a component) → WARNING or SUGGESTION: "Misplaced code: `<file:line>` belongs in `<location>`" + reason. When the architecture is unclear, prefer SUGGESTION.
+
+**Dead code:** scope functions/imports with no references in the repo (search calls and imports) → CRITICAL when proven (no references at all): "Unused code: `<file:line>`" + "Remove it". Otherwise SUGGESTION.
+
+### 4. Review Report
+
+```
+## Review: <scope description>
+
+### CRITICAL
+- ...
+
+### WARNING
+- ...
+
+### SUGGESTION
+- ...
+```
+
+**Issues by priority**, each with a specific recommendation:
+
+1. **CRITICAL** (proven duplication or proven dead code inside the scope).
+2. **WARNING** (likely redundancy or misplacement, evidence cited).
+3. **SUGGESTION** (uncertain or stylistic, needs human judgment).
+
+**Assessment:** CRITICAL → "X critical issue(s) found. Fix before merging."; warnings only → "No critical issues. Y warning(s) to consider."; clean → "No issues found in scope: `<scope>`."
+
+## Heuristics
+
+- **Scope discipline**: every finding must point at a file:line inside the scope; external files appear only as evidence.
+- **False positives**: when uncertain, prefer SUGGESTION > WARNING > CRITICAL.
+- **Actionability**: every issue carries a specific recommendation with file/line refs.
+
+## Guardrails
+
+- Read-only: never write, edit, or refactor code — only report.
+- Reference code as `file.ts:123`.
+- No vague suggestions ("consider reviewing") — every issue needs a specific recommendation.
+- Never paste diffs or code blocks — cite locations.
+- At most 5 findings per severity; if more exist, keep the 5 highest-impact and state the count of the rest.
+- This skill does not verify artifacts (that is `ancleto-verify`), conventions against an approved request (that is `reviewer`), or vulnerabilities (that is `ancleto-security`).