savant-code 0.0.17 → 0.0.19

package/docs/design/database-architecture.md

@@ -0,0 +1,217 @@
+# 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

@@ -0,0 +1,295 @@
+# 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.