@rigour-labs/core 6.7.10 → 6.8.0

package/dist/review-learning/repo-rules.js

@@ -8,6 +8,7 @@
  * is better served by the few rules that name a file or identifier the
  * change actually touches.
  */
+import { spawnSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
@@ -20,12 +21,55 @@ const MAX_RULES = 5;
 const CONTINUES = /^\**\s*(why|how to apply|example|examples|evidence|exception|exceptions|fix|note)\b\s*:?\**\s*:?/i;
 /** Worded as a requirement: the team said must, never, always, only, every, do not. A rule without these is guidance. */
 const REQUIREMENT = /\b(must|never|always|only|every|do not|don't|forbidden|required|non-negotiable)\b/i;
+/** The most rule files read, imports included: a loop or a sprawling import tree stops here. */
+const MAX_RULE_SOURCES = 50;
+/** Folders of someone else's code a repository carries: a rules file in one is that project's, not this team's. */
+const VENDORED = /(^|\/)(vendor|vendors|third_party|third-party|node_modules|bower_components|external|externals)\//;
+/**
+ * Every rule file of the repository: the root ones, the AGENTS.md and CLAUDE.md files in folders below it (outside
+ * vendored folders), the rule directories, and every file a rule file imports with an `@path` line (relative to the
+ * importing file, inside the repository). A judge does not load these by itself; this is how the repository's rules
+ * reach it. A nested file's rules apply to its own folder only, and so do the rules of the files it imports.
+ */
 export function readRepoRules(cwd) {
-    const files = [
-        ...RULE_FILES.filter(f => fs.existsSync(path.join(cwd, f))),
-        ...RULE_DIRS.flatMap(dir => listRuleFiles(cwd, dir)),
+    const queue = [
+        ...RULE_FILES.filter(f => fs.existsSync(path.join(cwd, f))).map(file => ({ file })),
+        ...nestedRuleFiles(cwd).map(file => ({ file, scope: `${path.posix.dirname(file)}/` })),
+        ...RULE_DIRS.flatMap(dir => listRuleFiles(cwd, dir)).map(file => ({ file })),
     ];
-    return files.flatMap(file => splitRules(file, fs.readFileSync(path.join(cwd, file), 'utf8')));
+    const read = new Set();
+    const rules = [];
+    while (queue.length && read.size < MAX_RULE_SOURCES) {
+        const { file, scope } = queue.shift();
+        // The same file imported from two places is read once, with the scope it was first reached with: a root import first.
+        if (read.has(file))
+            continue;
+        read.add(file);
+        let text;
+        try {
+            text = fs.readFileSync(path.join(cwd, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        rules.push(...splitRules(file, text).map(rule => (scope ? { ...rule, scope } : rule)));
+        for (const m of text.matchAll(/^@(\S+)\s*$/gm)) {
+            const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), m[1].replace(/^\.\//, '')));
+            if (target.startsWith('..') || path.isAbsolute(m[1]) || m[1].startsWith('~') || !fs.existsSync(path.join(cwd, target)))
+                continue;
+            // Root imports go to the front, so a file both a root and a nested file import keeps the repository-wide scope.
+            if (scope)
+                queue.push({ file: target, scope });
+            else
+                queue.unshift({ file: target });
+        }
+    }
+    return rules;
+}
+/** AGENTS.md and CLAUDE.md in folders below the root, as git tracks them, outside vendored folders. */
+function nestedRuleFiles(cwd) {
+    const listed = spawnSync('git', ['ls-files', '-z', '--', '*/AGENTS.md', '*/CLAUDE.md'], { cwd, encoding: 'utf8', timeout: 5000 });
+    return listed.status === 0 ? listed.stdout.split('\0').filter(f => f && !VENDORED.test(f)) : [];
 }
 /** One rule per top-level bullet or paragraph; headings and import lines are not rules. */
 export function splitRules(source, text) {
@@ -74,7 +118,9 @@ export function splitRules(source, text) {
  * not filtering: on a large change most rules share some words, so the judge decides applicability
  * rule by rule from the top `limit`.
  */
-function rulesForChange(rules, files, symbols, limit = MAX_RULES) {
+function rulesForChange(rules, files, symbols, limit = MAX_RULES, namedOnly = false) {
+    // A folder's own rules are served only when the change touches that folder: never checked, so never broken, elsewhere.
+    rules = rules.filter(rule => !rule.scope || files.some(f => f.startsWith(rule.scope)));
     const changeWords = new Set([...files.flatMap(f => f.split(/[/._-]+/)), ...symbols].flatMap(meaningfulWords));
     const scored = rules.map(rule => {
         const pathHits = rule.paths.filter(p => files.some(f => f === p || f.startsWith(p.endsWith('/') ? p : `${p}/`) || f.endsWith(`/${p}`))).length;
@@ -82,7 +128,7 @@ function rulesForChange(rules, files, symbols, limit = MAX_RULES) {
         const shared = new Set(meaningfulWords(rule.text).filter(w => changeWords.has(w))).size;
         return { rule, named: 3 * pathHits + 2 * symbolHits, shared };
     });
-    return scored.filter(s => s.named > 0 || s.shared >= 2).sort((a, b) => b.named - a.named || b.shared - a.shared).slice(0, limit).map(s => s.rule);
+    return scored.filter(s => s.named > 0 || (!namedOnly && s.shared >= 2)).sort((a, b) => b.named - a.named || b.shared - a.shared).slice(0, limit).map(s => s.rule);
 }
 export function rulesSection(rules) {
     if (rules.length === 0)
@@ -97,11 +143,15 @@ function listRuleFiles(cwd, dir) {
         return [];
     }
 }
-/** The rules that apply to a diff's changed files and added identifiers, the top `limit`. */
-export function rulesForDiff(cwd, diff, enabled = false, limit = MAX_RULES) {
+/**
+ * The rules that apply to a diff's changed files and added identifiers, the top `limit`. `namedOnly`: only rules that
+ * name a path or identifier the change touches (a briefing has no code to judge applicability against, so a rule that
+ * merely shares words with a large change is noise there).
+ */
+export function rulesForDiff(cwd, diff, enabled = false, limit = MAX_RULES, namedOnly = false) {
     if (!enabled)
         return [];
     const files = [...diff.matchAll(/^\+\+\+ b\/(.+)$/gm)].map(m => m[1].trim());
     const added = diff.split('\n').filter(line => line.startsWith('+') && !line.startsWith('+++')).join('\n');
-    return rulesForChange(readRepoRules(cwd), files, new Set(added.match(/[A-Za-z_$][\w$]*/g) ?? []), limit);
+    return rulesForChange(readRepoRules(cwd), files, new Set(added.match(/[A-Za-z_$][\w$]*/g) ?? []), limit, namedOnly);
 }

package/dist/review-learning/repo-rules.test.js

@@ -2,7 +2,8 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { rulesForDiff, rulesSection, splitRules } from './repo-rules.js';
+import { execFileSync } from 'child_process';
+import { readRepoRules, rulesForDiff, rulesSection, splitRules } from './repo-rules.js';
 const AGENTS = `# Conventions
 
 @SHARED.md
@@ -53,3 +54,40 @@ describe('repository rules', () => {
         expect(rulesSection(rulesForDiff(repo, diff('src/a.ts', 'await fetchWithTimeout(url);'), true))).toContain('[AGENTS.md] Prefer `fetchWithTimeout`');
     });
 });
+describe('the rule files a judge is given', () => {
+    it('follows @ imports from a rule file and reads AGENTS.md and CLAUDE.md in folders below the root, once each', () => {
+        fs.writeFileSync(path.join(repo, 'CLAUDE.md'), '@AGENTS.md\n@docs/conventions.md\n@../outside.md\n@/etc/hosts\n@docs/missing.md\n');
+        fs.mkdirSync(path.join(repo, 'docs'));
+        fs.writeFileSync(path.join(repo, 'docs/conventions.md'), '@../AGENTS.md\n\n- Never log `apiToken` from `src/auth/session.ts`, even partly.\n');
+        fs.writeFileSync(path.join(repo, 'SHARED.md'), '- Every job in `src/jobs/` takes `withLock()` before the first read.\n');
+        fs.mkdirSync(path.join(repo, 'services/billing'), { recursive: true });
+        fs.writeFileSync(path.join(repo, 'services/billing/AGENTS.md'), '- Amounts in `services/billing/` are integer cents via `toCents()`; never a float.\n');
+        execFileSync('git', ['-C', repo, 'init', '-q']);
+        execFileSync('git', ['-C', repo, 'add', '-A']);
+        const rules = readRepoRules(repo);
+        const by = (source) => rules.filter(r => r.source === source).map(r => r.text);
+        expect(by('docs/conventions.md')).toEqual(['Never log `apiToken` from `src/auth/session.ts`, even partly.']);
+        expect(by('SHARED.md')).toEqual(['Every job in `src/jobs/` takes `withLock()` before the first read.']); // imported by AGENTS.md
+        expect(by('services/billing/AGENTS.md')).toEqual(['Amounts in `services/billing/` are integer cents via `toCents()`; never a float.']);
+        expect(rules.filter(r => r.source === 'AGENTS.md')).toHaveLength(3); // imported twice, read once
+        expect(rules.some(r => /hosts|outside/.test(r.source))).toBe(false); // nothing outside the repository
+    });
+    it("applies a folder's own rules, and the rules it imports, only to changes in that folder; vendored folders add none", () => {
+        fs.mkdirSync(path.join(repo, 'services/billing'), { recursive: true });
+        fs.writeFileSync(path.join(repo, 'services/billing/AGENTS.md'), '@money.md\n\n- Never call `stripe.charges.create` directly from `services/billing/`; go through `ledgerClient`.\n');
+        fs.writeFileSync(path.join(repo, 'services/billing/money.md'), '- Every amount in `services/billing/` is integer cents via `toCents()`; never a float.\n');
+        fs.mkdirSync(path.join(repo, 'vendor/somelib'), { recursive: true });
+        fs.writeFileSync(path.join(repo, 'vendor/somelib/AGENTS.md'), '- Always run `make vendor-test` in `vendor/somelib/` before every commit.\n');
+        execFileSync('git', ['-C', repo, 'init', '-q']);
+        execFileSync('git', ['-C', repo, 'add', '-A']);
+        const all = readRepoRules(repo);
+        expect(all.filter(r => r.scope === 'services/billing/').map(r => r.source)).toEqual(['services/billing/AGENTS.md', 'services/billing/money.md']);
+        expect(all.some(r => r.source.startsWith('vendor/'))).toBe(false);
+        expect(all.filter(r => r.source === 'AGENTS.md').every(r => r.scope === undefined)).toBe(true);
+        // A change only in web/ that even names the billing words: the billing rules are not served, so never checked or broken.
+        const web = rulesForDiff(repo, diff('web/src/Price.tsx', 'const total = stripe.charges.create(toCents(amount));'), true, 15);
+        expect(web.some(r => r.scope)).toBe(false);
+        const billing = rulesForDiff(repo, diff('services/billing/charge.ts', 'const total = stripe.charges.create(toCents(amount));'), true, 15);
+        expect(billing.filter(r => r.scope).map(r => r.source).sort()).toEqual(['services/billing/AGENTS.md', 'services/billing/money.md']);
+    });
+});

package/dist/task/thread.d.ts

@@ -0,0 +1,47 @@
+/** Under the repository's git folder (the common one, shared by every worktree). */
+export declare const THREADS_DIR = "rigour/threads";
+export type TaskEventKind = 'edit-check' | 'stop-review' | 'push' | 'review' | 'brief';
+export interface TaskEvent {
+    kind: TaskEventKind;
+    /** The agent session it happened in, when a hook knows it. */
+    session?: string;
+    /** The agent (claude, cursor, codex, ...) or `person`, when known. */
+    agent?: string;
+    /** The pull request, once a review of it ran. */
+    pr?: number;
+    /** What happened, in a few fields; each kind documents its own. */
+    [field: string]: unknown;
+}
+export interface ThreadEvent extends TaskEvent {
+    at: string;
+    task: string;
+    branch: string;
+    head?: string;
+}
+/**
+ * The task the checkout is working on: the ticket its branch names when one of the branch's own commit subjects names
+ * it too, else the branch; undefined on a detached head.
+ */
+export declare function taskOf(cwd: string): {
+    key: string;
+    branch: string;
+    head?: string;
+} | undefined;
+/** Appends one event to the checkout's task thread. Best effort: a thread never breaks the hook or command it runs in. */
+export declare function appendTaskEvent(cwd: string, event: TaskEvent): ThreadEvent | undefined;
+/**
+ * The thread for a key, oldest first: a ticket (`PROJ-123`, every branch whose events carry it, from their first
+ * event), a branch name, a pull request (`#42` or `42`: the branches a review of it ran on), or nothing for the
+ * checkout's own task. Matching is on the keys stored in the events, never on file names. Unreadable lines are skipped.
+ */
+export declare function readThread(cwd: string, key?: string): {
+    task: string;
+    events: ThreadEvent[];
+} | undefined;
+/** The thread as a person reads it: who worked on it, what was caught and fixed, what blocked, then the events in order. */
+export declare function threadText(thread: {
+    task: string;
+    events: ThreadEvent[];
+}): string[];
+/** Where the repository's threads are: its common git folder, so every worktree of it writes to the same threads. */
+export declare function threadsDir(cwd: string): string | undefined;

package/dist/task/thread.js

@@ -0,0 +1,234 @@
+/**
+ * The engineering task: one piece of work, whatever agents and people touch it, and its thread, everything that
+ * happened to it in order. Events are kept per branch, one file each (`<git dir>/rigour/threads/<branch>-<hash>.jsonl`,
+ * the hash of the exact branch name, so no two branches share a file). The task is the ticket the branch names when
+ * the branch's own commit subjects, or the title of its pull request as a review recorded it, write it as a ticket
+ * (`PROJ-123`): a version token in a branch name (`pin-node-22`, `utf-8`) is not a ticket. Otherwise the task is the
+ * branch. The task is worked out once per commit and kept: the edit hook runs on every edit. Reading a ticket gathers every branch that worked on it;
+ * a pull request joins when a review of it runs. Writers only append, and never fail the hook or command they run in.
+ * The files live in the repository's common git folder, shared by its worktrees; nothing enters the working tree.
+ *
+ * What a thread holds is what Rigour saw: hooked agent sessions (the edit check, the stop review), the push gate, and
+ * reviews. Work done where no hook ran (an agent without hooks, a person in an editor) shows only through the commits
+ * and reviews that follow it.
+ */
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+/** Under the repository's git folder (the common one, shared by every worktree). */
+export const THREADS_DIR = 'rigour/threads';
+/** A ticket key in a branch name: `feat/proj-123-thing` → `PROJ-123`. */
+const TICKET = /(?:^|[^A-Za-z0-9])([A-Za-z][A-Za-z0-9]{1,9}-\d{1,7})(?=$|[^0-9])/;
+/**
+ * The task the checkout is working on: the ticket its branch names when one of the branch's own commit subjects names
+ * it too, else the branch; undefined on a detached head.
+ */
+export function taskOf(cwd) {
+    const task = taskIn(cwd);
+    return task ? { key: task.key, branch: task.branch, ...(task.head ? { head: task.head } : {}) } : undefined;
+}
+/** The task and the folder its thread is in, with one lookup of each: the edit hook pays for this on every edit. */
+function taskIn(cwd) {
+    const branch = git(cwd, ['symbolic-ref', '--short', '-q', 'HEAD']); // a branch with no commit yet has a task too
+    if (!branch)
+        return undefined;
+    const head = git(cwd, ['rev-parse', '-q', '--verify', 'HEAD']);
+    const dir = threadsDir(cwd);
+    const cache = dir ? path.join(dir, '..', 'task-cache.json') : undefined;
+    const cached = cache ? readJson(cache)[branch] : undefined;
+    if (cached && cached.head === (head ?? '') && typeof cached.key === 'string')
+        return { key: cached.key, branch, ...(head ? { head } : {}), ...(dir ? { dir } : {}) };
+    const ticket = TICKET.exec(branch)?.[1]?.toUpperCase();
+    // Written as a ticket (upper case, as trackers print it): `node-22` in a subject is a version, not a ticket.
+    const written = ticket ? new RegExp(`(^|[^A-Za-z0-9])${ticket.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![0-9])`) : undefined;
+    const titles = dir ? readEvents(path.join(dir, branchFile(branch))).map(e => e.pr_title).filter((t) => typeof t === 'string') : [];
+    const confirmed = !!written && [...titles, ...branchSubjects(cwd)].some(text => written.test(text));
+    const key = confirmed ? ticket : `branch:${branch}`;
+    if (cache)
+        writeCache(cache, branch, { head: head ?? '', key });
+    return { key, branch, ...(head ? { head } : {}), ...(dir ? { dir } : {}) };
+}
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The task worked out for a branch at a commit; `undefined` forgets it (a new pull request title may confirm a ticket). */
+function writeCache(file, branch, entry) {
+    try {
+        const all = readJson(file);
+        if (entry)
+            all[branch] = entry;
+        else
+            delete all[branch];
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(all));
+    }
+    catch {
+        // a cache that cannot be written is worked out again next time
+    }
+}
+/** The subjects of the branch's own commits: since it left the main branch, or its last 50 when no main branch is found. */
+function branchSubjects(cwd) {
+    const main = ['origin/main', 'main', 'origin/master', 'master'].find(ref => git(cwd, ['rev-parse', '--verify', '-q', ref]) !== undefined);
+    const base = main ? git(cwd, ['merge-base', 'HEAD', main]) : undefined;
+    const range = base && base !== git(cwd, ['rev-parse', 'HEAD']) ? [`${base}..HEAD`] : ['-50', 'HEAD'];
+    return (git(cwd, ['log', '--format=%s', ...range]) ?? '').split('\n').filter(Boolean);
+}
+/** Appends one event to the checkout's task thread. Best effort: a thread never breaks the hook or command it runs in. */
+export function appendTaskEvent(cwd, event) {
+    try {
+        const task = taskIn(cwd);
+        if (!task?.dir)
+            return undefined;
+        const dir = task.dir;
+        const line = { at: new Date().toISOString(), task: task.key, branch: task.branch, ...(task.head ? { head: task.head } : {}), ...event };
+        fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(path.join(dir, branchFile(task.branch)), JSON.stringify(line) + '\n');
+        // A pull request title can confirm the branch's ticket: work the task out again next time.
+        if (typeof event.pr_title === 'string' && task.key.startsWith('branch:'))
+            writeCache(path.join(dir, '..', 'task-cache.json'), task.branch, undefined);
+        return line;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The thread for a key, oldest first: a ticket (`PROJ-123`, every branch whose events carry it, from their first
+ * event), a branch name, a pull request (`#42` or `42`: the branches a review of it ran on), or nothing for the
+ * checkout's own task. Matching is on the keys stored in the events, never on file names. Unreadable lines are skipped.
+ */
+export function readThread(cwd, key) {
+    const dir = threadsDir(cwd);
+    if (!dir)
+        return undefined;
+    const wanted = key?.trim();
+    if (!wanted) {
+        const own = taskOf(cwd);
+        if (!own)
+            return undefined;
+        return own.key.startsWith('branch:') ? { task: own.key, events: readEvents(path.join(dir, branchFile(own.branch))).filter(e => e.branch === own.branch) } : byTask(dir, own.key) ?? { task: own.key, events: [] };
+    }
+    const pr = /^#?(\d+)$/.exec(wanted)?.[1];
+    if (pr) {
+        const found = gather(dir, `#${pr}`, events => events.some(e => e.pr === Number(pr)));
+        return found ? { task: found.events[found.events.length - 1].task, events: found.events } : undefined;
+    }
+    const branch = wanted.replace(/^branch:/, '');
+    const own = readEvents(path.join(dir, branchFile(branch))).filter(e => e.branch === branch);
+    if (own.length)
+        return { task: own[own.length - 1].task, events: own };
+    return byTask(dir, wanted.toUpperCase());
+}
+/** Every branch whose events name the task, whole, as one thread. */
+function byTask(dir, task) {
+    return gather(dir, task, events => events.some(e => e.task === task));
+}
+function gather(dir, task, wanted) {
+    const events = listThreads(dir).map(file => readEvents(path.join(dir, file))).filter(wanted).flat().sort(byTime);
+    return events.length ? { task, events } : undefined;
+}
+/** The thread as a person reads it: who worked on it, what was caught and fixed, what blocked, then the events in order. */
+export function threadText(thread) {
+    const { task, events } = thread;
+    if (events.length === 0)
+        return [`${task}: nothing recorded yet`];
+    const sessions = new Set(events.map(e => e.session).filter(Boolean));
+    const agents = [...new Set(events.map(e => e.agent).filter((a) => typeof a === 'string'))];
+    const prs = [...new Set(events.map(e => e.pr).filter((p) => typeof p === 'number'))];
+    const branches = [...new Set(events.map(e => e.branch))];
+    const checks = events.filter(e => e.kind === 'edit-check');
+    const caught = checks.reduce((n, e) => n + num(e.findings), 0);
+    const lines = [
+        `${task} · ${branches.join(', ')}${prs.length ? ` · PR ${prs.map(p => `#${p}`).join(', ')}` : ''}`,
+        `${events[0].at} → ${events[events.length - 1].at} · ${sessions.size} agent session(s)${agents.length ? ` (${agents.join(', ')})` : ''}`,
+        `edit checks: ${checks.length}, findings caught while writing: ${caught}${caught ? `, files clean again after a finding: ${cleanedAfter(checks)}` : ''}`,
+    ];
+    const stops = events.filter(e => e.kind === 'stop-review');
+    if (stops.length)
+        lines.push(`stop reviews: ${stops.length}, blocked: ${stops.filter(e => e.blocked).length}`);
+    const pushes = events.filter(e => e.kind === 'push');
+    if (pushes.length)
+        lines.push(`pushes: ${pushes.length}, blocked: ${pushes.filter(e => e.passed === false).length}`);
+    const reviews = events.filter(e => e.kind === 'review');
+    if (reviews.length)
+        lines.push(`reviews: ${reviews.length}, last: ${String(reviews[reviews.length - 1].outcome)} with ${num(reviews[reviews.length - 1].blocking)} blocking${typeof reviews[reviews.length - 1].integrity === 'string' ? ` (record ${String(reviews[reviews.length - 1].integrity).slice(0, 16)})` : ''}`);
+    lines.push('');
+    for (const e of events)
+        lines.push(`  ${e.at.slice(0, 19).replace('T', ' ')}  ${e.kind.padEnd(11)} ${describe(e)}`);
+    return lines;
+}
+/** Files that had a finding at one edit check and none at a later one: caught while writing, fixed before push. */
+function cleanedAfter(checks) {
+    const flagged = new Set();
+    const cleaned = new Set();
+    for (const e of checks) {
+        const files = Array.isArray(e.files) ? e.files.filter((f) => typeof f === 'string') : [];
+        if (num(e.findings) > 0)
+            files.forEach(f => flagged.add(f));
+        else
+            files.filter(f => flagged.has(f)).forEach(f => cleaned.add(f));
+    }
+    return cleaned.size;
+}
+function describe(e) {
+    const who = [e.agent, e.session ? `session ${String(e.session).slice(0, 8)}` : undefined].filter(Boolean).join(', ');
+    const files = Array.isArray(e.files) ? `${e.files.length} file(s)` : '';
+    const what = e.kind === 'edit-check' ? `${files}, ${num(e.findings)} finding(s)`
+        : e.kind === 'stop-review' ? (e.blocked ? `blocked: ${num(e.blocking)} to fix` : 'passed')
+            : e.kind === 'push' ? (e.passed === false ? `blocked: ${num(e.failed)} check(s) failed` : 'passed')
+                : e.kind === 'review' ? `${String(e.outcome)}, ${num(e.blocking)} blocking, ${num(e.should_fix)} should-fix${e.pr ? ` on #${e.pr}` : ''}`
+                    : e.kind === 'brief' ? `${num(e.items)} item(s) briefed` : '';
+    return [what, who ? `(${who})` : '', e.head ? `@${String(e.head).slice(0, 9)}` : ''].filter(Boolean).join(' ');
+}
+function readEvents(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return text.split('\n').filter(Boolean).flatMap(line => {
+        try {
+            const e = JSON.parse(line);
+            return e && typeof e.at === 'string' && typeof e.task === 'string' && typeof e.kind === 'string' ? [e] : [];
+        }
+        catch {
+            return [];
+        }
+    }).sort(byTime);
+}
+/** Where the repository's threads are: its common git folder, so every worktree of it writes to the same threads. */
+export function threadsDir(cwd) {
+    const common = git(cwd, ['rev-parse', '--git-common-dir']);
+    return common ? path.join(path.resolve(cwd, common), THREADS_DIR) : undefined;
+}
+function listThreads(dir) {
+    try {
+        return fs.readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+    }
+    catch {
+        return [];
+    }
+}
+/** A branch's thread file: a readable form of its name, and a hash of the exact name, so `a/b` and `a_b` never share one. */
+function branchFile(branch) {
+    return `${branch.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80)}-${createHash('sha1').update(branch).digest('hex').slice(0, 8)}.jsonl`;
+}
+function byTime(a, b) {
+    return a.at < b.at ? -1 : a.at > b.at ? 1 : 0;
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 5000 });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}

package/dist/task/thread.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/task/thread.test.js

@@ -0,0 +1,133 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { appendTaskEvent, readThread, taskOf, threadsDir, threadText } from './thread.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'thread-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    fs.writeFileSync(path.join(repo, 'a.ts'), 'export const a = 1;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+});
+afterEach(() => fs.rmSync(repo, { recursive: true, force: true }));
+describe('the engineering task', () => {
+    const commit = (subject) => {
+        fs.appendFileSync(path.join(repo, 'a.ts'), `// ${subject}\n`);
+        git('commit', '-qam', subject);
+    };
+    it('is the ticket the branch names only when its own commits name it too; a version token is never a ticket', () => {
+        for (const branch of ['chore/pin-node-22', 'fix/utf-8-decoding', 'feat/http-2-push', 'release-1.4', 'bump/python-3-12']) {
+            git('checkout', '-q', 'main');
+            git('checkout', '-qb', branch);
+            commit(`${branch.split('/').pop()}: bump it`); // the version token in the subject, as people write it
+            expect(taskOf(repo)?.key).toBe(`branch:${branch}`);
+        }
+        git('checkout', '-q', 'main');
+        git('checkout', '-qb', 'feat/proj-123-resume-emails');
+        expect(taskOf(repo)?.key).toBe('branch:feat/proj-123-resume-emails'); // named by the branch, not yet by a commit
+        commit('proj-123 resume emails');
+        expect(taskOf(repo)?.key).toBe('branch:feat/proj-123-resume-emails'); // lower case is how versions are written, not tickets
+        commit('PROJ-123: resume emails');
+        expect(taskOf(repo)).toMatchObject({ key: 'PROJ-123', branch: 'feat/proj-123-resume-emails' });
+        git('checkout', '-qb', 'fix-the-thing');
+        expect(taskOf(repo)?.key).toBe('branch:fix-the-thing'); // a branch with no ticket in its name
+        git('checkout', '-q', '--detach');
+        expect(taskOf(repo)).toBeUndefined();
+        expect(appendTaskEvent(repo, { kind: 'push', passed: true })).toBeUndefined();
+    });
+    it("takes the ticket from the pull request's title once a review recorded it, when the commits use another scope", () => {
+        git('checkout', '-qb', 'feat/PROJ-7-retry');
+        commit('fix(retry): back off on 429');
+        appendTaskEvent(repo, { kind: 'edit-check', files: ['src/retry.ts'], findings: 0 });
+        expect(taskOf(repo)?.key).toBe('branch:feat/PROJ-7-retry');
+        appendTaskEvent(repo, { kind: 'review', pr: 7, pr_title: 'feat(PROJ-7): retry with backoff', outcome: 'passed', blocking: 0 });
+        expect(taskOf(repo)?.key).toBe('PROJ-7'); // the same commit: the title confirmed it, and the kept task was dropped
+        appendTaskEvent(repo, { kind: 'push', passed: true });
+        expect(readThread(repo, 'PROJ-7')?.events.map(e => [e.kind, e.task])).toEqual([['edit-check', 'branch:feat/PROJ-7-retry'], ['review', 'branch:feat/PROJ-7-retry'], ['push', 'PROJ-7']]);
+    });
+    it('works the task out once per commit and keeps it, so the edit hook does not read the branch history on every edit', () => {
+        git('checkout', '-qb', 'feat/PROJ-9-cache');
+        commit('PROJ-9: start');
+        expect(taskOf(repo)?.key).toBe('PROJ-9');
+        const cache = path.join(repo, '.git', 'rigour', 'task-cache.json');
+        expect(JSON.parse(fs.readFileSync(cache, 'utf8'))['feat/PROJ-9-cache']).toEqual({ head: git('rev-parse', 'HEAD'), key: 'PROJ-9' });
+        fs.writeFileSync(cache, JSON.stringify({ 'feat/PROJ-9-cache': { head: git('rev-parse', 'HEAD'), key: 'KEPT-1' } }));
+        expect(taskOf(repo)?.key).toBe('KEPT-1'); // read from what was kept, not worked out again
+        commit('PROJ-9: more');
+        expect(taskOf(repo)?.key).toBe('PROJ-9'); // a new commit: worked out again
+    });
+    it('keeps one file per exact branch: a/b and a_b never share a thread', () => {
+        git('checkout', '-qb', 'feat/a/b');
+        appendTaskEvent(repo, { kind: 'push', passed: true });
+        git('checkout', '-q', 'main');
+        git('checkout', '-qb', 'feat/a_b');
+        appendTaskEvent(repo, { kind: 'push', passed: false, failed: 2 });
+        expect(readThread(repo, 'feat/a/b')?.events.map(e => [e.branch, e.passed])).toEqual([['feat/a/b', true]]);
+        expect(readThread(repo, 'feat/a_b')?.events.map(e => [e.branch, e.passed])).toEqual([['feat/a_b', false]]);
+        expect(fs.readdirSync(threadsDir(repo))).toHaveLength(2);
+    });
+    it('gathers a ticket across the branches and worktrees that worked on it, from their first event', () => {
+        git('checkout', '-qb', 'feat/PROJ-5-api');
+        appendTaskEvent(repo, { kind: 'edit-check', files: ['src/api.ts'], findings: 1 }); // before the first commit names the ticket
+        commit('PROJ-5: the api');
+        appendTaskEvent(repo, { kind: 'push', passed: true });
+        const other = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'thread-wt-')), 'wt');
+        git('worktree', 'add', '-q', '-b', 'feat/PROJ-5-ui', other, 'main');
+        fs.appendFileSync(path.join(other, 'a.ts'), '// ui\n');
+        execFileSync('git', ['-C', other, 'commit', '-qam', 'PROJ-5 the ui'], { encoding: 'utf8' });
+        appendTaskEvent(other, { kind: 'push', passed: true }); // written from the other worktree, into the same folder
+        const thread = readThread(repo, 'proj-5');
+        expect(thread?.task).toBe('PROJ-5');
+        expect(thread?.events.map(e => [e.kind, e.branch])).toEqual([['edit-check', 'feat/PROJ-5-api'], ['push', 'feat/PROJ-5-api'], ['push', 'feat/PROJ-5-ui']]);
+        expect(readThread(repo, 'feat/PROJ-5-ui')?.events).toHaveLength(1);
+        git('worktree', 'remove', '--force', other);
+    });
+    it('keeps an append-only thread, read by ticket, branch, pull request or the checkout, oldest first, skipping a broken line', () => {
+        git('checkout', '-qb', 'feat/PROJ-7-retry');
+        commit('PROJ-7 retry');
+        appendTaskEvent(repo, { kind: 'edit-check', session: 'sess-aaaa1111', agent: 'claude', files: ['src/job.ts'], findings: 2 });
+        appendTaskEvent(repo, { kind: 'edit-check', session: 'sess-aaaa1111', agent: 'claude', files: ['src/job.ts'], findings: 0 });
+        appendTaskEvent(repo, { kind: 'stop-review', session: 'sess-aaaa1111', agent: 'claude', blocked: true, blocking: 1 });
+        appendTaskEvent(repo, { kind: 'push', passed: false, failed: 1 });
+        appendTaskEvent(repo, { kind: 'push', passed: true, failed: 0 });
+        appendTaskEvent(repo, { kind: 'review', pr: 42, outcome: 'passed', blocking: 0, should_fix: 1, integrity: 'abcdef0123456789abcdef' });
+        const [name] = fs.readdirSync(threadsDir(repo));
+        const file = path.join(threadsDir(repo), name);
+        expect(name).toMatch(/^feat_PROJ-7-retry-[0-9a-f]{8}\.jsonl$/);
+        expect(fs.realpathSync(file)).toBe(fs.realpathSync(path.join(repo, '.git', 'rigour', 'threads', name)));
+        expect(git('status', '--porcelain')).toBe(''); // nothing in the working tree
+        fs.appendFileSync(file, 'not json\n{"kind":"push"}\n');
+        const byTicket = readThread(repo, 'proj-7');
+        expect(byTicket?.task).toBe('PROJ-7');
+        expect(byTicket?.events.map(e => e.kind)).toEqual(['edit-check', 'edit-check', 'stop-review', 'push', 'push', 'review']);
+        expect(readThread(repo, 'feat/PROJ-7-retry')?.events).toHaveLength(6);
+        expect(readThread(repo, '#42')?.task).toBe('PROJ-7');
+        expect(readThread(repo, '42')?.task).toBe('PROJ-7');
+        expect(readThread(repo)?.events).toHaveLength(6);
+        expect(readThread(repo, '#43')).toBeUndefined();
+        expect(readThread(repo, 'OTHER-1')).toBeUndefined();
+        expect(byTicket.events[0]).toMatchObject({ task: 'PROJ-7', branch: 'feat/PROJ-7-retry', head: git('rev-parse', 'HEAD') });
+        const text = threadText(byTicket).join('\n');
+        expect(text).toContain('PROJ-7 · feat/PROJ-7-retry · PR #42');
+        expect(text).toContain('1 agent session(s) (claude)');
+        expect(text).toContain('findings caught while writing: 2, files clean again after a finding: 1');
+        expect(text).toContain('stop reviews: 1, blocked: 1');
+        expect(text).toContain('pushes: 2, blocked: 1');
+        expect(text).toContain('reviews: 1, last: passed with 0 blocking (record abcdef0123456789)');
+        expect(text).toContain('blocked: 1 check(s) failed');
+    });
+    it('never fails the hook it runs in: an unwritable thread folder is skipped', () => {
+        git('checkout', '-qb', 'feat/PROJ-8');
+        fs.writeFileSync(path.join(repo, '.git', 'rigour'), 'a file where the folder should be');
+        expect(appendTaskEvent(repo, { kind: 'push', passed: true })).toBeUndefined();
+        expect(readThread(repo)?.events ?? []).toEqual([]);
+        expect(threadText({ task: 'PROJ-8', events: [] })).toEqual(['PROJ-8: nothing recorded yet']);
+    });
+});

package/dist/templates/universal-config.js

@@ -275,6 +275,10 @@ export const UNIVERSAL_CONFIG = {
     output: {
         report_path: 'rigour-report.json',
     },
+    brief: {
+        enabled: true,
+        max_items: 10,
+    },
     review: {
         include_heuristics: false,
         show_preexisting: false,

package/dist/types/index.d.ts

@@ -2399,6 +2399,19 @@ export declare const ConfigSchema: z.ZodObject<{
     }, {
         report_path?: string | undefined;
     }>>>;
+    /** The briefing an agent gets before it writes (rigour brief, the prompt hook, rigour_brief). */
+    brief: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        /** The kill switch: false stops every briefing, including an installed hook. The hook itself is installed only with `rigour hooks init --brief`. */
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        /** At most this many items, never more than 10. */
+        max_items: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        max_items: number;
+    }, {
+        enabled?: boolean | undefined;
+        max_items?: number | undefined;
+    }>>>;
     /** rigour review / rigour_review / the PR bot / the stop hook. */
     review: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         /** Let heuristic gates decide the verdict too; by default only findings that prove a defect do (quiet.ts). */
@@ -2873,6 +2886,10 @@ export declare const ConfigSchema: z.ZodObject<{
     output: {
         report_path: string;
     };
+    brief: {
+        enabled: boolean;
+        max_items: number;
+    };
     review: {
         include_heuristics: boolean;
         show_preexisting: boolean;
@@ -3165,6 +3182,10 @@ export declare const ConfigSchema: z.ZodObject<{
     output?: {
         report_path?: string | undefined;
     } | undefined;
+    brief?: {
+        enabled?: boolean | undefined;
+        max_items?: number | undefined;
+    } | undefined;
     review?: {
         include_heuristics?: boolean | undefined;
         show_preexisting?: boolean | undefined;

package/dist/types/index.js

@@ -365,6 +365,13 @@ export const ConfigSchema = z.object({
     output: z.object({
         report_path: z.string().default('rigour-report.json'),
     }).optional().default({}),
+    /** The briefing an agent gets before it writes (rigour brief, the prompt hook, rigour_brief). */
+    brief: z.object({
+        /** The kill switch: false stops every briefing, including an installed hook. The hook itself is installed only with `rigour hooks init --brief`. */
+        enabled: z.boolean().optional().default(true),
+        /** At most this many items, never more than 10. */
+        max_items: z.number().int().min(1).max(10).optional().default(10),
+    }).optional().default({}),
     /** rigour review / rigour_review / the PR bot / the stop hook. */
     review: z.object({
         /** Let heuristic gates decide the verdict too; by default only findings that prove a defect do (quiet.ts). */