You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/diataxis/en/explanation/development-progress-dashboard.md
+50-1Lines changed: 50 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,6 +29,48 @@ Verification for this slice:
29
29
-`node --check src/frontend/workspace_panes.js`
30
30
-`npm.cmd run build`
31
31
32
+
## 2026-06-07 Graph-Focus Source Rendering and AhaDiff Comparison
33
+
34
+
This slice corrects a remaining mismatch between the intended Knowledge Workspace interaction and the actual right-side graph-focus pane behavior.
35
+
The earlier implementation opened the right pane with `matchedSpans`, but only rendered a compact evidence list.
36
+
That meant the user could not inspect the original knowledge point in its normal rendered form and therefore could not see matched passages highlighted in-place.
37
+
38
+
Code-vs-plan reconciliation for this slice:
39
+
40
+
| Requirement | Current implementation evidence | Progress call |
41
+
|---|---|---|
42
+
| Render the original knowledge point in the right pane |`src/frontend/workspace_panes.js` now resolves `sourcePath`, reads the original markdown through `NoteConnectionStorage.readContent()`, and renders it through the shared `NoteConnectionMarkdownRuntime.renderMarkdownInto()` path instead of falling back to a snippet-only card. | Implemented |
43
+
| Highlight matched passages inside the normal rendered document | The graph-focus pane now scores rendered paragraphs/blocks against `matchedSpans[].snippet` terms and applies a restrained highlight style in `src/frontend/styles.css` via `.agent-focus-match` / `data-agent-focus-highlight`. | Implemented |
44
+
| Preserve backward compatibility when source rendering is unavailable | The previous summary + evidence-list view remains the fallback path when source markdown, storage access, or markdown runtime rendering is unavailable. | Preserved |
45
+
| Keep the pane inside the same Reader-aligned rendering substrate | The focus pane reuses the same markdown runtime owner already used by the Tauri reply surface rather than creating a second markdown/mermaid/math render stack. | Implemented |
46
+
47
+
Verification for this slice:
48
+
49
+
-`npm.cmd exec -- jest src/agent_workspace.frontend.test.ts -t "graph focus|knowledge hits as file entries" --runInBand --no-cache`
50
+
-`npm.cmd exec -- tsc --noEmit`
51
+
52
+
### AhaDiff comparison and implications
53
+
54
+
The latest `ref/ahadiff` codebase makes three moves that are directly relevant to this project's next phase.
55
+
56
+
1. It treats claims, evidence, runtime validation, and review state as first-class product surfaces, not hidden backend details.
57
+
Evidence in `ref/ahadiff/src/ahadiff/claims/verify.py` is verified against concrete file/hunk anchors instead of being treated as a loose text summary problem.
58
+
Viewer-side API boundaries are runtime-validated in `ref/ahadiff/viewer/src/api/schemas.ts`, which prevents UI drift from silently accepting malformed payloads.
59
+
2. It productizes memory/review/challenge loops as durable state, not just one-shot outputs.
60
+
`review.sqlite` is guarded as a real persistence boundary in `ref/ahadiff/src/ahadiff/review/database.py`, and the challenge loop in `ref/ahadiff/src/ahadiff/challenge/engine.py` converts missed understanding back into new learning signals.
61
+
3. Its UI is organized around explicit task surfaces with typed stores, typed API clients, and route-level product pages.
62
+
The viewer separates shell, API schemas, Zustand state, and focused pages/components rather than letting one large host file own too much of the interaction model.
63
+
64
+
For this project, that comparison sharpens the next gaps:
65
+
66
+
| Area | Current NoteConnection position | Gap vs AhaDiff-style maturity | Next move |
67
+
|---|---|---|---|
68
+
| Evidence model | Scoped citations and `matchedSpans` exist, but evidence is still mostly conversation-output metadata. | Missing a first-class evidence ledger that can survive beyond one answer turn and be reused by later agent flows. | Introduce a durable evidence/claim projection for agent answers and learning artifacts. |
69
+
| Runtime contract validation | TypeScript contracts exist, but runtime response validation is still uneven across the frontend boundary. | UI can still trust structurally malformed payloads too often. | Expand runtime schema validation at the agent-workspace API boundary, especially for richer assistant payloads and future learning-state endpoints. |
70
+
| Durable learning loop | Conversation memory exists, but challenge/review/adaptation loops are still shallow. | Missing a mechanism that turns failed understanding or weak answers back into future tasks/review signals. | Build an explicit agent learning loop: answer -> inspect evidence -> mark confusion/gap -> schedule guided follow-up. |
71
+
| UI information architecture | Tauri workspace is improving, but large host files still own too much orchestration and the workspace still mixes retrieval, action, and diagnostics surfaces densely. | Interaction surfaces are less modular and less stateful than AhaDiff's page/store split. | Continue extracting workspace surfaces behind clear owners and move high-density diagnostics/learning views toward typed state modules. |
72
+
| Cross-run quality governance | Foundation and runbook gates exist, but answer quality and learning effectiveness are not yet tracked with the same durability. | Missing a stable quality ratchet for agent-grounded learning outcomes. | Add persistent answer-quality / evidence-coverage / follow-up-effectiveness history that can drive policy rather than just reporting snapshots. |
73
+
32
74
## 2026-06-06 Active-Scope Miss Recovery and Document-Augmented RAG Patch
33
75
34
76
This patch resolves the live "what is water glass?" failure that reproduced while the WebView was already running on `npm run tauri:dev:mini:gpu`.
@@ -91,7 +133,7 @@ Code-vs-plan reconciliation:
91
133
| Durable resource/index/workspace/session/memory/export substrate | Program A-F code exists under `src/resources/`, `src/indexing/`, `src/workspace/`, `src/session/`, `src/workflows/`, `src/memory/`, and `src/export/`. | Implemented |
92
134
| Platform shell separation |`PlatformCapabilities`, `RenderMaterializer`, render routes, and workspace export bundles keep desktop/Godot/mobile materialization decisions explicit. Godot remains PNG-first because direct SVG import is unsafe. | Implemented |
93
135
| Runtime graphdb/ANN production closure | graphdb/sqlite, external graphdb HTTP, local-vector rollout controls, external HTTP vector acceleration, runtime capability checks, and rollout profile payloads exist. | Operational, not production-closed |
94
-
| Single route/runtime ownership | modular route registration exists, but conversation, runbook, turn-cache, rollout, and fallback orchestration still carry heavy ownership inside `src/server.ts`. | Partially complete |
136
+
| Single route/runtime ownership | modular route registration exists, and runtime runbook modular-route operations now have a dedicated owner in `src/routes/runtimeRunbookRouteOps.ts`, but conversation, turn-cache, rollout, and other stateful fallback/orchestration logic still carry heavy ownership inside `src/server.ts`. | Partially complete |
95
137
| Architecture reduction | Current line-count scan shows `src/server.ts` about 15,920 lines and `src/learning/KnowledgeLearningPlatform.ts` about 10,351 lines; major frontend hosts remain large. | Behind target |
96
138
97
139
Architecture progress map:
@@ -193,6 +235,13 @@ The next real improvement beyond that baseline is now also in code:
193
235
- the reply policy is now also intent-aware, so comparison-style and how-to-style prompts can shape the explanation and next-action sections differently,
194
236
- which means the Tauri agent surface can now look materially different even when the underlying knowledge result set is unchanged.
195
237
238
+
The next architecture-quality improvement beyond that rendering/semantics baseline is also now started:
239
+
240
+
- the agent-conversation reply composition path is no longer treated as permanent inline `KnowledgeLearningPlatform.ts` ownership,
241
+
- a dedicated `src/learning/conversationComposer.ts` module now owns grouped knowledge-point composition plus scoped reply-section synthesis,
242
+
- which lowers KLP pressure without changing the public `AgentConversationResponse` contract or the existing Tauri/browser rendering path.
243
+
- this is intentionally a small, ownership-oriented extraction rather than a new abstraction layer: KLP still owns runtime state and persistence, while the new module owns pure data composition only.
- Preserve endpoint names and response compatibility while moving ownership.
32
+
-`src/routes/runtimeRunbookRouteOps.ts` now owns runtime runbook modular-route operation assembly; remaining P2 work should keep peeling route-layer composition out of `server.ts` without introducing pass-through facades around stateful logic.
33
+
- Apply the same ownership-reduction rule to oversized learning-runtime helpers when they are pure data composers; agent conversation reply composition is now a candidate/module boundary rather than permanent KLP inline logic.
32
34
4.**P3: Learning-platform domain extraction**
33
35
- Continue extracting ingest/query/conversation/mastery/quality/tutor/memory ownership only when the new owner hides state or enforces invariants.
34
36
- Avoid pass-through facades around `KnowledgeLearningPlatform.ts`.
- Expand typed `assistantBlocks` coverage only through optional payloads and parity-tested capabilities.
40
+
- Treat evidence rendering and evidence persistence as separate concerns: the current graph-focus pane now renders source markdown with in-place highlights, but future work still needs a durable evidence/claim surface rather than turn-local snippets only.
38
41
6.**P5: Platform/export compatibility**
39
42
- Keep Godot/mobile PNG-first materialization and export profile semantics explicit.
40
43
- Keep core retrieval/synthesis free of shell-specific branches.
@@ -163,6 +166,8 @@ Align the active implementation plan with current code reality:
163
166
- structured reply composition now splits the assistant output into overview / explanation / evidence summary / memory notice / action guidance blocks instead of emitting only one wrapped markdown answer.
164
167
- those sections are now also semantically richer: the explanation is anchored to the strongest scoped knowledge point, the evidence summary reflects real scoped citations, and next-action guidance incorporates both scoped nodes and memory-action follow-through.
165
168
- reply composition is now intent-aware as well: comparison-style and how-to-style prompts no longer reuse the exact same explanation/action phrasing as plain explanatory prompts.
169
+
- reply-composition ownership is now explicitly treated as extractable architecture surface rather than permanent `KnowledgeLearningPlatform.ts` inline logic, and the current `conversationComposer` module boundary exists to reduce KLP gravity without changing the public response contract.
170
+
- the grouped-knowledge-point and scoped-reply-section assembly path now has an explicit code owner in `src/learning/conversationComposer.ts`, so `KnowledgeLearningPlatform.ts` no longer has to own both session/runtime state and reply-composition detail in the same file.
0 commit comments