Beagle SCM

WHY-002: machine-readable plain why — verbatim body, runs/commits footer, fragment scoping

Input

Context

The colour why: view bakes attribution into hidden O tokens (#rrggbb commit ?<hashlet>, WHY-001); --plain (view/bro.js whyPlain) strips U/O and emits bare file bytes, so a pipe consumer (LLM agent, grep, CI) gets NO attribution at all. Agents read byte streams only — the alt-screen TUI is invisible to them (BRO-027).

• Dispatch is already per-hunk JS: renderHunkLog sniffs hasWhyRuns and routes plain why hunks to whyPlain — the change is local, the sink/hunk contract stays untouched.
• Attribution truth is token RUNS (one line can carry several origins), so any line-prefix blame column is lossy; emit runs, derive projections later if wanted.

Goals

Plain why output an agent reads in one pass — self-contained, greppable, three parts:

• Banner why <uri> (verb form); body = file bytes behind a cat -n-style gutter (6 right-aligned + 2 spaces), ABSOLUTE file line numbers even for a scoped fragment.
• why-runs footer: one line per origin commit, 8-char hashlet, line.col-line.col spans, * marks a run crossing a line boundary, wt...... = the unattributed working-tree layer.
• why-commits legend: hashlet date5 author title per contributing commit; date5 is the 5-char DDMon / current-week DowDD form jab log prints.
• Fragment scoping: why <path>#L41 (line anchor) and why <path>#authorIdent / #authorIdent:L41 (symbol anchor, the HUNKu8sMakeURI convention) narrow the hunk; WITH a fragment the body defaults to ONE PAGE, without — the full file. Locator resolution is /todo/SPOT/SPOT-001's shared/spot.js, not why-local code.
• ?a..b range mode keeps the same shape; surfaced deleted runs carry a - mark in why-runs.

Constraints

• Fragment grammar must not collide with hashlets: 6..40-hex resolves as a hashlet FIRST (resolve_hash order is mandatory); non-hex symbols and L/:L forms are locators.
• Locator parsing + resolution live in shared/spot.js (/todo/SPOT/SPOT-001); why.js only maps the returned byte span onto the weave's alive view and picks the page window.
• whyPlain already walks [visible][O] pairs with byte offsets in hand; line.col comes from counting newlines in that SAME walk — no second scan, no new engine.
• "One page" is a constant to pick: pager rows when a tty is present, a fixed default (e.g. 48 body lines centered on the anchor) in pipe mode.

WIP

Design decisions

• Body stays verbatim modulo the fixed-width gutter — a mechanical 8-column strip recovers the exact file bytes.
• Footer section headers are column-0 barewords (why-runs, why-commits): one pass splits the hunk, grep <hashlet> pulls both spans and legend.
• The anchor grammar is URI-level, not verb-level — cat:/diff: can adopt the same fragments later (file a separate ticket if pursued).

TODOs

• whyPlain: line gutter + why-runs + why-commits emission
• parseArg: fragment → shared/spot.js locator (/todo/SPOT/SPOT-001), one-page default with fragment
• range mode: - marks on deleted runs in why-runs
• repro: golden plain-output check under be/test/why/ (buildBody + whyPlain, no loop drive)

Blockers and bummers

(none yet)

Outcome

(pending)