Signal/docs/build-spec-2026-06-20.md

# Build Spec: Shared Context + Knowledge Pipeline

**Date:** 2026-06-20
**Design session:** Pi (architecture)
**Build session(s):** Claude Code
**Verification:** Kisa reviews after each phase

---

## Phase 1 — Foundation (est. 1 session)

### 1.1 Add research_insight category to TriLane Memory

**Files to change:**

- [ ] `trilane/backend/app/models.py`
  - Line ~79: Add `research_insight` to the allowed category values on `MemoryItem.category`
  - Current: `category = Column(String(64), nullable=False)  # decision, preference, open_loop, project_fact`
  - Change comment to include `research_insight` or add enum validation

- [ ] `trilane/backend/app/schemas.py`
  - Line ~65: Add `research_insight` to `MemoryItemOut` or `MemoryCreate` schema validation
  - Ensure the field accepts the new category string

- [ ] Run DB migration (Alembic or manual)
  - If using Alembic: `cd trilane && alembic revision --autogenerate -m "add research_insight category" && alembic upgrade head`
  - If manual: `ALTER TABLE memory_items DROP CONSTRAINT IF EXISTS ...` or equivalent
  - Verify migration ran: `curl http://localhost:8000/api/workspaces` — should still list all 3 workspaces

**Verification:**

```
curl -X POST http://localhost:8000/api/memory/16ee4620-4c81-48f9-bcd6-6c0a8fbbd71a \
  -H "Content-Type: application/json" \
  -d '{"category": "research_insight", "content": "test", "salience": 1.0}'
```

Should return 201 with memory item ID. Then delete the test item.

---

### 1.2 Plant the first real research_insight

- [ ] POST to TriLane Memory with the CGM→pharmacy insight

**Payload:**

```json
{
  "workspace_id": "16ee4620-4c81-48f9-bcd6-6c0a8fbbd71a",
  "category": "research_insight",
  "content": "CGM is systematically moving to pharmacy channel. Payer rules in FL/CA/OH/NC have moved CGM to pharmacy-only. UHC MA requires Synapse Health enrollment. Humana MA has tied-routing rule. DMEPOS suppliers are being squeezed: paid less, held to stricter documentation requirements, pushed toward expensive TPA models. This trend Signal must track for supplier intelligence.",
  "salience": 1.0,
  "tags": ["cgm", "pharmacy", "payer_trend", "policy", "strategic"]
}
```

**Verification:**

```
curl http://localhost:8000/api/memory/16ee4620-4c81-48f9-bcd6-6c0a8fbbd71a
```

Should show 1 item with category "research_insight" and content matching above.

---

### 1.3 Move 9 leaked session summaries out of Signal workspace

- [ ] Identify all session summaries in Signal workspace (id: 16ee4620)
  - Expected: 9 files from April/May 2026
  - Filenames: `2026-04-24-session-summary*` through `2026-05-10-session-summary*`
- [ ] Find the TriLane API endpoint for moving/reassigning sources between workspaces
  - If no move endpoint exists: DELETE from Signal, re-upload to Sessions workspace (id: 3446107c)
  - If move endpoint exists: POST to move endpoint with source_id and target workspace_id

**Verification:**

```
# Signal workspace should have 38 docs (was 47, minus 9 summaries)
curl http://localhost:8000/api/sources/16ee4620 | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"
# Sessions workspace should have 88 docs (was 79, plus 9 summaries)
curl http://localhost:8000/api/sources/3446107c | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"
```

No session summaries should appear in the Signal workspace source list.

---

## Phase 2 — Session Brain Updates (est. 1 session)

### 2.1 Add current-state.md write to session brain

- [ ] Read `navaigate-session-brain/SKILL.md` to identify insertion point
- [ ] Add a substep between the current Step 3 (summary) and Step 4 (NotebookLM):

```
Step 3B — Write shared context file
  - Update signal/context/current-state.md
  - Set ACTIVE to what was accomplished
  - Set NEXT to the next priority
  - Add any new decisions (max 5, FIFO — oldest drops off)
  - Update open threads
  - Update stack state if anything changed
  - Set timestamp to now
```

**Verification:**

```
cat signal/context/current-state.md
```

Should show the session's update after the next session brain run.

---

### 2.2 Add insight extraction to session brain

- [ ] Add a second substep between Step 3 (or after Step 3B):

```
Step 3C — Extract research insights
  - Did this session produce cross-document synthesis?
  - If yes: POST a research_insight memory item to TriLane Signal workspace
  - Content: one paragraph describing the insight
  - Salience: 1.0 (permanent)
  - Tags: relevant category tags
  - If no new insight: skip this step
```

**Verification:**

After the next session brain runs, TriLane Memory for Signal workspace should show
a new research_insight item (in addition to the CGM→pharmacy seed from Phase 1).

---

## Phase 3 — Startup Ritual (est. 30 min)

### 3.1 Update CLAUDE.md

- [ ] Read `signal/CLAUDE.md`
- [ ] Add near the top, after the project description:

