cli-design: record the gh convention and both multi-value flag shapes #32

Merged

vnprc merged 2 commits from agent/cli-design-gh-convention into master

2026-07-29 14:48:35 +01:00

allod-agent commented

2026-07-29 14:41:13 +01:00

Member

cli-design.md stated the space-variadic form as the universal rule for multi-value flags, which is not what the tools do. A reader following the entry as written would call forge --label a b and hit unexpected argument: b.

States the actual rule: value lists are comma-separated with repetition accumulating, which is gh's shape and what forge already does.
Names the one exception and its reason: a comma is legal in a filename, so path lists are not comma-separated — gh takes them as positionals, and allod change record --files takes them space-separated.
Records the standing directive to copy gh wherever it has an established shape.
Keeps the invariants that hold either way: a following option ends a list, -- keeps a --prefixed value reachable, and an empty list is an error rather than a fall back to a broader default.

Risk

R0. Documentation only, in the memory repo. The entry it replaces was actively misleading about forge, so the failure mode this removes is an agent writing a wrong invocation; nothing executes from this file.

Validation

Both shapes were exercised against the installed tools rather than read from source. allod change record --files a b, the repeated form, and the two combined all parse; an empty list refuses with --files requires a value. forge's comma handling is append_csv_values at forge:267-279, reached from all seven label-flag call sites.

`cli-design.md` stated the space-variadic form as the universal rule for multi-value flags, which is not what the tools do. A reader following the entry as written would call `forge --label a b` and hit `unexpected argument: b`. - States the actual rule: value lists are comma-separated with repetition accumulating, which is `gh`'s shape and what `forge` already does. - Names the one exception and its reason: a comma is legal in a filename, so path lists are not comma-separated — `gh` takes them as positionals, and `allod change record --files` takes them space-separated. - Records the standing directive to copy `gh` wherever it has an established shape. - Keeps the invariants that hold either way: a following option ends a list, `--` keeps a `-`-prefixed value reachable, and an empty list is an error rather than a fall back to a broader default. ## Risk R0. Documentation only, in the memory repo. The entry it replaces was actively misleading about `forge`, so the failure mode this removes is an agent writing a wrong invocation; nothing executes from this file. ## Validation Both shapes were exercised against the installed tools rather than read from source. `allod change record --files a b`, the repeated form, and the two combined all parse; an empty list refuses with `--files requires a value`. `forge`'s comma handling is `append_csv_values` at `forge:267-279`, reached from all seven label-flag call sites.

allod-agent added 1 commit

2026-07-29 14:41:13 +01:00