docs(32.2-05): record the hold release decision and complete the tests plan

- 32.2-05-release-decision.txt: hold, framework-base v0.6.6, plugin-base v0.1.7
- 32.2-05-SUMMARY.md: tests, regression exit codes, deviations, release
  pending the user's go-ahead, live SameSite connector check unverified
This commit is contained in:
Jakub Zych
2026-11-21 02:30:45 +01:00
parent fc90a5470c
commit 7a39fda957
2 changed files with 305 additions and 0 deletions

View File

@@ -0,0 +1,302 @@
---
phase: 32.2-mcp-oauth-with-administrator-subjects
plan: 05
subsystem: testing
tags: [mcp, oauth, wristband, pier, cabana, admin-spa, sm-oauthserver-plugin, regression, release-gate]
requires:
- phase: 32.2-01
provides: wristband consent_path and DefaultScopes, pier backend-only grants, cabana MCP admin consent, account items, BackendAccessRevokedEvent
- phase: 32.2-02
provides: admin SPA /connect screen, login hint, My account item rows
- phase: 32.2-03
provides: sm-oauthserver-plugin mcp.subject backend (local commits 6996ffe, 9b97466, 4c209c1)
- phase: 32.2-04
provides: sm-grzybyfunkcjonalne-app mounts the plugin in backend mode, smoke-mcp-oauth.sh, check-deploy.sh guards
provides:
- TestBackendGrantToolsMatchPersonalToken - an OAuth administrator grant and a g15_ token with equal scopes list and call the same tools
- framework unit tests for SC-1 to SC-3 in wristband, pier and cabana
- admin SPA tests for the consent screen, the login hint and the My account item rows (four of the five UI backstops)
- plugin unit tests for backend-subject mode, consent, migration, grant rows, revocation and the D-13 cascade
- recorded regression runs across framework, admin, plugin, grzyby and sm-bm-app (all exit 0)
- admin:reset-password now runs in a lagoon transaction, so BackendAccessRevokedEvent listeners' after-commit work fires
- 32.2-05-release-decision.txt recording hold (framework-base v0.6.6, plugin-base v0.1.7)
affects: [32.2 VERIFICATION, the release of the next v0.6 patch and sm-oauthserver-plugin v0.1.8, grzyby pointer bump]
actuals:
tokens: 46063
tasks: 5
commits: 4
plan_head_before: d450a6819e9b6d6da8879e9bb6933a365394d156
plan_head_after: fc90a5470ce87acbbe199c4d0d0e64059315acee
tech-stack:
added: []
patterns:
- "Throttle-aware Docker tests: a cascade test rotates fresh OAuth clients instead of relaxing the plugin's register/token throttles"
- "Test-only hooks through export_test.go (cabana.FireBackendAccessRevokedForTest), never exported from the package"
key-files:
created:
- modules/wristband/consent_path_test.go
- modules/pier/backend_only_grant_test.go
- modules/cabana/token_scope_names_test.go
- modules/cabana/mcp_admin_consent_test.go
- modules/cabana/account_items_test.go
- modules/cabana/backend_access_revoked_test.go
- admin/tests/views/ConnectView.test.ts
- ../sm-oauthserver-plugin/backend_tools_test.go
- ../sm-oauthserver-plugin/backend_mode_test.go
- ../sm-oauthserver-plugin/backend_consent_test.go
- ../sm-oauthserver-plugin/backend_subject_migration_test.go
- ../sm-oauthserver-plugin/backend_grant_rows_test.go
- ../sm-oauthserver-plugin/backend_revoke_test.go
- ../sm-oauthserver-plugin/jwt_only_test.go
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/32.2-05-release-decision.txt
modified:
- modules/cabana/commands.go
- modules/cabana/export_test.go
- admin/tests/app/router.test.ts
- admin/tests/views/LoginView.test.ts
- admin/tests/account/AccountContributions.test.ts
- ../sm-oauthserver-plugin/testdata/php_methods.txt
- ../sm-oauthserver-plugin/testdata/PHP_METHOD_MAP.md
- .planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md
key-decisions:
- "Release checkpoint answered hold: no tag, no push, no changelog post; the release (next v0.6 patch above v0.6.6, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts) is pending the user's go-ahead after /msd-verify-work"
- "admin:reset-password runs in lagoon.Transaction instead of a plain GORM transaction, so lagoon.AfterCommit callbacks registered by BackendAccessRevokedEvent listeners run (Rule 1)"
- "TestPHPMethodMap: the five AuthorizeResolveUserJwtOnlyTest methods are mapped, three ported as adapted subtests and two marked not applicable (the Go plugin resolves users from the session JWT only)"
- "offline_access-only authorize requests storing no data scope is pre-existing (user mode behaves the same) and was logged to deferred-items.md, not changed"
patterns-established:
- "Plugin v0.1.8 must require a framework tag that contains b1b96d85"
requirements-completed: [SC-1, SC-2, SC-3, SC-4]
coverage:
- id: D1
description: "An administrator who consents over OAuth with acme:read lists and calls only the read-only tool, with acme lists and calls the write tool, and both tool lists equal a g15_ token's tools/list with the same scopes; revoking one connection from My account answers 401 for it and leaves the other working"
requirement: SC-2
verification:
- kind: integration
ref: "go -C ../sm-oauthserver-plugin test -count=1 -tags summercms_mcp -run TestBackendGrantToolsMatchPersonalToken . (backend_tools_test.go, Docker)"
status: pass
human_judgment: false
- id: D2
description: "Framework unit tests: consent handoff path and default scopes (wristband), backend-only grants and the user-mode linked-grant regression (pier), token scope names, MCP admin consent API, account contribution items and BackendAccessRevokedEvent at all seven D-13 sites (cabana)"
requirement: SC-1
verification:
- kind: unit
ref: "go test -count=1 -run 'TestAuthorizeConsentPath|TestAuthorizeDefaultScopes|TestBackendOnlyGrant|TestLinkedGrantNoScopeLimit|TestTokenScopeNames|TestMCPAdminConsent$|TestAccountContributionItems|TestBackendAccessRevokedEvent' ./modules/wristband ./modules/pier ./modules/cabana"
status: pass
human_judgment: false
- id: D3
description: "Admin SPA tests and four UI backstops: the * consent rule, no auto-allow with Allow/Deny through window.location.assign, the switch-account round trip, and account item rows back-compat"
requirement: SC-1
verification:
- kind: automated_ui
ref: "npm --prefix admin run test -- tests/views/ConnectView.test.ts tests/app/router.test.ts tests/views/LoginView.test.ts tests/account/AccountContributions.test.ts"
status: pass
human_judgment: false
- id: D4
description: "Plugin backend-mode unit tests: TestBackendMode, TestBackendConsent, TestBackendSubjectMigration, TestBackendGrantRows, TestBackendRevokeFromAccount, TestBackendCascade"
requirement: SC-3
verification:
- kind: integration
ref: "go -C ../sm-oauthserver-plugin test -count=1 -run 'TestBackendMode$|TestBackendConsent|TestBackendSubjectMigration|TestBackendGrantRows|TestBackendRevokeFromAccount|TestBackendCascade' . (Docker)"
status: pass
human_judgment: false
- id: D5
description: "User mode unchanged: full regression runs in framework, admin, plugin (both tag sets), grzyby (smoke, check-deploy, tagged tests) and sm-bm-app through a scratch go.work"
requirement: SC-4
verification:
- kind: integration
ref: "task 3 regression commands (see Verification below), every exit code 0"
status: pass
human_judgment: false
- id: D6
description: "Live connector check: on a real cross-site redirect from Claude the SameSite=Strict admin cookie still reaches the admin /connect screen, so the consent card shows the signed-in administrator rather than the login screen (D-03, RESEARCH A2, fifth UI backstop)"
requirement: SC-1
verification: []
human_judgment: true
rationale: "A localhost stack is same-site and cannot reproduce the cross-site redirect chain. It is routed to sm-grzybyfunkcjonalne-app DEPLOY.md 'Live connector check (deferred)', which runs after the deferred production deploy on the user's go-ahead. Status UNVERIFIED, not passed and not failed; no test in this plan claims to cover it."
- id: D7
description: "SC-5 release: next v0.6 patch tag, sm-oauthserver-plugin v0.1.8, grzyby pointer bump, two changelog posts"
requirement: SC-5
verification:
- kind: other
ref: "task 5 automated verify on the hold branch (no v0.6.7 in summercms.go, no v0.1.8 in sm-oauthserver-plugin): exit 0"
status: pass
human_judgment: true
rationale: "The checkpoint answer was hold. The release is pending the user's go-ahead after verification; SC-5 is not met yet."
duration: 48min
completed: 2026-11-21
status: complete
---
# Phase 32.2 Plan 05: tests, regression runs and release gate Summary
**An OAuth administrator grant and a `g15_` token with equal scopes now provably see and call the same MCP tools. Unit tests cover SC-1 to SC-3 in wristband, pier, cabana, the admin SPA and sm-oauthserver-plugin. Regression runs in five repos show user mode is unchanged. One real bug came out of the tests: `admin:reset-password` never ran its listeners' after-commit work, and it is now fixed. The release checkpoint answered hold, so nothing was tagged, pushed or posted.**
## Performance
- **Duration:** about 48 min
- **Started:** 2026-11-21T00:41:38Z
- **Completed:** 2026-11-21T01:29Z
- **Tasks:** 5 of 5 (task 4 was the checkpoint, task 5 ran its hold branch)
- **Files modified:** 13 in summercms.go (tests, commands.go, deferred items, decision record), 8 in ../sm-oauthserver-plugin
## Accomplishments
- **Tracer (task 1), sm-oauthserver-plugin `bae8222`.** `TestBackendGrantToolsMatchPersonalToken` (`summercms_mcp`, Docker) runs the real flow: authorize, admin consent, token exchange and `/mcp` calls.
- `acme:read` lists and calls only the read-only backend tool.
- `acme` lists and calls the write tool.
- In both cases the tool list matches a `g15_` token with the same scopes, name for name.
- Revoking one connection from My account makes that bearer get 401, and the other client keeps working.
- **Framework unit tests (task 2), `7ecfa608`.**
- wristband: `TestAuthorizeConsentPath`, `TestAuthorizeDefaultScopes`.
- pier (Docker): `TestBackendOnlyGrant`, `TestLinkedGrantNoScopeLimit`.
- cabana: `TestTokenScopeNames`, `TestMCPAdminConsent`, `TestAccountContributionItems`, `TestBackendAccessRevokedEvent` (Docker, all seven D-13 sites).
- **Admin SPA tests (task 2), `1e00ed3d`.**
- New `ConnectView.test.ts` covers every C1 state, the `*` rule, no auto-allow, the Allow and Deny bodies through `window.location.assign`, forbidden schemes, switch account, 401/404 handling, focus and the profile fallback.
- router, LoginView and AccountContributions tests are extended: anonymous `/connect` goes to login and back, the login hint, `items` null versus `[]`, the `:title` confirm, 404 `item_gone` and 409 `action_stale`.
- **Plugin backend-mode tests (task 3), sm-oauthserver-plugin `793eadd`.** `TestBackendMode`, `TestBackendConsent`, `TestBackendSubjectMigration`, `TestBackendGrantRows`, `TestBackendRevokeFromAccount`, `TestBackendCascade`.
- **Regression runs (task 3).** Every command in task 3's verify exits 0 (see Verification).
- **Release gate (tasks 4 and 5).** The user answered **hold**.
- `32.2-05-release-decision.txt` records `hold`, `framework-base v0.6.6` and `plugin-base v0.1.7`.
- Task 5's automated verify passes on the hold branch (exit 0).
- No tag was created and nothing was pushed in any repo. No changelog script ran and nothing was deployed.
## Task Commits
| Task | Name | Repo | Commit |
|---|---|---|---|
| 1 | Tracer: OAuth administrator grant tools equal a `g15_` token's tools | sm-oauthserver-plugin | `bae8222` (test) |
| 2 | Framework unit tests (wristband, pier, cabana) | summercms.go | `7ecfa608` (test) |
| 2 | Admin SPA tests | summercms.go | `1e00ed3d` (test) |
| 3 | Plugin backend-mode unit tests | sm-oauthserver-plugin | `793eadd` (test) |
| 3 | Rule 1 fix: admin:reset-password in a lagoon transaction | summercms.go | `b1b96d85` (fix) |
| 3 | TestPHPMethodMap: map AuthorizeResolveUserJwtOnlyTest | sm-oauthserver-plugin | `1124fd1` (test) |
| 3 | Deferred items after the plugin tests | summercms.go | `fc90a547` (docs) |
| 4 | Checkpoint: whether to tag, push and post the changelog | - | answered hold |
| 5 | Release only if the checkpoint accepted it | summercms.go | decision record, in the plan metadata commit |
`commits: 4` in the frontmatter is measured with the framework ledger (`d450a681..fc90a547`). The three plugin commits are local to `../sm-oauthserver-plugin`, which is now 6 commits ahead of `origin/master` (plans 03 and 05). Nothing was pushed.
Tracer gate: auto mode is off, human_verify_mode is end-of-phase and task 1's `<verify>` is automated-only. The verify ran again and passed, so the plan continued to task 2.
## Files Created/Modified
- `modules/wristband/consent_path_test.go`: consent handoff path and default scopes
- `modules/pier/backend_only_grant_test.go`: backend-only grants and the linked-grant regression
- `modules/cabana/{token_scope_names,mcp_admin_consent,account_items,backend_access_revoked}_test.go`: the SC-1 and SC-3 cabana tests
- `modules/cabana/export_test.go`: `FireBackendAccessRevokedForTest`, used by the de-duplication case
- `modules/cabana/commands.go`: `admin:reset-password` in `lagoon.Transaction`
- `admin/tests/views/ConnectView.test.ts` (new), `admin/tests/app/router.test.ts`, `admin/tests/views/LoginView.test.ts`, `admin/tests/account/AccountContributions.test.ts`
- `../sm-oauthserver-plugin/backend_{tools,mode,consent,subject_migration,grant_rows,revoke}_test.go`, `jwt_only_test.go`, `testdata/php_methods.txt`, `testdata/PHP_METHOD_MAP.md`
- `.planning/phases/32.2-mcp-oauth-with-administrator-subjects/deferred-items.md`, `32.2-05-release-decision.txt`
## Decisions Made
See key-decisions in the frontmatter.
**Release decision: hold. The release is pending the user's go-ahead after verification.** When the user says go, task 5's tag-and-publish branch runs in this order:
1. Tag the framework's next free v0.6 patch (v0.6.7 if still free) on master. It must contain every earlier tag and `b1b96d85`.
2. Point sm-oauthserver-plugin's go.mod at that framework tag, regenerate plugin.yaml, then tag v0.1.8 and push it.
3. Commit the grzyby pointer and go.mod bump to v0.1.8 as a separate commit, after the plugin push.
4. Publish the two changelog posts the same day.
The decision record is not rewritten if the bases move. Recompute the bases at release time.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] admin:reset-password skipped its listeners' after-commit work**
- **Found during:** Task 3 (regression runs, D-13 site coverage)
- **Issue:** The reset fired `BackendAccessRevokedEvent` inside a plain GORM transaction, and `lagoon.AfterCommit` refuses to run there. As a result the plugin's revoked `MCPSubjectChanged` events, which end MCP sessions, never ran for this D-13 site.
- **Fix:** The command now runs in `lagoon.Transaction`. `TestBackendAccessRevokedEvent` asserts that the after-commit callback runs once for a committed reset and does not run for a vetoed one.
- **Files modified:** `modules/cabana/commands.go`, `modules/cabana/backend_access_revoked_test.go`
- **Committed in:** `b1b96d85`
**2. [Rule 3 - Blocking] TestPHPMethodMap failure (pre-existing, logged by plan 03)**
- **Found during:** Task 3 (full plugin suite)
- **Issue:** The PHP reference tree gained `AuthorizeResolveUserJwtOnlyTest`, and its five methods were unmapped, so the plugin's full `go test ./...` could not pass.
- **Fix:** Three methods are ported as adapted subtests of `TestAuthorizeResolveUserJwtOnly`. Two are marked not applicable, because the Go plugin resolves users from the session JWT only.
- **Committed in:** sm-oauthserver-plugin `1124fd1`; deferred-items.md updated in `fc90a547`
**3. [Rule 3 - Blocking] TestBackendCascade hit the plugin's register and token throttles**
- **Found during:** Task 3
- **Fix:** The test rotates six fresh OAuth clients instead of reusing one. The throttles are not relaxed.
- **Committed in:** sm-oauthserver-plugin `793eadd`
**4. [Rule 3 - Blocking] De-duplication case needed an internal hook**
- **Fix:** `cabana.FireBackendAccessRevokedForTest` lives in `export_test.go`, so the package's exported API is unchanged.
- **Committed in:** `7ecfa608`
---
**Total deviations:** 4 (1 Rule 1, 3 Rule 3). **Impact:** the Rule 1 fix closes a real gap in session termination after a password reset. The other three are test plumbing only, with no scope creep.
## Issues Encountered
- The first `npm --prefix admin run test:browser` run hit a Vite dynamic-import flake under load in the code editor test files. The rerun passed (4 files, 13 tests) with no code change.
- A pre-existing behaviour was logged to deferred-items.md and not changed: an authorize request whose only scope is `offline_access` stores no data scope. User mode behaves the same way.
## Verification
Regression exit codes (task 3; logs in the session scratchpad, `r1-*.log` to `r5-bm.log`):
| Run | Exit |
|---|---|
| framework `go vet ./...` | 0 |
| framework `go test -count=1 ./...` (47 packages, Docker) | 0 |
| framework `go test -count=1 -tags summercms_mcp ./modules/pier ./modules/surf` | 0 |
| plugin `go vet` (both tag sets) | 0 |
| plugin `go test -count=1 ./...` | 0 |
| plugin `go test -count=1 -tags summercms_mcp ./...` | 0 |
| admin `typecheck` | 0 |
| admin `test` (117 files, 1729 tests) | 0 |
| admin `test:browser` (rerun, 4 files, 13 tests) | 0 |
| `scripts/check-admin-openapi.sh --check` | 0 |
| `scripts/check-admin-dist.sh` | 0 |
| `go test ./cmd/summer -run TestDocsTree` | 0 |
| `go run ./cmd/summer docs:build --check` | 0 |
| grzyby `scripts/smoke-mcp-oauth.sh` (`ok (12 steps)`) | 0 |
| grzyby `scripts/check-deploy.sh` | 0 |
| grzyby `go test -count=1 -tags summercms_mcp,nodynamic ./...` | 0 |
| sm-bm-app via scratch go.work: `vet -tags summercms_mcp` / `test -tags summercms_mcp` | 0 / 0 |
| task 5 verify (hold branch) | 0 |
The grzyby runs used the plugin working tree at local `4c209c1` and later. The grzyby gitlink is still uncommitted (` M plugins/golem15/oauthserver`) until the release.
**Human verification, open (UNVERIFIED, not a failure):** the D-03 `SameSite=Strict` admin cookie on a real cross-site connector redirect chain (RESEARCH A2, the fifth UI backstop, the VALIDATION.md manual-only row). It is routed to `../sm-grzybyfunkcjonalne-app/DEPLOY.md`, "Live connector check (deferred)", and runs after the deferred production deploy on the user's go-ahead. The phase VERIFICATION.md must list it under human verification with status unverified. No test in this plan claims to cover it.
## Known Stubs
None.
## Threat Flags
None beyond the plan's threat model:
- T-32.2-26: the tests assert status codes and ids, and the smoke output carries no tokens or codes. No changelog script ran, so the journal token was never read.
- T-32.2-27: the blocking checkpoint held. No tag and no push.
## User Setup Required
None.
## Next Phase Readiness
- Phase 32.2 is ready for `/msd-verify-work`.
- The release waits for the user's go-ahead, following the task 5 order above.
- Still not done: the plugin's 6 local commits are unpushed, the grzyby gitlink is uncommitted, and the DEPLOY.md minimum-version wording can name v0.1.8 once it exists.
- STATE.md and ROADMAP.md were not touched by this plan, as the orchestrator instructed.
## Self-Check: PASSED
- Files exist: the wristband, pier and cabana test files, `admin/tests/views/ConnectView.test.ts`, `../sm-oauthserver-plugin/backend_tools_test.go`, `../sm-oauthserver-plugin/backend_revoke_test.go` and `32.2-05-release-decision.txt`.
- Framework commits `7ecfa608`, `1e00ed3d`, `b1b96d85` and `fc90a547` exist, as do plugin commits `bae8222`, `793eadd` and `1124fd1`.
- There is no `v0.6.7` tag in summercms.go and no `v0.1.8` tag in sm-oauthserver-plugin.

View File

@@ -0,0 +1,3 @@
hold
framework-base v0.6.6
plugin-base v0.1.7