savant-code 0.0.19 → 0.0.20

package/docs/design/database-architecture.md

@@ -1,217 +0,0 @@
-# Database Architecture — `@savant-code/database`
-
-## Context
-
-**Agent**: Thinker  
-**Created**: 2026-07-16 (design session)  
-**Implemented**: 2026-07-16  
-**Status**: IMPLEMENTED  
-**Package**: `packages/database/`
-
-## Problem Statement
-
-The ECHO/Savant system stores vital state (session state, agent configurations, FID documents, message history, cost
-tracking) that needs durable, queryable storage. JSON files on disk have critical flaws:
-
-1. **Serialization cycles** — Live function references in session state objects cause `JSON.stringify` to fail when
-   cloning between runs
-2. **No durability** — Crashes, restarts, or hot reloads lose all state
-3. **No queryability** — Cannot search session history, track costs, or audit agent actions
-4. **Fragile state management** — Cloning in-memory objects between runs is error-prone
-
-## Solution
-
-SQLite database via `bun:sqlite` (Bun's built-in SQLite driver — no external dependency required).
-
-### Core Architecture
-
-```text
-┌─────────────────────────────────────────────────────────┐
-│                    ECHO System                          │
-├─────────────────────────────────────────────────────────┤
-│  Agent Runtime  │  Session Manager  │  FID Manager      │
-├─────────────────────────────────────────────────────────┤
-│                    Database Layer                       │
-│              packages/database/src/                     │
-├─────────────────────────────────────────────────────────┤
-│                 bun:sqlite (built-in)                   │
-├─────────────────────────────────────────────────────────┤
-│                  SQLite File                            │
-│              (~/.savant-free/echo.db)                   │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Database Schema (7 Tables)
-
-```sql
--- 0. Schema version tracking
-CREATE TABLE IF NOT EXISTS schema_version (
-  version INTEGER PRIMARY KEY,
-  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 1. Sessions: Core session state and metadata
-CREATE TABLE IF NOT EXISTS sessions (
-  id TEXT PRIMARY KEY,
-  chat_id TEXT NOT NULL,
-  agent_id TEXT NOT NULL,
-  selected_model TEXT DEFAULT '',
-  session_state TEXT NOT NULL,       -- Full SessionState blob (JSON serialized)
-  status TEXT DEFAULT 'active',
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 2. Agent Templates: Agent definition templates
-CREATE TABLE IF NOT EXISTS agent_templates (
-  id TEXT PRIMARY KEY,
-  template TEXT NOT NULL,            -- AgentTemplate blob (JSON serialized)
-  version INTEGER DEFAULT 1,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 3. Agent Configs: Runtime agent configurations (instance-specific)
-CREATE TABLE IF NOT EXISTS agent_configs (
-  id TEXT PRIMARY KEY,
-  session_id TEXT REFERENCES sessions(id),
-  template_id TEXT REFERENCES agent_templates(id),
-  config TEXT NOT NULL,              -- AgentConfig blob (JSON serialized)
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 4. FID Documents: Foundation Implementation Documents
-CREATE TABLE IF NOT EXISTS fid_documents (
-  id TEXT PRIMARY KEY,
-  session_id TEXT REFERENCES sessions(id),
-  content TEXT NOT NULL,             -- Markdown content
-  status TEXT DEFAULT 'draft',       -- draft, in_progress, complete
-  perfection_loop_phase TEXT DEFAULT 'idle',
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 5. Message History: Chat messages
-CREATE TABLE IF NOT EXISTS message_history (
-  id TEXT PRIMARY KEY,
-  session_id TEXT REFERENCES sessions(id),
-  role TEXT NOT NULL,
-  content TEXT NOT NULL,             -- MessageContent[] (JSON serialized)
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- 6. Cost Tracking: Cost and usage analytics
-CREATE TABLE IF NOT EXISTS cost_tracking (
-  id TEXT PRIMARY KEY,
-  session_id TEXT REFERENCES sessions(id),
-  agent_id TEXT NOT NULL,
-  credits_used REAL DEFAULT 0,
-  direct_credits_used REAL DEFAULT 0,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- Indexes for performance
-CREATE INDEX IF NOT EXISTS idx_sessions_chat_id ON sessions(chat_id);
-CREATE INDEX IF NOT EXISTS idx_sessions_agent_id ON sessions(agent_id);
-CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
-CREATE INDEX IF NOT EXISTS idx_fid_documents_session_id ON fid_documents(session_id);
-CREATE INDEX IF NOT EXISTS idx_fid_documents_status ON fid_documents(status);
-CREATE INDEX IF NOT EXISTS idx_message_history_session_id ON message_history(session_id);
-CREATE INDEX IF NOT EXISTS idx_cost_tracking_session_id ON cost_tracking(session_id);
-CREATE INDEX IF NOT EXISTS idx_cost_tracking_agent_id ON cost_tracking(agent_id);
-```
-
-### Service Layer
-
-`packages/database/src/service.ts` provides typed CRUD operations for all tables:
-
-| Function | Table | Purpose |
-|----------|-------|---------|
-| `createSession()` | sessions | Create a new session with agent state |
-| `getSession()` | sessions | Load session by ID (deserializes JSON state) |
-| `updateSession()` | sessions | Persist updated session state |
-| `getSessionsByChatId()` | sessions | List sessions for a chat |
-| `updateSessionModel()` / `saveModel()` / `getLatestModel()` | sessions | Model selection persistence |
-| `createAgentTemplate()` | agent_templates | Register agent definition |
-| `createAgentConfig()` | agent_configs | Create instance-specific config |
-| `createFidDocument()` | fid_documents | Create FID with markdown content |
-| `updateFidDocument()` | fid_documents | Update content, status, FSM phase |
-| `createMessage()` | message_history | Store chat message |
-| `getMessagesBySessionId()` | message_history | Retrieve session history |
-| `createCostRecord()` | cost_tracking | Record agent usage costs |
-| `getTotalCostBySessionId()` | cost_tracking | Aggregate costs for a session |
-
-## Technical Decisions
-
-### Decision 1: SQLite via `bun:sqlite`
-
-**Choice**: Use Bun's built-in `bun:sqlite` driver (zero external dependencies).  
-**Rationale**:
-
-- Ships with Bun — no `npm install` needed
-- Synchronous API (simpler error handling, no async overhead)
-- WAL mode for crash recovery and concurrent reads
-- Foreign key support enabled by default
-- File-based — single `echo.db` file, easy to backup/restore
-
-**Alternatives Considered**:
-
-- `better-sqlite3`: External dependency, same API shape, but `bun:sqlite` is equivalent and built-in
-- PostgreSQL: Requires server process, overkill for local CLI tool
-- `drizzle-orm`: Schema abstraction layer — adds complexity without benefit for this simple schema
-
-### Decision 2: TEXT Columns + Manual JSON Serialization
-
-**Choice**: Store complex data as `TEXT` columns with `JSON.stringify()`/`JSON.parse()` in the service layer.  
-**Rationale**:
-
-- Session state is a black box (server protocol, different shapes per agent)
-- Agent configs are dynamic (different tool sets, model options)
-- Simpler schema — fewer tables, no ORM
-- SQLite JSON functions (`json_extract`, etc.) available if needed later
-
-**Alternatives Considered**:
-
-- SQLite native JSON columns: Less portable, `bun:sqlite` treats JSON as TEXT anyway
-- Fully normalized schema: Too rigid, breaks when session state schema changes
-
-### Decision 3: Global Storage Location
-
-**Choice**: Store database at `~/.savant-free/echo.db`  
-**Rationale**:
-
-- Persists across projects
-- Follows XDG conventions (`~/.config/` or `~/.local/share/` pattern)
-- Easy to backup/restore (single file)
-- Single database for all sessions
-
-### Decision 4: WAL Mode
-
-**Choice**: Enable Write-Ahead Logging (`PRAGMA journal_mode = WAL`)  
-**Rationale**:
-
-- Crash recovery — committed transactions survive process kills
-- Concurrent reads — multiple processes can read while one writes
-- Performance — faster than rollback journal for mixed read/write workloads
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `packages/database/src/index.ts` | DB connection, schema creation, exports |
-| `packages/database/src/service.ts` | Typed CRUD operations for all tables |
-| `packages/database/package.json` | `@savant-code/database` workspace package |
-| `packages/database/tsconfig.json` | TypeScript config |
-| `packages/database/README.md` | Package documentation |
-
-## Status
-
-- [x] Schema design complete
-- [x] `bun:sqlite` connection + WAL mode
-- [x] All 7 tables created with indexes
-- [x] Service layer with typed CRUD operations
-- [x] Session state serialization/deserialization
-- [x] Model selection persistence
-- [x] FID document storage
-- [x] Message history storage
-- [x] Cost tracking aggregation

package/docs/design/deep-research-report.md

@@ -1,295 +0,0 @@
-# Savant Perfection Loop System Design
-
-**Summary:** We apply *loop engineering* principles to Savant’s multi-agent framework (9 agents including Orchestrator,
-Detective, Forge, Verifier, etc.) under the “Perfection Loop” protocol (RED→GREEN→AUDIT→COMPLETE phases). Drawing on
-Osmani, Greyling, and LangChain, we map loop components to each agent role and design a Rust/TypeScript harness. Key
-elements include a stateful **PerfectionLoopPhase** FSM, a **SequentialThinkingServer** (Thinker) to coordinate agents,
-robust handoffs with persistent loop state, circuit-breakers to halt runaway cycles, and a “double audit” (AI verifier +
-static analyzers) in the AUDIT phase. The following document outlines the system architecture, data models, and
-implementation roadmap.
-
----
-
-## Loop Architecture Mapping
-
-Loop engineering treats the agent workflow as a **recursive, automated cycle** rather than manual prompting. Greyling
-articulates that a production loop is “a small system with six parts” (five capabilities + persistent memory). Savant’s
-9-agent roster aligns with these components:
-
-- **Automations (Scheduler):** The **Orchestrator** agent implements Greyling’s “heartbeat”. It schedules loop
-  iterations (e.g. via cron or in-process timers) and triggers each cycle automatically. This corresponds to Osmani’s
-  notion of automated discovery/triage.
-- **Workspaces (Isolation):** Each agent run occurs in an isolated git **worktree**. Parallel Forge/Verifier processes
-  use separate checkouts (or containers) so they don’t collide on the repo. The harness automatically cleans up these
-  worktrees per Greyling’s guidance.
-- **Project Knowledge (Skills):** Shared knowledge (coding conventions, APIs) is codified in a **Memory/KnowledgeBase**.
-  For example, a `skills.md` or database of schema prevents agents from re-deriving project context each run. The
-  **Detective** agent may manage this memory, providing context to others.
-- **Connectors/Plugins:** All agents (via the Orchestrator) use a common tool interface (MCP plugins) to interact with
-  real systems (e.g. GitHub, build servers, etc.). This maps to Osmani’s “plugins/connectors” and lets Savant agents act
-  (open PRs, run CLI tests) rather than just suggest.
-- **Sub-Agents (Maker/Checker):** Savant enforces a strict maker-checker pattern. One agent (e.g. **Forge**) generates
-  code changes, and a separate **Verifier** agent (often with a “stronger” model or specialist logic) checks them
-  against tests/specs. This prevents the generator from “grading its own homework,” as Greyling notes.
-- **Persistent Memory (State):** The loop’s **state file** (e.g. `STATE.json` or database) answers “What are we working
-  on? What happened last run?”. The **Thinker** (SequentialThinkingServer) maintains this FSM state
-  (`PerfectionLoopPhase`, iteration count, logs) across agent calls. All agents read/write this shared state so no
-  context is lost.
-
-These loop components map to the RED/GREEN/AUDIT/COMPLETE FSM as follows:  
-
-- **RED (Failure/Investigate):** When tests fail or issues are detected, the system enters RED. The Detective analyzes
-  failures (stack traces, logs) and records them. Based on this analysis, Thinker updates `PerfectionLoopPhase = RED`
-  and signals Forge to generate fixes. This embodies the “investigate” step.
-- **GREEN (Fix & Verify):** After Forge proposes code changes, the Verifier (via the Thinker) runs the test suite.
-  Passing tests transition the state to GREEN. (If tests still fail, the Thinker stays in RED to continue looping.) In
-  Green, **Orchestrator** holds code confidently, preparing to audit.
-- **AUDIT (Deep Verification):** On GREEN, the system enters AUDIT. Here, a multi-pronged verification occurs: the
-  Verifier agent examines the solution’s correctness and coverage, while static analysis tools (“bashers”) check the
-  code graph and security constraints. Only an independent check (not the Forge’s own say-so) can approve this step. If
-  audit passes, phase transitions to COMPLETE; if not, Thinker drops back to RED for further fixes.
-- **COMPLETE (Done):** All checks have passed. The loop exits (or pauses) until new tasks arrive. The Thinker marks
-  completion and may emit a final report for human review.
-
-```mermaid
-stateDiagram-v2
-    [*] --> RED: Start or test failure  
-    RED --> GREEN: Tests pass (fix applied)  
-    GREEN --> AUDIT: Proceed to audit  
-    AUDIT --> COMPLETE: Audit passed  
-    AUDIT --> RED: Audit failed (refine code)  
-    COMPLETE --> [*]  
-```
-*State machine for Savant’s Perfection Loop (RED→GREEN→AUDIT→COMPLETE).*  
-
-Each arrow in the above FSM corresponds to transitions enforced by the Orchestrator and Thinker logic. For example,
-*VERIFIER* driving tests from RED to GREEN, and *AUDITOR* driving from AUDIT to COMPLETE. This loop closely follows
-Osmani’s pattern “investigate, implement, verify, repeat” with an independent verification at each cycle.
-
-## Codebuff Transformation Plan
-
-The existing Codebuff CLI (in `CodebuffAI/codebuff`) is a TypeScript monorepo with these key modules:
-
-- `cli/`: Interactive TUI client and main entrypoint  
-- `packages/agent-runtime/`: Core orchestration of prompts/tools  
-- `packages/code-map/`: Source parsing and code-location helpers  
-- `agents/`: Definitions of built-in AI agents and prompts  
-- `sdk/`: JS/TS SDK for external use  
-- `common/`: Shared types and utilities  
-
-To integrate the Perfection Loop, we must adapt these modules:
-
-1. **CLI Entry Points:** Extend the `cli/index.ts` to accept new mode flags (`--perfection-loop`, `--fid-bound`,
-   `--hybrid`) and to invoke the loop harness instead of a one-shot agent run. For example, the `codebuff init` command
-   (Day 4 launch) will spawn the Thinker server and begin scheduled iterations. We will *strip* or disable any purely
-   interactive flows, and add *hybrid mode* options (see below).
-2. **Orchestrator Logic:** Insert a new Orchestrator component (in `packages/agent-runtime` or a new `orchestrator/`
-   folder) that implements the RED→GREEN→AUDIT cycle. This may reuse parts of the existing runtime (which already
-   invokes agents and test runners), but must be extended to loop. It should handle state persistence (saving
-   `PerfectionLoopPhase` and iteration counts) before/after each agent call.
-3. **FID-Bound Execution:** We add support for *Function-ID–bounded* fixes. In practice, the CLI will parse a `--fid
-   <identifier>` flag or an explicit pointer to a code location (e.g. file+function name). The Forge agent will then
-   restrict edits to that scope. This likely means modifying the code-selection logic in `packages/code-map` and
-   `agents/forge/`. We will also adjust the test invocation so only relevant tests (based on the code scope) run,
-   passing context to the Verifier.
-4. **Hybrid Mode:** Codebuff’s blog mentions “--max” unlocking a Gemini/Sonnet hybrid model. Hybrid Mode here likely
-   means mixing open and proprietary models or mixing AI with deterministic transformations. Architecturally, we will
-   allow the Forge and Verifier to use either open models (e.g. Llama, Gem2 Flash) or closed models (e.g. Sonnet) based
-   on user config. This requires parameterizing the LLM provider in `packages/llm-providers/` and updating the CLI to
-   accept `--mode hybrid`.
-5. **Execution Flow Adjustments:** Remove any assumptions of a single-pass run. For example, Codebuff normally stops
-   after one repair; instead, we will loop until Thinker signals COMPLETE. We must embed the circuit-breaker checks
-   (below) at loop boundaries, so that after each Forge/Verifier invocation the system may break out to human review if
-   needed.
-6. **State and Logging:** Codebuff already has minimal state (e.g. `codebuff.json`); we will introduce a structured
-   `LoopState` persisted between runs (in Rust side or a `state.json`). The CLI should load/update this state.
-7. **Testing and Audit Hooks:** The CLI’s testing routine (in `cli` or `agent-runtime`) must now feed results to the
-   Thinker. We may extract existing test invocation (`npm test` or `cargo test`) into a callable function so that the
-   Orchestrator can interpret pass/fail and reroute the flow. Similarly, we will embed calls to static analyzers (e.g.
-   `bun run lint`, `cargo clippy`) in the AUDIT phase.
-
-In summary, **modules to strip/extend**: disable the legacy one-shot handler in `cli/`; modify `packages/agent-runtime`
-to include loop control; extend `code-map`, `llm-providers`, and agent prompts for FID/Hybrid modes; and add new
-orchestrator, circuit-breaker, and audit subsystems.
-
-## State Management & Handoffs
-
-We define a shared state and a coordinator to preserve context across agents:
-
-- **PerfectionLoopPhase FSM:** Define in Rust and TypeScript as:  
-  ```rust
-  // Rust
-  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-  enum PerfectionLoopPhase { Red, Green, Audit, Complete }
-  struct LoopState {
-      phase: PerfectionLoopPhase,
-      iteration: u64,
-      last_error: Option<String>,
-      history: Vec<String>, // e.g. commit hashes or error messages
-  }
-  ```  
-  ```typescript
-  // TypeScript
-  type PerfectionLoopPhase = "Red" | "Green" | "Audit" | "Complete";
-  interface LoopState {
-      phase: PerfectionLoopPhase;
-      iteration: number;
-      lastError?: string;
-      history: string[];  // e.g. list of error IDs or code diffs
-  }
-  ```  
-  This state lives in a durable store (e.g. a JSON file or database). It is loaded at loop start and updated after each
-agent action.
-
-- **SequentialThinkingServer (Thinker):** A lightweight service (e.g. a Rust HTTP/gRPC server or a long-running TS
-  process) holds `LoopState` in memory. Agents send requests to Thinker to report results or ask for next steps. For
-  instance, after Forge finishes a code edit, it sends `POST /report-code?commit=XYZ`, and Thinker updates state to
-  `phase = Green` or stays in `Red`. Thinker’s API can enforce circuit-breakers before returning “continue” or “halt” to
-  Orchestrator.
-
-- **Sequence Diagram:** The typical agent interaction is:  
-
-  ```mermaid
-  sequenceDiagram
-    participant O as Orchestrator
-    participant D as Detective
-    participant F as Forge
-    participant V as Verifier
-    participant T as Thinker
-
-    O->>D: Analyze codebase (discover tasks)
-    D->>T: Report identified issues (phase=Red)
-    T->>F: Instruct code generation (phase=Red→Green)
-    F->>T: Return with proposed patch
-    T->>V: Trigger tests on patch (phase=Green)
-    V->>T: Send test result
-    alt Tests Passed
-        T->>V: Trigger audit checks (phase=Audit)
-        V->>T: Send audit result
-        alt Audit Passed
-            T->>O: Report success (phase=Complete)
-        else Audit Failed
-            T->>O: Report findings (phase→Red)
-        end
-    else Tests Failed
-        T->>O: Request rework (remain in Red)
-    end
-  ```
-
-  Each arrow is a context-ful API call. For example, after tests, Verifier posts results and `Thinker` transitions the
-state. This sequence ensures **no context is lost**: each agent’s output (errors, diffs) is appended to
-`LoopState.history` before moving on.
-
-- **Data Handoffs:** Between agents, the Thinker serializes the relevant context. For example, when transitioning
-  RED→GREEN, the Thinker may include in its instruction the specific function or test suite to re-run. We may define a
-  common message format like:
-  ```typescript
-  interface AgentMessage {
-      phase: PerfectionLoopPhase;
-      iteration: number;
-      payload: any;  // e.g. errors list, code diff, test summary
-  }
-  ```
-  This is passed via HTTP or message queue. By embedding `phase` and `iteration`, we ensure agents always know the
-current loop context. Persistent memory (e.g. a `STATE.json` checked into the repo or a database) guarantees that if the
-orchestrator or server restarts, the loop can resume where it left off.
-
-## Circuit Breaker Implementation
-
-To prevent infinite loops, we implement **circuit-breaker rules** that analyze each iteration’s results:
-
-- **Levenshtein Cap (10% rule):** After each code edit, compute the Levenshtein distance between the previous and
-  current code version. If the change exceeds 10% of the file’s length, trigger the breaker. (This avoids wildly
-  oscillating edits.)
-- **Repetition/Convergence:** Track recent diffs in `LoopState.history`. If the same failure or similar code diff
-  repeats *N* times, or if diffs converge below a minimal threshold (i.e. no real change), trip the breaker. This
-  detects oscillation or stagnation.
-- **Token/Iteration Limits:** Enforce a max iteration count or API token budget per loop. Beyond that, the Thinker
-  returns an “escalate” signal.
-
-These checks run at the **start of each iteration**. A simplified flowchart:
-
-```mermaid
-flowchart LR
-    Start(["Begin Iteration"]) --> ComputeDiff{Compute code diff (Levenshtein %)}
-    ComputeDiff -- >10% --> Trip[Trip Circuit-Breaker]
-    ComputeDiff -- <=10% --> CheckOsc{Repeated/Oscillating?}
-    CheckOsc -- Yes --> Trip
-    CheckOsc -- No --> CheckLimit{Max attempts?}
-    CheckLimit -- Yes --> Trip
-    CheckLimit -- No --> Continue["Proceed with loop"]
-```
-
-If `Trip` is reached, the loop exits to **human review** instead of retrying. We implement this in a `CircuitBreaker`
-module (Rust/TS) that inspects `LoopState.history`. For example, in Rust:
-
-```rust
-struct CircuitBreaker {
-    max_diff: f64,           // e.g. 0.10
-    max_repeats: usize,      // e.g. 3
-    max_iterations: usize,   // e.g. 20
-}
-
-impl CircuitBreaker {
-    fn check(&self, state: &LoopState, new_code: &str) -> bool {
-        // Compute Levenshtein percent change:
-        let last_code = /* retrieve from state.history */;
-        let diff = levenshtein(&last_code, new_code) as f64 / last_code.len() as f64;
-        if diff > self.max_diff || state.iteration >= self.max_iterations {
-            return false; // trip circuit
-        }
-        // Additional logic for repeated diffs...
-        true // safe to continue
-    }
-}
-```
-
-In practice, we also scaffold a ledger (inspired by Greyling’s `loop-ledger.json`) to record consecutive failures.
-Before each retry, Orchestrator invokes this checker. On error, Thinker transitions to an **ESCALATE** state, triggering
-alerts. This ensures we **break** any runaway fix loops.
-
-## Double Audit Technical Spec
-
-During the AUDIT phase, we enforce **dual verification** before completing the loop:
-
-- **AI Verifier Agent:** A dedicated Verifier model (possibly a stronger LLM) reviews the code. It performs **call-graph
-  analysis** by parsing the code AST and ensuring that all functions/classes are reachable from entry points. It also
-  checks *business rules* captured in memory (e.g. security patterns, isolation). Its output is an `AuditReport`
-  structure, e.g.:
-  ```typescript
-  interface AuditReport {
-      verdict: "pass" | "fail";
-      unreachableFunctions: string[];  // unused code detected
-      disallowedCalls: string[];      // e.g. dynamic eval or unsafe I/O
-      callGraphCoverage: number;      // 0–100%
-      notes: string;
-  }
-  ```
-  If any `verdict` is `"fail"`, it reports errors back to Thinker.
-
-- **Static Analysis Tools:** In parallel, we run **traditional analyzers**. For Rust/TypeScript, this might include
-  `cargo check`, `clippy`, ESLint, type-checkers, and domain-specific linters. These are shell-invoked from the CLI.
-  Their findings (errors, warnings) form a `StaticReport`. We require **isolation**: e.g., ensure no forbidden syscalls
-  or library calls are introduced. A sample report type:
-  ```typescript
-  interface StaticReport {
-      success: boolean;
-      errors: string[];
-      warnings: string[];
-  }
-  ```
-
-- **Enforcement:** Thinker only permits progression to COMPLETE if *both* the AI Verifier’s `AuditReport.verdict` is
-  pass *and* the static tools `success` is true. Any issues (e.g. unreachable code, style violations, security flags)
-  cause Thinker to loop back to RED for fixes. This double-layer audit provides evidence that the code is robust,
-  meeting Osmani’s “quality checks” standard before shipping.
-
-Finally, if **both checks pass**, Thinker marks the loop as COMPLETE and outputs a final summary (the “verdict”). This
-architecture ensures all AI-generated code is cross-validated by independent methods (agentic and deterministic),
-embodying Greyling’s and Osmani’s emphasis on independent verification.
-
----
-
-**Sources:** The above design applies loop engineering concepts from Osmani’s and Greyling’s essays and LangChain’s
-multi-loop pattern to Savant’s agents and state machine.  Codebuff’s repository structure informs the module
-transformation plan. All architectural decisions are grounded in these references and the supplied Savant constraints.