Forge-cli v1 Sprint 8: wrapper + completion sync + README crosslink

[graysurf]

Summary

Sprint 8 of the forge-cli v1 plan is the final implementation milestone: ship forge-cli as a first-class workspace binary with the same wrapper / completion / brew install path the other CLIs use. After this PR merges, Task 8.3 (nils-cli minor bump + tap formula bump) runs through the existing nils-cli-bump-version-tag-release skill as a post-merge release action.

Changes

• wrappers/forge-cli (new) — bash wrapper mirroring wrappers/git-cli line-for-line. Three modes via NILS_WRAPPER_MODE: installed (resolve via $HOME/.local/nils-cli/forge-cli then PATH), debug (always cargo run -q -p nils-forge-cli), auto (installed first, cargo fallback). The bump skill that ships git-cli picks forge-cli up automatically because the wrapper layout is identical.

• crates/forge-cli/tests/integration/completion_sync.rs (new) — 4 tests pin the completion contract:

  1. forge-cli completion bash succeeds, non-empty, contains _forge-cli marker.
  2. forge-cli completion zsh succeeds, non-empty, contains #compdef forge-cli marker.
  3. completions/bash/forge-cli is byte-equal to the live binary output.
  4. completions/zsh/_forge-cli is byte-equal to the live binary output.

  Tests (3) and (4) fail loudly when a new flag is added but the snapshot isn't regenerated, with the error message telling the contributor exactly which command to run.

• README.md — workspace cross-link. Added a Forge automation | forge-cli row to the CLI surface map and a crates/forge-cli entry in the Git-tooling section so brew users discover the new binary alongside git-cli, git-scope, git-summary, git-lock.

• Execution ledger — docs/plans/forge-cli/forge-cli-execution-state.md records Tasks 8.1 + 8.2 as completed. Task 8.3 (nils-cli minor bump + tag + tap formula bump) is the only remaining row and runs post-merge through the existing nils-cli-bump-version-tag-release skill — it is intentionally NOT bundled into this PR per Sprint 8's plan.

Test-First Evidence

• Change classification: new feature (final v1 release prep for forge-cli).
• Failing test before fix: not applicable.
• Final validation:
  • cargo test -p nils-forge-cli — 219 lib + 93 integration green (was 219 + 89 at end of Sprint 7).
  • cargo clippy -p nils-forge-cli --all-targets -- -D warnings — clean.
  • bash scripts/ci/completion-asset-audit.sh — pass.
  • bash scripts/ci/completion-flag-parity-audit.sh — pass.
  • bash scripts/ci/cli-output-contract-lint.sh — pass.
  • bash scripts/ci/forge-cli-fixture-lint.sh --strict — pass.
  • bash scripts/ci/docs-{hygiene,placement}-audit.sh — pass.
  • NILS_WRAPPER_STATUS_HINTS=0 wrappers/forge-cli --help — produces the canonical help output.
• Waiver reason: n/a.

Testing

• pass: cargo test -p nils-forge-cli (312 total).
• pass: cargo clippy -p nils-forge-cli --all-targets -- -D warnings.
• pass: workspace CI gates (completion-asset, completion-flag-parity, cli-output-contract, fixture-lint, docs-hygiene, docs-placement).
• not run (post-merge): brew tap formula bump + nils-cli minor version bump — runs through nils-cli-bump-version-tag-release after this PR merges.

Risk / Notes

• The wrapper's runtime contract (env vars, mode names, exit codes) is copied verbatim from wrappers/git-cli, so the brew tap install hooks pick it up without any tap-side change. The actual tap formula bump still happens via nils-cli-bump-version-tag-release.
• The completion-sync test guards the most common drift source for completion-aware binaries: a contributor adds a flag in cli.rs but forgets to regenerate the static completions/{bash,zsh}/ snapshots. The test message gives them the exact regen command.
• This PR closes the v1 implementation surface. The next step is Task 8.3 (release flow) which is intentionally a separate action invoked by the bump skill against main once this merges.

[github-actions]

Coverage

Total line coverage: 85.44% (75426/88276 lines hit).