docs: align knowledge workspace and DAG progress

Author: Jacobinwwey

CI_STATUS.md

@@ -2,6 +2,26 @@
 
 Tracking progress toward all-green CI. Inspired by paseo's CI_STATUS.md.
 
+## 2026-06-10 Knowledge Workspace and DAG Alignment Sync
+
+- Current branch state has been re-audited against the earlier lightweight-RAG, agent-workspace, and mainline architecture plans.
+- The source-of-truth reconciliation note is now `docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md`.
+- Code-backed current-state confirmations for this slice:
+  - structured grounded conversation with additive compatibility,
+  - grouped knowledge points,
+  - durable `flashcard_batch` / `knowledge_run` workflow artifacts,
+  - workflow-artifact review follow-up runtime path,
+  - graph-focus source rendering with matched-span highlighting.
+- Local verification executed for this slice:
+  - `npm.cmd exec -- tsc --noEmit`
+  - `node --check src/frontend/agent_workspace.js`
+  - `node --check src/frontend/workspace_panes.js`
+  - `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`
+- Remaining architecture gaps from this slice are product-surface and answer-planning gaps, not missing substrate:
+  - contract the visible answer area toward a single targeted answer,
+  - converge knowledge-hit interaction on a right-pane-first model,
+  - add graph-conditioned context assembly between retrieval and answer synthesis.
+
 ## CI Gates
 
 | Gate | Workflow | Status | Notes |

Interface Document.md

@@ -62,6 +62,26 @@ Audit flow:
 - `assistantBlocks` are no longer only transport wrappers around the same legacy answer string. Current Tauri-capable clients should expect intent-aware overview / explanation / evidence / memory / action sections while still honoring `assistantMessage` as the compatibility fallback.
 - Compatibility rule: new response fields must remain additive and optional; Godot/mobile paths must continue to use PNG-first materialized render artifacts instead of requiring direct SVG import.
 
+## 0.2B Knowledge Workspace and DAG Alignment Addendum (2026-06-10)
+
+- The Knowledge Workspace runtime now includes durable workflow-artifact paths for `flashcard_batch` and `knowledge_run`, exposed through `/api/knowledge/workflow-artifacts` and `/api/knowledge/workflow-artifacts/review-follow-up`.
+- Runtime compatibility remains additive:
+  - `assistantMessage` stays valid,
+  - `answer`, `assistantBlocks`, `knowledgeRun`, grouped `knowledgePoints`, citations, memory actions, and trace coexist with legacy clients.
+- The codebase already contains a real DAG-backed learning substrate:
+  - `KnowledgeAtom`
+  - `RelationEdge`
+  - `TemporalEdge`
+  - path queries
+  - prerequisite-driven mastery/session flows
+  - `KnowledgeQueryItem.relationPath`
+- Current architecture reading:
+  - graph-backed retrieval and learning-path/session logic are implemented,
+  - graph-native answer planning is not yet complete because retrieval and answer synthesis still lack a dedicated graph-conditioned context-assembly layer.
+- Current product-surface reading:
+  - grouped file-first knowledge hits and right-pane source highlighting are implemented,
+  - the visible answer area still needs future contraction so targeted answers lead and supporting blocks move to secondary surfaces.
+
 ---
 
 ## 1. Runtime and Path Contracts

README.md

@@ -27,16 +27,16 @@ Unlike traditional "network" views that show a messy web of links, NoteConnectio
 
 ---
 
-## Current Mainline Architecture Status (2026-06-06)
+## Current Mainline Architecture Status (2026-06-10)
 
 - The current `main` branch has code-backed scoped retrieval, grounded conversation, durable resource/index/workspace/session/memory/export substrate, explicit export profiles, and PNG-first Godot/mobile render materialization.
