feat(cli): the command contract — help is the contract, and it is enforced (v0.20.0)

[ccisnedev]

Eight changes, each found by using the tool rather than reading it. Every one is reproduced by execution before it is fixed, and verified by execution after.

The through-line

iq init --host claude ran and exited 0. The flag did nothing — but nothing said so, so you believed it had. Chasing that led to the CLI's help, then to the SDK underneath it, and back. What comes out is a CLI where one declaration is the help, the machine catalog, and the parser — they cannot drift, because they are the same thing.

Added

Every command declares its contract. Parameters are declared as CliParam on each command's Input:

• iq <command> --help → that command's full contract (type, required, default, allowed values), positionals included, without having to supply them. iq <module> --help → every command under it.
• iq help --json → the whole catalog as JSON — the machine twin of the text help, and the CLI analogue of the OpenAPI document modular_api generates from its registered use cases.
• An undeclared option is refused, not ignored. The 8 commands that take no options declare an empty contract — a statement, not an absence:

$ iq init --host claude
Error: unknown option --host [VALIDATION_FAILED]
  parameter: host
Usage: init ...
exit=7

Fixed

• iq doctor could hang forever. Only the TCP handshake was bounded; a connection accepted but never answered waited indefinitely (observed: a 1m40s hang, killed by hand). Nothing threw, so the silent-on-failure catch never fired.
• iq doctor was blind to the skills that matter. It expected only the asset-tree skills, reporting agent + 3 skills deployed on a host carrying 7 — the four generated iq-* phase skills went unverified, and a host missing iq-plan read as healthy.
• The help had drifted and could not stop. A hand-written string: specification and issue shipped and were never listed in it, for two releases. It is now rendered from the catalog every registration feeds — a registered command cannot be absent from it.
• The specification_ready gate passed specs with a whole user story unimplemented. AC ids were bare AC-N, but numbering restarts per story, so US-1/AC-1 and US-2/AC-1 collapsed onto one id. Reproduced end-to-end: a login issue green-lit a spec whose CSV-export story had no issue at all. Ids are now qualified by their story (US2-AC3), read from the heading (US-2: / HU-2:) so the token is the same in both languages. Spec tables are unchanged.

Changed

• The whole cleanrooms/ working area is git-ignored — only the state file was, so diagnosis.md / plan.md accumulated. A cleanroom is a per-cycle working area; the durable artifacts are the published issue, the code and the tests.
• Requires modular_cli_sdk 0.3.3 + cli_router 0.1.0.

What this found in the SDK

Integrating the SDK surfaced three defects in it — none observable from inside the SDK, because its example had no CLI shaped like a real one. Each was fixed with TDD and released upstream (0.3.1, 0.3.2, 0.3.3):

1. The bare invocation was hijacked: iq printed the help instead of its banner, because the SDK assumed no route could claim the empty invocation.
2. An empty parameter contract was inexpressible — params: const [] was the same value as the default — so zero-option commands could not be enforced. That is the original bug.
3. A command with positionals could not answer --help: you had to supply the very argument you were asking about.

Verification

578 tests green, dart analyze clean (one pre-existing doc-comment lint). Every behaviour above was driven against the compiled binary, not just asserted in tests.