```markdown
## Startup Ritual

At session start, in order:
1. Read signal/context/current-state.md to know the active priority
2. Check TriLane Memory for recent research_insights
3. Begin work
```

**Verification:**

```
grep "current-state" signal/CLAUDE.md
```

Should show the startup ritual section.

---

### 3.2 Create startup instruction for Pi

- [ ] Add to `~/.pi/agent/AGENTS.md` or a startup prompt:

```
At session start:
  Read signal/context/current-state.md
  Check TriLane Memory for new research_insights
```

**Verification:**

Pi reads current-state.md at session start.

---

## Phase 4 — Support Bot Foundation (est. 1 session)

### 4.1 Generate support-api-ref.json

- [ ] Write a Python script at `signal/scripts/gen-api-ref.py` that:
  - Reads `python-backend/api/main.py`
  - Parses FastAPI route decorators (@app.get, @app.post, etc.)
  - Extracts route path, method, summary (from docstring first line)
  - Extracts response model info
  - Extracts error responses (from raise statements in the function body)
  - Writes `signal/docs/support-api-ref.json`

**Expected output structure:**

```json
{
  "generated": "2026-06-20",
  "source": "python-backend/api/main.py",
  "endpoints": [
    {
      "path": "/api/health",
      "method": "GET",
      "summary": "Health check endpoint",
      "responses": [
        {"code": 200, "description": "Service healthy"}
      ]
    },
    {
      "path": "/api/upload-csv",
      "method": "POST",
      "summary": "Upload and process a CSV file",
      "parameters": [
        {"name": "file", "in": "formData", "type": "file", "required": true}
      ],
      "responses": [
        {"code": 200, "description": "CSV processed successfully"},
        {"code": 400, "description": "Invalid CSV format or missing columns"},
        {"code": 401, "description": "Invalid or missing API key"},
        {"code": 500, "description": "Server error processing CSV"}
      ]
    }
  ]
}
```

**Verification:**

```
python3 signal/scripts/gen-api-ref.py
cat signal/docs/support-api-ref.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'{len(d[\"endpoints\"])} endpoints extracted')"
```

Should show all real API endpoints from the backend.

---

### 4.2 Cross-reference support-manual.md with generated API ref

- [ ] Read both files and ensure:
  - Error messages in the manual match actual error codes from the API ref
  - Endpoint descriptions in the manual are consistent with the generated routes
  - Any missing endpoints in the manual are added
- [ ] Add a note at the top of `support-manual.md` noting the generation timestamp

**Verification:**

The error tables in `support-manual.md` should reference real endpoints in
`support-api-ref.json`.

---

## Phase 5 — Session Brain Nugget Format Update (est. 30 min)

### 5.1 Compact nugget format

- [ ] Edit `navaigate-session-brain/SKILL.md` Step 3 (Write Session Summary)
- [ ] Change the format from verbose markdown to compact nugget (~400 bytes):

```markdown
## Session Nugget — YYYY-MM-DD
N themes · N tools touched · N insights

### Completed
- [action 1]
- [action 2]
- [action 3]

### Insight
One sentence if cross-document synthesis happened. Omit if not.

### Next (Top 1)
1. [single most important next step]

### Cross-Refs
- Tool/Project links
```

**Verification:**

After next session brain run, check the NotebookLM source to verify it's using
the compact format:

```
notebooklm source list --json
notebooklm source fulltext <source_id>
```

---

## Phase 6 — Startup Automation (est. 30 min)

### 6.1 Verify the full cycle works end-to-end

- [ ] Simulate a Pi session:
  1. Pi reads current-state.md
  2. Pi does design work
  3. Pi writes decisions to current-state.md
  4. Pi posts insight to TriLane Memory (if applicable)
  5. Pi runs session brain → pushes nugget
- [ ] Simulate a Claude Code session:
  1. Claude Code reads current-state.md
  2. Claude Code sees Pi's design decisions
  3. Claude Code builds the change
  4. Claude Code updates current-state.md
  5. Claude Code runs session brain → pushes nugget

**Verification:**

- current-state.md reflects the latest session
- TriLane Memory for Signal workspace has the planted insights
- NotebookLM Brain has nuggets from both sessions
- Barrier Log has any issues encountered (should be none for a clean build)

---

## Completion Report Template

When all phases are complete, fill in:

```markdown
## Build Complete: Shared Context + Knowledge Pipeline

### Phase 1 (Foundation)
- [x] research_insight category added to TriLane Memory
- [x] CGM→pharmacy insight planted (salience 1.0)
- [x] 9 session summaries moved from Signal → Sessions workspace

### Phase 2 (Session Brain)
- [x] current-state.md write added to session brain
- [x] Insight extraction added to session brain

### Phase 3 (Startup Ritual)
- [x] CLAUDE.md updated with startup ritual
- [x] Pi AGENTS.md updated

### Phase 4 (Support Bot)
- [x] support-api-ref.json generated
- [x] Manual cross-referenced against generated ref

### Phase 5 (Nugget Format)
- [x] Session brain nugget format compacted to ~400 bytes

### Phase 6 (Verification)
- [x] Full cycle verified end-to-end
```