/ERROR_CODES

Mission-Review Error & Warning Codes

> **Source of truth**: `src/specify_cli/cli/commands/review/_diagnostics.py` > (StrEnum class `MissionReviewDiagnostic`). > This file is a hand-maintained mirror. Until #645's code-to-docs flow exists, > the StrEnum members and this file's section count must match per NFR-008.

---

MODE_MISMATCH

**Code**: `MISSION_REVIEW_MODE_MISMATCH`

**When it fires**: `--mode post-merge` was requested but `meta.json.baseline_merge_commit` is absent, meaning the mission has not been merged via `spec-kitty merge`.

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Run `spec-kitty merge` to merge the mission and record the baseline commit, then retry `spec-kitty review --mode post-merge`. 2. Re-run with `--mode lightweight` to perform a consistency check without the full post-merge gate requirements. 3. For pre-083 missions already merged but lacking `baseline_merge_commit`, run `spec-kitty migrate backfill-identity` to backfill missing identity fields, which will also record the baseline merge commit if available.

**Body example**:

MISSION_REVIEW_MODE_MISMATCH: --mode post-merge was requested but meta.json.baseline_merge_commit is absent.

---

ISSUE_MATRIX_MISSING

**Code**: `MISSION_REVIEW_ISSUE_MATRIX_MISSING`

**When it fires**: The `issue-matrix.md` file is not present in the mission's `kitty-specs/<slug>/` directory when running in post-merge mode, or the file contains no Markdown table.

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Create `kitty-specs/<slug>/issue-matrix.md` with mandatory columns `issue`, `verdict`, and `evidence_ref`. 2. Populate one row per GitHub issue in scope with a valid verdict from the allow-list: `fixed`, `verified-already-fixed`, `deferred-with-followup`, or `in-mission`. 3. If running a lightweight consistency check, use `--mode lightweight` to bypass the issue-matrix requirement.

**Body example**:

MISSION_REVIEW_ISSUE_MATRIX_MISSING: issue-matrix.md is required in post-merge mode

---

ISSUE_MATRIX_SCHEMA_DRIFT

**Code**: `MISSION_REVIEW_ISSUE_MATRIX_SCHEMA_DRIFT`

**When it fires**: An `issue-matrix.md` file uses column headers outside the canonical mandatory + named-optional vocabulary, or mandatory columns are missing or out of order.

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Ensure mandatory columns are present in order: `issue`, `verdict`, `evidence_ref`. 2. Replace any unknown columns with named-optional columns from the canonical set: `title`, `scope`, `wp`, `fr`, `nfr`, `sc`, `repo`. 3. Apply canonical aliases: `theme` → `scope`, `wp_id` → `wp`, `fr(s)` → `fr`, `nfr(s)` → `nfr`, `evidence ref` → `evidence_ref`.

**Body example**:

MISSION_REVIEW_ISSUE_MATRIX_SCHEMA_DRIFT: Unknown column(s) not in mandatory or named-optional vocabulary: Severity

---

ISSUE_MATRIX_VERDICT_UNKNOWN

**Code**: `MISSION_REVIEW_ISSUE_MATRIX_VERDICT_UNKNOWN`

**When it fires**: A verdict cell value in `issue-matrix.md` is not in the closed-set allow-list (`fixed`, `verified-already-fixed`, `deferred-with-followup`, `in-mission`).

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Replace the unknown verdict with one of: `fixed`, `verified-already-fixed`, `deferred-with-followup`, or `in-mission`. 2. `deferred` (without `-with-followup`) is not valid; use `deferred-with-followup` and add a follow-up handle to `evidence_ref`. 3. `in-mission` declares the issue is being closed by a later WP in *this* mission. It is accepted at per-WP `approved`, but is rejected on the `done` transition (mission merge) — resolve it to a terminal verdict (`fixed` / `verified-already-fixed` / `deferred-with-followup`) before the mission lands. 4. Backtick-quoted verdicts (`` `fixed` ``) are accepted; the backticks are stripped during parsing.

**Body example**:

MISSION_REVIEW_ISSUE_MATRIX_VERDICT_UNKNOWN: Row for issue '#123': verdict 'deferred' is not in the allowed set

---

ISSUE_MATRIX_MULTI_TABLE

**Code**: `MISSION_REVIEW_ISSUE_MATRIX_MULTI_TABLE`

**When it fires**: `issue-matrix.md` contains more than one Markdown table at the top level. The schema requires exactly one table (additional prose sections are allowed).

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Consolidate all issue rows into a single Markdown table. 2. Move summary aggregation (e.g., verdict counts) to a prose section below the table, not a second table. 3. If the file was authored with separate product-findings / workflow-papercuts / pre-existing-failures tables, merge them into one table with an optional `scope` column to distinguish categories.

**Body example**:

MISSION_REVIEW_ISSUE_MATRIX_MULTI_TABLE: issue-matrix.md contains 3 Markdown tables; exactly one is allowed.

---

ISSUE_MATRIX_EVIDENCE_REF_EMPTY

**Code**: `MISSION_REVIEW_ISSUE_MATRIX_EVIDENCE_REF_EMPTY`

**When it fires**: The `evidence_ref` cell for a row in `issue-matrix.md` is empty or whitespace-only.

**JSON stability**: this code string is stable across minor releases; consumers may match it as an opaque identifier.

**Remediation**: 1. Add a concrete evidence reference: a commit SHA, test path, PR link, or file:line reference that closes the issue. 2. For deferred issues, the evidence_ref must contain a follow-up issue handle (e.g., `Follow-up: #NNN` or a URL matching `#\d+`). 3. Do not use placeholder values such as `TBD` or `N/A`; these will also be flagged by `ISSUE_MATRIX_DEFERRED_WITHOUT_HANDLE`.

**Body example**:

MISSION_REVIEW_ISSUE_MATRIX_EVIDENCE_REF_EMPTY: Ro