befund-stage-map
Extracts the real import/use graph per detected language, clusters files into stages by shallowest package boundary (never by manifest directory), and writes the full stage graph other befund skills depend on. Use when the user asks to "map the repo's architecture", "show me the real module boundaries", "map stages and wires", or as the first step of befund-autopilot's CHECK phase.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- befund-stage-map
- description
- Extracts the real import/use graph per detected language, clusters files into stages by shallowest package boundary (never by manifest directory), and writes the full stage graph other befund skills depend on. Use when the user asks to "map the repo's architecture", "show me the real module boundaries", "map stages and wires", or as the first step of befund-autopilot's CHECK phase.
03 SKILL.md 正文
befund-stage-map
Build the repository's real architectural map: stages (package/module boundaries) and wires (the import/use edges between them), verified against actual source, not guessed from directory names.
Step 0: Settings gate
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" check-enabled --repo <repo_root> --skill befund-stage-map
Stop on non-zero exit. Carry the returned output_dir and skip_verification through every
later step.
Step 1: Detect languages
Reuse the same detection as preflight -- do not hand-roll a different threshold:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" detect-languages --manifests <json> --extension-counts <json>
Step 2: Extract the import graph, one inline command per language
Dispatch the stage-mapper agent once per detected language. Each dispatch runs the
extraction as a single inline read-only command (e.g. a grep -rn / rg pass over
import statements, or a language-native AST dump), never by creating scratch files -- that is
the agent's own refusal, restated here so the calling skill does not ask for anything that
would violate it.
Cluster files into stages by the shallowest importable package boundary in each language
(the topmost directory that is itself an importable unit -- a directory with an __init__.py,
a package.json, a go.mod, etc.) -- never by "which directory does the manifest that covers
this file live in," which is wrong whenever two packages share one manifest.
Step 3: Verify candidate wires
Unless skip_verification is true, verify every candidate wire (an edge between two stages) by
re-reading the actual import statement at its cited location before it is trusted -- do not
accept a wire based on the extraction pass alone. Label unverified findings per
skip-verification-behavior when skip_verification is true (no adversarial refutation, but
every finding still carries verified: false).
Step 4: Write the full graph, never sampled
Rule stage-graph-vs-stage-map-json requires stage_graph.json to carry the complete edge
count, not a sample -- befund-arch-health depends on accurate fan-in/fan-out. Build it
with top-level stages, wires (every edge), edgeCount (== len(wires)), and deadEnds
(stages with no outgoing wires), then validate before writing:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" validate-artifact --kind stage_graph --file <path-or-inline-json>
The validator rejects the artifact outright if edgeCount != len(wires) -- a sampled edge list
cannot pass. The separate viewer-format stage_map.json (for STAGE_MAP.html) MAY sample down to
a handful of edges per stage for readability; only stage_graph.json carries this constraint.
Step 5: Write file_stage_index.json -- deliberately partial
Rule file-stage-index-partial-coverage: this flat {file: stage} lookup MUST contain only
files that are BOTH an edge endpoint AND fall under a detected package boundary. A file that is
neither is absent by design -- do not backfill it with a guessed stage. Downstream consumers
(befund-transform-brief) treat a miss as "Unattributed", never as an error; see
attribute-citation in the CLI for that exact lookup behavior.
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" validate-artifact --kind file_stage_index --file <path-or-inline-json>
Step 6: Resolve output paths and write
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename stage_graph.json
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename file_stage_index.json
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/befund_cli.py" resolve-output-path --repo <repo_root> --filename stage_map_summary.json
Write STAGE_MAP.md, stage_graph.json, file_stage_index.json, and stage_map_summary.json
to their resolved paths. stage_map_summary.json is a reporting sidecar, not a load-bearing
artifact: it records a short run summary -- stage/wire counts and a timestamp -- that
befund-status reads only as a presence flag for its dashboard. No other befund skill
depends on its schema, so it is written directly here and never passed through
validate-artifact.
stage_map.json (viewer format, sampled edges) is not written by this skill at all: no step
above resolves a path for it or builds it, and STAGE_MAP.html below renders from the full
stage_graph.json directly, never from stage_map.json's sampled edges. befund-transform-brief
is the sole producer of stage_map.json -- it creates the file, containing only a flows field,
when it finds the file absent, and appends that same field without altering existing stage/wire
data when the file already exists.
Then render STAGE_MAP.html -- a real canvas-based D3 viewer (force-directed graph layout,
pan/zoom, search, drag-to-reposition), not the old "simple static graph render":
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_stage_map_html.py" \
--stage-graph <resolved stage_graph.json path> \
--file-stage-index <resolved file_stage_index.json path> \
--template ${CLAUDE_PLUGIN_ROOT}/assets/stage-map-viewer.html \
--d3 ${CLAUDE_PLUGIN_ROOT}/assets/inline-d3.html \
--tokens ${CLAUDE_PLUGIN_ROOT}/assets/tokens.css \
--out <resolved STAGE_MAP.html path>
This reads the FULL stage_graph.json directly (never stage_map.json's sampled edges --
canvas rendering with proper culling doesn't need the edge count thinned down for readability
the way the old prose-only render did), and reuses lib.graph's own find_cycles/
find_god_modules to highlight cycles and god-modules in the viewer -- the exact same
functions befund-arch-health reports from, so the viewer can never show something that
skill disagrees with.
Read-only constraint
Never use Write/Edit for anything outside the resolved output paths above. The extraction
command dispatched to stage-mapper is read-only (grep/AST-dump), never a scratch file or a
mutation.
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.