pantheon-opencode 1.6.0-beta.6 → 1.6.0-beta.7

package/src/instructions/zeus-anti-stall.instructions.md

@@ -1,116 +1,13 @@
 ---
-description: "Stall detection, phase reminders, delegate retry, and progress checkpoints for Zeus"
+description: "Minimal stall recovery and progress guidance for Zeus"
 name: "Zeus Anti-Stall"
-applyTo: "agents/zeus.agent.md"
+agents: [zeus]
+fallback: shared
 ---
 
-# 🛑 ANTI-STALL & STALL DETECTION
+# Stall recovery
 
-You MUST proactively detect and recover from stalled states. Do NOT wait for user intervention when the system is idling or looping without progress.
-
-## Stall Detection Protocol
-
-You MUST self-monitor for these stall conditions:
-
-| Symptom | Detection Rule | Recovery Action |
-|---------|---------------|-----------------|
-| Silent loop | 3+ consecutive turns with no tool call AND no visible progress | Output `[STALL_DETECTED]` and re-read your task definition. If still stuck, escalate to user with: "I appear to be stuck on [task]. Options: (1) retry with different approach, (2) delegate to specialist, (3) simplify scope." |
-| Delegation black hole | Agent dispatched but no response after 2x the timeout from routing.yml | Log the hang, cancel via `cancel_task`, then follow the fallback chain in `## ⏱️ Timeout & Retry Enforcement` |
-| Circular delegation | Same specialist re-dispatched for same task 2+ times without progress | Break cycle: dispatch to different specialist OR escalate to user |
-| Idle after completion | All background tasks completed but no synthesis/next step for 2+ turns | Force synthesis: summarize all completed results and propose next action |
-| Context thrash | Re-reading same files repeatedly without new action | Stop re-reading. State: "Already have context on [file]. Proceeding with [action]." |
-
-## Phase Reminder
-
-After dispatching background specialists, you MUST:
-1. DO NOT poll running jobs or consume their partial output
-2. DO NOT advance dependent work until terminal results arrive
-3. Continue orchestration ONLY on non-overlapping independent work
-4. If nothing independent remains, briefly report what was launched and WAIT
-
-Self-check every 3 turns: "Am I waiting on a delegate? Have I polled without need? Is there independent work I can do?"
-
-## Delegate Retry Enhancement
-
-When a delegation fails (timeout, empty response, error):
-
-1. **FIRST:** Check if the error is a known pattern:
-   - "Agent not responding" → verify agent name matches routing.yml
-   - "Context exceeded" → reduce scope, split into smaller tasks
-   - "Permission denied" → verify agent has correct tools/permissions
-
-2. **Retry ONCE** with rephrased prompt — add: "Previous attempt failed with: [error]. Adjusted approach: [what changed]."
-
-3. **If retry also fails** → do NOT retry blindly; follow the fallback chain and escalation protocol in `## ⏱️ Timeout & Retry Enforcement`.
-
-## Progress Checkpoint
-
-On tasks expected to run > 5 turns:
-- After turn 5: output `[CHECKPOINT] Completed so far: [summary]. Remaining: [list].`
-- After turn 10: re-evaluate. If < 50% done, consider splitting or escalating.
-- If 3 consecutive turns produce no tool calls: trigger Stall Detection Protocol (see above).
-
-## Heartbeat & Checkpoint Integration
-
-All session state lives in **pantheon-persistence** (namespace `checkpoint:<slug>`).
-No file I/O, no checkpoint_session.py — TTL (4h) handles cleanup automatically.
-
-### Heartbeat Check
-- If `context_get(slug=slug, key="heartbeat", session_id=SESSION_ID)` returns a checkin older than 300s, log a stall warning and resume
-- Write heartbeat after every anti-stall recovery action:
-  ```
-  context_save(slug=slug, key="heartbeat", content=JSON.stringify({"status": "alive", "last_action": "...", "turn_count": N}), session_id=SESSION_ID)
-  ```
-
-### Checkpoint Auto-Save (Pré-Compactação)
-Before ANY delegate dispatch, save a checkpoint:
-```
-context_save(slug=slug, key="phase:N", content=JSON.stringify({
-  "phase": {"current": N, "total": M, "name": "..."},
-  "turn_count": N, "agent": "...", "summary": "..."
-}), session_id=SESSION_ID)
-```
-**`content.phase` must be an OBJECT, not a bare number.** `{"phase": 1}` is rejected with
-`context_save: content.phase must be an object (got number)`. The server reads `current`
-and `total` (non-negative ints) and `name` (string, max 256 **bytes** — the guard
-measures `len(value.encode())`, so multi-byte characters count as more than one). That
-set is not closed: any other key inside `phase` is accepted and ignored, never an
-error. The `"phase:N"` slot KEY above is unrelated to `content.phase` and stays a plain
-string.
-All checkpoints auto-expire after 4h (TTL=14400).
-
-### Gatilho de Pré-Compactação (Anti-perda de estado)
-Antes da compactação nativa do OpenCode disparar (75-96% do context window),
-o Zeus DEVE salvar o estado atual:
-1. Capture session_id do primeiro `context_save` da sessão
-2. Salve heartbeat + phase atual + tarefas pendentes
-3. Só então permita que a compactação prossiga
-```
-# Ao iniciar sessão (session_id é REQUIRED — use o id da sessão corrente):
-result = context_save(slug=slug, key="init", content=JSON.stringify(session_state), session_id=SESSION_ID)
-SESSION_ID = result.session_id   # ← guarde para toda a sessão
-
-# Antes de CADA delegação:
-context_save(slug=slug, key=f"pre:{agent}", content=JSON.stringify(current_state), session_id=SESSION_ID)
-
-# Após retorno do agente:
-context_save(slug=slug, key=f"post:{agent}", content=JSON.stringify(result_state), session_id=SESSION_ID)
-```
-Isso garante que o estado sobreviva à compactação — o "latest" pointer
-sempre aponta para o checkpoint mais recente, mesmo após compactação.
-
-
-### Context Retrieval
-Next-phase agents retrieve previous context via:
-```
-context_get(slug=slug, session_id=SESSION_ID)                    # most recent checkpoint ("latest" is the default key)
-context_get(slug=slug, key="phase:3", session_id=SESSION_ID)     # specific phase
-context_list(slug=slug, session_id=SESSION_ID)                   # all checkpoints
-```
-
-### Long-Session Progress
-Every 5 turns during a long session, update STATUS.md with:
-- Current phase
-- Completed tasks
-- Pending tasks
-- Any blockers
+- For a known background task, wait only on its returned task ID; do not poll or start dependent work before it completes.
+- For transient dispatch failures, use the single retry and fallback policy in `Zeus Timeout & Retry`. A refusal or failed check is information to act on, not a reason to repeat the same attempt.
+- If the same task makes no progress after one corrected route, stop and report the blocker or ask one focused question. Do not invent task IDs, session APIs, or recovery state.
+- Use progress checkpoints only for work expected to span more than five turns. State what is complete, what remains, and any blocker; do not create a status file for bounded work.

