feat(explorer): v0.8.3 Explorer recommendations — categorized findings with impact and actions

[tcballard]

Summary

Implements rac/roadmaps/v0.8.x-explorer/v0.8.3-explorer-recommendations.md.

Adds:

• A recommendations view (/recommendations, or r from the health view): RAC Core's review findings grouped by category, each presenting the finding, why it matters, a suggested action, and navigation to the affected artifact
• Core severities mapped to the three presentation tiers (Critical / Warning / Suggestion)
• A review_from_portfolio seam so Explorer reuses Core's review logic over a loaded repository without a second walk

Roadmap / ADR Trace

Roadmap: rac/roadmaps/v0.8.x-explorer/v0.8.3-explorer-recommendations.md (contract pinned in the first commit)

Relevant ADRs and designs:

• ADR-015 — recommendation logic stays in Core; Explorer presents
• ADR-002 — no AI dependency; recommendations come from deterministic review
• ADR-003 — stable finding shapes
• DESIGN-recommendations, DESIGN-health-model

Scope

Included

• rac.services.review.review_from_portfolio — builds the prioritized review from an already-computed portfolio; build_review delegates to it (byte-identical, golden battery)
• rac.explorer.state.RecommendationRow / RecommendationsState; ExplorerAdapter.recommendations_state() — one recommendation per Core review finding, grouped into the four categories in fixed order
• RecommendationsScreen (multi-line finding → impact → action blocks); /recommendations in the registry; r binding on the health screen; selecting a recommendation opens the affected artifact's context view

Excluded (deliberately)

• Applying changes, rewriting artifacts, or replacing human review (advisory only)
• Recommendation logic in Explorer (ADR-015) — every finding is Core's review output
• AI-dependent behaviour (ADR-002)
• Acting on a recommendation (editor launch, export) — v0.8.4
• No JSON contract movement; existing CLI output byte-identical

Product / Architecture Decisions

• Recommendations are Core's ReviewIssues. The mapping Explorer owns is presentation only: category (by finding code), severity tier (by Core severity), and a fixed impact sentence keyed by the finding code. The impact line is display copy — the same role as Explorer's existing status/phase labels — chosen over adding an impact field to Core's review JSON contract (which the roadmap does not call for).
• Category taxonomy is the fixed vocabulary (Validation, Relationships, Repository Health, Quality); only categories with findings render. "Repository Health" has no review-issue source today (orphan/traceability findings are counts, not per-artifact review items), so it appears only if such a finding type is later added to Core.
• Severity tiers map error → ✗ Critical, warning → ! Warning, info → · Suggestion; definitions stay in Core.
• Attention/recommendation lists are keyed by option index, not artifact path, since several findings may concern one artifact and OptionList ids must be unique.

User-Facing Contract

CLI / Keys

rac explorer        # /recommendations, or h then r

/recommendations (anywhere) · r (health view) → recommendations. Esc backs out. A recommendation + Enter → that artifact's context view.

Human Output (interactive)

Each recommendation renders as a block:

✗ Critical  ·  Validation
  REQ-004  Validation errors: missing-title
  Impact: The artifact fails its schema, so tooling and validation cannot trust it.
  Action: Run: rac validate rac/requirements/req-004.md

JSON Output

No changes; no new contracts.

Exit Codes

Unchanged: 0 session quit · 2 not a directory or missing explorer extra.

Verification

Ran

python -m pytest                      # 733 passed
python -m ruff check src/ tests/
python -m ruff format --check src/ tests/
python -m mypy src/
rac validate rac/                     # exit 0
rac relationships rac/ --validate     # exit 0
rac review rac/                       # no priority 1–2 findings

Covered

• Seam equivalence: review_from_portfolio(...).to_dict() == build_review(...).to_dict() across invalid / broken / clean / mixed fixtures
• Adapter: one recommendation per Core review finding; categories present in fixed order; broken-ref recommendation is ! Warning with a traceability impact and a navigable path; invalid artifact is ✗ Critical; clean repo yields none
• Screens: /recommendations opens the view; r from health opens it and a recommendation opens the context view; /help lists all 8 registry entries
• Registry: recommendations discoverable and parses

Review Path

1. rac/roadmaps/v0.8.x-explorer/v0.8.3-explorer-recommendations.md — the pinned contract
2. src/rac/services/review.py — the review_from_portfolio seam
3. src/rac/explorer/adapter.py — category/severity/impact mapping and recommendations_state
4. src/rac/explorer/screens/recommendations.py — the screen
5. src/rac/explorer/commands.py, screens/command.py, screens/health.py — /recommendations and the r binding
6. tests/ — review, adapter, app, commands
7. docs/cli.md, CHANGELOG.md

Notes For Reviewer

• Stacked on v0.8.2 (PR feat(explorer): v0.8.2 Explorer health — health view, four areas, navigable attention #53); until that merges this PR's diff also shows the v0.8.2 commits. Once feat(explorer): v0.8.2 Explorer health — health view, four areas, navigable attention #53 merges, this narrows to just the v0.8.3 commits.
• The one judgment call worth your eye: the impact sentences are Explorer-side presentation copy keyed by Core finding codes. If you'd rather impact be Core-owned, that's a review-service field addition (a JSON contract change) for a later pass — flagged here rather than done silently.

Implementation Process

Implemented with AI assistance under the roadmap contract.

Final scope, review, and acceptance decisions were made by the maintainer.