Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: register comment.

Kind: tracking. Source: review 8.3; 8.5 F and I; register row C33.

Problem

CLI_CONTRACT.md is the public surface's only reference, and almost all of it is checked by hand. Measured on 9c43dfc:

• Size: CLI_CONTRACT.md has 1,940 lines and 379 KB. At the review's snapshot (2463257) it had 1,638 lines and 332 KB. 54 lines exceed 1,000 characters, 13 exceed 3,000, and the longest, line 166, has 11,338 characters.
• History mixed into reference: 155 lines carry a v5.0 annotation and 29 a MAJOR/BREAKING marker. "Vendored JVM support (v5)" sits inside How the contract is enforced.
• The enforcement section overstates the guard. It says every item is "locked in" by the cli_parse_* tests. Those tests assert the parser, not the document. Only two mechanical checks read the contract at all:
  • tests/contract_gradle_codes.rs checks the Gradle/JVM codes;
  • scripts/tests/test_vlt_coverage.py checks the vlt codes.
• Measured drift: about 43 code-shaped literals in --json emitting positions appear nowhere in the contract (Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931). Two operator env vars read by core are undocumented (SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678).
• The argument and env-var tables have almost no drift today, but nothing keeps it that way. On a debug build, every --long flag in the --help of the nine visible subcommands, and every [env: SOCKET_*], was checked against Global arguments, Per-subcommand arguments and Environment variables. Every one is documented; Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949 lists two small gaps in the env-var lists. The only documented flags missing from --help are the hidden deprecated spellings (--apply, --vendor, --no-apply) and the removed --redirect/--detached, which exit 2. Both runs gave the same result.
• docs/testing doubles as test input (review 8.3). vlt-compatibility.md tables feed scripts/check-vlt-legs.py, and docs/testing/vlt-coverage.json maps codes to Rust test function names.

Target design

• A checked reference for the parts that are mechanically derivable: commands and flags from Cli::command(), env vars (clap-bound and the core-read registry), errorCode tables from the typed registry (Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930) and exit codes. Each is either generated into the contract or pinned to it by a freshness test that fails in both directions (undocumented and phantom).
• Prose that describes current behavior only, in 300 lines or less, linking to per-topic pages under docs/ for the long hosted, vendored and VEX notes. Version history moves to docs/migrating-to-v5.md and the release notes.
• Test inputs live under tests/, and the docs are rendered from them, not parsed by them.

Children, in order

• 1. Pin the argument and env-var tables to Cli::command() with a freshness test: Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949.
• 2. Document the core-read env vars and add a registry for them, checked by the same test: SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678.
• 3. Emit every --json code from one typed registry and check the contract's code tables against it: Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930 (first child An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931).
• 4. Pin the exit-code tables (global and vex's tri-state) to the code that returns them. Not filed yet.
• 5. Move version history (v5.0, MAJOR, BREAKING annotations, the "Removed in" paragraphs) out of the reference into docs/migrating-to-v5.md. Docs only. Not filed yet.
• 6. Split the long per-ecosystem behavior notes (pnpm/npm/vlt hosted contracts, takeover reconciliation, vendored JVM, Gradle) into docs/ pages and cut the contract's prose to 300 lines or less. Rewrite "How the contract is enforced" to list the real guards. Not filed yet; after 5.
• 7. Move docs/testing/vlt-coverage.json and the leg tables' machine data to tests/specs/, and render the markdown from them. Not filed yet.

Size and scope

Each child is one reviewable PR. Children 1, 2 and 4 are test plus small doc edits (≤300 lines each). Children 5 and 6 are documentation moves with no code change. Out of scope: changing any flag, env var, code or exit code (those are decisions), and CHANGELOG.md.

Acceptance criteria

• Every child is merged or closed with a reason.
• CLI_CONTRACT.md is 300 lines or less of prose plus checked tables, and no line exceeds 1,000 characters.
• Each table in the contract is covered by a test that fails on an undocumented entry and on a phantom one.

Dependencies

Child 3 follows #930. Child 6 should follow child 5. It doesn't block other work. C13 (#930) and C40 (#678) are folded in as children.

Consolidated work — backlog review, 2026-10-08

The following standalone issues are now tracked here. Their closure consolidates scheduling; it does not mean their implementation is complete. Original reports and discussion remain linked below.

#678: SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md

• Track the remaining scope from SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678 in this issue. Keep the two missing environment-variable docs and their freshness coverage as a checklist item in the CLI contract tracker.

#949: Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test

• Track the remaining scope from Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949 in this issue. Explicit CLI-contract freshness-test child; track it inside the parent documentation-contract work.