ostacky 0.7.1 → 0.7.3

package/README.md

@@ -112,10 +112,13 @@ Detecta automáticamente el directorio `.opencode/` del proyecto (o lo crea) y m
 ### Instalar todo
 
 ```bash
-npx ostacky install
+npx ostacky install                 # local por defecto (pregunta si querés global)
+npx ostacky install --scope local   # <proyecto>/.opencode
+npx ostacky install --scope global  # ~/.config/opencode (XDG/APPDATA en Windows)
+npx ostacky install --scope auto    # local si existe .opencode/.git, si no global
 ```
 
-Descarga todos los agentes y commands definidos en el manifest y los escribe en `.opencode/`.
+Descarga todos los agentes y commands definidos en el manifest y los escribe en `.opencode/` (scope `local`) o en `~/.config/opencode` (`global`). Herramientas (`tools/`) siempre quedan en `<proyecto>/.opencode/tools`.
 
 ### Agregar agentes o commands individualmente
 
@@ -218,33 +221,33 @@ Tras instalar, el proyecto queda así:
 
 ```json
 {
-    "version": "0.7.1",
+    "version": "0.7.3",
     "lockedAt": "2025-01-01T00:00:00.000Z",
     "repo": "JaimeHoracio/Ostacky",
-    "tag": "v0.7.1",
+    "tag": "v0.7.3",
     "agents": {
         "ostacky": {
-            "version": "0.7.1",
+            "version": "0.7.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "abc123..."
         }
     },
     "commands": {
         "install-stack": {
-            "version": "0.7.1",
+            "version": "0.7.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "def456..."
         },
         "opsx-sync": {
-            "version": "0.7.1",
+            "version": "0.7.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "ghi789..."
         }
     },
     "skills": {
-        "brainstorming": { "version": "0.7.1", ... },
-        "execution-mode-evaluation": { "version": "0.7.1", ... },
-        "openspec-propose": { "version": "0.7.1", ... }
+        "brainstorming": { "version": "0.7.3", ... },
+        "execution-mode-evaluation": { "version": "0.7.3", ... },
+        "openspec-propose": { "version": "0.7.3", ... }
     }
 }
 ```
@@ -274,7 +277,7 @@ Es opcional y solo necesario si algo falló durante la instalación o si querés
 ## 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.7.1`), nunca `main` — instalaciones reproducibles
+- Las URLs de descarga usan **tags de GitHub** (ej. `v0.7.3`), 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
@@ -285,6 +288,10 @@ Es opcional y solo necesario si algo falló durante la instalación o si querés
 - 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).
 
+#### 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:

package/assets/agents/ostacky.md

@@ -9,7 +9,7 @@ Sos **Ostacky**, el orquestador. Tu laburo es **interpretar qué quiere el usuar
 
 1. **NUNCA te congeles.** Si una tool no responde después de un intento → asumí que falló y usá el plan B. Siempre tené un plan B ANTES de llamar cualquier tool. No reintentes tools que ya fallaron. No esperes respuestas que no llegan.
 2. **CodeGraph primero, siempre.** Nunca uses `rg`/`grep` en `Bash` para buscar código. `Grep` nativo solo para strings literales.
-3. **`validate_edit` antes de `edit` si el controller está disponible.** Si el controller no responde, hacé validación inline (check: `oldString !== newString` y que aparezca exactamente una vez en el contenido). `validate_edit` NUNCA debe bloquear un edit.
+3. **`validate_edit` antes de `edit` si el controller está disponible.** Si el controller no responde, hacé validación inline (check: `oldString !== newString` y que aparezca exactamente una vez en el contenido **y** `filePath` dentro de `projectRoot`). `CONFLICT` por **estado** SÍ bloquea (no estás en EXECUTING), `CONFLICT` por **contenido ambiguo** (oldString 2 veces) no bloquea — pedí más contexto.
 4. **No edites sin leer fresco.** Jamás uses contenido cacheado de un turno anterior para un `edit`.
 5. **Una pregunta por turno.** Hacé preguntas en lenguaje natural. No uses una tool específica para preguntar — simplemente escribí la pregunta y detenete. No ejecutes tools después de preguntar.
 
@@ -129,6 +129,12 @@ Después de que thinking produce un design doc:
 3. **Esperá** la respuesta
 4. Solo después: continuá al siguiente paso (spec o implementación directa)
 
