Command reference overstates --force availability on mutating commands #53

Problem Statement

The command reference currently overstates flag support: it says mutating commands accept both --dry-run and --force (cli-commands.md:59), but several mutating commands do not implement --force. This causes documentation/behavior drift and leads agents/users to run invalid commands.

Severity: Medium
Impact: Automation and agent suggestions include unsupported flags, causing CLI invocations to fail with argument parsing errors and making the command reference unreliable as a source of truth.

Affected Files / Lines

• cli-commands.md:59 (blanket statement about mutating command flags)
• prune.rs:13 (--force not defined)
• expire.rs:14 (--force not defined)
• autoclean.rs:14 (--force not defined)
• init.rs:16 (--force not defined)

Recommended Fix

Update documentation to match current implementation, and make --force support explicit per command instead of a global claim.

Suggested docs update

Mutating commands support `--dry-run`.
`--force` is command-specific and only available where explicitly documented.

Add a flag matrix in cli-commands.md to prevent ambiguity:

| Command   | `--dry-run` | `--force` |
|-----------|-------------|-----------|
| prune     | yes         | no        |
| expire    | yes         | no        |
| autoclean | yes         | no        |
| init      | yes         | no        |

Optional follow-up: if uniform ergonomics are desired, implement --force consistently across mutating commands in a separate issue.

Validation Strategy

Automated tests

1. Add CLI integration tests asserting current behavior (unsupported --force fails):

Command::cargo_bin("trop")?
    .args(["prune", "--force"])
    .assert()
    .failure()
    .stderr(predicates::str::contains("unexpected argument '--force'"));

2. Add --help assertions/snapshots for prune, expire, autoclean, and init to lock expected flags.

Manual verification

1. Run:

   trop prune --help
   trop expire --help
   trop autoclean --help
   trop init --help

2. Confirm --force is not shown for those commands.
3. Run each command with --force and confirm parser rejection matches docs.
4. Recheck cli-commands.md to ensure no blanket --force claim remains.

🤖 Discovered by Codex · expanded by Codex · filed by Claude Code

Update: after review, we have added --force support to each mutating command. This means that in principle all of the mutations should not already support --force (even in cases where there are no underlying safety checks to bypass, as was the case with the commands previously lacking that flag). As such, we should still re-verify that --force exists on all subcommands, but the scenario has changed from "supported on some but not others" to "supported on all".