pantheon-opencode 1.3.4 → 1.3.5-beta.52.c75b04d

package/AGENTS.md

@@ -1,3 +1,6 @@
+<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
+<!-- Source of truth: src/instructions/*.instructions.md (AGENTS.md is a committed build artifact). -->
+
 # Pantheon Agent System — OpenCode
 
 This project uses the Pantheon multi-agent framework with 14 specialized agents.
@@ -45,3 +48,919 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 - Async/await on all I/O
 - Type hints on all functions
 - PRs always update the README — every pull request must document newly added features, behaviors, env vars, or commands in the README before being opened.
+
+---
+
+# Agent Instructions
+
+The following sections are consolidated from `src/instructions/*.instructions.md`
+so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the
+`instructions` config key) receive identical instruction content.
+
+<!-- Source: src/instructions/agent-return-format.instructions.md -->
+## Agent Return Format
+
+
+# Agent Return Format
+
+All implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) MUST return results to Zeus in this format:
+
+## subtask_summary
+**files_changed:** [list of file paths, one per line]
+**summary:** What was done, in 2-3 sentences
+**tests:** ✅ All passing / ⚠️ X failing / ❌ Not run (reason)
+**coverage:** X% (if applicable)
+**tokens:** ~N input / ~M output (estimated)
+**status:** complete | partial (reason) | escalated (reason)
+**blockers:** [list any blockers or null]
+
+For investigation agents (Apollo, Athena), return structured findings with:
+- Key findings as bullet points
+- File paths with line numbers
+- Relevant code snippets (max 3 lines each)
+
+## Council Specialist Response Format
+
+When responding to a `/pantheon` council synthesis invocation, specialists MUST return this structured format:
+
+```
+## specialist_response
+**position:** <clear one-sentence position answering the question>
+**reasoning:** <2-4 sentences with logical chain>
+**trade_offs:** <what's gained vs lost, specific>
+**risks:** <what could go wrong, max 3 items>
+**confidence:** High | Medium | Low
+**agreement_signals:** agree:@agent1 on <issue>, agree:@agent2 on <issue> | disagree:@agent3 on <issue>
+**specific_claims:** <count of specific factual claims in response>
+```
+
+### Field Rules
+
+| Field | Required | Validation |
+|-------|----------|------------|
+| position | ✅ | Single sentence, must directly answer the question |
+| reasoning | ✅ | 2-4 sentences with logical chain |
+| trade_offs | ✅ | At least one gain and one loss, specific to context |
+| risks | ✅ | Max 3 bullet points |
+| confidence | ✅ | One of: High, Medium, Low |
+| agreement_signals | Optional | Format: `agree:@agent on issue \| disagree:@agent on issue`. Use only when you can reference other specialists expected positions. |
+| specific_claims | ✅ | Integer count of verifiable factual statements in the response |
+
+### Confidence Guidelines
+
+- **High**: Position backed by 3+ specific claims with evidence or direct experience
+- **Medium**: Position backed by 1-2 specific claims
+- **Low**: Position is opinion-based or speculative
+
+### Example
+```
+## specialist_response
+**position:** The BackgroundJobBoard should be used for council crash recovery
+**reasoning:** The board already supports running→completed→reconciled state machine with persistence. Registering council dispatches there adds ~50ms overhead but prevents total session loss on context crash. The WAL pattern ensures no data loss on restart.
+**trade_offs:** Gain: crash recovery for multi-minute council sessions. Lose: ~50ms registration overhead per council.
+**risks:** Board persistence failure could block council start — implement with fire-and-forget error handling
+**confidence:** High
+**agreement_signals:** agree:@themis on persist-before-notify
+**specific_claims:** 3
+```
+
+## Memory Context
+If this agent used `memory_recall` or `memory_search`, include the relevant memory entries
+used as context for the response.
+
+<!-- Source: src/instructions/backend-standards.instructions.md -->
+## Backend Development Standards
+
+
+# Backend Development Standards (Hermes)
+
+## Async/Await
+- Use async/await for ALL I/O operations (database, external APIs, file operations)
+- Never block on async operations
+- Use `asyncio.gather()` for parallel operations
+
+## Test-Driven Development
+- RED: Write a failing test
+- GREEN: Write minimal code to pass
+- REFACTOR: Improve without breaking tests
+
+## Type Safety
+- Type hints on all function parameters
+- Type hints on all return types
+- Use Pydantic for request/response validation
+
+## Code Organization
+- Maximum 300 lines per file
+- Separate: routes → services → models
+- Docstrings on public functions (Google format)
+
+## Error Handling
+- Never silent failures (catch and log)
+- Use appropriate HTTP status codes
+- Return friendly error messages (no stack traces)
+- Implement retry logic with exponential backoff
+
+## Performance
+- Avoid N+1 queries (use eager loading/joins)
+- Implement pagination for list endpoints
+- Cache frequently accessed data
+- Monitor for async deadlocks
+
+## Security
+- Input validation on all endpoints
+- CSRF protection
+- Rate limiting for sensitive endpoints
+- Sanitize logs (never log passwords/tokens)
+
+<!-- Source: src/instructions/frontend-standards.instructions.md -->
+## Frontend Development Standards
+
+
+# Frontend Development Standards (Aphrodite)
+
+## TypeScript
+- Strict mode always (no `any` types)
+- Props interfaces on all components
+- Return type annotations on all functions
+
+## Components
+- Single Responsibility Principle
+- Reusable and composable
+- Max 300 lines per component
+- Atomic Design pattern
+
+## Accessibility
+- ARIA labels on interactive elements
+- Keyboard navigation support
+- Color contrast WCAG AA
+- Semantic HTML
+
+## Responsive Design
+- Mobile-first approach
+- Breakpoints: 640px, 768px, 1024px, 1280px
+- Test on multiple devices
+
+## State Management
+- Hooks (useState, useContext, useReducer)
+- Centralized state for app-wide data
+- Local state for component-specific needs
+
+## Testing
+- React Testing Library (no snapshot testing)
+- Test behavior not implementation
+- >80% coverage requirement
+- Test user workflows
+
+## Styling
+- Tailwind CSS + custom CSS when needed
+- Design tokens for colors/spacing
+- Responsive classes
+- No inline styles
+
+<!-- Source: src/instructions/memory-protocol.instructions.md -->
+## Memory Protocol
+
+
+# 🧠 Memory Protocol — Universal Rules
+
+These rules apply to ALL Pantheon agents. Agent-specific overrides are defined
+in each agent's `## 🧠 Memory Protocol` section.
+
+## Universal Rules
+
+### 1. Pre-Work Read-Only Recall
+**Call `memory_search()` at task start before any file reads.**
+- Use domain-specific context matching your agent's focus area
+- Single call per task, not per turn
+- Agents have **read-only** memory access — only `memory_search()` is available
+
+### 2. Auto-Store by Zeus on Subtask Summary
+**`memory_store()` is called AUTOMATICALLY by Zeus when you return a subtask_summary.**
+- Include a clear `summary` field in your return — no explicit `memory_store()` call needed
+- This is the **ONLY** persistence path: agent → subtask_summary → Zeus → memory_store
+- Zeus persists ALL agent returns (implementers and read-only agents alike)
+
+### 3. Write-Ahead Log (WAL)
+Before Zeus calls `memory_store()`, it writes a write-ahead log to:
+```
+.pantheon/memory-wal/<agent>/<timestamp>.json
+```
+- WAL format: `{ agent, phase, summary, files_changed, status, timestamp }`
+- WAL is written **before** the store operation — if store crashes, WAL is recovered on next session start
+- WAL files are ephemeral (auto-cleaned after 7 days)
+
+### 4. Relevance Threshold
+**Skip search results if relevance score < 0.3.**
+- Prevents noise from unrelated past entries
+- Applies to `memory_search()` results only
+
+### 5. Permanent Documentation
+**ADR-level decisions → delegate to `@mnemosyne`.**
+- Use for: architecture decisions, significant trade-offs, pattern changes
+- Not for: routine task summaries (handled by Auto-Store)
+
+## Per-Agent Overrides
+
+Each agent file defines overrides in its `## 🧠 Memory Protocol` section:
+- Domain-specific `memory_search()` context string
+- Read-only access via `memory_search()` only — no `memory_store` for subagents
+- Agent-specific rules (session-end, sprint close, quick-index, etc.)
+
+
+## Delegation Cache
+
+Para otimizar decisoes de delegacao e reduzir gasto de tokens:
+
+1. **memory_search(task_prompt, top_k=2)** antes de aplicar a arvore de roteamento
+2. Se score > 0.85 → reutiliza agente + background_mode do cache
+3. Se score ≤ 0.85 → aplica regras estaticas e memory_store() com:
+   - key: deleg:<task_type>
+   - value: {agent, background, pattern}
+   - metadata: {type: "decision", score: N}
+
+4. **kv_store("deleg:<pattern>", ...)** para padroes recorrentes de delegacao
+5. **kv_get("deleg:<pattern>")** para reusar decisoes ja tomadas
+
+Isso elimina ~300 tokens de reasoning por delegacao quando o cache acerta.
+
+## Council Decisions Namespace
+
+Council synthesis decisions are persisted in a dedicated `council_decisions` namespace for precedent fast-path retrieval:
+
+### Write Path
+After every `/pantheon` council synthesis completes, Zeus stores:
+```
+memory_store({
+  namespace: "council_decisions",
+  key: "council:<yyyy-mm-dd>:<slug>",
+  value: {
+    question: "original question",
+    specialists: ["@agent1", "@agent2"],
+    recommendation: "final recommendation",
+    confidence: "High|Medium|Low",
+    agreements: ["point1", "point2"],
+    divergences: [{"issue": "...", "resolution": "..."}],
+    response_rate: "X of Y",
+    themis_audit: "approved|issues"
+  },
+  metadata: {
+    type: "council_decision",
+    specialist_count: N,
+    model_tier_used: "premium|default|fast"
+  }
+})
+```
+
+### Read Path (Precedent Fast-Path)
+Before dispatching a new council, Zeus runs:
+```
+memory_search(question, top_k=2, namespace="council_decisions")
+```
+
+Result interpretation:
+| Score | Age | Action |
+|-------|-----|--------|
+| > 0.85 | < 30 days | Return precedent as fast-path answer. Skip council dispatch entirely. |
+| > 0.85 | >= 30 days | Return with warning "Reavaliar se contexto mudou" + proceed with council |
+| 0.5 - 0.85 | Any | Include as context for specialists but still dispatch council |
+| < 0.5 | Any | Ignore, proceed with fresh council |
+
+### TTL & Maintenance
+- Council decisions are LONG-TERM (no TTL or TTL = 365 days)
+- Stale decisions (age > 90 days) should be flagged but NOT deleted — they remain as historical record
+- Purge only via explicit namespace cleanup when decisions are superseded by ADRs
+
+### When NOT to Use
+- Routine task summaries → use `default` namespace (auto-store by Zeus)
+- Sprint/progress tracking → use `session` namespace
+- ADR-level architecture decisions → delegate to @mnemosyne for permanent documentation
+
+<!-- Source: src/instructions/yagni.instructions.md -->
+## YAGNI Anti-overengineering
+
+
+## YAGNI Principles
+
+1. **Don't add abstractions before the third repetition** — Two similar pieces of code are a coincidence. Three are a pattern.
+2. **Prefer duplication over the wrong abstraction** — A bad abstraction is worse than copy-paste.
+3. **Solve today's problem, not tomorrow's** — You don't know what tomorrow looks like.
+4. **If it's not tested, it doesn't exist** — Code without tests is not "done".
+5. **The simplest working solution is the best** — Fancy patterns add cognitive load.
+6. **Don't optimize prematurely** — Measure first, then optimize.
+7. **Remove unused code immediately** — Dead code is debt.
+8. **Prefer standard library over dependencies** — One less dependency = one less vulnerability.
+9. **Avoid configuration systems until something needs to vary** — Hard-coded values are fine until you have at least 3 different values.
+10. **Don't build for scale you don't have** — YAGNI applies to infrastructure too.
+11. **Delete more than you add** — Every line of code is a liability.
+12. **If you're not sure you need it, you don't need it** — Trust your gut.
+
+When reviewing code, always ask: "Is this YAGNI? Could we solve this more simply?"
+
+<!-- Source: src/instructions/zeus-anti-stall.instructions.md -->
+## Zeus Anti-Stall
+
+
+# 🛑 ANTI-STALL & STALL DETECTION
+
+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`, dispatch to fallback agent, report to user |
+| 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 a third time blindly. Instead:
+   - Dispatch to fallback agent (from routing.yml)
+   - If no fallback, escalate to user with: "Task [X] failed after retry. Options: (a) simplify, (b) different agent, (c) manual intervention."
+
+## 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, "heartbeat")` returns a checkin older than 300s, log a stall warning and resume
+- Write heartbeat after every anti-stall recovery action:
+  ```
+  context_save(slug, "heartbeat", json({"status": "alive", "last_action": "...", "turn_count": N}))
+  ```
+
+### Checkpoint Auto-Save (Pré-Compactação)
+Before ANY delegate dispatch, save a checkpoint:
+```
+context_save(slug, "phase:N", json({
+  "phase": N, "turn_count": N, "agent": "...", "summary": "..."
+}), session_id=SESSION_ID)
+```
+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:
+result = context_save(slug, "init", session_state)
+SESSION_ID = result.session_id   # ← guarde para toda a sessão
+
+# Antes de CADA delegação:
+context_save(slug, f"pre:{agent}", current_state, session_id=SESSION_ID)
+
+# Após retorno do agente:
+context_save(slug, f"post:{agent}", 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, "latest")        # most recent checkpoint
+context_get(slug, "phase:3")      # specific phase
+context_list(slug)                 # all checkpoints
+```
+
+### Long-Session Progress
+Every 5 turns during a long session, update STATUS.md with:
+- Current phase
+- Completed tasks
+- Pending tasks
+- Any blockers
+
+<!-- Source: src/instructions/zeus-communication-rules.instructions.md -->
+## Zeus Communication Rules
+
+
+# 🗣️ COMMUNICATION RULES
+
+These rules apply to Zeus and all agents in the system:
+
+- **No Flattery**: Never start a response with compliments or affirmations ("Great question!", "Absolutely!", "Sure!"). Begin directly with the answer or action.
+- **Honest Pushback**: If a request is technically unsound or will cause problems, say so clearly and explain why. Offer a better approach. Agreeing to avoid friction is worse than a useful correction.
+- **Concise Execution**: Skip lengthy preambles. State what you're doing in one line, do it, report the outcome. Avoid verbose commentary around trivial steps.
+- **No Padding**: Don't add filler sentences, summaries of what was just said, or redundant confirmations. Every sentence must carry information.
+- **Uncertainty = Ask**: If requirements are ambiguous, ask one targeted question. Don't guess and implement the wrong thing.
+
+<!-- Source: src/instructions/zeus-council-synthesis.instructions.md -->
+## Zeus Council Synthesis
+
+
+# 🏛️ INLINE COUNCIL SYNTHESIS — /pantheon
+
+When a question requires multiple expert perspectives on a trade-off or architecture decision, **dispatch specialists inline** (visible to user) instead of delegating to a hidden subagent.
+
+## Trigger Patterns (detect ANY)
+- Trade-off questions: "which is better?", "should we use X or Y?", "compare A and B"
+- Architecture decisions with long-term impact
+- Security/compliance choices
+- Technology selection (databases, frameworks, providers, libraries)
+- "Is this safe?", "trade-offs of...", "what are the risks?"
+- Cost vs quality decisions
+- Multi-stakeholder concerns (frontend + backend + infra)
+
+```mermaid
+---
+config:
+  look: classic
+  theme: dark
+---
+sequenceDiagram
+    participant U as User
+    participant Z as Zeus
+    participant M as Memory (Precedent)
+    participant A as Apollo (Research)
+    participant B as BackgroundJobBoard
+    participant S1 as Specialist 1
+    participant S2 as Specialist 2
+    participant S3 as Specialist 3
+    participant W as Web Search
+    participant T as Themis (Audit + Moderator)
+
+    U->>Z: /pantheon [--research] question
+    Z->>M: memory_search(council_decisions)
+    alt Precedent found (score > 0.85)
+        M-->>Z: ⚠️ Cached decision
+        Z->>U: Fast-path precedent
+    else No precedent
+        opt --research flag
+            Z->>A: 30s pre-scan
+            A-->>Z: Context brief
+        end
+        Z->>B: registerLaunch({council session})
+        par Dispatch all specialists
+            Z->>S1: Domain query + shared context
+            Z->>S2: Domain query + shared context
+            Z->>S3: Domain query + shared context
+        end
+        par Collect responses
+            S1-->>Z: Structured response
+            S2-->>Z: Structured response
+            S3-->>Z: Structured response
+        end
+        Note over Z: Cross-validate confidence
+        alt Agreement rate < 50%
+            Z->>S1: Rebuttal round
+            Z->>S2: Rebuttal round
+            Z->>S3: Rebuttal round
+            S1-->>Z: Refined response
+            S2-->>Z: Refined response
+            S3-->>Z: Refined response
+            Note over Z: Ainda divergência?
+            alt Agreement rate STILL < 50%
+                Z->>W: browser_search() for each divergence point
+                W-->>Z: Evidence brief with sources
+                Z->>T: Dispatches as moderator
+                Note over T: Reviews evidence + specialist responses
+                T-->>Z: Moderator verdict
+            end
+        end
+        Z->>Z: Synthesize (with evidence if tie-broken)
+        Z->>T: Audit synthesis fidelity
+        T-->>Z: ✅ / ⚠️ Issues
+        Z->>M: Store decision
+        Z->>B: Mark reconciled
+        Z->>U: 🏛️ Council Synthesis
+    end
+```
+
+## Dispatch Sequence (9-Step Protocol)
+
+### Step 0 — Precedent Fast-Path (Fase 1)
+Before any dispatch: `memory_search(query, top_k=2, namespace="council_decisions")`
+- Score > 0.85 AND age < 30 days → return precedent verbatim with note "⚠️ Decisão de [data] — reavaliar se contexto mudou". SKIP entire dispatch.
+- Score > 0.85 AND age > 30 days → return precedent with ⚠️ "Reavaliar se contexto mudou — decisão tem mais de 30 dias"
+- Else → proceed to Step 0b
+
+### Step 0b — Apollo Pre-Scan (Fase 2, --research flag)
+If `/pantheon --research <question>`: dispatch @apollo with 30s timeout. Inject findings as `shared_context` into ALL specialist prompts. Skip if flag absent.
+
+### Step 1 — Register on BackgroundJobBoard (Fase 1)
+Before dispatching specialists:
+```
+board.registerLaunch({
+  taskID: "council:<uuid>",
+  parentSessionID: "<session-id>",
+  agent: "zeus",
+  description: "Council: <question>",
+  objective: "Synthesize specialist recommendations"
+})
+```
+Enables crash recovery — if context is lost mid-synthesis, the board preserves session state.
+
+### Step 2 — Select Specialists
+Use domain-to-specialist mapping table (below). Max 3 specialists.
+
+### Step 3 — Dispatch ALL task() calls in ONE message
+Each specialist prompt MUST include:
+- Structured output template (see Specialist Output Format below)
+- `shared_context` if Apollo pre-scan was done
+- Timeout per role: 120s for reviewers, 60s for explorers/implementers
+
+### Step 4 — Collect Responses
+Wait for all responses. Note TIMEOUT agents. Partial results OK only for read-only specialists (@apollo, @gaia).
+
+### Step 5 — Confidence Cross-Validation (Fase 2)
+For each specialist response, validate confidence claims:
+
+| Reported | Minimum Required | Action |
+|----------|-----------------|--------|
+| High | ≥ 3 specific claims | If fewer → downgrade to Medium, annotate "(auto-downgraded from High: only N specific claims)" |
+| Medium | ≥ 1 specific claim | Pass |
+| Low | Any response | Pass |
+
+"Specific claim" = statement with evidence, data point, or verifiable fact (not opinion).
+
+### Step 6 — Divergence-Gated Rebuttal Round (Fase 2, conditional)
+Calculate agreement rate = `min(agreements, divergences) / total_points` from structured `agreement_signals`. If < 50% agreement:
+- Dispatch ONE rebuttal round: specialists see ALL other responses and refine their own
+- Updated responses treated as final
+- Hard cap: MAX 3 total rounds (initial + 2 rebuttals)
+- Skip if any TIMEOUT occurred (can't rebuttal without all voices)
+
+### Step 6b — Modo Desempate com Evidência (Fase 2, conditional)
+
+If after Step 6 the agreement rate is STILL < 50% (rebuttal did not resolve divergence):
+
+1. **Identify divergence points** — Parse all specialist responses (initial + rebuttal) and extract specific issues where positions differ
+2. **Web research** — For EACH divergence point, Zeus calls `browser_search()` or `webfetch()` to find factual evidence:
+   - Benchmarks, documentation, GitHub issues, official sources
+   - At least 2 independent sources per point when possible
+   - Focus on factual data, not opinion
+3. **Compile Evidence Brief** — Structure findings as:
+   ```
+   ## evidence_brief
+   **divergence_point_1:** <description>
+   **evidence_found:** <facts from web, max 3 sentences>
+   **sources:** [URL1, URL2]
+
+   **divergence_point_2:** ...
+   ```
+4. **Dispatch @themis as moderator** — Send ONE task with:
+   - All specialist responses (initial + rebuttal)
+   - The evidence brief
+   - Prompt: "Act as impartial moderator. These specialists disagree on [points]. Here is web evidence on each point. Issue a final verdict for each divergence point, citing specific evidence. Return structured verdict."
+5. **Themis returns moderator verdict** in this format:
+   ```
+   ## moderator_verdict
+   **divergence_points_analyzed:** <count>
+   **verdicts:**
+     - <point 1>: <decision> — evidence: <citation>
+     - <point 2>: <decision> — evidence: <citation>
+   **overall_direction:** <which approach is better supported by evidence>
+   **confidence:** High | Medium | Low
+   **unresolved:** <any points still unclear despite evidence>
+   ```
+6. **Zeus incorporates verdict** into synthesis (Step 7), showing which evidence supported which conclusion
+
+**Rules:**
+- Only triggers when agreement rate < 50% AFTER rebuttal round
+- Skip if NO divergence points are web-researchable (purely subjective/opinion-based disagreements)
+- Max 3 web searches per council (prevents runaway)
+- If Themis confidence is Low or points remain unresolved, note this explicitly in synthesis
+- Themis moderator role is SEPARATE from the Themis Audit Gate (Step 8) — they serve different functions
+
+### Step 7 — Zeus Synthesize
+Use structured `agreement_signals` to auto-detect agreements/divergences. Output synthesis template (see below).
+
+### Step 8 — Themis Audit Gate (Fase 1)
+Post-synthesis, dispatch @themis:
+```
+task(subagent_type: "themis", prompt: "Audit this council synthesis for fidelity. Compare raw specialist responses against the synthesized output. Check: (1) Any specialist misrepresented? (2) Divergences hidden or softened? (3) Confidence claims match response specificity? Return ✅ or list specific issues.")
+```
+- If ✅ → proceed
+- If issues → fix each issue before delivering to user
+
+### Step 9 — Persist & Reconcile (Fase 1)
+```
+memory_store({
+  namespace: "council_decisions",
+  key: "council:<yyyy-mm-dd>:<slug>",
+  value: JSON.stringify({
+    question, specialists, recommendation, confidence,
+    agreements, divergences, precedent_used, timestamp
+  }),
+  metadata: {type: "council_decision", specialist_count: N}
+})
+board.markReconciled("<task-id>")
+```
+
+## Specialist Output Format (Fase 1 — machine-parseable structured fields)
+
+Specialists MUST return these structured fields in their response:
+
+```
+## specialist_response
+**position:** <clear one-sentence position>
+**reasoning:** <2-4 sentences>
+**trade_offs:** <what's gained vs lost>
+**risks:** <what could go wrong>
+**confidence:** High | Medium | Low
+**agreement_signals:** agree: @agent1, @agent2 on [issue] | disagree: @agent3 on [issue]
+**specific_claims:** <count of specific factual claims in response>
+```
+
+## Domain-to-Specialist Mapping
+
+| Domain | Specialists |
+|--------|-------------|
+| Architecture | hermes, demeter, themis, athena |
+| Security | themis, hermes, prometheus, nyx |
+| Database | demeter, hermes, prometheus |
+| AI/RAG | hephaestus, nyx |
+| Infrastructure | prometheus, hermes, themis |
+| Frontend/UX | aphrodite, themis, hermes |
+| Observability | nyx, hermes |
+| General | athena, themis, hermes |
+
+## Synthesis Output Template (enhanced)
+
+```
+## 🏛️ Council Synthesis
+
+**Question:** <original question>
+**Date:** <date>
+**Response rate:** X of Y specialists responded
+**Timed out:** @agent1, @agent2 (if any)
+**Precedent used:** yes/no (which one, date)
+**Research context:** <shared_context summary> (if --research)
+
+### Specialist Perspectives
+| Agent | Position | Trade-offs | Confidence |
+|-------|----------|------------|------------|
+| @agent1 | ... | ... | High/Med/Low |
+
+### Agreements
+- <what 2+ specialists agree on>
+
+### Divergences
+| Issue | Side A | Side B | Resolution |
+|-------|--------|--------|------------|
+
+### Evidence & Moderation (if tie-break activated)
+**Divergence points researched:** <list>
+**Evidence summary:** <key findings from web>
+**Moderator verdict:** <Themis final determination>
+**Sources:** <citations>
+
+### Recommendation
+<decisive conclusion>
+
+### Audit Gate
+**Status:** ✅ Themis approved | ⚠️ Issues corrected
+
+### Decision Gate
+**Confidence:** High/Medium/Low (adjusted for response rate)
+```
+
+## Themis Audit Gate Rules (Fase 1)
+
+1. Every specialist mentioned in synthesis? → ✅
+2. Divergences from raw responses preserved (not softened/hidden)? → ✅
+3. No specialist attributed a position they didn't state? → ✅
+4. Confidence claims match response specificity? → ✅
+5. If any ❌, list specific issues for Zeus to fix before delivery
+
+## Rebuttal Round Rules (Fase 2)
+
+1. Only triggers when agreement rate < 50%
+2. MAX 3 rounds total (including initial dispatch)
+3. Skip if any TIMEOUT (can't rebuttal without all voices)
+4. Each rebuttal round: specialist sees ALL other responses + current synthesis draft
+5. Refined responses replace originals for the final synthesis
+6. If agreement rate STILL < 50% after rebuttal → Step 6b (Modo Desempate com Evidência)
+
+## Crash Recovery via BackgroundJobBoard (Fase 1)
+
+If Zeus context crashes mid-council:
+1. On restart, `board.recoverRunningJobs()` marks running jobs as error
+2. Check `board.formatForPrompt()` for unreconciled terminal jobs
+3. Re-dispatch council with same question, noting: "⚠️ Retry — previous council session crashed. Using same question."
+
+## Performance Budget
+
+| Step | Latency | Phase |
+|------|---------|-------|
+| Precedent fast-path | < 500ms | Fase 1 |
+| Apollo pre-scan | +30s (optional, --research) | Fase 2 |
+| Specialist dispatch | bounded by slowest (60-120s) | — |
+| Rebuttal round | +60s (conditional, < 50% agreement) | Fase 2 |
+| Web search (tie-break) | +15s (conditional, < 50% after rebuttal) | Fase 2 |
+| Themis moderator | +15s (conditional, tie-break activated) | Fase 2 |
+| Themis audit | +15s | Fase 1 |
+| **Total worst case** (research + rebuttal + tie-break) | ~255s | — |
+| **Total typical** (no research, no rebuttal, no tie-break) | ~45-90s | — |
+
+> **Note**: The user can explicitly invoke this via `/pantheon <question>`. The `--research` flag adds Apollo pre-scan. All decisions are stored in `council_decisions` memory namespace for fast-path retrieval on future councils.
+
+## Modo Desempate Rules (Fase 2)
+
+1. Only triggers when agreement rate < 50% AFTER rebuttal round
+2. If no divergence points are web-researchable (pure opinion disagreement), skip — Zeus synthesizes with lower confidence
+3. Max 3 web searches per council invocation
+4. Themis moderator role is DISTINCT from Themis audit gate:
+   - Moderator: resolves substantive disagreement between specialists (reads evidence, gives verdict)
+   - Audit gate: checks synthesis fidelity against raw responses (quality assurance)
+   Both run in the same council invocation, at different steps
+5. If Themis moderator confidence is Low, mark as "unresolved tie" in the synthesis output
+6. Evidence from web search must be cited with source URL or document reference — no anonymous claims
+
+<!-- Source: src/instructions/zeus-timeout-retry.instructions.md -->
+## Zeus Timeout & Retry
+
+
+# ⏱️ TIMEOUT & RETRY ENFORCEMENT
+
+When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
+
+## Timeout Behavior by Agent Role
+
+| 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 |
+
+## Retry Flow
+
+```
+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
+Expect a `subtask_summary` response with:
+```
+## subtask_summary
+**files_changed:** [paths]
+**summary:** What was done
+**tests:** ✅ or N/A
+**status:** complete | partial | escalated
+```
+
+## Timeout Parcial (Partial Results)
+
+Timeout parcial is ONLY for read-only, independent agents:
+- ✅ @apollo — can return partial file list ("found 7 of 12 files before timeout")
+- ✅ @gaia — can return partial literature findings
+
+- ✅ @talos — can confirm progress if hotfix times out
+- ❌ Never for implementers or reviewers — must complete or fail
+
+When dispatching with partial-OK, set expectation:
+```
+@apollo Search for auth files. Timeout parcial OK — return whatever you have.
+```
+
+---
+
+# 📊 TIMEOUT TRACKING
+
+Maintain awareness of in-flight delegations:
+
+| Agent | Timeout | Status | Partial OK? |
+|-------|---------|--------|-------------|
+| @apollo | 60s | ✅ complete | ✅ |
+| @hermes | 180s | ⏳ in progress | ❌ |
+| @themis | 120s | ⏳ in progress | ❌ |
+
+Log timeouts to `/memories/session/timeout-log.md` for later analysis.