8000 docs(minimal): T32 — One command model, its help, completions and reference by minimal-foundry[bot] · Pull Request #3700 · gominimal/minimal · GitHub
[go: up one dir, main page]

Skip to content

docs(minimal): T32 — One command model, its help, completions and reference - #3700

Merged
mitodrummer merged 7 commits into
mainfrom
agent/2922-one-command-model-its-help-completions-and-refer
Nov 21, 2026
Merged

mitodrummer merged 7 commits into
mainfrom
agent/2922-one-command-model-its-help-completions-and-refer

Conversation

@minimal-foundry
@minimal-foundry minimal-foundry Bot commented Nov 20, 2026 •
Copy link
Copy Markdown
Contributor

T32 — One command model, its help, completions and reference

slice: S8
kind: task
covers: BCLI-026, BCLI-028, BCLI-044, BCLI-043
size: M
est: 150 code, 300 tests
executor: agent
difficulty: routine
model: standard
diagnostics: min box --help lists every verb with one line on what it does, and min box <verb> --help lists its flags, pinned by help_and_completions_from_one_model
observability: the command's existing tracing span records the verb, the box id it resolved and the outcome
layers:
- client:
- crates/minimal/src/cli.rs: the verb's arguments and help in the one command model
- crates/minimal/src/completions.rs: completions come from the same command model as the help
- crates/minimal/src/tests.rs: the in-process minimald test harness gains this layer's tests
test: cargo nextest run -p minimal box_verbs_exist_with_arch_flags
test: cargo nextest run -p minimal help_and_completions_from_one_model
test: cargo nextest run -p minimal cli_reference_documents_box_grammar
test: cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note
test: cargo nextest run -p minimal setup_zed_unchanged
- docs:
- docs/reference/cli-min.md: documents every min box< 10000 /code>, session and task verb
- docs/concepts/sessions.md: carries the one migration note that names the old spellings
produces: none
consumes: none
proof: min box --help and the shell completions list every verb and flag, and the CLI reference documents each one.
depends on:
- blocked by #2913
- blocked by #2893
- blocked by #2915
- blocked by #2908
- blocked by #2909
- blocked by #2921
- blocked by #2917

Proof

min box --help, min session --help and min task --help list every verb with one line on what it does. Each min <noun> <verb> --help and the shell completion of min <noun> <verb> -- list the same flags, because both come from the one clap command model. docs/reference/cli-min.md now has a section for all 17 min box verbs and for each min session and min task alias, and the tests fail if a verb or flag goes missing from any of them. docs/concepts/sessions.md has the one migration note for the old spellings and --provider local-minimald.

Notes from the agent: The verbs and flags were already in the command model, so the code change in cli.rs is only the help lines of min box, min session and min task. completions.rs needed no change: completions already run through clap_complete over Cli::command, the same model as the help, and help_and_completions_from_one_model now pins that. Gap against BCLI-026: min box run still has no --name (BCLI-069). The comment on TaskRunArgs defers it to #3196, because RunEntry in task.rs takes no name, and task.rs is outside this task's layers. box_verbs_exist_with_arch_flags does not assert --name on box run. Observability: the task asks for the verb, the resolved box id and the outcome on the command's tracing span. The dispatch code is in main.rs and cmd/boxes, outside the layers, so I did not change it. Not done: just lint-prose (vale is not installed on this box) and just clippy-strict. cargo clippy -p minimal --all-targets is clean. Docs drift I saw but did not fix: the session attach section in cli-min.md still says an ambiguous bare attach opens a picker. BCLI-032 says it fails with exit 2 and lists the candidates. I did not check which behaviour the code has.

Tests

line exit tail
cargo nextest run -p minimal box_verbs_exist_with_arch_flags 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal help_and_completions_from_one_model 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal cli_reference_documents_box_grammar 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal setup_zed_unchanged 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt

Verify

