docs(14.2): record human verification, D-02 and D-12 amendments

This commit is contained in:
2026-10-12 13:02:13 +02:00
parent 2e6a72b6e9
commit 55476db582
2 changed files with 24 additions and 24 deletions

View File

@@ -18,6 +18,7 @@ Repos: `fonoteka.go` (seed command, start script, dev env template, any Go fixes
### Local data
- **D-01:** Local data comes from `fonoteka migrate` followed by a new seed command. The Phase 20 `import:winter` runner is not pulled forward, and PHP data is not imported in this phase.
- **D-02:** The seed is an application command, `fonoteka dev:seed` (final name at the planner's discretion), in the fonoteka plugin, not a framework seeder hook. It refuses to run unless the app environment is local/dev, and it is idempotent: a second run changes nothing. It creates:
- *Amended 2026-10-12 (code review WR-05, accepted by the developer):* the seed, the backend marker route and `dev-stack.sh` accept `SUMMER_ENV=local` only; `dev` is refused because it is a common name for shared servers. The seed also refuses to modify an existing user it did not create (opt-in `DEV_SEED_RESET_EXISTING=1`) and a token row owned by another user.
- a verified user;
- an owned collection;
- a few albums;
@@ -46,6 +47,7 @@ Repos: `fonoteka.go` (seed command, start script, dev env template, any Go fixes
- **D-10:** The marker is a route only the Go binary serves (an existing framework health/readiness route, or the smallest new one) that stays **outside the parity manifest**. No manifest route's response changes, and no new header is added to API responses.
- **D-11:** `vue-fonoteka-app` may receive **small non-breaking changes** (user's decision). The constraint: the app must still run without issues against the PHP backend. Gaps found during the session are fixed in Go first, with a parity case added where a recorded PHP response exists. An app change is acceptable only when it leaves PHP behavior unchanged (for example an env-switched test helper, a new backend-agnostic spec, or docs and `.env.example` notes). Commits in `vue-fonoteka-app` go to its own repo, which is a submodule of the PHP `fonoteka` repo.
- **D-12:** Failures show up through the Go request log, which is redacted by sunscreen and records each request's path and status, and through Nuxt's normal behavior. The script tees both processes into labeled log files, and the run docs say to watch them for 4xx/5xx and 404 responses. No 404 tally or dev-only error UI is added.
- *Amended 2026-10-12 (code review WR-01, accepted by the developer):* the Go request log never records the URL path, not even for unmatched requests, because share and invitation tokens travel in paths. It records method, matched pattern, status and duration. An unported route shows as `status=404 pattern=""`; take the path from the browser network tab.
### Flow proof
- **D-13:** The flows are proven twice:

View File

@@ -1,8 +1,8 @@
---
phase: 14.2-local-fonoteka-frontend-on-local-summercms-backend
verified: 2026-10-12T10:41:00Z
status: human_needed
score: 49/54 must-haves verified
status: passed
score: 54/54 must-haves verified (5 by override or human verification)
covered_files:
- .planning/phases/14.2-local-fonoteka-frontend-on-local-summercms-backend/14.2-01-PLAN.md
- .planning/phases/14.2-local-fonoteka-frontend-on-local-summercms-backend/14.2-01-SUMMARY.md
@@ -23,43 +23,41 @@ covered_files:
- modules/surf/uploads_test.go
- scripts/check-phase14.2.sh
covered_digest: "v2:sha256:458b8aba274a449e0c7fec7aa5776f833f9e2dc54b4b2686e64b625d0e59960c"
behavior_unverified: 1
overrides_applied: 1
behavior_unverified: 0
overrides_applied: 3
overrides:
- must_have: "Per D-11, D-16 and D-21, the new and rewritten specs also pass against the PHP backend on :8422 with the app's own PHP-targeted .env"
reason: "The PHP run (UAT item 11) gave expected=4 unexpected=2. Both failures were classified as non-contract: the PNG_1PX fixture cannot be decoded by PHP GD (Resizer.php:139), and the local PHP env has no Centrifugo config. Go passed the same specs. Both follow-ups are in deferred-items.md."
accepted_by: "developer (14.2-UAT.md item 11, 'The developer accepted the classification')"
accepted_at: "2026-10-11T21:04:28Z"
behavior_unverified_items:
- truth: "(14.2-02, edge: concurrency) `up` in the foreground stops both process groups and removes the pid file on Ctrl-C, TERM or any failure (EXIT trap)"
test: "Run `scripts/dev-stack.sh up` in the foreground (stack down first), wait for 'Ctrl-C stops both', press Ctrl-C. Separately, send TERM to the script's pid."
expected: "Both the Go and the Nuxt process groups are gone (ports 8423 and 3119 free), tmp/dev-stack/pids is removed, and the script exits non-zero (130 or 143)."
why_human: "cleanup() and the INT/TERM/EXIT traps are present and wired in up(), but no test or gate stage exercises a foreground interrupt. The gate only uses `up --detach` and `down`."
- must_have: "TestDevSeedRefusesProduction proves local and dev pass the gate; TestDevMarkerRoute answers 200 for local and dev (D-02; 14.2-01 truths 3 and 7, 14.2-04 truths 2 and 5)"
reason: "WR-05: dev is a common name for a shared server; seed, marker and dev-stack.sh accept local only. D-02 amended in 14.2-CONTEXT.md."
accepted_by: "developer (orchestrator question after verification)"
accepted_at: "2026-10-12T11:01:43Z"
- must_have: "http.access_log adds path without its query string only for unmatched requests (D-12; 14.2-01 truth 9, 14.2-04 truth 7)"
reason: "WR-01: share and invitation tokens travel in paths; the log records method, pattern, status and duration only. D-12 amended in 14.2-CONTEXT.md."
accepted_by: "developer (orchestrator question after verification)"
accepted_at: "2026-10-12T11:01:43Z"
behavior_unverified_items: []
human_verified:
- test: "Foreground `dev-stack.sh up`: SIGINT stops Go and Nuxt and removes the pid file"
result: "pass: ran by the orchestrator at the developer's request; exit=130, tmp/dev-stack/pids removed, ports 8423 and 3119 free, no fonoteka serve or nuxt dev process left; stack restarted with up --detach"
recorded_at: "2026-10-12T11:01:43Z"
- test: "Four test-tier prohibitions, checked with commands"
result: "pass: (1) `git log df7876b..HEAD -- plugins/golem15/user` in fonoteka.go is empty; (2) vue-fonoteka-app `git status --short` is clean; (3) dev-stack.sh mentions /etc/centrifugo/config.json only in warn text and has no systemctl or publish call; (4) all 54 'E2E ...' albums in fonoteka_go_dev have deleted_at set, i.e. every spec's DELETE ran; soft delete matches PHP (Album.php uses Winter SoftDelete)"
recorded_at: "2026-10-12T11:01:43Z"
- test: "UAT items 1-11 (login, browse collections/albums, album detail, search, edit, rate, cover upload, wishlist add/remove, realtime, no 5xx/no PHP header, PHP cross-check)"
uat_row: "1-11"
recorded_at: "2026-10-11T21:04:28Z"
note: "Files changed after the UAT (review fixes WR-01..09: accesslog.go, uploads.go, router.go, dev_seed.go, dev-stack.sh, runTinker.ts, realtime.spec.ts) were re-exercised by the gate's Go e2e run e2e-20261012T101126Z (17/0/0/0, started 10:11:27Z, after the last Go commit 261d9bc and the build stamp 09:28:54Z): login with the seed, cover decode through the Nuxt /storage proxy, search, wishlist, realtime subscribe and push. go.log has 0 5xx records. No re-test requested."
human_verification:
- test: "Accept WR-05: SUMMER_ENV=dev is now refused by fonoteka:dev-seed, the backend marker route and dev-stack.sh"
expected: "The developer confirms that 'local only' replaces the locked 'local or dev' rule (D-02, 14.2-01 truths 3 and 7, 14.2-04 truths 2 and 5), and records an override or updates D-02."
why_human: "Intentional contract change made during code-review fixes (REVIEW-FIX marks it 'requires human verification (behaviour change)'). TestDevSeedRefusesProduction and TestDevMarkerRoute now assert that dev is refused, which contradicts the plan-04 truths as written. Only the developer can accept a change to a locked decision."
- test: "Accept WR-01: the request log never records the URL path, not even for an unmatched request"
expected: "The developer confirms that D-12 ('records each request's path and status') and the 14.2-01 truth 9 / 14.2-04 truth 7 ('path without query only for unmatched requests') are superseded. An unported route then shows in go.log as status=404 with pattern=\"\", and the path is visible only in the browser network tab (README § Logs). The developer records an override or updates D-12."
why_human: "This is a security-motivated narrowing: share and invitation tokens travel in paths. It weakens the D-12 diagnostic ('a 404 on a path the Nuxt app calls is a route the port is missing'), because the Go log no longer names the missing path. Whether that trade-off is acceptable is a product decision."
- test: "Foreground `dev-stack.sh up`: Ctrl-C / TERM stops Go and Nuxt and removes the pid file"
expected: "Ports 8423 and 3119 are free, tmp/dev-stack/pids is gone, and the exit code is 130 (INT) or 143 (TERM)."
why_human: "Cleanup invariant with no automated test (see behavior_unverified_items)."
- test: "Review four test-tier prohibitions that are enforced only by static evidence (unverified-prohibition, human review recommended)"
expected: "Confirm: (1) sm-user-plugin is not modified by any phase commit; `git log df7876b..HEAD -- plugins/golem15/user` in fonoteka.go is empty, and the submodule drift (569768e) is another session's test-only commit from before plan 01. (2) dev-stack.sh writes no file in DEV_STACK_NUXT_DIR: it only checks writability, and `pnpm dev` gets the NUXT_* values as env. vue-fonoteka-app `git status` is clean. (3) dev-stack.sh never reads or edits /etc/centrifugo/config.json and never restarts Centrifugo or calls publish; the path appears only in warning text, and the probes are info/history. (4) Every spec deletes the albums and wishlist entries it created in `finally`, with Date.now() names. Known residue: orphan 'E2E Artist' rows (deferred-items.md)."
why_human: "These prohibitions are declared `verification: test`, but no test or gate stage enforces them. Under the fail-closed rule for test-tier prohibitions they cannot be marked green on code reading alone."
human_verification: []
---
# Phase 14.2: Local Fonoteka frontend on local SummerCMS backend: Verification Report
**Phase goal:** A developer runs the existing `vue-fonoteka-app` locally against the local `fonoteka.go` SummerCMS backend (not PHP), logs in, and uses the real Nuxt flows so the port is proven in daily use before production cutover.
**Verified:** 2026-10-12T10:41:00Z
**Status:** human_needed
**Status:** passed (after human verification on 2026-10-12T11:01:43Z: D-02 and D-12 overrides accepted, foreground Ctrl-C cleanup and the four prohibitions checked)
**Re-verification:** No (initial verification; no previous VERIFICATION.md)
The phase goal is achieved in the codebase. All four roadmap success criteria are verified with fresh or post-fix evidence. Nothing blocks. Four items need a human decision: two deliberate contract narrowings from the review fixes (WR-05, WR-01), one cleanup invariant that no test exercises, and four test-tier prohibitions enforced only statically.
@@ -100,7 +98,7 @@ ROADMAP sets `**Mode:** mvp`, but the goal is not in user-story form. `user-stor
| 14.2-03 | 10 | 10 (1 by override) | #7 PHP cross-check: PASSED (override); the developer accepted the classification. #8 no `app/` change: `git diff --name-only 984031f..HEAD -- app` is empty, and only `tests/` changed (12 files). #9 operator step: proven by behaviour, since the realtime spec (subscribe on `collection:` without 102, push received) passed with 0 skips. |
| 14.2-04 | 13 | 10 | ? #2 and #5 ("local and dev pass the gate", marker 200 for dev) superseded by WR-05. ? #7 ("raw path without query only for an unmatched request") superseded by WR-01. The rest is verified by the reruns. |
**Score:** 49/54 truths verified (4 roadmap SC plus 50 plan truths; 1 by override). 4 are UNCERTAIN (deliberate contract changes awaiting human acceptance) and 1 is present but behaviour-unverified.
**Score:** 54/54 truths verified after human verification (previously 49/54 (4 roadmap SC plus 50 plan truths; 1 by override). 4 are UNCERTAIN (deliberate contract changes awaiting human acceptance) and 1 is present but behaviour-unverified.)
### Prohibitions (must-NOT)