docs(09-01): complete separate-admin genre list tracer plan

.planning/ROADMAP.md

@@ -375,13 +375,13 @@ Plans:
   4. The relation-manager schema supports search/link/unlink/manage-or-view lists for Collections' editors tab, replacing the `partial` field entirely.
   5. Admin CRUD endpoints expose `listExtendQuery`/`formExtendQuery`/`formBeforeCreate`/`formBeforeUpdate`/`relationExtendManageQuery` hooks, bulk delete runs each record's lifecycle hooks, and the Settings model binds to a settings screen through the same schema pipeline.
 
-**Plans**: 12 plans
+**Plans**: 1/12 plans executed
 **Research flag:** yes
 
 Plans:
 
 **Wave 1**
-- [ ] 09-01-PLAN.md — Prove the architecture with one production end-to-end Genre list
+- [x] 09-01-PLAN.md — Prove the architecture with one production end-to-end Genre list
 
 **Wave 2** *(blocked on Wave 1 completion)*
 - [ ] 09-02-PLAN.md — Complete backend identity lifecycle and operator provisioning
@@ -529,7 +529,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 6. HTTP routing, auth groups and rate limiting | 14/14 | Complete   | 2026-09-21 |
 | 7. User plugin and authentication | 8/8 | Complete    | 2026-09-23 |
 | 8. OAuth2.1 authorization server | 10/10 | Complete   | 2026-09-23 |
-| 9. Backend admin authentication and schema pipeline | 0/TBD | Not started | - |
+| 9. Backend admin authentication and schema pipeline | 1/12 | In Progress|  |
 | 10. Admin Vue SPA | 0/TBD | Not started | - |
 | 11. Jobs, realtime and search infrastructure | 0/TBD | Not started | - |
 | 12. Płytarium API — Collections and Albums | 0/TBD | Not started | - |

.planning/STATE.md

@@ -2,18 +2,18 @@
 gsd_state_version: "1.0"
 milestone: v1.0
 current_phase: 09
-current_phase_name: backend-admin-authentication-and-schema-pipeline
+current_phase_name: Backend admin authentication and schema pipeline
 status: executing
-stopped_at: Phase 08 complete (10/10) — ready to discuss Phase 09
+stopped_at: Completed 09-01-PLAN.md
-last_updated: "2026-09-24T14:43:54.863Z"
+last_updated: "2026-09-24T15:22:53.884Z"
 last_activity: 2026-09-24
-last_activity_desc: Phase 09 planning complete
+last_activity_desc: Phase 09 execution started
-state_head: 1fbf492450fe6d8b0cf4fa0cd6f742d40e117ce5
+state_head: 18b2e851063f3a50b7a13c87413ac4ae3ece9998
 progress:
   total_phases: 15
   completed_phases: 8
   total_plans: 67
-  completed_plans: 55
+  completed_plans: 56
 milestone_name: milestone
 ---
 
@@ -24,14 +24,14 @@ milestone_name: milestone
 See: .planning/PROJECT.md (updated 2026-09-16)
 
 **Core value:** An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test.
-**Current focus:** Phase 09 — backend admin authentication and schema pipeline
+**Current focus:** Phase 09 — Backend admin authentication and schema pipeline
 
 ## Current Position
 
-Phase: 09 (backend-admin-authentication-and-schema-pipeline) — READY TO EXECUTE
+Phase: 09 (Backend admin authentication and schema pipeline) — EXECUTING
-Plan: Not started
+Plan: 2 of 12
 Status: Ready to execute
-Last activity: 2026-09-24 — Phase 09 planning complete
+Last activity: 2026-09-24 — Phase 09 execution started
 
 Progress: [██████████] 100%
 
@@ -105,6 +105,11 @@ Progress: [██████████] 100%
 | Phase 08 P08 | 20min | 2 tasks | 4 files |
 | Phase 08 P09 | 55min | 3 tasks | 25 files |
 | Phase 08 P10 | 55min | 3 tasks | 17 files |
+**Per-Plan Metrics:**
+
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
+| Phase 09 P01 | 26min | 2 tasks | 26 files |
 
 ## Accumulated Context
 
