# Debugging evidence contract

One report covers one observed failure. It records evidence paths and hashes so a reviewer can
re-run the reasoning without trusting the author's narrative.

## Required shape

```yaml
schema: shepherd.debugging-evidence/1
run: <run-id>
lane: <lane-id>
node: <node-id>
role: coder
status: reproduced|root-cause-found|fixed|unresolved|blocked
candidate_commit: <full commit>
worktree: <descriptor-bound path>
startup_skill: implementing
debugging_skill_digest: <sha256>
input_digest: <sha256>
```

## Required sections

- `reproduction`: exact command, input, environment/binary identity, exit status, stdout/stderr
  paths, and the fresh observed failure.
- `observed`: facts separated from interpretation, with file/symbol/line or artifact pointers.
- `hypothesis`: one falsifiable claim per suspected boundary and the probe that tests it.
- `falsification`: command, exit status, actual observation, and conclusion for each hypothesis.
- `root_cause`: the shared fault boundary and why caller-only alternatives do not explain it.
- `fix`: changed paths, scope, and why the change is the smallest root-cause correction.
- `regression`: test that was RED before the fix and GREEN after it, with input and output hashes.
- `gate`: fresh deterministic command, status, semantic result, and candidate identity.
- `evidence`: sorted artifact paths and SHA-256 values, paired eval and threshold when relevant.
- `residual_risk`: unresolved environment, timing, or compatibility limits and the next route.

A report with only a process exit, a self-attested root cause, stale output, a hidden error, or a
missing before/after regression is `unresolved`, never accepted.