@ok-ggwp/git-gloss 0.3.0 → 0.4.0

package/dist/render.js

@@ -2,7 +2,8 @@ import { spawnSync } from 'node:child_process';
 import { styleText } from 'node:util';
 import { gitTry } from './git.js';
 import { refLabel, sliceStats } from './selection.js';
-import { servesOf } from './schema.js';
+import { attentionRank } from './attention.js';
+import { IMPACT, servesOf } from './schema.js';
 export const style = (s, text) => styleText(s, text);
 const NECESSITY_STYLE = {
     required: 'green',
@@ -18,6 +19,50 @@ export function necessityTag(n) {
 export function necessityWord(n, pad = 0) {
     return style(NECESSITY_STYLE[n], n.padEnd(pad));
 }
+const IMPACT_STYLE = {
+    local: 'gray',
+    module: 'white',
+    shared: 'yellow',
+    contract: 'magenta',
+    sensitive: 'red',
+};
+// "[contract]", padded to `pad` columns.
+export function impactTag(i, pad = 0) {
+    return style(['bold', IMPACT_STYLE[i]], `[${i}]`) + ' '.repeat(Math.max(0, pad - i.length - 2));
+}
+// "(contract)": an impact derived from the diff rather than declared.
+export function derivedImpactTag(i, pad = 0) {
+    return style('dim', `(${i})`) + ' '.repeat(Math.max(0, pad - i.length - 2));
+}
+// Width of the widest impact tag, "[sensitive]".
+export const IMPACT_W = Math.max(...IMPACT.map((i) => i.length)) + 2;
+export const ATTENTION_STYLE = {
+    skim: 'gray',
+    look: 'cyan',
+    careful: 'yellow',
+    'must-read': 'red',
+};
+// Declared below the computed floor.
+export const belowFloor = (a, view) => !!a && !!view && attentionRank(a.level) < attentionRank(view.floor);
+// "attention: CAREFUL (declared) · floor: careful · focus: a, b" with the
+// reasons beneath. Without a declared level but with signals: "LOOK (derived)"
+// and why. "unrated" where nothing is declared and no signals could be computed.
+export function attentionBlock(a, view) {
+    const level = (l) => style(['bold', ATTENTION_STYLE[l]], l.toUpperCase());
+    if (!a) {
+        if (!view)
+            return [style('dim', 'attention: unrated')];
+        const d = view.derived;
+        return [`attention: ${level(d.level)} ${style('dim', '(derived)')}` + (d.level === view.floor ? '' : ` · floor: ${view.floor}`),
+            ...d.reasons.flatMap((r) => field('•', r))];
+    }
+    const head = `attention: ${level(a.level)}${view ? ' ' + style('dim', '(declared)') + ` · floor: ${view.floor}` : ''}` +
+        (a.focus?.length ? ` · focus: ${a.focus.join(', ')}` : '');
+    const below = belowFloor(a, view);
+    return [head, ...(a.reasons ?? []).flatMap((r) => field('•', r)),
+        ...(below ? field('⚠', `declared ${a.level}, below the computed floor ${view.floor}` + (a.override_reason ? '' : ' (no override_reason)'), 2).map((l) => style('yellow', l)) : []),
+        ...(a.override_reason ? field('override:', a.override_reason) : [])];
+}
 export const termWidth = () => Math.min(process.stdout.columns || 100, 120);
 // Word-wrap plain text to `width` columns.
 export function wrap(text, width) {
@@ -63,13 +108,16 @@ export function colorDiff(text, indent = '') {
         .join('\n');
 }
 export function groupHeader(g) {
-    const prefix = `■ [${g.necessity}] `;
-    const out = wrap(g.intent, termWidth() - prefix.length).map((l, i) => (i === 0 ? `${style('bold', '■')} ${necessityTag(g.necessity)} ` : ' '.repeat(prefix.length)) + style('bold', l));
+    const impact = g.impact ? ` [${g.impact}]` : '';
+    const prefix = `■ [${g.necessity}]${impact} `;
+    const out = wrap(g.intent, termWidth() - prefix.length).map((l, i) => (i === 0 ? `${style('bold', '■')} ${necessityTag(g.necessity)}${g.impact ? ' ' + impactTag(g.impact) : ''} ` : ' '.repeat(prefix.length)) + style('bold', l));
     out[out.length - 1] += ' ' + style('dim', `(${g.id})`);
     const serves = servesOf(g);
     if (serves[0] !== 'task')
         out.push(...field('serves:', serves.join(', ')));
     out.push(...field('if removed:', g.removal_impact));
+    if (g.impact_reason)
+        out.push(...field('impact:', g.impact_reason));
     if (g.evidence)
         out.push(...field('evidence:', g.evidence));
     if (g.notes)

package/dist/safe-match.js

@@ -0,0 +1,28 @@
+import vm from 'node:vm';
+// Patterns come from a repo's config, so one may backtrack without end. Each
+// batch of lines runs in a vm with a time budget; a pattern that exceeds it is
+// reported once on stderr, and from then on it counts as matching every line:
+// failing open would let a change pad a line to switch a trusted pattern off. Lines are never cut: a
+// change controls its own lines, and padding one must not hide a hit.
+const BUDGET_MS = 250;
+const script = new vm.Script('texts.map((t) => re.test(t))');
+// One context for all calls: creating one per call dominates the cost.
+const ctx = vm.createContext({ re: null, texts: [] });
+const skipped = new Set();
+export function matchLines(re, texts) {
+    const key = `${re.source}/${re.flags}`;
+    if (skipped.has(key))
+        return texts.map(() => true);
+    ctx.re = re;
+    ctx.texts = texts;
+    try {
+        return script.runInContext(ctx, { timeout: BUDGET_MS });
+    }
+    catch (err) {
+        if (err.code !== 'ERR_SCRIPT_EXECUTION_TIMEOUT')
+            throw err;
+        skipped.add(key);
+        console.error(`warning: pattern ${JSON.stringify(re.source)} took over ${BUDGET_MS}ms and is treated as matching every line from now on (catastrophic backtracking, or a padded line?)`);
+        return texts.map(() => true);
+    }
+}

package/dist/schema.js

@@ -10,6 +10,7 @@ export const NECESSITY = [
     'speculative',
     'mechanical',
 ];
+export const isNecessity = (s) => NECESSITY.includes(s);
 export const NECESSITY_HELP = {
     required: 'The task cannot be done without this change',
     supporting: 'Needed only because other groups need it (name them in `serves`)',
@@ -18,6 +19,24 @@ export const NECESSITY_HELP = {
     defensive: 'Guards edge cases or failures nobody asked about',
     speculative: 'Added because it might be useful later',
 };
+// How far a group's effect reaches if it is wrong, lowest first.
+export const IMPACT = ['local', 'module', 'shared', 'contract', 'sensitive'];
+export const isImpact = (s) => IMPACT.includes(s);
+export const IMPACT_HELP = {
+    local: 'Contained in one file or component; no outside callers (a private helper, template text, a test)',
+    module: 'One feature or project; its callers are inside it',
+    shared: 'Code used by several projects or modules, or root build, test or lint config',
+    contract: 'An interface others depend on: public APIs, routes, state shape, message formats, schemas, config keys, dependency versions, CI definitions',
+    sensitive: 'Correctness or safety critical whatever the size: auth, crypto, permissions, data writes or deletes, payments, hardware I/O, secrets',
+};
+// What a reviewer should do with the change, lowest first.
+export const ATTENTION = ['skim', 'look', 'careful', 'must-read'];
+export const ATTENTION_HELP = {
+    skim: 'Glance at the summary',
+    look: 'Read the focus groups',
+    careful: 'Read every non-mechanical group',
+    'must-read': 'Read line by line before approving',
+};
 export const Group = z.object({
     id: z
         .string()
@@ -36,12 +55,32 @@ export const Group = z.object({
         .string()
         .optional()
         .describe('A test, requirement or task line that demonstrates the need'),
+    impact: z
+        .enum(IMPACT)
+        .optional()
+        .describe('How far the effect reaches if this group is wrong: ' + IMPACT.join(' < ') + '; the highest that applies'),
+    impact_reason: z
+        .string()
+        .max(120)
+        .optional()
+        .describe('One short sentence on why the impact applies (expected for contract and sensitive)'),
     hunks: z
         .array(z.string().regex(REF_PATTERN, 'use a hunk id like "h3", or changed lines of one like "h3:2-5" or "h3:1,4-6"'))
         .min(1)
         .describe('Hunks from `git gloss hunks` that belong to this group: "h3" for a whole hunk, "h3:2-5" for its changed lines 2 to 5'),
     notes: z.string().optional(),
 });
+export const Attention = z.object({
+    level: z.enum(ATTENTION).describe('What the reviewer should do: ' + ATTENTION.map((l) => `${l} (${ATTENTION_HELP[l].toLowerCase()})`).join(', ')),
+    focus: z
+        .array(z.string())
+        .min(1)
+        .max(3)
+        .optional()
+        .describe('One to three group ids to look at first'),
+    reasons: z.array(z.string()).optional().describe('Short reasons for the level'),
+    override_reason: z.string().optional().describe('Why the level is lower than the change would suggest, if it is'),
+});
 export const Annotation = z.object({
     version: z.literal(1).default(1),
     task: z.string().min(1).describe('The task or request these changes were made for'),
@@ -52,6 +91,7 @@ export const Annotation = z.object({
         .optional()
         .describe('Approaches considered and why they were not taken'),
     risks: z.array(z.string()).optional().describe('Known risks or open questions'),
+    attention: Attention.optional().describe('How much attention a human reviewer should give this change'),
     author: z
         .object({
         agent: z.string().optional(),
@@ -63,10 +103,14 @@ export const Annotation = z.object({
 // A group's serves targets as a list, whichever form the gloss used.
 export const servesOf = (g) => (Array.isArray(g.serves) ? g.serves : [g.serves]);
 // Note formats: 1 whole-hunk references only; 2 line ranges ("h3:2-5");
-// 3 serves lists. A note is written with the lowest format that can hold it,
+// 3 serves lists; 4 impact, impact_reason or attention. A note is written with the lowest format that can hold it,
 // so older readers only refuse notes that use something they can't read.
-export const NOTE_FORMAT = 3;
+export const NOTE_FORMAT = 4;
 export function noteFormat(a) {
+    // Readers of lower formats drop fields they don't know (they would lose
+    // these on a carry), so they must refuse the note instead.
+    if (a.attention || a.groups.some((g) => g.impact || g.impact_reason))
+        return 4;
     if (a.groups.some((g) => servesOf(g).length > 1))
         return 3;
     if (a.groups.some((g) => g.hunks.some((ref) => ref.includes(':'))))

package/dist/signals.js

@@ -0,0 +1,292 @@
+import { basename } from 'node:path';
+import { bodyLines } from './selection.js';
+import { attentionForImpact, impactRank, maxAttention, maxImpact } from './attention.js';
+import { CONFIG_FILE, PATH_CLASSES, PATTERN_CLASSES } from './config.js';
+import { globToRegExp } from './glob.js';
+import { matchLines } from './safe-match.js';
+const compiled = new WeakMap();
+function pathMatchers(cfg) {
+    let m = compiled.get(cfg);
+    if (!m) {
+        m = {};
+        for (const c of PATH_CLASSES)
+            m[c] = cfg.paths[c].map(globToRegExp);
+        compiled.set(cfg, m);
+    }
+    return m;
+}
+export function pathClasses(cfg, ...files) {
+    const m = pathMatchers(cfg);
+    const out = new Set();
+    for (const f of files) {
+        if (!f)
+            continue;
+        for (const c of PATH_CLASSES)
+            if (m[c].some((re) => re.test(f)))
+                out.add(c);
+    }
+    // Dependency files are interfaces whatever the globs say.
+    if ((out.has('lockfile') || out.has('manifest')) && !out.has('sensitive'))
+        out.add('contract');
+    return PATH_CLASSES.filter((c) => out.has(c));
+}
+// The floor from the path alone, and what set it.
+//  - lockfile: at least contract, even if generated.
+//  - test, docs, generated or manifest-in-test: capped at local (the cap wins over path classes like sensitive).
+//  - otherwise the highest of sensitive > contract > shared, else module.
+function pathFloor(classes) {
+    const has = (c) => classes.includes(c);
+    const top = ['sensitive', 'contract', 'shared'].find(has);
+    if (has('lockfile'))
+        return has('sensitive') ? { floor: 'sensitive', why: ['path: sensitive', 'lockfile'] } : { floor: 'contract', why: ['lockfile'] };
+    if (has('test') || has('docs') || has('generated'))
+        return { floor: 'local', why: [] };
+    if (top)
+        return { floor: top, why: [`path: ${top}${has('manifest') ? ' (manifest)' : ''}`] };
+    return { floor: 'module', why: [] };
+}
+const clip = (s) => (s.length > 120 ? s.slice(0, 117) + '...' : s.trim());
+export function hunkSignals(h, cfg) {
+    const classes = pathClasses(cfg, h.file, h.oldFile);
+    const { floor: pFloor, why: pWhy } = pathFloor(classes);
+    const damped = classes.includes('test') || classes.includes('docs') || classes.includes('lockfile');
+    const hits = [];
+    // Only added and removed lines: never context, never the @@ header.
+    if (h.text.startsWith('@@') && (h.added || h.removed)) {
+        const lines = bodyLines(h).filter((l) => l.idx !== null && l.kind !== 'ctx' && l.kind !== 'meta');
+        const texts = lines.map((l) => l.raw.slice(1));
+        for (const c of PATTERN_CLASSES) {
+            for (const p of cfg.patterns[c]) {
+                const found = matchLines(p.re, texts);
+                lines.forEach((l, i) => {
+                    if (found[i])
+                        hits.push({ class: c, name: p.name, line: l.idx, sign: l.kind === 'add' ? '+' : '-', text: clip(texts[i]), damped });
+                });
+            }
+        }
+    }
+    const { floor, why } = floorFrom(pFloor, pWhy, hits, null);
+    const inert = classes.includes('test') || classes.includes('docs') || classes.includes('generated') || classes.includes('lockfile');
+    return { id: h.id, file: h.file, oldFile: h.oldFile, classes, hits, pathFloor: pFloor, pathWhy: pWhy, floor, why, inert, test: classes.includes('test') };
+}
+// The floor from a path floor and the pattern hits: damped hits never count,
+// and with `lines` only hits on those changed lines do. `why` names what set
+// it; the path's reasons stand only while the path itself sets the floor.
+function floorFrom(pFloor, pWhy, hits, lines) {
+    let floor = pFloor;
+    const live = hits.filter((x) => !x.damped && (!lines || lines.has(x.line)));
+    for (const x of live)
+        floor = maxImpact(floor, x.class);
+    const names = [...new Set(live.filter((x) => x.class === floor).map((x) => `pattern: ${x.name}`))];
+    return { floor, why: floor === pFloor ? [...pWhy, ...names.filter((n) => !pWhy.includes(n))] : names };
+}
+// The floor of a part of a hunk (a group's lines of it); all of it when null.
+export function partFloor(s, lines) {
+    return lines ? floorFrom(s.pathFloor, s.pathWhy, s.hits, lines) : { floor: s.floor, why: s.why };
+}
+// ---- dependency changes ----
+const NPM_KEY = /^\s*"(node_modules\/[^"]+)":\s*\{\s*$/;
+const NPM_VERSION = /^\s*"version":\s*"([^"]+)"/;
+const NPM_RESOLVED = /^\s*"resolved":\s*"[^"]*?\/((?:@[^/"]+\/)?[^/"]+)\/-\/[^"]*"/;
+function parsePackageLock(hunks) {
+    const old = new Map(), now = new Map();
+    for (const h of hunks) {
+        const lines = bodyLines(h);
+        let key = null;
+        lines.forEach((l, i) => {
+            if (l.kind === 'meta')
+                return;
+            const body = l.raw.slice(1);
+            const k = NPM_KEY.exec(body);
+            if (k) {
+                key = k[1];
+                return;
+            }
+            const v = NPM_VERSION.exec(body);
+            if (!v || l.kind === 'ctx')
+                return;
+            // The entry's key is usually the line above (context or changed); else
+            // the package's name is in the `resolved` URL a few lines below.
+            let id = key;
+            let name = id ? id.slice(id.lastIndexOf('node_modules/') + 'node_modules/'.length) : null;
+            if (!id) {
+                for (const n of lines.slice(i + 1, i + 5)) {
+                    const r = n.kind === 'meta' ? null : NPM_RESOLVED.exec(n.raw.slice(1));
+                    if (r) {
+                        name = r[1];
+                        id = `?${r[1]}`;
+                        break;
+                    }
+                }
+            }
+            if (!id || !name)
+                return;
+            (l.kind === 'del' ? old : now).set(id, { name, version: v[1] });
+        });
+    }
+    return { old, now };
+}
+const PNPM_KEY = [
+    // packages and snapshots: "/name@1.2.3:", "name@1.2.3(peer@1):", "'@scope/name@1.2.3':"
+    /^\s+['"]?\/?(@[^/@\s'"]+\/[^@\s'"]+|[^@\s'"/]+)@(\d[^\s'"(:]*)[^:]*?['"]?:\s*$/,
+    // older format: "/name/1.2.3:", "/@scope/name/1.2.3_peer:"
+    /^\s+\/(@[^/\s]+\/[^/\s]+|[^/\s@]+)\/(\d[^\s:_]*)[^:]*:\s*$/,
+];
+function parsePnpmLock(hunks) {
+    const old = new Map(), now = new Map();
+    for (const h of hunks) {
+        for (const l of bodyLines(h)) {
+            if (l.kind !== 'add' && l.kind !== 'del')
+                continue;
+            const body = l.raw.slice(1);
+            for (const re of PNPM_KEY) {
+                const m = re.exec(body);
+                if (m) {
+                    (l.kind === 'del' ? old : now).set(`${m[1]}@${m[2]}`, { name: m[1], version: m[2] });
+                    break;
+                }
+            }
+        }
+    }
+    return { old, now };
+}
+// Pair removed and added entries into bumps. By identity (npm: the entry's
+// path) when both sides have it; for pnpm, entries are name@version, so a
+// name with removed and added versions is a bump of those.
+function diffSeen(old, now, byName) {
+    const out = [];
+    if (!byName) {
+        for (const [id, n] of now) {
+            const o = old.get(id);
+            if (!o)
+                out.push({ name: n.name, from: null, to: n.version, kind: 'added' });
+            else if (o.version !== n.version)
+                out.push({ name: n.name, from: o.version, to: n.version, kind: 'bump' });
+        }
+        for (const [id, o] of old)
+            if (!now.has(id))
+                out.push({ name: o.name, from: o.version, to: null, kind: 'removed' });
+        return out;
+    }
+    const group = (m) => {
+        const g = new Map();
+        for (const e of m.values())
+            g.set(e.name, [...(g.get(e.name) ?? []), e.version]);
+        return g;
+    };
+    const o = group(old), n = group(now);
+    for (const [name, to] of n) {
+        const from = (o.get(name) ?? []).filter((v) => !to.includes(v));
+        const added = to.filter((v) => !(o.get(name) ?? []).includes(v));
+        if (!o.has(name))
+            out.push({ name, from: null, to: to.join(', '), kind: 'added' });
+        else if (added.length)
+            out.push(from.length ? { name, from: from.join(', '), to: added.join(', '), kind: 'bump' } : { name, from: null, to: added.join(', '), kind: 'added' });
+    }
+    for (const [name, from] of o)
+        if (!n.has(name))
+            out.push({ name, from: from.join(', '), to: null, kind: 'removed' });
+    return out;
+}
+const MANIFEST_DEP = /^\s*"([^"]+)"\s*:\s*"(?:[~^<>=*]|\d|npm:|workspace:|file:|link:|git|https?:|latest|catalog:)[^"]*"/;
+// Names a package.json change adds, removes or edits (by its changed lines).
+function manifestNames(hunks) {
+    const names = new Set();
+    for (const h of hunks) {
+        for (const l of bodyLines(h)) {
+            if (l.kind !== 'add' && l.kind !== 'del')
+                continue;
+            const m = MANIFEST_DEP.exec(l.raw.slice(1));
+            if (m)
+                names.add(m[1]);
+        }
+    }
+    return names;
+}
+function dependencyChanges(hs, sigs) {
+    const byFile = new Map();
+    hs.forEach((h, i) => {
+        const c = sigs[i].classes;
+        const kind = c.includes('lockfile') ? 'lockfile' : c.includes('manifest') && !sigs[i].inert ? 'manifest' : null;
+        if (!kind)
+            return;
+        const e = byFile.get(h.file) ?? { kind, hunks: [] };
+        e.hunks.push(h);
+        byFile.set(h.file, e);
+    });
+    const names = new Set();
+    for (const [file, e] of byFile)
+        if (e.kind === 'manifest' && basename(file) === 'package.json')
+            for (const n of manifestNames(e.hunks))
+                names.add(n);
+    return [...byFile].map(([file, e]) => {
+        const base = basename(file);
+        const format = e.kind === 'lockfile' && base === 'package-lock.json' ? 'package-lock.json'
+            : e.kind === 'lockfile' && base === 'pnpm-lock.yaml' ? 'pnpm-lock.yaml' : null;
+        if (!format)
+            return { file, kind: e.kind, format: null, bumps: [] };
+        const { old, now } = format === 'package-lock.json' ? parsePackageLock(e.hunks) : parsePnpmLock(e.hunks);
+        const bumps = diffSeen(old, now, format === 'pnpm-lock.yaml').map((b) => ({ ...b, unrelated: b.kind === 'bump' && !names.has(b.name) }));
+        return { file, kind: e.kind, format, bumps };
+    });
+}
+// ---- the whole change ----
+// Said wherever the floor reasons are: the change's own edit is not what rated it.
+export const CONFIG_EDIT_NOTE = `${CONFIG_FILE} is edited here; this change is rated with the base branch's config, not this edit`;
+export function analyze(hunks, cfg) {
+    const sigs = hunks.map((h) => hunkSignals(h, cfg));
+    const deps = dependencyChanges(hunks, sigs);
+    const files = new Map();
+    hunks.forEach((h, i) => {
+        const s = sigs[i];
+        const f = files.get(h.file) ?? { file: h.file, classes: [], hunks: [], added: 0, removed: 0, floor: s.floor, why: [] };
+        const first = !f.hunks.length;
+        f.classes = PATH_CLASSES.filter((c) => f.classes.includes(c) || s.classes.includes(c));
+        f.hunks.push(h.id);
+        f.added += h.added;
+        f.removed += h.removed;
+        if (first || s.floor === f.floor)
+            f.why = [...new Set([...f.why, ...s.why])];
+        else if (impactRank(s.floor) > impactRank(f.floor)) {
+            f.floor = s.floor;
+            f.why = [...s.why];
+        }
+        files.set(h.file, f);
+    });
+    const fileList = [...files.values()];
+    const testHunks = sigs.filter((s) => s.test).length;
+    const stats = {
+        files: fileList.length,
+        hunks: hunks.length,
+        added: hunks.reduce((n, h) => n + h.added, 0),
+        removed: hunks.reduce((n, h) => n + h.removed, 0),
+        testFiles: fileList.filter((f) => f.classes.includes('test')).length,
+        testHunks,
+        testHunkShare: hunks.length ? Math.round((testHunks / hunks.length) * 100) / 100 : 0,
+    };
+    // Dependency bumps that no manifest change explains are worth naming where
+    // the lockfile is reported.
+    for (const d of deps) {
+        const f = files.get(d.file);
+        if (!f)
+            continue;
+        for (const b of d.bumps.filter((x) => x.unrelated).slice(0, 3))
+            f.why.push(`transitive bump: ${b.name} ${b.from} -> ${b.to}`);
+    }
+    // The floor: the highest hunk floor decides the attention floor (local skim,
+    // module look, shared and contract careful, sensitive must-read). A change
+    // of more than largeChangeFiles files is at least careful. The "raise one
+    // step" rules of the derivation are not part of the floor: they depend on
+    // the gloss, and the floor must be the same whoever writes it.
+    const impact = sigs.reduce((m, s) => maxImpact(m, s.floor), 'local');
+    let attention = attentionForImpact(impact);
+    const reasons = fileList.filter((f) => f.floor === impact && impact !== 'module' && impact !== 'local')
+        .slice(0, 5).map((f) => `${impact}: ${f.file}${f.why.length ? ` (${f.why.join('; ')})` : ''}`);
+    if (stats.files > cfg.attention.largeChangeFiles) {
+        attention = maxAttention(attention, 'careful');
+        reasons.push(`${stats.files} files changed (more than ${cfg.attention.largeChangeFiles})`);
+    }
+    if (files.has(CONFIG_FILE))
+        reasons.push(CONFIG_EDIT_NOTE);
+    return { stats, hunks: sigs, files: fileList, dependencies: deps, floor: { impact, attention, reasons } };
+}

package/dist/validate.js

@@ -49,6 +49,12 @@ export function validate(annotation, hunks) {
             errors.push(`group "${g.id}" is "supporting" but serves "task"; name the group(s) it supports`);
         }
     }
+    const focus = annotation.attention?.focus ?? [];
+    for (const id of focus)
+        if (!groupIds.has(id))
+            errors.push(`attention.focus names unknown group "${id}"`);
+    if (new Set(focus).size < focus.length)
+        errors.push('attention.focus lists a group twice');
     // A group is in a cycle if it can reach itself by following serves links.
     const byId = new Map(annotation.groups.map((g) => [g.id, g]));
     for (const g of annotation.groups) {

package/package.json

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

package/skills/gloss/SKILL.md

@@ -31,7 +31,7 @@ The commands below are written as `git gloss …`. That works only where git-glo
 
 ## 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.
+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, and a `signals:` summary of what in it deserves attention (see "Impact and attention"). If you change files afterwards, run it again: that takes a new snapshot, and a gloss must match the snapshot it was written for.
 2. Group changes **by intent**, not by file. One intent often spans several files. When one hunk mixes intents (common in new files, which are a single hunk), give each group only its lines: `"h6:1-40"`, `"h6:41-55,60"`. The numbers count changed lines only, as `hunks` prints them. Every changed line must belong to at least one group; `add` lists any that don't.
    Take hunk ids and line numbers from the `git gloss hunks` output for this snapshot or commit, never from memory of the diff or from an earlier commit. Ids depend on the order git lists hunks, and line numbers count only changed lines, so guesses are easily wrong. `add` rejects ranges past the end of a hunk, but a wrong range that stays in bounds is accepted and silently attaches an intent to the wrong code.
 3. Write the annotation JSON (shape below; `git gloss schema` prints the full JSON Schema) to a file in your scratchpad, then run:
@@ -99,6 +99,32 @@ Where you can, set `evidence` to a test that exercises the change or the line of
 
 `alternatives` and `risks` are optional, but fill them in when you weighed real options. They are what later readers most often lack.
 
+## Impact and attention
+
+Necessity says whether a change is needed; `impact` says how far it reaches if it is wrong. Read the `signals:` summary at the end of `git gloss hunks wip` (or run `git gloss signals wip` for hunks, pattern hits and dependency bumps) **before** writing the gloss: it is the floor the gloss is checked against.
+
+- `impact` on each non-mechanical group, the highest level that applies: `local` (one file or component, no outside callers), `module` (one feature or project), `shared` (used by several projects, or root build, test or lint config), `contract` (an interface others depend on: public APIs, props and events, routes, state shape, message formats, schemas, config keys, dependency versions, CI definitions), `sensitive` (auth, crypto, permissions, data writes or deletes, payments, hardware I/O, secrets, whatever the size). Give `impact_reason` (one short sentence, up to 120 characters) at `contract` and above. `add` warns when a group is rated below its floor.
+- `attention` for the reviewer: `level` is `skim` (glance at the summary), `look` (read the focus groups), `careful` (read every non-mechanical group) or `must-read` (line by line); `focus` is one to three group ids to read first; `reasons` tie the level to signals.
+- Never declare `attention.level` below the floor without `override_reason`: `add` refuses it. Don't reach for `--allow-underrate`; raise the level, or say why the floor is wrong. A large "behaviour-neutral" refactor deserves `careful`, not `skim`, however many hunks are mechanical.
+- Name the groups that test others in `serves` (`"serves": ["gauge-fix"]`, not `"task"`): a behaviour change that no test group serves raises the derived attention, and say so in `reasons` when it is untested.
+- Both fields are optional. Without them `show` derives a value from the diff and marks it `(derived)`.
+
+Example: a change adds a dev dependency, fixes a device write, and tweaks a label with no test. `signals` says `sensitive: src/devices/gauge.ts (pattern: device write)` and `contract: package-lock.json (transitive bump: some-pkg 7.1.0 -> 7.1.2)`, so the floor is must-read.
+
+```json
+"groups": [
+  {"id": "gauge-fix", "intent": "Send the brightness value, not the signal", "necessity": "required", "serves": "task",
+   "impact": "sensitive", "impact_reason": "writes a value to the device", "removal_impact": "The gauge shows a constant", "hunks": ["h2"]},
+  {"id": "gauge-test", "intent": "Cover the written value", "necessity": "supporting", "serves": ["gauge-fix"], "removal_impact": "The fix is untested", "hunks": ["h3"]},
+  {"id": "label-fix", "intent": "Fix the Save label", "necessity": "required", "serves": "task",
+   "impact": "module", "removal_impact": "The button says Sav", "hunks": ["h4"]},
+  {"id": "report-dep", "intent": "Add the report tool; lockfile also bumps some-pkg 7.1.0 to 7.1.2", "necessity": "mechanical", "serves": "task",
+   "impact": "contract", "impact_reason": "dependency versions; the some-pkg bump is not ours", "removal_impact": "No test reports", "hunks": ["h1"]}
+],
+"attention": {"level": "must-read", "focus": ["gauge-fix", "report-dep"],
+  "reasons": ["gauge-fix writes to the device", "lockfile bumps some-pkg beyond the new dependency", "label-fix has no test"]}
+```
+
 ## Looking up intent
 
 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.