-- The Knowledge Workspace is no longer only a thin chat shell over the global folder selector: it now has an in-pane scope switcher, a compact `/api/knowledge/conversation` status strip, grouped knowledge-point hits rendered as file-first entries, matched-span rendering in the focus pane, and explicit recovered-source visibility when `planner_scope_recovery` is used.
-- graphdb/sqlite and ANN/external connector paths are operational baselines, not production-closed release claims. Release closure still depends on repeated soak evidence, workload thresholds, recall/latency calibration, and strict rollout proof.
-- `npm run verify:foundation:release-evidence` now audits the latest sqlite soak and ANN release-gate JSON reports for freshness and passing gates before current-host evidence is used as release context; `npm run verify:foundation:release-evidence:strict` additionally requires repeated fresh valid history reports, is exposed in foundation readiness as `foundation_release_evidence_history`, and now passes on the current Windows host with sqlite `3/3` and ANN `3/3`. `npm run verify:foundation:release-evidence:multi-host` is now available when a release window needs at least two host keys per component, but current Windows-host evidence remains single-host.
-- Backward compatibility is preserved through additive response evolution: `assistantBlocks` can carry richer Tauri agent replies while legacy `assistantMessage` remains valid.
-- Tauri agent replies are now materially richer than the old plain-text path: the backend emits intent-aware overview / explanation / evidence summary / memory notice / next-action sections, while still preserving the old `assistantMessage` field for legacy clients.
-- The current architecture pressure is ownership reduction: `src/server.ts`, `src/learning/KnowledgeLearningPlatform.ts`, and large frontend host files remain the next simplification targets.
-- Current code-vs-plan details are tracked in [Architecture Progress Alignment and Mainline Plan (2026-06-06)](docs/solutions/architecture-progress-alignment-2026-06-06.md) and [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
+- The Knowledge Workspace now includes an in-pane scope switcher, a compact `/api/knowledge/conversation` status strip, grouped file-first knowledge hits, source-markdown rendering with matched-span highlighting in the focus pane, and durable workflow artifacts for `flashcard_batch` and `knowledge_run`.
+- Agent conversation runtime is no longer limited to one flat string: `answer`, `assistantBlocks`, `knowledgeRun`, grouped knowledge points, citations, memory actions, and trace are all present while legacy `assistantMessage` remains valid.
+- The current DAG-backed learning substrate is real: `KnowledgeAtom`, `RelationEdge`, `TemporalEdge`, path queries, mastery-path/session logic, and `KnowledgeQueryItem.relationPath` already exist. The remaining gap is not “having a graph,” but letting answer planning consume it through a dedicated graph-conditioned context layer.
+- graphdb/sqlite and ANN/external connector paths remain operational baselines, not production-closed claims. Release closure still depends on repeated soak evidence, workload thresholds, recall/latency calibration, strict rollout proof, and multi-host evidence.
+- `npm run verify:foundation:release-evidence` audits the latest sqlite soak and ANN release-gate reports for freshness and passing gates before host evidence is used as release context; `npm run verify:foundation:release-evidence:strict` requires repeated fresh valid history and is exposed in foundation readiness as `foundation_release_evidence_history`; `npm run verify:foundation:release-evidence:multi-host` is available for release windows that require host diversity.
+- The current architecture pressure remains ownership reduction: `src/server.ts`, `src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/agent_workspace.js`, and `src/frontend/workspace_panes.js` remain the main simplification targets.
+- Current code-vs-plan details are tracked in [Knowledge Workspace and DAG Alignment Plan (2026-06-10)](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md), [Architecture Progress Alignment and Mainline Plan (2026-06-06)](docs/solutions/architecture-progress-alignment-2026-06-06.md), and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
 
 ---
 
@@ -1017,14 +1017,16 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 
 ---
 
-## 当前主线架构状态（2026-06-06）
+## 当前主线架构状态（2026-06-10）
 
 - 当前 `main` 已具备代码支撑的 scoped retrieval、grounded conversation、持久化 resource/index/workspace/session/memory/export 底座、显式 export profiles，以及 Godot/mobile PNG-first 渲染物化边界。
-- graphdb/sqlite 与 ANN/external connector 目前是 operational baseline，不是 production-closed 发布结论。发布闭环仍依赖多轮 soak 证据、工作负载阈值、recall/latency 校准与 strict rollout 证明。
-- `npm run verify:foundation:release-evidence` 现在会在当前宿主证据被作为 release context 前审计最新 sqlite soak 与 ANN release-gate JSON 报告的新鲜度和通过状态；`npm run verify:foundation:release-evidence:strict` 还会要求多份新鲜有效历史报告，已通过 `foundation_release_evidence_history` 暴露到 foundation readiness，并且当前 Windows 宿主已达到 sqlite `3/3` 与 ANN `3/3` 通过状态。当 release window 需要每个组件至少覆盖两个 host key 时，可以使用 `npm run verify:foundation:release-evidence:multi-host`，但当前 Windows 宿主证据仍是单宿主证据。
-- 向前兼容通过 additive response evolution 保持：`assistantBlocks` 可以承载更丰富的 Tauri agent 回复，同时 legacy `assistantMessage` 仍有效。
-- 当前架构压力是所有权缩减：`src/server.ts`、`src/learning/KnowledgeLearningPlatform.ts` 与大型前端宿主文件是下一阶段简化目标。
-- 代码 / 方案详细对齐请查看 [架构推进对齐与主线推进方案（2026-06-06）](docs/solutions/architecture-progress-alignment-2026-06-06.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
+- 知识工作区除了工作区内 scope 切换器、conversation API 状态条、按文件优先的 grouped knowledge hit 与 focus pane 中的 matched-span 高亮之外，还已经具备 durable workflow artifact：`flashcard_batch` 与 `knowledge_run`。
+- agent conversation 运行时已经不再只是单一回答字符串：`answer`、`assistantBlocks`、`knowledgeRun`、按文档聚合的 `knowledgePoints`、citations、memory actions 与 trace 已进入当前兼容性表面，同时保留 legacy `assistantMessage`。
+- 现有 DAG 学习底座是真实存在的：`KnowledgeAtom`、`RelationEdge`、`TemporalEdge`、path query、mastery-path/session 逻辑以及 `KnowledgeQueryItem.relationPath` 都已落地。真正剩余的缺口不是“有没有图”，而是“回答规划层还没有 dedicated graph-conditioned context layer”。
+- graphdb/sqlite 与 ANN/external connector 仍是 operational baseline。生产闭环仍需要多轮 soak 证据、工作负载阈值、recall/latency 校准、strict rollout proof 与多宿主证据。
+- 当前 release-evidence 审计面已由 `verify:foundation:release-evidence`、`verify:foundation:release-evidence:strict` 与 `verify:foundation:release-evidence:multi-host` 统一。
+- 下一阶段架构工作仍是缩减 `src/server.ts`、`src/learning/KnowledgeLearningPlatform.ts`、`src/frontend/agent_workspace.js` 与 `src/frontend/workspace_panes.js` 的所有权压力。
+- 当前代码 / 方案详细对齐请查看 [知识工作区与 DAG 对齐推进方案（2026-06-10）](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md)、[架构推进对齐与主线推进方案（2026-06-06）](docs/solutions/architecture-progress-alignment-2026-06-06.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
 
 ---
 

TEST_REPORT.md

@@ -1,3 +1,71 @@
+# 2026-06-10 v1.7.0 - Knowledge Workspace and DAG Alignment Verification
+
+## English Document
+
+### Verification Objective
+
+Verify that the current Knowledge Workspace and DAG alignment reading matches the actual code state before promoting the current branch to `main`.
+
+### Verified Scope
+
+- structured grounded conversation and grouped knowledge points
+- durable `flashcard_batch` / `knowledge_run` workflow artifacts
+- workflow-artifact review follow-up runtime path
+- graph-focus source rendering with matched-span highlighting
+- additive compatibility for current conversation/runtime payloads
+
+### Executed Verification (2026-06-10)
+
+- [x] `npm.cmd exec -- tsc --noEmit`
+  - PASS
+- [x] `node --check src/frontend/agent_workspace.js`
+  - PASS
+- [x] `node --check src/frontend/workspace_panes.js`
+  - PASS
+- [x] `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`
+  - PASS (`10` suites, `155` tests)
+
+### Conclusion
+
+- The current code-backed Knowledge Workspace and DAG alignment slice is internally consistent.
+- The current branch is ready for documentation-backed promotion to `main`.
+- This verification confirms current code truth; it does not claim that answer planning is already fully graph-native.
+
+---
+
+## 中文文档
+
+### 验证目标
+
+在把当前分支推进到 `main` 之前，确认这次“知识工作区 + DAG 对齐”结论与真实代码状态一致。
+
+### 本轮验证范围
+
+- 结构化 grounded conversation 与 grouped knowledge point
+- durable `flashcard_batch` / `knowledge_run` workflow artifact
+- workflow-artifact review follow-up 运行时路径
+- graph-focus 原始 markdown 渲染与 matched-span 高亮
+- 当前 conversation/runtime payload 的 additive compatibility
+
+### 已执行验证（2026-06-10）
+
+- [x] `npm.cmd exec -- tsc --noEmit`
+  - 通过
+- [x] `node --check src/frontend/agent_workspace.js`
+  - 通过
+- [x] `node --check src/frontend/workspace_panes.js`
+  - 通过
+- [x] `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`
+  - 通过（`10` 个 suites，`155` 项测试）
+
+### 结论
+
+- 当前代码支撑的“知识工作区 + DAG 对齐”切片在内部是一致的。
+- 当前分支已具备以文档为依据推进到 `main` 的条件。
+- 本轮验证确认的是当前代码真相，不等于回答规划已经完全进入 graph-native 状态。
+
+---
+
 # 2026-03-10 v1.5.38 - Multi-Terminal WASM Readiness Slice Verification (Mobile Capability Probe + Build-Mode Telemetry)
 
 ### Test Objective

TODO.md

@@ -1,3 +1,37 @@
+# 2026-06-10 v1.7.0 - Knowledge Workspace and DAG Alignment TODO
+
+## English Document
+
+### Objective
+Keep the root TODO aligned with the 2026-06-10 Knowledge Workspace and DAG code-vs-plan reconciliation on `main`.
+
+### Current Status
+- [x] A new mainline alignment note for this slice now exists at `docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md`.
+- [x] The current codebase already supports structured grounded conversation, grouped knowledge points, durable `flashcard_batch` / `knowledge_run` artifacts, and workflow-artifact review follow-up.
+- [x] The current codebase already has a real DAG-backed learning substrate: `KnowledgeAtom`, `RelationEdge`, `TemporalEdge`, path queries, and mastery/session graph logic are implemented.
+- [~] The visible answer area is still richer than the intended final product surface. The primary answer still needs contraction so users see the targeted answer first and supporting blocks move to secondary surfaces.
+- [~] Knowledge-hit interaction is file-first, but still not fully right-pane-first. Left-side preview/action behavior should converge on the right pane as the canonical reading surface.
+- [ ] Add a graph-conditioned context-assembly layer between retrieval and answer synthesis so the current DAG becomes a first-class answer-planning substrate rather than only a retrieval-side aid.
+- [ ] Continue ownership reduction in `src/server.ts`, `src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/agent_workspace.js`, and `src/frontend/workspace_panes.js`.
+- [ ] Keep `assistantMessage` compatibility while evolving richer optional `assistantBlocks` and durable artifact inspection surfaces.
+
+## 中文文档
+
+### 目标
+让根目录 TODO 与 `main` 上 2026-06-10 的“知识工作区 + DAG 对齐”代码 / 方案结论保持一致。
+
+### 当前状态
+- [x] 本轮主线对齐结果已新增到 `docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md`。
+- [x] 当前代码已经支持结构化 grounded conversation、按文档聚合的 knowledge point、durable `flashcard_batch` / `knowledge_run` artifact，以及 workflow-artifact review follow-up。
+- [x] 当前代码已经具备真实的 DAG 学习底座：`KnowledgeAtom`、`RelationEdge`、`TemporalEdge`、path query、mastery/session 图逻辑都已落地。
+- [~] 用户可见回答区仍比目标产品面更重；主回答区仍需继续收缩为“用户先看到 targeted answer，supporting block 退到次级表面”。
+- [~] 知识命中已经是 file-first，但还没有完全收敛为 right-pane-first；左侧 preview/action 行为仍需向“右侧 pane 才是权威阅读面”继续收口。
+- [ ] 在 retrieval 与 answer synthesis 之间补一个 graph-conditioned context-assembly layer，让当前 DAG 成为一等 answer-planning substrate，而不只是 retrieval 侧辅助信号。
+- [ ] 继续缩减 `src/server.ts`、`src/learning/KnowledgeLearningPlatform.ts`、`src/frontend/agent_workspace.js`、`src/frontend/workspace_panes.js` 的所有权压力。
+- [ ] 在演进 richer optional `assistantBlocks` 与 durable artifact inspection surface 时，继续保持 `assistantMessage` 兼容。
+
+---
+
 # 2026-06-06 v1.7.0 - Architecture Progress Alignment and Mainline TODO
 
 ## English Document