Card Schema

When to invoke

Invoke when other deck skills need schema context, or when the user asks about field semantics, status lifecycle, DoD format, tags, decision gates, or card titling.

Card Schema

The shared vocabulary that makes the deck a contract: defined semantics, enums, and a validator that refuses unknown values. Read-only reference; mutations go through the create-card skill / the advance-card skill / the finish-card skill. The machine-readable schema ships as the sibling schema.yaml.

Deep dives live in reference.md (sibling file in this skill's directory) — read the named section only when needed:

Layout

deck/<title>/             # one dir per card; never moves on state change
  README.md               # frontmatter + dashboard body — latest state
  log.md                  # append-only journal — history, decisions, flow
  reproduce.py, *.html …  # OPTIONAL artifacts, opaque to the engine

Status changes mutate frontmatter, never directories — references survive every transition (artifacts: the create-card skill Step 7).

What goes where (dashboard vs journal)

If the README alone would mislead, update the dashboard; if the value is in the sequence, append to the journal — most operations want both. "Latest finding (DATE)" blocks appended to a README are the antipattern: rewrite in place. Closure does not freeze the card (the finish-card skill "After closure").

Status semantics

blocked is deprecated — split into derived dependency-readiness and the waiting_on overlay (reference.md § Three-axis model). There is no unverified status: that is status: open + tags: [unverified].

Field reference

created / closed_at — timestamps

created at birth; closed_at on every terminal transition, required iff terminal. Two ordering-compatible shapes: ISO 8601 UTC datetime YYYY-MM-DDTHH:MM:SSZ (what the CLI writes) and legacy date-only YYYY-MM-DD. UTC only (reference.md § Timestamps).

summary

Optional free-form, ≤ 3 sentences, what + why (not the fix path), so triage views (goc -v) can prioritize without opening the body. Plain prose; renders inline. Convention, not validator-enforced.

stage

Optional KEP-style maturity ladder for research items: null (the default — no tracking) → alpha → beta → stable. status: done

• stage: alpha is valid; subsequent maturity work files a new card.

contribution

How much does closing this card alone deliver or unlock? high — terminal milestone OR load-bearing infrastructure many cards depend on; medium — improves a working system (optimization, hardening, guard rail); low — editorial polish. The sort composes it across the advances graph (Bellman discount γ=0.7) into the value score driving pull-card.

human_gate

Orthogonal to status: does progress require a human?

• none — autonomous-loop-safe; cron may auto-pick. An agent-checkable external wait is the waiting_on overlay, not a gate.
• decision — ONE human go/no-go. The body MUST already carry a ## Decision required section: reasoning, ≥ 2 named options with pros/cons and a file:line preview, one-line recommendation (reference.md § Decision-gate body contract).
• session — needs an interactive working session.

Pickability: none → next-card picks; decision → session ends cleanly, pointing at the parked card; session → only an interactive session advances. Terminal closes refuse while the gate is raised (goc decide first; reference.md § Gate symmetry). goc new default: decision.

waiting_on / waiting_until — impediment overlay

Stored, orthogonal to status; the exogenous waits the dependency graph cannot derive. waiting_on ∈ external (third party) | resource (person/skill unavailable) | deferred (calendar defer); waiting_until is an optional ISO date (bare date implies deferred). A future date — or a reason with no date — hides the card from --ready / next-card / pull-card and self-clears when it passes; an elapsed date surfaces as WAITING_OVERDUE. Set / clear via goc wait <title> [--reason <r>] [--until <date>] [--clear] (the advance-card skill Step 6).

Ready-to-pull predicate: status == open ∧ human_gate == none ∧ not waiting_impedes(card). An open advances prereq does NOT gate pulling — advisory "awaiting" line only (reference.md § Three-axis model).

worker

Optional free-form assignee: flat string (worker: rodja) or mapping (worker: {who: rodja, where: feature/foo}); unregistered values. Auto-populated at claim time by goc status <title> active; persists after close. Filter with goc --worker <X> or GOC_WORKER.

draft

Boolean overlay marking an unauthored scaffold. goc new stamps it; clears on claim or close, or via goc publish <title>. While set: hidden from queues (visible under --status all, ✎ on the board), protected from supersede/disprove closes, skipped by auto-commit; may not be terminal. Details: reference.md § Draft contract.

advances / advanced_by — value-flow axis

• advances — slugs whose progress this card contributes to ("X advances Y" = closing X delivers a piece of Y's value chain).
• advanced_by — the inverse; slugs contributing to this card.

Invariant: A.advances contains B ⇔ B.advanced_by contains A — maintained atomically by goc advance <title> --by <other> / goc unadvance; half-edges are validator errors; cycles forbidden. Epics are just cards with advanced_by: [children].

Value-chain rule (short form): a true edge means the target is not closeable while the source is open — the advanced-by-closed attest check enforces exactly this. When it fires: wait, or retract a false edge with goc unadvance — never --skip past it (reference.md § Value-chain rule).

Coordinating cards (short form): aggregation epic → child.advances: [epic]; governing cluster (closes when decided) → shared tag, NO edge; epic.advances: [children] is always wrong (BACKWARDS_EPIC_EDGE; reference.md § Coordinating cards).

supersedes / superseded_by — replacement axis

superseded_by — slugs replacing this card (on the old card); supersedes — the inverse (on the new card). goc status <title> superseded --by <successor> maintains both endpoints atomically. Validator-enforced: bidirectional consistency; non-empty superseded_by ⇒ status: superseded; every supersedes entry points at a superseded card. The typed edge is the pointer; the rationale still appends to the old card's log.md (reference.md § Deck as scheduler vs record).

tags — grouping

Canonical-set enforced (below). Soft grouping and governing clusters; one conventional tag per epic-shaped body of work, retired when the epic closes. Lineage is forensic prose for log.md, never frontmatter.

YAML format: non-empty edge lists (advances etc.) render block-style (one - item per line); empty lists inline []; tags stays inline flow style.

Definition of Done (layer 1)

Checkbox list (preferred): - [ ] items mutating to - [x]; goc done requires every box ticked. Detection: ^- \[[ x]\] lines; zero matches → free-form prose mode, which requires goc done --force. Layers 2 (project-wide) and 3 (GoC-wide) are recorded at closure by goc attest (reference.md § DoD layers).

DoD method tags

Declare each item's closure class with a colon-suffixed prefix:

Prefer TDD: whenever a closed-form expected value exists; mislabelling a provable assertion as EMPIRICAL: lets a real failure hide behind "the experiment ran". goc validate warns (UNTAGGED_DOD_ITEM, non-fatal) on untagged boxes in non-terminal cards.

Title antipatterns (rejected at filing time)

Titles ARE the kanban label — a non-engineer reading goc --board must understand each card without opening it. goc new rejects:

On rejection the CLI suggests a rephrasing from the observable problem; the refine-deck skill's quality pass checks the same dimensions across the existing deck.

Canonical tags

Project-specific tags register in .game-of-cards/canonical-tags.md (merged into the enum by goc validate); goc-shipped tags change via PR (reference.md § Adding new tags). A tag is load-bearing iff its row holds; when in doubt, drop it. Every row declares a check:

• state — satisfied out of frontmatter, edges, or card files. Scorable, so a disagreement is a fact.
• judgment — satisfied by what the card means. The row's patterns are recognition aids, never a membership test, so one that does not fire is not evidence the tag fails.

No sweep strips a tag mechanically. Both, plus the default pattern surface: reference.md § Why rows split.

Project-specific predicates appended below:

cat .game-of-cards/canonical-tags.md 2>/dev/null || true

Sibling files on this host

This skill ships reference.md, schema.yaml alongside its body. If a direct file read fails (sandboxed sessions cannot see the plugin install path), fetch the file through the goc tool: {verb: "skill", args: ["card-schema", "<file>"]}.