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:

{
  "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:

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

{
  "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):

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

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