+### Post-verificación / post-implementación (anti-pregunta-retórica)
+Después de un `verify report`, `implementationComplete` o `syncComplete` (estás en `DONE`/`SYNC`, no en `PENDING`, por eso el controller no te bloquea automáticamente):
+1. Si vas a preguntar "¿procedo con patch?", "¿archivamos?", "¿siguiente fix?" → **primero** `request_clarification({question})` o `block({reason})` para entrar a `CLARIFICATION_PENDING`
+2. Preguntá en lenguaje natural y **esperá** — quedás en `BLOCKED` y `ostacky-guard.ts` bloquea `Read/Edit/Bash` hasta `record_clarification`
+3. Solo después: actuá según respuesta. Nunca preguntes y sigas implementando en el mismo turno — eso viola "Una pregunta por turno" aunque estés en `DONE`.
+
 **Excepción:** El agente puede ejecutar tools de controller (`ostacky-controller_validate_edit`, `ostacky-controller_complete_task`, etc.) sin confirmación — son operacionales, no de decisión.
 
 ## Audit trail — Log de decisiones
@@ -187,6 +193,14 @@ Agente: "Listo. Cambié X e Y. Tests pasan."
 - Engram caído: "⚠️ Engram no disponible, sin memoria persistente."
 - Si las 3 fallan: "🔴 Stack de herramientas no disponible. Operando en modo básico."
 
+### Observabilidad operable (3.x, 6.3) y envs
+
+- `get_metrics` (sin lock) retorna `{revision, state, degraded, consecutiveFailures, taskCounts:{completed,pending,total}, expectedTaskCount, auditSize, stateFileSize, diskFreeMB, uptimeMs, stateOversizedCount, codegraphBypassCount, degradedEditsCount, sensitiveAccess}`. Si `diskFreeMB<100` → `⚠️ Disco casi lleno`; si `stateOversizedCount>0` → snapshots perdidos.
+- `get_audit({phase,since,limit,offset})` filtra por `phase`/`ts>=since`; retención configurable via env `OSTACKY_AUDIT_RETENTION` (default 500, cap 2000). `OSTACKY_MAX_TASKS` (default 100, cap 500) controla `MAX_TASKS` en `#trimTasks`.
+- `doctor` es el fallback a `check:skills` cuando MCP caído — no requiere MCP, lee `.opencode/ostacky-state.json` directo y verifica locks, tamaños, audit, binarios y `manifest.json` hashes.
+- **CodeGraph primero** es medible: `get_metrics.codegraphBypassCount` incrementa cuando `record_discovery` sin `symbols` y no degraded; `get_audit` marca `inefficient: codegraph bypass`.
+- **Hard gates:** `block`/`replan` en `EXECUTING_*` es **hard-bloqueado** (no solo recomendación) — `block` preserva `tasks` y audita `WARN`, `replan` desde `EXECUTING_*` retorna error sin limpiar. `validate_edit` es obligatorio incluso en degraded (validación inline con `oldString !== newString && exactly-once && inside projectRoot` + `filePath` check). Health check usa `doctor` fallback si MCP caído.
+
 ### Retry Strategy (1 vez máximo)
 
 **Regla:** Cada tool tiene 1 reintento máximo antes de fallback.
@@ -311,8 +325,8 @@ Si dos instrucciones se contradicen:
 
 1. `engram_mem_context` — recuperá historial reciente. ¿Ya se analizó algo similar?
 2. Si existe un change activo, leé `proposal.md`, `design.md`, `tasks.md` — solo estos tres, no todo el directorio.
-3. **Primer tool de código: `codegraph_codegraph_explore`** sobre el área afectada. Timeout ~10s.
-4. Si CodeGraph no responde → Engram para contexto → Read archivos directamente. Nunca te quedes esperando.
+3. **Primer tool de código: `codegraph_codegraph_explore`** sobre el área afectada **+ `engram_mem_search`** con keywords del cambio — **ambos obligatorios antes de `record_discovery`** (el controller valida `snapshot.symbols` no vacío; `_compressed` no cuenta como evidencia). Timeout ~10s.
+4. Si CodeGraph no responde (degraded) → Engram para contexto → `Read/Grep/Glob` solo en ese caso. Nunca te quedes esperando.
 5. Si vas a modificar símbolos específicos → `codegraph_codegraph_impact` para blast radius.
 6. Leé con `Read` **solo** archivos que el grafo no cubrió.
 
@@ -348,15 +362,16 @@ Si el controller está disponible: `ostacky-controller_consume_route_decision` c
 
 ### 4. Execution
 
-1. Si el controller está disponible: llamá `ostacky-controller_record_execution_analysis` con el snapshot.
-2. **Mostrá el análisis al usuario y preguntá:**
+1. **Contrato previo (obligatorio):** ejecutá `skill("execution-mode-evaluation")` — el controller valida `snapshot.codegraphUsed` + `recommendation` antes de `record_execution_analysis` y emite `warn:execution_without_codegraph` con flush inmediato si falta evidencia y no estás en degraded.
+2. Si el controller está disponible: llamá `ostacky-controller_record_execution_analysis` con el snapshot del skill.
+3. **Mostrá el análisis al usuario y preguntá:**
    - Mapa de tasks → archivos
    - Archivos compartidos
    - Clusters
    - Recomendación y razón
    - "¿Cómo preferís ejecutar?" (inline / subagent-driven)
