A --help flag must never execute a command; reject unknown flags across subcommands #439

New issue

Closed

opened 2026-08-23 19:29:07 +00:00 by mph · 1 comment

mph commented

2026-08-23 19:29:07 +00:00

Owner

./iw phase-merge --help merged a pull request.

What happened

While shipping Phase 1 of IW-423, ./iw phase-merge --max-retries 0 refused with Timed out waiting for CI checks after 30m.. ./iw phase-merge --help was then run to look for a flag to raise the budget. It printed no help. It merged PR 434:

Merging PR: https://code.iterative.works/iterative-works/iw-cli/pulls/434
{ "issueId": "IW-423", "phaseNumber": "01", ... }

The merge happened to be wanted, so nothing was lost — but the command that performed it was a request for documentation.

Why

phase-merge (core/commands/PhaseMerge.scala) has no required argument, so an unrecognised help flag falls through to the action. phase-pr behaves correctly by contrast: it fails with Missing required argument: --title and prints a usage line, because its required-argument check runs before anything else. That is accidental correctness, not a design.

Lesson: a command that acts by default and ignores unknown flags will perform its action when asked for its usage.

Fix

Handle the help flags before dispatch for every iw subcommand, not per command.
Reject unknown flags rather than ignore them, so a typo'd flag cannot silently become "do the thing".

The second half matters beyond help: today any misspelled flag on any subcommand is silently discarded and the command runs with defaults.

Note for whoever fixes this: ./iw issue create has a related parsing weakness — a --title whose value begins with two dashes is swallowed by the arg parser and the API rejects the request with a bare 422. That is the same "unknown flags are not rejected" family.

Recorded during IW-423; see project-management/issues/IW-423/LESSONS.md entry 11.

`./iw phase-merge --help` merged a pull request. ## What happened While shipping Phase 1 of IW-423, `./iw phase-merge --max-retries 0` refused with `Timed out waiting for CI checks after 30m.`. `./iw phase-merge --help` was then run to look for a flag to raise the budget. It printed no help. It merged PR 434: ``` Merging PR: https://code.iterative.works/iterative-works/iw-cli/pulls/434 { "issueId": "IW-423", "phaseNumber": "01", ... } ``` The merge happened to be wanted, so nothing was lost — but the command that performed it was a request for documentation. ## Why `phase-merge` (`core/commands/PhaseMerge.scala`) has no required argument, so an unrecognised help flag falls through to the action. `phase-pr` behaves correctly by contrast: it fails with `Missing required argument: --title` and prints a usage line, because its required-argument check runs before anything else. That is accidental correctness, not a design. **Lesson:** a command that acts by default and ignores unknown flags will perform its action when asked for its usage. ## Fix - Handle the help flags before dispatch for every `iw` subcommand, not per command. - Reject unknown flags rather than ignore them, so a typo'd flag cannot silently become "do the thing". The second half matters beyond help: today any misspelled flag on any subcommand is silently discarded and the command runs with defaults. Note for whoever fixes this: `./iw issue create` has a related parsing weakness — a `--title` whose value begins with two dashes is swallowed by the arg parser and the API rejects the request with a bare 422. That is the same "unknown flags are not rejected" family. --- Recorded during IW-423; see `project-management/issues/IW-423/LESSONS.md` entry 11.

mph referenced this issue from a commit

2026-08-23 20:00:59 +00:00

workflow: Triage lessons for IW-423

mph referenced this issue

2026-08-27 08:05:50 +00:00

Help must be able to guide an agent: an overview index, and a --help on every command that prints instead of executing #463

mph commented

2026-08-27 08:05:54 +00:00

Author

Owner

Superseded by #463, which carries both halves of this issue in full — help must never execute, and unknown flags must be rejected — and adds the content requirement: the help text itself must be instructive enough to guide an agent. Closing in favour of #463.

mph closed this issue

2026-08-27 08:05:57 +00:00

mph referenced this issue from a pull request that will close it,

2026-09-08 21:29:35 +00:00

IW-463: Help must be able to guide an agent #541