@ok-ggwp/git-gloss 0.1.0 → 0.2.0

package/README.md

@@ -30,6 +30,7 @@ git gloss review [<commit>|<range>]   print a review prompt: git gloss review ma
       --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
 ```
 
@@ -43,9 +44,16 @@ 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
 ```
 
+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`:
@@ -73,7 +81,7 @@ In each repo you use it in:
    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`.
+   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.
 
@@ -114,7 +122,24 @@ Nothing is deleted. Replacing a gloss, a group dropped from a wip gloss, or the
 
 `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.
+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
 

package/dist/cli.js

@@ -6,13 +6,14 @@ 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, sync, versions, schema,
+    init, hunks, add, adopt, carry, show, html, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +

package/dist/commands/adopt.js

@@ -6,6 +6,7 @@ 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
@@ -70,6 +71,8 @@ export function run(argv) {
         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() === '';

package/dist/commands/carry.js

@@ -8,6 +8,7 @@ import { mergeGlosses } from '../merge.js';
 import { noteFormat } from '../schema.js';
 import { refLabel } from '../selection.js';
 import { carriedErrors } from '../validate.js';
+import { copyReviews } from '../reviews.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
@@ -68,6 +69,8 @@ export function carry(sourceShas, target) {
         hunks: current.map(location),
         sources: merged.used,
     });
+    // The sources' reviews come along; their keys decide what of this commit they cover.
+    copyReviews(merged.used, target);
     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)

package/dist/commands/hunks.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { commitDiff, dropWipNote, readNote, resolveCommit, snapshotWorkingTree, WIP_NOTES_REF, writeNote } from '../git.js';
 import { carryGloss } from '../carry.js';
+import { copyReviews } from '../reviews.js';
 import { location, parseDiff } from '../diff.js';
 import { noteFormat } from '../schema.js';
 import { colorDiff, hunkLabel, page, style } from '../render.js';
@@ -40,6 +41,9 @@ export function run(argv) {
             // them, since their text is discarded with the old snapshot's gloss.
             if (carried.dropped.length)
                 console.error(`note: not kept (their changes were edited or committed): ${carried.dropped.join(', ')}`);
+            // Reviews of the old snapshot come along; their fingerprints say what
+            // of the new one they still cover.
+            copyReviews([snap.replaced], sha);
             dropWipNote(snap.replaced);
         }
     }

package/dist/commands/init.js

@@ -3,6 +3,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'n
 import { join, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { git, gitTry, NOTES_REF, REMOTE_NOTES_REF, WIP_REF } from '../git.js';
+import { REVIEWS_REF } from '../reviews.js';
 export const usage = 'init [--hooks]   set up glosses to follow amends/rebases and fetch from origin; --hooks: sync on push, adopt wip glosses on commit';
 const HOOK_MARKER = '# installed by git-gloss';
 // Runs before every `git push`. It syncs glosses with the remote being pushed
@@ -84,23 +85,31 @@ function installHook(name, body, done, manual) {
 }
 export function run(argv = []) {
     const { values } = parseArgs({ args: argv, options: { hooks: { type: 'boolean' } } });
+    // Reviews follow commits too; a squash joins their lines, which is what they need.
     const rewriteRefs = gitTry(['config', '--get-all', 'notes.rewriteRef'])?.split('\n') ?? [];
-    if (!rewriteRefs.includes(NOTES_REF))
-        git(['config', '--add', 'notes.rewriteRef', NOTES_REF]);
+    for (const ref of [NOTES_REF, REVIEWS_REF])
+        if (!rewriteRefs.includes(ref))
+            git(['config', '--add', 'notes.rewriteRef', ref]);
     console.log(`✓ glosses follow commits through amend and rebase (notes.rewriteRef=${NOTES_REF})`);
     console.log('  if the commit\'s diff changes, `show` and `review` will flag the gloss as stale');
     if (gitTry(['remote', 'get-url', 'origin'])) {
         // Fetch into a separate ref and merge explicitly. Fetching straight into
         // NOTES_REF with a forced refspec would overwrite unpushed local glosses.
-        const refspec = `+${NOTES_REF}:${REMOTE_NOTES_REF}`;
-        // Earlier versions of init added exactly that destructive refspec.
+        // One glob for the glosses and their reviews: a glob doesn't make
+        // `git fetch` fail while origin has none yet, as a plain refspec does.
+        const refspec = `+${NOTES_REF}*:${REMOTE_NOTES_REF}*`;
+        const fetches = () => gitTry(['config', '--get-all', 'remote.origin.fetch'])?.split('\n') ?? [];
+        // Earlier versions of init added exactly that destructive refspec, and
+        // later ones a plain one that the glob replaces.
         const legacy = `+${NOTES_REF}:${NOTES_REF}`;
-        if (gitTry(['config', '--get-all', 'remote.origin.fetch'])?.split('\n').includes(legacy)) {
+        if (fetches().includes(legacy)) {
             git(['config', '--unset-all', '--fixed-value', 'remote.origin.fetch', legacy]);
             console.log(`✓ removed the old refspec ${legacy}, which overwrote local glosses on fetch`);
         }
-        const fetches = gitTry(['config', '--get-all', 'remote.origin.fetch'])?.split('\n') ?? [];
-        if (!fetches.includes(refspec))
+        const plain = `+${NOTES_REF}:${REMOTE_NOTES_REF}`;
+        if (fetches().includes(plain))
+            git(['config', '--unset-all', '--fixed-value', 'remote.origin.fetch', plain]);
+        if (!fetches().includes(refspec))
             git(['config', '--add', 'remote.origin.fetch', refspec]);
         console.log(`✓ \`git fetch\` stores origin's glosses in ${REMOTE_NOTES_REF}`);
         if (!values.hooks)

