refactor: retire the hand-written site
Deletes the pre-Astro pages, scripts, and stylesheets that the migration replaced, and moves the ones it did not replace out of the way. Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js, rules/styles.css, skills/app.js, the ten route index.html files, and the root hands-on/ copy, which is byte-identical to public/hands-on/ -- the one the build actually ships. Moved to legacy/ (12 files): styles.css, full-guide/audit.css, chapters.css, skills/styles.css, skills-review/styles.css, skills-review/change-lens.css, and the skills-review/app.js module graph. These are not dead. The Astro pages import them and the build fails without them, which the plan had not accounted for. They go to legacy/ rather than src/ because check-tokens.mjs sweeps src, and these files are full of raw hex and unnamed breakpoints: moving one into src/ should mean migrating it to tokens in the same change, not adding a scan exclusion. The prettier, stylelint, and eslint ignore lists that already named these files at their old paths now name legacy/ instead. verify.mjs no longer reads app.js. The 102 Portuguese strings were extracted from its translations.pt object before deletion into .agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot of the Astro build, so the assertion still compares against an independent source. The brace-matching helper's assertion is replaced by one that rejects an empty snapshot entry, without which trimming the snapshot would make the presence check pass vacuously. Count stays at 84. audit-ui.mjs reads the ten pages from dist/ and resolves Astro's base-absolute hrefs against it. Before deleting anything, rendered-text-diff was run across all ten routes plus both Portuguese pages: every one at parity, 0 missing and 0 extra. That comparison is not repeatable once the legacy files are gone. computed-style-diff on /full-guide/ stays at 32 differences, so the moves are style-neutral. Docs updated to match: README, AGENTS.md, GATES.md, the architecture context, the operations guide's lab instructions, and the three skills that told you to serve the vanilla site. Publishing is not part of this commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -12,11 +12,11 @@ rules, and verification.** It is published as a static site on a self-hosted
|
||||
Gitea Pages Server, and it doubles as its own teaching artifact: the hands-on
|
||||
labs are dependency-free HTML/CSS/JS that workshop attendees point an agent at.
|
||||
|
||||
- **Current stack**: hand-written HTML + CSS + ES modules, no build step, no
|
||||
dependencies
|
||||
- **Target stack**: Astro (see
|
||||
[`plans/astro-refactor/`](plans/astro-refactor/README.md)) — migration in
|
||||
progress
|
||||
- **Stack**: Astro, static output, no runtime dependencies. The migration
|
||||
recorded in [`plans/astro-refactor/`](plans/astro-refactor/README.md) is
|
||||
complete; the hand-written pages it replaced are gone. What remains unmigrated
|
||||
is the editorial CSS and the review-desk modules under `legacy/`, still
|
||||
imported by the pages that need them.
|
||||
- **Languages**: English and Brazilian Portuguese, toggled client-side
|
||||
- **Companion service**: `vote-service/` (Go + Kubernetes) — separate lifecycle,
|
||||
see its own README
|
||||
@@ -24,33 +24,34 @@ labs are dependency-free HTML/CSS/JS that workshop attendees point an agent at.
|
||||
## Essential commands
|
||||
|
||||
```bash
|
||||
pnpm run verify # content + interaction contracts (scripts/verify.mjs) — the gate
|
||||
pnpm run dev # http://localhost:4321/ai-for-dummies/
|
||||
pnpm run build # writes dist/ — every check below reads it
|
||||
bash .agents/scripts/gate.sh # the full gate: check, build, verify, audit, tokens
|
||||
pnpm run verify # content + interaction contracts (scripts/verify.mjs)
|
||||
node scripts/audit-ui.mjs # responsive / no-external-dependency audit
|
||||
node scripts/build-skill-review.mjs # regenerate skill-reviews/improved/ from src/content/reviews/
|
||||
pnpm run serve # python3 -m http.server 4173
|
||||
```
|
||||
|
||||
`pnpm run verify` is not a formality. It is a set of ~42 string-token assertions
|
||||
that pin the site's real content and interactions. **A refactor that "passes" by
|
||||
deleting assertions has failed.** See
|
||||
`pnpm run verify` is not a formality. It is a set of 84 string-token assertions
|
||||
that pin the site's real content and interactions, read from the built output.
|
||||
**A refactor that "passes" by deleting assertions has failed.** See
|
||||
[`.agents/context/verification.md`](.agents/context/verification.md).
|
||||
|
||||
## Publishing
|
||||
|
||||
`main` is the source of truth. The `pages` branch is what the Gitea Pages Server
|
||||
actually serves, and its tree must end up identical to `main`'s. The full
|
||||
procedure — including why `merge --ff-only` does _not_ work here — is in
|
||||
[`docs/operations-guide.md`](docs/operations-guide.md).
|
||||
|
||||
Adding a build step changes this contract. Read
|
||||
[`.agents/context/publishing.md`](.agents/context/publishing.md) before doing
|
||||
so.
|
||||
actually serves, and it now carries **build output**, not a copy of `main`'s
|
||||
tree. The publish job force-pushes `dist/` over it. The full procedure is in
|
||||
[`docs/operations-guide.md`](docs/operations-guide.md); read
|
||||
[`.agents/context/publishing.md`](.agents/context/publishing.md) before changing
|
||||
it.
|
||||
|
||||
## Never touch
|
||||
|
||||
- `hands-on/starter/` and `hands-on/rules/` — **lab fixtures.** The exercise
|
||||
_is_ that they are dependency-free vanilla HTML/CSS/JS an attendee can hand to
|
||||
an agent. Componentizing them destroys the lesson. They ship as static assets.
|
||||
- `public/hands-on/starter/` and `public/hands-on/rules/` — **lab fixtures.**
|
||||
The exercise _is_ that they are dependency-free vanilla HTML/CSS/JS an
|
||||
attendee can hand to an agent. Componentizing them destroys the lesson. They
|
||||
ship as static assets.
|
||||
- `submitted-skills/` — other people's submitted work, reproduced verbatim
|
||||
- `skill-reviews/improved/` — generated; edit `src/content/reviews/*.md` instead
|
||||
- `vote-service/` — separate deploy lifecycle; do not fold into the site build
|
||||
|
||||
Reference in New Issue
Block a user