ostacky 0.8.2 → 0.8.3

package/README.md

@@ -110,16 +110,13 @@ Detecta automáticamente el directorio `.opencode/` del proyecto (o lo crea) y m
 ### Instalar todo
 
 ```bash
-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
+npx ostacky install                 # siempre local en <proyecto>/.opencode
+npx ostacky install --scope local   # <proyecto>/.opencode (único scope soportado)
 ```
 
-Descarga todos los agentes y commands definidos en el manifest y los escribe en `.opencode/` (scope `local`) o en `~/.config/opencode` (`global`). 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).
+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*`.
 
-> **Coherencia local/global:** aunque elijas `global`, los plugins y herramientas (`tools/` con CodeGraph/Engram) permanecen siempre en `<proyecto>/.opencode` local para el hard-gate por worktree. En global solo se escribe el scope global + un espejo local de plugins. Para stack completo por proyecto ejecutá `npx ostacky install --scope local` dentro de cada repo.
-> **Windows — dónde se instala realmente:** `global` es `%APPDATA%\opencode` (`C:\Users\<vos>\AppData\Roaming\opencode`), **no** `C:\Users\<vos>\.opencode`. 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á con `--scope local`; el log ahora muestra `projectRoot` y `toolsDir` explícitos para evitar confusión.
+> **Instalación siempre local:** 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.
 
 ### Agregar agentes o commands individualmente
 
@@ -151,10 +148,8 @@ Solo descarga los items que cambiaron de versión.
 ### Desinstalar
 
 ```bash
-npx ostacky uninstall                          # pregunta local vs global, luego qué borrar
+npx ostacky uninstall                          # qué borrar en <proyecto>/.opencode
 npx ostacky uninstall --scope local            # fuerza scope local
-npx ostacky uninstall --scope global           # fuerza scope global
-npx ostacky uninstall --scope auto             # auto
 ```
 
 **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.
@@ -164,7 +159,7 @@ npx ostacky uninstall --scope auto             # auto
 #### Desinstalar un agente puntual
 
 ```bash
-npx ostacky uninstall agent <nombre>           # también admite --scope local|global|auto
+npx ostacky uninstall agent <nombre>           # también admite --scope local
 npx ostacky uninstall agent                    # sin nombre → selector de instalados
 ```
 
@@ -177,7 +172,7 @@ npx ostacky uninstall agent ostacky
 #### Desinstalar un command puntual
 
 ```bash
-npx ostacky uninstall command <nombre>         # también admite --scope
+npx ostacky uninstall command <nombre>         # también admite --scope local
 npx ostacky uninstall command                  # sin nombre → selector
 ```
 
@@ -192,7 +187,7 @@ Si no especificás el nombre, el CLI te muestra un selector con los items instal
 #### Desinstalar todo el stack (tools + config)
 
 ```bash
