design: TDDs 0070–0072 + ADR 0017 (/ux-author phase)

[cahenesy]

Designs PRD FR-89–FR-101 (PRD-rev 3be6232): the optional /ux-author
phase between /prd-author and /tdd-author.

• 0070 ux-record-lib: scripts/lib/ux.sh plus python3-stdlib helpers.
  Covers the [UI] grammar (loud on a malformed marker), per-requirement
  hash delta, the docs/ux/index.json schema v1, validate (offline-only
  mocks, required states, no committed captures), scoped headless-Chrome
  render, capture, the generated index.html flow page, and merged-index
  coverage.
• 0071 ux-author-skill: the /ux-author skill and the agents/ux-reviewer
  critique. The skill shows a draft screen plan first, interviews,
  co-creates a rubric, then has mocks made by delegates by role (or the
  session, with fidelity declared), followed by in-session review, the
  fresh-worker critique, and a docs/ux/ PR it never merges.
• 0072 ux-in-prd-and-tdd-author: /prd-author writes [UI] markers;
  /tdd-author refuses an un-mocked [UI] requirement unless it is waived;
  a tdd-lint citation check; a design-reviewer bullet.
• ADR 0017: the UX record lives in-repo as self-contained HTML, design
  is delegated by role, and mocks are design input, never a build gate.

Cascade correction to #191: FR-89–FR-101 are new requirements, so no
implemented TDD is superseded.

Design critique (design-reviewer, fresh worker each round)

DESIGN_REVIEW: PASS on round 5. Rounds 1–4 BLOCKed:

• R1: render-degrade contract; orphaned mappings.
• R2: TL_SCREENS "empty means all"; FR-90 plan-first.
• R3: screenshot completeness vs scoped render.
• R4: screenshot fields owned by render but needing edits from the
  skill.
  All were fixed. R4 was fixed at the root: screenshots are derived from
  disk and never stored in index.json. R5 PASSed with 6 minor findings
  and 4 nits. All of them were folded in after the PASS as clarifications,
  not re-reviewed:
• step-8 assets limited to data:/SVG/fonts;
• the PR screenshot line comes from the final validate count;
• design-system cases ordered, and the established ADR written accepted;
• merged-screen drop removes requirements left with no screen;
• re-render on viewport change, with a stated point;
• mktemp paths recorded in the draft; obs wording.
  Every round graded against the co-created rubric (present in each TDD).
  No criterion was graded failing in round 5.

Open assumptions & waivers

• requirement id grammar — resolved: strict **<ID> [UI] <title>**, ID [A-Z][A-Z0-9]*-[0-9]+; any unparseable [UI] makes ux.sh exit 2 naming the line.
• delegate output not self-contained — resolved: validate rejects http(s)/// URLs in mocks; raster images inlined as data: URIs or SVG; only fonts/SVG vendored.
• delegate detection is unverifiable — resolved: the index lists only delegates actually invoked; the reviewer is told provenance is self-reported and grades the declared fidelity (accepted residual).
• renderer — resolved: headless Chrome/Chromium CLI found on PATH (or THROUGHLINE_UX_BROWSER); no Playwright; missing → "screenshots not rendered: no headless Chrome on PATH".
• changed UI requirement detection — resolved: a per-requirement block hash in index.json; no git-history dependency.
• skill file size — resolved: mechanics in ux.sh tl: blocks; interrogator/rubric rules read from /prd-author, not copied.
• tdd-author refusal needs merged index — resolved: coverage reads the integration-branch blob (best-effort fetch first); an unmerged UX set does not count.
• tokens artifact format — resolved: docs/ux/tokens.css (CSS custom properties), linked by every mock.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NpGG21Y2VGGhTQaFr4oshB