PhantomLogos

# Phantom Logos Agent Collaboration Guidelines (AGENTS.md)

## Reference Configurations
- [GEMINI.md](GEMINI.md) - Agent Identity and Cognitive Architecture
- [CONSTITUTION.md](.antigravity/CONSTITUTION.md) - Sovereign Core Constitution
- [rules.json](.antigravity/rules.json) - Governance and Verification Rules

This system operates through a 3-Tier hierarchical structure (RuFlow v1.1.0) designed for maximum accuracy, hardware-safe execution (7 GB VRAM Limit), and specialized expertise routing. External CLI agents (Claude Code, Gemini, OpenCode) connect through the **Hermes Bridge** and are mapped to RuFlow tiers based on complexity and capability.

## 1. Layers and Roles

### L0 - Hank (The Authority)

- Final decision-maker. All strategic plans require L0 consent.

### Hermes Bridge (CLI Gateway)

- **Role:** Entry point for all external CLI agents. Routes to RuFlow tiers based on task complexity and agent capability.
- **Registered CLI Agents:**
  - `Claude Code CLI` — Tier 3. Orchestrates Sophia (L1) + Clotho (L2) roles via native sub-agent spawn. Activated for complexity > 0.8 or after 3-strike escalation. See `agent/claude-code.yaml`.
  - `Gemini CLI` — Tier 3. Native parallel multi-agent. Full RuFlow coverage (L1+L2+L3 simultaneously). Activated for parallel workloads.
  - `OpenCode/DeepSeek` — Tier 1-2. Single orchestrator, sequential. Default for standard local-first execution.
- **Memory:** Axes 1, 6, 7, 13, 14. See `agent/hermes.yaml`.

### L1 - Architect (Strategist / Sophia)

- **Primary:** Sovereign Strategic Gateway (Local-Hybrid).
- **Memory:** Full 14-Axis Mnemosyne integration.
- **Responsibility:** High-level planning, complex decomposition, and architectural decisions. Enforces the Sovereign Write Path (Axis 1 logging).

### L2 - Runner (Executor / Clotho)

- **Primary (Coding):** `qwen3.5-4b-ud:latest`.
- **Light (Routine):** `ministral-3b-ud:latest`.
- **Ultra-Light (Rapid):** `deepscaler-1.5b:latest`.
- **Responsibility:** Task execution, code generation, and tool bridge orchestration via unified GatewayArchitrave.

### L3 - Auditor (Analyst / Lachesis)

- **Primary (Logic):** `phi-4-mini-ud:latest`.
- **Primary (Code/Math):** `qwen2.5-coder-3b:latest` or `qwen2.5-math-7b-q4:latest`.
- **Intelligence:** Spatial Graph Context Expansion (Axis 5).
- **Responsibility:** Adversarial auditing, formal verification, and codebase mapping with dependency-aware expansion.

---

## 2. RuFlow v1.1.0: Strategic Routing

Tasks are routed based on specific capability requirements to optimize VRAM and accuracy:

1. **Sovereign Gateway Flow:** Unified routing for Pydantic AI and reasoning calls.
2. **Vision Flow:** Diagram/OCR/Creative via `qwen2.5-vl-3b:latest` (Ollama).
3. **Spatial Graph Flow:** Context-aware codebase mapping via Axis 5.
4. **Formal Verification Flow:** Logical and mathematical truth guarding via Axis 11.
5. **Episodic Write Path:** Automated logging of agentic steps for cross-session continuity.

---

## 3. Operational Mandates (Rules of Engagement)

### Sequential Loading Protocol

- **Strict Prohibition:** Concurrent loading of multiple heavy models (>3 GB) is forbidden.
- **Enforcement:** Every transition to a heavy model tier must be preceded by a mandatory `Morpheus.flush()` call to clear VRAM (Ollama + LocalRuntime).

### 7.0 GB VRAM Hygiene

- **Hardware Boundary:** All agents must operate within a 7.0 GB VRAM budget.
- **Reservation:** 1.0 GB is strictly reserved for Windows OS and system stability.
- **Offloading:** LocalRuntime must use dynamic `-ngl` for stability.

### Memory & Citation (Sovereign Mandate)

- **Grounded Reasoning:** All outputs must cite the 14-axis memory architecture.
- **Evidence Format:** Mandatory `[SRC:axis_N]` citations for every strategic claim.
- **Socratic Inquiry:** Ambiguity must be resolved via questioning before action.
- **Atomic Progress:** Incremental, testable changes are the sovereign standard.

### Communication Protocol (BA-01)

