doc-impact

You are working on **doc impact** — the command that shows whether generated agent context is keeping up with the codebase, optionally interprets results via LLM, and can interactively apply recommended repairs.

## Domain purpose
Audits the agent context generated by aspens against the live source tree, reports per-target health (Claude, Codex), and offers an interactive `--apply` flow that re-runs the right `aspens doc init/sync` variant to repair gaps. The LLM interpretation is a thin layer on top of deterministic metrics — the metrics are the contract.

## Business rules / invariants
- **Target inference:** If `.aspens.json` is absent, targets are inferred from scan results (`.claude/` → claude, `.agents/` → codex). Falls back to `['claude']`.
- **LLM is optional and tool-less.** Runs only when a CLI backend is detected. `runLLM` is invoked with `disableTools: true`; prompt must return pure JSON (`bottom_line`, `improves`, `risks`, `next_step`). Failure is caught and reported as "Analysis unavailable" — never fatal.
- **Graph failure is non-fatal.** If `buildRepoGraph` throws (or `--no-graph` is passed), `graph` is `null` and hub coverage is skipped/`n/a`.
- **Hub coverage haystack is the code-map, not CLAUDE.md.** Post-Phase 1, `## Key Files` no longer lives in root instructions. `computeHubCoverage` reads `.claude/code-map.md` (claude) or `.agents/skills/architecture/references/code-map.md` (codex). If the code-map file is missing, it reports `codeMapMissing: true` instead of spurious "missing hub" warnings. Older callers without `repoPath` fall back to the legacy `contextText` haystack.
- **Health score deductions** (start 100): missing instructions −35; no skills −25; domain gaps proportional up to −25; missed hubs −4 each; drift −3 per file (cap −20); unhealthy hooks −10 (hook-capable targets only); broken save-tokens −5 (claude only).
- **`LOW_SIGNAL_DOMAIN_NAMES`** (`config`, `test`, `tests`, `__tests__`, `spec`, `e2e`) are excluded from coverage scoring but tracked in `excluded`.
- **`SOURCE_EXTS`** extends the scanner set with `.scala`, `.clj`, `.elm`, `.vue`, `.svelte` for drift detection. Adding a language for drift requires updating this set.
- **Walk depth capped at 5** — deep nested source files won't appear in drift analysis.

## Non-obvious behaviors
- **Agent skill-ref check (Phase 6):** `checkAgentSkillReferences()` scans `.claude/agents/*.md` frontmatter for `skills: [a, b]` and verifies each `.claude/skills/<name>/skill.md` exists. Broken refs surface as `agent-skill-refs` opportunities.
- **Save-tokens health is Claude-only** and only activates when `config.saveTokens.enabled` is true and `claude.enabled !== false`. Required hook/command files vary by sub-config (`saveHandoff`, `warnAtTokens`/`compactAtTokens` thresholds). Legacy `.mjs` siblings of the `.sh` hooks must be cleaned up — their presence is an issue.
- **`buildApplyPlan` dedupes** with `aspens doc sync` as a target-agnostic key; everything else is keyed `${target.id}:${action}`.
- **`applyRecommendedAction` is a hand-maintained dispatch table** mapping action strings to `docInitCommand`/`docSyncCommand` option shapes. Adding a new recommendation in `recommendActions()` requires a matching branch here, otherwise it warns "Cannot apply automatically".

## Critical files (purpose, not inventory)
- `src/commands/doc-impact.js` — CLI rendering, LLM prompt assembly, `buildApplyPlan`, and the action dispatch into `docInitCommand`/`docSyncCommand`.
- `src/lib/impact.js` — All deterministic analysis (`analyzeImpact`, target summarization, scoring, drift, hub/code-map coverage, hook/save-tokens health, opportunities, missing rollup, value comparison).
- `src/prompts/impact-analyze.md` — Strict JSON contract the LLM must honor; do not change shape without updating `parseAnalysis`.

## Critical Rules
- Skills/`activationPatterns` are matched via `findMatchingSkill` (substring or `/domain/` path hit). Renaming the skill-reader contract breaks coverage scoring.
- Don't surface root-context hub warnings when `codeMapMissing` is true — emit the `code-map-missing` item instead and tell the user to run `aspens doc graph`.
- Exported surface used by tests/consumers: `computeDomainCoverage`, `computeHubCoverage`, `computeDrift`, `evaluateHookHealth`, `evaluateSaveTokensHealth`, `computeHealthScore`, `computeTargetStatus`, `recommendActions`, `summarizeReport`, `summarizeMissing`, `summarizeOpportunities`, `summarizeValueComparison`, `checkAgentSkillReferences` from `impact.js`; `buildApplyPlan`, `buildApplyConfirmationMessage` from `doc-impact.js`.

---
**Last Updated:** 2026-05-11