docs: rebaseline mainline progress and post-m7 direction

Author: Jacobinwwey

docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md

@@ -0,0 +1,169 @@
+---
+date: 2026-04-19
+topic: mainline-progress-reconciliation-and-post-m7-direction
+---
+
+# Mainline Progress Reconciliation and Post-M7 Direction Requirements
+
+## Problem Frame
+
+Current risk is no longer missing implementation.
+Current risk is **stale architectural narration**:
+
+- some current progress sections still describe `main` as an earlier snapshot even though `main` now carries substantial L3/L4/L5 evidence,
+- some older branch-vs-mainline comparisons are still directionally useful but now understate what already landed on `main`,
+- the notification-threshold governance lane is coherent through `M7.28`, but continuing micro-increments without a stop rule risks local optimization instead of product or foundation leverage.
+
+This document re-baselines current mainline truth on 2026-04-19, records what changed relative to the prior requirement chain, and sets a concrete post-M7 direction that does not blindly continue the current micro-lane.
+
+## Verified Mainline Reality (2026-04-19)
+
+- `main` already contains the bounded notification-threshold governance chain through:
+  - `cbc9afc` (`M7.26` bounded apply-outcome history),
+  - `494d0c8` (`M7.27` supersession summary),
+  - `9a4488f` (`M7.28` filtered outcome history).
+- `src/server.ts` now carries a dense L5 operator-governance route family for notification-threshold preview, apply, reconciliation, bounded history, summary, and filtered history views.
+- `src/learning/KnowledgeLearningPlatform.ts`, `src/learning/types.ts`, `src/learning/KnowledgeLearningPlatform.test.ts`, and `src/learning/KnowledgeLearningPlatform.persistence.test.ts` show that mainline already has:
+  - explainable retrieval with `relationPath` and `temporalValidity`,
+  - learning-path generation,
+  - study-session planning,
+  - misconception querying,
+  - memory-layer operations,
+  - file-backed persistence and reload coverage.
+- `src/frontend/agent_workspace.js`, `src/frontend/agent_workspace_runtime.js`, `src/agent_workspace.contract.parity.test.ts`, `src/agent_workspace.frontend.test.ts`, `src/agent_workspace.runtime.integration.test.ts`, and `src/agent_workspace.runtime.behavior.test.ts` show that mainline already has:
+  - typed operation/result-presentation discipline,
+  - agent conversation rendering,
+  - focus-mode activation from conversation results,
+  - learning-path dock coexistence and fullscreen lifecycle coverage.
+- `src/markdown/MarkdownGateway.ts` exists on mainline, but markdown-reader governance is still a bounded backlog lane rather than the current active mainline delivery lane.
+- `src/learning/store.ts` remains file-backed on mainline.
+  Mainline still does **not** contain separate graphdb/vector adapter modules that would justify claiming foundation re-entry completion.
+
+## Deep Comparison: Prior Requirements vs Current Code
+
+| Prior source | Claim / direction | Current mainline evidence | Judgment | Why it matters now |
+|---|---|---|---|---|
+| `docs/brainstorms/2026-04-11-evolution-progress-alignment-requirements.md` | L2/L3/L4/L5 already had meaningful baseline substance | `src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/agent_workspace_runtime.js`, `src/server.ts` support this on `main` | Still true | Current dashboard language should not regress below this evidence level |
+| `docs/brainstorms/2026-04-14-mainline-integration-progress-gap-requirements.md` | Mainline still lacked much of the L4 shell/runtime/governance surface | true on 2026-04-14, but stale after M6-M7 landing on `main` | Partially stale | branch-vs-mainline gap framing now overstates how far behind `main` is |
+| `docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md` | strongest active lane was L4 convergence, foundation remained evidence-first future work | L4 convergence landed and then expanded into L5 governance on `main`; foundation caution still valid | Mixed: lane judgment aged, foundation warning still valid | current direction must recognize that L5, not L4, became the dominant recent lane |
+| `docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md` | M7 should stay reliability-first and bounded; `M7.29` is the next narrow increment | `main` now carries M7.26-M7.28 exactly as documented | Still true, but diminishing-return risk is now visible | next step should either finish `M7.29` as a closure increment or stop the lane |
+| current dashboards | Phase/Layer rows still describe `main` as “earlier baseline only” or “partially available” in places | tests and code now show stronger L2/L3/L4 mainline reality | Under-claimed | current progress docs need a truth refresh, not just another route bullet |
+
+## Architecture Progress Snapshot (Mainline, 2026-04-19)
+
+| Layer | Current Mainline State | Progress Judgment | Constraint |
+|---|---|---|---|
+| L0 Representation | atom/evidence extraction and staleness semantics are stable | Stable | no urgent blocker |
+| L1 Structure | relation and temporal graph semantics are present in current learning core | Stable | no urgent blocker |
+| L2 Retrieval foundation | explainable retrieval is already integrated, but persistence remains file-backed and no separate graphdb/vector adapter boundary has landed | Advanced baseline, foundation lane not re-entered | do not overclaim graphdb/vector readiness |
+| L3 Learning loop | misconception/path/session/memory flows are integrated and persistence-tested | Advanced baseline | avoid describing this as merely partial without qualifier |
+| L4 Interaction | conversation shell, typed operation routing, focus-mode, learning-path dock coexistence, and runtime verification are integrated | Integrated baseline | broaden only through typed contract discipline |
+| L5 Governance | operator diagnostics and notification-threshold governance expanded deeply through `M7.28` | Deep integrated lane | further route fragmentation now has diminishing returns |
+
+## Critical Findings (Pressure Test)
+
+1. **The current dashboard understates mainline reality.**
+   Calling L2 “earlier baseline only” and L3/L4 broadly “partially integrated” is no longer precise enough for 2026-04-19.
+
+2. **The branch-vs-mainline framing has aged unevenly.**
+   It is still useful for markdown-reader and foundation gaps, but it is now too pessimistic for L3/L4/L5.
+
+3. **The notification-threshold lane is coherent but near its economic limit.**
+   `M7.29` is still a defensible increment because it closes the current history-surface family.
+   Anything beyond that requires stronger justification than “the route family can still be subdivided.”
+
+4. **Foundation caution remains correct.**
+   Mainline has a stronger retrieval baseline than some current docs admit, but that is not the same as graphdb/vector foundation re-entry.
+
+## Strategy Options
+
+### Option A: Keep extending notification-threshold governance after M7.28
+
+- Pros: low context-switch cost; small, local diffs; route-family coherence remains high.
+- Cons: pushes the project deeper into a micro-operator lane with lower marginal product value.
+- Best when: there is a concrete operator consumer who needs one more history-surface cut immediately.
+
+### Option B: Stop the lane immediately and pivot straight to foundation or markdown work
+
+- Pros: rebalances attention toward broader architecture or user-facing value.
+- Cons: leaves the notification-threshold history family one step short of its currently documented closure increment.
+- Best when: current operator consumers do not need applied-mode filtering and the team wants a harder pivot now.
+
+### Option C: Finish `M7.29` as the last justified closure increment, then force a post-M7 lane switch (Recommended)
+
+- Pros: closes the currently documented history-surface family with one more bounded step, preserves local coherence, and creates a clean stopping point.
+- Cons: still spends one more increment on L5 before shifting to broader leverage.
+- Best when: the team wants disciplined closure rather than an abrupt pivot, but does not want infinite L5 expansion.
+
+## Requirements
+
+**Documentation Truth Refresh**
+- R1. Current progress documents must re-baseline L2/L3/L4/L5 against executable mainline evidence as of 2026-04-19.
+- R2. Current progress documents must explicitly separate:
+  - what is integrated on `main`,
+  - what is still branch-only or backlog-only,
+  - what is the next bounded direction.
+- R3. `docs/brainstorms/index.md` must list this reconciliation document as a current source-of-truth artifact.
+
+**Lane Direction Governance**
+- R4. `M7.29` may proceed only as a bounded closure increment for the notification-threshold history surface.
+- R5. No `M7.30+` notification-threshold increment should be planned unless a new operator requirement appears that is materially stronger than “surface completeness.”
+- R6. Immediately after `M7.29` completion, the primary lane must switch away from notification-threshold micro-expansion.
+
+**Progress Interpretation Corrections**
+- R7. L2 mainline must be described as an explainable retrieval baseline with file-backed persistence, not as an empty or merely placeholder baseline.
+- R8. L3 mainline must be described as an advanced integrated baseline for path/session/misconception/memory flows, while still noting that broader branch ambitions remain unmerged.
+- R9. L4 mainline must be described as an integrated conversation + focus/path runtime baseline with contract and runtime gates, not as a largely missing shell.
+- R10. L5 mainline must be described as a deep integrated operator-governance lane through `M7.28`, with a warning against indefinite route fragmentation.
+
+**Post-M7 Planning Gate**
+- R11. The next structured planning round after this reconciliation must choose exactly one **immediate** primary lane:
+  - `M7.29 notification-threshold applied-mode history views`,
+  - `M8 foundation re-entry readiness execution`,
+  - `M8 markdown-reader governance execution`.
+- R12. If the immediate primary lane is `M7.29`, the following structured planning round should default to `M8 foundation re-entry readiness execution`, because current docs still need an evidence-first bridge between the real L2 baseline and the not-yet-landed graphdb/vector claims.
+
+## Success Criteria
+
+- Current progress dashboards no longer describe mainline with stale 2026-04-14 underclaims.
+- The project has a concrete, written stop rule for the current notification-threshold micro-lane.
+- The next direction is explicit:
+  - `M7.29` as the last bounded L5 closure increment,
+  - then `M8 foundation re-entry readiness execution` as the recommended primary lane.
+- The workspace remains clean after documentation updates land on `main`.
+
+## Scope Boundaries
+
+- This document does not claim graphdb/vector foundation re-entry is already complete on `main`.
+- This document does not reopen broad branch merge strategy.
+- This document does not start markdown-reader execution work; it only repositions that lane in the priority stack.
+- This document does not introduce new endpoint or schema design beyond lane-level direction.
+
+## Key Decisions
+
+- **Use a fresh 2026-04-19 reconciliation document instead of mutating older requirement records wholesale**: older docs remain historically useful and should stay auditable.
+- **Treat `M7.29` as a closure increment, not a new open-ended lane**: this preserves coherence without normalizing infinite L5 slicing.
+- **Raise the documented maturity of current mainline L2/L3/L4**: current code and tests now justify stronger wording than some current dashboard rows use.
+- **Recommend foundation re-entry readiness after `M7.29`**: this is the highest-leverage correction to current architecture imbalance without overclaiming unfinished adapters.
+
+## Dependencies / Assumptions
+
+- Mainline verification gates used by the dashboards remain runnable:
+  - `npm run docs:diataxis:check`
+  - `npm run docs:site:build`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
+- The current working branch remains a reference source for future lanes, not a justification for direct wide merge.
+
+## Outstanding Questions
+
+### Deferred to Planning
+- [Affects R11][Technical] Should `M7.29` filter only by `appliedMode`, or should planning evaluate a combined `status + appliedMode` contract while keeping the route bounded?
+- [Affects R12][Needs research] What is the smallest executable `M8 foundation re-entry readiness` slice that increases evidence quality without prematurely introducing graphdb/vector abstractions?
+- [Affects R11][Needs research] Does markdown-reader governance now have a stronger near-term product case than foundation re-entry once the post-M7 checkpoint happens?
+
+## Next Steps
+
+-> /ce:plan for a structured plan that chooses one immediate lane now, with the recommended sequence being `M7.29` as the last bounded L5 closure increment and `M8 foundation re-entry readiness execution` as the default follow-on lane after that.

docs/brainstorms/index.md

@@ -4,6 +4,7 @@ This page tracks active and archived brainstorming outputs used before implement
 
 ## Current
 
+- [2026-04-19 Mainline Progress Reconciliation and Post-M7 Direction Requirements](2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md)
 - [2026-04-16 Mainline CI Stabilization and M7 Direction Requirements](2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md)
 - [2026-04-14 Mainline Reality Reconciliation and Next Direction Requirements](2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md)
 - [2026-04-14 Mainline Integration Progress Gap Closure Requirements](2026-04-14-mainline-integration-progress-gap-requirements.md)