docs: add tasks 02b and 02c for the dead token layer and the gap queue

2026-09-05 19:23:03 +00:00
parent 7f11b6e88e
commit 4b758c765d
3 changed files with 160 additions and 0 deletions
@@ -45,6 +45,8 @@ Phase 4  polish            18 ∥ 19, then 20
 | --- | ----------------------------------------------------------------- | --------------------- | ------------------ | ------------- |
 | 01  | [scaffold + gates](task-01-scaffold.md)                           | astro-architect       | —                  | —             |
 | 02  | [design tokens](task-02-tokens.md)                                | design-system-keeper  | 01                 | 03, 04        |
 | 02b | [token layer wiring](task-02b-token-layer-wiring.md)              | design-system-keeper  | 02                 | 03, 04        |
 | 02c | [token-gap queue](task-02c-token-gaps.md)                         | design-system-keeper  | 02b, 15d           | —             |
 | 03  | [verification net](task-03-verification-net.md)                   | verification-engineer | 01                 | 02, 04        |
 | 04  | [content schema](task-04-content-schema.md)                       | content-i18n-migrator | 01                 | 02, 03        |
 | 05  | [guide content](task-05-content-guide.md)                         | content-i18n-migrator | 04                 | 06            |
@@ -0,0 +1,107 @@
 # Task 02b — Wire the token layer in
 **Agent**: `design-system-keeper` · **Model**: `agy` (Gemini 3.1 Pro — needs
 vision for the screenshot diffs) **Depends on**: 02 · **Blocks**: 02c
 **Worktree**: `.agents/scripts/worktree.sh start 02b token-layer-wiring`
 ## Why this task exists
 Task 02 built the token layer and it was never connected to anything. This is
 not a criticism of that task — its brief and its done-when list never asked for
 the wiring, and `check-tokens.mjs` only looks for _violations_ in `src/`, so
 nothing could have caught it.
 Verify each of these yourself before you start; do not take my word for it:
 1. **`src/styles/tokens.css` is imported by nothing.** The only reference in the
   repo is `src/styles/base.css:2`, and `base.css` is itself imported nowhere.
   The whole layer is dead code.
 2. **The pages import the legacy stylesheets instead**, drifted `:root` blocks
   and all:
   - `src/layouts/ChapterLayout.astro:16` → `../../chapters.css?url`
   - `src/pages/skills.astro:11` → `../../skills/styles.css?url`
   - `src/pages/skills-review.astro:4,5` → `skills-review/styles.css`,
     `change-lens.css`
 3. **So task 02's `--blue` decision never reached a page.** It chose `#527f9f`
   and wrote it down. The built CSS today ships both values:
   ```
   dist/_astro/chapters.*.css   --blue:#215675
   dist/_astro/rules.*.css      --blue: #527f9f
   dist/_astro/styles.*.css     --blue:#215675
   ```
 ## Scope
 `src/styles/tokens.css`, `src/styles/base.css`,
 `.agents/scripts/check-tokens.mjs` — you are the only writer of these — plus the
 four import sites listed above and whatever layout work the wiring needs.
 ## Deliver
 ### 1. One loaded token layer
 Make `tokens.css` actually load on every route. Either fix `base.css` and import
 it from the layouts, or drop `base.css` and import `tokens.css` directly — your
 call, but say which and why. A file that exists and is never loaded is worse
 than no file, because it reads as done.
 ### 2. The legacy stylesheet imports reconciled
 Those three `?url` imports are how the drifted palettes reach production. You do
 not have to delete them in this task — much of that CSS is still load-bearing
 until task 15e and task 20 — but the `:root` blocks inside them must stop
 overriding the canonical tokens. Make the layer authoritative and prove with
 screenshots that nothing moved except what you intend.
 `--blue` is the one real difference: `#527f9f` vs `#215675` is visible. Task 02
 already decided `#527f9f`. Apply that decision; do not re-open it. If applying
 it looks wrong on a real page, screenshot it and escalate rather than quietly
 picking the other value.
 ### 3. Font tokens
 Manrope and DM Mono are **real now** — self-hosted in `public/fonts/`, wired
 through `public/fonts/fonts.css` (linked by `BaseLayout.astro`, `@import`ed by
 the legacy root `styles.css`). Read `.agents/context/design-system.md`; the old
 "delete the dead rule, fall back to Arial" instruction is **superseded and must
 not be re-applied**.
 Add `--font-sans` and `--font-mono` and point the stacks at them. Do not touch
 `public/fonts/fonts.css` itself, and do not remove the faces.
 ### 4. A check so this cannot recur
 The gap that let a dead token layer ship is that nothing asserts the tokens are
 _loaded_. Add that check — a build-output assertion that every route resolves
 the canonical palette, or an equivalent. Put it in `check-tokens.mjs`, which you
 own. **Do not touch `scripts/verify.mjs`**; it stays at 42 assertions and only
 the verification-engineer may change it.
 ## Screenshots: your baseline is HEAD, not history
 The self-hosted fonts landed in `7f11b6e` and **changed how every page
 renders**, deliberately — that is the one sanctioned visual change in this
 migration. Any screenshot taken before it shows Arial and is not a valid
 baseline. Capture your own "before" from HEAD at the start of this task.
 Widths: 560 / 800 / 1100 / 1600, plus the eight breakpoints task 02 removed
 (520, 530, 600, 620, 720, 850, 880, 900) — that is where regressions hide.
 ## Do not
 - Do not resolve the ~164 `token-gap:` markers. That is task 02c, and doing it
  here would collide with task 15d's page work. Report the count.
 - Do not delete `responsive.css`. That is 15e.
 - Do not convert the `gap:1px` over a coloured parent trick into `border` — it
  is deliberate house style and appears everywhere.
 - Do not rename tokens to numeric scales (`--color-neutral-900`).
 - Never use `--no-verify`; never set `core.hooksPath`.
 ## Done when
 - [ ] `tokens.css` loads on every route, proven from built output
 - [ ] One value per token in the shipped CSS — `--blue` is `#527f9f` everywhere
 - [ ] `--font-sans` / `--font-mono` exist and are used; the faces still load
 - [ ] A check exists that fails if the token layer stops being loaded
 - [ ] Before/after screenshots at all twelve widths, every difference explained
 - [ ] `pnpm run gate` green — the full gate; 42 assertions intact
