# Investigating a defect — reconstruct ground truth from a fix commit

audience: AI coding agents first. Imperative, BLUF-ordered.

**Core principle: ground truth comes from the git FIX COMMIT, reconstructed with RAW git, verified before trusted. The orchestrator may read ground truth; detectors/agents under test never may.**

## When to use
Invoke to build a corpus cell's ground truth, or to forensically confirm what a fix actually changed.

## Ladder
1. **Find the fix commit.** `git log --oneline -- <path>`; read the diff: `command git --no-pager show <fix>`.
2. **Reconstruct cells with RAW git** (RTK truncates routed git show — silent, variable):
   - vuln: `command git --no-pager show <fix>~1:<path> > vuln.ts`
   - safe: `command git --no-pager show <fix>:<path> > safe.ts`
3. **VERIFY before trusting:** each file ends on a clean closing token AND contains its canonical symbol. A cell missing its tail = a false "miss".
4. **Classify the shape** (spec §3, band-2 spike):
   - **single-file** — the defect is decidable from the one file. band-1.
   - **Shape-A cross-file IDOR** — user FK passed to an imported fn with no visible guard. band-1 FLAGS it on the smell.
   - **Shape-B imported insecure default** — call site is visible AND well-formed; the bug is the default INSIDE the imported symbol. band-1 single-file MISS; a 3/3 CATCH once the symbol is resolved into scope. → band-2.
5. **Record `canonical.json`** `{id, domain, class, band, shape, file, line, fix_sha, canonical_symbol, why}`. For Shape-B add `requires_resolution:true` + the resolved cell.

## DO NOT
- DO NOT reconstruct a cell via routed `git show` — // reject: silent truncation drops the tail → false clean.
- DO NOT let a detector/agent under test see the fix commit, audit doc, or canonical. Blind catch-test discipline.
- DO NOT print reconstructed secrets — secret-scrub every cell.

## Pointers
Shapes + measured recall: `docs/validation/2026-06-17-band2-crossfile-spike.md`. Ground-truth-from-git: `docs/specs/2026-06-17-security-gate-design.md` §6.