- **L0 Interaction (Chat):** All communication with the human user (Hank) must be in **Turkish**.
- **Bridge Layer (Plan, Walkthrough, Task, Rapor):** All user-facing `.md` artifacts must be in **Turkish**.
- **Core Layer (Code, Logs, DB, Config):** Must be in **English (ASCII-only)**. No Turkish characters in code or comments.
- **Reasoning Layer (Agent internals, debug):** Must be in **English (ASCII-only)**.
- **EMOJI_BAN:** The use of emojis or special character decorations is **strictly prohibited** in all outputs, files, and logs.
- **Timestamp Mandate:** All actions and system events must include timestamps in `[HH:MM AM/PM PT]` format.

---

## 4. Risk-Based Governance & L0 Sovereignty

- **L0 Sovereignty:** Explicit L0 consent ("basla", "yurut") AND a valid `L0_AUTH_TOKEN` (via `python scripts/create_l0_token.py`) are mandatory for any write or system action. Window: 60s.
- **Risk Tiers:**
  - **L3-Auto:** Read-only analysis and documentation (L3 audit sufficient).
  - **Sovereign-Gate:** Code edits, config changes, and deletions (Mandatory L0 consent).
  - **Sovereign-Hardened:** OutputGuard enforcement, l0_approved gate, reliability kill-switch (< 0.2 → END).

---

## 5. Tactical Artifacts & Execution Flow

Every phase must utilize the following triple-artifact structure:

1. **Implementation Plan (implementation_plan.md):** Architecture and strategy.
2. **Task List (task.md):** Granular TODOs. Skipping steps is forbidden.
3. **Scratch Book (scratch_book.md):** Continuous diary for context, errors, and reminders.

---

## 6. Error Handling & Termination (3-Strike Rule)

- If an error persists with >80% code similarity in changes, a maximum of 3 retries is allowed.
- After the 3rd failure, the agent must stop and provide a detailed post-mortem to L0.

---

## 7. Verification Standards

- The final step of every phase must be a "Test & Verification" step.
- Evidence (logs, test outputs, recordings) is required for phase finalization.

---

## 8. Output Governance & Artifact-First Mandate

- **Artifact-First:** All long plans, research, and analysis must be stored in `.md` files.
- **Terminal Hygiene:** Chat/Terminal must remain clean, used only for strategic summaries and L0 interaction.

---

### 9. Anti-Flash Pacing & Pre-Flight Audit

- **Risk Audit:** Before any `write` operation, identify 2 potential breaking points.
- **Protocol Over Pattern:** Rules in `rules.json` always override the urge to complete a task.
- **Analytical Rigor:** Prioritize system integrity over user-pleasing (Sycophancy).

### 10. Agnostic Modularity

- Maintain zero dependency on specific cloud proxies or proprietary LLM features.
- Ensure all logic is portable and grounds reasoning in execution feasibility.

### 11. FUNCTIONAL_TOOL_PRIORITY

- **Mandate:** Agents MUST use local SLM MCP tools and Muscle tools for status checks, context operations, and logging. Raw fs/bash is strictly prohibited for status/directory checks.
- **SLM MCP Tool Inventory (34 Tools):**
  - **Memory CUD:** `mcp_slm_remember` and `mcp_slm_observe` (active via ToolBridge custom interceptors with Axis 1 logging & shadow verify); `mcp_slm_update_memory`, `mcp_slm_delete_memory`, `mcp_slm_fetch`, `mcp_slm_list_recent` (maintenance/audit only).
  - **Retrieval:** `mcp_slm_recall` (as search), `mcp_slm_search` (FTS5), `mcp_slm_rerank`, `mcp_slm_embed` (embedding), `mcp_slm_context`.
  - **Session Lifecycle:** `mcp_slm_session_init` (must run at session start), `mcp_slm_close_session` (must run at session end), `mcp_slm_report_feedback`, `mcp_slm_report_outcome` (must run at phase end), `mcp_slm_get_session`, `mcp_slm_list_sessions`, `mcp_slm_tag_session`.
  - **Mesh P2P (Restricted):** `mcp_slm_mesh_peers`, `mcp_slm_mesh_send`, `mcp_slm_mesh_inbox`, `mcp_slm_mesh_state`, `mcp_slm_mesh_lock`, `mcp_slm_mesh_summary`.
  - **Behavioral/Assertions:** `mcp_slm_get_assertions`, `mcp_slm_get_soft_prompts`, `mcp_slm_reinforce_assertion`, `mcp_slm_contradict_assertion`.
  - **Skill Evolution:** `mcp_slm_plan_skill`, `mcp_slm_exec_skill`, `mcp_slm_reflect_skill`.
  - **Maintenance:** `mcp_slm_run_maintenance`, `mcp_slm_forget`, `mcp_slm_consolidate_cognitive`.
