@ok-ggwp/git-gloss 0.4.0 → 0.6.0

package/dist/batch.js

@@ -0,0 +1,129 @@
+import { closeSync, openSync, readSync } from 'node:fs';
+import { GlossError } from './git.js';
+import { checkDecision, MAX_DECISION_LINE } from './reviews.js';
+import { findingTexts } from './findings.js';
+import { plain } from './plain.js';
+// Limits for `reviews --decide-file`, checked before anything is parsed or written.
+export const MAX_BATCH_ENTRIES = 500;
+export const MAX_BATCH_BYTES = 1024 * 1024;
+export const TEMPLATE_TEXT = 80;
+// Reads a file, or stdin for "-", never more than MAX_BATCH_BYTES: a read that
+// goes past it is refused without holding the rest (also for a pipe or /dev/zero).
+export function readBounded(src) {
+    const what = src === '-' ? 'stdin' : plain(src);
+    const fail = (e) => new GlossError(`--decide-file: can't read ${what}: ${e.code ?? 'error'}`);
+    const buf = Buffer.allocUnsafe(MAX_BATCH_BYTES + 1);
+    let fd = 0, total = 0;
+    try {
+        if (src !== '-')
+            fd = openSync(src, 'r');
+        // Until end of input; a full buffer means the input is over the limit.
+        while (total < buf.length) {
+            let n;
+            try {
+                n = readSync(fd, buf, total, buf.length - total, null);
+            }
+            catch (e) {
+                // A non-blocking pipe with nothing yet: wait a little (no busy spin) and ask again.
+                if (e.code !== 'EAGAIN')
+                    throw e;
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                continue;
+            }
+            if (n === 0)
+                break;
+            total += n;
+        }
+    }
+    catch (e) {
+        throw fail(e);
+    }
+    finally {
+        if (fd !== 0)
+            closeSync(fd);
+    }
+    if (total > MAX_BATCH_BYTES)
+        throw new GlossError(`--decide-file: the input is over ${MAX_BATCH_BYTES / 1024 / 1024} MiB; split the decisions into several files`);
+    return buf.toString('utf8', 0, total);
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// Accepts a bare array of {finding, outcome, note?}, or {review?, complete?: boolean,
+// decisions: [...]}. Unknown keys are ignored. Everything is checked here; nothing is written.
+export function parseBatch(text, reviewId) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (e) {
+        throw new GlossError(`--decide-file: not valid JSON (${e instanceof RangeError ? 'nested too deeply' : plain(e.message).slice(0, 120)})`);
+    }
+    let list;
+    let complete = false;
+    if (Array.isArray(data))
+        list = data;
+    else if (isObject(data)) {
+        const d = data.decisions;
+        const c = data.complete;
+        if (c !== undefined && typeof c !== 'boolean')
+            throw new GlossError('--decide-file: "complete" must be true or false');
+        complete = c === true;
+        const r = data.review;
+        if (r !== undefined && r !== '' && r !== reviewId)
+            throw new GlossError(`--decide-file: the file is for review ${plain(String(r)).slice(0, 80)}, not ${plain(reviewId)}`);
+        if (!Array.isArray(d))
+            throw new GlossError('--decide-file: the object needs a "decisions" array');
+        list = d;
+    }
+    else
+        throw new GlossError('--decide-file: expected an array of {finding, outcome, note?}, or an object with a "decisions" array');
+    if (list.length > MAX_BATCH_ENTRIES)
+        throw new GlossError(`--decide-file: ${list.length} entries; at most ${MAX_BATCH_ENTRIES} per file`);
+    if (!list.length && !complete)
+        throw new GlossError('--decide-file: no decisions in the file');
+    // addReviews keeps a repeated line once, so a repeated finding would be counted but not written.
+    const firstAt = new Map();
+    const entries = list.map((e, i) => {
+        const at = `--decide-file: entry ${i + 1}`;
+        if (!isObject(e))
+            throw new GlossError(`${at} is not an object`);
+        const finding = e.finding, outcome = e.outcome, note = e.note;
+        if (typeof finding !== 'string')
+            throw new GlossError(`${at} has no "finding" text`);
+        const label = `${at} ("${plain(finding).slice(0, 40)}")`;
+        if (outcome === undefined || outcome === '')
+            throw new GlossError(`${label} has an empty outcome; fill it in or delete the row`);
+        if (typeof outcome !== 'string')
+            throw new GlossError(`${label}: "outcome" must be a string`);
+        if (note !== undefined && typeof note !== 'string')
+            throw new GlossError(`${label}: "note" must be a string`);
+        try {
+            checkDecision({ finding, outcome, note });
+        }
+        catch (err) {
+            if (err instanceof GlossError)
+                throw new GlossError(`${label}: ${err.message.replace(/^--/, '')}`);
+            throw err;
+        }
+        const seen = firstAt.get(finding.trim());
+        if (seen !== undefined)
+            throw new GlossError(`${label} repeats entry ${seen}`);
+        firstAt.set(finding.trim(), i + 1);
+        return { finding: finding.trim(), outcome: outcome, ...(note ? { note } : {}) };
+    });
+    return { entries, complete };
+}
+// A record that, as written, is a line readers would skip (escapes make control characters longer).
+export function checkLength(record, what) {
+    if (JSON.stringify(record).length > MAX_DECISION_LINE)
+        throw new GlossError(`${what} is too long to record: the finding and note, as written, exceed what readers accept; shorten them`);
+}
+// The skeleton `--decide-template` prints: one row per ref, outcome left empty.
+export function template(reviewId, findings) {
+    const rows = findingTexts(findings);
+    if (rows.length > MAX_BATCH_ENTRIES)
+        throw new GlossError(`review ${plain(reviewId)} has ${rows.length} findings; --decide-file takes at most ${MAX_BATCH_ENTRIES}`);
+    return {
+        review: reviewId, complete: false,
+        decisions: rows.map(([ref, text]) => ({ finding: `${ref}${ref.includes('.') ? '' : ':'} ${[...plain(text).replace(/\s+/g, ' ').trim()].slice(0, TEMPLATE_TEXT).join('')}`.trim(), outcome: '', note: '' })),
+    };
+}

