<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-26-1-done-judges-every-issue-matrix-row/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-26-1-done-judges-every-issue-matrix-row/</id>
  <title>ADR: at done, every issue-matrix row is judged, cited or not</title>
  <updated>2026-10-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-26-1-done-judges-every-issue-matrix-row/"/>
  <summary>At done the verdict decides resolution for every issue-matrix row; a present matrix is judged whole even with zero gating references, and a missing one is nothing to enforce.</summary>
  <content type="html">&lt;h2 id=&quot;at-done-every-issue-matrix-row-is-judged-cited-or-not&quot;&gt;At &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, every issue-matrix row is judged, cited or not&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-26). Operator rulings of 2026-10-26, recorded on #6653.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-26&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;#6653 (an uncited &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; row lands with exit 0).&lt;/li&gt;
&lt;li&gt;#4943 and PR #5222 (the &lt;code dir=&quot;auto&quot;&gt;issue_matrix_verdict_terminality&lt;/code&gt; merge gate, and its zero-reference early return, #5222 F1).&lt;/li&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;issue-matrix-terminality-all-rows-01M5X1ZJ&lt;/code&gt;; research in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/issue-matrix-terminality-all-rows-01M5X1ZJ/research.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Decisions &lt;code dir=&quot;auto&quot;&gt;01M5X206M989YE99MA0KHRFTNP&lt;/code&gt; (judge the whole matrix) and &lt;code dir=&quot;auto&quot;&gt;01M5X498X3ATTAB12KQWMDPZRV&lt;/code&gt; (a typed &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_NOT_AUTHORED&lt;/code&gt; code on the existing reader).&lt;/li&gt;
&lt;li&gt;It refines &lt;a href=&quot;/adr/3.x/2026-09-20-1-issue-matrix-not-applicable-verdict/&quot;&gt;ADR 2026-09-20-1&lt;/a&gt;: classification still decides which rows are required.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The issue-matrix has two levers. &lt;strong&gt;Classification&lt;/strong&gt; decides whether a row is required. &lt;strong&gt;Verdict&lt;/strong&gt; decides whether an existing row is resolved. The &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; check mixed them up in two places:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;_issue_matrix_in_mission_rows&lt;/code&gt; kept an &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; row only when its issue was a discovered gating reference. A row whose issue was not cited, was cited only as context (&lt;code dir=&quot;auto&quot;&gt;see #12&lt;/code&gt;), was a one-digit reference the detector skips, or was recorded with &lt;code dir=&quot;auto&quot;&gt;agent issue-verdict&lt;/code&gt; alone, was dropped before the &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; check.&lt;/li&gt;
&lt;li&gt;With zero gating references, both the blocker and the terminality gate returned before reading the matrix at all (“No gating issue references discovered — nothing to enforce”).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;So a Mission whose own matrix said it still owed a fix could be consolidated, or moved to &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, with exit 0. The gate’s PASS line, “No unresolved (in-mission/unknown) issue-matrix rows”, described rows it never looked at.&lt;/p&gt;
&lt;p&gt;The zero-reference early return existed for a reason (#5222 F1): a coordination Mission that never authored a matrix must not fail on a coordination probe for a file that was never written. Before this decision, the post-consolidation ref read could not tell “no matrix at a valid ref” from “the probe failed”.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;1-at-done-the-verdict-decides-resolution-for-every-existing-row&quot;&gt;1. At &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, the verdict decides resolution for every existing row&lt;/h3&gt;
&lt;p&gt;Every &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; row blocks at &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;block&lt;/code&gt; mode and warns in &lt;code dir=&quot;auto&quot;&gt;warn&lt;/code&gt; mode, whether or not its issue is cited. This applies to &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt; (the terminality gate) and to &lt;code dir=&quot;auto&quot;&gt;move-task --to done&lt;/code&gt;, which call the same blocker. Classification still decides which rows are &lt;strong&gt;required&lt;/strong&gt;: the completeness gate and the “missing rows” list are unchanged.&lt;/p&gt;
&lt;h3 id=&quot;2-a-present-matrix-is-judged-whole-even-with-zero-gating-references&quot;&gt;2. A present matrix is judged whole, even with zero gating references&lt;/h3&gt;
&lt;p&gt;With zero gating references, a matrix that exists is still judged at &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;: row diagnostics (malformed rows, unknown verdicts) and &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; rows both count as unresolved. Judging only &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; rows would keep a PASS that claims rows nobody checked.&lt;/p&gt;
&lt;h3 id=&quot;3-a-missing-matrix-is-still-nothing-to-enforce&quot;&gt;3. A missing matrix is still nothing to enforce&lt;/h3&gt;
&lt;p&gt;A Mission with zero gating references and no matrix passes, so #5222 F1 holds. “Missing” is a positive fact, never an inferred one:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;for a coord-less Mission, or a materialized coordination worktree, the matrix file is absent from that directory;&lt;/li&gt;
&lt;li&gt;after consolidation, the coordination ref is valid and neither &lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt; nor &lt;code dir=&quot;auto&quot;&gt;issue-matrix.md&lt;/code&gt; is in its tree. The reader reports this with its own code, &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_NOT_AUTHORED&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;4-issue_matrix_not_authored-means-nothing-to-enforce-only-without-gating-references&quot;&gt;4. &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_NOT_AUTHORED&lt;/code&gt; means “nothing to enforce” only without gating references&lt;/h3&gt;
&lt;p&gt;The terminality gate accepts &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_NOT_AUTHORED&lt;/code&gt; as a PASS only when the Mission has zero gating references. With gating references it stays a FAIL, as before. Every other read error (&lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_REF_ABSENT&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_PROBE_ERROR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_EMPTY_CONTENT&lt;/code&gt;) fails closed on every path.&lt;/p&gt;
&lt;p&gt;This now includes a Mission with zero gating references. One case reaches it in practice: running &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; again after a finished run tore the coordination branch down. The read ref is then the deleted coordination branch, so the gate reports &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_REF_ABSENT&lt;/code&gt; and FAILs, where the old early return passed. That is an accepted FAIL. The gate runs before any mutation, so an ordinary run never reaches it, and a Mission with gating references already failed the same way.&lt;/p&gt;
&lt;h3 id=&quot;5-a-pass-says-what-it-judged&quot;&gt;5. A PASS says what it judged&lt;/h3&gt;
&lt;p&gt;The PASS detail names the number of rows judged (“No unresolved (in-mission/unknown) rows among N issue-matrix row(s)”), or says “No issue-matrix authored and no gating issue references — nothing to enforce”.&lt;/p&gt;
&lt;h3 id=&quot;6-approved-is-unchanged&quot;&gt;6. &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; is unchanged&lt;/h3&gt;
&lt;p&gt;An &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; row is still accepted at &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, and a Mission with zero gating references still never needs a matrix to be approved.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A Mission cannot land while its own matrix says it still owes a fix.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;move-task --to done&lt;/code&gt; enforce one rule through one blocker.&lt;/li&gt;
&lt;li&gt;The gate output no longer overclaims.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Accepted behaviour change (C-005).&lt;/strong&gt; A Mission that passes today can be refused in &lt;code dir=&quot;auto&quot;&gt;block&lt;/code&gt; mode, or warned in &lt;code dir=&quot;auto&quot;&gt;warn&lt;/code&gt; mode, at consolidation and at &lt;code dir=&quot;auto&quot;&gt;move-task --to done&lt;/code&gt;. The remedy is to record a terminal verdict for the row with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent issue-verdict&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A zero-reference coordination Mission now reads its coordination ref at the terminality gate. A deleted ref, an unreadable object, an empty matrix or any other resolution error there now FAILs where the old early return passed. That is the fail-closed rule of NFR-002.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The completeness gate keeps its zero-reference early return.&lt;/li&gt;
&lt;li&gt;The compat names &lt;code dir=&quot;auto&quot;&gt;_issue_matrix_approval_blocker&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_issue_matrix_evaluation&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_issue_matrix_in_mission_rows&lt;/code&gt; keep their names and signatures.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Judge only &lt;code dir=&quot;auto&quot;&gt;in-mission&lt;/code&gt; rows with zero references, with a narrower PASS text.&lt;/strong&gt; Rejected by the operator (Decision &lt;code dir=&quot;auto&quot;&gt;01M5X206M989YE99MA0KHRFTNP&lt;/code&gt;): the PASS would still have to describe which rows it did not check, and a malformed row would land unseen.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A separate &lt;code dir=&quot;auto&quot;&gt;issue_matrix_present()&lt;/code&gt; probe in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;.&lt;/strong&gt; Rejected (Decision &lt;code dir=&quot;auto&quot;&gt;01M5X498X3ATTAB12KQWMDPZRV&lt;/code&gt;): it is a second entry point that repeats the ref and lifecycle-phase resolution. The typed code on the one reader keeps a single read authority.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/issue-matrix-verdicts/#what-done-enforces&quot;&gt;Issue-Matrix Verdict Reference: What &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; enforces&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tasks/issue_matrix_approval.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_issue_matrix_approval_blocker&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;issue_matrix_done_outcome&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/policy/merge_gates.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_evaluate_issue_matrix_verdict_terminality_gate&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;read_issue_matrix_ref_content&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX_NOT_AUTHORED&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
