feat(skill): pre-draw checkpoint, docs-sync gate, packaged self-check, ADRs

- SKILL.md: confirm type/pattern/size/cuts with the user before rendering;
  checklist hooks for the checkpoint and the packaged self-check
- scripts/verify-docs-sync.py: CI now fails when the frontmatter description
  loses a type's lexical hook, the gallery can't reach a shipped example, or
  the README tree names a missing file
- skills/diagram-design/scripts/self_check.py: distilled output checker that
  ships with the skill so installed agents can verify their own diagrams;
  adversarial suite in scripts/test-self-check.py
- assets/index.html: six new tabs (OAuth sequence + five single-variant
  examples with a data-single variant lock) so every shipped example is
  browsable
- docs/adr/0001-0004: settled policies recorded (pinned controller, taxonomy
  freeze, reveal-only autoplay, byte cap + trigger-rich description)
- README: It's-working-if section, new gates documented; CONTRIBUTING: gate
  table, ADR guidance, type-addition invariants; CI: two new steps
This commit is contained in:
Cathryn Lavery
2026-08-12 17:00:08 -07:00
parent 8a6623ad88
commit dbc4abd965
12 changed files with 804 additions and 5 deletions
@@ -0,0 +1,16 @@
# ADR 0003 — `reveal` is the only sanctioned autoplay
**Status:** accepted (v2.3, clarified after review)
## Context
The motion contract lists "autoplay on load" as an anti-pattern, yet the canonical controller starts a `reveal` run on load. Early drafts of `animation.md` stated both without reconciling them, which reads as a contradiction to anyone copying the template.
## Decision
`reveal` mode may run **once** on initial load — it exists for short ordered explanations where a click-to-start would be friction — and then remains complete. It never restarts on viewport re-entry, tab return, or without an explicit Replay action. Every other mode is user-initiated (`step`) or CSS-scoped (`loop`); `none` stays inert. Under `prefers-reduced-motion: reduce` and without JavaScript, all modes show the complete static frame.
## Consequences
- The anti-pattern is precisely "repeated or attention-trapping autoplay," not "any motion before interaction."
- `verify-motion.py` needs no autoplay heuristic: the pinned controller is the only code that can start a run, and it implements exactly this policy.