ostacky 0.7.3 → 0.8.0

package/assets/docs/engram-protocol.md

@@ -0,0 +1,79 @@
+# Engram Persistent Memory — Protocol (on-demand)
+
+Este archivo NO se inyecta en el prompt. Se lee con `Read assets/docs/engram-protocol.md` cuando el agente necesita detalles de `mem_save`/`mem_search`.
+
+> Fuente: `assets/plugins/engram.ts` `MEMORY_INSTRUCTIONS` — movido a lazy para ahorrar ~1.2k tokens en FULL.
+
+## WHEN TO SAVE (mandatory — not optional)
+
+Call `mem_save` IMMEDIATELY after any of these:
+- Bug fix completed
+- Architecture or design decision made
+- Non-obvious discovery about the codebase
+- Configuration change or environment setup
+- Pattern established (naming, structure, convention)
+- User preference or constraint learned
+
+Format for `mem_save`:
+- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
+- **type**: bugfix | decision | architecture | discovery | pattern | config | preference
+- **scope**: `project` (default) | `personal`
+- **topic_key** (optional, recommended for evolving decisions): stable key like `architecture/auth-model`
+- **content**:
+  **What**: One sentence — what was done
+  **Why**: What motivated it (user request, bug, performance, etc.)
+  **Where**: Files or paths affected
+  **Learned**: Gotchas, edge cases, things that surprised you (omit if none)
+
+Topic rules:
+- Different topics must not overwrite each other (e.g. architecture vs bugfix)
+- Reuse the same `topic_key` to update an evolving topic instead of creating new observations
+- If unsure about the key, call `mem_suggest_topic_key` first and then reuse it
+- Use `mem_update` when you have an exact observation ID to correct
+
+## WHEN TO SEARCH MEMORY
+
+When the user asks to recall something — any variation of "remember", "recall", "what did we do",
+"how did we solve", or the equivalent in the user's language, or references to past work:
+1. First call `mem_context` — checks recent session history (fast, cheap)
+2. If not found, call `mem_search` with relevant keywords (FTS5 full-text search)
+3. If you find a match, use `mem_get_observation` for full untruncated content
+
+Also search memory PROACTIVELY when:
+- Starting work on something that might have been done before
+- The user mentions a topic you have no context on — check if past sessions covered it
+- The user's FIRST message references the project, a feature, or a problem — call `mem_search` with keywords from their message to check for prior work before responding
+
+## SESSION CLOSE PROTOCOL (mandatory)
+
+Before ending a session or saying "done" / "that's it", you MUST:
+1. Call `mem_session_summary` with this structure:
+
+## Goal
+[What we were working on this session]
+
+## Instructions
+[User preferences or constraints discovered — skip if none]
+
+## Discoveries
+- [Technical findings, gotchas, non-obvious learnings]
+
+## Accomplished
+- [Completed items with key details]
+
+## Next Steps
+- [What remains to be done — for the next session]
+
+## Relevant Files
+- path/to/file — [what it does or what changed]
+
+This is NOT optional. If you skip this, the next session starts blind.
+
+## AFTER COMPACTION
+
+If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:
+1. IMMEDIATELY call `mem_session_summary` with the compacted summary content — this persists what was done before compaction
+2. Then call `mem_context` to recover any additional context from previous sessions
+3. Only THEN continue working
+
+Do not skip step 1. Without it, everything done before compaction is lost from memory.

package/assets/docs/ostacky-reference.md

