feat(agent-workspace): surface graph context in evidence pane

Author: Jacobinwwey

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -17,7 +17,9 @@ The key result is that the current code has moved further than the old plan word
 - a dedicated evidence pane now carries grounding inspection plus durable `knowledge_run` and `flashcard_batch` inspection,
 - grouped conversation knowledge points now retain relation-path and temporal-validity signals,
 - the composer now materializes an explicit `graphContext`,
-- and that `graphContext` now survives through conversation trace, snapshot persistence, and workspace export.
+- that `graphContext` now survives through conversation trace, snapshot persistence, and workspace export,
+- the grounding inspector now renders that persisted `graphContext` as structured graph evidence,
+- and grounding inspectability is now normalized per turn so later turns without grounding payload do not keep stale evidence-pane state alive.
 
 At the same time, the product surface is still behind the intended final behavior:
 
@@ -35,20 +37,21 @@ Code-vs-plan reconciliation for this slice:
 | Right-pane evidence reading | Graph focus reuses the shared markdown runtime and highlights matched spans in rendered source markdown. | Implemented baseline |
 | Answer area contraction to a single targeted answer | `agent_workspace.js` now keeps the full conversation result in runtime state while only rendering user-facing answer blocks (`structured_answer`, `main_markdown`, `html_artifact`) in the main chat surface. | Implemented current slice |
 | Hide developer-heavy evidence from the primary hit list | `workspace_panes.js` no longer renders inline knowledge previews or visible typed capability buttons in the left-side hit list; those flows now route into graph focus or the dedicated evidence pane. | Implemented current slice |
-| Durable evidence/claim inspector | `workspace_panes.js` now exposes a dedicated evidence pane for grounding metadata, `knowledge_run`, `knowledge_run_history`, `knowledge_run_compare`, and `flashcard_batch`; `agent_workspace.js` wires the API status strip into grounding inspection. | Implemented current slice |
-| DAG-native answer planning | `AgentConversationKnowledgePoint` now carries grouped `relationPath`, `relationKinds`, `relationPathAtomIds`, and `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace, persistence, and export surfaces. | Implemented partial slice |
+| Durable evidence/claim inspector | `workspace_panes.js` now exposes a dedicated evidence pane for grounding metadata, `knowledge_run`, `knowledge_run_history`, `knowledge_run_compare`, and `flashcard_batch`; `agent_workspace.js` wires the API status strip into grounding inspection and normalizes per-turn inspectability so stale grounding is cleared on later turns without evidence payloads. | Implemented broader current slice |
+| DAG-native answer planning | `AgentConversationKnowledgePoint` now carries grouped `relationPath`, `relationKinds`, `relationPathAtomIds`, and `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace, persistence, and export surfaces; `workspace_panes.js` now renders that persisted `graphContext` in the evidence pane as a structured graph explanation surface. | Implemented broader partial slice |
 
 Immediate next direction from this point:
 
