BREAKING: canonical --timeout everywhere; remove prepare --force alias

[NicolasSchuler]

BREAKING CHANGES

This PR intentionally breaks CLI backward compatibility (approved): the old
timeout flag spellings and the deprecated prepare --force alias are removed
outright, with no hidden aliases and no deprecation period. Stacked on #62
(feat/cli-contract-nits).

1. Timeout flags: one canonical --timeout <DURATION>

Every per-command "give up after this long" flag is now spelled --timeout and
takes a DURATION string (30s, 5m, 1h, or a bare number of seconds). Each
command's effective default is unchanged.

Command	Before	After	Default (unchanged)
test	--wait-timeout <DURATION> (hidden alias --timeout)	--timeout <DURATION>	180s
notebook	--ready-timeout <DURATION>	--timeout <DURATION>	10m
germinate	--pending-timeout <DURATION>	--timeout <DURATION>	30m
when	--timeout <DURATION>	unchanged	none
sweep observe	--timeout <DURATION>	unchanged	none
doctor mpi-smoke	--timeout-seconds <SECONDS> (raw u64)	--timeout <DURATION>	5m (= previous 300)
doctor fabric-smoke	--timeout-seconds <SECONDS> (raw u64)	--timeout <DURATION>	5m (= previous 300)
doctor readiness	--timeout-seconds <SECONDS> (raw u64, optional)	--timeout <DURATION> (optional)	none
doctor (hidden legacy flag interface)	--timeout-seconds (hidden)	--timeout (hidden, DURATION)	5m

Migration one-liners

# test
hpc-compose test --submit --wait-timeout 180s   ->  hpc-compose test --submit --timeout 180s
# notebook
hpc-compose notebook --ready-timeout 10m        ->  hpc-compose notebook --timeout 10m
# germinate
hpc-compose germinate --pending-timeout 30m     ->  hpc-compose germinate --timeout 30m
# doctor (DURATION still accepts a bare number of seconds)
hpc-compose doctor mpi-smoke --timeout-seconds 300  ->  hpc-compose doctor mpi-smoke --timeout 300   # or --timeout 5m

2. prepare --force removed

The hidden deprecated alias for prepare --force-rebuild is gone;
prepare --force is now an unknown-flag error (with clap's
"a similar argument exists: '--force-rebuild'" tip, pinned by a new test).
--force now means only "overwrite the output file" (new/evolve)
everywhere in the CLI.

hpc-compose prepare --force  ->  hpc-compose prepare --force-rebuild

Also in this PR

• CHANGELOG entries under ## [Unreleased] (### Changed + ### Removed,
  both marked BREAKING, with the before/after table). The pending 0.1.53
  section from Cut v0.1.53 release #63 is untouched.
• Docs updated (docs/src/cli-reference.md, docs/src/notebook.md) and man
  pages regenerated for the six affected pages; gen-manpages --check passes
  after regen (help-text changes here are deliberate).
• Error messages updated (test --timeout is invalid,
  germinate --timeout is invalid, doctor --timeout '...' must be like 30s or 5m,
  doctor ... --timeout must be at least 1s when --submit is used).

Gates

• cargo test --locked (full): pass
• cargo clippy --all-targets --locked -- -D warnings: pass, no issues
• cargo fmt --all -- --check: pass
• manpage regen + gen-manpages -- --check: pass
• docs gates on touched files: mdbook build pass, typos pass,
  markdownlint-cli2 no new findings (repo baseline unchanged), lychee all
  links OK except a sandbox DNS block on a pre-existing external URL

Verified end-to-end against the built binary: all six --help outputs show
--timeout <DURATION> with the preserved defaults, invalid durations produce
the new error messages, and prepare --force fails with the
--force-rebuild tip.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes intentional, breaking CLI contract changes by standardizing all “give up after this long” flags to a single canonical --timeout <DURATION> spelling and fully removing the deprecated prepare --force alias, then updates tests, docs, changelog, and man pages accordingly.

Changes:

• Canonicalize per-command timeout flags to --timeout <DURATION> (including migrating doctor subcommands from --timeout-seconds to --timeout).
• Remove the deprecated hidden prepare --force alias so --force only means “overwrite output file” for new/evolve.
• Regenerate/update user-facing docs (mdbook + manpages) and adjust integration tests to pin the new CLI behavior.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/cli_runtime.rs	Updates notebook timeout tests to use --timeout and expect the new flag name in errors.
tests/cli_init.rs	Migrates doctor CLI integration tests from --timeout-seconds N to --timeout Ns.
tests/cli_canary_rendezvous.rs	Switches germinate tests from --pending-timeout to --timeout and updates expected error strings.
tests/cli_cache.rs	Adds a regression test asserting prepare --force is now rejected and suggests --force-rebuild.
src/spec/mod.rs	Updates parse_short_duration docs to reference notebook --timeout.
src/output/tests.rs	Removes now-deleted force_deprecated field from a prepare-related test setup.
src/commands/runtime/mod.rs	Renames test command’s wait-timeout parameter to timeout and updates parse error context.
src/commands/runtime/germinate.rs	Renames germinate’s pending-timeout parameter to timeout and updates parse error context.
src/commands/mod.rs	Wires renamed CLI fields through dispatch; introduces parse_doctor_timeout and updates notebook timeout parsing context.
src/commands/doctor.rs	Updates doctor validation error messages to reference --timeout and 1s semantics.
src/cli/commands.rs	Removes prepare --force alias, converts doctor timeouts to --timeout <DURATION>, and standardizes test/notebook/germinate to --timeout.
man/man1/hpc-compose-test.1	Updates manpage flag from --wait-timeout to --timeout.
man/man1/hpc-compose-notebook.1	Updates manpage flag from --ready-timeout to --timeout.
man/man1/hpc-compose-germinate.1	Updates manpage flag from --pending-timeout to --timeout.
man/man1/hpc-compose-doctor-readiness.1	Updates manpage flag from --timeout-seconds to --timeout <DURATION>.
man/man1/hpc-compose-doctor-mpi-smoke.1	Updates manpage flag and default from --timeout-seconds 300 to --timeout 5m.
man/man1/hpc-compose-doctor-fabric-smoke.1	Updates manpage flag and default from --timeout-seconds 300 to --timeout 5m.
docs/src/notebook.md	Updates notebook documentation to reference --timeout instead of --ready-timeout.
docs/src/cli-reference.md	Updates CLI reference examples and option docs to the canonical --timeout spelling.
CHANGELOG.md	Adds BREAKING “Changed/Removed” entries documenting timeout canonicalization and removal of prepare --force.