package/dist/cli.js

@@ -7,6 +7,7 @@ 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 lint from './commands/lint.js';
 import * as reviews from './commands/reviews.js';
 import * as schema from './commands/schema.js';
 import * as show from './commands/show.js';
@@ -15,7 +16,7 @@ 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, signals, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
+    init, hunks, signals, lint, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +

package/dist/commands/ary.js

@@ -2,10 +2,10 @@ import { parseArgs } from 'node:util';
 import { createAry } from '../ary/server.js';
 import { GlossError, git } from '../git.js';
 import { openInBrowser } from './html.js';
-export const usage = 'ary [--port <n>] [--no-open]   browse glosses of branches, commits and uncommitted work in a local web page';
+export const usage = 'ary [--port <n>] [--no-open]   browse glosses of branches, commits and uncommitted work in a local web page (the html view with branch pickers)';
 // Starts a read-only server on this machine and keeps running until stopped.
-// The browser page lists branches and commits and shows each selection with
-// the same view as `git gloss html`.
+// The browser page is the same view as `git gloss html`, with branch pickers
+// and a revision box in its top bar; each choice loads a new page.
 export function run(argv) {
     const { values } = parseArgs({
         args: argv,

package/dist/commands/lint.js

@@ -0,0 +1,96 @@
+import { parseArgs } from 'node:util';
+import { GlossError, resolveCommits } from '../git.js';
+import { loadGloss } from '../loader.js';
+import { ratingIssues, tryAnalyze, whyText } from '../floor.js';
+import { attentionRank, impactRank } from '../attention.js';
+import { servesOf } from '../schema.js';
+import { unknownServes } from '../validate.js';
+import { plain } from '../plain.js';
+export const usage = 'lint [<commit> | wip] [--json]   advisory checks of a gloss that a reviewer would make by eye (always exits 0 for findings)';
+// What removal_impact says when it admits the group is not needed. Matched on the
+// lowercased text, after plain(): BARE phrases only when they are the whole text
+// ("Nothing." but not "Nothing else would work"); the others may start it.
+const NOTHING_BREAKS_WHOLE = ['nothing', 'none', 'n/a'];
+const NOTHING_BREAKS_START = ['nothing breaks', 'nothing would break', 'nothing is lost', 'nothing happens', 'no effect', 'no impact'];
+export function saysNothingBreaks(text) {
+    const t = plain(text).toLowerCase().trim().replace(/[\s.!;:,]+$/, '');
+    if (NOTHING_BREAKS_WHOLE.includes(t))
+        return true;
+    return NOTHING_BREAKS_START.some((p) => t === p || (t.startsWith(p) && /^[\s.,;:!-]/.test(t.slice(p.length))));
+}
+export function run(argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { json: { type: 'boolean' } } });
+    const arg = positionals[0] ?? 'HEAD';
+    const { shas, range } = resolveCommits(arg);
+    if (range)
+        throw new GlossError(`${arg}: lint takes one commit or wip, not a range`);
+    const sha = shas[0];
+    const gloss = loadGloss(sha);
+    if (!gloss)
+        throw new GlossError(`${sha.slice(0, 10)} has no gloss (annotate it with \`git gloss add\`)`);
+    for (const w of gloss.warnings)
+        console.error(`warning: ${plain(w)}`);
+    const a = gloss.note.annotation;
+    const findings = [];
+    // Text from a note is sanitized here, once, for both outputs.
+    const add = (code, message, at = {}) => findings.push({ code, ...(at.group !== undefined && { group: plain(at.group) }), ...(at.hunk !== undefined && { hunk: plain(at.hunk) }), message: plain(message) });
+    const ids = new Set(a.groups.map((g) => g.id));
+    const an = tryAnalyze(gloss);
+    if (an) {
+        const issues = ratingIssues(a, an);
+        for (const u of issues.unrated)
+            add('no-impact', `no impact rated${u.signal ? ` (floor ${u.floor}: ${whyText(u.why)})` : ''}`, { group: u.id });
+        for (const b of issues.belowFloor)
+            add('impact-below-floor', `impact "${b.impact}" is below its floor "${b.floor}" (${whyText(b.why)})`, { group: b.id });
+        if (issues.attention)
+            add('attention-below-floor', `attention "${issues.attention.level}" is below the computed floor "${issues.attention.floor}" (${issues.attention.why}) and has no override_reason`);
+        const sigOf = new Map(an.signals.hunks.map((s) => [s.id, s]));
+        for (const g of gloss.groups) {
+            const f = an.groups.get(g.group.id);
+            // A mechanical group made only of lockfiles, docs, tests or generated files sits on a path-class floor honestly (the skill's lockfile example).
+            const real = g.hunks.some((h) => h.current && !sigOf.get(h.current.id)?.inert);
+            if (g.group.necessity === 'mechanical' && f && impactRank(f.floor) > impactRank('module') && real) {
+                add('mechanical-on-floor', `graded mechanical but its floor is "${f.floor}" (${whyText(f.why)})`, { group: g.group.id });
+            }
+            if (f?.testsOnly && !servesOf(g.group).some((t) => t !== 'task' && ids.has(t) && t !== g.group.id)) {
+                add('test-serves-nothing', 'a test group that serves no existing group (set serves to the groups it verifies)', { group: g.group.id });
+            }
+        }
+    }
+    for (const g of a.groups) {
+        const bad = unknownServes(g, ids);
+        if (bad.length)
+            add('unknown-serves', `serves names no such group: ${bad.map((t) => `"${t}"`).join(', ')}`, { group: g.id });
+        if (g.necessity === 'required' && saysNothingBreaks(g.removal_impact)) {
+            add('required-but-nothing-breaks', `graded required but removal_impact says: "${g.removal_impact}"`, { group: g.id });
+        }
+    }
+    const level = a.attention?.level ?? an?.derived.level;
+    if (level && attentionRank(level) >= attentionRank('careful') && !a.risks?.length) {
+        add('missing-risks', `attention is ${level} but no risks are listed`);
+    }
+    for (const u of gloss.unannotated) {
+        add('uncovered-hunks', `${u.hunk.file}: ${u.lines ? `changed lines ${[...u.lines].join(',')}` : 'the whole hunk'} not covered by any group`, { hunk: u.hunk.id });
+    }
+    if (values.json) {
+        console.log(JSON.stringify({ target: sha.slice(0, 10), findings, ...(an ? {} : { incomplete: true }) }, null, 2));
+        return 0;
+    }
+    const subjects = new Map();
+    for (const f of findings) {
+        const key = f.group !== undefined ? `group ${f.group}` : f.hunk !== undefined ? `hunk ${f.hunk}` : 'whole gloss';
+        subjects.set(key, [...(subjects.get(key) ?? []), f]);
+    }
+    for (const [key, fs] of subjects) {
+        console.log(key);
+        for (const f of fs)
+            console.log(`  ${f.code.padEnd(28)} ${f.message}`);
+    }
+    if (findings.length)
+        console.log(`${findings.length} finding${findings.length === 1 ? '' : 's'}`);
+    if (!an)
+        console.log('incomplete: the rating checks need the diff signals, which are unavailable (see the warning above)');
+    else if (!findings.length)
+        console.log('clean');
+    return 0;
+}

package/dist/commands/review.js

@@ -1,4 +1,5 @@
 import { parseArgs } from 'node:util';
+import { plain } from '../plain.js';
 import { commitDiff, commitSubject, isWipSnapshot, resolveCommits } from '../git.js';
 import { parseDiff } from '../diff.js';
 import { refLabel, sliceText } from '../selection.js';
@@ -15,16 +16,16 @@ function fenced(lang, body) {
 // Author text is JSON-quoted so it stays on one line and can't fake a heading
 // or end the material section.
 const q = (s) => JSON.stringify(s);
-const hunkLine = (h) => `- ${h.id} ${h.oldFile && h.oldFile !== h.file ? `${h.oldFile} → ` : ''}${h.file} ` +
+const hunkLine = (h) => `- ${h.id} ${plain(h.oldFile && h.oldFile !== h.file ? `${h.oldFile} → ${h.file}` : h.file)} ` +
     `(-${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines}, +${h.added} -${h.removed})`;
 // The material for one commit: its gloss and the code under each group, or,
 // for an unglossed commit in a range, its whole diff.
 function commitMaterial(sha, gloss) {
     if (!gloss) {
         return [
-            `## Commit ${sha.slice(0, 10)}: ${commitSubject(sha)}`,
+            `## Commit ${sha.slice(0, 10)}: ${plain(commitSubject(sha))}`,
             'This commit has no gloss. Review its changes as unexplained.',
-            fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${h.file}\n${h.text}`).join('\n')),
+            fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${plain(h.file)}\n${h.text}`).join('\n')),
         ];
     }
     const a = gloss.note.annotation;
@@ -47,7 +48,7 @@ function commitMaterial(sha, gloss) {
     const sections = [
         isWipSnapshot(sha)
             ? `## Uncommitted work (snapshot ${sha.slice(0, 10)})\n\nThese changes are not committed yet; the author glossed them before committing.`
-            : `## Commit ${sha.slice(0, 10)}: ${gloss.subject}`,
+            : `## Commit ${sha.slice(0, 10)}: ${plain(gloss.subject)}`,
         ...gloss.warnings.map((w) => `> **Warning from git-gloss:** ${w}`),
         `**Task (author's statement):** ${q(a.task)}`,
         ...(a.summary ? [`**Summary (author's statement):** ${q(a.summary)}`] : []),

package/dist/commands/reviews.js

@@ -2,15 +2,34 @@ 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 { addReviews, checkBy, checkDecision, isValidDecision, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { findingRefs, labelFindings, orderDecisions, refOf } from '../findings.js';
+import { plain } from '../plain.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';
+import { checkLength, parseBatch, readBounded, template } from '../batch.js';
+export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings and what was decided about them\n  reviews <target> --decide <review-id> --finding <text> --outcome <fixed|follow-up|rejected|accepted> [--note <text>] [--by <name>]\n  reviews <target> --decide <review-id> --complete   the arbiter is done\n  reviews <target> --decide-template <review-id>   print a JSON skeleton of the findings of a review to fill in\n  reviews <target> --decide <review-id> --decide-file <file|->   record every decision of the filled-in skeleton at once, or none; --stamp, --record and --decide are for tools';
 export function run(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { stamp: { type: 'boolean' }, record: { type: 'boolean' } },
+        options: {
+            stamp: { type: 'boolean' }, record: { type: 'boolean' }, decide: { type: 'string' }, finding: { type: 'string' },
+            outcome: { type: 'string' }, 'decide-file': { type: 'string' }, 'decide-template': { type: 'string' }, note: { type: 'string' }, complete: { type: 'boolean' }, by: { type: 'string' },
+        },
     });
+    const batchFlag = values['decide-file'] !== undefined ? '--decide-file' : values['decide-template'] !== undefined ? '--decide-template' : null;
+    if (batchFlag) {
+        for (const k of ['finding', 'outcome', 'note', 'complete', 'stamp', 'record']) {
+            if (values[k] !== undefined)
+                throw new GlossError(`${batchFlag} cannot be combined with --${k}`);
+        }
+        if (values['decide-file'] !== undefined && values['decide-template'] !== undefined)
+            throw new GlossError('--decide-file and --decide-template cannot be combined');
+        if (batchFlag === '--decide-template' && (values.decide !== undefined || values.by !== undefined))
+            throw new GlossError('--decide-template takes the review id itself and no --decide or --by');
+        if (batchFlag === '--decide-file' && values.decide === undefined)
+            throw new GlossError('--decide-file goes with --decide <review-id>');
+    }
     if (values.record) {
         const input = JSON.parse(readFileSync(0, 'utf8'));
         for (const k of ['stage', 'agent', 'target', 'findings']) {
@@ -28,6 +47,9 @@ export function run(argv) {
             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`);
         }
+        // Readers skip what is over these limits, so a record that is would vanish: refuse it here instead.
+        if (input.findings.length > MAX_FINDINGS)
+            throw new GlossError(`--record: the findings are too long (${input.findings.length} characters; readers skip reports over ${MAX_FINDINGS / 1024} KiB); shorten the report`);
         const id = randomUUID();
         const at = new Date().toISOString();
         for (const [sha, seen] of Object.entries(input.stamp)) {
@@ -37,6 +59,8 @@ export function run(argv) {
                 target: input.target, lines: seen.lines, groups: seen.groups, findings: input.findings,
                 ...(verdictOf(input.findings) ? { verdict: verdictOf(input.findings) } : {}),
             };
+            if (JSON.stringify(record).length > MAX_REVIEW_LINE)
+                throw new GlossError(`--record: the record for ${sha.slice(0, 10)} is over ${MAX_REVIEW_LINE / 1024 / 1024} MiB with its stamp, which readers skip; review fewer changed lines at a time`);
             addReviews(sha, [record]);
         }
         const n = Object.keys(input.stamp).length;
@@ -44,6 +68,85 @@ export function run(argv) {
         return 0;
     }
     const { shas } = resolveCommits(positionals[0] ?? 'HEAD');
+    const target = positionals[0] ?? 'HEAD';
+    // Every commit of the target holding that review gets the decision.
+    const holdersOf = (id) => {
+        const holders = shas.filter((sha) => readReviews(sha).some((r) => r.id === id));
+        if (!holders.length) {
+            const known = [...new Set(shas.flatMap(readReviews).map((r) => r.id))];
+            throw new GlossError(`no review ${id} on ${target}` + (known.length ? ` (reviews there: ${plain(known.join(', '))})` : ' (it has no reviews)'));
+        }
+        return holders;
+    };
+    const reportOf = (id, holders) => holders.flatMap(readReviews).find((r) => r.id === id);
+    // A finding that starts with a ref names a finding of the report: say so when there is none (never refuse).
+    const warnUnknownRef = (id, report, finding, hint = '') => {
+        const ref = refOf(finding);
+        if (ref !== null && report && !findingRefs(report.findings).has(ref))
+            console.error(`git-gloss: review ${plain(id)} has no finding ${ref} (${hint}see the refs in \`git gloss reviews ${target}\`); recording it anyway`);
+    };
+    if (values['decide-template'] !== undefined) {
+        const id = values['decide-template'];
+        const report = reportOf(id, holdersOf(id));
+        console.log(JSON.stringify(template(id, report.findings), null, 2));
+        return 0;
+    }
+    if (values['decide-file'] !== undefined) {
+        const id = values.decide;
+        // Everything is checked before the first write: one bad entry records nothing.
+        const batch = parseBatch(readBounded(values['decide-file']), id);
+        const holders = holdersOf(id);
+        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
+        checkBy(by);
+        const at = new Date().toISOString();
+        const records = batch.entries.map((e, i) => {
+            const r = { decision: 1, review: id, at, by, finding: e.finding, outcome: e.outcome, ...(e.note ? { note: e.note } : {}) };
+            checkLength(r, `--decide-file: entry ${i + 1}`);
+            return r;
+        });
+        if (batch.complete)
+            records.push({ decision: 1, review: id, at, by, complete: true });
+        const report = reportOf(id, holders);
+        batch.entries.forEach((e, i) => warnUnknownRef(id, report, e.finding, `entry ${i + 1}; `));
+        // One compare-and-swap write per commit, whatever the number of records.
+        for (const sha of holders)
+            addReviews(sha, records);
+        const n = batch.entries.length;
+        console.log(`recorded ${n} decision${n === 1 ? '' : 's'} on ${holders.length} commit${holders.length === 1 ? '' : 's'}${batch.complete ? ' and marked the review complete' : ''}`);
+        return 0;
+    }
+    if (values.decide !== undefined) {
+        const id = values.decide;
+        if (values.complete) {
+            if (!isValidDecision({ complete: true, finding: values.finding, outcome: values.outcome, note: values.note })) {
+                throw new GlossError('--complete marks the review as arbitrated; it takes no --finding, --outcome or --note');
+            }
+        }
+        else
+            checkDecision(values);
+        const holders = holdersOf(id);
+        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
+        checkBy(by);
+        const record = {
+            decision: 1, review: id, at: new Date().toISOString(), by,
+            ...(values.complete ? { complete: true } : {
+                finding: values.finding.trim(), outcome: values.outcome,
+                ...(values.note ? { note: values.note } : {}),
+            }),
+        };
+        // Control characters are written as 6-byte escapes, so check the line itself against the reader's cap.
+        checkLength(record, 'that decision');
+        if (record.finding !== undefined)
+            warnUnknownRef(id, reportOf(id, holders), record.finding);
+        for (const sha of holders)
+            addReviews(sha, [record]);
+        console.log(`recorded ${values.complete ? 'the review as complete' : `"${record.finding}": ${record.outcome}`} on ${holders.length} commit${holders.length === 1 ? '' : 's'}`);
+        return 0;
+    }
+    for (const k of ['finding', 'outcome', 'note', 'complete', 'by']) {
+        if (values[k] !== undefined)
+            throw new GlossError(`--${k} goes with --decide <review-id>`);
+    }
     if (values.stamp) {
         console.log(JSON.stringify(Object.fromEntries(shas.map((sha) => [sha, stamp(sha)]))));
         return 0;
@@ -51,7 +154,8 @@ export function run(argv) {
     const out = [];
     for (const sha of shas) {
         const statuses = reviewStatus(sha);
-        out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', commitSubject(sha))}`);
+        const decisions = readDecisions(sha);
+        out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`);
         if (!statuses.length) {
             out.push(style('dim', '  no reviews recorded'), '');
             continue;
@@ -59,8 +163,15 @@ export function run(argv) {
         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('', 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}, id ${plain(r.id)}`));
+                out.push(...labelFindings(r.findings).trim().split('\n').map((l) => `  ${l}`));
+                const ds = decisions.filter((d) => d.review === r.id);
+                if (r.verdict !== 'clean' || ds.length) {
+                    out.push('', `  decisions on this review: ${decisionSummary(ds)}`);
+                    for (const d of orderDecisions(ds.filter((d) => d.outcome))) {
+                        out.push(`    ${d.outcome}: ${plain(d.finding)}${d.note ? ` — ${plain(d.note)}` : ''} ${style('dim', `(${plain(d.by)}, ${plain(d.at).slice(0, 10)})`)}`);
+                    }
+                }
             }
             out.push('');
         }

package/dist/commands/show.js

@@ -5,7 +5,8 @@ import { loadGloss } from '../loader.js';
 import { impactRank } from '../attention.js';
 import { showsImpact, tryAnalyze } from '../floor.js';
 import { IMPACT, NECESSITY, isImpact, isNecessity } from '../schema.js';
-import { current, reviewStatus, statusPhrase, verdict } from '../reviews.js';
+import { current, decisionSummary, readDecisions, readReviews, reviewStatus, statusPhrase, verdict } from '../reviews.js';
+import { plain } from '../plain.js';
 import { attentionBlock, colorDiff, derivedImpactTag, field, groupHeader, hunkLabel, IMPACT_W, impactTag, necessityWord, noteFooter, page, style, termWidth, wrap, } from '../render.js';
 export const usage = 'show [<commit> | <range>] [-g <group>]... [--full] [--diff] [--only <necessity|impact,...> (a group must match each kind named)] [--sort impact]   summarise a gloss, or each commit in a range';
 // Counts over the lines each part selects, not whole hunks, so groups that
@@ -102,12 +103,12 @@ export function run(argv) {
         out.push('', style('dim', '─'.repeat(Math.min(termWidth(), 60))));
         const gloss = glosses[i];
         if (!gloss) {
-            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', commitSubject(sha))}`, style('dim', 'no gloss for this commit'));
+            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`, style('dim', 'no gloss for this commit'));
             return;
         }
         // An --only filter can leave a commit with nothing to show; say so and move on.
         out.push(...(renderCommit(sha, gloss, values, only, false) ??
-            [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`, style('dim', `no ${only?.names.join('/')} groups`)]));
+            [`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(gloss.subject))}`, style('dim', `no ${only?.names.join('/')} groups`)]));
     });
     if (glossed)
         out.push('', style('dim', 'One commit in detail: git gloss show <commit> --full   (or -g <group> for its code)'));