package/dist/commands/review.js

@@ -107,7 +107,9 @@ Report, most important first:
 5. **Missing risks**: risks the author did not list.${range ? `
 6. **Across the branch**: later commits that undo, fix or rework earlier ones; the same intent spread over several commits; unglossed commits; whether the branch as a whole is lean for what it sets out to do.` : ''}
 
-For each finding, cite the ${range ? 'commit and ' : ''}group id and explain briefly. If the annotation is accurate and the change is lean, say so.`,
+For each finding, cite the ${range ? 'commit and ' : ''}group id and explain briefly. If the annotation is accurate and the change is lean, say so.
+
+End your report with one line on its own: \`VERDICT: CLEAN\` if you found no mismatches, misgrading or missing risks worth acting on, otherwise \`VERDICT: ISSUES\`. Tools record this line with the review.`,
         '---\n\n# Material under review',
         ...material,
     ];

package/dist/commands/reviews.js

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { commitSubject, gitTry, GlossError, resolveCommits } from '../git.js';
+import { addReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { page, style } from '../render.js';
+export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings; --stamp and --record are for review tools';
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { stamp: { type: 'boolean' }, record: { type: 'boolean' } },
+    });
+    if (values.record) {
+        const input = JSON.parse(readFileSync(0, 'utf8'));
+        for (const k of ['stage', 'agent', 'target', 'findings']) {
+            if (typeof input[k] !== 'string' || !input[k])
+                throw new GlossError(`--record: "${k}" is missing`);
+        }
+        if (!input.stamp || typeof input.stamp !== 'object')
+            throw new GlossError('--record: "stamp" is missing (take it with --stamp before the review)');
+        // Every commit the stamp names must exist before anything is written, so
+        // a bad stamp records nothing rather than part of the review.
+        for (const [sha, seen] of Object.entries(input.stamp)) {
+            if (!/^[0-9a-f]{40,64}$/.test(sha) || gitTry(['cat-file', '-e', `${sha}^{commit}`]) === null) {
+                throw new GlossError(`--record: the stamp names ${sha.slice(0, 12)}, which isn't a commit here`);
+            }
+            if (!Array.isArray(seen?.lines) || !Array.isArray(seen?.groups))
+                throw new GlossError(`--record: the stamp for ${sha.slice(0, 12)} has no lines or groups`);
+        }
+        const id = randomUUID();
+        const at = new Date().toISOString();
+        for (const [sha, seen] of Object.entries(input.stamp)) {
+            const record = {
+                review: 1, id, at, stage: input.stage, agent: input.agent,
+                ...(input.model ? { model: input.model } : {}), ...(input.mode ? { mode: input.mode } : {}),
+                target: input.target, lines: seen.lines, groups: seen.groups, findings: input.findings,
+                ...(verdictOf(input.findings) ? { verdict: verdictOf(input.findings) } : {}),
+            };
+            addReviews(sha, [record]);
+        }
+        const n = Object.keys(input.stamp).length;
+        console.log(`recorded the ${input.stage} review on ${n} commit${n === 1 ? '' : 's'}`);
+        return 0;
+    }
+    const { shas } = resolveCommits(positionals[0] ?? 'HEAD');
+    if (values.stamp) {
+        console.log(JSON.stringify(Object.fromEntries(shas.map((sha) => [sha, stamp(sha)]))));
+        return 0;
+    }
+    const out = [];
+    for (const sha of shas) {
+        const statuses = reviewStatus(sha);
+        out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', commitSubject(sha))}`);
+        if (!statuses.length) {
+            out.push(style('dim', '  no reviews recorded'), '');
+            continue;
+        }
+        for (const s of statuses) {
+            out.push(`  ${statusPhrase(s)}`);
+            for (const r of s.reviews) {
+                out.push('', style('dim', `  ── ${r.stage} by ${r.agent}${r.model ? `:${r.model}` : ''}${r.mode ? ` (${r.mode})` : ''}, ${r.at.slice(0, 16).replace('T', ' ')}, of ${r.target}`));
+                out.push(...r.findings.trim().split('\n').map((l) => `  ${l}`));
+            }
+            out.push('');
+        }
+    }
+    page(out.join('\n'));
+    return 0;
+}

