@ok-ggwp/git-gloss 0.0.0-stage → 0.2.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,161 @@
-# 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 reviews [<commit>|<range>]  the reviews recorded for commits, with their findings
+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
+```
+
+Then teach Claude Code to write glosses by installing the `gloss` skill as a plugin, at the prompt of a Claude Code session:
+
+```
+/plugin install git-gloss --marketplace ok-ggwp/git-gloss
+```
+
+Answer `y` to add the marketplace and choose the user scope. From a shell, the same is `claude plugin install git-gloss --marketplace ok-ggwp/git-gloss`. `/plugin update` picks up new versions of the skill. (Without the plugin, a symlink works too: `ln -s "$(npm root -g)/@ok-ggwp/git-gloss/skills/gloss" ~/.claude/skills/gloss`.)
+
+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 (the plugin 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 disposable clone, 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.
+
+### Recorded reviews
+
+git-gud records each review beside the glosses (`refs/notes/gloss-reviews`), so whoever reads a branch later can see whether its glosses were checked and what the checks found:
+
+```
+$ git gloss show main..feature
+main..feature: 4 commits, 4 glossed, 3 honesty-reviewed (1 with issues)
+...
+reviews: honesty: no issues (claude, 2026-10-18) · bugs: defects found (claude, 2026-10-18)
+```
+
+`git gloss reviews <commit>` prints the findings, and the HTML view shows each commit's reviews, with their reports a click away. A review records what it saw: a fingerprint of each changed line and of each gloss group. So it keeps counting through rebases, squashes and a wip gloss moved onto commits. If the code or the gloss changed after the review, the line says so ("gloss changed since review") instead of vouching for it.
+
+A review says that something was checked, not that it passed. Each review ends with a verdict (`VERDICT: CLEAN` or `VERDICT: ISSUES`). For each part of the commit, the latest review that saw it decides, and a clean result that followed one with issues says so.
+
+Like glosses, reviews follow rebased commits in repos set up with `git gloss init`. Reviews are shared by `git gloss sync` (and so by every push with the hooks) like glosses, for commits the remote has. They never conflict: everyone's reviews are kept. Other tools can record reviews too: `git gloss reviews --stamp <rev>` before the review, then `git gloss reviews --record` with the stamp and the report as JSON on stdin.
+
+## 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,48 @@
+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 reviews from './commands/reviews.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, reviews, 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,93 @@
+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';
+import { copyReviews } from '../reviews.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),
+    });
+    // Reviews of the uncommitted work cover the parts of it this commit holds.
+    copyReviews([wip], sha);
+    // 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;
+}