feat: multi-install cleanup + upgrade discoverability

[CybotTM]

Closes the gap where make upgrade warns about duplicate installs but offers no
way to act, and where the existing bulk-upgrade commands are undiscoverable.
Design: docs/superpowers/specs/2026-07-08-reconcile-and-upgrade-discoverability-design.md.

What changed

audit.py --reconcile (new CLI over the existing reconcile.py engine)

• --reconcile <tool> reports the plan: per-install version, which install
  is active on PATH (the default when called without a path), and which is
  preferred (kept). --apply removes the non-preferred duplicates
  (aggressive mode, honoring the system-tool safelist). --all sweeps the full
  catalog. JSON via CLI_AUDIT_JSON=1.
• Fixes reconcile_tool to resolve catalog candidates when a caller omits them,
  so alternate-named duplicates (pip/pip3, fd/fdfind) are caught in bulk sweeps.
  Previously bulk_reconcile only looked at config.tools (5 tools); the sweep
  now finds all of them (37 on the author's machine).

Guide (scripts/guide.sh)

• The ⚠️ Multiple installations listing now shows version + → active +
  ✓ keep per install, and notes when cleanup would change which binary runs.
• New inline c = clean up duplicates action (confirms, then applies).

Make targets

• make reconcile-all (confirm-each) and make reconcile-all-dry-run (plan only).

Discoverability + safety

• Audit readiness line and guide summary hint at make reconcile-all (when
  duplicates exist) and make upgrade-managed.
• auto_update.sh warns that native manager upgrades bypass cli-audit pins and
  project lockfiles before running (skipped on dry-run / FORCE=1).

Example

⚠️  Multiple installations detected (2):
   • 4.44.3  manual  /home/sme/.local/bin/yq   → active  ✓ keep
   • 4.40.1  manual  /usr/local/bin/yq

Verification

• pytest: 644 passed, 1 skipped (+10 new reconcile-CLI tests; +1 shell
  guard test that the dry-run target never passes --apply).
• Gating flake8 (E9,F63,F7,F82): clean. Smoke: pass. mypy: no new errors.
• test_guide_multi_install.sh: unchanged (same 3 pre-existing failures on
  main; no regression).
• make reconcile-all-dry-run verified non-destructive; --all sweep + render
  markers verified against real duplicates.

Safety model: confirm-each + dry-run; nothing removed without explicit yes;
critical-tools protect list honored; removing the active install gets an extra
heads-up. No version bump / CHANGELOG (feature branch).

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

❌ Patch coverage is 95.91837% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.45%. Comparing base (f03b57e) to head (46660c9).

Files with missing lines	Patch %	Lines
cli_audit/reconcile.py	95.55%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #101      +/-   ##
==========================================
+ Coverage   71.33%   72.45%   +1.12%     
==========================================
  Files          22       22              
  Lines        3359     3402      +43     
==========================================
+ Hits         2396     2465      +69     
+ Misses        963      937      -26     

Flag	Coverage Δ
unittests	72.45% <95.91%> (+1.12%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request introduces multi-install cleanup and upgrade discoverability features, adding new make targets (reconcile-all and reconcile-all-dry-run), CLI arguments, and interactive prompts in the guide to resolve duplicate tool installations. The review feedback highlights two important issues: a thread-safety race condition in _resolve_candidates when resolving candidates concurrently, and an incorrect exit code logic in cmd_reconcile that incorrectly treats expected blocks on protected tools as execution failures.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR adds a first-class “reconcile duplicate installs” flow across the CLI (audit.py --reconcile), the interactive guide, and Make targets, with additional discoverability hints and safety prompts to help users clean up multi-installs and find bulk-upgrade functionality.

Changes:

• Introduces audit.py --reconcile (plan + optional --apply) wired to the existing cli_audit.reconcile engine, plus catalog-candidate resolution for alternate binary names.
• Enhances scripts/guide.sh to render richer multi-install warnings (version/active/keep) and adds an inline cleanup action (c), plus summary hints.
• Adds make reconcile-all / make reconcile-all-dry-run, a pin/lock override warning in auto_update.sh, and new tests/docs to cover the safety-critical boundary.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
audit.py	Adds --reconcile command routing and plan/apply JSON/human output.
cli_audit/reconcile.py	Adds catalog-candidate resolution to detect alternate-named duplicates.
cli_audit/render.py	Prints discoverability hints for reconcile/upgrade-managed.
scripts/guide.sh	Renders reconcile-based multi-install details and adds inline duplicate cleanup action.
scripts/auto_update.sh	Adds an interactive warning that native manager upgrades bypass pins/lockfiles.
Makefile.d/user.mk	Adds reconcile-all and reconcile-all-dry-run targets.
Makefile	Exposes new reconcile-all targets in the top-level target list.
tests/test_reconcile_cli.py	Adds unit tests for reconcile plan shaping, candidate resolution, and JSON output.
tests/test_reconcile_dryrun.sh	Adds a shell test guarding that dry-run targets never pass --apply.
docs/superpowers/specs/2026-07-08-reconcile-and-upgrade-discoverability-design.md	Adds the design spec documenting goals, safety model, and UX expectations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated no new comments.

[sonarqubecloud]

Quality Gate passed

Issues
16 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube Cloud