> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spineworkspace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 02 — Execution Flow

> The end-to-end triage execution flow from intake trigger through classification, staging, and governed promotion.

# Triage System — Execution Flow

## Two-Path Mapping

Triage spans the **User Path** (human experience) and **System Path** (operational pipeline). The diagram below shows which steps belong to which path.

```
┌─────────────────── SYSTEM PATH ───────────────────────────────┐
│                                                               │
│  Intake → Classify → Link → Dedup → Stage → Audit            │
│                                                               │
└───────────────────────────┬───────────────────────────────────┘
                            │
                     ┌──────▼──────┐
                     │  BOUNDARY   │
                     │  Candidates │
                     │  flow to    │
                     │  User Path  │
                     └──────┬──────┘
                            │
┌───────────────────────────▼───────────────────────────────────┐
│                                                               │
│  User Path: Discover → Understand → Contextualize → DECIDE   │
│                                                               │
└───────────────────────────┬───────────────────────────────────┘
                            │
                     ┌──────▼──────┐
                     │  BOUNDARY   │
                     │  Decisions  │
                     │  flow to    │
                     │  System Path│
                     └──────┬──────┘
                            │
┌───────────────────────────▼───────────────────────────────────┐
│                                                               │
│  System Path: Consolidate → Promote → Index → Consume        │
│                                                               │
└───────────────────────────────────────────────────────────────┘
```

| Phase | Path | Steps |
| - | - | - |
| **Intake & Classification** | System | Intake → Classify → Link → Dedup → Stage → Audit |
| **Governance Decision** | User | Discover → Understand → Contextualize → Decide (approve/reject/defer) |
| **Promotion & Indexing** | System | Consolidate → Promote → Index → Consume |

**Neither path can bypass the other.** The System Path never writes canonical memory. The User Path never classifies.

## End-to-End Data Flow

```
┌─────────────────────────────────────────────────────────────┐
│                    INTAKE SOURCES                            │
│  MCP Capture · Conversation Archive · Session · Manual       │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                  TRIAGE INTAKE                               │
│  iw-agent-runtime TriageAgent (Durable Object)              │
│  - classify(content) → route                                │
│  - triage_items (operational state)                         │
│  - emitTriageInput → Continuity service                     │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              COGNITIVE TRIAGE (intelligence)                 │
│  TriageAgent (WorkflowStep)                                 │
│  - 4 Cognitive Dimensions: classify, link, review, govern   │
│  - Output: STAGE_FOR_REVIEW or REJECT                       │
│  - No AUTO_APPROVE for org memory                           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                  DURABLE WORKFLOW                            │
│  TriageWorkflow (Cloudflare Workflow)                       │
│  - Routes pending_approval → HITL DLQ                       │
│  - Routes rejected → terminal                               │
│  - NO direct writes to R2/Vectorize/D1/Pipeline             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              KNOWLEDGE SERVICE (triage-bot)                  │
│  AI extraction (Workers AI)                                 │
│  - All outputs: approval_status = 'pending'                 │
│  - Writes to triage_results (Neon/D1)                       │
│  - Slack notification (review channel, not authority)        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              HUMAN IN THE LOOP                              │
│  Knowledge Service: PATCH /v1/knowledge/triage/:id          │
│  - Authenticated principal                                  │
│  - Tenant authority                                         │
│  - Optimistic/version check                                 │
│  - Actions: approve | discard | defer                       │
└──────────┬─────────────────────┬────────────────────────────┘
           │                     │
     ┌─────▼─────┐        ┌─────▼─────┐
     │  approve   │        │  discard  │
     └─────┬─────┘        └─────┬─────┘
           │                     │
           ▼                     ▼
┌──────────────────┐    ┌──────────────┐
│  QUEUE:          │    │  TERMINAL    │
│  consolidation   │    │  No memory   │
│  trigger         │    │  published   │
└────────┬─────────┘    └──────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│         MEMORY CONSOLIDATOR (scheduled worker)              │
│  - Hourly: topic clustering of recent sessions              │
│  - Daily: user/account consolidation + health signals       │
│  - Weekly: cross-account patterns + best practices          │
│  - Reads approved triage items only                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│         CANONICAL PROMOTION (pipeline/memory-promoter)      │
│  - scoreForPromotion() — 7 Promotion Signals                │
│  - Governance gate: staging vs approved                     │
│  - Writes to org_memory (D1)                                │
│  - Audit trail (memory_promotion_audit)                     │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│         INDEXING (pipeline/memory-indexer)                   │
│  - Bulk index approved org_memory → AI Search               │
│  - Markdown + metadata per vector                           │
│  - Idempotent re-upload                                     │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│         CONSUMER                                           │
│  Twin reads published memory through bounded context        │
│  projection — never raw canonical storage                   │
└─────────────────────────────────────────────────────────────┘
```