package/dist/commands/show.js

@@ -3,6 +3,7 @@ import { commitSubject, gitTry, readNote, resolveCommits } from '../git.js';
 import { refLabel, sliceStats, sliceText } from '../selection.js';
 import { loadGloss } from '../loader.js';
 import { NECESSITY } from '../schema.js';
+import { current, reviewStatus, statusPhrase, verdict } from '../reviews.js';
 import { colorDiff, field, groupHeader, hunkLabel, necessityWord, noteFooter, page, style, termWidth, wrap, } from '../render.js';
 export const usage = 'show [<commit> | <range>] [-g <group>]... [--full] [--diff] [--only <necessity,...>]   summarise a gloss, or each commit in a range';
 // Counts over the lines each part selects, not whole hunks, so groups that
@@ -77,8 +78,15 @@ export function run(argv) {
     const glosses = shas.map((sha) => loadGloss(sha));
     const glossed = glosses.filter(Boolean).length;
     const stale = glosses.filter((g) => g?.stale).length;
+    // How many glossed commits had their gloss checked: an honesty review that
+    // saw this code and this gloss.
+    const honesty = shas.map((sha, i) => (glosses[i] ? reviewStatus(sha).find((r) => r.stage === 'honesty' && current(r)) : undefined));
+    const vetted = honesty.filter(Boolean).length;
+    const flagged = honesty.filter((r) => r && verdict(r) === 'issues').length;
     const out = [
         style('bold', `${range}: ${shas.length} commit${shas.length === 1 ? '' : 's'}, ${glossed} glossed`) +
+            (glossed ? style(vetted === glossed ? 'green' : 'yellow', `, ${vetted} honesty-reviewed`) : '') +
+            (flagged ? style('yellow', ` (${flagged} with issues)`) : '') +
             (stale ? style('red', ` (${stale} stale)`) : '') +
             (merges.length ? style('dim', `  (${merges.length} merge${merges.length === 1 ? '' : 's'} not shown)`) : ''),
     ];
@@ -98,6 +106,15 @@ export function run(argv) {
     page(out.join('\n'));
     return 0;
 }
+// One line on whether the commit as it is now was reviewed, per stage.
+function reviewsLine(sha) {
+    const statuses = reviewStatus(sha);
+    if (!statuses.length)
+        return style('dim', 'reviews: none recorded');
+    const color = (s) => (!current(s) || verdict(s) === 'issues' ? 'yellow' : verdict(s) === 'clean' ? 'green' : 'dim');
+    return `reviews: ${statuses.map((s) => style(color(s), statusPhrase(s))).join(style('dim', ' · '))}` +
+        style('dim', `   (findings: git gloss reviews ${sha.slice(0, 7)})`);
+}
 // One commit's view, or null if no group matches -g/--only. `hints` adds the
 // footer on how to expand, which a range prints once instead.
 function renderCommit(sha, gloss, values, only, hints) {
@@ -109,6 +126,7 @@ function renderCommit(sha, gloss, values, only, hints) {
         out.push(...field('summary:', a.summary, 0));
     for (const w of gloss.warnings)
         out.push(...field('⚠', w, 0).map((l) => style('red', l)));
+    out.push(reviewsLine(sha));
     const groups = gloss.groups
         .filter((g) => !only || only.includes(g.group.necessity))
         .filter((g) => !values.group || values.group.includes(g.group.id));

package/dist/commands/sync.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { git, gitTry, GitError, NOTES_REF } from '../git.js';
 import { carryNew } from '../origins.js';
+import { REVIEWS_REF } from '../reviews.js';
 import { carry } from './carry.js';
 export const usage = 'sync [<remote>]   fetch, merge and push glosses (default remote: origin)';
 const MAX_ATTEMPTS = 3;
@@ -150,6 +151,51 @@ function round(remote, pushing, carried) {
     }
     return { fetched, pushed: toPush.length, withheld, conflicts };
 }
+const REVIEWS_PUSH_REF = 'refs/notes/gloss-reviews-sync-tmp';
+// Reviews are shared like glosses, but never conflict: each review is a line,
+// and both sides' lines are kept (git's cat_sort_uniq). Only reviews of
+// commits the remote may see are sent. Returns null if the push lost a race.
+function syncReviews(remote, pushing) {
+    const tracking = `refs/notes/remotes/${remote}/gloss-reviews`;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF]) !== null;
+    if (remoteHas)
+        git(['fetch', '-q', remote, `+${REVIEWS_REF}:${tracking}`]);
+    const before = noteList(REVIEWS_REF);
+    const theirs = remoteHas ? noteList(tracking) : new Map();
+    if (remoteHas) {
+        if (gitTry(['rev-parse', '-q', '--verify', REVIEWS_REF]) === null)
+            git(['update-ref', REVIEWS_REF, tracking]);
+        else
+            git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', tracking]);
+    }
+    const merged = noteList(REVIEWS_REF);
+    const fetched = [...merged].filter(([object, blob]) => before.get(object) !== blob).length;
+    const allowed = shareable(remote, pushing);
+    const toPush = [...merged].filter(([object, blob]) => allowed.has(object) && theirs.get(object) !== blob);
+    if (!toPush.length)
+        return { fetched, pushed: 0 };
+    try {
+        if (remoteHas)
+            git(['update-ref', REVIEWS_PUSH_REF, tracking]);
+        else
+            gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+        for (const [object, blob] of toPush)
+            git(['notes', '--ref', REVIEWS_PUSH_REF, 'add', '-f', '-C', blob, object]);
+        try {
+            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`]);
+        }
+        catch (err) {
+            if (/\(fetch first\)|non-fast-forward/.test(err.message))
+                return null;
+            throw err;
+        }
+        git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', REVIEWS_PUSH_REF]);
+    }
+    finally {
+        gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+    }
+    return { fetched, pushed: toPush.length };
+}
 export function run(argv) {
     // --pushing (from the pre-push hook): read the refs being pushed from stdin,
     // as git gives them to the hook, so glosses of those commits go too.
@@ -183,6 +229,13 @@ export function run(argv) {
         }
         for (const c of carried)
             console.log(c);
+        let reviews = null;
+        for (let tries = 0; tries < MAX_ATTEMPTS && !reviews; tries++)
+            reviews = syncReviews(remote, pushing);
+        if (!reviews)
+            console.log(`  reviews not synced: others kept pushing reviews to ${remote}; run git gloss sync again`);
+        else if (reviews.fetched || reviews.pushed)
+            console.log(`  reviews: fetched ${reviews.fetched}, pushed ${reviews.pushed}`);
         if (outcome.withheld) {
             console.log(`  kept ${outcome.withheld} gloss${outcome.withheld === 1 ? '' : 'es'} local: their commits aren't on ${remote} yet`);
         }

package/dist/html/client.js

@@ -188,11 +188,31 @@
     var allGroups = []
     data.commits.forEach(function (c) { allGroups = allGroups.concat(c.groups) })
 
+    // Whether each commit as it is now was reviewed, per stage; each stage's
+    // reports open on demand. Findings are shown as text.
+    function reviewsBlock(c, target) {
+      var box = el('div', 'reviews')
+      if (!c.reviews.length) { add(target, add(box, el('span', 'review-none', 'No reviews recorded'))); return }
+      c.reviews.forEach(function (r) {
+        var d = el('details', 'review')
+        add(d, add(el('summary'), el('span', r.state === 'seen' && r.verdict !== 'issues' ? (r.verdict === 'clean' ? 'review-ok' : 'review-none') : 'stale', r.phrase)))
+        r.entries.forEach(function (e) {
+          add(d, el('div', 'note', r.stage + ' by ' + e.agent + (e.model ? ':' + e.model : '') + (e.mode ? ' (' + e.mode + ')' : '') +
+            ', ' + e.at.slice(0, 16).replace('T', ' ') + ', of ' + e.target), el('pre', 'findings', e.findings))
+        })
+        add(box, d)
+      })
+      add(target, box)
+    }
+
     // Header: the commit itself, or the range and its commits.
     if (multi) {
       var glossed = data.commits.filter(function (c) { return c.glossed }).length
+      var vetted = data.commits.filter(function (c) {
+        return c.glossed && c.reviews.some(function (r) { return r.stage === 'honesty' && r.state === 'seen' })
+      }).length
       add(main, add(el('div', 'commit'), el('span', 'sha', data.range),
-        el('span', null, plural(data.commits.length, 'commit') + ', ' + glossed + ' glossed')))
+        el('span', null, plural(data.commits.length, 'commit') + ', ' + glossed + ' glossed' + (glossed ? ', ' + vetted + ' honesty-reviewed' : ''))))
       add(main, el('h1', null, 'Branch ' + data.range))
       var list = el('ol', 'commit-list')
       data.commits.forEach(function (c) {
@@ -201,6 +221,13 @@
         var li = add(el('li'), a)
         if (!c.glossed) add(li, el('span', 'stale', 'no gloss'))
         else if (c.warnings.length) add(li, el('span', 'stale', 'stale gloss'))
+        if (c.glossed) {
+          var honesty = c.reviews.filter(function (r) { return r.stage === 'honesty' })[0]
+          add(li, !honesty ? el('span', 'stale', 'not reviewed')
+            : honesty.state !== 'seen' ? el('span', 'stale', 'changed since review')
+            : honesty.verdict === 'issues' ? el('span', 'stale', 'honesty: issues found')
+            : el('span', 'review-ok', honesty.verdict === 'clean' ? 'honesty: no issues' : 'honesty-reviewed'))
+        }
         list.appendChild(li)
       })
       data.merges.forEach(function (m) {
@@ -214,6 +241,7 @@
       statement(main, 'Task', only.task)
       statement(main, 'Summary', only.summary)
       only.warnings.forEach(function (w) { add(main, el('div', 'warning', '⚠ ' + w)) })
+      reviewsBlock(only, main)
     }
 
     // Necessity overview across every commit: bar weighted by changed lines,
@@ -266,6 +294,7 @@
         statement(target, 'Task', c.task)
         statement(target, 'Summary', c.summary)
         c.warnings.forEach(function (w) { add(target, el('div', 'warning', '⚠ ' + w)) })
+        reviewsBlock(c, target)
         add(main, target)
       }
       var tocList = commitBody(c, target)

package/dist/html/data.js

@@ -1,8 +1,19 @@
 import { commitDiff, commitSubject, git } from '../git.js';
+import { reviewStatus, statusPhrase, verdict } from '../reviews.js';
 import { parseDiff } from '../diff.js';
 import { loadGloss } from '../loader.js';
 import { bodyLines, changedCount, gapText, isGap, refLabel, slice, sliceStats } from '../selection.js';
 import { NECESSITY, NECESSITY_HELP, servesOf } from '../schema.js';
+function pageReviews(sha) {
+    return reviewStatus(sha).map((s) => ({
+        stage: s.stage,
+        state: s.code === 'changed' ? 'code-changed'
+            : (s.stage === 'honesty' || s.stage === 'improve') && s.gloss === 'changed' ? 'gloss-changed' : 'seen',
+        verdict: verdict(s),
+        phrase: statusPhrase(s),
+        entries: s.reviews.map((r) => ({ agent: r.agent, model: r.model, mode: r.mode, at: r.at, target: r.target, findings: r.findings })),
+    }));
+}
 // The lines to show for a selection: the @@ header, then the slice, with
 // changed lines that belong to other groups collapsed into gap rows.
 export function pageLines(h, selected) {
@@ -102,6 +113,7 @@ export function commitData(gloss) {
         unannotated: gloss.unannotated.map((u) => pageHunk(u.hunk, u.lines, 'unannotated', [])),
         alternatives: a.alternatives ?? [],
         risks: a.risks ?? [],
+        reviews: pageReviews(gloss.sha),
     };
 }
 function unglossedData(sha) {
@@ -118,6 +130,7 @@ function unglossedData(sha) {
         unannotated: parseDiff(commitDiff(sha)).map((h) => pageHunk(h, null, 'unannotated', [])),
         alternatives: [],
         risks: [],
+        reviews: pageReviews(sha),
     };
 }
 export function buildPageData(shas, range = null, merges = []) {

package/dist/html/style.css

@@ -3,6 +3,7 @@
   --surface: #ffffff;
   --surface-2: #f1f1ee;
   --border: #e2e2dc;
+  --ok: #1a7f37;
   --text: #1d1d1b;
   --muted: #6b6b66;
   --accent: #3b5bdb;
@@ -34,6 +35,7 @@
     --surface: #1e1e1c;
     --surface-2: #262624;
     --border: #34342f;
+    --ok: #57c47a;
     --text: #e8e8e3;
     --muted: #9a9a92;
     --accent: #8ea2ff;
@@ -218,3 +220,10 @@ kbd { font-family: var(--mono); font-size: 11.5px; border: 1px solid var(--borde
 .commit-section h2 { font-size: 20px; margin: 8px 0 12px; }
 .commit-section .section h3 { font-size: 16px; margin: 0 0 12px; }
 .toc h2.commit-head { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; text-transform: none; letter-spacing: 0; font-family: var(--mono); }
+
+/* Reviews recorded for a commit */
+.reviews { margin: 8px 0 12px; display: flex; flex-direction: column; gap: 4px; }
+.review summary { cursor: pointer; }
+.review-ok { color: var(--ok); font-weight: 600; }
+.review-none { color: var(--muted); font-size: 0.9em; }
+.findings { white-space: pre-wrap; font-size: 0.85em; max-height: 32em; overflow: auto; padding: 8px; border-left: 3px solid var(--border); }

package/dist/reviews.js

@@ -0,0 +1,205 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { commitDiff, git, gitTry, GlossError, readNote } from './git.js';
+import { parseDiff } from './diff.js';
+import { bodyLines } from './selection.js';
+// Reviews of commits (by git-gud, or anything else that records them), kept
+// beside the glosses so a reader can see whether a gloss was checked. One JSON
+// record per line: notes from different people and machines combine by taking
+// every line (git's cat_sort_uniq), with no conflicts.
+export const REVIEWS_REF = 'refs/notes/gloss-reviews';
+// The report's VERDICT line, which has to be a line of its own among the
+// last three, so a verdict quoted in the body can't stand in for it.
+export function verdictOf(findings) {
+    const tail = findings.trim().split('\n').filter((l) => l.trim()).slice(-3).reverse();
+    for (const line of tail) {
+        // The whole line, give or take markdown: not a sentence that starts so.
+        const m = /^\W*VERDICT:\W*(CLEAN|ISSUES)\W*$/i.exec(line.trim());
+        if (m)
+            return m[1].toLowerCase();
+    }
+    return undefined;
+}
+const key = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+// One key per changed line, repeated for repeated lines (a second "}" is a
+// second key), so adding another copy of a reviewed line isn't "seen". A
+// change with no lines (a binary file, a mode change, a pure rename) is keyed
+// by its file and content hash.
+export const lineKeys = (hunks) => hunks.flatMap((h) => {
+    const lines = bodyLines(h).filter((l) => l.idx !== null);
+    return lines.length ? lines.map((l) => key(`${h.file}\0${l.raw}`)) : [key(`meta\0${h.file}\0${h.hash}`)];
+}).sort();
+// A group's meaning, without its id or hunk references (which change when a
+// gloss is carried or adopted) and without the notes carrying adds.
+export function groupKey(g) {
+    const notes = (g.notes ?? '').replace(/\s*\((?:from [0-9a-f]{7,}|also served [^)]*)\)/g, '').trim();
+    const serves = (Array.isArray(g.serves) ? g.serves : [g.serves]).slice().sort();
+    return key(JSON.stringify([g.intent, g.necessity, serves, g.removal_impact, g.evidence ?? '', notes]));
+}
+// The gloss's parts a reviewer checks: each group, each risk and each
+// rejected alternative (keyed one by one, so a squash that combines several
+// glosses' risks still matches the reviews of each). The task and summary
+// are left out: carrying joins them.
+export function glossKeys(a) {
+    return [
+        ...a.groups.map(groupKey),
+        ...(a.risks ?? []).map((r) => key(`risk\0${r}`)),
+        ...(a.alternatives ?? []).map((x) => key(`alternative\0${x.option}\0${x.rejected_because}`)),
+    ];
+}
+// What a reviewer of `sha` sees now: its changed lines and its gloss's groups.
+export function stamp(sha) {
+    let groups = [];
+    try {
+        const note = readNote(sha);
+        groups = note ? glossKeys(note.annotation) : [];
+    }
+    catch { /* an unreadable gloss: nothing to stamp */ }
+    return { lines: lineKeys(parseDiff(commitDiff(sha))), groups };
+}
+export function readReviews(sha) {
+    const raw = gitTry(['notes', '--ref', REVIEWS_REF, 'show', sha]);
+    if (!raw)
+        return [];
+    // A rebase can join a note onto one with the same lines; each counts once.
+    return [...new Set(raw.split('\n'))].flatMap((line) => {
+        try {
+            const r = JSON.parse(line);
+            // Records arrive from other machines; skip any that aren't whole.
+            const ok = r?.review === 1 && Array.isArray(r.lines) && Array.isArray(r.groups) &&
+                ['id', 'at', 'stage', 'agent', 'target', 'findings'].every((k) => typeof r[k] === 'string') &&
+                ['model', 'mode'].every((k) => r[k] === undefined || typeof r[k] === 'string') &&
+                (r.verdict === undefined || r.verdict === 'clean' || r.verdict === 'issues');
+            return ok ? [r] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+// Adds records to a commit's reviews, keeping each line once. Several
+// reviews can finish at once, so the write is a compare-and-swap: the new
+// notes commit is built under a private ref, and the reviews ref moves to it
+// only if nobody else moved it meanwhile; otherwise it starts again.
+export function addReviews(sha, records) {
+    const mine = records.map((r) => JSON.stringify(r));
+    // git notes needs it under refs/notes; named so the refs/notes/gloss*
+    // fetch glob never matches it.
+    const tmp = `refs/notes/tmp-gloss-reviews-${process.pid}-${randomUUID().slice(0, 8)}`;
+    try {
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const old = gitTry(['rev-parse', '-q', '--verify', REVIEWS_REF])?.trim() ?? null;
+            if (old)
+                git(['update-ref', tmp, old]);
+            else
+                gitTry(['update-ref', '-d', tmp]);
+            const existing = (gitTry(['notes', '--ref', tmp, 'show', sha]) ?? '').split('\n').filter(Boolean);
+            const lines = [...new Set([...existing, ...mine])].sort();
+            git(['notes', '--ref', tmp, 'add', '-f', '-F', '-', sha], lines.join('\n') + '\n');
+            const next = git(['rev-parse', tmp]).trim();
+            // An empty old value means "must not exist yet".
+            if (gitTry(['update-ref', REVIEWS_REF, next, old ?? '']) !== null)
+                return;
+        }
+        throw new GlossError(`couldn't record the review on ${sha.slice(0, 10)}: other processes kept writing reviews at the same time`);
+    }
+    finally {
+        gitTry(['update-ref', '-d', tmp]);
+    }
+}
+// Reviews follow a gloss onto commits made from the reviewed ones (adopt,
+// carry); their keys decide what they still cover there.
+export function copyReviews(from, to) {
+    const records = from.flatMap(readReviews);
+    if (records.length)
+        addReviews(to, records);
+}
+// Whether reviews saw every changed line, counting repeats: each distinct
+// stamp (reviews of different commits, as for a squash) contributes its
+// lines; reviews of the same stamp count once.
+function covers(reviews, lines) {
+    const seen = new Map();
+    const stamps = new Set();
+    for (const r of reviews) {
+        const id = r.lines.join(',');
+        if (stamps.has(id))
+            continue;
+        stamps.add(id);
+        const counts = new Map();
+        for (const l of r.lines)
+            counts.set(l, (counts.get(l) ?? 0) + 1);
+        for (const [l, n] of counts)
+            seen.set(l, (seen.get(l) ?? 0) + n);
+    }
+    const need = new Map();
+    for (const l of lines)
+        need.set(l, (need.get(l) ?? 0) + 1);
+    return [...need].every(([l, n]) => (seen.get(l) ?? 0) >= n);
+}
+// Per stage: whether the commit as it is now was reviewed. A commit squashed
+// from several reviewed ones is covered when their reviews together saw all
+// of it.
+export function reviewStatus(sha, current = stamp(sha)) {
+    const byStage = new Map();
+    for (const r of readReviews(sha))
+        byStage.set(r.stage, [...(byStage.get(r.stage) ?? []), r]);
+    return [...byStage].map(([stage, reviews]) => {
+        const groups = new Set(reviews.flatMap((r) => r.groups));
+        return {
+            stage,
+            now: current,
+            reviews: reviews.sort((a, b) => b.at.localeCompare(a.at)),
+            code: covers(reviews, current.lines) ? 'seen' : 'changed',
+            gloss: current.groups.length ? (current.groups.every((g) => groups.has(g)) ? 'seen' : 'changed') : null,
+        };
+    });
+}
+// Whether this stage's reviews still apply to the commit as it is now.
+export const current = (s) => s.code === 'seen' && !((s.stage === 'honesty' || s.stage === 'improve') && s.gloss === 'changed');
+// What the reviews concluded about the commit as it is now. Each part of it
+// (a gloss group for honesty and improve, else a changed line) takes the
+// verdict of the latest review that saw it, so fixing a gloss and having it
+// reviewed again replaces the earlier verdict for the parts it saw. Issues
+// if any part's latest review found some; clean if every part's said clean.
+export function verdict(s) {
+    const v = latestVerdicts(s);
+    return v.includes('issues') ? 'issues' : v.length && v.every((x) => x === 'clean') ? 'clean' : 'unknown';
+}
+function latestVerdicts(s) {
+    const byGroups = (s.stage === 'honesty' || s.stage === 'improve') && s.now.groups.length;
+    const parts = byGroups ? s.now.groups : s.now.lines;
+    // s.reviews is newest first.
+    const latest = new Set();
+    for (const part of parts) {
+        // A review without a verdict line says nothing either way, so it doesn't
+        // replace an earlier one's.
+        const r = s.reviews.find((r) => r.verdict && (byGroups ? r.groups : r.lines).includes(part));
+        if (r)
+            latest.add(r);
+    }
+    return [...latest].map((r) => r.verdict);
+}
+// Whether a review older than the ones deciding the verdict found issues:
+// a clean result is then shown as following an earlier one with issues.
+export const earlierIssues = (s) => verdict(s) !== 'issues' && s.reviews.some((r) => r.verdict === 'issues');
+// What a verdict means for each stage: improve's "issues" are suggestions.
+const WORDS = {
+    bugs: { clean: 'no defects found', issues: 'defects found' },
+    improve: { clean: 'nothing to improve', issues: 'suggestions' },
+    default: { clean: 'no issues', issues: 'issues found' },
+};
+// One short phrase per stage, for summaries: "honesty: issues found (claude,
+// 2026-10-18)". A review says the commit was checked, not that it passed.
+export function statusPhrase(s) {
+    const latest = s.reviews[0];
+    const who = `${latest.agent}${latest.model ? `:${latest.model}` : ''}, ${latest.at.slice(0, 10)}${s.reviews.length > 1 ? `, ${s.reviews.length} reviews` : ''}`;
+    if (s.code === 'changed')
+        return `${s.stage}: code changed since review (${who})`;
+    if (!current(s)) {
+        const never = s.reviews.every((r) => !r.groups.length);
+        return `${s.stage}: ${never ? 'reviewed before it was glossed' : 'gloss changed since review'} (${who})`;
+    }
+    const v = verdict(s);
+    const words = WORDS[s.stage] ?? WORDS.default;
+    return `${s.stage}: ${v === 'clean' ? words.clean : v === 'issues' ? words.issues : 'reviewed'} (${who}` +
+        `${earlierIssues(s) ? '; an earlier review found issues' : ''})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ok-ggwp/git-gloss",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Annotate agent-written diffs with intent and necessity, stored in git notes",
   "license": "MIT",
   "keywords": [

package/skills/gloss/SKILL.md

@@ -100,3 +100,7 @@ Where you can, set `evidence` to a test that exercises the change or the line of
 You don't need to look up intent before ordinary edits. Use `git gloss why` when you are genuinely unsure why existing code is the way it is, especially before removing or rewriting something that looks unnecessary, defensive or wrong. That is when an unexplained check gets deleted and a fixed bug comes back.
 
 Ask about the block you're changing, not each line: `git gloss why <file>:<start>-<end> --json`. You get one explanation per commit that last changed those lines: the group's intent, `removal_impact`, `notes`, and the commit's `risks` and rejected `alternatives`. Check the alternatives before proposing an approach someone already tried and turned down. If the latest change to the lines was only `mechanical` (a rename, a reformat), `why` looks back past it to the real explanation; `--history` shows every change.
+
+## Reading someone else's branch
+
+When the user asks you to help review a branch or pull request, start from its glosses: `git fetch` (or `git gloss sync`), then `git gloss show <base>..<branch>`. You get each commit's task, groups and grades, and whether its gloss was honesty-reviewed. Lead with what the glosses grade `speculative`, `incidental` or `defensive`, and with commits that have no gloss or whose review found issues. `git gloss reviews <base>..<branch>` prints the recorded findings. A review vouches only for the gloss and code it saw: "changed since review" means it no longer does.