PLAN.md [component] deterministic

Recipe Compiler Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** Build a SQLite-based Recipe Compiler that captures AI decision records with full-text search, immutability, and version tracking.

**Architecture:** Single-file SQLite database with FTS5 for full-text search, immutable recipe records, and HTTP API for ingestion.

**Tech Stack:** Python 3.11+, SQLite, FTS5, FastAPI (for HTTP API), pytest

---

Task 1: Create Recipe Data Model

**Objective:** Define the Recipe dataclass with all required fields.

**Files:** - Create: src/recipe_compiler/models.py

**Step 1: Write the data model**

```python from dataclasses import dataclass, field from datetime import datetime from typing import List, Optional import uuid

@dataclass class Recipe: """Immutable AI decision record.""" # Core identity id: str = field(default_factory=lambda: f"recipe-{datetime.now().strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:6]}") # Objective - what was the task? objective: str # Model configuration model: str = "" # e.g., "qwen3.5", "llama3.1" model_version: Optional[str] = None # Memory state memory_version: int = 0 retrieved_docs: List[str] = field(default_factory=list) # doc IDs # Prompt versioning prompt_version: int = 0 prompt_hash: Optional[str] = None # Reasoning patterns used reasoning_patterns: List[str] = field(default_factory=list) # e.g., ["compare", "retrieve", "synthesize"] # Evaluation evaluation_score: Optional[float] = None # 0.0 to 1.0 evaluation_reviewed_by: Optional[str] = None # "expert", "auto", etc. # Outcome outcome: str = "unknown" # "accepted", "rejected", "needs_revision" outcome_notes: Optional[str] = None # Metadata created_at: datetime = field(default_factory=datetime.now) updated_at: Optional[datetime] = None tags: List[str] = field(default_factory=list) # Raw capture raw_prompt: Optional[str] = None raw_output: Optional[str] = None raw_context: Optional[dict] = field(default_factory=dict) def mark_updated(self): """Mark recipe as updated.""" self.updated_at = datetime.now() ```

**Step 2: Commit**

bash git add src/recipe_compiler/models.py git commit -m "feat: add Recipe data model with all fields"

---

Task 2: Create SQLite Database Schema with FTS5

**Objective:** Create the database schema with full-text search support.

**Files:** - Create: src/recipe_compiler/schema.py

**Step 1: Define the schema**

```python import sqlite3 from datetime import datetime from typing import Optional from dataclasses import dataclass, field

@dataclass class SchemaManager: """Manages the SQLite database schema for the Recipe Compiler.""" db_path: str def init_db(self): """Initialize the database with all tables and FTS5.""" conn = sqlite3.connect(self.db_path) cursor = conn.cursor() # Main recipes table cursor.execute(""" CREATE TABLE IF NOT EXISTS recipes ( id TEXT PRIMARY KEY, objective TEXT NOT NULL, model TEXT DEFAULT '', model_version TEXT, memory_version INTEGER DEFAULT 0, prompt_version INTEGER DEFAULT 0, prompt_hash TEXT, evaluation_score REAL, evaluation_reviewed_by TEXT, outcome TEXT DEFAULT 'unknown', outcome_notes TEXT, created_at TEXT NOT NULL, updated_at TEXT, raw_prompt TEXT, raw_output TEXT, raw_context TEXT ) """) # Recipe-Document relationships cursor.execute(""" CREATE TABLE IF NOT EXISTS recipe_docs ( id TEXT PRIMARY KEY, recipe_id TEXT NOT NULL, doc_id TEXT NOT NULL, FOREIGN KEY (recipe_id) REFERENCES recipes(id) ON DELETE CASCADE ) """) # Recipe-Tag relationships cursor.execute(""" CREATE TABLE IF NOT EXISTS recipe_tags ( id TEXT PRIMARY KEY, recipe_id TEXT NOT NULL, tag TEXT NOT NULL, FOREIGN KEY (recipe_id) REFERENCES recipes(id) ON DELETE CASCADE ) """) # Recipe-Pattern relationships cursor.execute(""" CREATE TABLE IF NOT EXISTS recipe_patterns ( id TEXT PRIMARY KEY, recipe_id TEXT NOT NULL, pattern TEXT NOT NULL, FOREIGN KEY (recipe_id) REFERENCES recipes(id) ON DELETE CASCADE ) """) # FTS5 virtual table for full-text search cursor.execute(""" CREATE VIRTUAL TABLE IF NOT EXISTS recipes_fts USING fts5( id, objective, model, model_version, evaluation_score, outcome, outcome_notes, created_at, content='recipes', content_rowid='rowid' ) """) # Triggers to keep FTS in sync cursor.execute(""" CREATE TRIGGER IF NOT EXISTS recipes_ai AFTER INSERT ON recipes BEGIN INSERT INTO recipes_fts(id, objective, model, model_version, evaluation_score, outcome, outcome_notes, created_at) VALUES (new.id, new.objective, new.model, new.model_version, new.evaluation_score, new.outcome, new.outcome_notes, new.created_at); END """) cursor.execute(""" CREATE TRIGGER IF NOT EXISTS recipes_au AFTER UPDATE ON recipes BEGIN DELETE FROM recipes_fts WHER