fix(complete): offer --help and --version when completing flags - #1605

### 🚀 Features

- **(go)** refuse undeclared environment variables in generated parsers
by [@jdx](https://github.com/jdx) in
[#1612](#1612)
- **(spec)** let a flag with setting declare its setting by
[@jdx](https://github.com/jdx) in
[#1610](#1610)
- **(spec)** refuse unknown environment variables under an application
prefix by [@jdx](https://github.com/jdx) in
[#1609](#1609)

### 🐛 Bug Fixes

- **(complete)** offer --help and --version when completing flags by
[@jdx](https://github.com/jdx) in
[#1605](#1605)
- **(spec)** let a flag inside a clause set its setting by
[@jdx](https://github.com/jdx) in
[#1611](#1611)

### 📚 Documentation

- **(contributing)** remove the AI reply restriction by
[@jdx](https://github.com/jdx) in
[#1602](#1602)

### 🔍 Other Changes

- set up jouet for agents by [@jdx](https://github.com/jdx) in
[#1603](#1603)

usage 7.2.0 (jdx/usage#1605) offers -h/--help in tab completion, so
completing after a task name lists the task's own --help too. The test
installs the latest usage, which broke it on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
AI-Assisted: Tool: Claude Code; model: unavailable; version: 2.1.309
Entire-Checkpoint: 01M6HXCENTKM8Z0YS2DTVQ2FDM

The v2026.11.0 docs deploy went out without the landing-page showreel,
and the run only logged a warning. The showreel job's captures failed
against mise 2026.11.0, and the cache had no earlier render to fall back
to. The docs job then built and deployed the site without the reel, so
mise.jdx.dev lost its homepage video without anyone being told.

Trusted docs runs outside pull requests (releases, pushes to main,
`workflow_dispatch`) now fail instead of building the site without a
reel:

- **The showreel job did not succeed** (failed, or dropped from the
`docs-showreel-volume` queue). The step that used to warn now errors
with the job's result.
- **The showreel job left no render.** "Put the showreel in place"
errors instead of carrying on.
- **The site builds only with the reel removed.** The second build that
dropped the reel is gone, so a failed build fails the job.

Unchanged:

- When a render fails, the showreel job still restores the last good
render from the cache. A stale reel still counts as a reel.
- Pull-request and untrusted runs don't run the showreel job and still
build without one.

Tradeoffs:

- **Releases fail until the reel renders again.** The captures failures
(C8, C14, C17 against 2026.11.0) are being fixed separately, so until
that lands, every release's docs deploy will fail.
- **A dropped showreel job now fails the deploy.** The showreel job
shares one Namespace volume, and GitHub keeps only the newest waiting
job for it. A release whose showreel job is dropped that way now fails,
and a rerun once the volume is free deploys it.

Also in this PR: `e2e/tasks/test_task_completion_global_flags` now
expects a task's own `--help` after the task name (`mise run deploy
--<TAB>` offers `--bump`, `--env`, `--help`, `--output-dir`). usage
7.2.0 (jdx/usage#1605) added `-h`/`--help` to tab completion. The test
installs the latest `usage`, so main started failing it, and `mise run
deploy --help` does print the task's usage.

Validation: `hk run check` (jactionlint, oxfmt, shellcheck, shfmt)
passes on the changed files, and the completion test passes against
usage 7.2.0. The workflow change itself runs only on trusted runs, so I
haven't run it.

*AI-assisted — Tool: Claude Code 2.1.309; model:
anthropic/claude-opus-5-5; version: unavailable.*

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes production docs deploy gates: trusted releases and main
deploys fail until a showreel render exists or is restored from cache,
which is intentional but can block shipping until capture/render issues
are fixed.
> 
> **Overview**
> Trusted docs deploys (main, releases, dispatch—not PRs) **no longer
ship mise.jdx.dev without the homepage showreel**. When the showreel job
fails, is dropped from the shared volume queue, or leaves no
`showreel.mp4`/poster, the docs job **errors and exits** instead of
logging a warning and building anyway.
> 
> The workflow drops the **second “build without the showreel” path**
and the build step’s `continue-on-error` retry; **`docs:build` runs
once** and a missing reel fails the run. Comments now distinguish
showreel-stage soft failures (keep last cached render) from hard
failures before the cache mount.
> 
> **`xtasks/docs/showreel`** comments align with that contract, and
restoring **`showreel-chapters.vtt`** uses the same atomic partial-file
copy as other public assets.
> 
> The **e2e completion test** expects **`--help`** after the task name
for `mise run deploy --`, matching usage 7.2.0 tab completion.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8cdd729. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **Documentation**
* Clarified that a docs deployment fails if no rendered showreel is
available.
* **Bug Fixes**
* Trusted docs builds now fail when showreel setup fails or required
render files are missing. Builds run once and no longer retry without
the showreel, while still using the last successful render as a fallback
when available.
* Task command completions now include `--help`; existing options such
as `--bump`, `--env`, and `--output-dir` remain available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

This adds `usage-help-completion-pr`, an opt-in whole-PR session task on
real usage code, built like `pitchfork-worktree-pr`. Whole-PR sessions
are where jouet wins most clearly (−36 to −46% input tokens on
pitchfork), and the bench had none on usage, which mixes Rust and Go.

The agent starts at the first push (f127151) of
[jdx/usage#1605](jdx/usage#1605). That PR makes
shell completion offer `--help` and `--version`, which the parser
answers without a declaration. The fake GitHub serves that push's real
`trusted / test` log and the six real review threads posted on it.

| thread | asks | expected |
|---|---|---|
| greptile | the Go runtime offers the same supplied flags (the CI
failure) | fix, reply, resolve |
| greptile | `SpecCommand::merge` overwrites again, so an included
`#false` restores help; the stay-disabled rule moves to `mount` | fix,
reply, resolve |
| greptile + coderabbit | an executable view of a versioned root offers
`--version`/`-V` | fix, reply, resolve (both) |
| coderabbit | `complete-word` adds the supplied flags before the
default command's | fix, reply, resolve |
| coderabbit | a flag awaiting a value completes `--help` as a value |
upstream declined it; reply |

**Why it is a fair whole-PR task**
- The CI failure reproduces locally: after `cargo build`, `go test
./...` in `go/` fails `TestTheCursorGetsTheReferencesAnswer` exactly as
the log shows. The Go suite compares `go/argv` with the `usage` binary
in `target/debug`.
- The fix spans four files in three crates plus Go:
`argv/src/complete.rs`, `cli/src/cli/complete_word.rs`,
`lib/src/spec/cmd.rs` and `go/argv/complete.go`. The reference fix is
upstream's 7eb1d6e and 343a135.
- Upstream added no tests for the review fixes, so the task has five
hidden tests of its own. Each pins only what a thread states:
- an include's `disable_help_flag`, `disable_help_subcommand` and
`disable_version_flag #false` win;
  - a mount still keeps the switches the command turned off;
  - a view of a versioned root offers `--version` and `-V`;
  - the root still offers `--version` only once;
- with `default_subcommand_flags`, a hidden `--help` on the default
command does not hide the root's.
- Each part fails on its own: without the Go change, only `go test`
fails; without the Rust changes, only the hidden tests fail.

**What the check requires**
- a new commit, with no tracked file left uncommitted (`mise.lock` is
ignored);
- `go test ./...` passes;
- `cargo test --all --all-features` passes (one retry, since the shell
integration tests can time out under load);
- the five hidden tests pass;
- the five threads above are replied to and resolved, and the declined
one has a reply.

No push is required.

**Where it differs from the real PR**
- Later pushes and their threads are left out.
- The CI log is trimmed to the end of the test job.
- The fake run has two jobs: `trusted / msrv` passes and `trusted /
test` fails.

**Setup**
- a clone at `~/src/usage` (base 9c84621 is on main);
- Cargo dependencies in `~/.cargo` and Go modules in `~/go/pkg/mod`,
since builds run offline (`CARGO_NET_OFFLINE`, `GOPROXY=off`,
`GOTOOLCHAIN=local`);
- Go 1.27.3 (usage's pin) installed by mise at
`~/.local/share/mise/installs/go/1.27.3`.

The per-run timeout is 3600 s and the check timeout 1800 s. The cost
seed is `cargo build`, `go test -C go ./...` and `cargo test --all
--all-features`. `docs/benchmarks.md` has a paragraph for the task.

**Validation**
- `MISE_ENV=bench mise x -- python3 bench/agents.py check-tasks --tasks
usage-help-completion-pr --jouet target/debug/jouet` passes: the check
fails unsolved and passes with `solve.py`, and all five probes get their
expected exit codes. It takes about 4.5 minutes.
- The check was also run by hand on two partial fixes: Go only, and Rust
only. Each failed for its own missing part.
- `mise run test:bench` passes (235).
- No agent pilot was run.

*AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5-5;
version: claude-code_2-1-309_agent.*

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Benchmark-only additions (fixtures, check/solve scripts, hidden tests)
with no production runtime changes in the repo itself.
> 
> **Overview**
> Adds **`usage-help-completion-pr`**, an opt-in bench task that replays
[jdx/usage#1605](jdx/usage#1605): shell
completion should offer parser-supplied **`--help`** / **`--version`**
across Rust, Go, mounts, and views.
> 
> The agent works from a fixed starting commit against a **mock GitHub**
fixture (`github.json`) with a failing **`trusted / test`** log (Go
conformance) and six review threads. **`check.py`** requires a clean
commit, passing **`go test ./...`** and **`cargo test --all
--all-features`**, five **hidden** tests (appended into the repo at
check time), and replies plus resolution on the scripted threads.
**`solve.py`** applies **`fix.patch`** (the upstream-shaped fix in
`argv`, `complete_word`, `lib/spec/cmd`, and `go/argv/complete.go`) and
posts the expected GraphQL replies.
> 
> This is benchmark infrastructure only; it does not change the usage
library in the main tree beyond what agents commit inside the task
workspace.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
7a616a0. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

When a change touches a file outside every crate in a cargo workspace,
`jouet test --affected` used to give up and run the whole suite. Shared
fixture directories hit this case. In jdx/usage,
`corpus/complete/*.json` sits at the workspace root, and the
`usage-conformance` crate reads it through `join("../corpus/complete")`.
Every PR that edits a completion vector therefore ran `cargo test
--workspace`.

Now such a file reaches the crates whose Rust files name it, or a
directory holding it, in a string. Each string with a `/` is resolved as
a path, with `.` and `..` taken out, from the crate's directory
(`join("../corpus/complete")`, or after `CARGO_MANIFEST_DIR` in a
`concat!`) and from the root. Inside `include_str!`, `include_bytes!` or
`include!`, it is resolved from the file's own directory instead. Only
the path it leads to counts, so `"../../corpus/x.json"` from `crates/a`
names `corpus/x.json`, not `crates/corpus/x.json`. A placeholder
(`"../../corpus/{name}.json"`) stands for the rest of the name. Bare
words such as `"corpus"` don't count, and neither do strings that lead
out of the repository. The Rust files are read once per run.

On usage at jdx/usage#1605's first push (f127151):

```
before: cargo cannot trace corpus/complete/01-positions.json to the tests that use it
        would run: cargo test --workspace
after:  21 crates ... usage-conformance: changed ...
        would run: cargo test -p clap_usage -p gate ... -p usage-conformance ...
```

That PR also changes `usage-argv`, which most of the workspace depends
on, so it still selects 21 of 26 crates. A PR that only edits the corpus
now runs `usage-conformance` and the crates that depend on it.

A file that no crate names still runs the whole suite. Tests: unit tests
covering crate-relative, root-relative and `include_str!` names, a
sibling directory, a placeholder, a bare word and a path that resolves
somewhere else. `mise run test:cargo` passes (1,538 tests).

*AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5-5;
version: claude-code_2-1-309_agent.*

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes core Rust workspace test-selection heuristics (static string
parsing can miss dynamic paths or mis-associate edge cases), but
behavior falls back to the full suite when nothing matches.
> 
> **Overview**
> **Cargo affected-test selection** no longer treats every file outside
a workspace member as untraceable. Changes to shared fixture trees (for
example `corpus/` at the repo root) now map to the crates whose sources
reference those paths in string literals, then the usual dependent-crate
expansion still applies.
> 
> The adapter scans tracked `*.rs` files once, extracts path-like
literals (including `include_str!` / `include_bytes!` / `include!`
resolved from the source file, crate-relative and root-relative joins,
and placeholder patterns like `cases/{name}.json`), and caches which
members **read** each path. **`traces`** and **`select`** use this via
**`reached`** instead of only **`owner`**. Unreferenced paths outside
all members still force the full workspace suite; docs now say
whole-suite fallback applies only when **no** member names the file.
> 
> Unit tests cover fixture routing, string-literal parsing, and path
resolution.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
6aa1926. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>