From bccf06d9606be04b817113b810adf28dfb0c5d28 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 23 Oct 2026 17:14:30 +0200 Subject: [PATCH] wip: phase 19.7 paused at gap plan 8/9 (before 19.7-09) --- .planning/HANDOFF.json | 46 ++++--- .../19.7-generic-mcp-module/.continue-here.md | 114 ++++++++++++++++++ 2 files changed, 136 insertions(+), 24 deletions(-) create mode 100644 .planning/phases/19.7-generic-mcp-module/.continue-here.md diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index 6e27bf3d..a25ed948 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,40 +1,38 @@ { "version": "1.0", - "timestamp": "2026-10-20T09:20:51.976Z", - "phase": "19.4.1", - "phase_name": "Early public demo on demo.summercms.io (INSERTED)", - "phase_dir": ".planning/phases/19.4.1-early-public-demo-on-demo-summercms-io", - "plan": 1, - "task": 4, + "timestamp": "2026-10-23T15:13:42.099Z", + "phase": "19.7", + "phase_name": "Generic MCP module (INSERTED)", + "phase_dir": ".planning/phases/19.7-generic-mcp-module", + "plan": "19.7-09", + "task": 0, "total_tasks": 4, "status": "paused", "completed_tasks": [ - {"id": 1, "name": "Tracer: English deck from ROADMAP.md shown in bm's viewer", "status": "done", "commit": "b80aaaf, 7a4a6b0, 4514159 (sm-demo-app)"}, - {"id": 2, "name": "Whole deck in EN and PL: roadmap, features, migration, pxpx, MCP future", "status": "done", "commit": "680fd82 (sm-demo-app)"}, - {"id": 3, "name": "OIDC provider screenshots, no duplicate images on re-seed", "status": "done", "commit": "37ee65e (sm-demo-app)"} + {"id": "19.7-06", "name": "pier hardening (review lane A)", "status": "done", "commit": "6ca9e17"}, + {"id": "19.7-07", "name": "auth_time, frontend token scopes seam, cabana and admin SPA (lane B)", "status": "done", "commit": "d6c7fd5"}, + {"id": "19.7-08", "name": "plugins and demo (lane C), E-1 logo, E-2 member token scopes", "status": "done", "commit": "1e5d9d4"} ], "remaining_tasks": [ - {"id": 4, "name": "checkpoint:human-verify — user reviews the EN/PL deck for the 2026-10-21 presentation", "status": "awaiting_user"} + {"id": "19.7-09", "name": "tests, gate, validation rows, security doc corrections", "status": "not_started"}, + {"id": "gate", "name": "re-review of 06-09, regression gate, msd-verifier, /msd-validate-phase, /msd-verify-work UAT", "status": "not_started"}, + {"id": "release", "name": "v0.5.0 then plugin tags then app bumps, changelog, g15office (user go-ahead only)", "status": "not_started"} ], "blockers": [ - {"description": "Plan 19.4.1-01 Task 4 is a blocking human-verify checkpoint", "type": "human_action", "workaround": "none — user must approve or list slide changes"} + {"description": "All work since the last tags is local and unpushed (framework 42 ahead, plugins and apps ahead). A different machine needs them pushed first.", "type": "human_action", "workaround": "Push with the user's go-ahead before resuming elsewhere"} ], "async_jobs": [], "human_actions_pending": [ - {"action": "Review both decks (30 slides each) and reply 'approved' or list slide changes (slide number, language, new text)", "context": "Deck is the user's main presentation on 2026-10-21", "blocking": true}, - {"action": "Decide whether the continuation agent should add a PRESENT_HOST env var to sm-demo-app/scripts/dev.sh (bind present servers to 0.0.0.0 for 10.8.3.4)", "context": "Currently done via an untracked scratchpad copy of dev.sh", "blocking": false}, - {"action": "Optionally report how the speaker view (/moje-prezentacje/roadmap) behaved without Centrifugo", "context": "Executor could not log in (visitor password lives in .env, which the secret guard blocks)", "blocking": false} + {"action": "Decide whether to push the local branches before moving machines", "context": "CLAUDE.md: no push without go-ahead", "blocking": true}, + {"action": "Decide sm-oauthserver-plugin's tracked go.work (local edit points user replace at the sm-demo-app checkout)", "context": "Must be clean before the oauthserver release", "blocking": false} ], "decisions": [ - {"decision": "Phase runs sequentially on main tree (workflow.use_worktrees=false); code commits go to sibling repos, planning commits to summercms.go", "rationale": "Plans target ../sm-demo-app and other siblings", "phase": "19.4.1"}, - {"decision": "Present servers bound to 0.0.0.0 via a scratchpad copy of dev.sh rather than editing dev.sh", "rationale": "Avoid uncommitted edits in a file the continuation agent will touch", "phase": "19.4.1"} + {"decision": "v0.5.0 only after full verification and validation", "rationale": "No x.y.1 hotfix right after the release", "phase": "19.7"}, + {"decision": "Plugin tags only after v0.5.0, requiring it", "rationale": "Plugins need new framework API (auth_time, HasFrontendTokenScopes)", "phase": "19.7"}, + {"decision": "Ban or password reset revokes MCP and OIDC grants", "rationale": "Compromised-account reset should end every OAuth grant", "phase": "19.7"}, + {"decision": "E-2 uses a separate pact.HasFrontendTokenScopes", "rationale": "Keeps the admin g15_ catalog untouched", "phase": "19.7"} ], - "uncommitted_files": [ - " M .planning/STATE.md", - " M .planning/state.json", - "?? .msd/", - "?? .planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/.gitkeep" - ], - "next_action": "/msd-execute-phase 19.4.1 → it finds 19.4.1-01 without SUMMARY but with commits (safe_resume_gate); choose to continue at Task 4 by spawning a continuation msd-executor with the user's deck response, then write 19.4.1-01-SUMMARY.md including deviations 1-9 from .continue-here.md", - "context_notes": "sm-demo-app is clean; 5 plan commits after 1439b3a, unpushed. No SUMMARY yet. STATE.md/state.json modifications are from state.begin-phase (and possibly other sessions) — leave alone, do not commit them with the handoff." + "uncommitted_files": [" M .planning/state.json", "?? .msd/", "?? .planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/.gitkeep", "?? .planning/phases/19.6.1-backend-administrators-screen/.gitkeep"], + "next_action": "Verify repos at the listed HEADs (see .continue-here.md), then /msd-execute-phase 19.7 --gaps-only to run 19.7-09", + "context_notes": "Orchestrator dispatches msd-executor per plan sequentially on the main tree, passing version-drift corrections; tracking is updated via msd-tools after each plan." } diff --git a/.planning/phases/19.7-generic-mcp-module/.continue-here.md b/.planning/phases/19.7-generic-mcp-module/.continue-here.md new file mode 100644 index 00000000..416acd3e --- /dev/null +++ b/.planning/phases/19.7-generic-mcp-module/.continue-here.md @@ -0,0 +1,114 @@ +--- +context: phase +phase: 19.7-generic-mcp-module +plan: 19.7-09 +task: 0 +total_tasks: 4 +status: paused +last_updated: 2026-10-23T15:13:42.099Z +--- + +# Phase 19.7: paused before gap plan 19.7-09 + +## Critical Anti-Patterns + +| Pattern | Description | Severity | Prevention Mechanism | +|---------|-------------|----------|---------------------| +| Tagging before full verification | The user will not accept a v0.5.0 that is bumped to v0.5.1 right after because verification found something. The plan 05 security review marked T-19.7-22 as verified, and a deep code review then found 3 critical issues. | blocking | Tag nothing until every gate below is green and its findings are fixed: the re-review of plans 06-09, the regression gate, msd-verifier, /msd-validate-phase and /msd-verify-work (UAT). Only then ask the user about v0.5.0. | +| Mid-phase framework tag | v0.5.0 is reserved for phase completion. The release order is decided: framework v0.5.0, then sm-user-plugin, sm-oauthserver-plugin and sm-journal-plugin tags that require it, then the app pointer bumps. | blocking | No tag, push or deploy step inside plan 09. The release happens only after phase verification, and only on the user's go-ahead. | +| Plan drift on versions | Plans written earlier named versions that were already taken (v0.1.9) or tags that were never cut ("plan-02 tag"). | advisory | Before dispatching an executor, check the current tags (`git tag`, `ls-remote`) and pass the corrections in the executor prompt. | + + +Phase 19.7 (Generic MCP module) is at 8 of 9 plans complete. + +- Plans 01-05 are the original phase. 01-02 are released in framework v0.4.4. 03 released sm-user-plugin v0.1.10. 04 released sm-oauthserver-plugin v0.1.2 and sm-journal-plugin v0.2.3. 05 added the unit tests, the check-phase19.7.sh gate and the security review. +- A deep 3-lane code review (19.7-REVIEW.md: 3 critical, 17 warning, 20 info) led to gap-closure plans 06-09 (19.7-GAP-INPUTS.md). They also carry two sm-servers-app escalations: E-1, an organisation logo, and E-2, plugin-declared scopes for member usr_ tokens. +- Gap plans 06, 07 and 08 are executed and summarized. **19.7-09 is the next plan and has not started.** It covers tests for every fix and for E-1/E-2, the extended gate, the validation rows, and the corrected security docs. + + + +- 19.7-03: the user-plugin identity chain; sm-user-plugin v0.1.10 tagged and pushed; five apps bumped (local commits). +- Fast fix d96c726: cabana subject events now fire as `*pact.MCPSubjectChanged` after commit. +- 19.7-04: oauthserver v0.1.2 and Journal v0.2.3 tagged and pushed; vue-demo-app pushed; demo MCP wiring, nginx and DEPLOY.md. +- 19.7-05: tests, the gate, the security review, and 3 framework fixes (c49983d, 1111828, c29d228). +- Code review: 19.7-REVIEW.md (fef1cbb). Regression gate green at that point. +- Gap plans: + - 19.7-06: pier hardening, lane A (commits 2bf9dca..95f177b; SUMMARY 6ca9e17). + - 19.7-07: auth_time, the pact.HasFrontendTokenScopes seam, cabana and the admin SPA, lane B (c14238b..88559d5; SUMMARY d6c7fd5). + - 19.7-08: the plugins and demo, lane C, plus E-1 and E-2 (SUMMARY 1e5d9d4). Commits: + - user: 32f9259, 970719c, ee5c096, f20a8d3 + - oauthserver: 671513d + - journal: b129902 + - vue-demo-app: 0125e29 + - sm-demo-app: 00f57bf, 3b569a1, 7731641 + + + +1. Execute 19.7-09 (`/msd-execute-phase 19.7 --gaps-only`). Notes for its executor, from the 08 SUMMARY: + - write the named revocation tests (TestMCPVerifierRevocation, TestMCPGrantRevocation, TestAccessRevocation); + - write unit tests for linkCode.ts and OrganisationLogoFields; + - remove the now-unused `connectWatching` helper in the demo e2e test; + - record as deferred: `admin:token:revoke` fires no MCP event (from 07), B-IN-05, B-IN-06. +2. Fresh code review of the gap-closure changes (06-09) across all repos; fix its findings. +3. Regression gate: + - `go vet` and `go test ./...` with and without `-tags summercms_mcp`; + - examples/hello; + - check-phase19.6.1.sh and check-phase19.7.sh `--all`; + - check-admin-openapi.sh, check-admin-dist.sh, `summer docs:build --check`. +4. Phase-goal verification (msd-verifier → 19.7-VERIFICATION.md), then Nyquist validation (/msd-validate-phase 19.7), then UAT with the user (/msd-verify-work 19.7). UAT must include a real MCP client against the local demo; plan 04 skipped that check. +5. Decide on the deferred items in deferred-items.md that could block v0.5.0 (the user decides each one). +6. Only then, on the user's go-ahead: + - tag framework v0.5.0 and post the changelog (CLAUDE.md); + - tag the plugins requiring v0.5.0; + - bump the apps, including the sm-demo-app submodule pointers for user, oauthserver, journal and vue-demo-app; + - g15office sync: move tasks hmguritm and tqyvnzxx into milestone dcnv4mha and post the phase comment. + + + +- v0.5.0 is tagged only after full verification and validation (user, 2026-10-23; saved in memory). +- Gap closure is 4 plans. 07 depends on 06 because of file overlap, so the waves run 1/2/3/4. The user approved this. +- Every critical and warning finding is fixed; info findings are fixed where cheap, otherwise deferred with a reason. +- E-2 uses a separate `pact.HasFrontendTokenScopes`, not cabana's HasTokenScopes (note .planning/notes/2026-10-23-frontend-token-scopes.md). `MintAPITokenFor(app, …)` is scoped to the app; the legacy MintAPIToken uses a process-wide fallback. +- E-1 adds the logo as a second attachment beside avatar, delivered as the helpers OrganisationLogoURL and OrganisationLogoFields. The plugin serves no organisation payload. +- A ban or password reset revokes MCP AND OIDC grants (user, 2026-10-23). A link change revokes backend-scoped MCP grants. +- `auth_time` is set at sign-in and copied unchanged by refresh. Sessions issued before the upgrade must sign in again before linking. + + + +- None technical. +- **Everything since the last pushes is local and unpushed** (see Infrastructure State). If the next session runs on a different machine, these commits must be pushed first, with the user's go-ahead (CLAUDE.md: no push without go-ahead). + + +## Required Reading (in order) + +1. `.planning/phases/19.7-generic-mcp-module/19.7-GAP-INPUTS.md`: gap scope, escalations, decisions, release order +2. `19.7-REVIEW.md`: the findings 06-09 fix +3. `19.7-06-SUMMARY.md`, `19.7-07-SUMMARY.md`, `19.7-08-SUMMARY.md`: what was done and the deviations +4. `19.7-09-PLAN.md`: the next plan +5. `deferred-items.md` +6. Memory: release-tag-only-at-phase-completion + +## Infrastructure State + +Last measured 2026-10-23T15:13Z. Nothing is pushed beyond the tags listed above. + +| Repo | Branch @ HEAD | Ahead of origin | Uncommitted | +|---|---|---|---| +| summercms.go | master | 42 | `.planning/state.json` (another session's), `.msd/`, two `.gitkeep` | +| sm-user-plugin (sm-demo-app/plugins/golem15/user) | master @ f20a8d3 | 5 | clean | +| sm-oauthserver-plugin | master @ 671513d | 2 | `go.work`: tracked file, its user replace was pointed at ../sm-demo-app/plugins/golem15/user for local dev. Restore it or decide its fate before release | +| sm-journal-plugin | main @ b129902 | 2 | `go.work.sum` (untracked, not ours) | +| sm-demo-app | master @ 7731641 | 12 | `main.go` (another session's); submodule checkouts user/oauthserver/journal moved to local commits, and their pointers are bumped only at release | +| vue-demo-app | master @ 0125e29 | 1 | clean. Must be pushed before sm-demo-app 00f57bf | +| fonoteka.go | master @ 06bc9d0 | 35 | clean | +| sm-bm-app, sm-grzybyfunkcjonalne-app, sm-summercmsio-app | master | 1 each (the plugin v0.1.10 bump) | unrelated untracked files | + +Tools: the msd CLI is `node ~/.claude/msd-core/bin/msd-tools.cjs` (no msd_run on PATH). Docker tests run directly (socket available); fall back to `sudo -u golem` if the socket is denied. + + +Execution model: the orchestrator dispatches one msd-executor per plan, sequentially on the main tree (workflow.use_worktrees=false). It passes the drift corrections in the prompt and updates ROADMAP/STATE through msd-tools after each plan ("docs(phase-19.7): update tracking after gap wave N"). Plan 09 is autonomous, with no checkpoints. The user wants evidence-backed gates and dislikes surprise version bumps. + + + +Start with: confirm the repos above are present at the listed HEADs on this machine (push or pull first if moving machines, with the user's go-ahead). Then run `/msd-execute-phase 19.7 --gaps-only`; it will pick up 19.7-09. +