Contracts

issue-matrix-read.md

Contract: Coordination-aware issue-matrix read

Behavioral contract (not HTTP) for the read authority that every issue-matrix consumer routes through. Backed by ATDD tests; each MUST-clause names its witnessing scenario.

Inputs

  • repo_root, mission_slug
  • kind = MissionArtifactKind.ISSUE_MATRIX
  • topology (from meta.json), coordination branch name (when applicable)

Guarantees

1. Discovery/verdict partition split — reference discovery reads the PRIMARY partition (always a directory); matrix verdicts read the matrix's owning partition, which on coord topology is a different source. That source is a directory when the coordination worktree is materialized and branch-ref content (git show <ref>:<path>, no on-disk dir) when it is unmaterialized-but-retained — so the read authority yields matrix content, not only a Path. Readers accept a content source (IC-01b), not only a directory. (FR-001, FR-003, FR-004, FR-005; witnessed: US1.1/1.3, US2.1/2.2/2.3/2.4, US4.1/4.2) 2. Branch-flat unchanged — on single_branch/lanes the matrix resolves to PRIMARY; behavior is byte-for-byte identical to today. (US1.3, US2.4 parity) 3. Post-consolidation read via the write's phase authority — when the artifact has no on-disk worktree, the read surface is chosen by the SAME lifecycle-phase authority the write uses (resolve_lifecycle_phase): PUBLISHED ⇒ consolidated-primary ref; CONSOLIDATED/PRE_CONSOLIDATION on coord topology ⇒ coordination branch ref. Content is read from the resolved ref (git show <ref>:<path>, existence via git rev-parse --verify). The read never hardcodes a surface, so it cannot diverge from where the write landed. (FR-005; witnessed: US4.1, US4.2) 4. Fail closed — the read REFUSES (raises / returns a typed refusal), never falling back to PRIMARY residue or passing vacuously, when:

(FR-007, NFR-002) 5. Positive controls — for each refusal clause a same-fixture positive assertion proves the read returns the verdict when present (non-empty set → resolves; probe ok → reads fixed). (US4.4/4.5) 6. Performance — resolution completes within the CLI <2s bar on the NFR-003 fixture (10 issues / 25 rows); the branch-ref read adds no measurable overhead vs the worktree read. (NFR-003)

  • the coordination ref is absent (deleted) — US4.3;
  • the content probe errors — US4.5 negative;
  • the authored set is empty while gating references exist — US4.4 negative.

Non-goals

  • No second resolver authority; extends the existing seam in src/mission_runtime/resolution.py.
  • No change to verdict semantics or the canonical verdict vocabulary.

merge-verdict-terminality.md

Contract: Merge verdict-terminality enforcement

Behavioral contract for the merge path applying the terminal-verdict rule (FR-006), mirroring tasks_move_task.py::_issue_matrix_approval_blocker. Backed by ATDD tests.

Trigger

spec-kitty merge recording work packages done / advancing the target, on any topology.

Guarantees

1. Block mode — with policy.merge_gates.mode: block, if any gating row is non-terminal (in-mission or unknown), merge REFUSES before the target advances and names the offending row(s). (US3.1) 2. Warn mode — with mode: warn, merge still advances and records the work packages done, but prints the same unresolved-row list the done transition prints. The change from today is the surfaced warning, not a changed landing outcome under warn. (US3.2) 3. Positive control — the same mission with the row resolved to a terminal verdict advances in either mode with no verdict-terminality complaint. (US3.3) 4. Correct partition — the verdict read that feeds this rule resolves from the COORD partition / branch ref (per the issue-matrix-read contract), including post-consolidation; it never reads the PRIMARY residue. (FR-004, FR-005; witnessed US4.2) 5. Rule reuse — the terminality classification is the existing one (unknown/in-mission non-terminal; fixed/verified-already-fixed/deferred-with-followup/not-applicable terminal); merge does not re-define verdict semantics.

Failure modes closed

issue-matrix-read contract's partition split).

  • Merge landing a mission whose gating row is still in-mission with exit 0 (the #4943 leg-2 bug).
  • The coord husk read making the gate see "nothing to enforce" (the #4943 leg-1 bug — closed by the