@rigour-labs/core 6.7.10 → 6.8.1-rc.1

package/dist/review/reviewer/verdict.js

@@ -12,6 +12,34 @@ import { createHash } from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { textSimilarity } from './consensus.js';
+/** How alike a judge's prior point and a labelled line of the review must read to take the reviewer's label. */
+const LABEL_SIMILARITY = 0.4;
+/**
+ * The point with the severity its reviewer wrote, when the review labels it; the judge's reading otherwise. The reviewer
+ * is matched by login; the review by the date the judge names (judges write a timestamp, a date, or reformat it), and
+ * when no review of that reviewer has that date, by that reviewer's latest labelled review. A disagreement is said.
+ */
+function labelled(p, labels) {
+    const [login, ...rest] = (p.review ?? '').trim().split(/\s+/);
+    const day = /\d{4}-\d{2}-\d{2}/.exec(rest.join(' '))?.[0];
+    const theirs = login ? labels.filter(l => l.login === login) : [];
+    const sameDay = day ? theirs.filter(l => l.at.startsWith(day)) : [];
+    const latest = theirs.reduce((max, l) => (l.at > max ? l.at : max), '');
+    const candidates = sameDay.length ? sameDay : theirs.filter(l => l.at === latest);
+    const asItem = (issue) => ({ id: '', kind: 'prior', class: 'prior point', issue });
+    let best;
+    for (const label of candidates) {
+        const score = textSimilarity(asItem(p.point), asItem(label.text));
+        if (score >= LABEL_SIMILARITY && (!best || score > best.score))
+            best = { label, score };
+    }
+    if (!best)
+        return { point: p, took: false, disagreed: false };
+    if (best.label.severity === p.severity)
+        return { point: p, took: true, disagreed: false };
+    const note = `the review labels it ${best.label.severity}${p.severity ? `; the judge read ${p.severity}` : ''}`;
+    return { point: { ...p, severity: best.label.severity, evidence: p.evidence ? `${p.evidence}; ${note}` : note }, took: true, disagreed: true };
+}
 const NO_PRIOR_CHECKS = { approvals: [], inCheckout: () => undefined };
 /** The touched lines of a unified diff (`git diff base...head`). */
 export function changedLinesOf(diff) {
@@ -214,7 +242,10 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
     const notes = [];
     const advisory = [];
     const seen = new Set();
-    const accepted = verdict.prior_points.filter(p => p.severity === 'non-blocking');
+    // The reviewer's own label wins over the judge's reading of it: a judge that calls a blocker a should-fix would demote it silently.
+    const read = verdict.prior_points.map(p => labelled(p, prior.labels ?? []));
+    const points = read.map(r => r.point);
+    const accepted = points.filter(p => p.severity === 'non-blocking');
     // A should-fix is shown only when the judge could show it: a quote Rigour finds. One that cannot be checked is not a claim worth a person's time.
     const advise = (item) => {
         if (seen.has(item.id))
@@ -243,7 +274,7 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
         open.push(item);
     };
     const answerInReply = [];
-    for (const p of verdict.prior_points) {
+    for (const p of points) {
         if (p.resolved)
             continue;
         if (p.severity === 'non-blocking') {
@@ -270,7 +301,11 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
             continue;
         }
         // Still open only where the judge quotes the code that keeps it open: a point a later commit already fixed never blocks.
-        add(item);
+        // A should-fix keeps the tier its reviewer gave it: shown with its quote, never a block, like a should-fix finding.
+        if (p.severity === 'should-fix')
+            advise(item);
+        else
+            add(item);
     }
     for (const r of verdict.redundant) {
         if (r.removed === false)
@@ -374,7 +409,7 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
             }
         }
     }
-    return { open: onePerRootCause(open), unverified, resolved, answerInReply, notes, advisory: onePerRootCause(advisory) };
+    return { open: onePerRootCause(open), unverified, resolved, answerInReply, notes, advisory: onePerRootCause(advisory), labels: { served: prior.labels?.length ?? 0, taken: read.filter(r => r.took).length, disagreed: read.filter(r => r.disagreed).length } };
 }
 /** How alike two items' words must be to be the same point made in two places; and, on the same lines, to be one point said two ways. */
 const SAME_POINT = 0.6;