-npx ostacky uninstall-stack                    # pregunta scope, limpia mcp.codegraph/engram de opencode.json + .codegraph/ + .opencode/tools/
+npx ostacky uninstall-stack                    # limpia mcp.codegraph/engram de opencode.json + .codegraph/ + .opencode/tools/
 npx ostacky uninstall-stack --scope local
 ```
 
@@ -251,37 +246,37 @@ Tras instalar (`--scope local`), el proyecto queda así:
 
 ```json
 {
-    "version": "0.8.2",
+    "version": "0.8.3",
     "lockedAt": "2025-01-01T00:00:00.000Z",
     "repo": "JaimeHoracio/Ostacky",
-    "tag": "v0.8.2",
+    "tag": "v0.8.3",
     "agents": {
         "ostacky": {
-            "version": "0.8.2",
+            "version": "0.8.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "abc123..."
         }
     },
     "commands": {
         "install-stack": {
-            "version": "0.8.2",
+            "version": "0.8.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "def456..."
         },
         "opsx-sync": {
-            "version": "0.8.2",
+            "version": "0.8.3",
             "installedAt": "2025-01-01T00:00:00.000Z",
             "sha256": "ghi789..."
         }
     },
     "skills": {
-        "brainstorming": { "version": "0.8.2", ... },
-        "execution-mode-evaluation": { "version": "0.8.2", ... },
-        "openspec-propose": { "version": "0.8.2", ... }
+        "brainstorming": { "version": "0.8.3", ... },
+        "execution-mode-evaluation": { "version": "0.8.3", ... },
+        "openspec-propose": { "version": "0.8.3", ... }
     },
     "mcpServers": {
-        "ostacky-controller": { "version": "0.8.2", ... },
-        "openspec": { "version": "0.8.2", ... }
+        "ostacky-controller": { "version": "0.8.3", ... },
+        "openspec": { "version": "0.8.3", ... }
     }
 }
 ```
@@ -313,7 +308,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.8.2`), nunca `main` — instalaciones reproducibles
+- Las URLs de descarga usan **tags de GitHub** (ej. `v0.8.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
@@ -370,7 +365,7 @@ CodeGraph está instalado en `.opencode/tools/codegraph/bin/codegraph` y se conf
 | `.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.8.2 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
+> **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.8.3 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
 
 ## Licencia
 

package/assets/agents/ostacky.md

@@ -1,12 +1,12 @@
 ---
 description: Orquestador principal — rutea por nivel, orquesta CodeGraph + OpenSpec + Superpowers.
 mode: primary
-version: 0.8.2
+version: 0.8.3
 ---
 
-Sos **Ostacky v0.8.2**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
+Sos **Ostacky v0.8.3**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
 
-> **Versión:** `0.8.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.8.2"** (o `v0.8.2` si te piden solo el número). No inventes otra versión.
+> **Versión:** `0.8.3` (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.8.3"** (o `v0.8.3` si te piden solo el número). No inventes otra versión.
 
 ## Reglas innegociables
 
@@ -18,6 +18,16 @@ Sos **Ostacky v0.8.2**, orquestás, no implementás. Interpretás, clasificás (
 
 > Ver `assets/docs/ostacky-reference.md` para TRANSITIONS, TTL y métricas. Tiered LITE/TIER1/FULL vía suffix hint.
 
+## Principios de honestidad (SHALL)
+
+1. **Engram contradiction check SHALL.** Antes de proponer o discutir cambios (Nivel 0+1/1+, eximido si `isTrivial && DONE`), SHALL `mem_search` por keywords del pedido (max 5 keywords = sustantivos del pedido + `topic_key` del change activo si lo hay); si hit `type:decision|architecture` con contradicción semántica (ej: pide Zustand y hay #571 “usar Redux por X”), SHALL mostrar diff `“Antes decidimos X el <fecha> por Z (topic_key), ahora pedís ¬X”`, llamar `request_clarification` y esperar. Si Engram `degraded`/timeout → SHALL advertir “sin memoria” y continuar (no block). Si usuario confirma override → SHALL `mem_save` mismo `topic_key` + `mem_compare supersedes` + `record_user_confirmation`.
+2. **Solo propuestas que ayudan SHALL.** Toda propuesta SHALL incluir `por qué ayuda + tradeoff + evidencia` (CodeGraph symbol, Engram hit) o literal `“no verificado”` + best practice 2026. No sugerir por sugerir.
+3. **Pocas honestas > muchas de relleno SHALL.** Si solo hay una opción honesta, dar una. Si hay 2-3, tabla `coste|riesgo|complejidad`. No inventar para llenar.
+4. **Si no hay propuesta honesta SHALL decirlo.** Literal: `“No hay propuesta honesta que aporte vs no hacer nada en este contexto.”`
+5. **Si dudás SHALL preguntar.** Ante ambigüedad aunque el pedido parezca claro, SHALL una pregunta clarificadora (una por turno, natural, sin tool, STOP) y esperar. No asumir.
+6. **Verificar antes de afirmar SHALL.** No acordar sin chequear código/docs. Citar evidencia o admitir `“no pude verificar en disco”`.
+7. **YAGNI scope SHALL.** No proponer refactor oportunista fuera del pedido; si lo ves, mencionar `“fuera de scope: …”` sin implementarlo.
+
 ## Stack
 
 - **Controller** (plugin `ostacky-plugin.ts`): state machine in-process, hard gates.
@@ -62,6 +72,11 @@ Preguntar nivel y `consume_route_decision`.
 
 Router `brainstorming`↔`OpenSpec` por `level`/`estLines`/`fileCount`/`hasAPI` (no keywords). `1+` no-downgradeable → `skill(brainstorming)` genera `design.md ## Alternatives`; downgradeable → `docs/...` + `DIRECT`.
 
+**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.
+- 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.

package/assets/commands/install-stack.md

@@ -5,13 +5,13 @@ 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.8.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.
+**Nota:** A partir de v0.8.3, `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.
 
 **Origen del set curado:** el set de 15 skills referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. 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.8.2)
+## Scope de instalación — local vs global (desde v0.8.3)
 
 `npx ostacky install` soporta `--scope local|global|auto` (también `--scope=...`):
 

package/assets/mcp/ostacky-controller/controller-core.js

@@ -0,0 +1,206 @@
+/**
+ * controller-core — Single source of truth para TRANSITIONS, STATES, DEFAULT_STATE y helpers.
+ * Extraído de assets/mcp/ostacky-controller/index.js y assets/plugins/ostacky-plugin.ts
+ * para eliminar duplicación (D1). Ambos importan de acá.
+ */
+
+import { SENSITIVE_DEFAULT } from "./security.js";
+
+// --- Constants (headroom generoso) ---
+export const MAX_TASKS = 100;
+export const MAX_TASKS_DEFAULT = 100;
+export const MAX_TASKS_CAP = 500;
+export const MAX_SNAPSHOT_JSON_LENGTH = 50 * 1024;
+export const MAX_STATE_FILE_SIZE = 2 * 1024 * 1024;
+export const DEGRADED_THRESHOLD = 3;
+
+export const STATES = Object.freeze({
+  INTERPRETATION_PENDING: "INTERPRETATION_PENDING",
+  CLARIFICATION_PENDING: "CLARIFICATION_PENDING",
+  DISCOVERY: "DISCOVERY",
+  ROUTE_DECISION_PENDING: "ROUTE_DECISION_PENDING",
+  SPECIFICATION: "SPECIFICATION",
+  EXECUTION_ANALYSIS: "EXECUTION_ANALYSIS",
+  EXECUTION_DECISION_PENDING: "EXECUTION_DECISION_PENDING",
+  EXECUTING_INLINE: "EXECUTING_INLINE",
+  EXECUTING_SUBAGENTS: "EXECUTING_SUBAGENTS",
+  SYNC: "SYNC",
+  DONE: "DONE",
+  BLOCKED: "BLOCKED",
+});
+
+export const TRANSITIONS = {
+  INTERPRETATION_PENDING: [
+    { via: "request_clarification", to: "CLARIFICATION_PENDING" },
+    { via: "proceed_to_discovery", to: "DISCOVERY" },
+    { via: "record_discovery", to: "ROUTE_DECISION_PENDING" },
+    { via: "block", to: "BLOCKED" },
+  ],
+  CLARIFICATION_PENDING: [
+    { via: "record_clarification", to: "DISCOVERY" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  DISCOVERY: [
+    { via: "record_discovery", to: "ROUTE_DECISION_PENDING" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  ROUTE_DECISION_PENDING: [
+    { via: "consume_route_decision", to: "SPECIFICATION", choice: "SPEC" },
+    { via: "consume_route_decision", to: "EXECUTION_ANALYSIS", choice: "DIRECT" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  SPECIFICATION: [
+    { via: "spec_complete", to: "EXECUTION_ANALYSIS" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  EXECUTION_ANALYSIS: [
+    { via: "record_execution_analysis", to: "EXECUTION_DECISION_PENDING" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  EXECUTION_DECISION_PENDING: [
+    { via: "consume_execution_decision", to: "EXECUTING_INLINE", mode: "INLINE" },
+    { via: "consume_execution_decision", to: "EXECUTING_SUBAGENTS", mode: "SUBAGENT_DRIVEN" },
+    { via: "block", to: "BLOCKED" },
+    { via: "abandon", to: "BLOCKED" },
+  ],
+  EXECUTING_INLINE: [
+    { via: "implementation_complete", to: "SYNC" },
+    { via: "block", to: "BLOCKED" },
+  ],
+  EXECUTING_SUBAGENTS: [
+    { via: "implementation_complete", to: "SYNC" },
+    { via: "block", to: "BLOCKED" },
+  ],
+  BLOCKED: [
+    { via: "replan", to: "INTERPRETATION_PENDING" },
+    { via: "abandon", to: "DONE" },
+  ],
+  SYNC: [
+    { via: "sync_complete", to: "DONE" },
+    { via: "block", to: "BLOCKED" },
+  ],
+  DONE: [],
+};
+
+export const TERMINAL_STATES = Object.freeze([
+  STATES.INTERPRETATION_PENDING,
+  STATES.CLARIFICATION_PENDING,
+  STATES.BLOCKED,
+  STATES.DONE,
+]);
+
+export const DEFAULT_STATE = {
+  state: STATES.INTERPRETATION_PENDING,
+  revision: 0,
+  requestId: null,
+  changeId: null,
+  routeDecisionId: null,
+  routeChoice: null,
+  level: null,
+  executionDecisionId: null,
+  executionMode: null,
+  snapshots: { codegraph: null, execution: null },
+  tasks: {},
+  fileFingerprints: {},
+  error: null,
+  lastHandoff: null,
+  expectedTasks: null,
+  expectedTaskCount: null,
+  auditSeq: 0,
+  degraded: false,
+  schemaVersion: 2,
+  stateOversizedCount: 0,
+  codegraphBypassCount: 0,
+  degradedEditsCount: 0,
+  cacheHitCount: 0,
+  cacheMissCount: 0,
+  tokenSavingEstimate: 0,
+  discoveryCacheHitCount: 0,
+  redundantCallCount: 0,
+  cacheMissWithoutPutCount: 0,
+  stateCheckCount: 0,
+  toolCallCount: 0,
+  lastProposal: null,
+  allowedFiles: {},
+  deniedFiles: {},
+  sensitivePatterns: [...SENSITIVE_DEFAULT],
+  sensitiveAccess: { allowed: 0, denied: 0, blockedAttempts: 0 },
+  staleContentAttempts: 0,
+  completeWithoutValidateCount: 0,
+  toolTimeoutCount: 0,
+  lastToolDurationMs: 0,
+  stateDurationMs: 0,
+  subagentFailedCount: 0,
+  lastValidated: null,
+  pendingFileAccess: {},
+  lastHeartbeat: 0,
+  watchdogEnabled: true,
+  ts: Date.now(),
+  specNotInSync: false,
+};
+
+export function safeJsonStringify(obj, pretty = false) {
+  const seen = new WeakSet();
+  try {
+    return JSON.stringify(
+      obj,
+      (key, value) => {
+        if (typeof value === "object" && value !== null) {
+          if (seen.has(value)) return "[Circular]";
+          seen.add(value);
+        }
+        return value;
+      },
+      pretty ? 2 : undefined
+    );
+  } catch (e) {
+    return `[Unstringifiable: ${e.message}]`;
+  }
+}
+
+const SENSITIVE_REDACT_RE = /(apiKey|secret|token|password|api_key)/i;
+
+export function redactForLog(data) {
+  if (!data || typeof data !== "object") return data;
+  try {
+    const str = safeJsonStringify(data);
+    if (SENSITIVE_REDACT_RE.test(str)) {
+      const copy = JSON.parse(str);
+      const redactRecursively = (obj) => {
+        if (!obj || typeof obj !== "object") return;
+        for (const k of Object.keys(obj)) {
+          if (SENSITIVE_REDACT_RE.test(k)) obj[k] = "[REDACTED]";
+          else if (typeof obj[k] === "object") redactRecursively(obj[k]);
+        }
+      };
+      redactRecursively(copy);
+      return copy;
+    }
+    return data;
+  } catch {
+    return data;
+  }
+}
+
+export function getMaxTasks() {
+  const raw = process.env.OSTACKY_MAX_TASKS;
+  if (raw == null || raw === "") return MAX_TASKS_DEFAULT;
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n <= 0) return MAX_TASKS_DEFAULT;
+  if (n > MAX_TASKS_CAP) return MAX_TASKS_CAP;
+  return n;
+}
+
+export function getAuditRetention() {
+  const raw = process.env.OSTACKY_AUDIT_RETENTION;
+  if (raw == null || raw === "") return 500;
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n <= 0) return 500;
+  if (n > 2000) return 2000;
+  return n;
+}