-1. Extend the new DAG-aware conversation slice into a dedicated graph-conditioned context-assembly layer instead of relying on grouped relation hints and a thin `graphContext` alone.
-2. Preserve the new primary answer / right-pane-first interaction contract while growing the evidence pane and `graphContext` toward a broader durable evidence ledger and graph explanation surface.
+1. Extend the new DAG-aware conversation slice into a dedicated graph-conditioned context-assembly layer instead of relying on grouped relation hints and the current thin `graphContext` alone.
+2. Build on the new evidence-pane graph projection by adding richer predecessor/successor/path semantics and temporal replacement handling without expanding the primary chat transcript.
 3. Continue ownership reduction across `src/server.ts`, `KnowledgeLearningPlatform.ts`, `agent_workspace.js`, and `workspace_panes.js`.
 
 Verification for the current code-backed alignment:
 
 - `npm.cmd exec -- tsc --noEmit`
 - `node --check src/frontend/agent_workspace.js`
 - `node --check src/frontend/workspace_panes.js`
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts src/agent_workspace.locale.contract.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/learning/conversationComposer.test.ts src/learning/KnowledgeLearningPlatform.test.ts src/learning/KnowledgeLearningPlatform.persistence.test.ts src/learning/KnowledgeLearningPlatform.program-f.test.ts src/agent_workspace.frontend.test.ts src/knowledge.api.contract.test.ts src/routes/registry.contract.test.ts src/pathbridge.handshake.contract.test.ts src/server.port.fallback.contract.test.ts src/workflows/WorkflowArtifactStore.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts src/agent_workspace.locale.contract.test.ts src/agent_workspace.contract.parity.test.ts src/agent_workspace.runtime.behavior.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/export/WorkspaceExportBundle.test.ts --runInBand --no-cache`

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -19,7 +19,9 @@
 - 独立 evidence pane 现已承接 grounding inspection 以及 durable `knowledge_run` / `flashcard_batch` 检查；
 - grouped conversation knowledge point 现已保留 relation-path 与 temporal-validity 信号；
 - composer 现在会显式构建 `graphContext`；
-- 该 `graphContext` 现在也会沿着 conversation trace、snapshot persistence 与 workspace export 一起传播。
+- 该 `graphContext` 现在也会沿着 conversation trace、snapshot persistence 与 workspace export 一起传播；
+- grounding inspector 现在会把持久化的 `graphContext` 渲染为结构化图解释面；
+- grounding 检查入口现在按当前回合标准化判断，因此后续无 grounding payload 的回合不会继续保留陈旧的 evidence pane 状态。
 
 但当前产品面仍未完全达到目标行为：
 
@@ -37,20 +39,21 @@
 | 右侧证据阅读面 | graph focus 已复用共享 markdown runtime，并在原始 markdown 中高亮 matched span。 | 已实现基线 |
 | 主回答区收缩为单一 targeted answer | `agent_workspace.js` 现在会保留完整 conversation result 到 runtime state，但主聊天面仅渲染用户面的回答块（`structured_answer`、`main_markdown`、`html_artifact`）。 | 当前切片已实现 |
 | 主命中列表不暴露开发者导向 evidence / action | `workspace_panes.js` 已不再在左侧命中列表中渲染 inline preview 或可见 typed capability button；这些流程现在会路由到 graph focus 或专门的 evidence pane。 | 当前切片已实现 |
-| durable evidence / claim inspector | `workspace_panes.js` 现已提供专门的 evidence pane，用于承接 grounding metadata、`knowledge_run`、`knowledge_run_history`、`knowledge_run_compare` 与 `flashcard_batch`；`agent_workspace.js` 也已把 API 状态条接成 grounding inspection 入口。 | 当前切片已实现 |
-| DAG-native answer planning | `AgentConversationKnowledgePoint` 现已保留 grouped `relationPath`、`relationKinds`、`relationPathAtomIds` 与 `temporalValidity`；`conversationComposer.ts` 现已显式构建 `graphContext`；`KnowledgeLearningPlatform.ts` 与 `WorkspaceExportBundle.ts` 也已在 trace / persistence / export 中保留它。 | 当前切片已部分实现 |
+| durable evidence / claim inspector | `workspace_panes.js` 现已提供专门的 evidence pane，用于承接 grounding metadata、`knowledge_run`、`knowledge_run_history`、`knowledge_run_compare` 与 `flashcard_batch`；`agent_workspace.js` 也已把 API 状态条接成 grounding inspection 入口，并按当前回合规范清理陈旧 grounding 状态。 | 当前切片已更完整实现 |
+| DAG-native answer planning | `AgentConversationKnowledgePoint` 现已保留 grouped `relationPath`、`relationKinds`、`relationPathAtomIds` 与 `temporalValidity`；`conversationComposer.ts` 现已显式构建 `graphContext`；`KnowledgeLearningPlatform.ts` 与 `WorkspaceExportBundle.ts` 也已在 trace / persistence / export 中保留它；`workspace_panes.js` 现在会在 evidence pane 中把该 `graphContext` 渲染成结构化图解释面。 | 当前切片已更宽的部分实现 |
 
 从这里出发的即时推进方向：
 
-1. 把当前 DAG-aware 对话切片继续扩展成专门的 graph-conditioned context-assembly layer，而不是停留在 grouped relation hint 与薄 `graphContext` 层。
-2. 在保持新的主回答区与 right-pane-first 主交互契约稳定的前提下，把 evidence pane 与 `graphContext` 继续扩展成更广义的 durable evidence ledger / graph explanation surface。
+1. 把当前 DAG-aware 对话切片继续扩展成专门的 graph-conditioned context-assembly layer，而不是停留在 grouped relation hint 与当前仍较薄的 `graphContext` 层。
+2. 以当前新增的 evidence-pane 图解释面为基础，继续补 predecessor / successor / path 语义与 temporal replacement 处理，同时不把复杂度重新塞回主聊天区。
 3. 继续缩减 `src/server.ts`、`KnowledgeLearningPlatform.ts`、`agent_workspace.js`、`workspace_panes.js` 的所有权压力。
 
 当前代码对齐切片的本地验证：
 
 - `npm.cmd exec -- tsc --noEmit`
 - `node --check src/frontend/agent_workspace.js`
 - `node --check src/frontend/workspace_panes.js`
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts src/agent_workspace.locale.contract.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/learning/conversationComposer.test.ts src/learning/KnowledgeLearningPlatform.test.ts src/learning/KnowledgeLearningPlatform.persistence.test.ts src/learning/KnowledgeLearningPlatform.program-f.test.ts src/agent_workspace.frontend.test.ts src/knowledge.api.contract.test.ts src/routes/registry.contract.test.ts src/pathbridge.handshake.contract.test.ts src/server.port.fallback.contract.test.ts src/workflows/WorkflowArtifactStore.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts src/agent_workspace.locale.contract.test.ts src/agent_workspace.contract.parity.test.ts src/agent_workspace.runtime.behavior.test.ts --runInBand --no-cache`
 - `npm.cmd exec -- jest src/export/WorkspaceExportBundle.test.ts --runInBand --no-cache`

docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md

@@ -128,6 +128,8 @@ Implemented evidence:
 - Graph-focus can render original markdown and highlight matched evidence.
 - `agent_workspace.js` no longer auto-expands the first knowledge preview and keeps the full conversation result plus grounding summary in runtime getters for follow-up flows.
 - the conversation API status strip now opens a grounding inspector in the evidence pane.
+- the grounding inspector now renders persisted `trace.graphContext` as structured graph evidence instead of only aggregate scope/citation counters.
+- grounding inspectability is now derived from the current-turn normalized payload, so a later turn with no grounding payload clears stale evidence-pane state instead of reusing older turn grounding.
 - `knowledge_run`, `knowledge_run_history`, `knowledge_run_compare`, and `flashcard_batch` inspections now open in the evidence pane instead of appending new primary chat cards.
 
 Progress call:
@@ -181,13 +183,19 @@ What the current slice now adds:
   - add graph-aware next-action guidance when prerequisite chains or temporal validity warnings are present.
 - `KnowledgeLearningPlatform.ts` now persists and restores that `graphContext` across conversation turn history and snapshot reload.
 - `WorkspaceExportBundle.ts` now carries `graphContext` through workspace export/runtime turn serialization.
+- `workspace_panes.js` now projects that persisted `graphContext` into the evidence pane as a structured graph explanation surface:
+  - anchor identity
+  - relation kinds and relation summaries
+  - supporting titles and atom ids
+  - temporal-validity status and warning reasons
+- `agent_workspace.js` now normalizes grounding payload construction in one place and clears stale grounding state when a later turn returns no grounding payload.
 
 What is still missing:
 
 - a dedicated graph-conditioned context assembly layer between retrieval and answer synthesis,
 - richer use of predecessor/successor chains beyond grouped relation summaries,
 - answer-time use of temporal replacement / supersession beyond warning text,
-- frontend/runtime use of the persisted `graphContext` as a durable graph explanation surface rather than markdown-only guidance.
+- broader frontend/runtime reuse of the persisted `graphContext` beyond the current evidence-pane projection.
 
 Progress call:
 
@@ -204,7 +212,7 @@ Progress call:
 | Durable learning/review loop | Implemented through workflow artifacts, knowledge runs, review follow-up, flashcard batch persistence, and a pane-backed evidence inspector for durable artifact inspection | Implemented current slice | Still lacks a broader durable evidence ledger and challenge-loop product surface |
 | File-first scoped knowledge hits | Implemented and now routed directly into graph focus from file-only entries | Implemented current slice | Graph-focus and evidence-pane cohesion now matters more than entry-point cleanup |
 | Hide developer-heavy evidence from the main user-facing answer | Implemented in the primary chat and hit-list surfaces, with grounding and durable artifact inspection moved into a dedicated evidence pane | Implemented current slice | Secondary surfaces still share large frontend owners |
-| Use current DAG as a first-class answer-planning substrate | `AgentConversationKnowledgePoint` now carries grouped `relationPath` / `relationKinds` / `relationPathAtomIds` / `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace/persistence/export surfaces | Implemented partial slice | Missing a dedicated graph-conditioned context assembly layer and richer downstream use of the graph context |
+| Use current DAG as a first-class answer-planning substrate | `AgentConversationKnowledgePoint` now carries grouped `relationPath` / `relationKinds` / `relationPathAtomIds` / `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace/persistence/export surfaces; `workspace_panes.js` now exposes that `graphContext` in the evidence pane as a structured graph explanation surface | Implemented broader partial slice | Missing a dedicated graph-conditioned context assembly layer and richer downstream use of the graph context |
 | Ownership reduction in runtime and frontend hosts | Not complete | Behind target | `server.ts`, `KnowledgeLearningPlatform.ts`, `agent_workspace.js`, and `workspace_panes.js` still own too much |
 
 ### Current Risks
@@ -296,6 +304,8 @@ Shipped characteristics:
 - grouped conversation knowledge points now retain `relationPath`, `relationKinds`, `relationPathAtomIds`, and `temporalValidity`,
 - structured answer overview/explanation/next-actions now use those grouped DAG signals additively,
 - the resulting `graphContext` now survives through conversation trace, snapshot persistence, and workspace export.
+- the evidence pane now renders that `graphContext` directly for user inspection,
+- grounding-pane state now clears cleanly when a later turn has no grounding payload.
 
 Remaining requirements: