ostacky 0.9.7 → 0.10.1

package/README.md

@@ -1,395 +1,172 @@
 # Ostacky
 
-Ostacky es un **agent harness** para [OpenCode](https://opencode.ai). No es solo un agente más: es el orquestador que instalás en tu proyecto para que **4 herramientas** trabajen en sinergia sin pisarse y sin quemar tokens de mas.
+Ostacky es un **agent harness** para [OpenCode](https://opencode.ai): el orquestador que instalás en tu proyecto para que **4 herramientas** trabajen en sinergia sin pisarse y sin quemar tokens de más.
 
-| Herramienta                                               | Rol                 | Define                                 |
+| Herramienta                                               | Rol                 | Responde                               |
 | --------------------------------------------------------- | ------------------- | -------------------------------------- |
 | [CodeGraph](https://github.com/colbymchenry/codegraph)    | Grafo de código     | DÓNDE está el código y a quién impacta |
 | [OpenSpec](https://github.com/Fission-AI/OpenSpec/)       | Especificaciones    | QUÉ hay que construir y POR QUÉ        |
 | [Superpowers](https://github.com/obra/superpowers)        | Ejecución           | CÓMO se implementa, prueba y revisa    |
 | [Engram](https://github.com/Gentleman-Programming/engram) | Memoria persistente | QUÉ aprendimos en sesiones anteriores  |
 
-Ostacky las rutea según el **nivel de impacto del cambio** (Nivel 0, Nivel 0+1, Nivel 1+), priorizando siempre eficiencia de tokens y preguntándote antes de actuar. Para cambios grandes usa OpenSpec (spec-driven development); para cambios chicos ejecuta directo con Superpowers skills.
-
-## Cómo empezar
-
-Después de instalar Ostacky (con `npx ostacky install`), necesitás iniciar OpenCode para usarlo. Tenés dos formas:
-
-### Terminal UI (TUI) — recomendado para daily driving
-
-```bash
-opencode
-```
-
-Abre la interfaz de terminal interactiva. **Para elegir el agente Ostacky: usá `Tab` para navegar entre agentes** en el panel lateral, o escribí `/agent Ostacky` en el chat.
-
-### Web UI — para usar desde el navegador (OpenCode v2)
-
-```bash
-opencode pair
-```
-
-Abre el link de un solo uso (expira en 5 minutos) o escaneá el QR en el navegador para cargar la web UI con cookie de sesión (30 días). **Para elegir el agente Ostacky: abrí el combo/selector de agentes** en la barra superior y seleccioná "Ostacky". Útil para sesiones largas, trabajo en equipo o cuando querés compartir pantalla sin compartir terminal.
-
-> Por defecto el server corre en `http://127.0.0.1:49374` solo en localhost. Cambialo con `opencode service` (ver tabla). Docs: https://opencode.ai/v2/docs/cli/web
-
-Opciones útiles (v2):
-
-| Comando                                            | Qué hace                                                        |
-| -------------------------------------------------- | --------------------------------------------------------------- |
-| `opencode pair`                                    | Muestra URL + QR para conectar web/app (links de un uso, 5 min) |
-| `opencode serve --hostname 0.0.0.0 --port 4096`    | Server dedicado en foreground (host remoto, Docker/systemd)     |
-| `opencode --server http://127.0.0.1:4096`          | Conectar un cliente TUI a un server activo                      |
-| `opencode service set hostname 0.0.0.0`            | Escuchar en red local (luego `opencode service start`)          |
-| `opencode service set port 49374`                  | Puerto fijo en vez del default del channel                      |
-| `opencode service set password "un-secreto-largo"` | Reemplaza password generado (rota todas las sesiones)           |
-
-> 💡 Si no tenés OpenCode instalado aún: `curl -fsSL https://opencode.ai/install | bash`
-
-## ¿Qué es?
-
-`Ostacky` es el agente (`.opencode/agents/`) que se instala directamente desde GitHub Releases. Cada instalación queda registrada en un lockfile con versión y checksum, lo que permite actualizaciones controladas y reproducibles.
-
-## Stack
-
-Ostacky integra **4 herramientas** especializadas para que trabajen en conjunto sin pisarse:
-
-### Cómo trabajan en sinergia
-
-1. **CodeGraph** descubre el alcance del cambio sin escanear el repo entero (consulta `codegraph_explore`, `codegraph_impact`).
-2. **OpenSpec** documenta requisitos, contratos y escenarios de aceptación (proposal → design → spec → tasks).
-3. **Superpowers** ejecuta con TDD, testing automatizado y review (brainstorming → plans → tdd → review).
-4. **Engram** persiste decisiones, bugs y descubrimientos con `mem_save` para que el agente no pierda contexto entre sesiones ni necesite re-ejecutar tool calls.
-
-Ostacky decide **cuándo y cómo** usar cada herramienta según el **nivel de impacto** del cambio:
+Ostacky las rutea según el **nivel de impacto del cambio** y **te pregunta antes de actuar**:
 
 | Nivel   | Cuándo aplica                            | Flujo                                                                  |
 | ------- | ---------------------------------------- | ---------------------------------------------------------------------- |
 | **0**   | <5 líneas, 1 archivo, trivial            | CodeGraph → directo a inline                                           |
-| **0+1** | 5-10 líneas, 1-2 archivos, sin API nueva | CodeGraph → usuario elige: spec o directo                              |
+| **0+1** | 5-10 líneas, 1-2 archivos, sin API nueva | CodeGraph → vos elegís: spec o directo                                 |
 | **1+**  | >10 líneas, API pública, refactors       | CodeGraph → OpenSpec → execution-mode-evaluation → subagentes o inline |
 
-Antes de ejecutar, Ostacky **muestra el análisis de archivos compartidos** (qué tasks tocan los mismos archivos) para que el usuario decida el modo de ejecución informado. Usa `execution-mode-evaluation` para recomendar inline o subagent-driven según clusters de archivos compartidos.
-
-## ¿Para qué sirve?
-
-- Instalar el agente `Ostacky` en cualquier proyecto con un solo comando.
-- Mantener un registro de qué versión está instalada (`ostacky-lock.json`)
-- Detectar y aplicar actualizaciones mostrando el diff de versiones antes de confirmar
-- Evitar descargas repetidas gracias al cache local en `.opencode/cache/`
-- Resolver tareas chicas sin overhead extra de coordinación.
-- Ejecutar tareas independientes en paralelo con **subagentes** cuando no comparten archivos, o inline secuencial cuando se pisan.
+Antes de ejecutar te muestra qué tasks comparten archivos, así elegís el modo de ejecución con información en mano.
 
 ## Requisitos
 
-- [Node.js](https://nodejs.org/) >= 20 (para usar con `npx`)
-- o [Bun](https://bun.sh/) >= 1.x (para usar con `bunx` o desarrollo)
-- [OpenCode](https://opencode.ai) instalado en tu máquina
-- **WSL:** Si usás Windows con WSL, seguí las instrucciones para **Linux** — WSL corre un kernel Linux real. No uses los comandos de PowerShell aunque estés en Windows.
-
-## Uso rápido (para usuarios)
-
-No requiere instalación global ni clonar el repositorio. Se usa directamente con `npx` o `bunx`:
-
-```bash
-npx ostacky
-```
-
-```bash
-bunx ostacky
-```
+- [Node.js](https://nodejs.org/) >= 20 (para `npx`) o [Bun](https://bun.sh/) >= 1.x (para `bunx` o desarrollo)
+- [OpenCode](https://opencode.ai) instalado ([docs](https://opencode.ai/v2/docs)): `bun install -g --trust @opencode/cli` o `npm install -g @opencode/cli` (el `--trust` de Bun habilita el postinstall que elige tu binario nativo)
+- Git recomendado: con git hay aislamiento por worktree; sin git Ostacky instala en el directorio actual con un aviso
+- **WSL:** seguí las instrucciones de **Linux** — WSL corre un kernel Linux real, no uses los comandos de PowerShell aunque estés en Windows
 
-## Uso
+## Instalación
 
-### Menú interactivo
+No requiere instalación global ni clonar el repositorio:
 
 ```bash
-npx ostacky
+npx ostacky          # menú interactivo (te pregunta el scope)
+bunx ostacky         # lo mismo con Bun
 ```
 
-Detecta automáticamente el directorio `.opencode/` del proyecto (o lo crea) y muestra un menú para elegir qué hacer.
-
-### Instalar todo (local, default)
+### Local (default)
 
 ```bash
-npx ostacky install                 # local en <proyecto>/.opencode (default)
-npx ostacky install --scope local   # <proyecto>/.opencode (explícito)
+npx ostacky install                 # <proyecto>/.opencode (default)
+npx ostacky install --scope local   # explícito
 ```
 
-Descarga todos los agentes y commands definidos en el manifest y los escribe en `<proyecto>/.opencode`. Además copia los plugins **Ostacky-owned** `ostacky-plugin.ts` + `engram.ts` en `.opencode/plugins/` (el legacy `ostacky-guard.ts` fue fusionado en `ostacky-plugin.ts` y ya no se instala; `ostacky-controller.ts` legacy se limpia automáticamente si quedó de una instalación previa) y asegura `.gitignore` con ` .opencode/tools/, .codegraph/, .opencode/cache/, ostacky-state.json*`.
-
-> **Instalación local (default):** Ostacky vive por proyecto/worktree (CodeGraph index `.codegraph/` y `ostacky-state.json` aislados). Si ves `C:\Users\...\ .opencode\tools\codegraph` y esperabas `D:\mi-proyecto\.opencode`, es porque corriste `npx ostacky` desde tu home sin estar dentro del proyecto (sin `.git`). Hacé `cd` al proyecto y re-ejecutá; el log muestra `projectRoot` y `toolsDir` explícitos.
+Instala el núcleo (agente, commands, skills, MCPs, plugins) más el stack de herramientas (CodeGraph, Engram) en `<proyecto>/.opencode`, y asegura `.gitignore` con `.opencode/tools/`, `.codegraph/`, `.opencode/cache/` y `ostacky-state.json*`.
 
-### Instalación global (opt-in)
+### Global (opt-in)
 
 ```bash
 npx ostacky --scope global           # menú interactivo global
-npx ostacky install --scope global   # núcleo global (agente + commands + skills + MCPs + plugins)
+npx ostacky install --scope global   # el mismo núcleo, sin el stack
 ```
 
-Escribe el núcleo en el config dir global de OpenCode sin tocar ningún proyecto:
-
-| SO | Dir global |
-|---|---|
-| Linux / macOS | `~/.config/opencode` (respeta `XDG_CONFIG_HOME`) |
-| Windows | config dir global de OpenCode según SO |
-| WSL | como Linux |
+Escribe el núcleo en el config dir global de OpenCode, sin tocar ningún proyecto:
 
-El stack de binarios (CodeGraph, Engram) es **siempre local por proyecto**: con `--scope global` se omite y se indica instalarlo por proyecto (`npx ostacky install-stack` dentro del proyecto). La config global acepta `opencode.json` o `opencode.jsonc`; si el proyecto define el mismo MCP, su objeto reemplaza al global (comportamiento v2), y en skills con mismo ID gana la del proyecto.
+| SO            | Dir global                                              |
+| ------------- | ------------------------------------------------------- |
+| Linux / macOS | `~/.config/opencode` (respeta `XDG_CONFIG_HOME`)        |
+| Windows       | `%APPDATA%\opencode` (fallback: `~/.config/opencode`)   |
+| WSL           | como Linux                                              |
 
-> **Migración v1 → v2:** `npx ostacky` (sin subcomando) busca la última versión publicada y, si detecta v1 instalada, ofrece desinstalar v1 e instalar v2 (siempre con confirmación; sin red o no-interactivo sigue al menú sin preguntar).
+La config global acepta `opencode.json` o `opencode.jsonc`. Si el proyecto define el mismo MCP, el del proyecto reemplaza al global (comportamiento v2); en skills con mismo ID gana la del proyecto.
 
-### Agregar agentes o commands individualmente
+> **Migración v1 → v2:** `npx ostacky` sin subcomando busca la última versión publicada y, si detecta v1 instalada, ofrece migrar (siempre con confirmación).
 
-```bash
-npx ostacky add agent
-npx ostacky add command
-```
-
-Muestra un selector múltiple con los recursos disponibles. Indica si ya están instalados y en qué versión.
-
-### Actualizar
-
-```bash
-npx ostacky update
-```
+### Por qué el stack es local
 
-Consulta la última GitHub Release, compara las versiones instaladas contra el manifest remoto y muestra el diff antes de confirmar:
+Con `--scope global` el stack (CodeGraph, Engram) **se omite** — se instala por proyecto con `npx ostacky install-stack` dentro de cada repo. El motivo:
 
-```
-Actualizaciones disponibles
-  agente   ostacky             0.0.1 → 0.0.2
-  command  install-stack    0.0.1 → 0.0.2
+- **El índice `.codegraph/` describe UN repo.** Se crea con `codegraph init` en cada proyecto y un watcher lo mantiene al día. Un índice global mezclaría símbolos de proyectos distintos (dos `UserService` colisionarían), no podría seguir ramas ni worktrees, y cada consulta arrastraría contexto ajeno. Como `.git/`: el motor puede ser global, el dato es por proyecto.
+- **El `ostacky-state.json` es por worktree.** Guarda fase, locks y auditoría del orquestador; aislado por worktree, varios agentes en paralelo no se pisan.
+- **Los binarios SÍ podrían ser globales** — ambos proyectos lo soportan (`npm i -g @colbymchenry/codegraph`; Engram vía Homebrew o su `setup.sh`, con datos en `~/.engram`). Ostacky prefiere una copia local versionada junto al lockfile para instalaciones reproducibles sin depender de tu PATH. Si ya tenés `engram` global, Ostacky lo reutiliza.
 
-¿Aplicar 2 actualización(es)? › Sí / No
-```
+## Primeros pasos
 
-Solo descarga los items que cambiaron de versión.
+1. **Iniciá OpenCode:** `opencode` (terminal) u `opencode pair` (web: abrí el link de un solo uso o escaneá el QR).
+2. **Elegí el agente:** `/agents` → `ostacky` (o Shift+Tab / Ctrl+X A).
+3. Escribí tu mensaje en el chat. En OpenCode v2, `@` es solo para referenciar archivos, no agentes.
 
-> **Nota:** `@latest` y `update` son cosas distintas. `npx ostacky@latest` fuerza a descargar la **última versión publicada** del instalador (el `@latest` es el tag de npm) y, sin subcomando, abre el menú interactivo. `npx ostacky update` corre la **acción de actualizar** (trae el manifest remoto y actualiza lo instalado según el lockfile) con la versión del instalador que npx resuelva (puede ser cacheada). Para ambas garantías, combinalos: `npx ostacky@latest update`.
+> Por defecto la web corre en `http://127.0.0.1:49374` solo en localhost. Docs: https://opencode.ai/v2/docs/cli/web
 
-### Desinstalar
+## Uso diario
 
 ```bash
-npx ostacky uninstall                          # qué borrar en <proyecto>/.opencode (default local)
-npx ostacky uninstall --scope local            # fuerza scope local
-npx ostacky uninstall --scope global           # qué borrar en el dir global
-```
-
-**Safe-delete:** solo borra lo trackeado en `.opencode/ostacky-lock.json` (agentes, commands, skills, MCPs) — nunca toca componentes previos del usuario que no estén en el lockfile. Antes de borrar muestra preview con `Scope: <ruta>` + lista de paths y pide confirmación. Los plugins Ostacky-owned (`ostacky-plugin.ts`, `engram.ts` + legacy `ostacky-guard.ts`/`ostacky-controller.ts` si quedaron) se limpian automáticamente via allowlist, nunca se borran plugins custom.
-
-> Si el lockfile no existe o está vacío → `No hay nada instalado.` y no borra nada.
-
-#### Desinstalar un agente puntual
-
-```bash
-npx ostacky uninstall agent <nombre>           # también admite --scope local
-npx ostacky uninstall agent                    # sin nombre → selector de instalados
-```
-
-Por ejemplo:
-
-```bash
-npx ostacky uninstall agent ostacky
-```
-
-#### Desinstalar un command puntual
-
-```bash
-npx ostacky uninstall command <nombre>         # también admite --scope local
-npx ostacky uninstall command                  # sin nombre → selector
-```
-
-Por ejemplo:
-
-```bash
-npx ostacky uninstall command install-stack
+npx ostacky add agent              # selector múltiple (indica instalados y versión)
+npx ostacky add command
+npx ostacky update                 # diff de versiones antes de confirmar
+npx ostacky@latest update          # update con la última versión publicada del instalador
 ```
 
-Si no especificás el nombre, el CLI te muestra un selector con los items instalados para que elijas cuáles desinstalar (puede ser uno o varios).
-
-#### Desinstalar todo el stack (tools + config)
+> `@latest` y `update` son cosas distintas: `@latest` es el tag de npm (qué instalador descargás), `update` es la acción (qué contenido actualizás según el lockfile).
 
 ```bash
-npx ostacky uninstall-stack                    # limpia mcp.codegraph/engram de opencode.json + .codegraph/ + .opencode/tools/
-npx ostacky uninstall-stack --scope local
+npx ostacky uninstall                          # safe-delete en <proyecto>/.opencode
+npx ostacky uninstall --scope global           # safe-delete global
+npx ostacky uninstall agent <nombre>           # puntual (sin nombre → selector)
+npx ostacky uninstall-stack                    # limpia config del stack del proyecto
+npx ostacky --version  |  npx ostacky --help
 ```
 
-No toca binarios globales ni datos de Engram, solo la configuración del proyecto.
+**Safe-delete:** solo borra lo trackeado en `ostacky-lock.json` — nunca toca componentes tuyos. Muestra preview con `Scope: <ruta>` y pide confirmación. Los plugins que instaló Ostacky no están en el lockfile: se limpian por allowlist; los tuyos no se tocan.
 
-### Otros
+## Qué se instala
 
-```bash
-npx ostacky --version   # muestra la versión del CLI
-npx ostacky --help      # muestra la ayuda
-```
-
-## Estructura generada
-
-Tras instalar (`--scope local`), el proyecto queda así:
+Local (`<proyecto>/.opencode`) o global (mismo árbol bajo el dir global, sin stack):
 
 ```
 .opencode/
-├── agents/
-│   └── ostacky.md
-├── commands/
-│   ├── install-stack.md
+├── agents/ostacky.md
+├── commands/install-stack.md
 │   └── opsx-sync.md
-├── skills/
-│   ├── brainstorming/
-│   ├── tdd/
-│   ├── review/
-│   ├── execution-mode-evaluation/
-│   ├── subagent-driven-development/
-│   ├── dispatching-parallel-agents/
-│   ├── openspec-propose/
-│   ├── openspec-apply-change/
-│   ├── openspec-archive-change/
-│   ├── receiving-code-review/
-│   ├── using-git-worktrees/
-│   ├── using-superpowers/
-│   ├── writing-skills/
-│   └── graceful-degradation/
+├── skills/                 ← brainstorming, tdd, review, execution-mode-evaluation,
+│                              subagent-driven, dispatching-parallel-agents, openspec-* (3),
+│                              receiving-code-review, using-git-worktrees,
+│                              using-superpowers, writing-skills, graceful-degradation
 ├── plugins/
-│   ├── ostacky-plugin.ts      ← controller hard-gate (fusiona guard legacy)
-│   └── engram.ts              ← plugin Engram
+│   ├── ostacky-controller/ ← controller hard-gate (index.ts + core + security + tiered)
+│   └── engram.ts           ← plugin Engram
 ├── mcp/
-│   ├── ostacky-controller/    ← MCP thin (observabilidad)
+│   ├── ostacky-controller/ ← MCP thin (observabilidad)
 │   └── openspec/
-├── tools/
-│   ├── codegraph/bin/codegraph
-│   └── engram/bin/engram
-├── cache/codegraph/           ← cache local CodeGraph/Discovery
-├── ostacky-state.json         ← estado por worktree (aislado)
-└── ostacky-lock.json          ← versiones instaladas (agentes, commands, skills, mcpServers)
+├── tools/                  ← SOLO local: codegraph/bin + engram/bin
+├── cache/codegraph/        ← cache local de descargas
+├── ostacky-state.json      ← SOLO local: estado aislado por worktree
+└── ostacky-lock.json       ← versiones instaladas (agents, commands, skills, mcpServers)
 ```
 
-> `assets/plugins/ostacky-guard.ts` fue **fusionado en `ostacky-plugin.ts` y eliminado** (re-export legacy). Fresh install solo escribe `ostacky-plugin.ts` + `engram.ts`; si venís de una versión previa con `ostacky-guard.ts` o `ostacky-controller.ts` legacy, el installer los elimina automáticamente.
-
-### ostacky-lock.json
+`plugins/` y `tools/` **no** se trackean en el lockfile. Instalaciones viejas con archivos legacy sueltos (`ostacky-plugin.ts`, `ostacky-guard.ts`, `ostacky-controller.ts`) se limpian automáticamente.
 
 ```json
 {
-    "version": "0.9.7",
-    "lockedAt": "2025-01-01T00:00:00.000Z",
-    "repo": "JaimeHoracio/Ostacky",
-    "tag": "v0.9.7",
-    "agents": {
-        "ostacky": {
-            "version": "0.9.7",
-            "installedAt": "2025-01-01T00:00:00.000Z",
-            "sha256": "abc123..."
-        }
-    },
-    "commands": {
-        "install-stack": {
-            "version": "0.9.7",
-            "installedAt": "2025-01-01T00:00:00.000Z",
-            "sha256": "def456..."
-        },
-        "opsx-sync": {
-            "version": "0.9.7",
-            "installedAt": "2025-01-01T00:00:00.000Z",
-            "sha256": "ghi789..."
-        }
-    },
-    "skills": {
-        "brainstorming": { "version": "0.9.7", ... },
-        "execution-mode-evaluation": { "version": "0.9.7", ... },
-        "openspec-propose": { "version": "0.9.7", ... }
-    },
-    "mcpServers": {
-        "ostacky-controller": { "version": "0.9.7", ... },
-        "openspec": { "version": "0.9.7", ... }
-    }
+    "version": "0.10.1",
+    "tag": "v0.10.1",
+    "agents": { "ostacky": { "version": "0.10.1", "sha256": "…" } },
+    "commands": { "install-stack": { … }, "opsx-sync": { … } },
+    "skills": { "brainstorming": { … }, "…" : {} },
+    "mcpServers": { "ostacky-controller": { … }, "openspec": { … } }
 }
 ```
 
-`plugins/` (`ostacky-plugin.ts`, `engram.ts`) y `tools/` **no** se trackean en el lockfile — son allowlist Ostacky-owned y se gestionan via `uninstall` (allowlist) y `uninstall-stack`.
-
-Se recomienda agregar `ostacky-lock.json` al control de versiones para que el equipo instale exactamente las mismas versiones.
+Versionado con checksums: sumá `ostacky-lock.json` a git para que el equipo instale exactamente las mismas versiones (mismo tag y mismos checksums).
 
-## Después de la instalación
+## Comandos útiles
 
-Al terminar la instalación, el flujo normal es:
+Engram y CodeGraph viven en `.opencode/tools/<herramienta>/bin/` y se exponen como MCP servers. Algunos comandos CLI:
 
-1. **Iniciar OpenCode** (si no está corriendo):
-    - **TUI:** `opencode` en tu terminal → seleccioná el agente con `/agents` (o atajos **Shift+Tab** / **Ctrl+X A**)
-    - **Web:** `opencode pair` y abrí el link impreso (ej. `http://127.0.0.1:49374/auth/...`) o escaneá el QR → abrí el selector de agentes de la interfaz y elegí `ostacky`
-2. OpenCode detecta automáticamente los archivos nuevos en `.opencode/` al iniciar, no necesita recarga manual.
-3. Para usar el agente, seleccionalo con `/agents` y escribí tu mensaje en el chat. (En OpenCode v2, `@` es solo para referenciar archivos, no agentes.)
+| Comando                                                           | Qué hace                                                |
+| ----------------------------------------------------------------- | ------------------------------------------------------- |
+| `engram list-projects`                                            | Proyectos con memoria                                   |
+| `engram clean-content --project <nombre>` \| `--all`              | Borra memoria de un proyecto / de todos                 |
+| `engram --version`                                                | Versión instalada                                       |
+| `codegraph init -i`                                               | Indexa el proyecto (crea `.codegraph/`)                 |
+| `codegraph sync` / `codegraph status`                             | Sincroniza / muestra estado del índice                  |
+| `codegraph install --target opencode --location local --yes`      | Recablea CodeGraph a OpenCode y genera AGENTS.md        |
 
-### Regenerar el stack manualmente
+## Troubleshooting
 
-El comando `/install-stack` también está disponible **dentro del chat de OpenCode** (TUI o web) por si querés regenerar el stack local sin salir de la sesión. Seleccioná primero el agente `ostacky` (con `/agents`) y ejecutá:
-
-```text
-/install-stack
-```
-
-Es opcional y solo necesario si algo falló durante la instalación o si querés verificar que todo esté en orden.
+- **Instalé fuera del proyecto / sin git:** el log muestra `projectRoot` y `toolsDir` explícitos; si `toolsDir` apunta a tu home (ej. `C:\Users\...\.opencode\tools\codegraph`) y esperabas tu proyecto, corriste el comando fuera de un repo git. Hacé `cd` al proyecto y re-ejecutá.
+- **El install global creó `.opencode/` local:** actualizá (`npx ostacky@latest`) y reinstalá — el menú interactivo ya propaga el scope y el stack se omite en global.
+- **Windows `cmd.exe ... codegraph.cmd init -i` durante el install:** warning no fatal — el binario quedó, solo falta el índice. Reintentá con `npx ostacky install-stack --scope local` o corré `.opencode\tools\codegraph\bin\codegraph.exe init -i` dentro del proyecto.
+- **¿Errores en el stack?** Elegí el agente `ostacky` y ejecutá `/install-stack` en el chat: regenera el stack sin salir de la sesión.
 
 ## Seguridad
 
-- `opencode.jsonc` se versiona en el repo para compartir permisos y MCP de forma reproducible.
-- Las URLs de descarga usan **tags de GitHub** (ej. `v0.9.7`), nunca `main` — instalaciones reproducibles
-- Cada path de archivo descargado es validado para prevenir **path traversal**
-- Los archivos incluyen **checksum SHA-256** opcional; si el manifest lo define, el contenido se verifica antes de escribir
-- El cache local (`.opencode/cache/`) también valida integridad al servir archivos cacheados
-
-#### Restricciones de acceso a credenciales
-
-- La configuración local de OpenCode (`opencode.jsonc`) bloquea lectura y escritura de `*.env` y `.secret/**` con `deny`.
-- La sesión sigue ejecutándose después del bloqueo porque `experimental.continue_loop_on_deny` está activado.
-- Para worktrees, el repo prefiere `.worktrees/` o `worktrees/` (ambos project-local).
-
-#### Patrones sensibles configurables (hardening-v2)
-
-- Variable `OSTACKY_SENSITIVE_PATTERNS` overridea los patrones por defecto (`**/.env*`, `**/.secrets/**`, `**/*.pem`, `**/*.key`, `**/.aws/**`, `**/.ssh/**`, `**/credentials.json`, `**/.npmrc`).
-- Ejemplo: `OSTACKY_SENSITIVE_PATTERNS="**/.env*,**/.secrets/**" bunx ostacky doctor` — `doctor` imprime el patrón efectivo.
-- Allowlist: `.env.example`, `.env.template`, `.env.sample` nunca se bloquean.
-- Fuente única: `src/security.ts` (`SENSITIVE_DEFAULT`, `isSensitive`, `BASH_SENSITIVE_RE`) — mirrors generados en `assets/plugins/security.ts` y `assets/mcp/ostacky-controller/security.js` vía `bun run scripts/sync-controller-core.ts`; `ostacky-plugin.ts` importa de `./security.ts` (self-contained). Ver `doctor` para verificar.
-
-#### Aislamiento de worktrees (harness-prod-hardening)
-
-Cada worktree de git tiene su **propio** `ostacky-state.json` aislado (resuelto via `findProjectRoot()` con `git rev-parse --show-toplevel`). Dos worktrees no comparten `statePath`, locks ni backups — 3 agentes en 3 worktrees no corrompen el estado del otro. Ver `assets/skills/using-git-worktrees/SKILL.md` §Ostacky Worktree Isolation y `src/fs.ts:findProjectRoot`.
-
-## Cache
-
-Los archivos descargados se guardan en:
-
-```
-.opencode/cache/<repo>/<tag>/<ruta-del-archivo>
-```
-
-Si ya existe un archivo en cache con el hash correcto, no se hace ninguna petición de red.
-
-## Comandos útiles de las herramientas
-
-### Engram (memoria persistente)
-
-Engram está instalado localmente en `.opencode/tools/engram/bin/engram` y se configura como MCP server en `opencode.json`. Desde el chat de OpenCode, usá las tools de Engram directamente. Algunos comandos CLI útiles:
-
-| Comando                                                              | Qué hace                                                  |
-| -------------------------------------------------------------------- | --------------------------------------------------------- |
-| `.opencode/tools/engram/bin/engram list-projects`                    | Lista todos los proyectos con memoria en Engram           |
-| `.opencode/tools/engram/bin/engram clean-content --project <nombre>` | Borra el contenido de memoria de un proyecto específico   |
-| `.opencode/tools/engram/bin/engram clean-content --all`              | Borra TODO el contenido de memoria de todos los proyectos |
-| `.opencode/tools/engram/bin/engram serve`                            | Inicia el server de session tracking (puerto 7437)        |
-| `.opencode/tools/engram/bin/engram --version`                        | Muestra la versión instalada                              |
-
-### CodeGraph (grafo de código)
-
-CodeGraph está instalado en `.opencode/tools/codegraph/bin/codegraph` y se configura como MCP server. Desde el chat de OpenCode, usá las tools de CodeGraph directamente (`codegraph_explore`, `codegraph_trace`, etc.). Algunos comandos CLI útiles:
-
-| Comando                                                                                    | Qué hace                                                    |
-| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
-| `.opencode/tools/codegraph/bin/codegraph init -i`                                          | Indexa el proyecto actual (crea `.codegraph/` con el grafo) |
-| `.opencode/tools/codegraph/bin/codegraph sync`                                             | Sincroniza cambios incrementales al grafo                   |
-| `.opencode/tools/codegraph/bin/codegraph status`                                           | Muestra estado del index y archivos pendientes              |
-| `.opencode/tools/codegraph/bin/codegraph install --target opencode --location local --yes` | Configura CodeGraph para OpenCode y genera AGENTS.md        |
-
-> **Windows:** si ves `Command failed: cmd.exe /d /c call ... codegraph.cmd init -i` durante `npx ostacky install`, es un _warning_ no fatal — el binario se instaló pero el índice no se pudo crear. Reintentá con `npx ostacky install-stack --scope local` o ejecutá manualmente `.opencode\tools\codegraph\bin\codegraph.exe init -i` (o `codegraph.cmd` si no hay `.exe`) dentro del proyecto. Desde v0.9.7 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
+- `opencode.jsonc` puede versionarse para compartir permisos y MCP de forma reproducible.
+- Descargas por tags de GitHub (nunca `main`), validación anti path-traversal y checksums SHA-256 del manifest.
+- Cache local en `.opencode/cache/<repo>/<tag>/<ruta>` con validación de integridad: si el hash cacheado coincide, no hay petición de red.
+- Lectura/escritura de `*.env` y `.secret/**` bloqueadas con `deny` (la sesión sigue por `experimental.continue_loop_on_deny`).
+- Patrones sensibles configurables: `OSTACKY_SENSITIVE_PATTERNS="**/.env*,**/.secrets/**" bunx ostacky doctor` (allowlist: `.env.example/.template/.sample`). Fuente única en `src/security.ts`; verificá con `npx ostacky doctor`.
 
 ## Licencia
 

package/assets/agents/ostacky.md

@@ -1,12 +1,12 @@
 ---
 description: Orquestador principal — rutea por nivel, orquesta CodeGraph + OpenSpec + Superpowers.
 mode: primary
-version: 0.9.7
+version: 0.10.1
 ---
 
-Sos **Ostacky v0.9.7**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
+Sos **Ostacky v0.10.1**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
 
-> **Versión:** `0.9.7` (sincronizada desde `package.json` vía `scripts/sync-version.ts`). Cuando te pregunten qué versión tenés, qué versión sos, o `¿qué versión tenés?` / `version` / `¿en qué versión estás?`, respondé exactamente: **"Ostacky v0.9.7"** (o `v0.9.7` si te piden solo el número). No inventes otra versión.
+> **Versión:** `0.10.1` (sincronizada desde `package.json` vía `scripts/sync-version.ts`). Cuando te pregunten qué versión tenés, qué versión sos, o `¿qué versión tenés?` / `version` / `¿en qué versión estás?`, respondé exactamente: **"Ostacky v0.10.1"** (o `v0.10.1` si te piden solo el número). No inventes otra versión.
 
 ## Reglas innegociables
 
@@ -45,7 +45,7 @@ Sos **Ostacky v0.9.7**, orquestás, no implementás. Interpretás, clasificás (
 
 **CodeGraph:** `codegraph_codegraph_explore` antes de búsqueda manual. Si ya llamaste para área, reusar. Timeout 10s → Engram → Read.
 
-**Discovery-cache (único):** `getDiscoverySnapshot(query)` TTL 1h + `gitDiffHash`. Si hit → reusar. Si miss → `codegraph_explore`+`mem_search` + `put` obligatorio. Dedup `mem_search` por `requestId`.
+**Discovery:** `codegraph_explore` + `mem_search`. Si ya llamaste para el área en este request, reusar ese output. No hay cache de archivo.
 
 **Engram:** `mem_context` inicio, `mem_search` antes de decidir, `mem_save` tras gate.
 
@@ -59,7 +59,7 @@ Si vago → preguntar. Si claro → `start_request`.
 
 1. `engram_mem_context` (lazy si `isTrivial && DONE` solo pointer)
 2. Change activo → `proposal.md`/`design.md`/`tasks.md`
-3. `getDiscoverySnapshot`; si miss → `codegraph_explore`+`mem_search` + `put`
+3. `codegraph_explore` + `mem_search`; reusar si ya lo hiciste para el área en este request
 4. `codegraph_impact` solo si no cubierto
 5. `Read` solo lo no cubierto
 
@@ -79,14 +79,14 @@ Router `brainstorming`↔`OpenSpec` por `level`/`estLines`/`fileCount`/`hasAPI`
 
 **SHALL sin ambigüedad (spec iterativo + sync proactiva):**
 
-- Antes de crear/editar `openspec/changes/<id>/{proposal.md,design.md,tasks.md}` **O** `docs/superpowers/specs/*.md`: si existe → SHALL `read` fresco de TODOS y SHALL `edit` (no `write`); `write` solo si no existía. Para `open-explore` sin archivo → SHALL `mem_save topic_key:brainstorm/<hash>` por iteración. `getDiscoverySnapshot` no aplica a specs/docs.
+- Antes de crear/editar `openspec/changes/<id>/{proposal.md,design.md,tasks.md}` **O** `docs/superpowers/specs/*.md`: si existe → SHALL `read` fresco de TODOS y SHALL `edit` (no `write`); `write` solo si no existía. Para `open-explore` sin archivo → SHALL `mem_save topic_key:brainstorm/<hash>` por iteración. El discovery no aplica a specs/docs.
 - Al final de cada turno de brainstorming/spec con decisiones nuevas no reflejadas en disco: SHALL listar cálido `Noté que lo que acordamos (X por Z) aún no está en <archivo>: 1) ...` (max 3) y SHALL proponer en UNA sola pregunta `¿Querés que agregue [X, Y] a <archivo> e implemente <mejor propuesta> —la recomiendo por <tradeoff/evidencia>—?` (respetando Regla 5). Si no hay delta, no proponer. Eximido si `isTrivial`.
 
 ### 4. Execution
 
 1. `skill(execution-mode-evaluation)` en memoria, reusa discovery.
 2. Gate ÚNICO (sin segunda pregunta): presentar resumen único `Nivel + DIRECT/SPEC + INLINE/SUBAGENT + archivos + ~líneas` (+ comparativa tokens|tiempo si `1+` multi-archivo) → UNA sola pregunta `¿Procedo?` (el usuario puede modificar). Si hay Riesgo concreto verificable aunque sea 0+1, el resumen incluye `Riesgo concreto: … → Mitigación: …`; sin riesgo verificable no se inventa ninguno. Todo override a advertencia del agente (de memoria o técnica) SHALL pasar por `record_user_confirmation`. Si confirma → `record_execution_analysis` + `consume_execution_decision` seguidos sin volver a preguntar. `Nivel 0` y mismo-archivo → recomendación fija `INLINE/DIRECT` sin alternativa. `1+` multi-archivo → tabla `INLINE (1x contexto, más lento) vs SUBAGENT (Nx contexto, más rápido, reglas 2b/3c intactas)` + recomendación; nunca forzar `INLINE`.
-3. Por task: `Read` fresco → plugin valida edición in-process → `edit` → `verifyTask` (genérico: `codegraph:<Symbol>` con `codegraph_codegraph_explore`, `file:<path> contiene <string>` con `Read`/`Grep`, `test:<cmd>` con `shell` acotado — según `— verificar:` de `tasks.md`) → solo si `verifyTask.ok` → `complete_task`. **NUNCA marques `complete_task` a ojo**; si `verifyTask` falla, reintentá el fix. Vale para SPEC y DIRECT, INLINE y SUBAGENTS.
+3. Por task: `Read` fresco → plugin valida edición in-process → `edit` → `complete_task`. El chequeo corre dentro de complete_task (no existe la tool `verify_task`): elige la verificación de `— verificar:` en `tasks.md` y devuelve el motivo si falla. **NUNCA marques `complete_task` a ojo**; si la verificación falla, reintentá el fix. Vale para SPEC y DIRECT, INLINE y SUBAGENTS.
 
 ### 5. Sync y cierre
 
@@ -100,4 +100,4 @@ Router `brainstorming`↔`OpenSpec` por `level`/`estLines`/`fileCount`/`hasAPI`
 - Una pregunta por turno, sin deadlock
 - Fase gate: en EXECUTING/SYNC no volver a DISCOVERY
 - Audit: log antes de gate + `mem_save` solo en gates
-- **Tasks son verificables, no instruccionales (genérico):** `tasks.md` SHALL describir `qué` + `cómo verificar` con formato `— verificar: codegraph:<Symbol> | file:<path> contiene <string> | test:<cmd>` (ej: `— verificar: codegraph:CurrencyContext` o `— verificar: test: bun test tests/domains/settle.test.ts`). El controller parsea `taskVerifications` y `verifyTask` lo re-verifica con `CodeGraph`/`Read`/`test`; `complete_task` solo pasa si `verifyTask.ok`. Nunca SHALL contener instrucciones genéricas (`“sé cuidadoso”`) — eso vive acá. Para `Level 0` trivial, tasks SHALL ser de 1 línea sin overhead.
+- **Tasks son verificables, no instruccionales (genérico):** `tasks.md` SHALL describir `qué` + `cómo verificar` con formato `— verificar: codegraph:<Symbol> | file:<path> contiene <string> | test:<cmd>` (ej: `— verificar: codegraph:CurrencyContext` o `— verificar: test: bun test tests/domains/settle.test.ts`). El controller parsea `taskVerifications` al registrar el análisis de ejecución. `file:<path> contiene <str>` exige el string en el archivo; `codegraph:<Symbol>` exige que el símbolo aparezca en el archivo (proxy textual, NO consulta al grafo); `test:<cmd>` exige evidencia: el agente corre el test, el plugin registra cada `shell` con su `exit` real, y `complete_task` sólo acepta una corrida con el comando exacto, `exit 0` y posterior a la última edición (sin evidencia, falla). `complete_task` corre el chequeo y sólo marca COMPLETED si pasa. Nunca SHALL contener instrucciones genéricas (`“sé cuidadoso”`) — eso vive acá. Para `Level 0` trivial, tasks SHALL ser de 1 línea sin overhead.

package/assets/commands/install-stack.md

@@ -6,7 +6,7 @@ subagent: false
 
 Instala el stack tecnológico de desarrollo para OpenCode. **IMPORTANTE:** las herramientas se instalan por separado (cada una con su propio CLI/comando). `npx ostacky install` solo instala el agente y commands de Ostacky en `.opencode/`. Este comando (`/install-stack`) es la guía de referencia para la instalación manual completa paso a paso.
 
-**Nota:** A partir de v0.9.7, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
+**Nota:** A partir de v0.10.1, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
 
 **RESTRICCIÓN ABSOLUTA:** instalar ÚNICAMENTE para OpenCode. Está terminantemente prohibido crear o modificar archivos en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/`, `.antigravity/`, `.windsurf/` o cualquier otro directorio de plataformas externas.