{"slug":"strategy/product-strategy/TRIAGE_BOT_SPEC","title":"Triage Bot & Book of Projects Specification","section":"strategy","sectionLabel":"Strategy","status":"current","type":"document","path":"strategy/product-strategy/TRIAGE_BOT_SPEC.mdx","bytes":5127,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** Active\n> **Context:** Governs the ingestion of institutional knowledge (Decisions, Commitments, Learnings, Episodes) into the Book of Projects (`memory.org_memory`).\n\n## 1. The Core Principle: Spine vs. Book of Projects\n\nIntegrateWise maintains a strict architectural boundary between operational truth and institutional memory:\n\n- **The Spine (Operational Truth):** What the business knows about the world right now. Mutable, continuous, flat entities (Accounts, Deals, Tasks).\n- **The Book of Projects (Institutional Memory):** What the business knows about itself. Append-only, episodic, versioned graphs of knowledge (Decisions, Learnings, Episodes).\n\n### Conflation is a System-Level Failure\n\nPutting Decisions/Learnings into the Spine breaks governance, update patterns, data shape, and consumption.\nThe Book of Projects connects to the Spine **only via directional entity references** (`entity_ref`). The Spine does not know about the Book of Projects.\n\n## 2. Sole Writer Architecture\n\nThe Book of Projects (`memory.org_memory`) is **append-only** and **highly governed**. It is never written to directly by user tools, standard sync pipelines, or general backend processes.\n\n**The Triage Bot is the sole writer to the Book of Projects.**\n\n### Write Pipeline\n\n1. **Source:** Twin reasoning, human judgment (HITL via Ops Surface), or pattern recognition generates a \"Knowledge Proposal\" (e.g., a new Decision or Learning).\n2. **Staging:** The Proposal lands in the Triage Bot's staging queue (`proposal_queue`).\n3. **Scoring & Review:** The Triage Bot evaluates the proposal against organizational doctrine and routes it to a human-in-the-loop (HITL) if the confidence/impact requires it.\n4. **Commit:** Only after approval does the Triage Bot write the append-only entry into `memory.org_memory` (and its R2 backing store for large narrative context).\n\n## 3. Proposal Schema for Institutional Knowledge\n\nWhen an agent or system proposes knowledge for the Book of Projects, it must use the `memory.propose` interface. Direct `upsert` or `write` commands to `org_memory` are banned.\n\n```typescript\ntype KnowledgeCategory = \"decision\" | \"commitment\" | \"learning\" | \"episode\" | \"doctrine\";\n\ninterface KnowledgeProposal {\n  category: KnowledgeCategory;\n  title: string;\n  narrative_content: string; // The episodic context\n  entity_refs: string[]; // e.g., [\"account:Northwind\", \"deal:Renewal Q2\"]\n  source_evidence: any[]; // Links to the conversational memory, email, or signal that led to this\n  confidence_score: number;\n}\n```\n\n## 4. Triage Bot Governance Scoring & Staging\n\nThe Triage Bot evaluates every incoming memory or knowledge proposal against four scoring vectors to compute the final **Confidence Score ($S_c$)**:\n\n$$S_c = (W_{ev} \\cdot S_{ev}) + (W_{co} \\cdot S_{co}) + (W_{re} \\cdot S_{re}) + (W_{se} \\cdot S_{se})$$\n\nWhere:\n\n- **Evidence Score ($S_{ev}$)**: Weights the presence of trace IDs, source document links, or email logs. Missing evidence reduces this score.\n- **Coherence Score ($S_{co}$)**: Checks if the proposal contradicts existing locked doctrine or approved history.\n- **Relevance Score ($S_{re}$)**: Evaluates semantic similarity to L1 spine entities in the active schema.\n- **Sentiment Coherence ($S_{se}$)**: Evaluates sentiment consistency between conversation logs and proposed insights.\n\n### Governance Action Rails:\n\n- **Auto-Approve ($S_c \\ge 0.85$ and Category = `'learning'`)**: Automatically committed to `consolidated_memories` and cached in D1 edge.\n- **HITL Review Required ($0.50 \\le S_c < 0.85$ or Category $\\in$ `['decision', 'commitment', 'doctrine']`)**: Staged in `ai_memories` with `status = 'pending_review'`. Surfaces in the human Command Center for manual approval/edit.\n- **Auto-Reject ($S_c < 0.50$)**: Dropped with an entry to the `normalization_errors` table for auditing.\n\n---\n\n## 5. Dual-Write Memory Promotion Execution\n\nUpon human or automated approval, the promotion workflow performs a transactional dual-write:\n\n1.  **Supabase Postgres Write**: Inserts the record into the permanent `public.consolidated_memories` table, index-linked to entity IDs and equipped with pgvector embeddings for future semantic search query retrieval.\n2.  **Filesystem Vault Write**: Writes a sanitized, markdown file containing the memory narrative and trace logs to the persistent filesystem directory `/org-memory/` to guarantee permanent offline access.\n3.  **Edge Sync**: Pushes the consolidated record to the local edge `D1` SQLite mirror and invalidates the active `KV` cache signal window.\n\n---\n\n## 6. The Twin Context Assembly (Dual Read)\n\nWhen the Twin requires context to answer a query or generate a recommendation, it must assemble context from both stores:\n\n1.  **Spine Read**: Gets the current state (e.g., Account health, Deal stage, Open tasks).\n2.  **Book of Projects Read**: Gets the institutional history for the referenced entities (e.g., Past decisions, Escalations, Learnings).\n\nThis ensures the Twin's reasoning benefits from both real-time operational data and permanent institutional memory.\n"}