Module notes 

Reasoning travels with the code: a redacted excerpt per landed commit, as a git note.

borg notes attach [<commit>] writes, for each commit a drone’s session landed (or the one named), the session’s task, the drone’s last proposal and the session’s episode ids to refs/notes/borg in that repo. Notes are local refs: borg never pushes them (an engineer who wants them on a remote pushes refs/notes/borg like any ref). The hook’s end event runs it in the background when the session started in a git repo (<state>/<session>.head holds the repo and its HEAD at the session’s first prompt).

Only the session’s own commits (landed): a commit gets this session’s note only if HEAD’s reflog says commit (or commit (amend), commit (initial), revert, cherry-pick) created it while the session was working (between one of its prompts and the stop that followed, <state>/<session>.active) and it is still on HEAD. A git pull, a merge, a checkout of another branch, or a commit made while this session was idle (the engineer, or another session in the same repo) gets nothing from it. Two sessions working in the same worktree at the same second cannot be told apart.

Redaction first (redact): tokens, keys, passwords and .env-style values are replaced before an excerpt is written anywhere, by a conservative regex list (it rather blanks a harmless value than lets a secret through).

Replication (PLAN.md “Availability”): the same excerpt is appended to the collective’s reasoning.jsonl, which the mesh (borg-mesh, sync.rs) hands to two member replicas, so the “why” survives the author being offline. Only when collective::may_sync allows it: a local (private) collective’s excerpts stay in that repo’s notes, and an off repo gets nothing at all. borg notes fetch [<commit>...] reads it back: it asks the known members (borg-mesh fetch, author or replica) and writes what they hold as notes (restore.rs).

Links (regress.rs): after attach, the landed commits are matched against the earlier decisions whose lines they changed; a note then lists them under borg fixed in: (on the decision) and borg fixes: (on the fix), links.rs.

Re-exports

pub use restore::restore;

pub use restore::wanted;

Modules

links

Decision → fix links (regress.rs finds them): the record a link leaves in the collective’s reasoning.jsonl and the borg fixed in: / borg fixes: sections of a borg note.

reasoning

The reasoning recorded for commits, as borg why and regress.rs look it up: a commit’s borg note (notes.rs) or else the excerpt the collective’s reasoning.jsonl holds, each only where it may be shown (visible). One notes list plus one cat-file --batch, and one read of the store.

regress

Decision → fix links: which earlier decision did a fix correct? (PLAN.md “Milestone B”)

regress_cli

borg regress: the decision → fix links regress.rs would make, as a dry run (nothing is written: no note, no record).

regress_cosmetic

Which hunks of a fix change no decision (regress.rs drops them before blame): a formatter’s reflow (equal once all whitespace and trailing commas are gone, also when git split it across hunks), a rename (one identifier swapped throughout), and a move: a removed line the fix adds again verbatim in another file, further away, or as part of a block. A line swapped with its neighbour is a change: an ordering fix.

regress_diff

What git says about a fix, parsed (regress.rs runs git): --numstat -z sizes, -U0 hunks, and blame --porcelain per line. No git here, so every rule is a unit test.

regress_git

git for regress.rs: every call with a timeout inside one deadline for the whole run, so the end-of-session job never hangs on a huge repo. Paths come back unquoted (core.quotePath=false), as blame takes them.

regress_learn

The end of borg notes attach for a session’s landed commits (notes.rs After): link them to the earlier decisions they fixed (regress.rs), record the links, and with BORG_REGRESS=learn turn each strong link into a regret episode in the collective’s store, team or local (regret.rs). One git deadline covers it all (regress_git.rs). Once learned as a lesson, borg learn credits each regret back to the lessons asked in the deciding session before the decision (learn.rs credit_regrets).

regress_signals

Was it a fix? The signals regress.rs weighs for a commit that changed an earlier decision’s lines: a revert, a fix-shaped subject, a test that failed and then passed in the session, or the engineer’s own words about a bug. A revert or a fix subject makes the link strong (fix) on its own; tests and words only together (strong): red, then green is also how a feature is built test first, and a prompt names failures a feature handles. Otherwise the link is weak (revisited), stored but never learned from.

regret

Regret episodes: a strong link (regress.rs) becomes an episode borg learn generalises with the regret prompt (learn/regret.rs) into a question to ask at the decision point. Only with BORG_REGRESS=learn, and only where the collective may sync: a local collective keeps its links in the repo’s notes and nothing more.

restore

borg notes fetch, the write side: what the mesh handed over (borg-mesh fetch, into the store’s reasoning.jsonl) becomes notes. An excerpt becomes the note of a commit that has none; a decision → fix link record (links.rs) goes into the notes on both sides that exist.

Structs

Attached

What one run did.

Excerpt

The redacted reasoning of one landed commit.

Landed

A run’s commits and where they go: what attach notes, and what runs after it (main.rs passes regress_learn.rs, which links them to the earlier decisions they fixed).

Start

Where a session started: the repo’s top level and its HEAD then.

Constants

NOTES_REF

Functions

attach

Notes for l.commits from l.session in the collective l.route names (an off route attaches nothing); excerpts go to l.store’s reasoning.jsonl only if the route may sync. force replaces an existing borg note (an explicitly named commit), keeping the links it lists.

excerpt

The session’s task, last proposal and episode ids, redacted, for commit of repo.

landed

The commits the session itself made (module doc), newest first, at most MAX_COMMITS: HEAD’s reflog entries of a commit within one of windows, still reachable from HEAD but not from the session’s starting HEAD.

landed_by

The commits session landed so far (landed, from its start recorded in dir); empty when it started outside git or left no record here.

latest_session

The session that last started in repo, from the .head files in dir.

main

borg notes attach [<commit>] [--session ID] [--dir DIR] [--store DIR] [--then-learn], or borg notes fetch [<commit>...] [--dir DIR] (runs borg-mesh fetch: the network is there).

mark

Marks the session working (prompt) or idle again (stop), for landed (hook).

note_of

The borg note of commit, parsed; None without one.

on_end

Hook, end: if the session started in a git repo, attach notes in the background (never delays the drone; any failure is silent), and borg learn --session after them (--then-learn), so learning sees the regret episodes the links made. False when no job was started: the caller then starts borg learn itself.

redact

text with every secret the list recognises replaced (module doc).

remember_proposal

Keeps the drone’s latest proposal for the excerpt (hook, at stop and end): redacted whole, then cut to its last learn::PROPOSAL_CHARS, so a cut never lands inside a secret that was not redacted.

remember_start

Records where session started, once (hook, first prompt in a git repo).

start_of

Where session started (remember_start, recorded in dir); None outside git or without a record.

state_dir

The per-session scratch directory (as the hook uses it).

toplevel

The top level of the git repo dir is in.

windows

When the session was working, as [from, to] epoch ms: from each prompt to the stop after it (open-ended while it works). Without marks, everything since the session started.

write_note

Writes e as the borg note of its commit (replacing an older borg note). Never pushes.

Type Aliases

After

Runs after attach for the session’s landed commits (not for a named one); its text ends the run’s message.