@@ -122,7 +123,14 @@ function reviewsLine(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', ' · '))}` +
+    // What was decided about the reviews that found something (or didn't say);
+    // a commit with only clean reviews has nothing to decide.
+    const open = readReviews(sha).filter((r) => r.verdict !== 'clean');
+    const decisions = readDecisions(sha).filter((d) => open.some((r) => r.id === d.review));
+    const decided = open.length
+        ? ` ${style('dim', '·')} decisions: ${decisionSummary(decisions, open.every((r) => decisions.some((d) => d.review === r.id && d.complete)))}`
+        : '';
+    return `reviews: ${statuses.map((s) => style(color(s), statusPhrase(s))).join(style('dim', ' · '))}${decided}` +
         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
@@ -130,14 +138,14 @@ function reviewsLine(sha) {
 function renderCommit(sha, gloss, values, only, hints) {
     const a = gloss.note.annotation;
     const short = sha.slice(0, 7);
-    const out = [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`];
+    const out = [`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(gloss.subject))}`];
     out.push(...field('task:', a.task, 0));
     if (a.summary)
         out.push(...field('summary:', a.summary, 0));
     for (const w of gloss.warnings)
         out.push(...field('⚠', w, 0).map((l) => style('red', l)));
     const an = tryAnalyze(gloss);
-    out.push(...attentionBlock(a.attention, an ? { floor: an.floor, derived: an.derived } : undefined), reviewsLine(sha));
+    out.push(...attentionBlock(a.attention, an ? { floor: an.floor, derived: an.derived, timedOut: an.timedOut } : undefined), reviewsLine(sha));
     const groups = gloss.groups
         .filter((g) => matchesOnly(g.group, only))
         .filter((g) => !values.group || values.group.includes(g.group.id));

package/dist/commands/signals.js

@@ -1,3 +1,4 @@
+import { plain } from '../plain.js';
 import { parseArgs } from 'node:util';
 import { loadConfig } from '../config.js';
 import { commitDiff, diffBetween, git, GitError, resolveCommit, workingDiff } from '../git.js';
@@ -17,11 +18,11 @@ export function summaryLines(sig, max = 6) {
     const files = sig.files.filter((f) => impactRank(f.floor) >= impactRank('shared'))
         .sort((a, b) => impactRank(b.floor) - impactRank(a.floor) || a.file.localeCompare(b.file));
     for (const f of files.slice(0, max))
-        out.push(`  ${(f.floor + ':').padEnd(10)} ${f.file}${f.why.length ? ` (${f.why.join('; ')})` : ''}`);
+        out.push(`  ${(f.floor + ':').padEnd(10)} ${plain(f.file)}${f.why.length ? ` (${plain(f.why.join('; '))})` : ''}`);
     if (files.length > max)
         out.push(`  ... and ${files.length - max} more at shared or above (git gloss signals)`);
     for (const r of sig.floor.reasons.filter((r) => / files changed /.test(r)))
-        out.push(`  large:     ${r}`);
+        out.push(`  large:     ${plain(r)}`);
     if (sig.floor.reasons.includes(CONFIG_EDIT_NOTE))
         out.push(`  note:      ${CONFIG_EDIT_NOTE}`);
     out.push(`  stats: ${statsLine(sig.stats)}`);
@@ -31,16 +32,16 @@ function detailLines(sig, label) {
     const out = [style('bold', `signals for ${label}:`) + ` floor attention = ${style(['bold', ATTENTION_STYLE[sig.floor.attention]], sig.floor.attention)}` +
             style('dim', `  (floor impact: ${sig.floor.impact})`)];
     for (const r of sig.floor.reasons)
-        out.push(`  why: ${r}`);
+        out.push(`  why: ${plain(r)}`);
     out.push(`  stats: ${statsLine(sig.stats)}`);
     const notable = sig.hunks.filter((h) => impactRank(h.floor) > impactRank('module') || h.hits.length);
     if (notable.length)
         out.push('', style('bold', 'hunks with signals'));
     for (const h of notable) {
-        out.push(`  ${style('bold', h.id.padEnd(5))} ${impactTag(h.floor, 11)} ${h.file}` +
-            style('dim', `  [${h.classes.join(', ') || 'no class'}]${h.why.length ? ' ' + h.why.join('; ') : ''}`));
+        out.push(`  ${style('bold', h.id.padEnd(5))} ${impactTag(h.floor, 11)} ${plain(h.file)}` +
+            style('dim', `  [${h.classes.join(', ') || 'no class'}]${h.why.length ? ' ' + plain(h.why.join('; ')) : ''}`));
         for (const x of h.hits.slice(0, 8)) {
-            out.push(`        ${h.id}:${x.line} ${x.sign} ${x.class} pattern "${x.name}"${x.damped ? style('dim', ' (damped: test, docs or lockfile path)') : ''}  ${style('dim', x.text)}`);
+            out.push(`        ${h.id}:${x.line} ${x.sign} ${x.class} pattern "${x.name}"${x.timedOut ? ' (pattern timed out: counted as matching)' : ''}${x.damped ? style('dim', ' (damped: test, docs or lockfile path)') : ''}  ${style('dim', plain(x.text))}`);
         }
         if (h.hits.length > 8)
             out.push(style('dim', `        ... ${h.hits.length - 8} more hits (--json)`));
@@ -51,9 +52,9 @@ function detailLines(sig, label) {
     if (sig.dependencies.length)
         out.push('', style('bold', 'dependency changes'));
     for (const d of sig.dependencies) {
-        out.push(`  ${d.file} (${d.kind}${d.format ? `, parsed as ${d.format}` : d.kind === 'lockfile' ? ', no version detail for this format' : ''})`);
+        out.push(`  ${plain(d.file)} (${d.kind}${d.format ? `, parsed as ${d.format}` : d.kind === 'lockfile' ? ', no version detail for this format' : ''})`);
         for (const b of d.bumps.slice(0, 20)) {
-            const what = b.kind === 'bump' ? `${b.name} ${b.from} -> ${b.to}` : b.kind === 'added' ? `+ ${b.name} ${b.to}` : `- ${b.name} ${b.from}`;
+            const what = plain(b.kind === 'bump' ? `${b.name} ${b.from} -> ${b.to}` : b.kind === 'added' ? `+ ${b.name} ${b.to}` : `- ${b.name} ${b.from}`);
             out.push(`    ${what}${b.unrelated ? style('yellow', '  (transitive: no manifest change names it)') : ''}`);
         }
         if (d.bumps.length > 20)

package/dist/commands/sync.js

@@ -46,6 +46,18 @@ function shareable(remote, pushing) {
         return new Set();
     return new Set(git(['rev-list', ...starts, '--']).split('\n').filter(Boolean));
 }
+// The fetched ref is the remote's to set: it must be a commit before notes
+// code (or an update-ref onto our own notes ref) touches it.
+function checkTracking(remote, ref, tracking) {
+    if (gitTry(['rev-parse', '-q', '--verify', `${tracking}^{commit}`]) === null) {
+        gitTry(['update-ref', '-d', tracking]);
+        throw new GitError(`${remote}'s ${ref} is not a notes commit; ignoring it (nothing was changed here)`);
+    }
+}
+function fetchTracking(remote, ref, tracking) {
+    git(['fetch', '-q', remote, `+${ref}:${tracking}`]);
+    checkTracking(remote, ref, tracking);
+}
 const PUSH_REF = 'refs/notes/gloss-sync-tmp';
 // One fetch → merge → push round. Returns null if the push lost a race with
 // someone else's push and the round should be retried.
