/diff-recap

Turns a git diff into a recap you can paste into a pull request — a per-file change table whose numbers are transcribed from git, grouped and labelled, rendered as an inline annotated widget with a mandatory ASCII twin, and backed by a diff-recap/1 record. It fills the gap the orient- family leaves open: orient-map shows the shape of the work and orient-status shows where you stand, but neither recaps what a concrete change-set contains for a reviewer. diff-recap does exactly that, and only that.

Its differentiator is true by construction: the structured numbers (per-file added/removed/status and the headline totals) come straight from git diff --numstat and --name-status — the model authors only the prose labels. A record whose totals don't equal the sum of its rows is rejected by a value gate before it can be shown, so the recap cannot quietly lie about the diff. And unlike a hosted recap renderer, it has zero external dependency — the ASCII twin is self-contained and PR-pasteable in any channel.

Structured execution spec: protocol.yon. Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

When to use

• "Recap this diff / summarize these changes for a PR" — you want a reviewer-ready change summary, not a fresh read of the whole tree.
• "What changed in this branch" as a change-set, grouped by area with a one-line why per file.
• Right before opening a pull request, when you want a paste-able summary whose numbers you can trust.

How it works (self-sufficient — works without protocol.yon)

Every call recomputes from the real diff; nothing is stored.

1. Take range, repo, and intent as inputs — never prompt. range defaults to the working tree against HEAD (or a A..B range, or --staged); repo defaults to the cwd. intent (the PR's goal) shapes the labels — if it's ungrounded, the recap still emits the mechanical facts but caps the labels to descriptive and never invents a rationale.