@ok-ggwp/git-gloss 0.3.0 → 0.5.0

package/dist/commands/add.js

@@ -5,7 +5,9 @@ import { commitDiff, isWipSnapshot, NOTES_REF, readNote, resolveCommit, WIP_NOTE
 import { location, parseDiff } from '../diff.js';
 import { Annotation, noteFormat } from '../schema.js';
 import { validate } from '../validate.js';
-export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--dry-run]   attach an annotation (JSON from file or stdin)';
+import { loadConfig } from '../config.js';
+import { analyzeGroups, groupInputsFor, ratingProblems } from '../floor.js';
+export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--allow-underrate] [--dry-run]   attach an annotation (JSON from file or stdin)';
 export function run(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -14,6 +16,7 @@ export function run(argv) {
             file: { type: 'string', short: 'f' },
             force: { type: 'boolean' },
             partial: { type: 'boolean' },
+            'allow-underrate': { type: 'boolean' },
             'dry-run': { type: 'boolean' },
         },
     });
@@ -41,10 +44,23 @@ export function run(argv) {
     if (uncovered.length && !values.partial) {
         errors.push(`hunks not assigned to any group: ${uncovered.join(', ')} (every hunk needs a group, or pass --partial)`);
     }
+    // Computed signals: group impact below its floor is a warning; attention
+    // below the floor is an error unless explained (override_reason) or allowed.
+    // A malformed config stops here with its own message.
+    const warnings = [];
+    if (!errors.length) {
+        const analysis = analyzeGroups(hunks, groupInputsFor(parsed.data, hunks), loadConfig());
+        const problems = ratingProblems(parsed.data, analysis);
+        warnings.push(...problems.warnings);
+        if (problems.underrated)
+            (values['allow-underrate'] ? warnings : errors).push(problems.underrated);
+    }
     if (errors.length) {
         console.error('error: annotation is inconsistent with the commit:\n' + errors.map((e) => `  ✖ ${e}`).join('\n'));
         return 1;
     }
+    for (const w of warnings)
+        console.error(`warning: ${w}`);
     // Not an error: long intents still work, but they make the summary rows tall.
     for (const g of parsed.data.groups.filter((g) => g.intent.length > 100)) {
         console.error(`note: group "${g.id}" has a ${g.intent.length}-character intent; keep it under ~80 and move detail to "notes"`);

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

@@ -6,6 +6,10 @@ import { location, parseDiff } from '../diff.js';
 import { noteFormat } from '../schema.js';
 import { colorDiff, hunkLabel, page, style } from '../render.js';
 import { bodyLines, changedCount } from '../selection.js';
+import { loadConfig } from '../config.js';
+import { withSignals } from '../floor.js';
+import { analyze } from '../signals.js';
+import { summaryLines } from './signals.js';
 export const usage = 'hunks [<commit> | wip] [--stat] [--json]   list a commit\'s hunks (or snapshot uncommitted work with wip), numbering changed lines';
 export function run(argv) {
     const { values, positionals } = parseArgs({
@@ -59,6 +63,9 @@ export function run(argv) {
             return colorDiff(h.text, '       ');
         return [colorDiff(header, '       '), ...body.map((l) => style('dim', (l.idx === null ? '' : String(l.idx)).padStart(5)) + '  ' + colorDiff(l.raw))].join('\n');
     };
-    page(hunks.map((h) => hunkLabel(h) + style('dim', `  (${changedCount(h)} changed)`) + (values.stat ? '' : '\n' + numbered(h) + '\n')).join('\n'));
+    // What the diff itself says about attention, for the author to read before glossing.
+    const summary = withSignals(() => summaryLines(analyze(hunks, loadConfig())));
+    const signals = summary ? ['', ...summary] : [];
+    page([hunks.map((h) => hunkLabel(h) + style('dim', `  (${changedCount(h)} changed)`) + (values.stat ? '' : '\n' + numbered(h) + '\n')).join('\n'), ...signals].join('\n'));
     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,14 +2,18 @@ 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, MAX_DECISION_LINE, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.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';
+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; --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' }, note: { type: 'string' }, complete: { type: 'boolean' }, by: { type: 'string' },
+        },
     });
     if (values.record) {
         const input = JSON.parse(readFileSync(0, 'utf8'));
@@ -28,6 +32,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 +44,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 +53,42 @@ export function run(argv) {
         return 0;
     }
     const { shas } = resolveCommits(positionals[0] ?? 'HEAD');
+    if (values.decide !== undefined) {
+        const id = values.decide;
+        if (values.complete) {
+            if (values.finding !== undefined || values.outcome !== undefined || values.note !== undefined) {
+                throw new GlossError('--complete marks the review as arbitrated; it takes no --finding, --outcome or --note');
+            }
+        }
+        else
+            checkDecision(values);
+        // Every commit of the target holding that review gets the decision.
+        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 ${positionals[0] ?? 'HEAD'}` + (known.length ? ` (reviews there: ${plain(known.join(', '))})` : ' (it has no reviews)'));
+        }
+        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.
+        if (JSON.stringify(record).length > MAX_DECISION_LINE)
+            throw new GlossError('that decision is too long to record: the finding and note, as written, exceed what readers accept; shorten them');
+        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 +96,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 +105,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('', 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(...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 ds.filter((d) => d.outcome).sort((a, b) => a.at.localeCompare(b.at))) {
+                        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

@@ -2,10 +2,13 @@ import { parseArgs } from 'node:util';
 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';
+import { impactRank } from '../attention.js';
+import { showsImpact, tryAnalyze } from '../floor.js';
+import { IMPACT, NECESSITY, isImpact, isNecessity } from '../schema.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
 // split a hunk don't both count all of it.
 function stats(parts) {
@@ -26,12 +29,18 @@ export function run(argv) {
             full: { type: 'boolean' },
             diff: { type: 'boolean' },
             only: { type: 'string' },
+            sort: { type: 'string' },
         },
     });
-    const only = values.only?.split(',').map((s) => s.trim());
-    const unknown = only?.filter((n) => !NECESSITY.includes(n));
+    const names = values.only?.split(',').map((s) => s.trim());
+    const unknown = names?.filter((n) => !isNecessity(n) && !isImpact(n));
     if (unknown?.length) {
-        console.error(`error: unknown necessity ${unknown.join(', ')}; expected ${NECESSITY.join(', ')}`);
+        console.error(`error: unknown necessity or impact ${unknown.join(', ')}; expected ${NECESSITY.join(', ')} or ${IMPACT.join(', ')}`);
+        return 2;
+    }
+    const only = names && { names, necessities: names.filter(isNecessity), impacts: names.filter(isImpact) };
+    if (values.sort !== undefined && values.sort !== 'impact') {
+        console.error(`error: unknown sort ${values.sort}; expected impact`);
         return 2;
     }
     const { shas, merges, range } = resolveCommits(positionals[0] ?? 'HEAD');
@@ -63,7 +72,7 @@ export function run(argv) {
         }
         const out = renderCommit(sha, gloss, values, only, true);
         if (!out) {
-            console.error(`no groups match ${[values.group && `-g ${values.group.join(',')}`, only && `--only ${only.join(',')}`].filter(Boolean).join(' and ')}`);
+            console.error(`no groups match ${[values.group && `-g ${values.group.join(',')}`, only && `--only ${only.names.join(',')}`].filter(Boolean).join(' and ')}`);
             return 1;
         }
         page(out.join('\n'));
@@ -94,25 +103,34 @@ 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?.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)'));
     page(out.join('\n'));
     return 0;
 }
+const matchesOnly = (g, only) => !only ||
+    ((!only.necessities.length || only.necessities.includes(g.necessity)) && (!only.impacts.length || (!!g.impact && only.impacts.includes(g.impact))));
 // 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', ' · '))}` +
+    // 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
@@ -120,21 +138,31 @@ 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)));
-    out.push(reviewsLine(sha));
+    const an = tryAnalyze(gloss);
+    out.push(...attentionBlock(a.attention, an ? { floor: an.floor, derived: an.derived, timedOut: an.timedOut } : undefined), reviewsLine(sha));
     const groups = gloss.groups
-        .filter((g) => !only || only.includes(g.group.necessity))
+        .filter((g) => matchesOnly(g.group, only))
         .filter((g) => !values.group || values.group.includes(g.group.id));
     if (!groups.length)
         return null;
+    // --sort impact: the most consequential first, then by necessity as usual.
+    const byNecessity = (x, y) => NECESSITY.indexOf(x.group.necessity) - NECESSITY.indexOf(y.group.necessity);
+    const byImpact = (x, y) => impactRank(y.group.impact) - impactRank(x.group.impact) || byNecessity(x, y);
+    const detail = values.group || values.full || values.diff;
+    // The summary lists required first; detail views keep the gloss's order unless asked.
+    if (values.sort === 'impact')
+        groups.sort(byImpact);
+    else if (!detail)
+        groups.sort(byNecessity);
     // -g: chosen groups with their code. --full: every group's details, plus
     // alternatives and risks. --diff: --full plus code.
-    if (values.group || values.full || values.diff) {
+    if (detail) {
         const withCode = values.diff || !!values.group;
         for (const g of groups) {
             out.push('', ...groupHeader(g.group));
@@ -163,13 +191,12 @@ function renderCommit(sha, gloss, values, only, hints) {
         return out;
     }
     // Summary: one line per group.
-    const sorted = [...groups].sort((x, y) => NECESSITY.indexOf(x.group.necessity) - NECESSITY.indexOf(y.group.necessity));
     const tally = NECESSITY.map((n) => [n, gloss.groups.filter((g) => g.group.necessity === n).length])
         .filter(([, c]) => c > 0)
         .map(([n, c]) => `${c} ${necessityWord(n)}`);
-    const showing = groups.length < gloss.groups.length ? style('dim', `  (showing ${groups.length}: --only ${only?.join(',')})`) : '';
+    const showing = groups.length < gloss.groups.length ? style('dim', `  (showing ${groups.length}: --only ${only?.names.join(',')})`) : '';
     out.push('', `${style('bold', `${gloss.groups.length} groups:`)} ${tally.join(style('dim', ' · '))}${showing}`, '');
-    const rows = sorted.map((g) => {
+    const rows = groups.map((g) => {
         const s = stats(currentParts(g));
         const stale = g.hunks.filter((h) => h.status !== 'ok').length;
         return {
@@ -182,14 +209,21 @@ function renderCommit(sha, gloss, values, only, hints) {
     const statW = Math.max(...rows.map((r) => r.stat.length), un.count ? 8 : 0);
     const addW = Math.max(...rows.map((r) => r.added.length));
     const remW = Math.max(...rows.map((r) => r.removed.length));
-    const intentCol = 2 + 11 + 2 + idW + 2;
+    // An impact column only when some group declares one or the diff puts one
+    // above the baseline (module), so plain glosses look as before. Undeclared
+    // ones show the group's floor in parentheses.
+    const floorOf = (g) => an?.groups.get(g.group.id)?.floor;
+    const showImpact = showsImpact(gloss.groups.map((g) => g.group), an);
+    const impactW = showImpact ? IMPACT_W + 2 : 0;
+    const anyDerived = showImpact && gloss.groups.some((g) => !g.group.impact && floorOf(g));
+    const intentCol = 2 + 11 + 2 + impactW + idW + 2;
     const statsW = 2 + statW + 1 + addW + 1 + remW;
     const intentW = Math.max(20, termWidth() - intentCol - statsW);
     for (const r of rows) {
         // Intents wrap within their column rather than being cut off; the stats
         // stay on the first line so the numbers still line up.
         const [first, ...rest] = wrap(r.g.group.intent, intentW);
-        out.push(`  ${necessityWord(r.g.group.necessity, 11)}  ${style('bold', r.g.group.id.padEnd(idW))}  ` +
+        out.push(`  ${necessityWord(r.g.group.necessity, 11)}  ${impactW ? (r.g.group.impact ? impactTag(r.g.group.impact, IMPACT_W) : floorOf(r.g) ? derivedImpactTag(floorOf(r.g), IMPACT_W) : ' '.repeat(IMPACT_W)) + '  ' : ''}${style('bold', r.g.group.id.padEnd(idW))}  ` +
             `${first.padEnd(intentW)}  ` +
             style('dim', r.stat.padStart(statW)) + ' ' + style('green', r.added.padStart(addW)) + ' ' + style('red', r.removed.padStart(remW)), ...rest.map((l) => ' '.repeat(intentCol) + l));
         if (r.stale) {
@@ -200,6 +234,8 @@ function renderCommit(sha, gloss, values, only, hints) {
         const where = gloss.unannotated.map((u) => refLabel(u.hunk.id, u.lines)).join(', ');
         out.push(`  ${style(['bold', 'red'], 'unannotated'.padEnd(11))}  ${style('red', `+${un.added} -${un.removed} not in any group: ${where}`)}`);
     }
+    if (anyDerived)
+        out.push('', style('dim', '(impact in parentheses is derived from the diff, not declared)'));
     // Rejected alternatives and risks: short, and often what a reader most
     // lacks, so they're in the summary rather than only behind --full.
     out.push(...noteFooter(gloss.note));

package/dist/commands/signals.js

@@ -0,0 +1,89 @@
+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';
+import { parseDiff } from '../diff.js';
+import { analyze, CONFIG_EDIT_NOTE } from '../signals.js';
+import { impactRank } from '../attention.js';
+import { ATTENTION_STYLE, impactTag, page, style } from '../render.js';
+export const usage = 'signals [<commit> | <range> | wip] [--json]   what the diff itself says about attention: path classes, pattern hits, dependency bumps and the computed floor';
+const pct = (x) => `${Math.round(x * 100)}%`;
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+const statsLine = (s) => `${plural(s.files, 'file')}, ${plural(s.hunks, 'hunk')}, +${s.added} -${s.removed}, ${plural(s.testFiles, 'test file')}` +
+    (s.hunks ? ` (${pct(s.testHunkShare)} of hunks in tests)` : '');
+// The short form `hunks` prints at its end: the floor, the files that set it,
+// and the stats.
+export function summaryLines(sig, max = 6) {
+    const out = [style('bold', 'signals:') + ` floor attention = ${style(['bold', ATTENTION_STYLE[sig.floor.attention]], sig.floor.attention)}`];
+    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)} ${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:     ${plain(r)}`);
+    if (sig.floor.reasons.includes(CONFIG_EDIT_NOTE))
+        out.push(`  note:      ${CONFIG_EDIT_NOTE}`);
+    out.push(`  stats: ${statsLine(sig.stats)}`);
+    return out;
+}
+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: ${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)} ${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.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)`));
+    }
+    const quiet = sig.hunks.length - notable.length;
+    if (quiet)
+        out.push(style('dim', `  (${plural(quiet, 'other hunk')} at module or below, no pattern hits)`));
+    if (sig.dependencies.length)
+        out.push('', style('bold', 'dependency changes'));
+    for (const d of sig.dependencies) {
+        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 = 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)
+            out.push(style('dim', `    ... ${d.bumps.length - 20} more (--json)`));
+    }
+    return out;
+}
+// The diff to analyse: wip is the working tree as it is now (no snapshot is taken).
+function target(arg) {
+    if (arg === 'wip')
+        return { diff: workingDiff().diff, label: 'uncommitted changes' };
+    if (arg.includes('...'))
+        throw new GitError(`${arg}: use A..B for the commits on B since A`);
+    if (arg.includes('..')) {
+        const [a, b] = arg.split('..');
+        const base = git(['merge-base', '--end-of-options', a || 'HEAD', b || 'HEAD']).trim();
+        return { diff: diffBetween(base, resolveCommit(b || 'HEAD')), label: arg };
+    }
+    const sha = resolveCommit(arg);
+    return { diff: commitDiff(sha), label: sha.slice(0, 10) };
+}
+export function run(argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { json: { type: 'boolean' } } });
+    const { diff, label } = target(positionals[0] ?? 'HEAD');
+    const sig = analyze(parseDiff(diff), loadConfig());
+    if (values.json) {
+        console.log(JSON.stringify({ target: label, ...sig }, null, 2));
+        return 0;
+    }
+    page(detailLines(sig, label).join('\n'));
+    return 0;
+}

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;