@@ -387,9 +422,14 @@ const SAME_LINES = 3;
 function onePerRootCause(items) {
     const kept = [];
     for (const item of items) {
-        // The same class in the same words anywhere, or any two non-human items on the same lines that read alike (a rule break and the finding it caused).
+        // The same class in the same words anywhere, or any two non-human items on the same lines that read alike (a rule break and
+        // the finding it caused). A human's point owns its lines: a rule break or finding there in like words is that point found
+        // again and folds into it; the human's words stay. One in other words is a different problem and stays its own item, so
+        // fixing the human's point does not leave it for the next round. Two human points never merge.
         const nearby = (k) => !!k.file && k.file === item.file && k.line !== undefined && item.line !== undefined && Math.abs(k.line - item.line) <= SAME_LINES;
-        const same = item.kind === 'prior' ? undefined : kept.find(k => k.kind !== 'prior' && ((k.class === item.class && textSimilarity(k, item) >= SAME_POINT) || (nearby(k) && textSimilarity(k, item) >= SAME_PLACE)));
+        const same = item.kind === 'prior' ? undefined : kept.find(k => k.kind === 'prior'
+            ? nearby(k) && textSimilarity(k, item) >= SAME_PLACE
+            : (k.class === item.class && textSimilarity(k, item) >= SAME_POINT) || (nearby(k) && textSimilarity(k, item) >= SAME_PLACE));
         if (!same) {
             kept.push(item);
             continue;

package/dist/review/reviewer.d.ts

@@ -84,6 +84,8 @@ export interface ReviewerResult {
     /** The latest human review it worked from (`<login>, <date> (<n> reviews)`). */
     previousReview?: string;
     pr?: number;
+    /** The pull request's title, when one was read. */
+    prTitle?: string;
 }
 export interface ModeRecord {
     asked: 'single' | 'cross' | 'full' | 'panel';

package/dist/review/reviewer.js

@@ -36,6 +36,7 @@ import { buildContext, dismissedAs, readReviewDismissals, relatedDocs } from './
 import { buildRecord } from './reviewer/record.js';
 import { account, attachServedRules, changedLinesOf, checkoutSearch, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 import { judgeUnset } from './reviewer/judge-env.js';
+import { appendTaskEvent } from '../task/thread.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays } from './reviewer/exec.js';
 export { itemLine } from './reviewer/verdict.js';
 /** Findings and no verdict stop a push; a skipped review does not, and is reported as owed. */
@@ -48,7 +49,16 @@ const MAX_DELTA_LINES = 400;
 /** The reviewer, and one anonymous usage event for what it did (only when the person opted in to telemetry). */
 export async function runReviewer(cwd, base, config, exec = defaultExec, progress = message => process.stderr.write(`${message}\n`), options = {}) {
     const result = await review(cwd, base, config, exec, progress, options);
-    await trackUsage('reviewer_completed', reviewerUsage(result, options.trigger ?? (options.reviewsBefore ? 'backtest' : 'review')));
+    const trigger = options.trigger ?? (options.reviewsBefore ? 'backtest' : 'review');
+    await trackUsage('reviewer_completed', reviewerUsage(result, trigger));
+    // On the task's thread, unless it replays history: a backtest's worktree is not anyone's task.
+    if (trigger !== 'backtest' && result.outcome !== 'skipped')
+        appendTaskEvent(cwd, {
+            kind: 'review', trigger, outcome: result.outcome, blocking: result.items.length, should_fix: result.advisory.length,
+            ...(result.pr ? { pr: result.pr } : {}),
+            ...(result.prTitle ? { pr_title: result.prTitle } : {}),
+            ...(result.record ? { integrity: result.record.integrity, cost_usd: result.record.judges.reduce((sum, j) => sum + (j.cost_usd ?? 0), 0), judges: result.record.judges.map(j => j.reviewer) } : {}),
+        });
     return result;
 }
 async function review(cwd, base, config, exec, progress, options) {
@@ -107,7 +117,7 @@ async function review(cwd, base, config, exec, progress, options) {
         if (skip)
             return none('skipped', skip, { reviewers, pr: pr?.number });
     }
-    let reviews = { markdown: 'none\n', key: '', count: 0, approvals: [] };
+    let reviews = { markdown: 'none\n', key: '', count: 0, approvals: [], labels: [] };
     if (gh && pr) {
         const read = await humanReviews(gh, pr, options.reviewsBefore);
         if (read.error)
@@ -187,12 +197,17 @@ async function review(cwd, base, config, exec, progress, options) {
     const openFile = store.openPath(verdictFile);
     const previousOpen = scope === 'delta' ? store.readJson(store.openPath(previous.verdict)) ?? [] : undefined;
     const verify = checkoutVerifier(cwd);
-    const prior = { approvals: reviews.approvals, inCheckout: checkoutSearch(cwd), changed: changedLinesOf(fullDiff) };
+    const prior = { approvals: reviews.approvals, inCheckout: checkoutSearch(cwd), changed: changedLinesOf(fullDiff), labels: reviews.labels };
     const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
     // The record of the review, written beside the verdict once and rebuilt from the same verdict on a cached read.
+    // What a judge reads besides the repository and Rigour's inputs, on this machine: on the record, so "the same judge" is a claim it can check.
+    const outsideOf = (reviewer) => {
+        const outside = ADAPTERS[reviewer]?.outsideRepo?.(os.homedir(), installed.get(reviewer)?.version);
+        return outside ? { outside_repo: outside } : {};
+    };
     const withRecord = (accounted, verdict, cached) => {
         const res = result(accounted, verdict, reviewers, scope, why, cached, reviews, pr, modeRecord, settings.dismissals);
-        const judges = (verdict.reviewers ?? []).map(r => ({ reviewer: r.reviewer, ...(installed.get(r.reviewer)?.version ? { version: installed.get(r.reviewer).version } : {}), ...(modelFor(r.reviewer) ? { model: modelFor(r.reviewer) } : {}), ...(typeof r.cost_usd === 'number' ? { cost_usd: r.cost_usd } : {}), ...(r.trace?.turns ? { turns: r.trace.turns } : {}) }));
+        const judges = (verdict.reviewers ?? []).map(r => ({ reviewer: r.reviewer, ...(installed.get(r.reviewer)?.version ? { version: installed.get(r.reviewer).version } : {}), ...(modelFor(r.reviewer) ? { model: modelFor(r.reviewer) } : {}), ...(typeof r.cost_usd === 'number' ? { cost_usd: r.cost_usd } : {}), ...(r.trace?.turns ? { turns: r.trace.turns } : {}), ...outsideOf(r.reviewer) }));
         const recordPath = store.recordPath(verdictFile);
         const record = (cached && store.readJson(recordPath)) || buildRecord({ head, base: baseSha, scope, verdict, accounted, judges, lessonsServed: context.lessons, humanReviews: reviews.count });
         if (!cached || !fs.existsSync(recordPath))
@@ -212,7 +227,7 @@ async function review(cwd, base, config, exec, progress, options) {
     let inlineInputs = [];
     const runJudge = (name, prompt, model) => name === 'api'
         ? runApiJudge(prompt, { url: settings.api.url, model: settings.api.model, key: process.env[settings.api.key_env] ?? '', maxTurns: settings.api.max_turns, timeoutMs: settings.timeout_ms, cwd, roots: [cwd, work], inputs: inlineInputs, ...(settings.reasoning[name] ? { reasoning: settings.reasoning[name] } : {}), ...(options.fetch ? { fetchImpl: options.fetch } : {}) })
-        : exec(installed.get(name).binary, ADAPTERS[name].args(prompt, model, { reasoning: settings.reasoning[name] }), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
+        : exec(installed.get(name).binary, ADAPTERS[name].args(prompt, model, { reasoning: settings.reasoning[name] }), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env), ...(ADAPTERS[name].env ? { env: ADAPTERS[name].env } : {}) });
     try {
         const file = (name, text) => {
             const target = path.join(work, name);
@@ -336,6 +351,9 @@ async function review(cwd, base, config, exec, progress, options) {
             verdict = { ...verdict, panel: { judgeItemIds: judgeItems.flat().map(item => item.id), items }, reviewers: [...(verdict.reviewers ?? []), ...cross] };
         }
         const accounted = decide(verdict, previousOpen, verify, prior, dismissals);
+        // Said every run where the reviews carry labels, so a matcher that takes none is visible rather than silent.
+        if (accounted.labels?.served)
+            progress(`Rigour reviewer: ${accounted.labels.taken} of ${verdict.prior_points.length} prior point(s) took the review's own severity label (${accounted.labels.served} labelled line(s)); the judge read ${accounted.labels.disagreed} otherwise`);
         store.writeJson(verdictFile, { ...verdict, inputs: { head, base: baseSha, scope, why, mode: modeRecord, reviewers, versions: reviewerVersions, authors: [...authors], fingerprint, human_reviews: reviews.count, reviews_before: options.reviewsBefore ?? null, since: previous?.head ?? null, at: new Date().toISOString() } });
         store.writeJson(openFile, accounted.open);
         store.writeJson(store.decidedPath(verdictFile), accounted);
@@ -462,5 +480,6 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         cached,
         ...(reviews.label ? { previousReview: reviews.label } : {}),
         ...(pr ? { pr: pr.number } : {}),
+        ...(pr?.title ? { prTitle: pr.title } : {}),
     };
 }

package/dist/review-learning/repo-rules.d.ts

@@ -5,14 +5,26 @@ export interface RepoRule {
     text: string;
     /** Paths the rule names (files or directories). */
     paths: string[];
+    /** Where the rule applies: the folder of the nested rules file it came from (`services/billing/`); the whole repository when absent. */
+    scope?: string;
     /** Identifiers the rule names. */
     symbols: string[];
     /** Worded as a requirement: a break can block. Guidance otherwise: a break is shown. */
     requirement: boolean;
 }
+/**
+ * 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 declare function readRepoRules(cwd: string): RepoRule[];
 /** One rule per top-level bullet or paragraph; headings and import lines are not rules. */
 export declare function splitRules(source: string, text: string): RepoRule[];
 export declare function rulesSection(rules: RepoRule[]): string;
-/** The rules that apply to a diff's changed files and added identifiers, the top `limit`. */
-export declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean, limit?: number): RepoRule[];
+/**
+ * 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 declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean, limit?: number, namedOnly?: boolean): RepoRule[];

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/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/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,