Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(cli): move index verdict exit codes off the usage-error code

Martin Vogel864484d3d802
diff --git a/src/cli/cli.h b/src/cli/cli.h
index cc96c591e..bdd0c156c 100644
--- a/src/cli/cli.h
+++ b/src/cli/cli.h
@@ -87,14 +87,20 @@ int cbm_cli_exit_status_after_maintenance(int exit_status, bool maintenance_canc
* A freshness gate must not have to read anyone's account of itself: it reads
* the process status. `index_repository` therefore grades its own outcome.
*
- * 0 indexed, quality at or above the thresholds
- * 1 hard failure (pipeline fell over inside a reachable repository)
- * 2 indexed, but below a quality threshold — a graph that exists and lies
- * about how much of the tree it covers is worse than no graph
- * 3 target unavailable: repo_path is absent, unreadable, or not a directory
+ * 0 indexed, quality at or above the thresholds
+ * 1 hard failure (pipeline fell over inside a reachable repository)
+ * 10 indexed, but below a quality threshold — a graph that exists and lies
+ * about how much of the tree it covers is worse than no graph
+ * 11 target unavailable: repo_path is absent, unreadable, or not a directory
*
* 1 keeps its historical meaning so existing `|| fail` scripts are unaffected;
- * 2 and 3 are new and carve out cases that used to return 0 and 1.
+ * 10 and 11 are new and carve out cases that used to return 0 and 1.
+ *
+ * STABLE CONTRACT: these four values are public. CI pipelines branch on them,
+ * so they are never renumbered or reused for another outcome. 2 is
+ * deliberately not a verdict: the binary already returns 2 for a usage error
+ * (an invalid --tool-profile), and shells and CI tooling read 2 that way, so a
+ * verdict on 2 could not be told apart from a mistyped command line.
*
* The contract is opt-in: it applies only when CBM_GATE is set to a non-empty
* value other than "0". Without it the CLI exits exactly as before, so a
@@ -114,8 +120,8 @@ int cbm_cli_exit_status_after_maintenance(int exit_status, bool maintenance_canc
enum {
CBM_CLI_EXIT_OK = 0,
CBM_CLI_EXIT_FAILURE = 1,
- CBM_CLI_EXIT_QUALITY = 2,
- CBM_CLI_EXIT_TARGET = 3,
+ CBM_CLI_EXIT_QUALITY = 10,
+ CBM_CLI_EXIT_TARGET = 11,
};
/* Grade an index_repository result envelope. `base_status` is what the
diff --git a/tests/test_cli.c b/tests/test_cli.c
index 3f2d506c7..54dc5ed29 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -18263,8 +18263,20 @@ static void cli_gate_env_restore(cli_gate_env_t saved) {
restore_test_env("CBM_GATE_MAX_PARTIAL_PCT", saved.partial_pct);
}
+/* The verdict codes are a public contract: CI pipelines branch on the
+ * numbers, so a renumbering must fail here rather than in someone's
+ * pipeline. Neither verdict may sit on 2, which the binary already returns
+ * for a usage error and which shells and CI tooling read that way. */
+TEST(cli_index_exit_codes_are_a_stable_contract) {
+ ASSERT_EQ(CBM_CLI_EXIT_OK, 0);
+ ASSERT_EQ(CBM_CLI_EXIT_FAILURE, 1);
+ ASSERT_EQ(CBM_CLI_EXIT_QUALITY, 10);
+ ASSERT_EQ(CBM_CLI_EXIT_TARGET, 11);
+ PASS();
+}
+
/* Without CBM_GATE the CLI exits exactly as it always did: a payload that
- * would grade 2 or 3 with the gate on keeps the base status. "0" and the
+ * would grade 10 or 11 with the gate on keeps the base status. "0" and the
* empty string count as off, so an exported CBM_GATE=0 is not a surprise. */
TEST(cli_index_exit_gate_off_keeps_base_status) {
cli_gate_env_t saved = cli_gate_env_clear();
@@ -18387,7 +18399,7 @@ TEST(cli_index_exit_separates_missing_target_from_broken_run) {
}
/* Silence is never upgraded into a verdict. A payload the grader cannot
- * read says nothing about index quality, and inventing a 2 from it would
+ * read says nothing about index quality, and inventing a 10 from it would
* fail runs for the crime of an unexpected response shape. */
TEST(cli_index_exit_never_upgrades_silence) {
cli_gate_env_t saved = cli_gate_env_clear();
@@ -18989,6 +19001,7 @@ SUITE(cli) {
RUN_TEST(cli_stdin_args_gate_tracks_tool_schema_issue1359);
/* index_repository exit contract */
+ RUN_TEST(cli_index_exit_codes_are_a_stable_contract);
RUN_TEST(cli_index_exit_gate_off_keeps_base_status);
RUN_TEST(cli_index_exit_clean_run_stays_zero);
RUN_TEST(cli_index_exit_unusable_file_is_a_quality_failure);