@@ -264,6 +269,9 @@ Recent decisions affecting current work:
 - [Phase 08]: Security review self-performed by the 08-10 executor (no Task/Agent spawner available), disclosed in 08-SECURITY-REVIEW.md's frontmatter and Reviewer Note — Per 08-CONTEXT.md D-04's documented fallback; every cited file:TestName was individually re-run, not inherited unverified
 - [Phase 08]: Checkpoint decision: approved closing Phase 8 with the Playwright UI matrix gap (check-phase8-ui.mjs:458) carried forward as a named follow-up — Every other scripts/check-phase8.sh stage ran green in the sole full gate execution; the Playwright matrix was a deliberate, never-authored fatal() left by 08-05 as 08-10's seam
 - [Phase 08]: AUTH-05, AUTH-06 and AUTH-07 marked complete in REQUIREMENTS.md — Each requirement's exact text is satisfied by the delivered backend/gate evidence; none mandates a Playwright-verified browser regression suite, so the carried-forward UI gap does not block completion
+- [Phase 09]: Frontend verification accepts PHP tokens that omit aud and rejects any other explicit audience
+- [Phase 09]: Backend JWTs require aud=backend, use admin.jwt.secret, and omit the PHP user prv hash
+- [Phase 09]: Cabana mounts from BuildRouter only when a plugin registers admin controllers; an empty admin.jwt.secret fails that assembly
 
 ### Pending Todos
 
@@ -286,6 +294,6 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-09-23T23:03:36.023Z
+Last session: 2026-09-24T15:22:53.442Z
-Stopped at: Completed 08-10-PLAN.md (Phase 8 closed; Playwright UI matrix gap carried forward)
+Stopped at: Completed 09-01-PLAN.md
 Resume file: None

.planning/WINDOWS.md

@@ -0,0 +1,36 @@
+---
+schema_version: 1
+open_count: 0
+waived_count: 0
+fixed_count: 1
+total_count: 1
+last_updated: 2026-09-24T15:23:23.945Z
+---
+
+# Broken Windows Ledger
+
+> Cross-phase defect register. With `workflow.windows_enforce` enabled, `/gsd-ship` blocks while `open_count > 0`.
+> Waive with `gsd-tools windows waive <id> "<reason>"` (reason required).
+> Mark fixed with `gsd-tools windows fixed <id>`.
+
+| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |
+|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|
+| 1 | 09 | deviation | plugins/golem15/fonoteka/routes_cors_test.go |  | Admin test secret also set on bootConfigWithHTTP and testConfigCORS so router assembly keeps failing closed | fixed |  | 2026-09-24T15:22:55.173Z | 2026-09-24T15:23:23.945Z |
+
+````json
+[
+  {
+    "id": 1,
+    "kind": "deviation",
+    "phase": "09",
+    "file": "plugins/golem15/fonoteka/routes_cors_test.go",
+    "line": null,
+    "description": "Admin test secret also set on bootConfigWithHTTP and testConfigCORS so router assembly keeps failing closed",
+    "status": "fixed",
+    "reason": "",
+    "recorded_at": "2026-09-24T15:22:55.173Z",
+    "resolved_at": "2026-09-24T15:23:23.945Z",
+    "milestone": "v1.0"
+  }
+]
+````

.planning/phases/09-backend-admin-authentication-and-schema-pipeline/09-01-SUMMARY.md