- **Muscle Tools:** Direct system interaction via path-protected local binaries. Mandates `LocalRuntime.run_vision_async`, `JinaReranker.rerank`, `_validate_path`, and `_shadow_verify_claim`.
- **Dual-Path Fallback:** If the SLM MCP server is unhealthy, auto-routing to local LanceDB + Ollama + Jina Reranker is enforced, checked with a 15-second heartbeat TTL.
- **Non-SLM MCP Tools (5 servers, 69 tools):**
  - **Web Fetch:** `fetch_fetch` (static pages with readability + robots.txt), `playwright_navigate` (dynamic/SPA pages)
  - **Reasoning:** `sequentialthinking_sequentialthinking` (complex multi-step CoT with branching)
  - **Knowledge Graph:** `kg-mem_create_entities`, `kg-mem_create_relations`, `kg-mem_add_observations`, `kg-mem_search_nodes`, `kg-mem_open_nodes`, `kg-mem_read_graph`, `kg-mem_delete_*`
  - **GitHub:** `github_create_or_update_file`, `github_get_file_contents`, `github_push_files`, `github_search_code`, `github_search_repositories`, `github_create_issue`, `github_create_pull_request`, `github_merge_pull_request`, `github_create_branch`, `github_search_issues`, `github_search_users`, `github_list_commits`, `github_list_issues`, `github_get_issue`, `github_get_pull_request`, `github_list_pull_requests`, `github_fork_repository`, `github_add_issue_comment`, `github_update_issue`, `github_create_pull_request_review`, `github_create_repository`, `github_get_pull_request_files`, `github_get_pull_request_status`, `github_update_pull_request_branch`, `github_get_pull_request_comments`, `github_get_pull_request_reviews`
  - **Playwright:** `playwright_navigate`, `playwright_screenshot`, `playwright_click`, `playwright_fill`, `playwright_select`, `playwright_hover`, `playwright_evaluate`, `playwright_get_visible_text`, `playwright_get_visible_html`, `playwright_close`, `playwright_go_back`, `playwright_go_forward`, `playwright_resize`, `playwright_press_key`, `playwright_drag`, `playwright_upload_file`, `playwright_save_as_pdf`, `playwright_custom_user_agent`, `playwright_click_and_switch_tab`, `playwright_iframe_click`, `playwright_iframe_fill`, `playwright_expect_response`, `playwright_assert_response`, `playwright_console_logs`, `playwright_get`, `playwright_post`, `playwright_put`, `playwright_patch`, `playwright_delete`, `start_codegen_session`, `end_codegen_session`, `get_codegen_session`, `clear_codegen_session`
- **Call Convention:** Tools above use `{server}_{tool}` naming (e.g. `playwright_navigate`). This is for direct ToolBridge.execute() calls. When interacting via IDE/Antigravity MCP protocol, the same tools are accessed by passing server and tool name as separate parameters.
- **Tool Selection Priority:**
  - **Web content:** `webfetch` (built-in) > `fetch` (MCP) > `playwright_navigate` (MCP, JS-rendered)
  - **Code search:** `codesearch` (built-in, local) > `github_search_code` (GitHub remote)
  - **Memory:** `mcp_slm_recall` (semantic, primary) > `kg-mem_search_nodes` (structured graph) > `semantic_store` (fallback)
  - **File ops (local):** ToolBridge write/replace (primary) > `github_create_or_update_file` (remote only)
- **Local Model Requirement:** All local inference runs use `qwen3.5-4b-ud:latest` (L2 Primary), `ministral-3b-ud:latest` (Light), or `deepscaler-1.5b:latest` (Ultra-Light). No 9B+ models are permitted for local execution due to the 7GB VRAM constraint.

---

## 12. Workspace Hygiene & Pathing (C: vs D:)

- **D: Workspace (Primary):** All project files, code, and temporary scratch scripts must reside in the `D:` project directory.
- **Python Environment:** All Python commands must be executed through the local `.venv` within the `D:` project directory to ensure dependency isolation.
- **C: Artifacts (Restricted):** The `C:` drive is strictly reserved for system-generated artifacts within the `.gemini/antigravity/brain` path. Writing any other file or script to `C:` is forbidden.
- **Terminal Hygiene:** The `Ccwd` for all commands must be within the `D:` workspace.

---

## 13. Laconism Mandate (Output Efficiency)

- **Directness Over Explanation:** Answer the user's question directly. No preamble, no postamble, no "I'm happy to help" or "Let me explain". If the answer is one word, say one word.
- **Filler Prohibition:** Do not add qualifying phrases, polite hedges, or meta-commentary about your own reasoning process in visible output (e.g., "I understand", "You are right", "I apologize").
- **CoT Seclusion:** Chain-of-thought reasoning must remain in internal `<thinking>` tags only. Only the final answer is user-visible.
- **Context Economy:** If the user's question can be answered without file reads, do not read files. If a short answer suffices, do not generate a long one.
- **Exception:** When the user explicitly asks for explanation, detail, or elaboration, provide it fully.

## 14. Neuro-Symbolic Cognitive Pipeline