@@ -0,0 +1,79 @@
+# Ostacky Reference — Detalle no crítico para prompt
+
+Este archivo NO se inyecta en el prompt. Se lee on-demand con `Read assets/docs/ostacky-reference.md` cuando el LLM necesita detalle exacto.
+
+## TRANSITIONS (controller)
+
+```
+INTERPRETATION_PENDING: request_clarification→CLARIFICATION_PENDING, proceed_to_discovery→DISCOVERY, record_discovery→ROUTE_DECISION_PENDING, block→BLOCKED
+CLARIFICATION_PENDING: record_clarification→DISCOVERY, block→BLOCKED, abandon→BLOCKED
+DISCOVERY: record_discovery→ROUTE_DECISION_PENDING, block→BLOCKED, abandon→BLOCKED
+ROUTE_DECISION_PENDING: consume_route_decision(SPEC→SPECIFICATION, DIRECT→EXECUTION_ANALYSIS), block→BLOCKED
+SPECIFICATION: spec_complete→EXECUTION_ANALYSIS, block→BLOCKED
+EXECUTION_ANALYSIS: record_execution_analysis→EXECUTION_DECISION_PENDING, block→BLOCKED
+EXECUTION_DECISION_PENDING: consume_execution_decision(INLINE→EXECUTING_INLINE, SUBAGENT→EXECUTING_SUBAGENTS), block→BLOCKED
+EXECUTING_INLINE/SUBAGENTS: implementation_complete→SYNC, block→BLOCKED (block preserva tasks, replan prohibido)
+SYNC: sync_complete→DONE
+BLOCKED: replan→INTERPRETATION_PENDING, abandon→DONE
+```
+
+`proceed_to_route` deprecated → no-op alias retorna `{deprecated:true, state:"ROUTE_DECISION_PENDING"}` (compat).
+
+## Retry / Timeouts
+
+| Tool | Timeout | Reintentos | Fallback |
+|------|---------|------------|----------|
+| codegraph_* | 10s | 1 | Engram → Read+Glob |
+| controller_* | 5s | 1 | degraded |
+| engram_* | 5s | 1 | sin memoria |
+| context7_* | 10s | 1 | sin docs |
+
+## 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.
+
+## 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`
+
+## BASH_SENSITIVE_RE
+
+```js
+/(?:^|[^a-zA-Z0-9_.-])(\.env(\b|[_.-])|\.secrets\b|\.pem\b|\.key\b|credentials\.json|\.aws\b|\.ssh\b|\.npmrc\b)/i
+```
+Allowlist: `.env.example/.template/.sample` nunca bloquea. `extractPathsFromBash` tokeniza `| ; && || > >> <`.
+
+## validate_edit contrato
+
+`content` requerido salvo `content:"hash:"+fastFingerprint` cuando `lastValidated.filePath==filePath && fingerprint==hash` y fingerprint coincide con disco → EDITABLE sin body. Hash stale → CONFLICT `stale fingerprint`.
+
+## Enforcement (plugin)
+
+El plugin hace cumplir `PENDING` en `tool.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).
+
+## 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)`
+
+- **Trivial + DONE**: `output.system[0]` permanece `FULL` diet cacheable (10% hit), plugin añade suffix hint `[PLUGIN HINT: Saludo trivial — responde breve sin tools]` y bloquea `mem_context`/`codegraph_*` con `SKIP`. Solo Engram pointer 1 línea, no `MEMORY_INSTRUCTIONS`.
+- **TIER1** (0/0+1 con intent): hint `TIER1` en suffix, `FULL` sigue cacheado, `DIRECT` sin `Alternatives`.
+- **FULL** (1+): sin hint, `FULL` con `MEMORY_INSTRUCTIONS` lazy (solo si `!isTrivial` o nudge >15m).
+
+Principio: **eficacia > recorte** — si recorte rompiera caché y saliera más caro, se prioriza mantener `FULL` estable.
+
+## Security single-source
+
+`src/security.ts` único origen de `SENSITIVE_DEFAULT`/`BASH_SENSITIVE_RE`/`isSensitive`/`extractPathsFromBash`; plugin y guard importan, no copian. `BASH_SENSITIVE_RE` arriba. `OSTACKY_SENSITIVE_PATTERNS` override.
+
+## Tiered single-source
+
+`src/tiered.ts` único origen de `isTrivial(msg,state)` + `getControllerState(dir)`. Ambos plugins importan lógica idéntica, no duplican regex. Ver `assets/plugins/ostacky-plugin.ts` y `assets/plugins/engram.ts`.
+
+## Prompt-efficiency
+
+- `ostacky.md` 109→72 líneas (diet estable cacheable). Tiered vía suffix, no reemplazo `system[0]`.
+- `controller` descriptions <150 chars
+- `context7` lazy: `enabled:false` default, trigger `docs|api|lib|Context7` habilita
+- `MEMORY_INSTRUCTIONS` lazy: siempre pointer (~1 línea) en `system.transform`; full vive en `assets/docs/engram-protocol.md` on-demand via `Read` (ahorro ~1.2k en FULL, trivial ya era pointer)