@@ -0,0 +1,223 @@
+---
+phase: 09-backend-admin-authentication-and-schema-pipeline
+plan: 01
+subsystem: auth
+tags: [jwt, postgres, gorm, admin, cabana, bouncer]
+
+requires:
+  - phase: 06-http-routing-auth-groups-and-rate-limiting
+    provides: named bouncer guards and raw route groups
+  - phase: 07-user-plugin-and-authentication
+    provides: HS256 mint/verify, bcrypt, and the jti blacklist
+provides:
+  - Audience-separated frontend and backend JWTs
+  - Framework backend_users and backend_user_roles tables
+  - Cabana raw admin login, list schema, and record-list routes
+  - One compiled Genre list served from embedded Winter YAML
+affects: [09-backend-admin-authentication-and-schema-pipeline, admin-api, phase-10-spa]
+
+actuals:
+  tokens: 17027
+  tasks: 2
+  commits: 3
+
+tech-stack:
+  added: []
+  patterns:
+    - "Admin routes mount from surf.BuildRouter only when a plugin registers admin controllers"
+    - "D-10 envelopes stay inside cabana; frontend 401 bodies stay PHP-shaped"
+    - "Plugin AdminFS plus AdminRecordSource keep table names and permission codes out of cabana"
+
+key-files:
+  created:
+    - cabana/http.go
+    - cabana/auth.go
+    - cabana/schema.go
+    - cabana/registry.go
+    - cabana/contracts.go
+    - lagoon/backend_admin_migrations.go
+    - bouncer/audience_test.go
+    - cabana/security_test.go
+  modified:
+    - bouncer/jwt.go
+    - bouncer/mint.go
+    - bouncer/refresh.go
+    - bouncer/context.go
+    - pact/capabilities.go
+    - surf/router.go
+    - lagoon/migrations.go
+
+key-decisions:
+  - "Frontend verification still accepts PHP tokens that omit aud, and rejects any explicit audience other than user"
+  - "Backend tokens require aud=backend, use admin.jwt.secret, and omit the PHP user prv lock-subject"
+  - "Empty admin.jwt.secret fails router assembly only when admin controllers are registered; there is no fallback secret"
+  - "golang-jwt emits a one-element aud array; both guards accept that form"
+
+patterns-established:
+  - "Pattern: guard, then controller lookup, then RequiredPermissions, then schema or SQL"
+  - "Pattern: Winter list YAML is compiled once at activation with DisallowUnknownField"
+
+requirements-completed: [AUTH-08, ADMIN-02]
+
+coverage:
+  - id: D1
+    description: A developer-role backend admin logs in and reads one persisted Genre through the compiled admin list.
+    requirement: ADMIN-02
+    verification:
+      - kind: integration
+        ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerGenreList/genre_list
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: An empty admin.jwt.secret fails router assembly with a named configuration error.
+    requirement: AUTH-08
+    verification:
+      - kind: integration
+        ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerGenreList/empty_secret
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: Frontend and backend guards reject each other's audience even when the HMAC secret matches.
+    requirement: AUTH-08
+    verification:
+      - kind: unit
+        ref: bouncer/audience_test.go#TestAudienceCrossover
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: Missing and invalid admin credentials return unauthenticated 401 before a missing controller can be distinguished, and bodies do not echo secrets or tokens.
+    requirement: AUTH-08
+    verification:
+      - kind: integration
+        ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerAuthBoundary
+        status: pass
+      - kind: unit
+        ref: cabana/security_test.go#TestSecretRedaction
+        status: pass
+    human_judgment: false
+  - id: D5
+    description: A non-superuser without the Genre permission receives forbidden 403 before schema or SQL, and a superuser can list.
+    requirement: ADMIN-02
+    verification:
+      - kind: unit
+        ref: cabana/security_test.go#TestAuthorizationOrder
+        status: pass
+      - kind: integration
+        ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerPermissionBoundary
+        status: pass
+    human_judgment: false
+
+duration: 26min
+completed: 2026-09-24
+status: complete
+plan_head_before: 01d3871510f503f07e89282aa5501022cc4839af
+plan_head_after: 18b2e851063f3a50b7a13c87413ac4ae3ece9998
+---
+
+# Phase 9 Plan 01: Separate-admin Genre list tracer Summary
+
+**A backend administrator logs in with a distinct JWT audience and reads one real Genre row through a boot-compiled Winter list schema on PostgreSQL.**
+
+## Performance
+
+- **Duration:** 26 min
+- **Started:** 2026-09-24T14:55:33Z
+- **Completed:** 2026-09-24T15:21:30Z
+- **Tasks:** 2
+- **Files modified:** 26
+
+## Accomplishments
+
+- Backend identity lives in Winter-shaped `backend_users` and `backend_user_roles` tables, seeded with the developer and publisher system roles, and is never read from frontend `users`.
+- `surf.BuildRouter` activates cabana only when a plugin registers admin controllers, and refuses an empty `admin.jwt.secret` instead of borrowing the user secret.
+- `POST /_admin/api/v1/auth/login` accepts a login or a normalized email, and `GET /_admin/api/v1/golem15/fonoteka/genres` returns the persisted row plus list meta from the embedded `columns.yaml`.
+- The same HMAC secret cannot move a token across the frontend and backend guards. Permission denial happens before the list callback.
+
+## Task Commits
+
+Each task was committed atomically. SummerCMS `commits: 3` is `git rev-list --count` from the plan ledger. Fonoteka commits are in the sibling repository.
+
+1. **Task 1: Genre list tracer (RED)** - `9defed3` (test, fonoteka.go) login was 404 and an empty admin secret still assembled
+2. **Task 1: Genre list tracer (GREEN)** - `dfa00f7` (feat, summercms.go) and `a87eacc` (feat, fonoteka.go)
+3. **Task 2: Token and permission boundaries (RED)** - `8c1de83` (test, summercms.go) and `195c95c` (test, fonoteka.go)
+4. **Task 2: Token and permission boundaries (GREEN)** - `18b2e85` (feat, summercms.go) frontend guard rejects a backend audience
+
+**Plan metadata:** pending docs commit
+
+## Files Created/Modified
+
+- `cabana/http.go` - raw admin login, list-schema, and record-list routes
+- `cabana/auth.go` - backend user model, login lookup, and principal grants
+- `cabana/schema.go` - strict compile of `config_list.yaml` and `columns.yaml`
+- `cabana/registry.go` - immutable controller registry
+- `cabana/contracts.go` - D-10 envelopes and permission matching
+- `lagoon/backend_admin_migrations.go` - backend identity tables and system roles
+- `bouncer/jwt.go` - audience-aware verify and backend guard
+- `bouncer/mint.go` / `bouncer/refresh.go` - audience-preserving mint and refresh
+- `pact/capabilities.go` - admin asset, permission, navigation, settings, and hook contracts
+- `surf/router.go` - activates cabana before route wrapping
+- `fonoteka.go` `admin.go`, Genre controller, and embedded list YAML
+- `fonoteka.go/config/admin.yaml` - empty `admin.jwt.secret` with no production default
+
+## Decisions Made
+
+- Legacy frontend tokens with no `aud` claim stay valid. A present audience must be `user` on the frontend guard and `backend` on the backend guard.
+- Backend tokens do not carry the PHP user `prv` hash.
+- Admin route assembly is skipped when no plugin implements `HasAdminControllers`, so existing surf tests do not need an admin secret.
+- golang-jwt v5 writes `aud` as a JSON array even for one value. The tracer accepts that encoding.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Admin test secret added to every shared router config helper**
+- **Found during:** Task 1 (Genre list tracer)
+- **Issue:** Once the Genre controller is registered, every full-app `BuildRouter` needs `admin.jwt.secret`. The plan named `plugin_boot_test.go` and `parity/migrate_test.go`, but `routes_cors_test.go` and `parity/genre_security_test.go` assemble the same router through their own helpers.
+- **Fix:** Set `SUMMER_ADMIN__JWT__SECRET` to the test-only admin secret in those helpers too. It is not the user secret and it is not a production default.
+- **Files modified:** `plugins/golem15/fonoteka/routes_cors_test.go`, `parity/genre_security_test.go`, plus the two helpers the plan named
+- **Verification:** `go test ./plugins/golem15/fonoteka -count=1` passed
+- **Committed in:** `a87eacc` (fonoteka.go)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** The extra helpers are the same test-secret change the plan required. No production secret was added and no module dependency changed.
+
+## TDD Gate Compliance
+
+| Gate | Commit | Result |
+|------|--------|--------|
+| RED task 1 | `9defed3` test(09-01) | `TestAdminTracerGenreList` failed on login 404 and a nil empty-secret error |
+| GREEN task 1 | `dfa00f7` / `a87eacc` feat(09-01) | tracer passed on real PostgreSQL |
+| RED task 2 | `8c1de83` test(09-01) | `TestAudienceCrossover` failed because the frontend guard accepted a backend token |
+| GREEN task 2 | `18b2e85` feat(09-01) | audience, authorization-order, and boundary tests passed |
+
+`gsd_run check tdd-red-evidence` returned `RED_EVIDENCE_OK` for both RED runs. Go's test output is not TAP, so each evidence record appends a TAP trailer that names the test the go harness actually failed.
+
+## Authentication Gates
+
+None.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+Production boots that register admin controllers must set `SUMMER_ADMIN__JWT__SECRET`. `config/admin.yaml` ships the key empty on purpose.
+
+## Next Phase Readiness
+
+Ready for 09-02. The cabana registry, backend principal, audience-aware bouncer helpers, and D-10 envelope are the skeleton later plans extend. `AUTH-08` and `ADMIN-02` stay shared with later plans in this phase, so they are not marked complete yet.
+
+## Self-Check: PASSED
+
+- FOUND: cabana/http.go, cabana/auth.go, cabana/schema.go, cabana/registry.go, cabana/contracts.go, lagoon/backend_admin_migrations.go
+- FOUND: fonoteka admin.go, genres admin controller, config_list.yaml, columns.yaml, admin_tracer_test.go, config/admin.yaml
+- FOUND commits: 9defed3, dfa00f7, a87eacc, 8c1de83, 195c95c, 18b2e85
+
+---
+*Phase: 09-backend-admin-authentication-and-schema-pipeline*
+*Completed: 2026-09-24*