min task run agent-verify exited 100, so this PR is a draft.

/1232) minimal::bin/min tests::invalid_project_file_prints_toml_error_once
        PASS [   0.004s] (1207/1232) minimal::bin/min tests::invalid_project_file_prints_toml_error_once_for_io
        PASS [   0.004s] (1208/1232) minimal::bin/min tests::loadout_not_found_exits_4
        PASS [   0.005s] (1209/1232) minimal::bin/min tests::local_host_not_found_exits_4
        PASS [   0.005s] (1210/1232) minimal::bin/min tests::machine_mode_answers_write_failures
        PASS [   0.005s] (1211/1232) minimal::bin/min tests::machine_mode_error_line_keeps_an_empty_hint
        PASS [   0.005s] (1212/1232) minimal::bin/min tests::machine_mode_error_object_is_one_stamped_line
        PASS [   0.004s] (1213/1232) minimal::bin/min tests::machine_mode_error_object_on_stderr
        PASS [   0.005s] (1214/1232) minimal::bin/min tests::machine_mode_names_the_grant_refusal_code
        PASS [   0.005s] (1215/1232) minimal::bin/min tests::machine_output_mode_keys_on_the_output_flag
        PASS [   0.005s] (1216/1232) minimal::bin/min tests::misplaced_run_flag_exits_2
        PASS [   0.005s] (1217/1232) minimal::bin/min tests::network_flag_refusal_exits_2
        PASS [   0.005s] (1218/1232) minimal::bin/min tests::project_file_not_found_exits_4
        PASS [   0.005s] (1219/1232) minimal::bin/min tests::prune_off_tty_needs_yes_exits_2
        PASS [   0.005s] (1220/1232) minimal::bin/min tests::resume_and_session_attach_refusals_map_to_exit_codes
        PASS [   0.004s] (1221/1232) minimal::bin/min tests::rm_running_box_refuses_naming_force_with_exit_2
        PASS [   0.005s] (1222/1232) minimal::bin/min tests::row_not_back_exit_codes
        PASS [   0.005s] (1223/1232) minimal::bin/min tests::run_verbs_and_wait_timeout_return_124_with_code_timeout
        PASS [   0.005s] (1224/1232) minimal::bin/min tests::start_entry_refusals_exit_with_their_codes
        PASS [   0.005s] (1225/1232) minimal::bin/min tests::task_file_invalid_exits_3
        PASS [   0.005s] (1226/1232) minimal::bin/min tests::task_network_key_a_task_does_not_apply_exits_3
        PASS [   0.005s] (1227/1232) minimal::bin/min tests::task_not_found_exits_4
        PASS [   0.004s] (1228/1232) minimal::bin/min tests::task_run_is_a_stdout_contract
        PASS [   0.005s] (1229/1232) minimal::bin/min tests::type_refusals_exit_3_and_4
        PASS [   0.904s] (1230/1232) minimal::otel_cli a_silent_collector_costs_min_ls_little_and_prints_nothing
        PASS [   2.058s] (1231/1232) minimal::named_vm named_vm_reaches_autospawn
  stdout ───

    running 1 test
    test exec_run_attach_and_task_run_share_the_commands_trace ... FAILED

    failures:

    failures:
        exec_run_attach_and_task_run_share_the_commands_trace

    test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 5 filtered out; finished in 13.00s

  stderr ───

    ]
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

  Cancelling due to test failure: 
────────────
error: test run failed

Residuals

BCLI-026 gaps (arch C2 at 3d25bc3). box_verbs_exist_with_arch_flags lists each one in DEFERRED_ARCH_FLAGS:

Closes #2922

…ence

Five tests check that every min box, session and task verb and flag is in
the one command model, in --help and in the shell completions. They also
check the CLI reference and the one migration note. The noun help lines
now say what each noun does.
Add a reference section for each box verb and each type-noun alias, and
one migration note in the sessions concept page for the old spellings.
The task puts the old spellings in one migration note in
docs/concepts/sessions.md. The T31 docs check now skips only that
section and still rejects the old spellings everywhere else.
@coderabbitai
coderabbitai Bot commented Nov 20, 2026 •
Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot user detected.

