@ok-ggwp/git-gloss 0.1.0 → 0.3.0

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/page.js

@@ -6,7 +6,7 @@ const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
 export function embedJson(data) {
     return JSON.stringify(data).replace(/</g, '\\u003c');
 }
-const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
 export function renderPage(data) {
     // The page only runs our own inline script. If escaping ever failed, an
     // injected script would lack the nonce and the CSP would block it.

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.3.0",
   "description": "Annotate agent-written diffs with intent and necessity, stored in git notes",
   "license": "MIT",
   "keywords": [

package/skills/gloss/SKILL.md

@@ -25,6 +25,10 @@ Gloss changes **before they are committed**, unless the user asks you to commit
 
 To gloss a commit instead, use its revision (default `HEAD`) wherever these steps say `wip`.
 
+## Calling git-gloss
+
+The commands below are written as `git gloss …`. That works only where git-gloss is on PATH. Check first with `command -v git-gloss`. If it isn't, look for a project install (`node_modules/.bin/git-gloss`, or a `package.json` that lists `@ok-ggwp/git-gloss`) and run the same commands as `pnpm exec git-gloss …`, `npx git-gloss …` or `node_modules/.bin/git-gloss …`. Use the package manager the repo uses. In a monorepo the install may sit in a subdirectory: run the commands from there, and give file paths to `why` relative to that directory. Don't install it globally just to run the skill.
+
 ## Steps
 
 1. Run `git gloss hunks wip` to snapshot the uncommitted work and see it split into hunks with ids `h1`, `h2`, …, with each hunk's changed (`+`/`-`) lines numbered from 1. If you change files afterwards, run it again: that takes a new snapshot, and a gloss must match the snapshot it was written for.
@@ -100,3 +104,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.