|
| 1 | +--- |
| 2 | +date: 2026-04-20 |
| 3 | +topic: mainline-checkpoint-ci-hardening-and-post-m8-direction |
| 4 | +--- |
| 5 | + |
| 6 | +# Mainline Checkpoint: CI Hardening and Post-M8 Direction Requirements |
| 7 | + |
| 8 | +## Problem Frame |
| 9 | + |
| 10 | +`main` is no longer missing evidence. |
| 11 | +`main` is missing a clean checkpoint. |
| 12 | + |
| 13 | +Three things drifted at once: |
| 14 | + |
| 15 | +- the newest mainline truth moved from post-M7 closure into `M8.1` through `M8.18` foundation-readiness inspectability work, |
| 16 | +- the current EN/ZH progress pages still carry outdated framing in their top-level time window and delivery-focus narrative, |
| 17 | +- the most recent `Migration Gates` failure on `main` was not an architecture regression but a Windows timing-sensitive cache-restore test, and that distinction needs to be captured accurately before the next lane choice. |
| 18 | + |
| 19 | +This checkpoint re-baselines current code and docs on 2026-04-20, closes the restore-cache CI timing hole, and makes the next primary direction explicit. |
| 20 | + |
| 21 | +## Verified Mainline Reality (2026-04-20) |
| 22 | + |
| 23 | +- `main` already carries the full bounded notification-threshold governance closure through `M7.29`. |
| 24 | + The current route family is coherent and should now be treated as closed unless a materially new operator need appears. |
| 25 | +- `main` already carries the full bounded foundation-readiness inspectability chain through `M8.18`: |
| 26 | + - readiness bundle/report generation, |
| 27 | + - typed readiness route, |
| 28 | + - query/vector boundary evidence, |
| 29 | + - graph/vector signal semantics, |
| 30 | + - provenance, |
| 31 | + - promotion criteria and derived ids, |
| 32 | + - runtime parity for gates, blockers, recommendations, and the full criterion matrix. |
| 33 | +- current foundation status on `main` is still: |
| 34 | + - `status = in_progress` |
| 35 | + - `decision = no-go` |
| 36 | + - `graphBackendIndependent = false` |
| 37 | + - `vectorAdapterIndependent = false` |
| 38 | +- the latest published `main` CI state is green, not red: |
| 39 | + - `Migration Gates` run `24703509626` succeeded, |
| 40 | + - `Fixrisk Operational Readiness` run `24703509639` succeeded, |
| 41 | + - `Mobile E2E Detox Contracts` run `24703509627` succeeded, |
| 42 | + - `Docs Diataxis Site` run `24703509663` succeeded, |
| 43 | + - `Docs GitHub Pages Publish` run `24703509632` succeeded. |
| 44 | +- the last confirmed `main` CI failure was a transient Windows flake, not a readiness-status change: |
| 45 | + - workflow `Migration Gates`, run `24702925778`, |
| 46 | + - failing job `desktop-migration-suite`, |
| 47 | + - failing test `src/server.migration.test.ts` named-target cache restore coverage, |
| 48 | + - failure mode `Exceeded timeout of 20000 ms for a test`. |
| 49 | + |
| 50 | +## Deep Comparison: Prior Requirements vs Current Code |
| 51 | + |
| 52 | +| Prior source | Earlier direction | Current code reality | Judgment | Consequence | |
| 53 | +|---|---|---|---|---| |
| 54 | +| `docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md` | finish bounded M7 work, then shift to foundation readiness | `M7.29` is landed and `M8.1`-`M8.18` already executed on `main` | partially stale | current docs must stop speaking as if the lane switch is still pending | |
| 55 | +| `docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md` | post-M7 truth pass, recommend M8 readiness execution | recommendation was correct, but execution already advanced far beyond the initial M8 entry slice | needs superseding checkpoint | current checkpoint should record delivered M8 inspectability scope, not re-propose it | |
| 56 | +| `docs/diataxis/en/explanation/development-progress-dashboard.md` | delivery focus still framed as staged L4/L5 integration into `main` | current mainline work is now checkpoint hygiene plus CI hardening, not basic integration catch-up | stale framing | top-level dashboard sections should stop narrating old integration anxiety | |
| 57 | +| `docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md` | anti-overclaim gate and readiness contract | still correct, but missing the latest CI timing-failure interpretation and checkpoint date | still valid but incomplete | checklist should distinguish runtime-truth from CI-flake recovery | |
| 58 | +| `src/server.migration.test.ts` + `src/server.ts` | restore-cache dedupe implicitly proved by sequential duplicate request | sequential duplicate request depended on the second request landing inside a three-second suppression window after the first restore began | timing-sensitive on slow Windows runners | dedupe proof should become in-flight and deterministic | |
| 59 | + |
| 60 | +## Critical Findings |
| 61 | + |
| 62 | +1. `M8` inspectability work is already beyond “entry” status. |
| 63 | + Any document still framing foundation readiness as merely a future bridge is lagging behind code reality. |
| 64 | + |
| 65 | +2. The latest remote `main` CI problem was a flake, not a current outage. |
| 66 | + Treating it as an active red-main incident would be factually wrong. |
| 67 | + |
| 68 | +3. The restore-cache flake came from a bad test assumption, not just slow hardware. |
| 69 | + The old test assumed a sequential duplicate restore would still hit the three-second suppression window after the first restore path completed. |
| 70 | + That assumption is weak on a loaded Windows runner because the first restore can consume enough time to push the second request outside the dedupe window. |
| 71 | + |
| 72 | +4. Another M8 runtime-parity micro-slice is not the highest-leverage next move. |
| 73 | + After `M8.18`, continuing inspectability-only increments without a fresh lane decision is local optimization. |
| 74 | + |
| 75 | +## Requirements |
| 76 | + |
| 77 | +**Checkpoint Truth Refresh** |
| 78 | +- R1. Add a fresh 2026-04-20 checkpoint requirements document instead of silently rewriting the 2026-04-19 record. |
| 79 | +- R2. EN/ZH progress dashboards must update their top-level time window, current delivery focus, and current priority narrative to match the real `main` state after `M8.18`. |
| 80 | +- R3. EN/ZH readiness checklist pages must record that the last `main` CI failure was run `24702925778`, while the latest published `main` runs are green. |
| 81 | +- R4. The new checkpoint must state clearly that `main` remains `in_progress` / `no-go` for foundation promotion, despite the expanded readiness inspectability surface. |
| 82 | + |
| 83 | +**CI Hardening** |
| 84 | +- R5. Named-target cache restore dedupe must no longer depend on a sequential duplicate request arriving inside a narrow timing window after the first restore copy path completes. |
| 85 | +- R6. `/api/restore-cache` must suppress in-flight duplicate restore requests for the same target using runtime state, while preserving the existing short post-completion suppression behavior for immediate repeats. |
| 86 | +- R7. The migration contract test must assert deterministic in-flight dedupe instead of timing-sensitive sequential dedupe. |
| 87 | +- R8. CI hardening must preserve existing endpoint semantics: |
| 88 | + - first restore still materializes `data.js` and `graph_data.json`, |
| 89 | + - duplicate restore still returns `success: true` with `deduped: true`, |
| 90 | + - missing cache behavior must remain unchanged. |
| 91 | + |
| 92 | +**Post-M8 Direction Governance** |
| 93 | +- R9. The current primary lane must be described as `checkpoint closure + CI hardening`, not “keep extending M8 runtime parity”. |
| 94 | +- R10. After this checkpoint lands, the next planning round should default to foundation backend independence work, not another inspectability-only increment. |
| 95 | +- R11. Notification-threshold governance must remain explicitly closed after `M7.29`; no `M7.30+` planning should resume without a new operator requirement. |
| 96 | +- R12. Markdown-reader and broader product-surface work remain secondary until the next lane is chosen deliberately against the checkpointed mainline truth. |
| 97 | + |
| 98 | +## Success Criteria |
| 99 | + |
| 100 | +- A new checkpoint document exists and becomes the top current source-of-truth item in `docs/brainstorms/index.md`. |
| 101 | +- EN/ZH progress dashboards and EN/ZH readiness checklists are updated section-by-section to reflect current mainline truth and the CI recovery interpretation. |
| 102 | +- `src/server.ts` and `src/server.migration.test.ts` no longer rely on timing-sensitive sequential restore dedupe assumptions. |
| 103 | +- Local verification passes for migration, runtime contracts, readiness verification, and docs build. |
| 104 | +- The branch is pushed to `main`, remote CI is re-triggered from the hardened commit, and the worktree is clean afterward. |
| 105 | + |
| 106 | +## Scope Boundaries |
| 107 | + |
| 108 | +- This checkpoint does not claim graph backend or vector backend independence landed on `main`. |
| 109 | +- This checkpoint does not reopen notification-threshold route expansion. |
| 110 | +- This checkpoint does not start markdown-reader execution work. |
| 111 | +- This checkpoint does not choose or implement a new backend persistence engine. |
| 112 | + |
| 113 | +## Key Decisions |
| 114 | + |
| 115 | +- **Create a new checkpoint doc instead of mutating the 2026-04-19 record**: historical reasoning stays auditable and the new checkpoint can speak plainly about what actually landed after that date. |
| 116 | +- **Fix the restore-cache flake at the runtime contract boundary, not by hand-waving CI**: the timing-sensitive test assumption is the weak point, so both runtime dedupe semantics and the test proof should become deterministic. |
| 117 | +- **Freeze inspectability-only expansion after `M8.18`/checkpoint hardening**: current marginal value is lower than backend-independence planning or other broader product work. |
| 118 | +- **Describe remote CI honestly**: `main` is currently green, and the job here is recurrence hardening plus checkpoint documentation, not incident-response theater. |
| 119 | + |
| 120 | +## Dependencies / Assumptions |
| 121 | + |
| 122 | +- Verification commands remain available and representative: |
| 123 | + - `npm run test:migration` |
| 124 | + - `npm run test:agent-workspace:contracts` |
| 125 | + - `npm run verify:agent-workspace:runtime` |
| 126 | + - `npm run verify:foundation:readiness` |
| 127 | + - `npm run docs:diataxis:check` |
| 128 | + - `npm run docs:site:build` |
| 129 | +- Published GitHub Actions history remains available through `gh run view` for run-level evidence. |
| 130 | + |
| 131 | +## Outstanding Questions |
| 132 | + |
| 133 | +### Deferred to Planning |
| 134 | +- [Affects R10][Technical] Which concrete backend-independence slice should lead the next foundation round: graph persistence independence, vector independence, or a thinner readiness gate around one of them? |
| 135 | +- [Affects R12][Needs research] After backend-independence planning is refreshed, does markdown-reader governance still merit the next user-facing lane, or has agent/product-side value overtaken it? |
| 136 | + |
| 137 | +## Next Steps |
| 138 | + |
| 139 | +-> /ce:plan for post-checkpoint foundation backend independence planning, after this CI hardening and documentation checkpoint lands on `main`. |
0 commit comments