feat(pipeline): codebase health analysis step — forge-aware repository state artifact

[nextlevelshit]

Parent: #184

Summary

Implement a codebase health analysis pipeline step that produces a structured artifact describing the current state of a repository. This step performs forge-aware analysis (GitHub/Bitbucket/GitLab/Gitea) covering recent commit history, open PR status (including review state, comments, triage), open issues with actionable categorization, and code health metrics. The output artifact follows the existing inject_artifacts pattern and is the primary input for the pipeline proposal engine.

Acceptance Criteria

• Health analysis step produces a structured JSON artifact with well-defined schema
• Artifact includes recent commit history analysis (frequency, authors, areas of activity)
• Artifact includes open PR status: count, review state, comment activity, staleness
• Artifact includes open issue summary: count, categories, actionable items, priorities
• Artifact includes basic code health signals (test pass rate if available, recent CI status)
• Analysis is forge-aware — uses correct API (gh, glab, tea, or Bitbucket REST) based on detected forge type
• GitHub (gh) forge path is fully implemented as the primary target
• Other forge paths (bb, gl, gt) have stub implementations with clear TODO markers
• Artifact schema is documented and validated via contract
• Step integrates with the existing artifact injection system (inject_artifacts)

Dependencies

• feat(preflight): extend system readiness checks for wave run wave pre-flight #206 — System readiness checks (forge CLI must be validated before health analysis runs)

Scope Notes

• In scope: Forge-aware API calls to gather repository state, structured artifact output, contract schema for the artifact, GitHub as primary implementation target
• Out of scope: Deep static analysis of source code (e.g., complexity metrics, dependency audits), performance profiling, security scanning — these are separate pipeline concerns
• Design note: The artifact must be machine-parseable (JSON) so the proposal engine can consume it programmatically; human-readable markdown summaries are optional additions

[nextlevelshit]

Revival Update (March 2026)

Audit Findings

What exists in internal/tui/health_provider.go:

• ✅ Infrastructure health: git status, adapter availability, DB, config, tools, skills
• ✅ GitHub info fetching via FetchGitHubInfo() in header_provider.go (issue counts, gh auth check)

What does NOT exist:

• ❌ PR status analysis (review state, comments, staleness)
• ❌ Issue categorization and prioritization
• ❌ Recent commit history analysis
• ❌ CI/CD status integration
• ❌ Structured artifact output (JSON schema, consumable by proposal engine)
• ❌ Multi-forge API support (only GitHub via gh CLI)

Revised Scope

This issue is about codebase health (what's happening in the repo), not infrastructure health (are tools installed) — that's #206.

The output should be a JSON artifact with:

{
  "forge": "github",
  "repo": "re-cinq/wave",
  "prs": { "open": 3, "needs_review": 1, "approved": 2, "stale": 0 },
  "issues": { "open": 7, "high_priority": 2, "actionable": 4 },
  "activity": { "last_commit": "4h ago", "active_branches": 3 },
  "ci": { "status": "passing", "last_run": "2h ago" }
}

Implementation approach:

1. GitHub: use gh api (already authenticated per header_provider.go)
2. Other forges: stub implementations with clear TODO markers
3. Wire into wave doctor output and wave suggest input

Revised Size: M (was L)

The GitHub path is mostly gh api calls and JSON parsing. Previous PR #217 was closed without merging.

[nextlevelshit]

Implementation Update (March 2026)

Current status: Being implemented

Codebase health analysis is now part of wave doctor:

• internal/doctor/codebase.go — AnalyzeCodebase() queries forge API for PR status (open, needs review, stale), issue status (open, poor quality, unassigned), and CI status (recent runs, failures)
• Currently GitHub-only implementation via gh CLI
• Output is rendered in wave doctor text output and available via --json

Relationship to #296

The new #296 (AI-steered project optimization) produces a project profile artifact that complements this issue's codebase health artifact. Together they give the proposal engine (#208) both "what is the project" (language, build system, conventions) and "what state is the project in" (PRs, issues, CI health).

Previous attempt

PR #217 was closed without merging. Fresh implementation is simpler — integrated into doctor rather than a separate pipeline step.

[nextlevelshit]

Implemented as part of wave doctor. internal/doctor/codebase.go provides forge-aware codebase analysis (PRs, issues, CI) via AnalyzeCodebase(). GitHub path fully implemented, other forges return nil gracefully.