epic: selectively port b08x session intelligence, long-context retrieval, RAG chat and source adapters #31

Epic 狀態（2026-10-28）

• Phase A：feat(analysis): decision agency attribution and verified turn-citation deep links #32 對應 Draft PR feat(analysis): decision provenance and citation foundations (#32) #37（部分完成，尚待 E2E／Review）；fix(analysis): finish rage-loop and repeated-failure detection end-to-end #34 對應 Draft PR fix(analysis): complete rage-loop detection and avoid false positives (#34) #38（正式 Development 已連結，待驗證 Rage Loop）。
• Phase D：feat(providers): add opt-in Claude Desktop and Pi AI session parsers #36 對應 Draft PR feat(providers): opt-in Claude Desktop and Pi AI session sources (#36) #39（正式 Development 已連結，待 Claude Desktop／Pi 的真實資料 smoke）。
• Phase B：feat(analysis): adaptive long-session chunking and grounded retrieval pipeline #33（長 Session 分塊與 Retrieval Pipeline）目前沒有對應實作 PR；Phase C feat(rag): local read-only session knowledge chat with cited answers #35（RAG Agent Chat）依賴 Phase B，尚未實作。
• 保持 Open。Epic 是分階段追蹤，不應由 feat(analysis): decision provenance and citation foundations (#32) #37/fix(analysis): complete rage-loop detection and avoid false positives (#34) #38/feat(providers): opt-in Claude Desktop and Pi AI session sources (#36) #39 任一子工作合併而自動結案。

Goal

Selectively port the following b08x/code-insights development capabilities into firstsun-dev/code-insights main, without merging the diverged forks wholesale.

Source revision: b08x/development@789723ffb18a40733ee6c2a957a435fd94e0deb8
Target baseline: firstsun-dev/main@3edfec99e6632ef60d6950ce918707bfda516ebf

Implementation PRs (Draft; no merge)

• feat(analysis): decision provenance and citation foundations (#32) #37 — Decision Attribution / Turn Citation; CI passed, real-session acceptance pending
• fix(analysis): complete rage-loop detection and avoid false positives (#34) #38 — Rage Loop pipeline and false-positive handling; CI passed, manual acceptance pending
• feat(providers): opt-in Claude Desktop and Pi AI session sources (#36) #39 — Claude Desktop / Pi AI adapters; CI passed, real-session acceptance pending
• feat(analysis): adaptive long-session chunking and grounded retrieval pipeline #33 — Long-session retrieval: issue only, no implementation PR yet
• feat(rag): local read-only session knowledge chat with cited answers #35 — RAG chat: issue only, blocked on feat(analysis): adaptive long-session chunking and grounded retrieval pipeline #33 and security gate

Implementation issues

• feat(analysis): decision agency attribution and verified turn-citation deep links #32 — Decision Attribution + verified Turn Citation (P1)
• fix(analysis): finish rage-loop and repeated-failure detection end-to-end #34 — Rage Loop end-to-end: existing detector, taxonomy/wiring/tests (P1)
• feat(analysis): adaptive long-session chunking and grounded retrieval pipeline #33 — Long-session chunking & Retrieval (P1; additive migration)
• feat(rag): local read-only session knowledge chat with cited answers #35 — Read-only RAG Agent Chat (P2; after feat(analysis): adaptive long-session chunking and grounded retrieval pipeline #33 and security gate)
• feat(providers): add opt-in Claude Desktop and Pi AI session parsers #36 — Claude Desktop + Pi AI adapters (P2; independent)

Scope (independent PRs)

1. Decision attribution (user | agent | collaborative | unknown) with validated, navigable turn citations.
2. Long-session semantic chunking, context-aware retrieval and quality/cost regression tests.
3. Rage-loop/repeated-failure detection end-to-end (detector already present with identical blob SHA; fix wiring/taxonomy rather than re-copying).
4. Read-only interactive RAG Agent Chat with citations and opt-in permissions.
5. Claude Desktop and Pi AI session source adapters, tested independently.

Architectural constraints (non-negotiable)

• Preserve Firstsun-only functionality: multi-home, Personality, Kilo, reports, OpenAPI, Docker/sidecar, provider support, existing filters and pricing.
• Preserve Node 24 / pnpm 12.14.0 build and CI toolchain.
• Firstsun DB currently at V14; b08x has independently assigned V12-V18 meanings. Never copy b08x migration numbers or replace Firstsun's migration history. Add forward-only additive migrations starting after V14, with backfill and fresh/production-copy upgrade tests.
• Preserve current embedding dimensions/model metadata. Do not attach a 1024-dimensional index to a 768-dimensional embedding table.
• Restrict RAG access by project + home with fail-closed filters; any optional codebase tools must require explicit opt-in.
• Harden service binding/auth and disable outbound telemetry for isolated tests before enabling a chat interface. Avoid wholesale $HOME RW mounts.
• Use representative multi-tool session fixtures and benchmark changes against main; avoid noisy auto-reanalysis or migrations that overwrite existing insight history.

Suggested sequence

• Phase A: decision attribution + stable citation resolver, then end-to-end rage-loop integration.
• Phase B: long-context retrieval and additive schema/index changes, offline backfill.
• Phase C: RAG chat atop the retrieval foundation, including privacy and authorization.
• Phase D: Claude Desktop and Pi parsers (can proceed independently when fixtures exist).

Done when

All five workstreams have independent tested PRs, no existing functionality regresses, database upgrades remain forward-compatible, and human review occurs before merge/deploy.

Refs:

• https://github.com/b08x/code-insights
• https://github.com/firstsun-dev/code-insights
• refactor(fca): attributes are mutually exclusive, so the lattice is degenerate by construction b08x/code-insights#21 (FCA issue: FCA lattice not a dependency of this port)