impact: specs

Constants at the top of impact.py: DAYS=30, PRE_MIN=5, POST_MIN=30, MIN_CALLS=10, WRITE_TOOLS, OUTSIDE_P=0.9, MIN_P=0.5, LINK_OPTION="yes", AGENT_TRAILERS; in connectors.py: SCAN_MARGIN=1 day, DEFAULT_BRANCHES.

L-scan: commit metadata

Per repo, git log --all --no-merges --numstat from the earliest session start − PRE_MIN until now (author date, UTC; git --since gets SCAN_MARGIN extra because it filters on committer date). Kept per commit: sha, author ts, author email (output only as sha256[:12]), files, added, deleted (binary files count as a file with 0 lines), trailers, the sha named by This reverts commit <sha> in the body (nothing else of the body is kept), whether the sha is reachable from the default branch (origin/HEAD, else main, master, else HEAD). Commit subject: not used. impact.read_subjects is reserved: the connector reads it, but no output or schema field carries it, so it changes nothing. Merges excluded.

L-repo: which sessions belong to a repo

Repos = impact.repos (if non-empty) else distinct session.repo. A session belongs to repo R when realpath(session.repo) == R, or session.repo is null and session.project == basename(R). Sessions outside every repo are unlinked, except L-outside. repo_label = basename(R).

L-outside: sessions started outside any repo

Only when impact.repos is set: sessions with null repo (started in a parent dir such as ~/projects and committing with git -C), or whose repo is a strict parent dir of R (nested repo, e.g. a session in ~/projects/know-how committing to know-how/opentokenmini/v002), are also candidates for the L-trailer commits of R (never for L-window). If one wins L-assign it gets link:"trailer", link_p = OUTSIDE_P (0.9: the trailer proves the harness, L-assign picks the session). Such a session can link to several repos; L-split shares its cost. Why: on real data 80% of Claude Code events had cwd ~/projects, and the session driving v002 had repo ~/projects/know-how.

L-window: time window

Session window = [start − PRE_MIN, end + POST_MIN] (inclusive).

L-trailer: agent trailer link (p = 1)

A trailer line matching an AGENT_TRAILERS regex (case-insensitive, first match) names a harness; agent_trailer = that harness id. A trailer commit can link only to sessions of that harness in the same repo whose window holds the commit ts (L-assign). Such a session gets link:"trailer", link_p:1.0, and only its trailer commits.

L-assign: one session per commit

Among eligible sessions (window holds the commit ts) the commit goes to the first by: sessions with ≥ MIN_CALLS API calls before smaller ones; sessions that used a WRITE_TOOLS tool (can edit files or run git commit, so shell tools count; decide EDIT_TOOLS is narrower on purpose, see decide/METHOD.md D-commit-link) before ones that did not; smallest distance (0 if ts in [start, end], else minutes to the nearer edge); most calls; latest start; session_id. A commit is never counted twice. Why: on real data many tiny automated sessions (claude -p, swarm helpers, 1 call, no tools) overlap the real one, and nearest-in-time gave them 17 v002 commits for $0.01. Sessions carry tool counts, not touched file paths, so "used a write tool" is the closest signal impact has to "touched the committed files".

L-candidate: window candidates

Commits with no agent trailer whose author email is a user.email of the repo (local author) go, by L-assign, to sessions of any harness without a trailer link. Each such session gets one record link:"window", link_p:null (pending). Non-local authors are ignored.

L-subject: decision subject

<session_id>:<sha256(",".join(sorted(commit shas)))[:8]>. decide asks commit_link with this subject; a changed commit set yields a new subject, so stale answers never apply.

Contract impact<->decide (commit_link, single copy; decide/METHOD.md links here): subject = <session_id>:<sha256(",".join(sorted(commit shas)))[:8]> (impact subject_of, decide link_subject; repo_label is not used because one session can hold candidates in several repos); options = decide/points.json commit_link (yes/no); impact reads probabilities.yes (LINK_OPTION) of the latest decision per subject as link_p. Round trip: 04-auto-analysis/tests/test_impact.py test_roundtrip_decide.

L-decided: applying commit_link

From decisions.jsonl, point commit_link, latest ts per subject wins; p = probabilities[LINK_OPTION] (missing → 0). p ≥ MIN_P → record kept with link_p = p; p < MIN_P → record dropped (session unlinked). No decision → stays pending (link_p:null).

L-revert: reverts

Commit X is reverted when a scanned commit R (any time up to now, any ref) says it reverts a sha prefix of X; X.reverted_by = R. Per record: revert commits are neither kept nor reverted and add no lines; added/deleted = sum over non-revert commits; commits_kept = non-revert, not reverted; commits_reverted = non-revert, reverted.

L-split: one session, several repos

A session's cost is split across its linked records by share of commits: record cost = session cost.total × len(record.commits) / Σ len(commits) over that session's linked records. So Σ by_repo.cost = Σ by_harness.cost = Σ cost of linked sessions (no double count).

L-cost: summary

Only linked records (link_p non-null) count. Per group (repo_label, harness): cost = Σ record cost (L-split); lines_added = Σ max(0, record.added − added of its reverted commits); cost_per_kept_commit = cost/commits_kept, cost_per_100_lines = 100·cost/lines_added, revert_rate = reverted/(kept+reverted); each null when its denominator is 0. sessions_total = sessions with end within --days; unlinked_cost = Σ cost of sessions not linked (pending included). Rounded to 6 decimals.

L-ex: worked example (04-auto-analysis/tests/test_impact.py, fixtures/impact/sessions.jsonl)

Sessions a (claude-code 10:00–11:00, $2), b (codex 14:00–14:30, $1), c (claude-code 20:00–20:10, $0.50). Commits: c1 10:30 Claude trailer +10; c2 11:20 Claude trailer +5 (in POST_MIN); c3 13:00 Claude trailer +4 (no window); c4 14:10 local, no trailer +7; c5 14:20 other author +3; c6 16:00 reverts c2. Pass 1: a = trailer, [c1, c2], added 15, kept 1, reverted 1; b = window, link_p null, [c4]. Summary: linked 1/3, by_repo cost 2.0, lines_added 10, cost_per_kept_commit 2.0, cost_per_100_lines 20.0, revert_rate 0.5, unlinked_cost 1.5. Pass 2 with p(b)=0.8: linked 2, cost 3.0, lines_added 17, unlinked 0.5. With p(b)=0.3: b dropped, unlinked 1.5.