@ok-ggwp/git-gloss 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ok-ggwp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# git-gloss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agents write a lot of code, and reviewers can't easily tell what each part is for or whether it was needed. `git-gloss` lets the author of a commit (usually the agent that wrote it) attach a **gloss**: the diff grouped by intent, with each group graded for necessity and saying what breaks without it.
+
+Glosses are stored in git notes (`refs/notes/gloss`), so they don't touch history. Git doesn't push or fetch notes by default; `git gloss sync` shares them, and `git gloss init --hooks` makes every `git push` do it.
+
+## Commands
+
+```
+git gloss init [--hooks]              follow amends/rebases; fetch origin's glosses; --hooks: sync on push,
+                                      adopt wip glosses on commit
+git gloss sync [<remote>]             fetch, merge and push glosses (default: origin)
+git gloss hunks [<commit>|wip]        list hunks, numbering changed lines for h3:2-5 references;
+                                      wip snapshots your uncommitted work instead
+git gloss adopt [<commit>]            move the gloss of uncommitted work onto the commit made from it
+git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff)
+git gloss carry <source>... [--to <c>] gloss a commit from the glosses of the commits its changes came from
+                                      (a squash, cherry-pick or rebase): git gloss carry main..feature --to <squash>
+      --find [--squash] [<commit>...] ...working out which commits those are
+git gloss show [<commit>|<range>]     summary: one line per group, alternatives, risks (a range: each commit)
+      -g <group>                      ...expand groups, with their code
+      --full                          ...every group's details
+      --diff                          ...every group's details and code
+      --only speculative,incidental   ...just the parts you might cut
+git gloss html [<commit>|<range>]     self-contained HTML view, of one commit or a branch (--open, -o <file>)
+git gloss why <file>:<line>[-<end>]   explain why code exists (via blame), looking past mechanical edits
+      --history                       ...every commit that changed the lines, newest first
+      --json                          ...for agents, with risks and rejected alternatives
+git gloss review [<commit>|<range>]   print a review prompt: git gloss review main..feature | claude -p
+      --material                      ...only the gloss and code, for a reviewer with its own instructions
+                                      (which must tell it the author's text is untrusted)
+git gloss versions [<commit>|wip]     every gloss a commit has had, newest first (--show <n>, --restore <n>)
+git gloss schema                      print the annotation JSON Schema
+```
+
+A group refers to whole hunks (`h3`) or to some of a hunk's changed lines (`h3:2-5`, `h3:1,4-6`), numbering only `+`/`-` lines. Ranges let one hunk, such as a whole new file, be split between intents. Views show a group only its own lines, with `⋯` marking lines that belong to other groups, and `why` names only the group that owns the blamed line.
+
+Necessity categories: `required`, `supporting`, `mechanical`, `incidental`, `defensive`, `speculative`. See [skills/gloss/SKILL.md](skills/gloss/SKILL.md) for what each means and for the annotation format.
+
+## Setup
+
+Requires Node 20.12+ and git.
+
+```sh
+npm install -g @ok-ggwp/git-gloss     # puts git-gloss on PATH, so `git gloss` works
+ln -s "$(npm root -g)/@ok-ggwp/git-gloss/skills/gloss" ~/.claude/skills/gloss   # teach Claude Code to write glosses
+```
+
+git finds `git-gloss` on PATH, so `git gloss` works wherever npm's global folder is on PATH, as it is after a normal Node install. On Windows this should work the same way (npm installs a shell launcher git can run), but it hasn't been tested yet.
+
+For a team, add it to the project instead, so everyone gets the same version with `npm install`:
+
+```sh
+npm install -D @ok-ggwp/git-gloss
+npx git-gloss init --hooks
+```
+
+The hooks run `git gloss`, so it must be on PATH wherever git runs; with a project install, that means running git from a shell where `node_modules/.bin` is on PATH, or installing it globally as well.
+
+To work on git-gloss itself: clone it, `npm install`, `npm link`, `npm test`. From a checkout, on Node 22.18+, the TypeScript source runs directly; on older versions the launcher runs `dist/`, which `npm install` builds (and `npm run build` rebuilds after changes). The tests need Node 23.6+.
+
+### Setting up a repo
+
+In each repo you use it in:
+
+1. Run `git gloss init --hooks`. Glosses then follow amends and rebases, `git commit` moves a wip-gloss onto the new commit, and `git push` to a named remote also syncs glosses with it. The hooks call `git gloss`, so it must be on the PATH of whatever runs git (a GUI client may not have it); `init` warns if it isn't. Without the hooks, run `git gloss adopt` after committing and `git gloss sync` to share.
+2. Tell your coding agent to wip-gloss its changes. Add this to the repo's `CLAUDE.md` (Claude Code), or `AGENTS.md` for agents that read that file:
+
+   ```markdown
+   ## git-gloss
+   After making a non-trivial code change, wip-gloss it before reporting back: leave
+   the changes uncommitted and gloss them with git-gloss, following the gloss skill.
+   Don't commit unless asked.
+   ```
+
+   Claude Code finds the procedure in the `gloss` skill (installed above). Other agents won't have the skill, so for them add a pointer in `AGENTS.md` to a copy of `skills/gloss/SKILL.md`.
+
+Put the line in the repo rather than in your user-level `CLAUDE.md`: it only makes sense where `git gloss init` has been run.
+
+`sync` fetches the remote's glosses into `refs/notes/remotes/<remote>/gloss`, merges them into yours, and pushes the glosses of commits the remote has (or, from the hook, is being sent), retrying if someone else pushed in between. Glosses of commits that exist only on your machine, such as a private branch, stay local until those commits are pushed. Glosses on different commits simply combine, and a gloss changed on only one side since you last synced is taken from that side. Only when both sides changed the same commit's gloss since then is it a conflict: the newer gloss (by its `created_at`) wins, because a re-gloss is normally a correction, and if either can't be read, yours is kept. It prints what it fetched, pushed and decided. The hook never blocks a push: if syncing fails it prints a warning and the push goes ahead. It does nothing for `git push --dry-run`. It syncs before the branch is pushed (so glosses arrive even if the branch push is then rejected), and it disables credential prompts so a remote that needs one fails fast instead of stalling the push. If you already have a `pre-push` or `post-commit` hook, `init --hooks` leaves it alone and prints the lines to add. It also won't install into a `core.hooksPath` outside the repository, since other repositories may share that directory.
+
+## Glossing before you commit
+
+You don't have to commit to gloss or review. `wip` stands for your uncommitted work:
+
+```sh
+git gloss hunks wip            # snapshot tracked and untracked changes (respects .gitignore)
+git gloss add wip -f a.json    # gloss the snapshot
+git gloss show wip             # read it; html wip and review wip work too
+git commit                     # with init --hooks, the gloss moves onto the commit
+git gloss adopt                # ...or move it by hand
+```
+
+The snapshot is a commit object built from a temporary index, kept by the private ref `refs/worktree/gloss/wip` (one per linked worktree); your branch, index and files are never touched. Taking a new snapshot keeps the gloss of groups whose changes are unchanged, so after committing part of the work or editing one part, only the rest needs glossing again. Its gloss lives in `refs/notes/gloss-wip`, which `sync` doesn't push. Untracked files that look like secrets (`.env`, `*.key`, `*.pem`, `credentials.json`, …) are left out of the snapshot, with a note, because snapshots are shown and sent to reviewers; stage one with `git add` to include it. If a branch or tag is called `wip`, `wip` still means it when there's no snapshot; otherwise use `heads/wip`. Commands warn when you've edited files or committed since the snapshot. `adopt` matches the snapshot's hunks to the commit's by content, so the work can be committed in several commits (each takes the groups whose changes it contains), and changes made after glossing are reported as unexplained rather than silently covered. Once everything is committed, the snapshot is cleared.
+
+## Glosses that follow your history
+
+A gloss is attached to a commit, so anything that makes new commits from old ones has to bring it along. With `git gloss init --hooks`:
+
+| You | What happens to the gloss |
+|---|---|
+| amend, or rebase without changing a commit's diff | copied to the new commit (`notes.rewriteRef`) |
+| amend or rebase that changes the diff (a conflict, an edit) | re-glossed from the original, line by line; changes it doesn't explain are listed |
+| squash or fixup commits in a rebase | the glosses of all of them are combined into one |
+| cherry-pick (with or without `-x`) | carried from the picked commit |
+| `git merge --squash`, keeping git's message | carried from the squashed commits |
+| a squash or rebase merge on GitHub, or any other squash (your own message, `reset --soft`) | carried on your next `git gloss sync` or push, if you have the original commits (the author does): it looks for unglossed commits whose diff matches a glossed branch's combined diff (80% of changed lines in common), or a glossed commit's patch with the same author and date. By hand: `git gloss carry --find --squash` |
+
+Carrying matches each changed line to a glossed line with the same text in the original commits, and gives it that line's group: intents, grades and notes survive, and anything changed along the way is reported as unexplained rather than guessed. `git gloss carry` does the same by hand.
+
+Nothing is deleted. Replacing a gloss, a group dropped from a wip gloss, or the losing side of a sync conflict all stay in the notes history, and glossed wip snapshots stay reachable from `refs/worktree/gloss/archive` so `git gc` keeps them. `git gloss versions <commit>` (or `wip`) lists every version, and `--restore <n>` brings one back; a wip version is carried onto the current snapshot. The archive keeps those snapshots' files too, including anything since removed from them; `git update-ref -d refs/worktree/gloss/archive` lets `git gc` collect them (the glosses' text stays in the notes history).
+
+## Agent reviews
+
+`git gloss review | claude -p` gives a reviewer the gloss and the code, and asks it whether the gloss is honest: does each group do what it says, is its necessity graded fairly, what could be cut.
+
+To have agents review in a sandbox, where they can run the code and verify what they find, use [git-gud](https://github.com/ok-ggwp/git-gud). `git gud review [<commit>|<range>|wip]` runs this honesty review, a blind bug review that doesn't see the gloss, and an improvements review informed by it, with Claude Code, Codex or Cursor as the reviewer. git-gloss itself never runs an agent.
+
+## HTML view
+
+`git gloss html --open` writes a single HTML file (no network access, works offline) and opens it. It shows the task and summary, a bar of how the changed lines split across necessity categories, and a card per group with its rationale; code is collapsed until you ask for it. Click categories to filter, use the sidebar to jump between groups, or press `j`/`k` to move, `o` to show code, and `e`/`c` to expand or collapse everything. `#g-<group>` in the URL opens that group.
+
+Give a range (`git gloss html main..feature --open`) for a branch or PR view: every non-merge commit in order (merges are listed as not reviewed; `A...B` is rejected), a necessity bar across the whole branch, and the sidebar grouped by commit. Commits without a gloss appear with their whole diff marked as unexplained. On range pages a group's link is `#g-<commit>-<group>`. `git gloss review main..feature` likewise covers every commit and adds branch-level questions, such as later commits that undo earlier ones.
+
+All gloss and diff text is rendered as text, and a Content-Security-Policy with a per-page nonce blocks any script the page didn't generate.
+
+## Caveats
+
+- Carrying a gloss onto a server-side squash needs the original commits in your repository; usually the author has them. If a squash merge resolved conflicts or changed much of the code, it may not reach the 80% match; run `git gloss carry <branch commits> --to <squash>`.
+- A gloss records each hunk's location and a hash of its content. If a commit is amended or rebased so its diff changes, `show`, `review` and `why` flag the gloss as stale instead of showing it against the wrong code.
+- Merge commits are diffed against their first parent.
+- `git gloss html` writes to `~/.cache/git-gloss/<commit>.html` by default (or `$XDG_CACHE_HOME`). The page is a snapshot; regenerate it after re-glossing.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/git-gloss.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// From a checkout, on a Node that runs TypeScript, use the source directly, so
+// development needs no build; otherwise (an installed package, an older Node)
+// the compiled JavaScript in dist/.
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const src = new URL('../src/cli.ts', import.meta.url)
+const dist = new URL('../dist/cli.js', import.meta.url)
+if (!process.features.typescript && !existsSync(dist)) {
+  console.error(`${process.argv[1]}: no build found; run \`npm run build\` in ${fileURLToPath(new URL('..', import.meta.url))}, or use Node 22.18+ to run the source`)
+  process.exit(1)
+}
+const { main } = process.features.typescript && existsSync(src) ? await import(src.href) : await import(dist.href)
+process.exitCode = await main(process.argv.slice(2))

package/dist/carry.js

@@ -0,0 +1,56 @@
+import { servesOf } from './schema.js';
+import { bodyLines, changedCount, parseRef, selections, uncovered } from './selection.js';
+import { alsoServed } from './validate.js';
+const changedText = (h) => new Set(bodyLines(h).filter((l) => l.idx !== null).map((l) => l.raw));
+// Move a gloss onto another diff: a commit made from a wip snapshot, or a new
+// snapshot of work that has partly changed. Each glossed hunk is matched to
+// the new hunk with the same changes (the content hash used to follow
+// rebases); a group keeps its references to the hunks that matched, renamed
+// to the new ids, with line ranges unchanged because matched hunks have the
+// same changed lines. Groups with no matching hunk are left behind.
+// `previous` is the diff the gloss was written for, used to compare content
+// (line numbers from two different bases can't be compared).
+export function carryGloss(note, current, previous = []) {
+    const used = new Set();
+    const idMap = new Map();
+    for (const stored of note.hunks) {
+        const match = stored.hash ? current.find((h) => !used.has(h) && h.hash === stored.hash && h.file === stored.file) : undefined;
+        if (match) {
+            used.add(match);
+            idMap.set(stored.id, match);
+        }
+    }
+    const unmatchedOld = note.hunks.filter((s) => !idMap.has(s.id))
+        .flatMap((s) => previous.filter((p) => p.id === s.id && p.hash === s.hash && p.file === s.file))
+        .map((p) => ({ file: p.file, lines: changedText(p) }));
+    const partialMatch = current.some((h) => !used.has(h) &&
+        unmatchedOld.some((p) => p.file === h.file && [...changedText(h)].some((l) => p.lines.has(l))));
+    const a = note.annotation;
+    const kept = a.groups.flatMap((g) => {
+        const hunks = g.hunks.flatMap((ref) => {
+            const r = parseRef(ref);
+            const h = r && idMap.get(r.hunk);
+            return h ? [r.ranges ? `${h.id}:${r.ranges.map(([x, y]) => (x === y ? `${x}` : `${x}-${y}`)).join(',')}` : h.id] : [];
+        });
+        return hunks.length ? [{ ...g, hunks }] : [];
+    });
+    const dropped = a.groups.filter((g) => !kept.some((k) => k.id === g.id)).map((g) => g.id);
+    if (!kept.length)
+        return { annotation: null, kept: 0, total: a.groups.length, dropped, gaps: [], partialMatch };
+    // A group may serve one that was left behind; point it at the task instead
+    // and say so, rather than leave a reference validation would reject.
+    const keptIds = new Set(kept.map((g) => g.id));
+    const groups = kept.map((g) => {
+        const targets = servesOf(g);
+        const lost = targets.filter((t) => t !== 'task' && !keptIds.has(t));
+        if (!lost.length)
+            return g;
+        const remaining = targets.filter((t) => t === 'task' || keptIds.has(t));
+        const note = alsoServed(lost, 'glossed with other changes');
+        return { ...g, serves: remaining.length > 1 ? remaining : remaining[0] ?? 'task', notes: g.notes ? `${g.notes} ${note}` : note };
+    });
+    const byId = new Map(current.map((h) => [h.id, h]));
+    const claims = groups.flatMap((g) => [...selections(g.hunks, (id) => { const h = byId.get(id); return h && changedCount(h); })]
+        .flatMap(([id, lines]) => { const h = byId.get(id); return h ? [{ hunk: h, lines }] : []; }));
+    return { annotation: { ...a, groups }, kept: groups.length, total: a.groups.length, dropped, gaps: uncovered(current, claims), partialMatch };
+}

package/dist/cli.js

@@ -0,0 +1,47 @@
+import { GlossError } from './git.js';
+import * as add from './commands/add.js';
+import * as adopt from './commands/adopt.js';
+import * as carry from './commands/carry.js';
+import * as html from './commands/html.js';
+import * as hunks from './commands/hunks.js';
+import * as init from './commands/init.js';
+import * as review from './commands/review.js';
+import * as schema from './commands/schema.js';
+import * as show from './commands/show.js';
+import * as sync from './commands/sync.js';
+import * as versions from './commands/versions.js';
+import * as why from './commands/why.js';
+const COMMANDS = {
+    init, hunks, add, adopt, carry, show, html, why, review, sync, versions, schema,
+};
+function help() {
+    return 'usage: git gloss <command> [options]\n\n' +
+        Object.values(COMMANDS)
+            .map((c) => {
+            const [synopsis, desc] = c.usage.split(/ {3}/);
+            return `  ${synopsis}\n      ${desc}`;
+        })
+            .join('\n');
+}
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+        console.log(help());
+        return 0;
+    }
+    const command = COMMANDS[cmd];
+    if (!command) {
+        console.error(`unknown command "${cmd}"\n\n${help()}`);
+        return 2;
+    }
+    try {
+        return command.run(rest);
+    }
+    catch (err) {
+        if (err instanceof GlossError || err.code?.startsWith('ERR_PARSE_ARGS')) {
+            console.error(`error: ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+}

package/dist/commands/add.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { commitDiff, isWipSnapshot, NOTES_REF, readNote, resolveCommit, WIP_NOTES_REF, writeNote } from '../git.js';
+import { location, parseDiff } from '../diff.js';
+import { Annotation, noteFormat } from '../schema.js';
+import { validate } from '../validate.js';
+export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--dry-run]   attach an annotation (JSON from file or stdin)';
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            file: { type: 'string', short: 'f' },
+            force: { type: 'boolean' },
+            partial: { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+        },
+    });
+    const sha = resolveCommit(positionals[0] ?? 'HEAD');
+    if (!values.file && process.stdin.isTTY) {
+        console.error('error: pipe annotation JSON on stdin or pass -f <file> (see `git gloss schema`)');
+        return 2;
+    }
+    const raw = readFileSync(values.file ?? 0, 'utf8');
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        console.error(`error: annotation is not valid JSON: ${err.message}`);
+        return 1;
+    }
+    const parsed = Annotation.safeParse(json);
+    if (!parsed.success) {
+        console.error('error: annotation does not match the schema:\n' + z.prettifyError(parsed.error));
+        return 1;
+    }
+    const hunks = parseDiff(commitDiff(sha));
+    const { errors, uncovered } = validate(parsed.data, hunks);
+    if (uncovered.length && !values.partial) {
+        errors.push(`hunks not assigned to any group: ${uncovered.join(', ')} (every hunk needs a group, or pass --partial)`);
+    }
+    if (errors.length) {
+        console.error('error: annotation is inconsistent with the commit:\n' + errors.map((e) => `  ✖ ${e}`).join('\n'));
+        return 1;
+    }
+    // Not an error: long intents still work, but they make the summary rows tall.
+    for (const g of parsed.data.groups.filter((g) => g.intent.length > 100)) {
+        console.error(`note: group "${g.id}" has a ${g.intent.length}-character intent; keep it under ~80 and move detail to "notes"`);
+    }
+    if (values['dry-run']) {
+        console.log(`ok: annotation is valid for ${sha.slice(0, 10)} (${parsed.data.groups.length} groups, ${hunks.length} hunks)`);
+        return 0;
+    }
+    // A gloss carried over from an earlier snapshot, or by `carry` from the
+    // commits these changes came from, is a starting point; a fresh gloss
+    // replaces it without --force (the old one stays in the notes history).
+    const existing = values.force ? null : readNote(sha);
+    if (existing && !existing.carried_from && !existing.sources) {
+        console.error(`error: ${sha.slice(0, 10)} already has a gloss; pass --force to replace it`);
+        return 1;
+    }
+    // Store a one-item serves list as a plain string: same meaning, and it keeps
+    // the note readable by versions without list support (format below 3).
+    for (const g of parsed.data.groups)
+        if (Array.isArray(g.serves) && g.serves.length === 1)
+            g.serves = g.serves[0];
+    writeNote(sha, {
+        gloss: noteFormat(parsed.data),
+        commit: sha,
+        created_at: new Date().toISOString(),
+        annotation: parsed.data,
+        hunks: hunks.map(location),
+    }, isWipSnapshot(sha) ? WIP_NOTES_REF : NOTES_REF);
+    console.log(`glossed ${sha.slice(0, 10)}: ${parsed.data.groups.length} groups over ${hunks.length} hunks`);
+    return 0;
+}

package/dist/commands/adopt.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { archiveSnapshot, commitDiff, dropWipNote, git, gitTry, GlossError, readNote, resolveCommit, WIP_REF, writeNote } from '../git.js';
+import { carryGloss } from '../carry.js';
+import { location, parseDiff } from '../diff.js';
+import { noteFormat } from '../schema.js';
+import { refLabel } from '../selection.js';
+import { carriedErrors } from '../validate.js';
+export const usage = 'adopt [<commit>] [--force]   move the gloss of uncommitted work (wip) onto a commit made from it';
+// Carry a wip snapshot's gloss onto a real commit made from it (see
+// carryGloss): a commit takes the groups whose hunks it contains, so the work
+// can be committed in several commits, and its changes the wip gloss doesn't
+// cover are reported.
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        // --quiet-unless-adopted (for the post-commit hook): print nothing when
+        // there was nothing to adopt.
+        options: { force: { type: 'boolean' }, 'quiet-unless-adopted': { type: 'boolean' } },
+    });
+    const quiet = values['quiet-unless-adopted'];
+    const say = (msg) => console.log(msg);
+    const skip = (msg) => { if (!quiet)
+        console.log(msg); return 0; };
+    if (positionals[0] === 'wip') {
+        throw new GlossError('adopt moves the wip gloss onto a commit made from it; give that commit (default HEAD), not wip');
+    }
+    const wip = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+    const wipNote = wip ? readNote(wip) : null;
+    if (!wip || !wipNote)
+        return skip('nothing to adopt: there is no glossed snapshot of uncommitted work');
+    const sha = resolveCommit(positionals[0] ?? 'HEAD');
+    if (!values.force && readNote(sha)) {
+        if (quiet)
+            return 0; // the commit was glossed directly
+        throw new GlossError(`${sha.slice(0, 7)} already has a gloss; pass --force to replace it with the adopted one`);
+    }
+    // Only commits descended from the snapshot's base can contain its work.
+    // During a rebase, the hook stays out: replayed commits' glosses follow them
+    // through notes.rewriteRef instead.
+    const base = git(['log', '-1', '--format=%P', wip]).trim().split(' ')[0];
+    if (base && gitTry(['merge-base', '--is-ancestor', base, sha]) === null) {
+        return skip(`nothing to adopt for ${sha.slice(0, 7)}: it isn't built on the commit the wip snapshot was taken from`);
+    }
+    const rebasing = ['rebase-merge', 'rebase-apply'].some((d) => existsSync(git(['rev-parse', '--git-path', d]).trim()));
+    if (quiet && rebasing)
+        return 0;
+    const current = parseDiff(commitDiff(sha));
+    const carried = carryGloss(wipNote, current, parseDiff(commitDiff(wip)));
+    if (!carried.annotation) {
+        // A glossed hunk split across commits (or edited after glossing) can't be
+        // matched; say so even under the hook, since the gloss would otherwise
+        // never reach any commit without a word.
+        if (carried.partialMatch) {
+            console.log(`git-gloss: ${sha.slice(0, 7)} changes glossed code, but no hunk matches the wip gloss exactly ` +
+                '(a hunk split across commits, or edited after glossing); gloss this commit with: git gloss add');
+            return 0;
+        }
+        return skip(`nothing to adopt for ${sha.slice(0, 7)}: none of its changes are in the wip gloss`);
+    }
+    const { annotation, gaps } = carried;
+    const real = carriedErrors(annotation, current);
+    if (real.length)
+        throw new GlossError(`the adopted gloss doesn't fit ${sha.slice(0, 7)}:\n${real.map((e) => `  ✖ ${e}`).join('\n')}`);
+    writeNote(sha, {
+        gloss: noteFormat(annotation),
+        commit: sha,
+        created_at: new Date().toISOString(),
+        annotation,
+        hunks: current.map(location),
+    });
+    // Once nothing uncommitted is left, the snapshot has served its purpose.
+    const head = gitTry(['rev-parse', '--verify', '--quiet', 'HEAD'])?.trim();
+    const done = head === sha && git(['status', '--porcelain']).trim() === '';
+    const left = carried.total - carried.kept;
+    say(`adopted ${carried.kept} of ${carried.total} wip groups onto ${sha.slice(0, 7)}` +
+        (left > 0 && !done ? `; the other ${left} stay in the wip gloss for later commits` : ''));
+    if (gaps.length) {
+        say(`  not explained by the wip gloss (edited after glossing, or never glossed): ${gaps.map((u) => refLabel(u.hunk.id, u.lines)).join(', ')}`);
+        say(`  gloss them with: git gloss add ${sha.slice(0, 7)} --force -f <annotation including them>`);
+    }
+    if (done) {
+        archiveSnapshot(wip);
+        dropWipNote(wip);
+        git(['update-ref', '-d', WIP_REF]);
+        say('  all work is committed; cleared the wip snapshot');
+    }
+    return 0;
+}

package/dist/commands/carry.js

@@ -0,0 +1,172 @@
+import { parseArgs } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import { commitDiff, git, GlossError, readNote, resolveCommit, resolveCommits, writeNote } from '../git.js';
+import { matchHunks } from '../loader.js';
+import { findOrigins } from '../origins.js';
+import { location, parseDiff } from '../diff.js';
+import { mergeGlosses } from '../merge.js';
+import { noteFormat } from '../schema.js';
+import { refLabel } from '../selection.js';
+import { carriedErrors } from '../validate.js';
+export const usage = 'carry <source>... [--to <commit>] [--force] | carry --find [--squash] [<commit>...]   gloss a commit from the glosses of the commits its changes came from (a squash, cherry-pick or rebase); --find works out which commits those are';
+// The target's current gloss: none, one written by hand, one carried, or one
+// that can't be read (such as the joined notes a squash leaves). Carrying may
+// replace all but a hand-written one without --force.
+export function targetState(sha) {
+    try {
+        const note = readNote(sha);
+        // A carried gloss is a starting point that a better one may replace, as add allows.
+        return note ? (note.sources || note.carried_from ? 'carried' : 'glossed') : 'none';
+    }
+    catch (err) {
+        if (err instanceof GlossError)
+            return 'broken';
+        throw err;
+    }
+}
+// Gloss `target` from the glosses of `sources`. Sources without a readable
+// gloss are skipped. Writes nothing if no source explains any of its changes.
+export function carry(sourceShas, target) {
+    const short = target.slice(0, 7);
+    const sources = [];
+    // Sources whose gloss can't be read are named, so their lines aren't
+    // mistaken for changes nobody glossed.
+    const unreadable = [];
+    for (const sha of sourceShas) {
+        if (sha === target)
+            continue;
+        let note;
+        try {
+            note = readNote(sha);
+        }
+        catch (err) {
+            if (!(err instanceof GlossError))
+                throw err;
+            unreadable.push(`${sha.slice(0, 7)} (${err.message.replace(/^the gloss on \S+ /, '')})`);
+            continue;
+        }
+        if (note)
+            sources.push({ sha, note, hunks: parseDiff(commitDiff(sha)) });
+    }
+    const skipped = unreadable.length ? `\n  skipped sources whose gloss can't be read: ${unreadable.join('; ')}` : '';
+    if (!sources.length)
+        return { written: false, message: `nothing to carry onto ${short}: none of the sources has a readable gloss${skipped}` };
+    const current = parseDiff(commitDiff(target));
+    const merged = mergeGlosses(sources, current);
+    const stale = merged.stale.length ? `\n  skipped glossed hunks that no longer match their commit's diff: ${merged.stale.join(', ')}` : '';
+    if (!merged.annotation)
+        return { written: false, message: `nothing to carry onto ${short}: none of its changes match the sources' glossed changes${skipped}${stale}` };
+    // Changes no source explains are reported below, not errors.
+    const errors = carriedErrors(merged.annotation, current);
+    if (errors.length)
+        throw new GlossError(`the carried gloss doesn't fit ${short}:\n${errors.map((e) => `  ✖ ${e}`).join('\n')}`);
+    writeNote(target, {
+        gloss: noteFormat(merged.annotation),
+        commit: target,
+        created_at: new Date().toISOString(),
+        annotation: merged.annotation,
+        hunks: current.map(location),
+        sources: merged.used,
+    });
+    const lines = [`carried ${merged.annotation.groups.length} group${merged.annotation.groups.length === 1 ? '' : 's'} from ` +
+            `${merged.used.map((s) => s.slice(0, 7)).join(', ')} onto ${short}`];
+    if (merged.dropped.length)
+        lines.push(`  groups with no change left in ${short}: ${merged.dropped.join(', ')}`);
+    if (skipped)
+        lines.push(skipped.slice(1));
+    if (stale)
+        lines.push(stale.slice(1));
+    if (merged.gaps.length) {
+        lines.push(`  not explained by the sources (edited while combining, never glossed${skipped || stale ? ', or in a skipped source' : ''}): ${merged.gaps.map((u) => refLabel(u.hunk.id, u.lines)).join(', ')}`, `  gloss them with: git gloss add ${short} -f <annotation including them>`);
+    }
+    return { written: true, message: lines.join('\n') };
+}
+// Whether a commit's gloss was written for different changes than the
+// commit now has (it was copied onto a rewritten commit whose diff changed).
+function isStale(sha) {
+    const note = readNote(sha);
+    if (!note)
+        return false;
+    return [...matchHunks(note.hunks, parseDiff(commitDiff(sha))).values()].some((r) => r.status !== 'ok');
+}
+// For the post-rewrite hook: git gives "<old> <new>" lines for an amend or a
+// rebase. A commit made from several (squash, fixup) is glossed from all of
+// them, replacing the joined notes notes.rewriteRef leaves; a commit made from
+// one keeps its copied gloss unless the rewrite changed its diff, in which
+// case it is glossed line by line from the original.
+function rewritten(kind, input) {
+    // During a rebase, each squash step also reports an amend of a temporary
+    // commit; the rebase's own report at the end covers them all.
+    const rebasing = ['rebase-merge', 'rebase-apply'].some((d) => existsSync(git(['rev-parse', '--git-path', d]).trim()));
+    if (kind === 'amend' && rebasing)
+        return [];
+    const from = new Map();
+    for (const line of input.split('\n')) {
+        const [old, now] = line.trim().split(/\s+/);
+        if (!old || !now)
+            continue;
+        from.set(now, [...(from.get(now) ?? []), old]);
+    }
+    const out = [];
+    for (const [now, olds] of from) {
+        if (olds.length === 1 && ['glossed', 'carried'].includes(targetState(now)) && !isStale(now))
+            continue;
+        const res = carry(olds, now);
+        if (res.written)
+            out.push(res.message);
+    }
+    return out;
+}
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            to: { type: 'string' },
+            force: { type: 'boolean' },
+            find: { type: 'boolean' },
+            squash: { type: 'boolean' },
+            rewritten: { type: 'string' },
+            quiet: { type: 'boolean' },
+        },
+    });
+    // Hooks print only what they carried, prefixed so it's clear where it came from.
+    const report = (msgs) => { for (const m of msgs)
+        console.log(values.quiet ? `git-gloss: ${m}` : m); };
+    if (values.rewritten) {
+        report(rewritten(values.rewritten, readFileSync(0, 'utf8')));
+        return 0;
+    }
+    if (values.find) {
+        const out = [];
+        for (const target of (positionals.length ? positionals : ['HEAD']).map((p) => resolveCommit(p))) {
+            if (targetState(target) === 'glossed' && !values.force) {
+                if (!values.quiet)
+                    out.push(`${target.slice(0, 7)} already has a gloss`);
+                continue;
+            }
+            const origins = findOrigins(target, { squash: values.squash });
+            if (!origins) {
+                if (!values.quiet)
+                    out.push(`found no glossed commits that ${target.slice(0, 7)}'s changes came from` + (values.squash ? '' : ' (add --squash to look for a squashed branch)'));
+                continue;
+            }
+            const res = carry(origins, target);
+            if (res.written || !values.quiet)
+                out.push(res.message);
+        }
+        report(out);
+        return 0;
+    }
+    if (!positionals.length)
+        throw new GlossError('name the commits the changes came from, e.g. git gloss carry main..feature --to HEAD');
+    const target = resolveCommit(values.to ?? 'HEAD');
+    const state = targetState(target);
+    if (state === 'glossed' && !values.force) {
+        throw new GlossError(`${target.slice(0, 7)} already has a gloss; pass --force to replace it (the old one stays in the notes history)`);
+    }
+    const sources = positionals.flatMap((p) => resolveCommits(p).shas);
+    const res = carry(sources, target);
+    console.log(res.message);
+    return res.written ? 0 : 1;
+}