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
@@ -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