Spec Sub-Spec: decision-card-surface
This sub-spec is part of the spec.md product contract. SSOT order is spec.md core > docs/spec/* sub-specs > Plans.md.
Decision Card Surface Contract
Decision Cards surface human judgment during breezing with structured options, impact scoring, and optional past-decision context from harness-mem search. This contract productizes Phase 95 Decision Card UI and mem read layer on top of Breezing Brief Contract (judgment-card.v1 v0 issuance rules) and Tri-Tool Parallel Collaboration Contract (runtime hard floor precedence).
judgment-card.v1 v1 extension
Schema: templates/schemas/judgment-card.v1.json. v1 retains all v0 required fields (question, options, recommendation, confidence, impact, diff_summary) and adds:
| Field | Shape | Constraints |
|---|---|---|
impact_score | integer | 0–100 inclusive |
similar_past_decisions | array | max 3 items; each \{summary, decision, outcome, decided_at, mem_id\} (all non-empty strings) |
impact_score combines (i) worktree-fingerprint impact (changed file count and line magnitude within the task worktree) and (ii) distance from the five-category runtime hard floor (Phase 92.2.1). When any hard-floor category matches, impact_score is 100; otherwise it scales 0–99 from fingerprint impact alone.
v0 card JSON without v1 fields validates as v1 (backward compatible input).
Past decision reference accuracy
When harness-mem is configured and reachable, Decision Card population calls harness_mem_search (or equivalent HTTP search) and returns exactly up to three past decisions ranked by similarity score (highest first). Each similar_past_decisions[] entry carries the matched observation summary, recorded decision, known outcome, decided_at, and source mem_id.
When mem is not-configured or unreachable, similar_past_decisions is an empty array (fail-open — card issuance continues without past context).
Floor precedence over judgment cards
The five-category runtime action hard floor (Phase 92.2.1; money/billing, external send/egress, credential/secret read, production deploy/publish, destruction outside the task worktree) always takes precedence over Decision Card surfaces:
- When any hard-floor category matches, Harness hard-stops for the human, sets
impact_score=100, does not issue a judgment card, and surfacesHARD_STOPonly. - Judgment cards apply only to non-floor ambiguity (DoD interpretation, scope, trade-offs) — same rule as Breezing Brief Contract floor precedence.
- The pre-merge policy gate (
go/internal/floor) and runtime hard floor remain distinct.
Fail-open memory behavior (Decision Card read layer)
Brief Composer, Triad Dispatcher (scripts/resolve-impl-backend.sh evolution), and Decision Card render paths that call harness-mem for read/search must follow the same fail-open tri-state model:
| State | Behavior |
|---|---|
not-configured | Silent skip — proceed with empty similar_past_decisions |
unreachable | One stderr warning line (breezing-mem: or component prefix), then continue |
Mem read state never blocks brief confirmation, worker dispatch, judgment card render, or aggregation.