> ## 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.

# 08 — Promotion Path

> The governed promotion path from staged candidate to approved organizational memory.

# Promotion Path

## The Canonical Writer

The **only** canonical writer of organizational memory is `services/pipeline/src/memory-promoter.ts`.

No other service, workflow, or agent may write to `org_memory` directly.

## Promotion Flow

```
Approved triage candidate
        |
        v
Memory Consolidator (scheduled)
        |
        v
scoreForPromotion() — 7 Promotion Signals
        |
        v
Governance gate: staging vs approved
        |
   ┌────┴────┐
   |         |
staging   approved
   |         |
   v         v
Human     Direct write
review    to org_memory
   |         |
   v         v
approve   Index to
   |      AI Search
   v
Pipeline
promotion
```

## 7 Promotion Signals

| Signal | Weight | Meaning |
| - | - | - |
| strategic | 2 | Entity is inherently strategic (account, deal, contract, etc.) |
| decision | 2 | Explicit decision provenance |
| exception | 2 | Risk, anomaly, breach, blocked, churn |
| important | 1 | Material value, financial significance |
| repeated | 1 | Multiple occurrences or contributors |
| behavioral | 1 | Activity, engagement, interaction |
| preference | 1 | Explicit user/customer preference |

**Strong signals** (weight >= 2) can promote alone. Weak signals need company.

**Threshold:** Score >= 2 to promote.

## Governance Gate

```typescript theme={null}
const needsApproval =
  !schema.governanceDefaults.autoPromote ||
  schema.governanceDefaults.requiresApproval.includes(category);

const governanceState = needsApproval ? "staging" : "approved";
```

Sensitive categories (risk, decision, policy) always land in `staging` — the Twin must not use them until approved.

## Deduplication

Promotion deduplicates by `lineage_ref` (the source Spine entity):

* Existing memory found → update confidence (+0.1), update content
* No existing memory → insert new row
* Audit trail always written

## Indexing

After promotion, approved memory is indexed into AI Search:

* Markdown content with full metadata
* Idempotent re-upload (same ID overwrites)
* Batch processing (10 per batch, 100ms delay between batches)

## What Promotion Produces

| Output | Store | Purpose |
| - | - | - |
| `org_memory` row | D1 | Canonical organizational memory |
| `memory_promotion_audit` row | D1 | Immutable audit trail |
| AI Search document | Vectorize/AI Search | Searchable memory |
| Outbox event | Queue | Downstream notifications |


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