pantheon-opencode 1.5.2 → 1.6.0-beta.10

package/AGENTS.md

@@ -1,28 +1,13 @@
+<!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
 <!-- 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). -->
+<!-- Source of truth: the static project sections in scripts/build-agents-md.mjs. -->
+<!-- pantheon:agents-md v2 artifact=project generated-at=2026-10-14T15:44:12-03:00 sha=a305942 -->
 
-# Pantheon Agent System — OpenCode
+# Pantheon — Repository Setup
 
-This project uses the Pantheon multi-agent framework with 14 specialized agents.
-
-## Available Agents
-
-| Agent | Role |
-|-------|------|
-| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review. |
-| @apollo | Read-only investigation scout — 3–10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands. |
-| @athena | Strategic planner & architect — research-first, plan-only, never implements. Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo for discovery. |
-| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis. |
-| @gaia | Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data. |
-| @hephaestus | AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis. |
-| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Calls apollo for discovery, sends to themis. |
-| @iris | GitHub operations specialist — branches, pull requests, issues, releases, tags. Called by zeus after review. Never pushes or merges without explicit human approval. Integrates with VS Code GitHub Pull Requests extension. |
-| @mnemosyne | Memory bank quality owner — initializes .pantheon/memory-bank/, writes ADRs and task records on explicit request. Called by zeus. Never invoked automatically after phases. |
-| @nyx | Observability & monitoring specialist — OpenTelemetry tracing, token/cost tracking, agent performance analytics, LangSmith integration. Calls apollo for discovery, sends to themis. |
-| @prometheus | Infrastructure + model provider specialist — Docker, CI/CD, multi-model routing, cost optimization, provider abstraction |
-| @talos | Hotfix express lane — direct fixes for small bugs, CSS, typos, minor logic. No TDD ceremony, no orchestration overhead. Standalone, no subagents. Escalates complex issues to zeus. |
-| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, coverage >80%, correctness, deprecation audit. Called by implementers; escalates blockers to zeus. |
-| @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
+Shared Pantheon rules (agent table, return format, memory protocol, YAGNI,
+communication rules) live in the global `~/.config/opencode/AGENTS.md`; this
+file carries only repository-specific setup so no rule is loaded twice.
 
 ## OpenCode Setup
 
@@ -43,875 +28,9 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 
 ## Conventions
 
-- TDD: Write failing test first, then implement
-- Coverage minimum: 80%
+- TDD: RED→GREEN→REFACTOR for testable behavior; use focused checks for micro-edits
+- Honor repository coverage thresholds when relevant; preserve stronger auth/security/data-integrity gates
 - 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",
-    precedent_used: false,
-    timestamp: "<ISO-8601>"
-  },
-  metadata: {
-    type: "council_decision",
-    specialist_count: N,
-    model_tier_used: "premium|default|fast"
-  }
-})
-```
-`value` is JSON-serialized before storing (the MCP `memory_store.value` argument is a string).
-
-### 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 verbatim (note "⚠️ Decisão de [data] — reavaliar se contexto mudou") as fast-path answer. Skip council dispatch entirely. |
-| > 0.85 | >= 30 days | Return with warning "Reavaliar se contexto mudou — decisão tem mais de 30 dias" + 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`, 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, "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)
-Run the precedent read path defined in `## Memory Protocol > Council Decisions Namespace` (`memory_search(query, top_k=2, namespace="council_decisions")`). If no precedent applies, 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)
-Persist the decision using the write path in `## Memory Protocol > Council Decisions Namespace`, then `board.markReconciled("<task-id>")`.
-
-## Specialist Output Format (Fase 1 — machine-parseable structured fields)
-
-Specialists MUST return the structured `## specialist_response` format (position, reasoning, trade_offs, risks, confidence, agreement_signals, specific_claims) defined in `## Agent Return Format > Council Specialist Response Format`.
-
-## 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
-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.
+<!-- pantheon:generated:end — user content outside this region is preserved verbatim -->