docs(19.1-06): complete PHP maps, goldens and phase gate plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-18 16:01:40 +02:00
parent b1a2c783e7
commit 7e51959b14
1 changed files with 273 additions and 0 deletions
--- a/.planning/phases/19.1-chat-satellites/19.1-06-SUMMARY.md
+++ b/.planning/phases/19.1-chat-satellites/19.1-06-SUMMARY.md
@@ -0,0 +1,273 @@
+---
+phase: 19.1-chat-satellites
+plan: 06
+subsystem: testing
+tags: [php-method-map, goldens, check-phase19.1, lighthouse, livekit, breakwater, testcontainers]
+
+# Dependency graph
+requires:
+  - phase: 19.1
+    provides: plans 01-05 sibling plugins (userfriends, forum, chatbots, herald, chatvideo) with TestHTTPTracer and TestBaseline
+  - phase: 19
+    provides: analog sm-chat-plugin php_method_map_test.go, golden_test.go, scripts/check-phase19.sh
+provides:
+  - "scripts/check-phase19.1.sh fail-closed gate (self-test, plugins, docs, postgres) with sibling env USERFRIENDS/FORUM/CHATBOTS/HERALD/CHATVIDEO"
+  - "testdata/PHP_METHOD_MAP.md + TestPHPMethodMap in each sibling (chatbots 22, forum 25, herald 13 unique of 14 declarations, userfriends 31, chatvideo 0 in-plugin + Wavepath generic-or-N/A)"
+  - "golden_test.go + testdata/goldens/ for serializers, lighthouse MemoryDriver publications, LiveKit JWT claims, forum semantic HTML (D-18)"
+affects: [verify-work, security-review]
+
+actuals:
+  tokens: 30153
+  tasks: 3
+  commits: 12
+plan_head_before: 374088eccfe1359a84ea3fbbcf37de159d0fc1c8
+plan_head_after: b1a2c783e786a976fcdf025ce0f35d08b85be3de
+
+tech-stack:
+  added: []
+  patterns:
+    - "Fail-closed go test -json detectors: skip, miss, red, zero, no-tests-to-run; --self-test plants JSON the detectors must refuse"
+    - "HTTP tracers and other testcontainers suites live in the postgres stage because a skip under -short would fail-closed"
+    - "PHP method map not-applicable rows name a D-id; Herald EndpointGuard pin/reject is D-10 with a fetchguard pointer"
+    - "Forum HTML goldens compare normalized DOM tokens (tags, sorted attrs, collapsed text), not byte-identical markup"
+
+key-files:
+  created:
+    - scripts/check-phase19.1.sh
+    - ../sm-userfriends-plugin/testdata/PHP_METHOD_MAP.md
+    - ../sm-userfriends-plugin/php_method_map_test.go
+    - ../sm-userfriends-plugin/golden_test.go
+    - ../sm-forum-plugin/testdata/PHP_METHOD_MAP.md
+    - ../sm-forum-plugin/golden_test.go
+    - ../sm-chatbots-plugin/testdata/PHP_METHOD_MAP.md
+    - ../sm-chatbots-plugin/golden_test.go
+    - ../sm-herald-plugin/testdata/PHP_METHOD_MAP.md
+    - ../sm-herald-plugin/classes/golden_test.go
+    - ../sm-chatvideo-plugin/testdata/PHP_METHOD_MAP.md
+    - ../sm-chatvideo-plugin/golden_test.go
+  modified:
+    - ../sm-chatvideo-plugin/fixture_plugin_test.go
+
+key-decisions:
+  - "Goldens from PHP fixtures; live capture NOT RUN"
+  - "Execute should now run the security-review agent (five APIs, push sender, token issuer, sanitizer boundary, GDPR cascades). This execute did not spawn it."
+  - "Gate named-short vs postgres split follows the skip detector: TestHTTPTracer and TestReconcileEmptyRoom skip under -short so they are postgres-only"
+
+patterns-established:
+  - "Phase 19.1 gate analog to check-phase19.sh: sibling env overrides, docs greps of locked module path + version, postgres Docker-host stage"
+
+requirements-completed: [SC-19.1-1, SC-19.1-4, D-04]
+
+coverage:
+  - id: D1
+    description: "scripts/check-phase19.1.sh fail-closed self-test, plugins, docs, postgres stages"
+    requirement: SC-19.1-4
+    verification:
+      - kind: other
+        ref: "bash scripts/check-phase19.1.sh --self-test"
+        status: pass
+      - kind: other
+        ref: "bash scripts/check-phase19.1.sh plugins"
+        status: pass
+      - kind: other
+        ref: "bash scripts/check-phase19.1.sh docs"
+        status: pass
+      - kind: other
+        ref: "bash scripts/check-phase19.1.sh postgres"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "PHP method maps + TestPHPMethodMap (chatbots 22, forum 25, herald 14 declarations / 13 unique, userfriends 31, chatvideo 0 in-plugin + Wavepath generic-or-N/A); Herald EndpointGuard D-10; components/seeders D-07"
+    requirement: D-04
+    verification:
+      - kind: unit
+        ref: "go -C ../sm-userfriends-plugin test -count=1 -short -run '^TestPHPMethodMap$' ."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-chatbots-plugin test -count=1 -short -run '^TestPHPMethodMap$' ."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-forum-plugin test -count=1 -short -run '^TestPHPMethodMap$' ."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-herald-plugin test -count=1 -short -run '^TestPHPMethodMap$' ."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-chatvideo-plugin test -count=1 -short -run '^TestPHPMethodMap$' ."
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "Serializer / lighthouse / LiveKit JWT / forum semantic-HTML goldens without VAPID private keys or LiveKit API secrets; TestUserDeletingHeir"
+    requirement: SC-19.1-4
+    verification:
+      - kind: unit
+        ref: "go -C ../sm-userfriends-plugin test -count=1 -short ./..."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-forum-plugin test -count=1 -short ./..."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-chatbots-plugin test -count=1 -short ./..."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-herald-plugin test -count=1 -short ./..."
+        status: pass
+      - kind: unit
+        ref: "go -C ../sm-chatvideo-plugin test -count=1 -short ./..."
+        status: pass
+      - kind: integration
+        ref: "../sm-userfriends-plugin/user_deleting_test.go#TestUserDeletingHeir"
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "Live Wavepath payload capture against a PHP backend"
+    requirement: D-04
+    verification: []
+    human_judgment: true
+    rationale: "goldens from PHP fixtures; live capture NOT RUN — 127.0.0.1:8000, localhost:8000 and wavepath.test were unreachable; https://wavepath.org returned 301 to a public site, not a capture target"
+
+duration: 16min
+completed: 2026-10-18
+status: complete
+---
+
+# Phase 19.1 Plan 06: PHP maps, goldens, scripts/check-phase19.1.sh Summary
+
+**Fail-closed `scripts/check-phase19.1.sh` plus PHP-method maps and PHP-fixture goldens across the five chat-satellite plugins (serializers, lighthouse publications, LiveKit JWT claims, forum semantic HTML).**
+
+## Performance
+
+- **Duration:** 16 min
+- **Started:** 2026-10-18T13:44:31Z
+- **Completed:** 2026-10-18T14:00:36Z
+- **Tasks:** 3
+- **Files modified:** 46 (gate script in summercms.go; maps/goldens/named tests in five sibling repos)
+
+## Accomplishments
+
+- `scripts/check-phase19.1.sh` copies the phase-19 gate shape: stages self-test, plugins, docs, postgres; env `USERFRIENDS` / `FORUM` / `CHATBOTS` / `HERALD` / `CHATVIDEO` default `$ROOT/../sm-<name>-plugin`. Fail-closed skip/miss/red/"no tests to run". `--self-test` plants JSON the detectors must refuse. Docs greps `SherClockHolmes/webpush-go` v1.4.0, `livekit/server-sdk-go/v2` v2.19.0, forum-policy bluemonday v1.0.27.
+- PHP maps: userfriends 31, chatbots 22 all port, forum 25 all port, herald 14 declarations (13 unique names; `test_default_presence_gate_denies` is duplicated in PHP) with EndpointGuard pin/reject **not-applicable (D-10)** plus a fetchguard pointer, chatvideo 0 in-plugin plus Wavepath host methods mapped to generic-API Go or explicit N/A (D-07 guest rooms, call cards, `/_wave` host routes). Components and demo seeders are not-applicable (D-07).
+- Goldens from PHP fixtures; live capture NOT RUN. Serializers (Friend/GroupView, CommandResult, herald web_push payload, forum Category/Thread/Post JSON), lighthouse MemoryDriver publications for `video:call:*`, LiveKit JWT claims without API secret, forum semantic HTML normalized DOM (script, javascript:, iframe, onerror, GFM tables, code blocks, links, autolinks). Adopted `content_html` is served stored (`TestAdoptedContentHTML`). `grep -nE 'private_key|API_SECRET'` on all `testdata/goldens/` is empty.
+- Named tests the gate requires: `TestUserDeletingHeir` (postgres; admin heir + empty hard-delete). After Task 1 verify: ⚡ Tracer verified end-to-end — expanding.
+- Execute should now run the security-review agent now that the five APIs, push sender, token issuer, sanitizer boundary, and GDPR cascades exist. This execute did not spawn it.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: End-to-end phase gate — check-phase19.1.sh self-test plus one named map** - `b1a2c78` (chore, summercms.go); `5ca665b` (test, sm-userfriends-plugin, pushed)
+2. **Task 2: Remaining PHP method maps** - `827b09c` (sm-chatbots-plugin), `191ddf1` (sm-forum-plugin), `86179a8` (sm-herald-plugin), `050b4fe` (sm-chatvideo-plugin); all pushed `origin main`
+3. **Task 3: Goldens and human capture of Wavepath payloads** - `f83726f` (sm-userfriends-plugin), `dbb6135` (sm-forum-plugin), `0f98d95` (sm-chatbots-plugin), `8f9825a` (sm-herald-plugin), `ebb2264` (sm-chatvideo-plugin); all pushed `origin main`
+
+**summercms.go HEAD at Task 1:** `b1a2c78` (not pushed). **Sibling HEADs on origin/main:** userfriends `f83726f`, forum `dbb6135`, chatbots `0f98d95`, herald `8f9825a`, chatvideo `ebb2264`.
+
+## Files Created/Modified
+
+- `scripts/check-phase19.1.sh` - fail-closed phase 19.1 gate
+- `../sm-userfriends-plugin/testdata/PHP_METHOD_MAP.md`, `php_method_map_test.go`, `golden_test.go`, `user_deleting_test.go`, `testdata/goldens/`
+- `../sm-forum-plugin/testdata/PHP_METHOD_MAP.md`, `php_method_map_test.go`, `golden_test.go`, `api/json_test.go`, `testdata/goldens/`
+- `../sm-chatbots-plugin/testdata/PHP_METHOD_MAP.md`, `php_method_map_test.go`, `golden_test.go`, `testdata/goldens/`
+- `../sm-herald-plugin/testdata/PHP_METHOD_MAP.md`, `php_method_map_test.go`, `classes/golden_test.go`, `testdata/goldens/`
+- `../sm-chatvideo-plugin/testdata/PHP_METHOD_MAP.md`, `php_method_map_test.go`, `golden_test.go`, `testdata/goldens/`, `fixture_plugin_test.go` (skip `testdata/` in the retired-token walker)
+
+## Decisions Made
+
+- Goldens from PHP fixtures; live capture NOT RUN.
+- Execute should now run the security-review agent. It was not spawned from this plan.
+- Named tests that skip under `-short` (HTTP tracers, `TestReconcileEmptyRoom`, GDPR cascades, `TestSendEventRollback`) belong in the postgres stage so the skip detector stays fail-closed.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] HTTP tracers skip under -short**
+- **Found during:** Task 1 (gate named-short list)
+- **Issue:** Plan listed `TestHTTPTracer` and `TestReconcileEmptyRoom` among named short tests; they skip without Docker/`-short`, and a skip is refuse.
+- **Fix:** Those names live in the postgres stage alongside `TestSendEventRollback` and GDPR cascade names.
+- **Files modified:** `scripts/check-phase19.1.sh`
+- **Verification:** `--self-test` and `plugins` pass on a Docker-free short run; `postgres` pass with Docker
+- **Committed in:** `b1a2c78`
+
+**2. [Rule 3 - Blocking] Herald unique PHP names are 13 not 14**
+- **Found during:** Task 2
+- **Issue:** RESEARCH counted 14 methods; `test_default_presence_gate_denies` is declared in two PHP files, so unique names are 13.
+- **Fix:** Map unique names; EndpointGuard pin/reject rows remain not-applicable (D-10) with a fetchguard pointer.
+- **Files modified:** `../sm-herald-plugin/testdata/PHP_METHOD_MAP.md`
+- **Verification:** `TestPHPMethodMap` pass
+- **Committed in:** `86179a8`
+
+**3. [Rule 3 - Blocking] phpCustomCode regex allowed 1-char codes**
+- **Found during:** Task 1 (userfriends GroupModels)
+- **Issue:** First regex allowed a 1-character invite code; PHP format is 4–32 without edge hyphens.
+- **Fix:** Pin `^[a-z0-9][a-z0-9-]{2,30}[a-z0-9]$`.
+- **Files modified:** `../sm-userfriends-plugin/group_models_test.go`
+- **Verification:** `TestGroupModels` pass
+- **Committed in:** `5ca665b`
+
+**4. [Rule 3 - Blocking] TestPHPMethodMap D-id must accept D-10**
+- **Found during:** Task 2 (herald)
+- **Issue:** Chat analog required D-02 on not-applicable rows; herald uses D-10.
+- **Fix:** Accept `D-\d+`.
+- **Files modified:** each sibling `php_method_map_test.go`
+- **Verification:** five `TestPHPMethodMap` pass
+- **Committed in:** Task 1/2 sibling commits
+
+**5. [Rule 3 - Blocking] chatvideo PHP_METHOD_MAP.md names Wavepath**
+- **Found during:** Task 3 (`TestFixtureAbsentFromProduction`)
+- **Issue:** The Wavepath host-test table is required by D-04; `wavepath` is a retired production token.
+- **Fix:** Skip the `testdata/` directory in the walker (testdata is not production source).
+- **Files modified:** `../sm-chatvideo-plugin/fixture_plugin_test.go`
+- **Verification:** `go test -count=1 -short ./...` pass
+- **Committed in:** `ebb2264`
+
+---
+
+**Total deviations:** 5 auto-fixed (Rule 3 blocking)
+**Impact on plan:** Required so the fail-closed gate, unique PHP-name map, invite-code pin, D-10 N/A rows, and Wavepath mapping coexist. No scope creep. Plans 01-05 production code was not re-implemented.
+
+## Issues Encountered
+
+No live PHP Wavepath backend was reachable for payload capture (loopback :8000, `wavepath.test` failed; `https://wavepath.org` is a public 301). Goldens were derived from frozen PHP tests / Go serializers. Security-review agent was not spawned (recorded for execute).
+
+## TDD Gate Compliance
+
+N/A — TDD is not applicable for this plan. Tracer verify is automated-only (`HUMAN_VERIFY_MODE=end-of-phase`). After Task 1 automated verify passed: ⚡ Tracer verified end-to-end — expanding.
+
+## Auth gates
+
+None. Task 3 human-check used the documented fallback (PHP fixtures; live capture NOT RUN) and did not invent a blocking-human checkpoint.
+
+## Known Stubs
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+Phase 19.1 plans 01-06 have SUMMARYs. Ready for `/msd-verify-work` on 19.1. Execute should now run the security-review agent (five generic APIs, push sender, LiveKit token issuer, HTML sanitizer boundary, GDPR cascades) — not spawned here. summercms.go was not pushed.
+
+---
+*Phase: 19.1-chat-satellites*
+*Completed: 2026-10-18*
+
+## Self-Check: PASSED
+
+- FOUND: `scripts/check-phase19.1.sh` (`USERFRIENDS`, `TestPHPMethodMap`, `TestReconcileEmptyRoom`)
+- FOUND: `../sm-userfriends-plugin/testdata/PHP_METHOD_MAP.md` (wc -l > 31)
+- FOUND: `../sm-chatbots-plugin/testdata/PHP_METHOD_MAP.md` (22)
+- FOUND: `../sm-forum-plugin/testdata/PHP_METHOD_MAP.md` (25)
+- FOUND: `../sm-herald-plugin/testdata/PHP_METHOD_MAP.md` (`not-applicable (D-10)`)
+- FOUND: `../sm-chatvideo-plugin/testdata/PHP_METHOD_MAP.md` (`N/A`)
+- FOUND: five `testdata/goldens/` trees; `grep -nE 'private_key|API_SECRET'` empty
+- FOUND: `../sm-forum-plugin/golden_test.go` (`TestForumSemanticHTML`); `../sm-forum-plugin/api/json_test.go` (`TestAdoptedContentHTML`)
+- FOUND: `../sm-userfriends-plugin/user_deleting_test.go` (`TestUserDeletingHeir` PASS postgres)
+- PASS: `bash scripts/check-phase19.1.sh --self-test`
+- PASS: `bash scripts/check-phase19.1.sh plugins`
+- PASS: `bash scripts/check-phase19.1.sh docs`
+- PASS: `bash scripts/check-phase19.1.sh postgres`
+- PASS: `go test -count=1 -short ./...` in all five siblings
+- RECORDED: goldens from PHP fixtures; live capture NOT RUN
+- RECORDED: execute should now run the security-review agent