## Step-by-Step Walkthrough

### Step 1: Intake

An event arrives from one of:

* **MCP Connector** — saves session memory after a tool call
* **Conversation Archive** — triggers extraction when a conversation is archived
* **Session Triage** — `/v1/triage/session` endpoint receives session summary
* **Manual Trigger** — admin triggers triage via API

The `iw-agent-runtime` `TriageAgent` (Durable Object) receives the event, classifies it by simple pattern matching, and stores it as a `triage_item` in operational state.

### Step 2: Continuity Emission

The TriageAgent calls `emitTriageInput()` which posts to the Continuity service at `http://internal/v1/continuity/events`. This creates a cognition/system event in the continuity stream.

### Step 3: Cognitive Evaluation

If the event qualifies for cognitive triage (higher-stakes content), the `intelligence` service's `TriageAgent` performs a deep evaluation:

1. **Intelligent Categorization** — What is the true intent? (Lead, Document, Operational Request)
2. **Contextual Linking** — How does this relate to canonical memory? Which entities does it touch?
3. **Canonical Review** — Is it stale? Duplicate? Conflicts with established truths?
4. **Guardrails & Governance** — Based on sensitivity, should it be staged for review or rejected?

Output is strictly: `"STAGE_FOR_REVIEW"` or `"REJECT"`. **No AUTO\_APPROVE.**

### Step 4: Workflow Routing

The `TriageWorkflow` durable workflow routes the result:

* **`pending_approval`** → sent to HITL DLQ (Human-In-The-Loop Dead Letter Queue)
* **`rejected`** → terminal state, no memory published
* **`approved`** (legacy — should not occur after patching) → treated as staging\_for\_review

**No direct writes to R2, Pipeline, D1, or Vectorize from this workflow.**

### Step 5: Knowledge Extraction

The `knowledge` service's `triage-bot.ts` extracts structured knowledge using Workers AI:

* Memory types: insight, preference, fact, decision, action\_item, relationship
* All extractions written to `triage_results` with `approval_status = 'pending'`
* Slack notification sent for review (channel, not authority bypass)

### Step 6: Human Review

A human reviews the triage item via:

* **Workspace Triage Inbox** — `GET /v1/knowledge/inbox` shows pending/deferred items
* **Slack Reactions** — ✅ Approve, ❌ Discard, ⏰ Defer (must be verified as approval event)
* **API** — `PATCH /v1/knowledge/triage/:id` with action: approve/discard/defer

The approval endpoint requires:

1. Authenticated principal
2. Tenant authority
3. Optimistic/version check
4. Approver identity and timestamp
5. Immutable decision audit

### Step 7: Consolidation

The Memory Consolidator runs on schedule:

| Schedule | What It Does |
| - | - |
| **Hourly** | Topic clustering of recent sessions |
| **Daily** | Deep user/account consolidation + health signals |
| **Weekly** | Cross-account pattern extraction + best practices |

It reads only approved triage items and generates consolidated memories.

### Step 8: Canonical Promotion

The Pipeline's `memory-promoter.ts` is the sole canonical writer:

1. Scores the Spine write against 7 Promotion Signals
2. Determines governance state (staging vs approved)
3. Writes to `org_memory` (D1)
4. Deduplicates by lineage\_ref
5. Creates audit trail in `memory_promotion_audit`
6. Indexes approved memory into AI Search

### Step 9: Indexing and Consumption

Approved org\_memory entries are indexed into AI Search as markdown documents with full metadata. Twin reads published memory through bounded context projection — never raw canonical storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.