befund-arch-health

befund-arch-health

Judge the real stage/wire dependency graph for structural deficiencies.

Step 0: Settings gate, then the stage_graph prerequisite

python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" check-enabled --repo <repo_root> --skill befund-arch-health

Check whether <output_dir>/stage_graph.json exists. If it does not, this skill degrades to Ready-with-gaps -- write a short ARCH_HEALTH.md and an arch_health_summary.json with empty findings and a note that befund-stage-map has not run, then stop:

{"findings": [], "note": "befund-stage-map has not run; no stage_graph.json to analyze"}

This is a degrade, not an error: do not fail the skill invocation, just produce a minimal, honest artifact.

Step 1: Read the full graph

Read stage_graph.json in full -- never the sampled viewer-format stage_map.json. Fan-in and fan-out numbers must come from the complete graph.

Step 2: Find deficiencies mechanically, then confirm against code

Use the graph helpers for the two structural checks that have precise definitions:

python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" find-cycles --stage-graph <path to stage_graph.json>
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" find-god-modules --stage-graph <path to stage_graph.json>

find-cycles only returns strongly-connected components of size >= 2 (rule cycle-definition-in-graph) -- a pair of stages that merely both import a shared third stage is not a cycle, and the Tarjan-based implementation will not report it as one. find-god-modules flags stages whose fan-in crosses the documented ratio-of-other-stages threshold (see README "Design decisions" for the exact constant, since the spec leaves the numeric cutoff to this plugin's judgment).

Before dispatching arch-health-auditor, resolve the shared symbol-index snapshot the same way befund-lint-audit does: read analysis/befund/current.json; if missing or its source_fingerprint no longer matches, run

python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_symbol_index.py" --repo-path . --plugin-name befund

(single-flight lock makes concurrent callers safe -- see references/parallel-safe-research-protocol.md). For a repo well under ~50 tracked files the build overhead may not be worth it -- skip this and dispatch without it.

Dispatch arch-health-auditor to confirm each mechanically-flagged candidate against the actual source before it becomes a finding -- a high-fan-in stage that is a legitimate shared kernel (e.g. a types/errors package everything imports) is not a god-module, and the agent's own refusal list covers exactly this case. When the snapshot is available, pass its path to the agent as additional evidence. Layering violations (a production stage importing a test-only/fixture/example stage) have no purely structural signature in the graph alone -- confirm each one by reading the importing stage's actual role.

Step 3: Validate and write

Unless skip_verification is set, every finding must carry verified: true/false from Step 2 before reaching here.

python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" validate-artifact --kind arch_health_summary --file <path-or-inline-json>

The validator rejects any type outside {god-module, cycle, layering-violation} and any cycle finding whose members list has fewer than 2 entries. The artifact wraps the per-finding shape arch-health-auditor already returns (see that agent's "Output format" section) in a top-level findings array: {"findings": [<agent findings>]}.

python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename ARCH_HEALTH.md
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename arch_health_summary.json

Read-only constraint

Never use Write/Edit outside the resolved output paths. Never refactor, split, or merge a stage here -- that is befund-transform-brief's planning step and befund-transform- execute's (separately gated) execution step.