|
| 1 | +--- |
| 2 | +date: 2026-04-16 |
| 3 | +topic: mainline-ci-stabilization-and-m7-direction |
| 4 | +--- |
| 5 | + |
| 6 | +# Mainline CI Stabilization and M7 Direction Requirements (Execution v1, 2026-04-16) |
| 7 | + |
| 8 | +## Problem Frame |
| 9 | + |
| 10 | +Current blocker is no longer capability definition. |
| 11 | +Current blocker is **integration credibility under CI**: |
| 12 | + |
| 13 | +- `Migration Gates` was repeatedly red on `main` for the agent-workspace runtime/browser/tauri contract suites. |
| 14 | +- failure logs were too shallow (`Command failed: npm.cmd ...`) to diagnose root cause quickly on Windows runners. |
| 15 | +- branch-vs-mainline drift risk remains high if progress docs are not updated with today’s verified evidence. |
| 16 | + |
| 17 | +This cycle therefore prioritizes: |
| 18 | + |
| 19 | +1. make CI diagnostics and cross-platform npm execution deterministic for agent-workspace gates, |
| 20 | +2. re-baseline requirements and progress docs against current mainline code reality, |
| 21 | +3. define next execution direction (`M7`) with explicit tradeoffs and risk controls. |
| 22 | + |
| 23 | +## Inputs |
| 24 | + |
| 25 | +- `docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md` |
| 26 | +- `docs/brainstorms/2026-04-14-mainline-integration-progress-gap-requirements.md` |
| 27 | +- `docs/brainstorms/2026-04-14-agent-workspace-contract-closure-next-direction-requirements.md` |
| 28 | +- `docs/diataxis/en/explanation/development-progress-dashboard.md` |
| 29 | +- `docs/diataxis/zh/explanation/development-progress-dashboard.md` |
| 30 | +- `docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md` |
| 31 | +- `scripts/verify-agent-workspace-runtime.js` |
| 32 | +- `scripts/verify-agent-workspace-browser.js` |
| 33 | +- `scripts/verify-agent-workspace-tauri.js` |
| 34 | +- `.github/workflows/migration-gates.yml` |
| 35 | +- `src/frontend/agent_workspace_runtime.js` |
| 36 | +- `src/frontend/path_app.js` |
| 37 | +- `src/agent_workspace.runtime.integration.test.ts` |
| 38 | +- `src/agent_workspace.runtime.behavior.test.ts` |
| 39 | + |
| 40 | +## Verified Mainline Reality (2026-04-16) |
| 41 | + |
| 42 | +- mainline commit with this stabilization: `3967b9d` (`fix(ci): harden agent workspace verify npm invocation on windows`). |
| 43 | +- `Migration Gates` latest run: `24502592419` -> `success` (all matrix jobs green). |
| 44 | +- previously failing runs (for context): `24405317254`, `24404975285`. |
| 45 | +- agent-workspace verify wrappers now: |
| 46 | + - prefer `process.execPath + process.env.npm_execpath`, |
| 47 | + - fallback to `cmd.exe /d /s /c npm ...` on Windows, |
| 48 | + - surface `status/signal/error_code` on failure. |
| 49 | +- conversation -> focus mode and conversation -> learning path dock behavior remains covered by runtime and integration tests. |
| 50 | + |
| 51 | +## Deep Comparison: Prior Requirements vs Current Code |
| 52 | + |
| 53 | +| Requirement Source | Requirement | Verified Code Evidence | Status | Gap / Risk | |
| 54 | +|---|---|---|---|---| |
| 55 | +| 2026-04-14 mainline reality (R1-R5) | docs claims must map to runnable gates | `docs/diataxis/*/development-progress-dashboard.md`, `.github/workflows/migration-gates.yml`, `src/agent_workspace.verification.contract.test.ts` | Done | need continuous doc refresh per increment | |
| 56 | +| 2026-04-14 mainline reality (R6-R10) | capability expansion must remain typed + fail-fast | `src/learning/types.ts`, `src/frontend/agent_workspace.js`, `src/frontend/agent_workspace_runtime.js`, contract/behavior tests | Done (M6 lane) | action surface is broad; future drift risk grows with manual wiring | |
| 57 | +| 2026-04-14 mainline reality (R9) | agent-workspace suites must stay mandatory in CI | `.github/workflows/migration-gates.yml`, run `24502592419` | Done | Windows invocation fragility was real and just fixed | |
| 58 | +| agent-conversation-focus-mode-plan | conversation primary, focus/path panes side-by-side, independent fullscreen | `src/frontend/agent_workspace_runtime.js`, `src/frontend/path_styles.css`, `src/agent_workspace.runtime.integration.test.ts` | Partial+ | source-level evidence is strong; end-to-end pane coexistence evidence under real Tauri window lifecycle is still thin | |
| 59 | +| 2026-04-14 integration gap (R8-R9) | foundation lane re-entry only after concrete mainline evidence | `src/learning/store.ts` remains file-backed baseline on mainline | Planned | risk of overclaiming branch-only foundation progress | |
| 60 | +| markdown reader upgrade requirements | markdown governance lane should advance as bounded track | mainline docs exist, but no new mainline increment after 2026-04-14 chain | Planned | avoid coupling this lane with L4 CI stabilization lane | |
| 61 | + |
| 62 | +## Architecture Progress Snapshot (Mainline) |
| 63 | + |
| 64 | +| Layer | Current Mainline State | Progress Judgment | |
| 65 | +|---|---|---| |
| 66 | +| L0-L1 (representation/structure) | stable baseline, no new regression signal in this cycle | Stable | |
| 67 | +| L2 (retrieval foundation) | file-backed persistence baseline still dominant on mainline | Not yet re-entered | |
| 68 | +| L3 (learning loop) | session/quality/memory/query/misconception capability surface integrated through typed actions | Advanced baseline | |
| 69 | +| L4 (interaction) | conversation + focus + path dock orchestration integrated; CI stabilization completed | Main active lane | |
| 70 | +| L5 (governance) | migration gate coverage and diagnostics improved; Windows failure observability fixed | Improved, still expandable | |
| 71 | + |
| 72 | +## Critical Pressure Test |
| 73 | + |
| 74 | +1. Assumption: "CI now green means lane is closed." |
| 75 | + - Flaw: current fix addresses invocation robustness and observability, not all future contract drift classes. |
| 76 | + - Requirement: preserve strict parity tests and keep capability additions gated. |
| 77 | + |
| 78 | +2. Assumption: "source-level tauri contract equals UX closure." |
| 79 | + - Flaw: source-level checks do not fully represent multi-pane lifecycle under real desktop runtime transitions. |
| 80 | + - Requirement: add bounded runtime evidence cases for pane coexistence and fullscreen restore behavior. |
| 81 | + |
| 82 | +3. Assumption: "foundation and markdown lanes can be pulled into same increment safely." |
| 83 | + - Flaw: coupling these lanes with L4 runtime lane increases blast radius and review complexity. |
| 84 | + - Requirement: keep lane boundaries explicit in M7 execution. |
| 85 | + |
| 86 | +## Approach Options |
| 87 | + |
| 88 | +### Option A: Continue capability expansion immediately |
| 89 | + |
| 90 | +- Pros: visible product delta. |
| 91 | +- Cons: increases wiring drift risk while runtime evidence depth is incomplete. |
| 92 | +- Risk: medium-high. |
| 93 | + |
| 94 | +### Option B: M7 reliability-first closure, then bounded expansion (Recommended) |
| 95 | + |
| 96 | +- Pros: preserves momentum while reducing false-green risk and doc/code divergence. |
| 97 | +- Cons: less headline feature velocity. |
| 98 | +- Risk: low-medium. |
| 99 | + |
| 100 | +### Option C: pivot directly to foundation lane |
| 101 | + |
| 102 | +- Pros: aligns with long-term architecture goals. |
| 103 | +- Cons: interrupts active interaction lane and risks reopening CI instability surface. |
| 104 | +- Risk: high. |
| 105 | + |
| 106 | +Recommendation: **Option B**. |
| 107 | + |
| 108 | +## M7 Requirements (Next Direction) |
| 109 | + |
| 110 | +### R1-R4 Reliability and Contract Discipline |
| 111 | + |
| 112 | +- R1. Keep the three agent-workspace verify wrappers on shared cross-platform invocation semantics (`npm_execpath` first, Windows fallback second). |
| 113 | +- R2. Failure diagnostics from wrappers must always include `status/signal/error_code` when available. |
| 114 | +- R3. Any new capability action must still satisfy typed union + contract suite + runtime behavior suite together. |
| 115 | +- R4. Keep `migration-gates.yml` agent-workspace matrix entries contract-tested. |
| 116 | + |
| 117 | +### R5-R8 Interaction Evidence Depth |
| 118 | + |
| 119 | +- R5. Add/expand behavior evidence for focus + learning-path dock coexistence and independent fullscreen toggles. |
| 120 | +- R6. Keep agent conversation panel as primary surface; pane promotions must remain reversible state transitions. |
| 121 | +- R7. Ensure path bridge visibility calls remain deterministic when pane state changes. |
| 122 | +- R8. Keep language re-render behavior stable for capability cards and pane labels. |
| 123 | + |
| 124 | +### R9-R11 Lane Boundary Governance |
| 125 | + |
| 126 | +- R9. Foundation lane stays planned until mainline modules and gates land as code evidence. |
| 127 | +- R10. Markdown reader governance remains a bounded parallel lane and must not be bundled into M7 reliability closure by default. |
| 128 | +- R11. Every M7 checkpoint must update both EN/ZH progress dashboards with runnable gates. |
| 129 | + |
| 130 | +## M7 Execution Plan (Concrete) |
| 131 | + |
| 132 | +### M7.1 (Immediate): Reliability Closure Pack |
| 133 | + |
| 134 | +Deliverables: |
| 135 | + |
| 136 | +- CI wrapper hardening landed and documented. |
| 137 | +- migration run evidence linked in progress docs. |
| 138 | +- dashboards refreshed with today’s mainline status. |
| 139 | + |
| 140 | +Gates: |
| 141 | + |
| 142 | +```bash |
| 143 | +npm run test:agent-workspace:contracts |
| 144 | +npm run verify:agent-workspace:runtime |
| 145 | +npm run verify:agent-workspace:browser |
| 146 | +npm run verify:agent-workspace:tauri |
| 147 | +npm run docs:diataxis:check |
| 148 | +npm run docs:site:build |
| 149 | +``` |
| 150 | + |
| 151 | +### M7.2 (Next): Pane Coexistence Runtime Evidence Deepening |
| 152 | + |
| 153 | +Deliverables: |
| 154 | + |
| 155 | +- expanded behavior/runtime tests for focus-path coexistence + fullscreen promote/restore lifecycle. |
| 156 | +- explicit assertions around `requestBridgeWindowVisibility` transitions. |
| 157 | + |
| 158 | +### M7.3 (Then): Foundation Re-entry Readiness Checklist (No Overclaim) |
| 159 | + |
| 160 | +Deliverables: |
| 161 | + |
| 162 | +- documented mainline preconditions for graphdb/ANN re-entry. |
| 163 | +- explicit non-goal statement preventing branch-only claims from entering mainline progress sections. |
| 164 | + |
| 165 | +## Success Criteria |
| 166 | + |
| 167 | +- CI failure mode that previously blocked the three agent-workspace suites is eliminated on mainline. |
| 168 | +- progress docs are updated section-by-section in both languages with current evidence. |
| 169 | +- next direction is explicit (`M7 reliability-first`) and bounded by lane governance. |
| 170 | +- active workspace is clean after push to `main`. |
| 171 | + |
| 172 | +## Next Step |
| 173 | + |
| 174 | +Proceed to `/prompts:ce-plan` using this document as the source for `M7.2` and `M7.3` decomposition. |
0 commit comments