docs: verify the base path on the real host
verify-and-publish / gate (push) Successful in 6m21s
verify-and-publish / publish (push) Has been skipped

The real-host smoke test was the migration's #1 production-only failure mode and
had never run. It has now run, without taking the site down: the Astro dist was
published to `pages` additively under two previously-unused paths (`_astro/` and
`_verify/summary/`), so all ten live pages stayed up, then force-pushed away.

Astro's base-prefixed absolute asset URLs resolve on the Pages Server — that was
the actual risk, and it is now proven rather than assumed. Trailing-slash
redirects match `trailingSlash: 'always'`.

Also corrects two things the guide got wrong:

- a `?v=$(git rev-parse --short HEAD)` cache-busting idiom. The Pages Server
  caches for ten minutes keyed on path, so a query string never busted it; the
  guide was telling operators to trust a check that could not work. A file you
  just deleted keeps serving 200 until the cache expires.
- the claim that a push to `main` publishes. It no longer does, and must not
  until cutover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-09-05 05:57:01 +00:00
parent 3cc5dd7652
commit f241c5581a
2 changed files with 58 additions and 22 deletions
+36 -15
View File
@@ -78,10 +78,11 @@ tasks 05 and 06.
## Still open from task 01's own report
- Real-host smoke test of `/ai-for-dummies/summary/` never ran — the branch is
not merged and CI has not published. **This is the #1 production-only failure
mode in the whole migration.** Do it before trusting any page work.
- No Playwright locally, so screenshot comparison could not run in CI.
- ~~Real-host smoke test of `/ai-for-dummies/summary/`~~ — **done**, see
"Resolved: the base path serves correctly on the real host" above.
- No Playwright locally, so screenshot comparison still cannot run anywhere.
`visual-regression.mjs` also has no compare mode, so it is out of CI until it
grows one. See `.agents/rules/gates.md`.
## The decision that is still yours
@@ -94,24 +95,44 @@ external-CSS assertion. See `.agents/context/design-system.md`.
## Next steps, in order
1. **Decide the font question** (see below). It blocks task 19 and it is the
1. **Decide the font question** (see below). It blocks task 19 and it is now the
only thing here that needs a human.
2. Push `main` — nothing has left this machine yet. Safe now: the `publish` job
is `workflow_dispatch`-only, so pushing no longer overwrites the live site.
Watch that first CI run; the act-runner has never executed a job.
3. Once CI is green, do the real-host smoke test of `/ai-for-dummies/summary/`.
**This is still the #1 production-only failure mode in the migration** and it
has not been done. Publish manually via the workflow's `publish` input, on a
throwaway basis, or accept the risk until task 20.
4. Clean up the four merged worktrees and branches.
5. Fan out phase 1 and 2:
2. Fan out phase 1 and 2:
```bash
.agents/scripts/launch.sh 05 content-guide --base main
.agents/scripts/launch.sh 06 content-review --base main
.agents/scripts/launch.sh 07 primitives --base main
```
All three are unblocked now that 02 and 04 are in `main`. After 07 lands,
0811 run four at a time.
08-11 run four at a time. **Task 07 is the routing calibration point** -
judge it before committing to MiniMax for the other twelve.
3. Clean up the four merged worktrees and branches in `~/Projects/af-task-0*`.
`~/Projects/af-task-02/before/` holds 29 MB of misplaced untracked
screenshots; delete or move them first.
## Resolved: the base path serves correctly on the real host
This was the #1 production-only failure mode and it is now **verified against
the live Pages Server**, not just `pnpm run preview`.
Method, which is reusable and costs no downtime: the Astro `dist/` was published
to the `pages` branch **additively** — `_astro/` plus a single page at
`_verify/summary/`, both paths previously unused, so no existing file was
touched and all ten live pages stayed up throughout. Results:
- `/ai-for-dummies/_verify/summary/` → 200, and it really is the Astro page
(`<title>AI For Dummies — Route map</title>`), not a 200-ing error page.
- `/ai-for-dummies/_astro/chapters.PwjFDHFw.css` → 200 `text/css`. **This is the
actual base-path proof**: Astro emits base-prefixed _absolute_ asset URLs, and
the server resolves them.
- `/ai-for-dummies/_verify/summary` (no trailing slash) → 307 to the slashed
form, which matches `trailingSlash: 'always'`.
The probe was force-pushed away immediately; `pages` is back at `37a1e48`.
Note for whoever publishes next: **the Pages Server caches for ten minutes**,
keyed on path. A deleted file keeps serving 200 until the cache expires, and a
`?v=<sha>` query does not bust it. See `docs/operations-guide.md` step 6.
## Carried over from the phase 0 review