feat(telemetry): bug_causality table + reconstruction job (bo-s1kb)

[scbrown]

bo-s1kb — bug_causality table + caused_by reconstruction job (telemetry Phase 0)

Adds the supervised signal for "risky change" in the feature↔code↔bug reconcile/predict loop (GH#9): a bug_causality table reconstructing which prior commit most likely introduced the bug a later bead fixed.

Changes

• New table bug_causality (bug_id, culprit_sha, culprit_bead_id, file, confidence, created_at) with UNIQUE(bug_id, culprit_sha, file) for idempotent re-runs.
• New CLI bobbin bead reconstruct-causality [--bug <id>] [--limit N]. For each bug bead: gather the files its fix touched, find the most-recent prior commit touching each file (candidate culprit), and score confidence by how much of the fix's changeset that commit overlaps (concentrated blame ⇒ higher confidence). Upserts one row per (bug, culprit_sha, file).
• Store methods: prior_lineage_touching_files (json_each over touched_files), record_bug_causality (upsert), list_bug_causality, distinct_lineage_bead_ids (bug discovery via the lineage bead_type column, falling back to bd show).
• Docs: new cli/bead.md page documenting the whole bead command family (link / auto-link / reconstruct-causality / history) + SUMMARY entry.

Test

• cargo test --bin bobbin green (852 tests).
• Pure reconstruct_culprits heuristic unit-tested (most-recent wins, confidence scales with overlap, unrelated files / empty sha ignored).
• Store path tested end-to-end against sqlite: json_each lookup, upsert idempotency (re-record refreshes confidence, no dup), distinct_lineage_bead_ids.

Scope / design call for dearing

v1 is the recency + file-overlap heuristic over bead_lineage. Two parts of the original AC are deliberately deferred:

1. Git-blame sharpening to the exact introducing commit (blame removed lines of the fix) — a confidence refinement, not required for the signal.
2. change_events outcome labeling (introduced_bug label + time-to-first-bug) — change_events has no table anywhere in the codebase yet; this needs a schema decision before it can be built.

Neither blocks the supervised signal this table provides. Flagging #2 as a design call.

Depends on bo-xrsy (#23, merged) for the lineage numstat/symbol fields.

CI Style check (Vale) failure is pre-existing doc debt, unrelated (per #22–#25).

🤖 Generated with Claude Code