package/src/instructions/zeus-communication-rules.instructions.md

@@ -1,7 +1,6 @@
 ---
 description: "Communication rules for Zeus and all Pantheon agents — clarity, conciseness, and directness"
 name: "Zeus Communication Rules"
-applyTo: "agents/zeus.agent.md"
 ---
 
 # 🗣️ COMMUNICATION RULES

package/src/instructions/zeus-memory-operations.instructions.md

@@ -0,0 +1,26 @@
+---
+description: "Zeus-only council memory procedures"
+name: "Zeus Memory Operations"
+agents: [zeus]
+fallback: shared
+---
+
+# Zeus Memory Operations
+
+## Routing
+
+Use the task-start memory result for context and static agent descriptions for routing. Do not add KV/cache calls to ordinary dispatches.
+
+## Council Decisions
+
+Before a council, search separately from the required task-start search:
+`memory_search(query=question, top_k=2, namespace="council_decisions")`.
+Use a recent, directly matching decision only after checking current context;
+otherwise treat it as background, never as authority to skip a needed review.
+
+Persist only reusable, material decisions. Use
+`key="council:<yyyy-mm-dd>:<slug>"`; JSON-stringify both `value` and
+`metadata` for `memory_store(namespace="council_decisions", ...)`. Keep the
+record concise: question, recommendation, specialists, confidence, unresolved
+trade-off, and timestamp. Use `default` for routine summaries and @mnemosyne
+for ADRs.