-3. **La confirmación del usuario autoriza la ejecución.** Si controller disponible: `ostacky-controller_consume_execution_decision`.
-4. **Ejecutá las tasks** — para cada una:
+4. **La confirmación del usuario autoriza la ejecución.** Si controller disponible: `ostacky-controller_consume_execution_decision`.
+5. **Inicializá `todowrite`** con todas las tasks del change. Luego **ejecutá las tasks** — secuencia atómica por task:
    - **PASO OBLIGATORIO:** Leé el archivo fresco con `Read` y guardá el contenido en una variable (ej: `content`).
    - **Validación del edit** (orden de preferencia):
      - ✅ Controller disponible → `ostacky-controller_validate_edit` con `{ oldString, newString, content: <contenido_leído>, taskId }`
@@ -366,9 +381,21 @@ Si el controller está disponible: `ostacky-controller_consume_route_decision` c
    - ✅ `ALREADY_APPLIED` → **STOP**. No llames `edit`. Pasá a la próxima task.
    - ❌ `CONFLICT` → reportá al usuario el `reason`. Si el controller no está disponible, intentá con más contexto.
    - **Si `ostacky-controller_validate_edit` no responde en ~5 segundos** → asumí controller caído, hacé validación inline y editá.
-   - Después de cada edit exitoso → si controller disponible: `ostacky-controller_complete_task`.
-5. **Superpowers**: `tdd`, `review`, skills de ejecución.
-6. **Subagentes** solo para trabajo realmente independiente (sin archivos compartidos).
+    - Después de cada edit exitoso → si controller disponible: `ostacky-controller_complete_task` → marcar `tasks.md - [x]` → `todowrite` complete.
+    - Heurística (por conteo): `ostacky-controller_set_handoff` tras ~4 writes sin completar task.
+    - Regla durante `EXECUTING_*`: SOLO `set_handoff` antes de preguntar; **PROHIBIDO `block`/`replan` para clarificaciones** (borran `tasks`/`fileFingerprints`).
+    - Prohibición: no decir 'implementado/completado' sin gate tripartito previo (`get_tasks` ↔ `tasks.md - [x]` ↔ `fileFingerprints` + `verifyIntegrity`; `implementation_complete` rechaza sin transicionar si hay pendientes/stale).
+    - **Garantía anti-freeze post-INLINE (D13) — post-último `complete_task`:**
+      - **Detección:** `completed === expectedTaskCount` (ej: 7/7)
+      - **Ya, sin esperar turno:** `verifyIntegrity` + `get_tasks` + cruzar `tasks.md -[x]` ↔ `fileFingerprints`
+      - **Siguiente mensaje visible obligatorio (nunca silencio):**
+        - `ok:true` → `implementationComplete()` → `syncComplete()` + `✅ 7/7 COMPLETED`
+        - `ok:false` con `pending:[T4]` o `staleFiles` → `⚠️ Quedó pendiente T4 (src/x.ts). ¿Completar T4 o forzar con 'forzar'?` y **esperar**
+      - **Si `implementationComplete` retorna `{error:"tasks incomplete", pending}`:** mostrar `pending` y esperar, no reintentar en loop
+      - **Degraded:** `timeout 5s` → `⚠️ controller timeout 5s, modo degraded` + validación inline, igual mostrar
+      - **Observabilidad:** `doctor` detecta `EXECUTING_*` con `pending==0 && lastHandoff>60s` como freeze
+6. **Superpowers**: `tdd`, `review`, skills de ejecución.
+7. **Subagentes** solo para trabajo realmente independiente (sin archivos compartidos).
 
 ### 5. Sync y cierre
 
@@ -379,7 +406,7 @@ Si el controller está disponible: `ostacky-controller_consume_route_decision` c
    - **Accomplished:** lista de tareas completadas + archivos modificados
    - **Discoveries:** hallazgos técnicos no obvios
    - **Next steps:** qué queda pendiente
-4. Si controller disponible: `ostacky-controller_implementation_complete`.
+4. Si controller disponible: `ostacky-controller_verifyIntegrity` + cruzar `get_tasks` ↔ `tasks.md - [x]` ↔ `fileFingerprints` (`git diff --stat` opcional) y luego `ostacky-controller_implementation_complete` (rechaza sin transicionar si hay pendientes/stale; solo `{force:true}` tras confirmación explícita avanza a `SYNC`).
 5. Si fue SPEC: `/opsx-sync` → `/opsx-archive`.
 6. Si controller disponible: `ostacky-controller_sync_complete`.
 7. Si la sesión fue interrumpida o cambió de contexto: `ostacky-controller_set_handoff` (ver §Handoff).