@@ -53,7 +65,7 @@ function round(remote, pushing, carried) {
     const tracking = `refs/notes/remotes/${remote}/gloss`;
     const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF]) !== null;
     if (remoteHas)
-        git(['fetch', '-q', remote, `+${NOTES_REF}:${tracking}`]);
+        fetchTracking(remote, NOTES_REF, tracking);
     const local = noteList(NOTES_REF);
     const theirs = remoteHas ? noteList(tracking) : new Map();
     // The last state both sides shared. A gloss changed on one side only is
@@ -159,7 +171,7 @@ 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}`]);
+        fetchTracking(remote, REVIEWS_REF, tracking);
     const before = noteList(REVIEWS_REF);
     const theirs = remoteHas ? noteList(tracking) : new Map();
     if (remoteHas) {

package/dist/commands/why.js

@@ -1,3 +1,4 @@
+import { plain } from '../plain.js';
 import { parseArgs } from 'node:util';
 import { blameRange, commitSubject, lineHistory } from '../git.js';
 import { loadGloss } from '../loader.js';
@@ -158,8 +159,8 @@ export function run(argv) {
     const renderStep = (s, label, older) => {
         // Where the lines were in an older commit: after edits or a file rename
         // that differs from the query.
-        const then = older || s.file !== file ? style('dim', `  (${s.file}:${formatRanges(s.lines)} then)`) : '';
-        out.push(`${label}${style('yellow', s.commit.slice(0, 10))} ${s.subject}${then}`);
+        const then = older || s.file !== file ? style('dim', `  (${plain(s.file)}:${formatRanges(s.lines)} then)`) : '';
+        out.push(`${label}${style('yellow', s.commit.slice(0, 10))} ${plain(s.subject)}${then}`);
         if (!s.gloss) {
             out.push(style('dim', '  no gloss for this commit'));
             return;