ostacky 0.10.0 → 0.10.2

package/README.md

@@ -9,7 +9,7 @@ Ostacky es un **agent harness** para [OpenCode](https://opencode.ai): el orquest
 | [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**, preguntándote antes de actuar: cambios grandes van por OpenSpec (spec-driven development), cambios chicos ejecutan directo con skills de Superpowers.
+Ostacky las rutea según el **nivel de impacto del cambio** y **te pregunta antes de actuar**:
 
 | Nivel   | Cuándo aplica                            | Flujo                                                                  |
 | ------- | ---------------------------------------- | ---------------------------------------------------------------------- |
@@ -17,12 +17,12 @@ Ostacky las rutea según el **nivel de impacto del cambio**, preguntándote ante
 | **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 qué tasks tocan los mismos archivos para que elijas el modo de ejecución informado (inline secuencial o subagentes en paralelo).
+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 `npx`) o [Bun](https://bun.sh/) >= 1.x (para `bunx` o desarrollo)
-- [OpenCode](https://opencode.ai) instalado: `curl -fsSL https://opencode.ai/install | bash`
+- [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
 
@@ -31,7 +31,7 @@ Antes de ejecutar, Ostacky muestra qué tasks tocan los mismos archivos para que
 No requiere instalación global ni clonar el repositorio:
 
 ```bash
-npx ostacky          # menú interactivo
+npx ostacky          # menú interactivo (te pregunta el scope)
 bunx ostacky         # lo mismo con Bun
 ```
 
@@ -44,13 +44,11 @@ npx ostacky install --scope local   # explícito
 
 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*`.
 
-> Si el log muestra `toolsDir` en tu home (ej. `C:\Users\...\.opencode\tools\codegraph`) y esperabas tu proyecto, es porque corriste el comando fuera de un repo git. Hacé `cd` al proyecto y re-ejecutá.
-
 ### 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:
@@ -81,8 +79,6 @@ Con `--scope global` el stack (CodeGraph, Engram) **se omite** — se instala po
 
 > Por defecto la web corre en `http://127.0.0.1:49374` solo en localhost. Docs: https://opencode.ai/v2/docs/cli/web
 
-Si algo del stack falló durante la instalación, regeneralo sin salir de la sesión: seleccioná `ostacky` y ejecutá `/install-stack` en el chat.
-
 ## Uso diario
 
 ```bash
@@ -102,7 +98,7 @@ npx ostacky uninstall-stack                    # limpia config del stack del pro
 npx ostacky --version  |  npx ostacky --help
 ```
 
-**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 Ostacky-owned se limpian por allowlist; los custom no se tocan.
+**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.
 
 ## Qué se instala
 
@@ -129,20 +125,20 @@ Local (`<proyecto>/.opencode`) o global (mismo árbol bajo el dir global, sin st
 └── ostacky-lock.json       ← versiones instaladas (agents, commands, skills, mcpServers)
 ```
 
-`plugins/` y `tools/` **no** se trackean en el lockfile (allowlist Ostacky-owned). Instalaciones viejas con archivos legacy sueltos (`ostacky-plugin.ts`, `ostacky-guard.ts`, `ostacky-controller.ts`) se limpian automáticamente.
+`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.10.0",
-    "tag": "v0.10.0",
-    "agents": { "ostacky": { "version": "0.10.0", "sha256": "…" } },
+    "version": "0.10.2",
+    "tag": "v0.10.2",
+    "agents": { "ostacky": { "version": "0.10.2", "sha256": "…" } },
     "commands": { "install-stack": { … }, "opsx-sync": { … } },
     "skills": { "brainstorming": { … }, "…" : {} },
     "mcpServers": { "ostacky-controller": { … }, "openspec": { … } }
 }
 ```
 
-Versionado con checksums: sumá `ostacky-lock.json` a git para que el equipo instale exactamente las mismas versiones. Las descargas usan tags de GitHub (nunca `main`) y cada path se valida contra path traversal.
+Versionado con checksums: sumá `ostacky-lock.json` a git para que el equipo instale exactamente las mismas versiones (mismo tag y mismos checksums).
 
 ## Comandos útiles
 
@@ -159,22 +155,19 @@ Engram y CodeGraph viven en `.opencode/tools/<herramienta>/bin/` y se exponen co
 
 ## Troubleshooting
 
-- **Instalé fuera del proyecto / sin git:** hacé `cd` al proyecto y re-ejecutá. El log muestra `projectRoot` y `toolsDir` explícitos para diagnosticar scope.
+- **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?** Desde el chat de OpenCode: `/install-stack`.
+- **¿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` puede versionarse para compartir permisos y MCP de forma reproducible.
-- Descargas por tags de GitHub + validación anti path-traversal + checksums SHA-256 del manifest + cache local con validación de integridad.
+- 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`.
 
-## Cache
-
-Descargas en `.opencode/cache/<repo>/<tag>/<ruta>`. Si el archivo cacheado tiene el hash correcto, no hay petición de red.
-
 ## Licencia
 
 MIT

package/assets/agents/ostacky.md

@@ -1,17 +1,17 @@
 ---
 description: Orquestador principal — rutea por nivel, orquesta CodeGraph + OpenSpec + Superpowers.
 mode: primary
-version: 0.10.0
+version: 0.10.2
 ---
 
-Sos **Ostacky v0.10.0**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
+Sos **Ostacky v0.10.2**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
 
-> **Versión:** `0.10.0` (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.0"** (o `v0.10.0` si te piden solo el número). No inventes otra versión.
+> **Versión:** `0.10.2` (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.2"** (o `v0.10.2` si te piden solo el número). No inventes otra versión.
 
 ## Reglas innegociables
 
 1. **NUNCA te congeles.** Plan B antes de tool, no reintentes fallida.
-2. **CodeGraph primero.** Nunca `rg/grep` para código. `Grep` solo literales.
+2. **CodeGraph primero ante query de símbolo/flujo/impacto** (¿quién llama a X?, blast radius, dónde vive un símbolo). Grep/glob directo es legítimo ante query de literal (string exacto, TODO, config, `.md`/`.json`) — pero el gate SIEMPRE exige un `codegraph_codegraph_explore` completado antes de leer código (`shouldBlockCodeRead`). Para leer código no-indexable a conciencia, el explore previo es calibración, no sobrehead: barato, local y confirma que el índice está vivo.
 3. **El plugin hace cumplir PENDING.** Hard gate en `ctx.tool.hook("execute.before")`; no llames `check_*` manual.
 4. **No edites sin Read fresco.** Nunca cache de turno anterior.
 5. **Una pregunta por turno.** Natural, sin tool, STOP y esperar. Respuesta vinculante.
@@ -45,7 +45,7 @@ Sos **Ostacky v0.10.0**, 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
 
@@ -97,7 +97,8 @@ Router `brainstorming`↔`OpenSpec` por `level`/`estLines`/`fileCount`/`hasAPI`
 ## Guardrails
 
 - Decisión en OpenSpec/CodeGraph/controller → no re-resolver
+- **Multi-sesión (un state file por proyecto):** si `start_request` devuelve `conflict:true` o un tool devuelve `BLOCKED: … pertenece a otra sesión`, NO re-presentes el resumen de ejecución ni consumas/bloquees esa decisión. Preguntá una sola cosa: takeover explícito (`start_request({force:true})`, auditado) o continuar en la otra sesión. Si `get_state` muestra `callerSessionId:null` con `ownerSessionId` no nulo, tratá la request como ajena (no hay identidad que pruebe lo contrario).
 - 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.10.0, `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.2, `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.
 

package/assets/docs/ostacky-reference.md

@@ -27,12 +27,11 @@ BLOCKED: replan→INTERPRETATION_PENDING, abandon→DONE
 | controller_* | 5s | 1 | degraded |
 | engram_* | 5s | 1 | sin memoria |
 
-## Cache
-
-- `src/cache-codegraph.ts`: `.opencode/cache/codegraph/<sha256(query)>.json` con `{ts, result, gitHead, gitDiffHash}`, TTL 1h, `OSTACKY_CACHE_DISABLE=1` bypass, LRU 50MB, invalidación `git diff --name-only` + `git status --porcelain --untracked-files=all` (hash combinado).
-- `src/discovery-cache.ts`: `.opencode/cache/codegraph/discovery-<sha256>.json` con `{codegraph, engramHits, gitDiffHash, gitHead, ts, query}`, mismo TTL/LRU. `getDiscoverySnapshot` → hit reusar sin llamar tools; miss → SHALL `putDiscoverySnapshot` antes de `record_discovery` (auditable `WARN:cache_miss_without_put`).
-- `record_cache_hit/miss` internos: `cache-codegraph.ts` hace write directo a `ostacky-state.json` incrementando `cacheHitCount/tokenSavingEstimate` sin tool LLM.
+## Discovery
 
+- Sin cache de archivo: discovery = `codegraph_explore` + `mem_search`; el reuso es del output ya presente en el contexto del request. `src/discovery-cache.ts` y `src/cache-codegraph.ts` se retiraron (change `remove-discovery-cache-phantom`).
+- `OSTACKY_CACHE_DISABLE` ya no existe: no hay cache filesystem que desactivar.
+- Los contadores `cacheHitCount`/`tokenSavingEstimate` quedan en `get_metrics` por compatibilidad, en 0: nada los incrementa.
 ## Metrics (get_metrics)
 
 `revision, state, degraded, taskCounts{completed,pending,total,expected}, expectedTaskCount, auditSize, stateFileSize, diskFreeMB, uptimeMs, stateOversizedCount, codegraphBypassCount, degradedEditsCount, cacheHitCount, cacheMissCount, tokenSavingEstimate, sensitiveAccess, subagentFailedCount, discoveryCacheHitCount, redundantCallCount, cacheMissWithoutPutCount, stateCheckCount, toolCallCount`
@@ -56,6 +55,34 @@ Tras refino post-complete (archivo ya correcto, sin edición pendiente): `refres
 
 El plugin hace cumplir `PENDING` en `ctx.tool.hook("execute.before")`; `lastCheck={revision, result}` cachea ALLOW por revisión, revalida si cambia o >5 tools; `BLOCKED` nunca cacheado. Métricas `stateCheckCount` cuentan checks del plugin (no del LLM).
 
+## Gate de CodeGraph (alcance real)
+
+Cubre `read`/`grep`/`glob`/`read_mcp_resource` y **`shell`** cuando el comando revela contenido (`cat`, `head`, `tail`, `sed` sin `-i`, `grep`, `rg`, `awk`, `diff`…). Predicado puro: `shellReadTargets(command)` devuelve los paths de código **revelados**, no los mencionados — `bun test x.ts`, `tsc src/x.ts` y `git diff` pasan.
+
+**Fail-open:** redirección a archivo (`>`/`>>` a path), `sed -i` y verbo fuera de la allowlist → se permite. `read` falla cerrado porque es inequívoco; `shell` no, y un falso positivo rompe tests/builds sin escape hatch. Los redirects de stderr (`2>&1`, `1>&2`, `2>/dev/null`) NO cuentan como escritura (mismo criterio que `isShellMutation`): `cat src/x.ts 2>&1` sigue gateado.
+
+**Exenciones `isShellPathExempt(p, directory, freshState)`:** paths FUERA del projectRoot (fixtures temporales, reportes generados — `cat /tmp/out.ts` nunca bloquea), specs/docs (openspec, `assets/docs`, `.md`, `.json`) y archivos ya trackeados en tasks/fileFingerprints/lastValidated.
+
+**No es un sandbox.** Bypass residual por diseño: `git show`, `python -c`, `node -e`, `find -exec`, `xargs`, `base64`. El objetivo es quitar el bypass casual (`cat src/x.ts`, incluida su variante `cat src/x.ts 2>&1`), no probar imposibilidad.
+
+`execute` (Code Mode) **no** se gatea: su catálogo no expone `read`/`grep`/`shell` ni filesystem. Si una versión futura lo expone, el gate debe extenderse.
+
+**Evidencia válida de discovery:** únicamente un `codegraph_codegraph_explore` COMPLETADO en esta sesión (`discoveryHitByRequest`, memo limpiado con `session.deleted`). No hay fallback a cache en disco (el legado `getDiscoveryCacheHit` se retiró con discovery-cache).
+
+## Evidencia de ejecución (`test:`)
+
+`test:<cmd>` no se puede verificar sin ejecutar. El plugin observa cada `shell` pero **sólo persiste** `{cmd, exit, ts}` cuando el comando matchea un `test:` declarado en `taskVerifications` (D10: `git`/`ls`/`builds` no son evidencia; cada persist cuesta lock + re-read + write + backups). `complete_task` exige comando exacto (trim), `exit 0` y `ts` posterior a `lastMutationTs` (que avanza en cada `edit`/`write`/`patch` completado y en cada `shell` que escribe con exit 0: `cp`, `mv`, `rm`, `sed -i`, `tee`, redirección). `verifyIntegrity` re-verifica en el cierre: una edición posterior vence la evidencia y bloquea.
+
+**Fail-closed en orden de operaciones:** si el test corre antes de `record_execution_analysis` (que carga `taskVerifications` en el state), el plugin no lo registra como evidencia → `complete_task` pide re-correr con razón explícita. El orden correcto es analysis → tests → complete.
+
+**No se usa `status`:** en OpenCode 2.0.32, `sh -c 'exit 3'` llega con `status: "completed"` y `result.metadata.status: "completed"`. El único campo veraz es `result.metadata.exit`.
+
+**Límites declarados:** un test débil pasa (semántica, no mecánica); sin el plugin no hay `shellRuns` y `test:` falla cerrado.
+
+## Force gate (human confirmation, D4)
+
+`implementation_complete({force:true})` exige una frase del USUARIO (`/forzar|confirmo|force/i`) en `lastUserPrompts` — no en el audit, que redacta el agente. El plugin registra cada prompt con `{text, ts}` antes de inyectar hints. Cada rechazo del gate setea `lastForceAttemptTs`: sólo cuenta una frase con `ts` POSTERIOR al último intento (un "¿qué hace force:true?" previo no habilita). Prompts legacy sin `ts` (formato viejo en disco) pasan sólo si nunca hubo intento registrado.
+
 ## Tiered Behaviour
 
 `isTrivial(msg,state) = state==DONE && msg.trim().length<30 && /^(hola|hey|gracias|buenas|hi|hello)\b/i.test(msg) && !/(necesito|quiero|agregá|fix|bug|feature|auth|spec|implementar)/i.test(msg)`
@@ -86,4 +113,12 @@ Principio: **eficacia > recorte** — si recorte rompiera caché y saliera más
 
 ## Propose Flow (1+)
 
-`openspec-propose` SHALL Paso 0: `getDiscoverySnapshot(query)` + `getEngramDedup` → si miss `codegraph_codegraph_explore` + `engram_mem_search` + `putDiscoverySnapshot` **antes** de `openspec new`. Cita símbolos existentes en `proposal/design`; sin esto dispara `WARN:codegraphBypass` y `design.md` alucina API. Ver `assets/skills/openspec-propose/SKILL.md: Paso 0` y `brainstorming` (router por nivel: `brainstorming` decide 0/0+1/1+, `openspec-explore` es stance sin nivel).
+`openspec-propose` SHALL Paso 0: `codegraph_codegraph_explore` + `engram_mem_search` sobre el área (si no se hicieron ya en el request) **antes** de `openspec new`. Citá símbolos existentes en `proposal/design`; sin esto dispara `WARN:codegraphBypass` y `design.md` alucina API. Ver `assets/skills/openspec-propose/SKILL.md: Paso 0` y `brainstorming` (router por nivel: `brainstorming` decide 0/0+1/1+, `openspec-explore` es stance sin nivel).
+
+## CI — openspec validate (remediación)
+
+El job `test` de `.github/workflows/ci.yml` corre `bunx openspec validate --all --strict` (dep pinneada en `package.json`). Si falla en `main`: un delta/spec inválido entró — NO archivearlo roto ni hacer workaround. Protocolo:
+1. El output lista el item roto (`✗ change/<id>` / `✗ spec/<name>`) + `Details: openspec validate <id> --type change|spec` — ese comando da la causa exacta y los next steps (el CLI es autoexplicativo: headers `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`, cada requirement con al menos un `#### Scenario:`).
+2. Debug de deltas parseados: `openspec show <id> --json --deltas-only`.
+3. Change WIP incompleto en `main` → completarlo o removerlo del repo; specs de `openspec/specs/` rotos → fixear el formato in-place.
+4. Si tocás `assets/` regenerá hashes (`bun run scripts/update-manifest-hashes.ts`) y usá `bun run test:safe` (nunca `bun test` full: se cuelga).