card-schemalisted

# Card Schema XP's **system metaphor** (Beck, 1999): a shared vocabulary that lets humans and agents collaborate without re-deriving terms each conversation. Names mean the same thing across every commit, every sub-agent, every /loop iteration. The schema is what makes the deck a **contract** instead of a chat thread — every field has a defined semantics, a defined enum, and a validator that refuses unknown values. Without that contract, frontmatter rots into ad-hoc prose and the deck loses its read-pattern guarantee. This is the read-only reference. Mutations go through `Skill(create-card)`, `Skill(advance-card)`, and `Skill(finish-card)`. The authoritative schema lives in `Skill(card-schema)` frontmatter, which `goc` parses with the same parser it uses for every card's `README.md` — one parser, one mental model. The body of `Skill(card-schema)` is a stub that points here; this file is the canonical explanation. ## Layout ``` deck/ SCHEMA.md # frontmatter IS the schema; body points here README.md # navigation + conventions deck.py # CLI; computes filtered views from frontmatter <title>/ # one dir per card; never moves on state change README.md # frontmatter + dashboard body — latest knowledge + current state log.md # append-only journal — history, details, decisions, flow reproduce.py # OPTIONAL — bug-class executable proof *.html / *.svg