CARD-CONTRACT describes the pre-recompose AgentCard anatomy

Context

apps/agentos/CARD-CONTRACT.md is "the single citable contract for what an agent card renders, from which wire fields, under which render rules." It has been describing an anatomy the component does not have since 2026-07-20.

The card was recomposed to the evolved-D synthesis anatomy (status-first, two-row, actions-in-flow) in 76574e20f3 under #15536. The contract was not touched by that commit, and has since taken three unrelated edits — ac4b089c00, 90de2ce569, e59c7f19e4 — while continuing to document the previous shape. It contains zero mentions of the synthesis / two-row / status-first anatomy.

Filed as its own leaf per the close-target remediation split: PR #16044 delivers this correction, and #15536's AC11 also names "and #14618 baselines", a limb owned by a separate deferred ticket. Rather than re-scope another author's ACs, this leaf carries exactly what the PR delivers.

The Problem

The contract's own opening names its consumers: "the AgentCard implementation … the detail header (#14608), and every surface that renders a resident at card grain." Two concrete readers are misled:

1. anyone building a new card-grain surface builds the old anatomy;
2. #14618 (FM cockpit visual-regression baseline harness) must encode some composition, and this document is what says which.

The second is the expensive one. A baseline harness does not merely record an anatomy — it makes that anatomy the ground truth every future diff is judged against, so the failure surfaces as a flood of false positives on correct changes, blaming everyone else. Nothing was captured against the stale contract only because #14618 is deferred from v13.2; the window opened and closed with no one inside it.

The contract closes with "Deltas from this contract are recorded design decisions on tickets — never silent drift." This was silent drift, in the document that forbids it.

The Architectural Reality

• apps/agentos/view/fleet/AgentCard.mjs is the authority for behaviour; design/agentcard-rebaseline-d.html is the authority for intent. The contract must be corrected against the component, since the mockup cannot state degrade rules.
• Elements the recompose introduced and the field table never had: profile avatar, the name drill as the sole disclosure route, the throttle/wake telltale, the control-status line, and the source strip.
• The Foot meta row describes an element that no longer exists (grep foot on the component returns nothing); the source strip replaced it.
• The Controls slot row describes a slot where the component now renders actions in flow.
• Two behaviours the contract never carried: the lane's head+tail middle elision, and that every lane fragment is an inert text node rather than html (remote fleet data through Neo's innerHTML-backed vdom).
• The conformance checklist claims a 1:1 mapping to the #14598 spec suite; entries added for the new elements are not in that suite, so the claim must be scoped rather than extended.

The Fix

Correct apps/agentos/CARD-CONTRACT.md against the component:

1. Remove the Foot meta row; add the source strip with its role=status and level-colours-the-dot rules.
2. Replace the Controls slot row with control-verbs-in-flow (both verbs at every width, no overflow menu, toggle icon derived from state).
3. Add rows for profile avatar, name drill, telltale, and control status — each degrade rule read off the implementation, never inferred. Specifically: the drill is unconditional (no absent-detail branch exists), and controlReason is producer-required as {action, kind, reason} with two kind-keyed branches (timeout, and the general ⚠ kind: reason) and no missing-field fallback.
4. Document the lane's elision mechanism and its text-node-not-html requirement.
5. Split the conformance checklist into the entries genuinely mapped 1:1 to #14598 and the additions that are not yet mapped, so the document never claims coverage it lacks.
6. Record anatomy provenance: which mockup the table describes, and that the document lagged the recompose.

Acceptance Criteria

• The field table contains no row describing a non-existent element, and no degrade rule that the component does not implement.
• Every element the evolved-D recompose introduced has a row with a degrade rule traceable to a line in AgentCard.mjs.
• The conformance checklist's 1:1 claim covers only entries with an actual spec witness; unmapped additions are labelled as such.
• The document records which anatomy it describes and that it previously lagged the component.
• Post-merge: #14618's pre-capture gate points at this contract before any baseline is captured (already recorded in that ticket's body).

Out of Scope

Writing the specs for the not-yet-mapped conformance entries; capturing #14618's baselines; any change to AgentCard.mjs itself — the component is correct and the document was wrong.

Avoided Traps

Correcting against the mockup rather than the component. The mockup states intent and cannot state degrade rules, so a mockup-derived contract invents the branches it cannot see. Reviewer @neo-gpt caught exactly this in the first attempt: two degrade rules were invented (an absent-detail branch for an unconditional drill, and a missing-kind fallback that does not exist) while a real kind === 'timeout' branch went undocumented. Read the component's branches; do not imagine its failure modes.

Extending the 1:1 checklist claim instead of scoping it. Adding aspirational entries under a header asserting spec parity makes the document claim coverage it does not have — the same defect class as the stale anatomy, one layer up.

Decision Record impact

none — aligned with ADR 0032 (institution-cockpit render model) and ADR 0029 §2.6 (cards are layout-blind); this leaf changes documentation only and introduces no ADR surface.

Related

#15536 (the recompose whose AC11 first limb this delivers; stays open for the #14618 baseline limb) · #14618 (baseline harness — deferred; carries the pre-capture gate) · #14605 (the contract's origin) · #14598 (the spec suite the checklist maps to) · #15562 (preserved rejected directions) · PR #16044 (delivers this) · epic #14560.

Origin Session ID: f1bcb0a9-68f5-4910-bef6-1a5a33aad1f5 Retrieval Hint: query_raw_memories("CARD-CONTRACT stale anatomy evolved-D recompose degrade rules read off component")

Live latest-open sweep: checked latest 20 open issues at 2026-07-27T07:55Z plus a title/body search for CARD-CONTRACT; nearest candidates #15536 and #14618 are the two limbs this leaf splits from, and #14805 is the design-conformance epic rather than this document. No equivalent found.

Authored by Vega (@neo-opus-vega, Claude Opus 5, Claude Code)

🌿