package/src/instructions/zeus-timeout-retry.instructions.md

@@ -1,139 +1,18 @@
 ---
-description: "Timeout enforcement, retry policies, subtask dispatch, and timeout tracking for Zeus"
+description: "Bounded retries and lightweight subtask routing for Zeus"
 name: "Zeus Timeout & Retry"
-applyTo: "agents/zeus.agent.md"
+agents: [zeus]
+fallback: shared
 ---
 
-# ⏱️ TIMEOUT & RETRY ENFORCEMENT
+# Bounded delegation
 
-When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
+Use the native `task()` result as the source of truth. Do not simulate per-agent timers, poll without a known background task ID, or check for reusable sessions through APIs that are not available. `routing.yml` defines the concurrency limit, retry count, and canonical fallback chains.
 
-## Timeout Behavior by Agent Role
+For a transient dispatch failure (timeout, crash, or empty response), retry that agent once. If it fails again, follow its configured fallback chain left-to-right once; if none is configured or the chain is exhausted, report what failed and stop. Never retry a refusal, failed test, validation, or migration as though it were a dispatch error. Do not restart an exhausted chain.
 
-| Agent Role | Timeout | Retry Policy | Fallback Chain | Partial Results OK? | Reasoning Effort |
-|------------|---------|-------------|----------|---------------------|------------------|
-| Explorer (@apollo) | 60s | 2 retries, exp backoff | @athena (plan) → @hermes (impl) | ✅ Yes | low |
-| Implementer (@hermes, @aphrodite, @demeter) | 180s | 3 retries, exp backoff | @talos (hotfix) → @athena (replan) | ❌ No | medium |
-| Reviewer (@themis) | 120s | 3 retries, exp backoff | @zeus (escalate) → user | ❌ No | high |
-| Infrastructure (@prometheus) | 300s | 3 retries, exp backoff | @hermes (config) → @zeus (escalate) | ❌ No | medium |
-| Hotfix (@talos) | 30s | 2 retries, no backoff | @hermes (full fix) | ✅ Yes | low |
-| Remote Sensing (@gaia) | 120s | 2 retries, exp backoff | @hermes (generic) | ✅ Yes | high |
+Fallbacks for auth/security/data/schema work must preserve specialist competence, Themis review, and human approval. Full-auto does not bypass these gates.
 
-## Retry Flow
+## Lightweight subtask
 
