spur-trace
Runs a project's pipeline or test suite once under a tracer and renders one static HTML page per run: per step the command, a call tree of the project's own functions, every file read and written with its sha256, which step's output fed which, and a hash-chain check; also exports W3C PROV-JSON. Use when a reviewer asks how a result was produced, which files a step read, or whether one step's output is really the next step's input — 'trace this pipeline', 'show provenance for this run', 'which step wrote this file', 'prove the outputs chain'. Writes only under analysis/spur/ (one directory per run) and never edits the traced code. Not for whether tests would catch a bug (zeugnis-assertion-audit) or for proving and fixing a handoff between stages (andon-verify).
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- spur-trace
- description
- Runs a project's pipeline or test suite once under a tracer and renders one static HTML page per run: per step the command, a call tree of the project's own functions, every file read and written with its sha256, which step's output fed which, and a hash-chain check; also exports W3C PROV-JSON. Use when a reviewer asks how a result was produced, which files a step read, or whether one step's output is really the next step's input — 'trace this pipeline', 'show provenance for this run', 'which step wrote this file', 'prove the outputs chain'. Writes only under analysis/spur/ (one directory per run) and never edits the traced code. Not for whether tests would catch a bug (zeugnis-assertion-audit) or for proving and fixing a handoff between stages (andon-verify).
03 SKILL.md 正文
Record one run of the pipeline as it actually happened. This skill changes no source file: the tracer is loaded beside the program, never into it.
The rule above the others: the traced run must behave exactly like an untraced one. If a traced run fails where a plain run succeeds, stop and report it as a spur defect — do not work around it by editing the project.
Steps
-
Detect the stack.
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/spur_trace.py" detectExit
0names each stack found and the adapter it gets; exit4found none. Python is traced in-process. Rust, Node and Go have no in-process adapter: readreferences/adapters.mdbefore tracing one, and say to the user which parts of the record will be missing. -
Find the one command that runs the pipeline, in this order: a documented pipeline command in the README, a
Makefile/justfiletarget, a driver script, the test suite (pytest,cargo test,npm test). Ask the user only when none of these names it. One command, run once: every step must be a process that command starts. -
Run it under the tracer from the project root.
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/spur_trace.py" run -- <command> [args...]Exit codes, which decide the next step:
exit meaning next 0the command succeeded and every link verified step 4 3a link is broken: a file changed between producer and consumer step 4, lead with it 4incomplete (an input is unverified) or empty (no step read another's output) step 4; never call it a pass 2usage or instrument error fix the invocation, rerun step 3 other the command's own exit code: the pipeline failed step 4, lead with the failing step On stderr it prints the summary and the run directory:
spur: 6 step(s), chain broken (2 verified, 1 broken, 1 unverified, 1 source) spur: wrote analysis/spur/20261030T183037Z/{trace.json,prov.json,spur-report.html} -
Report from
trace.json, not from memory. Readanalysis/spur/<runId>/trace.json(the format is inreferences/trace-format.md) and tell the user:- the chain verdict in one sentence, naming each
brokeninput asproducer → path@version → consumerwith itsnote(it names any untraced step that ran in between); - every
unverifiedinput, and every untraced step with itswhy; - any step whose
exit.codeis non-zero, and the run'sdroppedcount if it is not 0; - the path of
spur-report.htmlto open, andprov.jsonfor PROV tools.
Show two or three inputs with their sha256 and status as evidence, verbatim from the record. Never round a
brokenorunverifiedinput into "mostly fine". - the chain verdict in one sentence, naming each
-
Only if the user asks whether the outputs are still the ones the run produced, run
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/spur_trace.py" verify analysis/spur/<runId>Exit
0every final output matches its recorded hash;3names eachDRIFTfile. Drift after the run is not a chain break — the run was fine, the files changed since.
What the record holds, and what it does not
- Recorded: argv of every process, the project's own function calls (code under the root; the interpreter, site-packages and the tracer itself are excluded), sha256 of every data file read and written, the code files it loaded (hashed, kept out of the chain), renames and removals.
- Never recorded: environment values, file contents, anything under the home directory
in readable form (it becomes
~). The raw per-process fragments hold absolute paths and are deleted after the merge unless--keep-fragmentsis passed. - Not observable: a process started with
python -I/-E, or given its ownenv=withoutPYTHONPATH, and any non-Python program. Each still appears as an untraced step.
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.