docs(progress): add deep code-vs-requirements comparison and direction

- Add structured comparison tables: roadmap phases, backend sufficiency,
  foundation readiness, agent conversation plan, architecture advancement.
- Document current gaps vs roadmap targets with explicit next actions.
- Define active lane (conversation-product continuity), next lane
  (mastery loop Phase 2), and dormant lanes (backend escalation).
- Update journal with comparison and direction completion.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Jacobinwwey

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

@@ -12,6 +12,102 @@ It explicitly separates branch-level implementation status from mainline integra
   - route/runtime layer (`src/server.ts`),
   - executable tests.
 
+## Code-vs-Requirements Deep Comparison (2026-04-27)
+
+Each prior solution document sets requirements. This section compares those requirements against actual shipped code.
+
+### Comparison: Knowledge Mastery Evolution Roadmap
+
+| Phase | Requirement | Code Evidence | Status |
+|-------|-------------|---------------|--------|
+| P1: Backbone | Unified ingest + staleness rebuild | `POST /api/knowledge/ingest-diff` in `src/server.ts`, `KnowledgeLearningPlatform.ingestDiff()` | **Shipped** |
+| P1: Backbone | Relation + temporal graph contracts | `src/learning/types.ts` — `KnowledgeRelation`, `TemporalEvidence` types | **Shipped** |
+| P1: Backbone | Store abstraction (file/memory/graphdb) | `src/learning/store.ts` — `KnowledgeGraphStore` interface, `SqliteKnowledgeGraphStore` (default), `FileBackedKnowledgeGraphStore` (fallback) | **Shipped** — graphdb not integrated yet |
+| P1: Backbone | Query backend comparability | `src/learning/queryBackend.ts` — `local_hybrid` vs `keyword_only`, request-level override via `queryBackend` field | **Shipped** |
+| P2: Mastery | Mastery diagnostics + misconception tracking | `POST /api/knowledge/mastery/misconceptions` in `src/server.ts`, `MasteryPath` / `DivergencePath` types in `src/learning/types.ts` | **Shipped** (API), UI gated |
+| P2: Mastery | Dual path outputs in session planning | `POST /api/knowledge/session/plan` → `masteryPaths` + `divergencePaths`, `includeDivergence` flag | **Shipped** (API) |
+| P2: Mastery | Quality trend + threshold checks | `POST /api/knowledge/quality/snapshot`, `/quality/history`, `/quality/trend` | **Shipped** |
+| P3: Tutor | Pluggable tutor actions under evidence-first | `src/learning/tutorAdapter.ts`, `TutorAction` type with `evidence` + `verificationStatus` fields | **Shipped** (API), provider integration gated |
+| P3: Memory | Memory policy diagnostics + trend governance | `POST /api/knowledge/memory-policy/*`, `memoryLayer: session/unit/long_term` | **Shipped** |
+| P3: Runtime | Runtime capability runbook + remediation | `/api/knowledge/operator/agent-workspace-diagnostics/triage/*`, `primaryRunbookAction` contract | **Shipped** |
+
+### Comparison: Local Backend Sufficiency and Escalation Plan
+
+| Requirement | Code Evidence | Status |
+|-------------|---------------|--------|
+| sqlite as system of record | `DEFAULT_KNOWLEDGE_GRAPH_STORE_KIND = 'sqlite'` (`src/learning/store.ts:59`) | **Compliant** |
+| Local embeddings + ANN pruning | `vectorAccelerationAdapter.ts` — `mode = local_ann`, `vectorAdapterSignalKind = embedding_ann` | **Compliant** |
+| Backend sufficiency control surface | `GET /api/knowledge/backend/sufficiency`, `verify:backend:baseline:sufficiency` script | **Compliant** |
+| Measurement hardening before backend replacement | Query-latency observation upgrades to `measured` when runtime history exists; rebuild/recovery duration also observed | **Compliant** (partial — most top-level modes still `policy_default`) |
+| Escalation trigger: measured pressure | Sufficiency route exposes observation modes; no automated escalation yet | **Gate intact** |
+| Product/memory work takes priority | M8.20-M8.53 (34 increments) shipped, all frontend-bounded, no backend expansion | **Compliant** |
+
+### Comparison: Foundation Re-entry Readiness Checklist
+
+| Gate | Code Evidence | Status |
+|------|---------------|--------|
+| sqlite persistence merged to main | `src/learning/store.ts` — `SqliteKnowledgeGraphStore` class, `CREATE TABLE IF NOT EXISTS` | **Pass** |
+| Query-backend separation merged to main | `src/learning/queryBackend.ts` — `local_hybrid` and `keyword_only` backends | **Pass** |
+| Vector acceleration independent | `src/learning/vectorAccelerationAdapter.ts` — `mode = local_ann` | **Pass** |
+| Foundation contract tests passing | `src/foundation.readiness.contract.test.ts`, `src/learning/KnowledgeLearningPlatform.test.ts` (80KB) | **Pass** (7/7 promotion criteria) |
+| Readiness route operational | `GET /api/knowledge/backend/sufficiency` — returns live observation data | **Pass** |
+| No foundation blockers | `promotionBlockers = []` | **Pass** |
+
+### Comparison: Agent Conversation Focus Mode Plan (M1-M8)
+
+| Milestone | Requirement | Code Evidence | Status |
+|-----------|-------------|---------------|--------|
+| M1 Baseline | `AgentConversationAPI` contract | `src/learning/api.ts` — `runAgentConversation()`, `src/learning/types.ts` — conversation types | **Shipped** |
+| M2 Runtime | Agent workspace dock panel | `src/frontend/agent_workspace.js` + `agent_workspace_runtime.js` + `index.html` dock wiring | **Shipped** |
+| M3 CI Gates | Migration-gates workflow suites | `.github/workflows/migration-gates.yml` — 3 agent-workspace suites | **Shipped** |
+| M4-M6 | Capability expansion (study, history, quality, tutor, memory) | 11 typed conversation actions in `src/learning/types.ts`, all wired through `runAgentConversation()` | **Shipped** |
+| M7 CI Stabilization | CI hardening + post-M7 direction | `docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md` | **Shipped** |
+| M8.20-M8.52 | Conversation-product hardening (33 increments) | All verified in `src/frontend/agent_workspace_runtime.js`, `src/server.ts`, contract tests | **Shipped** |
+| M8.53 | Primary runbook consumer adoption | `resolvePrimaryRunbookAction()` in `agent_workspace_runtime.js`, tests in `agent_workspace.runtime.behavior.test.ts` | **Shipped** (2026-04-27) |
+
+### Architecture Advancement Summary
+
+| Layer | v1.7.0 Baseline (2026-03-31) | Current (2026-04-27) | Delta |
+|-------|-----------------------------|---------------------|-------|
+| Graph persistence | File snapshots only | sqlite (default) + file (fallback), `KnowledgeGraphStore` interface | **Independent** |
+| Query backend | Lexical-only (`keyword_only`) | `local_hybrid` with ANN + keyword + relation scoring, per-request override | **Independent** |
+| Vector acceleration | Not present | `mode = local_ann`, deterministic embeddings, benchmark parity with WASM | **New capability** |
+| Learning API surface | Basic ingest + query | Full ingest/session/tutor/memory/quality/governance API (15+ endpoints) | **3x expansion** |
+| Conversation surface | Not present | Agent workspace with dock panel, capability execution, 11 action types | **New capability** |
+| Active-atom continuity | Not present | Focus rail, pane-state, summary cards, history drill-down, follow-up ranking (M8.24-M8.33) | **New capability** |
+| History explanation | Not present | Tradeoff/drift/stability explanation, confidence signals (M8.34-M8.37) | **New capability** |
+| Managed-memory continuity | Not present | Gap follow-up, continuity rollups, transition explanation (M8.38-M8.46) | **New capability** |
+| Operator triage/runbook | Not present | Continuity-aware triage, severity calibration, prioritization, primary action contract (M8.47-M8.53) | **New capability** |
+| Spec/guidelines | Not present | 11 filled spec files, development plan, session journal | **New governance** |
+
+### Current Gaps vs. Roadmap Target
+
+| Gap | Priority | Blocked By | Next Action |
+|-----|----------|------------|-------------|
+| Graphdb backend not integrated | Medium | Measured sqlite pressure | Keep dormant; escalate only if `backend/sufficiency` shows degradation |
+| Standalone vector index not integrated | Medium | ANN parity verified | Keep dormant; local ANN is sufficient for current product scope |
+| Mastery loop UI not yet shipped | Medium | M8.53 pattern validated | Apply bounded consumer pattern to mastery/divergence surfaces |
+| Tutor provider integration not yet shipped | Low | Evidence-first gate | Provider adapter exists; full integration gated behind mastery loop |
+| `server.ts` (499KB) monolithic | Tech debt | No test failures | Schedule refactor as separate task; not blocking any lane |
+| `agent_workspace_runtime.js` (217KB) large | Tech debt | All tests pass | Monitor; split only when a second consumer forces module extraction |
+
+## Subsequent Direction (Post-2026-04-27)
+
+### Active Lane: Conversation-Product Continuity
+- **Current**: M8.53 shipped — `primaryRunbookAction` consumer live in diagnostics report.
+- **Next**: Evaluate whether single-consumer adoption unlocks enough operator value before broadening.
+- **Decision gate**: If the diagnostics report consumer proves sufficient → gate stays; consider mastery-loop UI next. If operator feedback demands broader visibility → add one more bounded consumer (still no dashboard shell).
+
+### Next Lane: Mastery & Divergence Loop (Phase 2)
+- **API ready**: Mastery diagnostics, misconception tracking, dual-path session planning, quality trends.
+- **UI gap**: No rich operator-facing UI beyond the learning workbench.
+- **Approach**: Apply the M8.53 pattern — one bounded consumer reusing shipped API contracts, no new persistence or routes.
+
+### Dormant Lanes
+- **Backend escalation**: sqlite + ANN sufficient. Wake only on measured pressure.
+- **Broader operator dashboards**: Stay behind consumer-adoption seam.
+- **Markdown reader work**: Not ahead of mastery loop unless it directly compounds the operator/study loop.
+
 ## Current Delivery Focus
 
 The conversation-product hardening lane (M8.20-M8.52) is **complete**. All 33 increments ship on `main` with passing CI.