- **Mandatory Formal Audit:** All code mutations must pass the 4-stage verification chain (AST -> QWED Logic -> SymPy/LLM Math -> Z3 SAT) via `scripts/sovereign_audit.py`.
- **Z3 SAT Bridge:** Phi-4 Mini serves as the logic extractor, converting drafts into native SMT-LIB2 for formal Z3 verification.
- **Fail-Closed Policy:** Any verification failure (UNSAT/Unknown) or SDK timeout triggers an immediate rejection of the draft.
- **QWED 2-Pass:** Code audits utilize a 2-pass strategy (Primary 2B -> Expert 4B) based on the `logic_score` threshold (< 0.6).

---

## 15. LangGraph State & Router Governance

### GraphState Fields (orchestrator.py:GraphState)
| Field | Type | Purpose |
|-------|------|---------|
| `task` | str | Active task description |
| `draft` | str | Current draft response |
| `partial_correction` | str | Iterative correction delta |
| `tool_iteration` | int | Tool call loop counter (max: 2) |
| `verification_retry` | int | Verification retry counter (max: 3) |
| `l0_approved` | bool | L0 sovereign gate flag |
| `recovered_state` | StateSnapshot | Checkpoint recovery state |

### Conditional Edges (krisis.py)
| Edge | Rule |
|------|------|
| `should_use_tier` | complexity -> Tier 0-3 |
| `should_continue` | reliability < 0.4 -> Red Zone / < 0.2 -> END |
| `should_call_tools` | tool_iteration < 2 -> call / else -> refine |
| `should_after_reflection` | confidence > 0.9 -> END (skip refine) |
| `wait_for_l0` | L0_AUTH_TOKEN required (60s TTL) |

### Sovereign Gate Nodes
| Node | Trigger |
|------|---------|
| `wait_for_l0` | Write operations, config changes, deletions |
| `deadlock_resolver` | 3+ failed audits with >80% code similarity |
| `aporia` | Unresolvable constraint relaxation |

### Formal Verification Chain
1. **AST Parse** (`ast_parser.py`) - Syntax & dependency check
2. **QWED Logic** (`qwed_engine.py`) - 2-pass (2B -> 4B if logic_score < 0.6)
3. **SymPy Math** (`sympy_engine.py`) - parse_expr() secure parsing
4. **Z3 SAT** (`z3_engine.py`) - Phi-4 Mini -> SMT-LIB2 -> solver.check()
5. **LLM Audit** (`llm_verifier.py`) - Phi-4 Mini final reasoning pass

### Checkpointer Validation
- `SqliteSaver` (patched sync) saves to `data/langgraph_checkpoints.sqlite`
- `_validate_checkpoint()` verifies state integrity on resume
- `ainvoke(None)` crash recovery in `control_handoff.py`

---

## 16. MCP ToolBridge Registration & Dual-Path Fallback

### Dynamic Tool Discovery
- `discover_and_register_mcp_tools(tool_bridge_cls)` queries all active MCP servers from `MCPRegistry` and registers them as class-level handlers with `{server_name}_{tool_name}` prefix.
- **Custom Interceptors (`_mcp_handlers`):** `remember` and `observe` must use custom handlers mapped in `_mcp_handlers` to support Axis 1 logs, failure memory, and `aobserve` calls. All other tools utilize dynamic generic handlers.
- **Fallback Execution:** When `SLM_ENABLED` is false or the SLM MCP server is unhealthy, the client gracefully falls back to the local database and model layer (`LanceDB + Ollama + Jina Reranker`) without throwing runtime errors.

---

## 17. Local-First Routing Protocol

### Model Selection Priority
1. `skill_loader.match_for_task(task)` -> skill
2. `skill.model_role` -> role
3. `model_registry.find_fitting_model(role, vram)` -> model
4. `self_tuner.get_best_model_for_role(role)` -> alternative if first fails

### CLOUD_AS_EXCEPTION Mandate
- Cloud Gateway (`generate_async`) may only be called for Tier 3 strategic/architectural tasks (complexity > 0.8) or when the entire local fallback chain has been exhausted. Every cloud call must be logged to Axis 1 with its justification.
- `MORPHEUS_SMART_SELECT` queries VRAM state and model coefficients before each draft, dynamically selecting the best fit from the 22 model variants in `ROLE_TO_MODEL`.

---

## 18. Token Preservation Mandate

### ASSISTANT_TOKEN_PRESERVATION_MANDATE (RULE-038)
- Native `view_file` tool is STRONGLY PROHIBITED due to its 800-line token bloat imposition.
- The agent MUST use `read_file` or `read_text_file` via the MCP filesystem server to read file contents.
- For research and search, prefer low-cost tools (`grep_search`, `glob`) over full-file reads.

---

Last Updated: 2026-05-25