feat: card staging generalization — precedence staging, entitlement gate, merge records, test extensions (program WS2/S4, engineering slice)

[aarontrowbridge]

Important

Problem — The five worker base cards just landed, but the extension's staging path still knows only the two director cards (a fixed two-file list), and nothing enforces the overlay architecture the agent-cards decision defines: entitlement-gated overlay resolution, interface-field rejection at the merge, provenance merge records, and the dispatch-target validator. The cards exist; the machinery that stages and protects them does not.
Approach — Generalize card staging into precedence staging over every card in the package's agents directory, add the entitlement gate + overlay merge (fixture-driven — the real overlays live in the premium repo and are not part of this slice), write the provenance merge records, and extend the mode-card test suite with the contract-floor, method-body floor, interface-rejection, dispatch-validator, and entitlement-gate tests.
Scope — in: card staging (the staging module + its caller), the deploy-agents operator script's card list, one new/extended test surface, staging receipts · out: overlay content (premium repo), the entitlement provider itself (exists — read it, do not rewrite it), the director cards, the worker card content.

Acceptance Criteria

• Staging covers every card in the package's agents directory (two directors + five workers), replacing the fixed two-file list; the operator deploy script's card list extends to match
• With no entitlement: base cards stage alone — no overlay fields, no missing-target errors (fixture-driven test)
• With entitlement and overlays present: fixture overlays merge method-class fields into base cards; provenance is stamped to a merge record (base card name, base content hash, overlay id, timestamp) — never a merged overlay field
• Interface-class fields are rejected at the merge, table-driven over the full frozen list (output schema, tool permissions, brief/cast grammar, dispatch/cast rules); unclassified field names default-reject
• The dispatch-target validator: every card's dispatch: target resolves against the staged overlay registry when present, and the card validates and stages alone when absent
• Test extensions land: contract-floor per worker card (one test per card — blocklist over banned names AND proprietary strings, output-contract assertion); default-method-body floor per card (four pinned sections, method-class dimension coverage, staging-without-entitlement); interface-rejection (table-driven); dispatch validator; entitlement gate
• The existing suite stays green; the two director cards are byte-untouched

Testing Decisions

Reuse-first: extend the mode-card test file and its staging sibling (the blocklist-loading pattern is the precedent to crib); overlay fixtures live in test fixtures — the interface-rejection test is table-driven over the full freeze list, not a single example.

Key Decisions

• The frozen interface list is the decision of record in the premium bundle's ADR-0003 (agent cards) — the merge implements those lists verbatim as a field classification
• Overlay resolution is fixture-driven in this slice: a configurable overlay source (explicit config → known checkout location → absent), with fixture dirs for the tests; the real overlay content arrives with the premium slice
• Provenance lives in staging receipts (merge records), not in the merged cards

Constraints & Invariants

• The word "conductor" and the blocklist's proprietary strings must not appear in any new code, test, or fixture (tests may reference the blocklist file itself)
• Never stage interface-class fields from an overlay; never write provenance into the staged card; never require the entitlement for base cards to stage
• Read the existing entitlement provider and follow its resolution pattern — do not invent a second one

Prior Art

The staging module (the fixed list to generalize), the mode-card test files (blocklist loading + spine parity patterns), the worker cards' dispatch: fields (the targets to resolve), the entitlement code in the amico-run package (the provider to read), the premium bundle's ADR-0003 (the freeze lists to implement).

Source

Part of the agent-orchestration program — spec-20260903-054637-agent-orchestration (WS2), plan step S4, engineering sub-slice (content sub-slice landed as PR #759).

Notes

Handoff facts from the content slice: the staging list AND the operator deploy script's list are both explicit two-element lists — extend both; the dispatch targets are researcher-tuning, experimenter-tuning, librarian-tuning, engineer-tuning (librarian-tuning covers two cards); the harness schema accepts extra frontmatter keys (they hoist into options — the dispatch field rides there).