feat(analysis): decision agency attribution and verified turn-citation deep links #32

狀態更新（2026-10-28）

• 對應 Draft PR feat(analysis): decision provenance and citation foundations (#32) #37（Decision Attribution 與 Turn Citation 第一階段）；已加入 actor/provenance metadata、backend TurnRef resolver 與點擊深連結實作。
• PR feat(analysis): decision provenance and citation foundations (#32) #37 明確標示 Partially implements feat(analysis): decision agency attribution and verified turn-citation deep links #32；仍欠 multi-home、tool-result、compaction、duplicate timestamp、歸因品質的 E2E fixtures 與人工 Review。
• 保持 Open：不得因第一階段 PR 合併而自動關閉此 Issue；在完整驗收前只保留文字引用，不建立會導致自動關閉的 closing link。Parent Epic 為 epic: selectively port b08x session intelligence, long-context retrieval, RAG chat and source adapters #31。

Parent: #31 · Phase A (P1)

Existing vs source

Firstsun already stores evidence: string[] in decision/learning metadata, and formatMessagesForAnalysis emits role-specific zero-based User#N / Assistant#N while skipping tool-result/system-artifact user messages. b08x additionally emits decided_by, intent, branch_point, actor reasoning and citation requirements. Firstsun's evidence currently renders as non-clickable text.

Implementation

• Port the useful attribution semantics from b08x cli/src/analysis/{prompt-types,prompts,analysis-db,schemas/session-analysis.json} into Firstsun's versions, preserving existing prompts, feature flags, native runners and tests.
• Store decided_by / branch_point / evidence in insights.metadata (no DB migration needed for first slice); choose unknown when evidence is insufficient. Never silently default ungrounded decisions to collaborative.
• Use a shared TurnRef parse/validation routine for all cited User#N / Assistant#N evidence; refuse malformed/out-of-range refs and support legacy arbitrary evidence as non-linked text.
• Add a backend turn resolver (source role + logical role-ordinal -> message ID) consistent with classifyStoredUserMessage and full session ordering. Account for tool-only rows, compactions, pagination, multiple homes and duplicate timestamps; avoid UI-only array indices.
• Render decision actor (User / Agent / Collaborative / Unknown) and clickable evidence deep links in the insight UI; navigate to the correct session and load the cited message if outside currently loaded page.
• Keep legacy metadata and historical analyses readable; new extraction only for newly analyzed or explicitly requested reanalysis.

Acceptance tests

• End-to-end fixtures for user, agent, collaborative, unknown and contradictory/missing turn references.
• Citation resolver returns the exact message ID; UI scroll/highlight works across pagination and the matching multi-home session.
• Non-human/compaction user messages do not consume User ordinals; stale evidence does not create fake links.
• No schema-version change; Firstsun CI/build pass on Node 24/pnpm 12.

Source: https://github.com/b08x/code-insights/blob/development/cli/src/analysis/prompts.ts