core/docs/assessment/03-card-schema.md

Phase 1 — The Card Schema

Executor: Fable 5, 2026-07-27. Companion: 02-layer-taxonomy.md. Applies to: every card written in Phases 2 (10-layer-cards/) and 3 (20-component-cards/), and every claim consumed by Phase 4's registers.

This is D2 executed: the system map's 17-field node schema and 7-value liveness vocabulary are extended, not replaced. The map's vocabulary encodes distinctions it earned over 205 subsystems — serving vs merely-executing, never-built vs built-and-disconnected, research that returned a negative result. What it lacks are the four dimensions Phase 0 measured as missing: evidence, capacity, design-vs-build, fitness. Those arrive as orthogonal fields, not fatter enums.

---

1. Design principles

P1 — Orthogonal axes, not fatter enums. Liveness answers "is it running?"; fitness answers "should it be?" These are independent. The governing example: ADR-0252 condemns the 34 surface organs while ruling they keep serving until a proven replacement exists — liveness live-serving, fitness superseded-in-place. A single merged status could not express that state, and that state is load-bearing. The same separation holds for design (what documents articulate) versus build (what code does): a component can be fully designed and unbuilt (L11 process), or built with no surviving design authority (fragments of allocation physics).

P2 — Evidence or it is a claim. Every live-serving / live-internal verdict requires at least one evidence pointer that would fail if the mechanism were deleted (the sabotage test). Evidence that would look identical with the mechanism absent is decoration and does not count toward liveness — this repository has produced exactly that failure (g_args_rate was 0.0 while prose claimed the reader read it). A card may cite decoration, but must label it as such.

P3 — Stamped verification. Every card carries verified_at: the commit SHA actually inspected and the date. A claim inherited from the 2026-06-09 system map without re-verification is written as claimed (map 2026-06-09), never as fact. Staleness must be visible on the card, not discoverable by archaeology.

P4 — Pins must run. An invariant "enforced by a test" is only enforced if the pin lives in a suite that executes (a pin registered in no suite never runs). Citing a pin requires naming its suite and confirming the suite's membership count moved when the pin was added, or that the suite demonstrably collects it today.

P5 — Identity, not value. When a card asserts two things are the same mechanism (shared, not duplicated), the evidence must be identity-grade (same object, same call path), not equal-looking values or name-greps.

---

2. Field specification

2.1 Identity block

Field	Req	Notes
id	✓	Stable slug; zones keep their map zone_id unchanged for greppability
kind	✓	layer | zone | component
parent	✓	Containment: component → zone → macro layer (per taxonomy §4)
verified_at	✓	<SHA> (<date>) — the tree actually inspected (P3)
assessor	✓	Who filled the card

2.2 Teleology block (the "philosophical understanding" dimension)

Field	Req	Notes
philosophical_intent	✓	What this element is for in the cognitive model — one paragraph, teleological, answerable to the north star. Distinct from what_it_does. If no document states an intent, write undetermined — that is itself a finding
telos_stages	✓	Stages served, from the ratified vocabulary; candidate functions cited as candidate:CR-n, never bare
macro_role	✓	Kept from map: the element's role in its layer's story

2.3 Description & contract block (kept from the map — its strongest part)

Field	Req	Notes
what_it_is / what_it_does	✓	As in the map: essence vs behavior, in prose
inputs / outputs	✓	Typed where the code types them
invariants	✓	Each entry: the invariant, its enforcement pin, and the suite that runs the pin (P4). An invariant with no running pin is recorded with enforcement none — a finding, not a formality
topology_role	✓	The AGENTS.md repository-topology classification (runtime boundary / candidate compiler / reviewed data / read-only projection / demo envelope / benchmark artifact / historical note / tooling) — replaces the map's classification

2.4 Design-vs-build block (new — the design/implementation split Shay asked for)

Field	Req	Notes
design_state	✓	Where the design is articulated (doc/ADR + status) and its one-paragraph summary. none if the code has no surviving design authority
build_state.liveness	✓	The 7-value vocabulary, unchanged: live-serving → live-internal → partial-wiring-debt → spike → inert → unbuilt → research-negative
build_state.key_files	✓	Kept from map
build_state.evidence[]	✓	See §3.2 — the field P2 is about

2.5 Capacity block (new — "to what capacity" now has a field)

Field	Req	Notes
capacity.designed	✓	The envelope the design claims (e.g. "any clause the grammar owns")
capacity.measured	✓	The envelope evidence supports, with numbers (e.g. "reader comprehends 19 constructions; writer emits 1739; overlap 6"; "16-premise cap holds a band to ≤16 entailed cases")
capacity.ceilings	✓	Known hard limits and what imposes them (unknown is a legal and honest value)

2.6 Dependency & provenance block

Field	Req	Notes
relationships	✓	Kept: typed edges (feeds / reads / depends-on / verifies / …)
owning_adrs	✓	Kept; extended to include governing analysis/ratification docs with dates

2.7 Judgment block (new — feeds Phase 4)