Ask an organization administrator to verify that this bot has an active assigned CodeRabbit review seat. See the seat-assignment guide. After the seat is confirmed, request a review again.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 5b694b86-e404-45d0-ad6a-e39f7ec2c12c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@agent-137
Copy link
Copy Markdown
Member

/arch-review

@agent-137
agent-137 requested a review from a team as a code owner November 21, 2026 01:56
@minimal-foundry
minimal-foundry Bot commented Nov 21, 2026 •
Copy link
Copy Markdown
Contributor Author

Reviewed: no findings; approval withheld, 7 threads unresolved at 7be346c14265.

APPROVE withheld: 7 unresolved threads — minimal-arch[bot] crates/minimal/src/tests.rs:26141, minimal-arch[bot] crates/minimal/src/tests.rs:26144, minimal-arch[bot] docs/reference/cli-min.md:434, minimal-arch[bot] docs/reference/cli-min.md:471, minimal-arch[bot] crates/minimal/src/tests.rs:26096, …. Resolving the last thread releases the approval on this head.

Resolve the open threads. Resolving the last one releases the approval on this head; no new review is required.

Verdict APPROVE, posted as a comment: the App cannot review its own pull request; the check and the label carry it.

Clobber: none seen.

@minimal-foundry minimal-foundry Bot left a comment
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approved

Verdict APPROVE — No findings.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Nov 21, 2026
@minimal-arch minimal-arch Bot left a comment
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arch-review: CONDITIONS · 3 conditions · the full ruling

The help and completions come from one command model, and the new reference sections are complete. BCLI-026 is not met yet. Architecture lines 488 and 493 give box run the flags --name, --loadout and --ingress, and give box list the flags --type and --parent. The model does not have them. box_verbs_exist_with_arch_flags hides this gap, so C1 makes the test name each deferred flag with its issue. C2 files the issues that do not exist and lists every gap as a residual in the PR body. C3 removes the session attach picker text, because architecture line 511 and the code refuse with exit 2.