@@ -0,0 +1,51 @@
 # Task 02c — Work the token-gap queue
 **Agent**: `design-system-keeper` · **Model**: `agy` (Gemini 3.1 Pro) **Depends
 on**: 02b, 15d · **Blocks**: 19 **Worktree**:
 `.agents/scripts/worktree.sh start 02c token-gaps`
 ## Why this task exists
 `check-tokens.mjs` bans raw hex, `font-size: Npx` and ad-hoc breakpoints outside
 the token layer. Until the escape hatch was added it offered no legal
 alternative, so agents told both "keep the site identical" and "get the gate
 green" cheated — writing px through the `font:` shorthand the regex misses, or
 substituting the nearest token and shipping a silent redesign (`12px` and `14px`
 both became `var(--step-1)`, 15px; a diff-added green became `var(--accent)`,
 purple).
 The `/* token-gap: <reason>; owner design-system-keeper */` marker replaced that
 with an honest, visible queue. **You are the owner it names.** There are ~164
 markers on `main`; get the real count yourself from `check-tokens.mjs` output.
 ## The work
 For each marked value, one of three outcomes — and the choice is yours to make,
 not to defer:
 1. **The scale should cover it.** Extend `--step-*` and point the site at it.
   Most of the queue is this: `24px`, `25px`, `20px`, `17px`, `13px` fixed sizes
   from `chapters.css` that fall between existing steps.
 2. **It is genuinely one-off.** Keep the literal value, delete the marker, and
   leave a comment saying why it is exempt.
 3. **It was already wrong.** Some markers record a near-miss substitution an
   earlier task made under duress. Restoring the true legacy value is a visible
   change — screenshot it and say so.
 Work in batches by source file and commit per batch. A single 164-site commit is
 unreviewable.
 ## Do not
 - Do not weaken `check-tokens.mjs` to make markers disappear. Removing a check
  is not resolving a gap.
 - Do not touch `scripts/verify.mjs` — 42 assertions, verification-engineer only.
 - Do not leave a marker whose reason you have satisfied.
 ## Done when
 - [ ] Every marker either resolved into the scale or documented as a deliberate
      exemption
 - [ ] `check-tokens.mjs` reports zero unexplained gaps
 - [ ] Screenshots for every change that moved a pixel, differences explained
 - [ ] `pnpm run gate` green; 42 assertions intact