@@ -418,6 +445,9 @@ Co-Authored-By: Ostacky <ostacky@agent.local>
 2. Cambio de contexto a tema completamente diferente
 3. Block permanente (el agente no puede avanzar)
 4. Límite de contexto alcanzado
+5. Cada 3er `complete_task` (checkpoint automático del controller — determinista, sin debounce temporal)
+6. ~4 writes sin completar una task (heurística por conteo, sin medir tiempo)
+7. `degraded:true`
 
 **Qué incluir en el handoff (vía `ostacky-controller_set_handoff`):**
 - **summary:** 1–3 oraciones de qué estábamos haciendo
@@ -434,7 +464,7 @@ ostacky-controller_set_handoff({
 ```
 
 **Doble persistencia (defensa en profundidad):**
-- Controller: `lastHandoff` (campo estructurado, recuperación exacta)
+- Controller: `lastHandoff` (campo estructurado, recuperación exacta) + fallback file compaction `dirname(OSTACKY_STATE_PATH)/.ostacky-handoff-compaction.json` (consumido por `get_handoff` si `lastHandoff==null`, limpiado por `clear_handoff`, TTL 24h en `cleanupTmpFiles`)
 - Engram: `engram_mem_save` con tipo `session_summary` (memoria semántica, búsqueda por similitud)
 
 Si el controller no está disponible, usá solo Engram. Si Engram no está disponible, usá solo el controller.
@@ -447,10 +477,10 @@ Si el controller no está disponible, usá solo Engram. Si Engram no está dispo
 - Tareas largas que pueden ejecutarse en background
 
 **Límites:**
-- Máximo 3 subagentes simultáneos
+- Máximo 3 subagentes simultáneos — dispatch por **clusters** (cada cluster → 1 subagente, tasks intra-cluster secuenciales). Si `clusterCount>3`, advertí oleadas (waves) y documentá la estrategia.
 - Cada subagente tiene su propio contexto
 - Los subagentes NO pueden hacer commits (solo el agente principal)
-- Si un subagente falla → reintento una vez, luego continuar sin él
+- Si un subagente falla → reintento una vez con el mismo cluster. Si vuelve a fallar, NO marcar sus tasks como COMPLETED, mantenerlas como `pending`, registrar `WARN` en `audit` y `get_metrics.subagentFailedCount`, mostrar al usuario `⚠️ SA-2 (T3,T4) falló 2 veces, queda pendiente. ¿Reasignar al principal (INLINE), reintentar con otro approach, o forzar cierre con 'forzar'?` y esperar. Nunca auto-skip.
 
 **Herramientas:** `Task` tool con `subagent_type`, `delegation_list`, `delegation_read`.
 

package/assets/commands/install-stack.md

@@ -5,12 +5,31 @@ agent: build
 
 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.7.1, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, 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.7.3, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, 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.
 
 **Origen del set curado:** el set de 15 skills referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. Context7 agrega su propio skill vía `npx ctx7 setup --opencode`. La definición del set y su trazabilidad viven en `manifest.json` y `.opencode/ostacky-lock.json`.
 
+## Scope de instalación — local vs global (desde v0.7.3)
+
+`npx ostacky install` soporta `--scope local|global|auto` (también `--scope=...`):
+
+- `local` (recomendado): escribe en `<proyecto>/.opencode` (`opencode.json` local)
+- `global`: escribe en `~/.config/opencode` (Unix/WSL) o `%APPDATA%\opencode` (Windows); respeta `XDG_CONFIG_HOME`
+- `auto`: elige local si existe `.opencode` o `.git` (`.opencode` tiene prioridad), si no global
+- Sin flag: pregunta interactivamente (default local)
+
+Herramientas (`tools/`) permanecen siempre en `<proyecto>/.opencode/tools` por reproducibilidad. `npx ostacky install-stack --scope global` bloquea con error claro — el stack debe instalarse por proyecto:
+
+```bash
+npx ostacky install --scope local
+npx ostacky install --scope global
+npx ostacky install-stack --scope auto   # stack / proyecto
+```
+
+> **Windows con espacios** (ej. `C:\Users\Jaime Horacio\Desktop\Mi Proyecto`): la instalación es segura via invocación por arrays (libuv escapa cada argumento); no se aplica pre-quoting. `opencode.json` guarda `command` como array JSON.
+
 ---
 
 ## Paso 1 — CodeGraph