Field	Req	Notes
fitness.verdict	✓	See §3.3
fitness.rationale	✓	Why — with evidence pointers. undetermined requires naming what evidence would determine it
honest_wrinkles	✓	Kept from the map, deliberately: what is true about this element that its labels would otherwise hide
open_questions	○	Questions the card raises but cannot answer; each tagged with who can (Phase 3 / Phase 4 / ruling)

2.8 Layer cards only

Field	Req	Notes
stage_coverage	✓	For each telos_stage the layer claims: covered / claimed-only / uncovered, with the evidence that decides it (taxonomy §6)
zone_roster	✓	The layer's zones from taxonomy §4, with re-verified liveness
rollup_note	✓	Mandatory restatement: zone liveness is weakest-link; the subsystem-level picture; never a completion rate

---

3. Vocabularies

3.1 Liveness (unchanged, 7 values, ordered)

live-serving · live-internal · partial-wiring-debt · spike · inert · unbuilt · research-negative

research-negative is knowledge, not failure — a mechanism investigated and honestly refuted (field-wedge). Do not "clean it up" into inert.

3.2 Evidence entry shape

{ claim, kind: test | lane | pin | acceptance-packet | measurement | code-read,
  pointer: <path or doc + location>,
  would_fail_if_absent: yes | no | unknown }

Only would_fail_if_absent: yes counts toward liveness (P2). code-read is legitimate evidence for existence and wiring (per the read-the-code doctrine) but never for behavior — behavior needs a test, lane, or measurement.

3.3 Fitness (new, 6 values)

Verdict	Meaning
fit	Right mechanism, right owner, serving its intent
strained	Right place, but shape or capacity no longer matches the load (e.g. an index that stopped scaling)
misplaced	Sound mechanism, wrong owner — belongs to another layer/component whose design parameters (possibly extended) suit it
wrong-solution	The mechanism does not serve the underlying problem; a different approach is needed
superseded-in-place	Condemned by ruling but deliberately still serving until a proven replacement exists
undetermined	Not yet judged — must name the deciding evidence

misplaced and wrong-solution entries are the direct feed for Phase 4's hindrance audit (31-hindrance-audit.md); every such verdict must name its evidence and its proposed better home — and decides nothing (rulings are Shay's).

---

4. Card template

# <id> — <name>

**Kind:** <layer|zone|component> · **Parent:** <parent> · **Assessor:** <who>
**Verified at:** `<SHA>` (<date>)
**Liveness:** `<value>` · **Fitness:** `<verdict>` · **Topology role:** <role>

> <philosophical_intent — one paragraph>

**Telos stages:** <stages; candidates as candidate:CR-n>
**Macro role:** <one line>

## What it is / What it does
<prose, two short paragraphs>

## Contract
- Inputs: …
- Outputs: …
- Invariants: <invariant> — pin: <test> — suite: <suite> — status: <running|none>

## Design vs build
- Design: <doc/ADR + status> — <summary or `none`>
- Build: <liveness>; key files: …
- Evidence:
  - <claim> — <kind> — <pointer> — would-fail-if-absent: <yes|no|unknown>

## Capacity
- Designed: … · Measured: … · Ceilings: …

## Dependencies & provenance
- Relationships: …
- Owning ADRs / governing docs: …

## Judgment
- Fitness rationale: …
- Honest wrinkles: …
- Open questions: … (→ Phase 3 / Phase 4 / ruling)

Layer cards append the stage_coverage table, zone_roster, and rollup_note (§2.8).

---

5. Anti-patterns (each has already occurred in this repository's history)

1. Exists ≠ live. A module's presence proves nothing about execution. (Dormant readback rules; explain.py.)
2. Threaded ≠ behavioral. A flag reaching a call site is not the flag changing output; pair every wiring claim with a behavior sweep. (The ignored-flag lesson.)
3. Green ≠ meaningful. A measurement that would look identical with the mechanism removed measures nothing. (g_args_rate = 0.0.)
4. Pinned ≠ enforced. A pin in no suite never runs; check the count moved. (The suite-membership lesson.)
5. Documented ≠ true. Roughly a third of a plausible external blueprint was falsified by reading the code (Finding 0-G). Documents are testimony; code is evidence.
6. Zone label ≠ completion rate. Weakest-link rollups understate; quoting them as progress metrics misleads in both directions.
7. Acceptance ≠ comprehension. Never quote an acceptance metric without its identity metric; use faithful / fabricating / refused — never two buckets.

---

6. Depth allocation for Phase 3

Full-depth descent (every component gets a full card): serving-path truth behavior (M4 + the M3 serve seam), the two-grammars frontier and the four ⚑ zero-subsystem zones, the learning boundary (M5's INV regime), M6's built footings and unbuilt center, and everything carrying a fitness verdict other than fit.

Cite-and-summarize (short card pointing at the acceptance packet): closed arcs with ratified acceptance evidence (deduction bands v1–v6, cohesion ADR-0241/0242, GSM8K sealed-lane machinery), unless Phase 2 surfaces a contradiction — in which case they promote to full depth.

The rule's purpose is honesty about attention, not economy for its own sake: a short card must say why it is short and what would reopen it.