Ruled at 3d25bc3 against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.

],
),
(
"run",
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C1 · Architecture line 488 gives box run the flags --name, --loadout and --ingress. The model does not have them, and this table does not name them. Add them to a DEFERRED_ARCH_FLAGS table with their issues (#3196, #3237, #3163). Assert that they are absent.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 2312cce31bcd: Added DEFERRED_ARCH_FLAGS with box run --name (#3196), --ingress (#3163) and --loadout (#3237). The test asserts that each one is absent from the model.

"run",
&["--detach", "--network", "--no-loadouts", "--no-hooks"],
),
("list", &["--all", "--output"]),
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C1 · Architecture line 493 gives box list the flags --type <name> and --parent <box>. The Non-goals exempt only self. Put both in DEFERRED_ARCH_FLAGS with the issue that C2 files.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 2312cce31bcd: Added box list --type and --parent (#3714) to DEFERRED_ARCH_FLAGS. The test asserts that both are absent.

Comment thread docs/reference/cli-min.md
| Flag | Description |
|------|-------------|
| `--detach` | Start the box, print its id and return. The box gets no input |
| `--path <PATH>` | The project directory. The default is the directory that `-C` names, else the current directory |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C2 · Architecture line 488 gives box run no --path, and the global -C names the project. The row stays while the flag is in the model. File an issue to remove the flag from BoxRunArgs and cmd_box_run, and list it as a residual in the PR body.

10BC8
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 2312cce31bcd: No code change in this round. #3715 tracks removing --path from BoxRunArgs and cmd_box_run. The PR body lists it as a residual, and the row stays while the flag is in the model.

Comment thread docs/reference/cli-min.md
attaches to the running box of this project that has a terminal. When no such
box runs, it attaches to the project's only stopped or exited box that has a
terminal, which starts again. When more than one box can match, the command
lists them and exits with code 2.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C3 · This line agrees with architecture line 511. The session attach section at lines 332–334 does not: it says an ambiguous bare attach opens a picker. The code refuses with exit 2. Change that section and docs/concepts/sessions.md lines 123–126 to say the command lists the candidates and exits with code 2.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 2312cce31bcd: The session attach section of cli-min.md and docs/concepts/sessions.md now say: when more than one session can match, the command lists them and exits with code 2.

@agent-137
Copy link
Copy Markdown
Member

/revise Arch's ruling at 3d25bc3 (CONDITIONS): C1 and C3. C2 is done: #3714 and #3715 are filed, and the PR body lists the residuals.

  1. C1, in crates/minimal/src/tests.rs box_verbs_exist_with_arch_flags: add a DEFERRED_ARCH_FLAGS table of the architecture's flags that the model does not have yet, each with its issue URL:

    Assert that each one is absent from visible_long_flags(&model_verb("box", verb)), so the test fails when a flag lands without a table update. Change the test's doc comment to say it pins the delivered flags plus this deferred list, not every flag of architecture lines 488 and 493.

  2. C3, in docs/reference/cli-min.md ### session attach (lines 332 to 334): replace "opens an interactive picker if the choice is ambiguous (--no-input errors instead)" with: when more than one session can match, the command lists them and exits with code 2. In docs/concepts/sessions.md lines 123 to 126, replace "opens a picker to choose between them (and fails when ...)" with the same statement. This matches the code: attach_command in crates/minimal/src/cmd/boxes/attach.rs refuses with AmbiguousSessions (exit 2). Only bare min (cmd/list.rs) uses a picker.

Change nothing else, and do not edit cli.rs or the PR body. Run cargo nextest run -p minimal box_verbs_exist_with_arch_flags cli_reference_documents_box_grammar. The verify failure in exec_run_attach_and_task_run_share_the_commands_trace is the known flake #3483.

The box_verbs_exist_with_arch_flags test now lists the architecture's
box run and box list flags that the model does not have yet, each with
its issue, and fails when one of them lands. The session attach docs
say an ambiguous bare attach lists the sessions and exits with code 2.
@minimal-foundry
Copy link
Copy Markdown
Contributor Author

Round 1 of 10 on a /revise note, pushed as 2312cce31bcd.

line exit tail
cargo nextest run -p minimal box_verbs_exist_with_arch_flags 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal help_and_completions_from_one_model 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal cli_reference_documents_box_grammar 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal setup_zed_unchanged 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt

Verify min task run agent-verify exited 100.

3) minimal::bin/min tests::invalid_project_file_for_box_spec_says_spec_cannot_show
        PASS [   0.008s] (1208/1233) minimal::bin/min tests::invalid_project_file_prints_toml_error_once
        PASS [   0.009s] (1209/1233) minimal::bin/min tests::invalid_project_file_prints_toml_error_once_for_io
        PASS [   0.012s] (1210/1233) minimal::bin/min tests::loadout_not_found_exits_4
        PASS [   0.008s] (1211/1233) minimal::bin/min tests::local_host_not_found_exits_4
        PASS [   0.008s] (1212/1233) minimal::bin/min tests::machine_mode_answers_write_failures
        PASS [   0.008s] (1213/1233) minimal::bin/min tests::machine_mode_error_object_is_one_stamped_line
        PASS [   0.010s] (1214/1233) minimal::bin/min tests::machine_mode_error_line_keeps_an_empty_hint
        PASS [   0.009s] (1215/1233) minimal::bin/min tests::machine_mode_names_the_grant_refusal_code
        PASS [   0.009s] (1216/1233) minimal::bin/min tests::machine_mode_error_object_on_stderr
        PASS [   0.009s] (1217/1233) minimal::bin/min tests::misplaced_run_flag_exits_2
        PASS [   0.009s] (1218/1233) minimal::bin/min tests::machine_output_mode_keys_on_the_output_flag
        PASS [   0.008s] (1219/1233) minimal::bin/min tests::project_file_not_found_exits_4
        PASS [   0.009s] (1220/1233) minimal::bin/min tests::network_flag_refusal_exits_2
        PASS [   0.009s] (1221/1233) minimal::bin/min tests::prune_off_tty_needs_yes_exits_2
        PASS [   0.009s] (1222/1233) minimal::bin/min tests::resume_and_session_attach_refusals_map_to_exit_codes
        PASS [   0.007s] (1223/1233) minimal::bin/min tests::rm_running_box_refuses_naming_force_with_exit_2
        PASS [   0.009s] (1224/1233) minimal::bin/min tests::row_not_back_exit_codes
        PASS [   0.008s] (1225/1233) minimal::bin/min tests::run_verbs_and_wait_timeout_return_124_with_code_timeout
        PASS [   0.008s] (1226/1233) minimal::bin/min tests::start_entry_refusals_exit_with_their_codes
        PASS [   0.008s] (1227/1233) minimal::bin/min tests::task_file_invalid_exits_3
        PASS [   0.008s] (1228/1233) minimal::bin/min tests::task_network_key_a_task_does_not_apply_exits_3
        PASS [   0.007s] (1229/1233) minimal::bin/min tests::task_not_found_exits_4
        PASS [   0.009s] (1230/1233) minimal::bin/min tests::task_run_is_a_stdout_contract
        PASS [   0.009s] (1231/1233) minimal::bin/min tests::type_refusals_exit_3_and_4
        PASS [   2.074s] (1232/1233) minimal::named_vm named_vm_reaches_autospawn
  stdout ───

    running 1 test
    test exec_run_attach_and_task_run_share_the_commands_trace ... FAILED

    failures:

    failures:
        exec_run_attach_and_task_run_share_the_commands_trace

    test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 5 filtered out; finished in 13.17s

  stderr ───

    ]
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

  Cancelling due to test failure: 