-```
-Task dispatch → timeout elapsed → log timeout
-  ├─ retry_count > 0 → retry with exponential backoff → decrement retry_count
-  │    └─ still failing? → retry again (up to retry_count limit)
-  │
-  ├─ retries exhausted → FALLBACK CHAIN:
-  │    ├─ fallback[0] exists? → dispatch to fallback agent
-  │    │    └─ keep original task spec + context; add error context
-  │    ├─ fallback[1] exists? → dispatch to second fallback
-  │    └─ all fallbacks failed? → ESCALATE
-  │
-  ├─ no fallbacks defined → return TIMEOUT error to user
-  │
-  └─ ESCALATE: "Agent X failed after N retries. Fallbacks Y, Z also failed.
-                 Options: (a) try different agent, (b) simplify scope, (c) manual"
-```
-
-
-
-## Fallback Chain Definitions
-
-Each fallback chain is evaluated left-to-right: if the first fallback fails, try the second, etc.
-
-| Agent | Fallback[0] | Fallback[1] | Escalate To |
-|-------|------------|------------|-------------|
-| @apollo | @athena (plan scoped task) | @hermes (implement search) | @zeus |
-| @hermes | @talos (minimal fix) | @athena (replan + simplify) | @zeus |
-| @aphrodite | @talos (CSS/UX fix) | @hermes (generic fallback) | @zeus |
-| @demeter | @hermes (generic backend) | @athena (replan schema) | @zeus |
-| @themis | @zeus (direct escalation) | — | user |
-| @prometheus | @hermes (config/deploy) | @zeus | user |
-| @talos | @hermes (full implementation) | — | @zeus |
-| @hephaestus | @nyx (observability debug) | @hermes (generic) | @zeus |
-| @nyx | @hermes (generic) | — | @zeus |
-| @iris | @zeus (manual override) | — | user |
-| @mnemosyne | @zeus (manual) | — | user |
-
-### Escalation Protocol
-When ALL fallbacks fail:
-1. Log the full failure chain: which agents were tried, what error each returned
-2. Report to user: "Task [X] failed. Tried: [agent list]. Error: [summary]."
-3. Offer options: (a) try different approach, (b) simplify scope, (c) manual fix
-4. NEVER retry the same chain automatically — break the cycle
-
-### Session Reuse Check
-Before dispatching a task, check if a reusable session exists:
-
-```
-@hermes — continuing from previous session.
-Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
-New task: add refresh token rotation.
-```
-
-Use `session_max` from routing.yml to determine how many sessions to keep per agent.
-
----
-
-# 📦 SUBTASK DISPATCH (Lightweight Delegation)
-
-Subtask is a bounded, low-risk delegation mode that **skips** the standard artifact lifecycle. Use it for focused work that doesn't need Themis review.
-
-## When to Use Subtask vs Full Task
-
-> **REGRA DE OURO:** Quando em dúvida, use full task. Subtask é para o que você tem 100% de certeza que é seguro pular revisão.
-
-### Subtask Decision Tree (run BEFORE every delegation)
-
-```
-□ Scope: ≤2 files AND ≤10 lines changed?         [YES→continue | NO→full task]
-□ Risk: No schema change, no security impact?      [YES→continue | NO→full task]
-□ Auth: No authentication/authorization logic?      [YES→continue | NO→full task]
-□ Data: No data loss risk, no migration?            [YES→continue | NO→full task]
-□ Review: Output does NOT feed into Themis review?  [YES→continue | NO→full task]
-
-ALL YES → subtask (skip artifact + Themis)
-ANY NO  → full task (IMPL artifact + Themis review mandatory)
-```
-
-### Comparison Table
-
-| Aspect | Subtask | Full Task |
-|--------|---------|-----------|
-| Scope | Single file, <10 lines, read-only | Feature, multi-file, schema change |
-| Risk | Low (no security/data implications) | Any risk level |
-| Artifact | ❌ No IMPL artifact | ✅ IMPL artifact required |
-| Themis review | ❌ None | ✅ Mandatory |
-| Use case | Apollo discovery, Talos hotfix, bounded fix | Feature implementation, migration, API change |
-
-### Concrete Examples
-
-| Task | Scope | Risk | Subtask? | Why |
-|------|-------|------|----------|-----|
-| Fix typo in CSS class | 1 file, 1 line | None | ✅ | Bounded, no security impact |
-| Add error handling to existing endpoint | 1 file, 5 lines | Low | ✅ | No schema change |
-| Implement login endpoint | 2+ files, 50+ lines | High (auth) | ❌ | Security-critical, needs Themis |
-| Database migration | 1 file, 15 lines | High (data) | ❌ | Data loss risk, needs rollback |
-| Apollo codebase search | 0 files | None | ✅ | Read-only investigation |
-| Update README | 1 file, 3 lines | None | ✅ | Documentation only |
-
-### Safety Rules
-1. **Bounded scope** — single file or read-only investigation
-2. **Low risk** — no security implications, no data loss, no breaking changes
-3. **No Themis dependency** — output doesn't feed into a phase that requires review
-
-## Subtask Return Format
-Return the standard `## subtask_summary` defined in `## Agent Return Format` (files_changed, summary, tests, coverage, tokens, status, blockers).
-
-## Timeout Parcial (Partial Results)
-
-Only agents marked ✅ in the Timeout Behavior table above may return partial results: @apollo (partial file list, e.g. "found 7 of 12 files before timeout"), @gaia (partial literature findings) and @talos (confirm progress if a hotfix times out). Never for implementers or reviewers — they must complete or fail. When dispatching with partial-OK, set the expectation: `@apollo Search for auth files. Timeout parcial OK — return whatever you have.`
-
----
-
-# 📊 TIMEOUT TRACKING
-
-Track in-flight delegations against the Timeout Behavior table above. Log timeouts to `/memories/session/timeout-log.md` for later analysis.
+For clear, bounded, reversible, low-risk work, dispatch directly to one specialist. Skip routine plan/artifact phases and discovery; ask the specialist to inspect only relevant context, make the change, run focused verification, and return `subtask_summary`. Add planning, artifacts, Themis review, or approval only when scope or risk requires them.