Module why 

borg why: the reasoning behind code, on demand (PLAN.md “Recall mechanics”).

borg why <path>[:<line>[-<line>]] blames the span (the whole file without a range) and borg why <commit> takes that commit. For each distinct commit, newest first: short sha, date, author and subject, then the drone’s reasoning (task, last proposal, episode ids) and the lessons learned from those episodes (question and consequence, one line each).

Where the reasoning comes from: the commit’s borg note (refs/notes/borg, notes.rs); if the repo lacks it, the excerpts the collective’s store holds (reasoning.jsonl: this machine’s own and those the mesh replicated to it from peers). No network and no model call: borg notes fetch is the step that asks peers. Lessons come from the routed collective’s lessons.jsonl only.

Links (notes/regress.rs): a decision shows the later commits that fixed its lines (→ fixed in Y (task: …)), a fix the decisions it fixed (← decided in X (task: …) → fixed here), from the notes and the store’s link records, at most 3 each unless --full (why/linked.rs).

Privacy: decided before git is asked anything. A cwd (or target) that routes off, or an invalid config, prints nothing and exits 0. A note or excerpt that names another collective is never shown (a private collective’s note only where the cwd routes to that same collective); an excerpt from before notes named their collective is treated as this repo’s. Everything shown is redacted again at display time (notes::redact), whatever the note says. Paths are routed resolved (absolute, symlinks followed, as git sees them), and the repo git reads must route to the cwd’s collective too: a symlink or submodule into an off or other repo prints nothing.

Cost: the blame headers give each commit’s time, so the cap is applied before any per-commit work; then one git log, one git notes list plus one cat-file --batch, and one read of reasoning.jsonl (only if a shown commit lacks a note).

Compact by default: at most MAX_COMMITS commits, the task’s first line and the proposal’s last PROPOSAL_CAP characters, MAX_LESSONS lessons per commit. --full shows everything, --json prints the same (capped unless --full) for scripts. It costs tokens only when a drone runs it: nothing injects it.

Structs

LessonLine

LinkLine

The other commit of a link.

Reasoning

Report

Why

Enums

Target

What to explain.

Functions

blamed

The distinct commits of git blame --porcelain output with their author time, in order of first appearance, and the number of lines not committed yet.

explain

The explanation of target (an argument as typed) from cwd, or None when cwd, the target or the repo they lie in routes off or elsewhere. base is the root store (BORG_HOME). Paths are routed resolved (absolute, symlinks followed), as git sees them.

main

borg why <target> [--full] [--json] [--dir DIR].

parse_span

path, path:12 or path:12-20 (a commit is told apart later, by what exists).

render

The report as text.