────────────
error: test run failed

Converted to a draft: verify exited 100.

Review threads the coder judged:

min box --help and the shell completions list every verb and flag, and the CLI reference documents each one. The test now also names the architecture flags that are still deferred, each with its issue, and fails when one of them lands. The session attach docs now say that an ambiguous bare attach lists the sessions and exits with code 2.

Notes from the agent: Revise round 1: C1 and C3 are done. C2 needed no change in this round. cli.rs and the PR body are unchanged. I ran the five test lines in two combined nextest invocations, and each test is named in them. I did not run the wider verify suite, so I did not check the known flake #3483.

@minimal-foundry
minimal-foundry Bot marked this pull request as draft November 21, 2026 02:39
@agent-137
agent-137 marked this pull request as ready for review November 21, 2026 02:39
@agent-137
Copy link
Copy Markdown
Member

/arch-review

@minimal-arch minimal-arch Bot left a comment
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling

The three earlier conditions are met. The test now pins each deferred architecture flag as absent, with its issue. The PR body lists each gap as a residual. The attach docs say an ambiguous attach exits 2, as architecture line 511 requires. The flags that lines 488 and 493 give and the model lacks stay open as filed residuals. C1 records that follow-up work.

Ruled at 2312cce against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.

// The architecture's flags that are not in the model yet, each with the
// issue that delivers it. When one of them lands, this test fails until
// the flag moves from this table to `expected`.
const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C1 · This table holds the flags that architecture lines 488 and 493 give and the model lacks. Each issue that delivers a flag must move it from this table to expected. The --path removal (#3715) is not in this table. Remove --path from BoxRunArgs and assert it is absent when #3715 lands.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracked after merge. #3196, #3163, #3237 and #3714 each move their flag from DEFERRED_ARCH_FLAGS to expected when they land. #3715 removes --path from BoxRunArgs and cmd_box_run, and asserts that it is absent from min box run.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Disputed — not addressed: Nothing to change in this PR. --path is still in BoxRunArgs, so it cannot be asserted absent yet. #3715 removes it from BoxRunArgs and cmd_box_run and adds that assertion when it lands.

@minimal-foundry minimal-foundry Bot left a comment
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

Comment on lines +26399 to +26402
for flag in visible_long_flags(&model_verb(noun, verb)) {
let documented =
section.contains(&flag) || (points_to_start && session_start.contains(&flag));
if !documented {
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOW · tests · confidence 0.55 · in cli_reference_documents_box_grammar

cli_reference_documents_box_grammar checks a flag with section.contains(&flag), a substring match. A flag such as --all or --network passes when the section only names a longer flag such as --all-providers. The test can pass while the flag is undocumented. Match the flag as a whole word, for example in backticks.

What the reviewer checked

tests.rs:26401 section.contains(&flag) || (points_to_start && session_start.contains(&flag))

Hand this to an agent
Act on a code-review finding.

File:       crates/minimal/src/tests.rs
Lines:      26399-26402
Category:   tests
Severity:   low (reviewer confidence 0.55)

Finding:
`cli_reference_documents_box_grammar` checks a flag with `section.contains(&flag)`, a substring match. A flag such as `--all` or `--network` passes when the section only names a longer flag such as `--all-providers`. The test can pass while the flag is undocumented. Match the flag as a whole word, for example in backticks.

First verify this against the code yourself. It is model output and
may be wrong. If it is wrong, or the tradeoff was deliberate, say so
and change nothing.

👍 useful · 👎 noise — react to tell the reviewer. Replying works too, and says more.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 7be346c14265: cli_reference_documents_box_grammar now uses names_flag, a whole-word match, so --all does not match inside --all-providers. A unit test pins the helper.

@minimal-foundry minimal-foundry Bot removed the review:approved minimal-review approved the current head label Nov 21, 2026
A flag such as --all no longer passes on a section that names only
--all-providers.
@minimal-foundry
Copy link
Copy Markdown
Contributor Author

Round 2 of 10 on the runtime's review findings, pushed as 7be346c14265.

line exit tail
cargo nextest run -p minimal box_verbs_exist_with_arch_flags 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal help_and_completions_from_one_model 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal cli_reference_documents_box_grammar 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal docs_name_aliases_only_in_one_migration_note 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt
cargo nextest run -p minimal setup_zed_unchanged 0 warning: unknown fields in task runtime-implement-test-0: network warning: unknown fields in task runtime-implement-test-1: network warning: unknown fields in task runtime-implement-test-2: network warning: unknown fields in task runtime-implement-test-3: network warning: unknown fields in task runt

Verify min task run agent-verify exited 100.

4) minimal::bin/min tests::invalid_project_file_for_box_spec_says_spec_cannot_show
        PASS [   0.013s] (1209/1234) minimal::bin/min tests::invalid_project_file_prints_toml_error_once
        PASS [   0.008s] (1210/1234) minimal::bin/min tests::invalid_project_file_prints_toml_error_once_for_io
        PASS [   0.008s] (1211/1234) minimal::bin/min tests::loadout_not_found_exits_4
        PASS [   0.007s] (1212/1234) minimal::bin/min tests::local_host_not_found_exits_4
        PASS [   0.008s] (1213/1234) minimal::bin/min tests::machine_mode_answers_write_failures
        PASS [   0.007s] (1214/1234) minimal::bin/min tests::machine_mode_error_line_keeps_an_empty_hint
        PASS [   0.007s] (1215/1234) minimal::bin/min tests::machine_mode_error_object_on_stderr
        PASS [   0.009s] (1216/1234) minimal::bin/min tests::machine_mode_error_object_is_one_stamped_line
        PASS [   0.009s] (1217/1234) minimal::bin/min tests::machine_mode_names_the_grant_refusal_code
        PASS [   0.008s] (1218/1234) minimal::bin/min tests::machine_output_mode_keys_on_the_output_flag
        PASS [   0.008s] (1219/1234) minimal::bin/min tests::misplaced_run_flag_exits_2
        PASS [   0.009s] (1220/1234) minimal::bin/min tests::network_flag_refusal_exits_2
        PASS [   0.008s] (1221/1234) minimal::bin/min tests::project_file_not_found_exits_4
        PASS [   0.007s] (1222/1234) minimal::bin/min tests::prune_off_tty_needs_yes_exits_2
        PASS [   0.007s] (1223/1234) minimal::bin/min tests::resume_and_session_attach_refusals_map_to_exit_codes
        PASS [   0.009s] (1224/1234) minimal::bin/min tests::rm_running_box_refuses_naming_force_with_exit_2
        PASS [   0.007s] (1225/1234) minimal::bin/min tests::row_not_back_exit_codes
        PASS [   0.008s] (1226/1234) minimal::bin/min tests::run_verbs_and_wait_timeout_return_124_with_code_timeout
        PASS [   0.007s] (1227/1234) minimal::bin/min tests::start_entry_refusals_exit_with_their_codes
        PASS [   0.008s] (1228/1234) minimal::bin/min tests::task_file_invalid_exits_3
        PASS [   0.008s] (1229/1234) minimal::bin/min tests::task_network_key_a_task_does_not_apply_exits_3
        PASS [   0.008s] (1230/1234) minimal::bin/min tests::task_not_found_exits_4
        PASS [   0.007s] (1231/1234) minimal::bin/min tests::task_run_is_a_stdout_contract
        PASS [   0.007s] (1232/1234) minimal::bin/min tests::type_refusals_exit_3_and_4
        PASS [   2.063s] (1233/1234) minimal::named_vm named_vm_reaches_autospawn
  stdout ───

    running 1 test
    test exec_run_attach_and_task_run_share_the_commands_trace ... FAILED

    failures:

    failures:
        exec_run_attach_and_task_run_share_the_commands_trace

    test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 5 filtered out; finished in 13.09s

  stderr ───

    ]
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

  Cancelling due to test failure: 
────────────
error: test run failed

Converted to a draft: verify exited 100.

Review threads the coder judged:

  • 👎 invalid — crates/minimal/src/tests.rs:26096: Nothing to change in this PR. --path is still in BoxRunArgs, so it cannot be asserted absent yet. Remove --path from min box run #3715 removes it from BoxRunArgs and cmd_box_run and adds that assertion when it lands.
  • 👍 valid — crates/minimal/src/tests.rs:26402: cli_reference_documents_box_grammar now uses names_flag, a whole-word match, so --all does not match inside --all-providers. A unit test pins the helper.

min box --help and the shell completions list every verb and flag, and the CLI reference documents each one. The reference check now fails when a flag is named only as part of a longer flag.

Notes from the agent: Revise round 2. The reference test now matches each flag as a whole word through a new names_flag helper, with its own unit test. All flags in docs/reference/cli-min.md still pass, so the docs needed no change. The --path removal stays with #3715, as the earlier reply on that thread says.

@minimal-foundry
minimal-foundry Bot marked this pull request as draft November 21, 2026 03:16
@minimal-arch minimal-arch Bot left a comment
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling

The new commit makes the reference test match each flag as a whole word. That is a stricter proof of BCLI-044, and it conforms. C1 from the last ruling stays open. The flags that architecture.md lines 488 and 493 list are still deferred to the filed issues. The change can merge with C1 open. Close C1 through issues #3196, #3163, #3237, #3714 and #3715.

Ruled at 7be346c against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.

// The architecture's flags that are not in the model yet, each with the
// issue that delivers it. When one of them lands, this test fails until
// the flag moves from this table to `expected`.
const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C1 · C1 stays open. architecture.md lines 488 and 493 list --name, --ingress, --loadout, --type and --parent. Each issue moves its flag from this table to expected when it lands. Issue #3715 removes --path from BoxRunArgs.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left open as a residual, as the ruling at 7be346c1 allows: #3196 (--name), #3237 (--loadout) and #3163 (--ingress), listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.

@minimal-foundry minimal-foundry Bot left a comment
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approval withheld

Verdict COMMENT — APPROVE withheld: 7 unresolved threads — minimal-arch[bot] crates/minimal/src/tests.rs:26141, minimal-arch[bot] crates/minimal/src/tests.rs:26144, minimal-arch[bot] docs/reference/cli-min.md:434, minimal-arch[bot] docs/reference/cli-min.md:471, minimal-arch[bot] crates/minimal/src/tests.rs:26096, …. No findings.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

@agent-137
agent-137 marked this pull request as ready for review November 21, 2026 03:54
@agent-137
Copy link
Copy Markdown
Member

/arch-review

@minimal-arch minimal-arch Bot left a comment
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arch-review: PASS_WITH_CONDITIONS · 3 conditions · the full ruling

The help, the completions and the CLI reference now come from one command model, and the tests pin them. BCLI-028, BCLI-043 and BCLI-044 conform. The command model still differs from the architecture's min box run, min task run and min box list lines (488, 473, 493). This change pins each gap in DEFERRED_ARCH_FLAGS, and each gap has a filed issue. C1, C2 and C3 name the edits. They can stay open at merge as the filed residuals. Make sure that CI is green before the merge, because the verify run failed on an otel test outside this diff.

Ruled at 7be346c against gominimal/arch@4f2eb87d5d12 by claude-opus-5-5.

// The architecture's flags that are not in the model yet, each with the
// issue that delivers it. When one of them lands, this test fails until
// the flag moves from this table to `expected`.
const DEFERRED_ARCH_FLAGS: [(&str, &str, &str); 5] = [
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C1 · Line 488 gives min box run the flags --name, --loadout and --ingress. Line 473 gives the same flags to min task run. When #3196, #3237 and #3163 add them to BoxRunArgs and TaskRunArgs, move the three run rows from this table to expected.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left open as a residual, as the ruling at 7be346c1 allows: #3196 (--name), #3237 (--loadout) and #3163 (--ingress), listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.

"https://github.com/gominimal/minimal/issues/3237",
),
(
"list",
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C2 · Line 493 gives min box list the flags --type <name> and --parent <box>. When #3714 adds them to BoxListArgs, move these two rows to expected.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left open as a residual, as the ruling at 7be346c1 allows: #3714, listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.

Comment thread docs/reference/cli-min.md
| Flag | Description |
|------|-------------|
| `--detach` | Start the box, print its id and return. The box gets no input |
| `--path <PATH>` | The project directory. The default is the directory that `-C` names, else the current directory |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C3 · Line 488 gives min box run no --path, and the global -C names the project. When #3715 removes the path field from BoxRunArgs, remove this row and add an absence check in box_verbs_exist_with_arch_flags.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left open as a residual, as the ruling at 7be346c1 allows: #3715, listed under Residuals in the PR body. DEFERRED_ARCH_FLAGS pins the gap until that issue lands.

@mitodrummer mitodrummer left a comment
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved.

@mitodrummer
mitodrummer added this pull request to the merge queue Nov 21, 2026
Merged via the queue into main with commit 4181b86 Nov 21, 2026
39 checks passed
@mitodrummer
mitodrummer deleted the agent/2922-one-command-model-its-help-completions-and-refer branch November 21, 2026 08:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

T32 — One command model, its help, completions and reference

2 participants

0