@rigour-labs/cli 6.7.10 → 6.8.0

package/dist/cli.js

@@ -14,6 +14,8 @@ import { demoCommand } from './commands/demo.js';
 import { hooksInitCommand, hooksCheckCommand } from './commands/hooks.js';
 import { hooksStopCommand } from './commands/hooks-stop.js';
 import { backtestCommand, backtestInitCommand } from './commands/backtest.js';
+import { threadCommand } from './commands/thread.js';
+import { briefCommand, hooksBriefCommand, hooksBriefFileCommand } from './commands/brief.js';
 import { hooksPushCommand } from './commands/hooks-push.js';
 import { hooksReviewBackgroundCommand } from './commands/hooks-review-background.js';
 import { gitPushGateCommand, selfTestCommand, selfTestGitPushHook } from './commands/hooks-git.js';
@@ -460,6 +462,7 @@ hooksCmd
     .option('--dry-run', 'Show what files would be created without writing them')
     .option('-f, --force', 'Overwrite existing hook files')
     .option('--block', 'Configure hooks to block on failure (exit code 2)')
+    .option('--brief', 'Also brief Claude Code with the team\'s rules and lessons: from each session\'s first prompt, and on the first edit of each file (off unless asked)')
     .addHelpText('after', `
 Examples:
   $ rigour hooks init                    # Auto-detect tools, generate hooks
@@ -471,6 +474,30 @@ Examples:
     .action(async (options) => {
     await hooksInitCommand(process.cwd(), options);
 });
+hooksCmd
+    .command('brief')
+    .description('Prompt hook: brief the agent once per session from its first prompt (installed by rigour hooks init --brief); reads the hook payload on stdin')
+    .action(async () => {
+    const chunks = [];
+    if (!process.stdin.isTTY)
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+    const reply = await hooksBriefCommand(Buffer.concat(chunks).toString('utf8'), process.cwd());
+    if (reply)
+        process.stdout.write(reply + '\n');
+});
+hooksCmd
+    .command('brief-file')
+    .description('Edit hook: the team\'s word on a file the first time a session edits it (installed by rigour hooks init --brief); reads the hook payload on stdin')
+    .action(async () => {
+    const chunks = [];
+    if (!process.stdin.isTTY)
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+    const reply = await hooksBriefFileCommand(Buffer.concat(chunks).toString('utf8'), process.cwd());
+    if (reply)
+        process.stdout.write(reply + '\n');
+});
 hooksCmd
     .command('stop')
     .description('Stop hook: review the branch against main (on main, what the session changed) before the agent finishes; reads the hook payload on stdin')
@@ -485,6 +512,21 @@ hooksCmd
     if (reply)
         process.stdout.write(reply + '\n');
 });
+program
+    .command('brief [goal]')
+    .description('The briefing for the task in this checkout: the repository\'s rules, the team\'s verified lessons and settled points for the files it will likely touch, at most 10, each cited. Goal: the argument, else the pull request\'s title and description, else the branch')
+    .option('--files <list>', 'The files the task will touch, comma separated (default: the branch\'s changes and files the goal names)')
+    .option('--json', 'Output the briefing in JSON format')
+    .action(async (goal, options) => {
+    process.exit(await briefCommand(process.cwd(), goal, options));
+});
+program
+    .command('thread [key]')
+    .description('The thread of an engineering task: what agents, checks, pushes and reviews did to it, in order. Key: a ticket (PROJ-123), a branch, or a pull request (#42); the checkout\'s own task by default')
+    .option('--json', 'Output the thread in JSON format')
+    .action((key, options) => {
+    process.exit(threadCommand(process.cwd(), key, options));
+});
 const backtestCmd = program
     .command('backtest')
     .description('Score the review against the points people made reviewing this repository (.rigour/backtest.json); exit 1 until every point is caught with no false block')
@@ -592,6 +634,7 @@ hooksCmd
     .option('--mode <mode>', 'Check mode: "check" (default) or "dlp" (credential scanning)')
     .option('--agent <name>', 'Agent name for DLP audit trail (e.g., cursor, claude)')
     .option('--dlp-allow-last', 'Record the last DLP warning as learned false positives (hook feedback)')
+    .option('--brief', 'DLP mode before an edit: also give the team\'s word on the file, the first time the session edits it')
     .addHelpText('after', `
 Examples:
   $ rigour hooks check --files src/app.ts

package/dist/commands/brief.d.ts

@@ -0,0 +1,29 @@
+/** `rigour brief [goal]`: the briefing for the task in this checkout, as text or JSON. The goal, else the pull request's title and description, else the branch. */
+export declare function briefCommand(cwd: string, goal: string | undefined, options: {
+    files?: string;
+    json?: boolean;
+}): Promise<number>;
+/**
+ * Claude Code's UserPromptSubmit hook: the session's first prompt is the goal; the briefing is added to the agent's
+ * context once per session, and never again in it. Prints nothing when switched off or when there is nothing to say.
+ */
+export declare function hooksBriefCommand(stdin: string, fallbackCwd: string): Promise<string>;
+/**
+ * Claude Code's PreToolUse hook on Edit, Write and MultiEdit: the first time a session edits a file, the team's word on
+ * that file (at most three items) is added to the agent's context. Once per file per session; the check for that comes
+ * first, so every later edit of the file costs one small file read. Prints nothing when off or when there is nothing.
+ */
+export declare function hooksBriefFileCommand(stdin: string, fallbackCwd: string): Promise<string>;
+export interface FileHookPayload {
+    cwd?: string;
+    session_id?: string;
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+    };
+}
+/**
+ * The team's word on the file a PreToolUse payload is about to edit, the first time the session edits it; '' otherwise.
+ * Shared by the edit hook and the DLP pre-tool hook, so a machine with DLP on pays no second process per edit.
+ */
+export declare function fileBriefingContext(payload: FileHookPayload, fallbackCwd: string): Promise<string>;

package/dist/commands/brief.js

@@ -0,0 +1,169 @@
+/**
+ * The briefing an agent gets before it writes: `rigour brief` for a person or any agent, and `rigour hooks brief` for
+ * Claude Code's prompt hook, which briefs once per session from the session's first prompt. Off unless installed with
+ * `rigour hooks init --brief`; `brief.enabled: false` in rigour.yml or RIGOUR_BRIEF=0 stops it wherever it is installed.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { briefFile, briefingText, briefTask, fileBriefingText, threadsDir } from '@rigour-labs/core';
+import { loadHookConfig } from './hooks-stop.js';
+/** Whether briefings are switched off here: the team's rigour.yml or the person's environment. */
+async function briefingOff(cwd) {
+    if (/^(0|false|off|no)$/i.test(process.env.RIGOUR_BRIEF?.trim() ?? ''))
+        return { off: true, max: 0 };
+    try {
+        const config = await loadHookConfig(cwd);
+        // The same lessons the team's reviewer checks a change against (gates.deep.review_lessons), before the code exists.
+        return { off: config.brief?.enabled === false, max: config.brief?.max_items ?? 10, ...(config.gates.deep?.review_lessons ? { lessons: config.gates.deep.review_lessons } : {}) };
+    }
+    catch {
+        return { off: false, max: 10 }; // a broken rigour.yml is reported by the checks, not by a briefing
+    }
+}
+/** `rigour brief [goal]`: the briefing for the task in this checkout, as text or JSON. The goal, else the pull request's title and description, else the branch. */
+export async function briefCommand(cwd, goal, options) {
+    const { off, max, lessons } = await briefingOff(cwd);
+    if (off) {
+        if (options.json)
+            console.log(JSON.stringify({ off: true, items: [] }));
+        else
+            console.error(chalk.yellow('Briefings are switched off here (brief.enabled: false in rigour.yml, or RIGOUR_BRIEF=0).'));
+        return 0;
+    }
+    const files = options.files?.split(',').map(f => f.trim()).filter(Boolean);
+    const briefing = briefTask(cwd, { goal: goal?.trim() || pullRequestGoal(cwd), ...(files?.length ? { files } : {}), limit: max, agent: 'cli', ...(lessons ? { lessons } : {}) });
+    if (options.json)
+        console.log(JSON.stringify(briefing, null, 2));
+    else
+        console.log(briefingText(briefing) || chalk.dim(`Nothing to brief: no rule or verified lesson of this repository applies to ${briefing.files.length ? briefing.files.join(', ') : 'this task'} yet.`));
+    return 0;
+}
+/**
+ * Claude Code's UserPromptSubmit hook: the session's first prompt is the goal; the briefing is added to the agent's
+ * context once per session, and never again in it. Prints nothing when switched off or when there is nothing to say.
+ */
+export async function hooksBriefCommand(stdin, fallbackCwd) {
+    let payload = {};
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return '';
+    }
+    const cwd = payload.cwd || fallbackCwd;
+    const session = payload.session_id;
+    const { off, max, lessons } = await briefingOff(cwd);
+    if (off || !session || briefedAlready(cwd, session))
+        return '';
+    const briefing = briefTask(cwd, { goal: payload.prompt, limit: max, session, agent: 'claude', ...(lessons ? { lessons } : {}) });
+    markBriefed(cwd, session);
+    const text = briefingText(briefing);
+    return text ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }) : '';
+}
+/**
+ * Claude Code's PreToolUse hook on Edit, Write and MultiEdit: the first time a session edits a file, the team's word on
+ * that file (at most three items) is added to the agent's context. Once per file per session; the check for that comes
+ * first, so every later edit of the file costs one small file read. Prints nothing when off or when there is nothing.
+ */
+export async function hooksBriefFileCommand(stdin, fallbackCwd) {
+    let payload = {};
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return '';
+    }
+    const text = await fileBriefingContext(payload, fallbackCwd);
+    return text ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text } }) : '';
+}
+/**
+ * The team's word on the file a PreToolUse payload is about to edit, the first time the session edits it; '' otherwise.
+ * Shared by the edit hook and the DLP pre-tool hook, so a machine with DLP on pays no second process per edit.
+ */
+export async function fileBriefingContext(payload, fallbackCwd) {
+    const session = payload.session_id;
+    const target = payload.tool_input?.file_path;
+    if (!session || typeof target !== 'string' || !target)
+        return '';
+    const cwd = payload.cwd || fallbackCwd;
+    const root = gitOut(cwd, ['rev-parse', '--show-toplevel']);
+    if (!root)
+        return '';
+    // Once per file per session, checked first and keyed on the path as the agent sent it (one session spells a file one
+    // way): every later edit of the file costs this check only.
+    const key = `${session}\u0000${path.resolve(cwd, target)}`;
+    if (briefedAlready(root, key))
+        return '';
+    markBriefed(root, key); // first, so two quick edits of one file never brief twice
+    // Where the file sits, as git says it, never by comparing paths (symlinked folders, Windows drive letters and short
+    // names make two spellings of one folder). A file being created is placed through the nearest folder that exists.
+    let dir = path.dirname(path.resolve(cwd, target));
+    const rest = [path.basename(target)];
+    while (!fs.existsSync(dir) && path.dirname(dir) !== dir) {
+        rest.unshift(path.basename(dir));
+        dir = path.dirname(dir);
+    }
+    if (gitOut(dir, ['rev-parse', '--show-toplevel']) !== root)
+        return ''; // outside this repository: not the team's file
+    const file = `${gitOut(dir, ['rev-parse', '--show-prefix']) ?? ''}${rest.join('/')}`;
+    if (!file)
+        return '';
+    const { off, lessons } = await briefingOff(root);
+    if (off)
+        return '';
+    return fileBriefingText(briefFile(root, file, { session, agent: 'claude', ...(lessons ? { lessons } : {}) }));
+}
+function gitOut(cwd, args) {
+    const run = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 5000 });
+    return run.status === 0 ? run.stdout.trim() : undefined;
+}
+/** The pull request's title and description as the goal, when gh can read one quickly; undefined otherwise. */
+function pullRequestGoal(cwd) {
+    const view = spawnSync('gh', ['pr', 'view', '--json', 'title,body'], { cwd, encoding: 'utf8', timeout: 5000 });
+    if (view.status !== 0)
+        return undefined;
+    try {
+        const pr = JSON.parse(view.stdout);
+        return [pr.title, pr.body].filter((t) => typeof t === 'string' && t.trim()).join('\n') || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function briefedFile(cwd) {
+    const dir = threadsDir(cwd);
+    return dir ? path.join(dir, '..', 'briefed-sessions.json') : undefined;
+}
+function briefedAlready(cwd, session) {
+    const file = briefedFile(cwd);
+    try {
+        return !!file && !!JSON.parse(fs.readFileSync(file, 'utf8'))[session];
+    }
+    catch {
+        return false;
+    }
+}
+function markBriefed(cwd, session) {
+    const file = briefedFile(cwd);
+    if (!file)
+        return;
+    try {
+        let all = {};
+        try {
+            all = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            // first briefing in this repository
+        }
+        all[session] = new Date().toISOString();
+        // Keep the newest 2,000 entries (sessions, and files within them): a guard against repeating, not a history (the thread is).
+        const kept = Object.entries(all).sort((a, b) => (a[1] < b[1] ? 1 : -1)).slice(0, 2000);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(Object.fromEntries(kept)));
+    }
+    catch {
+        // a session briefed twice is the worst case
+    }
+}

package/dist/commands/brief.test.d.ts

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

package/dist/commands/brief.test.js

@@ -0,0 +1,134 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readThread } from '@rigour-labs/core';
+import { briefCommand, hooksBriefCommand, hooksBriefFileCommand } from './brief.js';
+import { hooksCheckCommand, hooksInitCommand } from './hooks.js';
+let repo;
+const write = (file, text) => {
+    fs.mkdirSync(path.dirname(path.join(repo, file)), { recursive: true });
+    fs.writeFileSync(path.join(repo, file), text);
+};
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'brief-cli-'));
+    execFileSync('git', ['-C', repo, 'init', '-q', '-b', 'feat/retry']);
+    write('AGENTS.md', '- Every job in `src/jobs/` must take `withLock()` before its first read; a job that reads first double-sends.\n');
+    write('src/jobs/retry.ts', 'export async function retryJob() {}\n');
+    execFileSync('git', ['-C', repo, 'add', '-A']);
+    delete process.env.RIGOUR_BRIEF;
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.RIGOUR_BRIEF;
+    fs.rmSync(repo, { recursive: true, force: true });
+});
+describe('the prompt hook', () => {
+    const payload = (session, prompt = 'make the jobs retry with backoff') => JSON.stringify({ cwd: repo, session_id: session, prompt, hook_event_name: 'UserPromptSubmit' });
+    it("briefs from the session's first prompt, once per session, as context Claude Code adds", async () => {
+        const reply = JSON.parse(await hooksBriefCommand(payload('s1'), '/'));
+        expect(reply.hookSpecificOutput.hookEventName).toBe('UserPromptSubmit');
+        expect(reply.hookSpecificOutput.additionalContext).toContain('1. [must] Every job in `src/jobs/` must take `withLock()`');
+        expect(await hooksBriefCommand(payload('s1', 'now add tests'), '/')).toBe(''); // never twice in a session
+        expect(await hooksBriefCommand(payload('s2'), '/')).not.toBe(''); // a new session is briefed
+        expect(readThread(repo)?.events.map(e => [e.kind, e.session, e.agent])).toEqual([['brief', 's1', 'claude'], ['brief', 's2', 'claude']]);
+    });
+    it('says nothing when the team or the person switched briefings off, or the payload is not a session', async () => {
+        write('rigour.yml', 'version: 1\nbrief:\n  enabled: false\n');
+        expect(await hooksBriefCommand(payload('s1'), '/')).toBe('');
+        fs.rmSync(path.join(repo, 'rigour.yml'));
+        process.env.RIGOUR_BRIEF = '0';
+        expect(await hooksBriefCommand(payload('s2'), '/')).toBe('');
+        delete process.env.RIGOUR_BRIEF;
+        expect(await hooksBriefCommand('not json', '/')).toBe('');
+        expect(await hooksBriefCommand(JSON.stringify({ cwd: repo, prompt: 'x' }), '/')).toBe('');
+        expect(readThread(repo)?.events ?? []).toEqual([]);
+    });
+    it('caps the briefing at the max_items the team set', async () => {
+        write('AGENTS.md', Array.from({ length: 8 }, (_, i) => `- Every job in \`src/jobs/\` must call \`step${i}()\` before \`retryJob\` reads.\n`).join('\n'));
+        write('rigour.yml', 'version: 1\nbrief:\n  max_items: 3\n');
+        const text = JSON.parse(await hooksBriefCommand(payload('s3', 'retry job'), '/')).hookSpecificOutput.additionalContext;
+        expect(text.split('\n').filter(l => /^\d+\. /.test(l))).toHaveLength(3);
+    });
+});
+describe('the edit hook', () => {
+    const edit = (session, file) => JSON.stringify({ cwd: repo, session_id: session, hook_event_name: 'PreToolUse', tool_name: 'Edit', tool_input: { file_path: path.join(repo, file) } });
+    it("gives the team's word on a file the first time a session edits it, once per file per session", async () => {
+        const first = JSON.parse(await hooksBriefFileCommand(edit('s1', 'src/jobs/retry.ts'), '/'));
+        expect(first.hookSpecificOutput.hookEventName).toBe('PreToolUse');
+        expect(first.hookSpecificOutput.additionalContext).toContain('Rigour, before you edit src/jobs/retry.ts');
+        expect(first.hookSpecificOutput.additionalContext).toContain('1. [must] Every job in `src/jobs/` must take `withLock()`');
+        expect(await hooksBriefFileCommand(edit('s1', 'src/jobs/retry.ts'), '/')).toBe(''); // the same file again
+        expect(await hooksBriefFileCommand(edit('s2', 'src/jobs/retry.ts'), '/')).not.toBe(''); // another session
+        expect(await hooksBriefFileCommand(edit('s1', 'README.md'), '/')).toBe(''); // nothing applies: nothing said
+        expect(readThread(repo)?.events.map(e => [e.kind, e.file, e.session, e.items])).toEqual([['brief', 'src/jobs/retry.ts', 's1', 1], ['brief', 'src/jobs/retry.ts', 's2', 1], ['brief', 'README.md', 's1', 0]]);
+    });
+    it('places a file being created in a new folder, and says nothing for a file of another repository inside this one', async () => {
+        const created = JSON.parse(await hooksBriefFileCommand(edit('n1', 'src/jobs/new/sweep.ts'), '/'));
+        expect(created.hookSpecificOutput.additionalContext).toContain('Rigour, before you edit src/jobs/new/sweep.ts');
+        fs.mkdirSync(path.join(repo, 'vendor/other'), { recursive: true });
+        execFileSync('git', ['-C', path.join(repo, 'vendor/other'), 'init', '-q']);
+        expect(await hooksBriefFileCommand(edit('n1', 'vendor/other/src/jobs/x.ts'), '/')).toBe('');
+    });
+    it('says nothing for a file outside the repository, a bad payload, or when briefings are switched off', async () => {
+        expect(await hooksBriefFileCommand(JSON.stringify({ cwd: repo, session_id: 's1', tool_input: { file_path: '/etc/hosts' } }), '/')).toBe('');
+        expect(await hooksBriefFileCommand('not json', '/')).toBe('');
+        expect(await hooksBriefFileCommand(JSON.stringify({ cwd: repo, tool_input: { file_path: 'src/jobs/retry.ts' } }), '/')).toBe('');
+        process.env.RIGOUR_BRIEF = 'off';
+        expect(await hooksBriefFileCommand(edit('s3', 'src/jobs/retry.ts'), '/')).toBe('');
+        delete process.env.RIGOUR_BRIEF;
+        write('rigour.yml', 'version: 1\nbrief:\n  enabled: false\n');
+        expect(await hooksBriefFileCommand(edit('s4', 'src/jobs/retry.ts'), '/')).toBe('');
+        expect(readThread(repo)?.events ?? []).toEqual([]);
+    });
+});
+describe('the DLP pre-tool hook with --brief', () => {
+    it("adds the file's briefing to its own answer on a first edit, and nothing on other tools or later edits", async () => {
+        const out = [];
+        vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => (out.push(String(chunk)), true));
+        vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const run = async (tool, session) => {
+            out.length = 0;
+            await hooksCheckCommand(repo, { mode: 'dlp', brief: true, files: JSON.stringify({ cwd: repo, session_id: session, tool_name: tool, tool_input: { file_path: path.join(repo, 'src/jobs/retry.ts') } }) });
+            return JSON.parse(out.join(''));
+        };
+        const first = await run('Edit', 'd1');
+        expect(first.status).toBe('clean'); // the DLP answer is unchanged
+        expect(first.hookSpecificOutput).toMatchObject({ hookEventName: 'PreToolUse', additionalContext: expect.stringContaining('Rigour, before you edit src/jobs/retry.ts') });
+        expect((await run('Edit', 'd1')).hookSpecificOutput).toBeUndefined(); // briefed once in the session
+        expect((await run('Read', 'd2')).hookSpecificOutput).toBeUndefined(); // not an edit
+        out.length = 0;
+        await hooksCheckCommand(repo, { mode: 'dlp', files: JSON.stringify({ cwd: repo, session_id: 'd3', tool_name: 'Edit', tool_input: { file_path: path.join(repo, 'src/jobs/retry.ts') } }) });
+        expect(JSON.parse(out.join('')).hookSpecificOutput).toBeUndefined(); // without --brief, DLP only
+    });
+});
+describe('rigour brief', () => {
+    it('prints the briefing as JSON for a goal and files', async () => {
+        const out = [];
+        vi.spyOn(console, 'log').mockImplementation((line) => void out.push(String(line)));
+        expect(await briefCommand(repo, 'retry', { files: 'src/jobs/retry.ts', json: true })).toBe(0);
+        expect(JSON.parse(out.join('\n'))).toMatchObject({ goal: 'retry', files: ['src/jobs/retry.ts'], items: [{ kind: 'rule', requirement: true, cite: 'AGENTS.md' }] });
+    });
+});
+describe('rigour hooks init --brief', () => {
+    it('installs the prompt hook only when asked', async () => {
+        vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        await hooksInitCommand(repo, { tool: 'claude' });
+        const plain = JSON.parse(fs.readFileSync(path.join(repo, '.claude/settings.json'), 'utf8')).hooks;
+        expect(plain.UserPromptSubmit).toBeUndefined();
+        expect(plain.PreToolUse.some((h) => h.matcher === 'Write|Edit|MultiEdit')).toBe(false);
+        await hooksInitCommand(repo, { tool: 'claude', brief: true, force: true });
+        const hook = JSON.parse(fs.readFileSync(path.join(repo, '.claude/settings.json'), 'utf8')).hooks.UserPromptSubmit;
+        expect(hook[0].hooks[0].command).toMatch(/ brief$/);
+        expect(hook[0].hooks[0].timeout).toBe(20);
+        // DLP on (the default): the DLP hook, which already runs before every tool, briefs too; no second process per edit.
+        const pre = JSON.parse(fs.readFileSync(path.join(repo, '.claude/settings.json'), 'utf8')).hooks.PreToolUse;
+        expect(pre.some((h) => h.matcher === 'Write|Edit|MultiEdit')).toBe(false);
+        expect(pre.find((h) => h.matcher === '.*').hooks[0].command).toMatch(/--mode dlp --stdin --brief$/);
+        // DLP off: an edit hook of its own.
+        await hooksInitCommand(repo, { tool: 'claude', brief: true, dlp: false, force: true });
+        const own = JSON.parse(fs.readFileSync(path.join(repo, '.claude/settings.json'), 'utf8')).hooks.PreToolUse.find((h) => h.matcher === 'Write|Edit|MultiEdit');
+        expect(own.hooks[0].command).toMatch(/ brief-file$/);
+    });
+});

package/dist/commands/hooks-push.js

@@ -16,7 +16,7 @@ import { spawnSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { branchBase, branchFailures, captureHumanEdits, diffFromGit, itemLine, mergeBaseOf, resolveReviewer, reviewChange, reviewerInputs, reviewerBlocks, runReviewer, runToolchain, startBackgroundReview, } from '@rigour-labs/core';
+import { appendTaskEvent, branchBase, branchFailures, captureHumanEdits, diffFromGit, itemLine, mergeBaseOf, resolveReviewer, reviewChange, reviewerInputs, reviewerBlocks, runReviewer, runToolchain, startBackgroundReview, } from '@rigour-labs/core';
 import { loadHookConfig } from './hooks-stop.js';
 export async function hooksPushCommand(stdin, fallbackCwd) {
     const payload = parse(stdin);
@@ -45,6 +45,7 @@ export async function pushGate(dir) {
         // learning never blocks a push
     }
     const failures = await gates(repo, base, branch.mainRef, config);
+    appendTaskEvent(repo, { kind: 'push', passed: failures.lines.length === 0, failed: failures.lines.length });
     if (failures.lines.length === 0)
         return { exitCode: 0, message: await backgroundReviewNote(repo, branch.mainRef, config) };
     const log = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-push-')), 'gates.log');

package/dist/commands/hooks-push.test.js

@@ -3,6 +3,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { readThread } from '@rigour-labs/core';
 import { hooksPushCommand, isPush, pushTarget } from './hooks-push.js';
 describe('push command parsing', () => {
     it('acts on a real push only', () => {
@@ -60,6 +61,8 @@ describe('rigour hooks push', () => {
         expect(result.exitCode).toBe(2);
         expect(result.message).toContain('- typed-checks-unavailable could not run: ');
         expect(result.message).toContain('.generated/tsconfig.json');
+        // The task's thread keeps the blocked push.
+        expect(readThread(repo, 'feature')?.events.map(e => [e.kind, e.passed, e.failed])).toEqual([['push', false, 1]]);
     });
     it('blocks a push that adds an export nothing uses, saying where', async () => {
         write('src/util.ts', 'export const used = 1;\nexport const forgotten = 2;\n');

package/dist/commands/hooks-stop.js

@@ -20,7 +20,7 @@ import { execFileSync } from 'child_process';
 import fs from 'fs-extra';
 import path from 'path';
 import yaml from 'yaml';
-import { alreadyReviewed, appendAgentEvent, clearStopAttempts, ConfigSchema, countUsage, nextStopAttempt, recordFixLessons, recordReviewed, recordReviewOutcome, workFingerprint, sessionBaseline, STOP_MAX_ATTEMPTS, stopReview, teamMessage, untaught, recordTaught, captureHumanEdits, } from '@rigour-labs/core';
+import { alreadyReviewed, appendAgentEvent, appendTaskEvent, clearStopAttempts, ConfigSchema, countUsage, nextStopAttempt, recordFixLessons, recordReviewed, recordReviewOutcome, workFingerprint, sessionBaseline, STOP_MAX_ATTEMPTS, stopReview, teamMessage, untaught, recordTaught, captureHumanEdits, } from '@rigour-labs/core';
 export async function hooksStopCommand(tool, stdin, fallbackCwd) {
     const payload = parsePayload(stdin);
     const cwd = payload.cwd || fallbackCwd;
@@ -45,6 +45,7 @@ export async function hooksStopCommand(tool, stdin, fallbackCwd) {
         const decision = await stopReview(cwd, config ?? await loadHookConfig(cwd), attempt, sessionBaseline(cwd, session));
         const nothing = decision.reviewedFiles.length === 0;
         appendAgentEvent(cwd, { type: 'stop_review', tool, session, blocked: decision.block, blocking: decision.blocking, against: decision.against, ...(nothing ? { nothing_to_review: true } : {}) });
+        appendTaskEvent(cwd, { kind: 'stop-review', agent: tool, session, blocked: decision.block, blocking: decision.blocking, files: decision.reviewedFiles });
         if (nothing)
             process.stderr.write(`Rigour stop review: nothing to review against ${decision.against}.\n`);
         countUsage('stop_review');

package/dist/commands/hooks-stop.test.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { recordSessionBaseline } from '@rigour-labs/core';
+import { readThread, recordSessionBaseline } from '@rigour-labs/core';
 import { hooksStopCommand } from './hooks-stop.js';
 // A credential header on a redirect-following request: a proven (verified) high finding.
 const LEAKY = "export async function notify(endpoint: string, signature: string) {\n  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });\n}\n";
@@ -35,6 +35,8 @@ describe('rigour hooks stop', () => {
         expect(first.decision).toBe('block');
         expect(first.reason).toContain('src/notify.ts:2');
         expect(first.reason).toContain('attempt 1 of 3');
+        // The task's thread keeps the blocked stop review, with the agent and its session.
+        expect(readThread(repo)?.events.map(e => [e.kind, e.agent, e.session, e.blocked])).toEqual([['stop-review', 'claude', 's1', true]]);
         for (const n of [1, 2]) {
             write('src/notify.ts', `${LEAKY}// attempt ${n}\n`); // the agent edits, still leaking
             await hooksStopCommand('claude', payload, '/');

package/dist/commands/hooks.d.ts

@@ -15,6 +15,8 @@ export interface HooksOptions {
     block?: boolean;
     /** Also generate DLP pre-input warning hooks */
     dlp?: boolean;
+    /** Also brief the agent from its first prompt (Claude Code's UserPromptSubmit). Off unless asked. */
+    brief?: boolean;
 }
 export interface HooksCheckOptions {
     files?: string;
@@ -27,6 +29,8 @@ export interface HooksCheckOptions {
     agent?: string;
     /** Record last DLP warning detections as learned false positives (hook feedback) */
     dlpAllowLast?: boolean;
+    /** DLP mode before an edit: also give the team's word on the file, the first time the session edits it (one process for both). */
+    brief?: boolean;
 }
 /** This CLI, pinned to its version, as a hook runs it (`npx --yes @rigour-labs/cli@6.6.6`). */
 export declare function pinnedCliCommand(): string;

package/dist/commands/hooks.js

@@ -12,7 +12,8 @@ import path from 'path';
 import chalk from 'chalk';
 import { randomUUID } from 'crypto';
 import { fileURLToPath } from 'url';
-import { allowLastDLPBlock, createDLPAuditEntry, formatDLPAlert, recordInteractionEvidence, runHookChecker, countUsage, scanInputForCredentials, updateAutomaticIndexForFiles, writeDLPBlockManifest, STOP_MAX_ATTEMPTS, recordHookPayload, recordSessionBaseline, recordAgentWrites, } from '@rigour-labs/core';
+import { fileBriefingContext } from './brief.js';
+import { allowLastDLPBlock, appendTaskEvent, createDLPAuditEntry, formatDLPAlert, recordInteractionEvidence, runHookChecker, countUsage, scanInputForCredentials, updateAutomaticIndexForFiles, writeDLPBlockManifest, STOP_MAX_ATTEMPTS, recordHookPayload, recordSessionBaseline, recordAgentWrites, } from '@rigour-labs/core';
 import { pushGateShell, rigourUserDir } from '@rigour-labs/core';
 import { groupFilesByRepo, recordEditCatches } from './hooks-check-repos.js';
 import { installGitPushHook } from './hooks-git.js';
@@ -100,6 +101,13 @@ function stopHookCommand(checker, tool) {
     const args = checker.args[checker.args.length - 1] === 'check' ? [...checker.args.slice(0, -1), 'stop'] : [...checker.args, 'stop'];
     return checkerToShellCommand({ command: checker.command, args: [...args, '--tool', tool] });
 }
+/** A briefing hook: the checker command with `brief` (or `brief-file`) in place of `check`. */
+function briefHookCommand(checker, command = 'brief') {
+    const args = checker.args[checker.args.length - 1] === 'check' ? [...checker.args.slice(0, -1), command] : [...checker.args, command];
+    return checkerToShellCommand({ command: checker.command, args });
+}
+/** Seconds Claude Code waits for the briefing: it reads local files only. */
+const BRIEF_HOOK_TIMEOUT_S = 20;
 /** Seconds Claude Code waits for the stop review before letting the agent stop. */
 const STOP_HOOK_TIMEOUT_S = 120;
 /** Seconds Claude Code waits for the push gate: the project's tests and the reviewer can take minutes. */
@@ -144,7 +152,7 @@ function resolveTools(cwd, toolFlag) {
     return detected;
 }
 // ── Per-tool hook generators ─────────────────────────────────────────
-function generateClaudeHooks(checker, block, dlp = true) {
+function generateClaudeHooks(checker, block, dlp = true, brief = false) {
     const blockFlag = block ? ' --block' : '';
     const checkerCommand = checkerToShellCommand(checker);
     const hooks = {
@@ -171,11 +179,20 @@ function generateClaudeHooks(checker, block, dlp = true) {
             matcher: ".*",
             hooks: [{
                     type: "command",
-                    command: `${checkerCommand} --mode dlp --stdin`,
+                    // With --brief, the same process also briefs on a file's first edit: no second process before each edit.
+                    command: `${checkerCommand} --mode dlp --stdin${brief ? ' --brief' : ''}`,
                 }]
         });
     }
     hooks.PreToolUse = preToolUse;
+    // Opt-in: the team's briefing for the task, once per session, from the session's first prompt (rigour hooks brief),
+    // and the team's word on each file the first time the session edits it (rigour hooks brief-file).
+    if (brief) {
+        hooks.UserPromptSubmit = [{ hooks: [{ type: "command", command: briefHookCommand(checker), timeout: BRIEF_HOOK_TIMEOUT_S }] }];
+        // The DLP hook already runs before every tool and briefs too; without it, an edit hook of its own.
+        if (!dlp)
+            preToolUse.push({ matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: briefHookCommand(checker, 'brief-file'), timeout: BRIEF_HOOK_TIMEOUT_S }] });
+    }
     const settings = { hooks };
     return [{
             path: '.claude/settings.json',
@@ -481,7 +498,7 @@ export async function hooksInitCommand(cwd, options = {}) {
     // Collect generated files — each generator includes DLP hooks in the SAME config file
     const allFiles = [];
     for (const tool of tools) {
-        allFiles.push(...GENERATORS[tool](checker, block, dlp));
+        allFiles.push(...GENERATORS[tool](checker, block, dlp, !!options.brief));
     }
     if (options.dryRun) {
         printDryRun(allFiles);
@@ -490,7 +507,7 @@ export async function hooksInitCommand(cwd, options = {}) {
     const { written, skipped, failedPaths } = await writeHookFiles(cwd, allFiles, !!options.force);
     const failed = failedPaths.size;
     const unavailableTools = new Set(tools.filter(tool => {
-        const generatedPaths = GENERATORS[tool](checker, block, dlp).map(file => file.path);
+        const generatedPaths = GENERATORS[tool](checker, block, dlp, !!options.brief).map(file => file.path);
         return generatedPaths.every(filePath => failedPaths.has(filePath));
     }));
     console.log('');
@@ -626,8 +643,10 @@ export async function hooksCheckCommand(cwd, options = {}) {
         // Parse Cursor's structured payload to extract prompt text
         let textToScan = rawInput;
         let cursorMode = false;
+        let toolPayload;
         try {
             const payload = JSON.parse(rawInput);
+            toolPayload = payload;
             // Claude Code's PreToolUse hook sees every agent tool call: record it so
             // Studio's context savings are observed, not assumed.
             recordHookPayload(payload, cwd);
@@ -672,7 +691,9 @@ export async function hooksCheckCommand(cwd, options = {}) {
             }
         }
         else {
-            process.stdout.write(JSON.stringify(result));
+            // The first edit of a file in a session: the team's word on it rides on this same hook's answer.
+            const briefing = options.brief && /^(Write|Edit|MultiEdit)$/.test(String(toolPayload?.tool_name ?? '')) ? await fileBriefingContext(toolPayload, cwd).catch(() => '') : '';
+            process.stdout.write(JSON.stringify(briefing ? { ...result, hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: briefing } } : result));
         }
         if (result.status !== 'clean') {
             process.stderr.write('\n' + formatDLPAlert(result) + '\n');
@@ -702,6 +723,7 @@ export async function hooksCheckCommand(cwd, options = {}) {
     const timeout = options.timeout ? Number(options.timeout) : 5000;
     let rawStdin = '';
     let cursorMode = false;
+    let hookSession;
     if (options.stdin) {
         rawStdin = await readStdin();
         // Detect Cursor/IDE hook payload format
@@ -712,8 +734,10 @@ export async function hooksCheckCommand(cwd, options = {}) {
             }
             // The session's first edit fixes the commit its stop review starts from (hooks-stop.ts).
             const session = payload.session_id || payload.conversation_id;
-            if (typeof session === 'string')
+            if (typeof session === 'string') {
                 recordSessionBaseline(cwd, session);
+                hookSession = session;
+            }
         }
         catch (parseErr) {
             // Not valid JSON — log for debugging (stderr only, stdout must stay clean)
@@ -744,6 +768,7 @@ export async function hooksCheckCommand(cwd, options = {}) {
         const outcome = repoResult.status === 'pass' ? 'success' : repoResult.status === 'fail' ? 'rejected' : 'error';
         return [
             Promise.resolve().then(() => recordAgentWrites(root, repoFiles)), // as the agent left them: a person's later change is a lesson
+            Promise.resolve().then(() => appendTaskEvent(root, { kind: 'edit-check', ...(hookSession ? { session: hookSession } : {}), ...(agentId || cursorMode ? { agent: agentId || 'cursor' } : {}), files: repoFiles, findings: repoResult.failures.length, status: repoResult.status })),
             updateAutomaticIndexForFiles(root, repoFiles),
             recordEditCatches(root, repoResult, repoFiles),
             recordInteractionEvidence(root, {

package/dist/commands/hooks.test.js

@@ -2,6 +2,8 @@
  * Tests for hooks init command.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import { readThread } from '@rigour-labs/core';
 import { hooksInitCommand, hooksCheckCommand, parseStdinFiles } from './hooks.js';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -197,6 +199,13 @@ describe('hooksCheckCommand', () => {
         const output = stdoutSpy.mock.calls.map(call => String(call[0])).join('');
         expect(output).toContain('"status":"pass"');
     });
+    it("keeps each edit check on the task's thread, with the files and the findings", async () => {
+        execFileSync('git', ['-C', testDir, 'init', '-q', '-b', 'feat/PROJ-21-thread']);
+        fs.writeFileSync(path.join(testDir, 'ok.ts'), 'export const x = 1;\n');
+        vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await hooksCheckCommand(testDir, { files: 'ok.ts', agent: 'codex' });
+        expect(readThread(testDir, 'feat/PROJ-21-thread')?.events.map(e => [e.kind, e.agent, e.files, e.findings, e.status])).toEqual([['edit-check', 'codex', ['ok.ts'], 0, 'pass']]);
+    });
     it('reports skipped, not pass, when the hook named no file', async () => {
         const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         vi.spyOn(process.stderr, 'write').mockImplementation(() => true);

package/dist/commands/thread.d.ts

@@ -0,0 +1,3 @@
+export declare function threadCommand(cwd: string, key: string | undefined, options: {
+    json?: boolean;
+}): number;

package/dist/commands/thread.js

@@ -0,0 +1,26 @@
+/**
+ * `rigour thread [key]`: the thread of one engineering task, everything Rigour saw happen to it in order. The key is a
+ * ticket (`PROJ-123`), a branch, or a pull request (`#42`); without one, the checkout's own task.
+ */
+import chalk from 'chalk';
+import { readThread, threadText } from '@rigour-labs/core';
+export function threadCommand(cwd, key, options) {
+    const thread = readThread(cwd, key);
+    if (!thread) {
+        const what = key ? `no thread for ${key}` : 'no task here: the checkout is on a detached head';
+        if (options.json)
+            console.log(JSON.stringify({ task: key ?? null, events: [], error: what }, null, 2));
+        else
+            console.error(chalk.yellow(`${what}. A thread starts when a hooked agent edits, a stop review or push gate runs, or a review runs on a branch.`));
+        return 1;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(thread, null, 2));
+        return 0;
+    }
+    const [head, ...rest] = threadText(thread);
+    console.log(chalk.bold(head));
+    for (const line of rest)
+        console.log(line.startsWith('  ') ? chalk.dim(line) : line);
+    return 0;
+}

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

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

package/dist/commands/thread.test.js

@@ -0,0 +1,32 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { appendTaskEvent } from '@rigour-labs/core';
+import { threadCommand } from './thread.js';
+let repo;
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'thread-cli-'));
+    execFileSync('git', ['-C', repo, 'init', '-q', '-b', 'feat/PROJ-9-thing']);
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(repo, { recursive: true, force: true });
+});
+describe('rigour thread', () => {
+    it('prints the thread, as text or JSON, and exits 1 with a reason when there is none', () => {
+        const out = [];
+        vi.spyOn(console, 'log').mockImplementation((line) => void out.push(String(line)));
+        vi.spyOn(console, 'error').mockImplementation((line) => void out.push(String(line)));
+        expect(threadCommand(repo, 'feat/PROJ-9-thing', {})).toBe(1);
+        expect(out.join('\n')).toContain('no thread for feat/PROJ-9-thing');
+        appendTaskEvent(repo, { kind: 'push', passed: true, failed: 0 });
+        out.length = 0;
+        expect(threadCommand(repo, undefined, {})).toBe(0);
+        expect(out[0]).toContain('branch:feat/PROJ-9-thing'); // no commit names the ticket yet
+        out.length = 0;
+        expect(threadCommand(repo, 'feat/PROJ-9-thing', { json: true })).toBe(0);
+        expect(JSON.parse(out.join('\n'))).toMatchObject({ task: 'branch:feat/PROJ-9-thing', events: [{ kind: 'push', passed: true }] });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/cli",
-  "version": "6.7.10",
+  "version": "6.8.0",
   "description": "Code review that happens while your agent writes: deterministic checks on the lines it changed, quiet unless it can prove a defect, and learning from your team's fixes and dismissals. Works with Claude Code, Cursor, Codex, Cline and Windsurf.",
   "engines": {
     "node": ">=22.13"
@@ -56,13 +56,13 @@
     "inquirer": "9.2.16",
     "ora": "^8.0.1",
     "yaml": "^2.8.2",
-    "@rigour-labs/core": "6.7.10"
+    "@rigour-labs/core": "6.8.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/inquirer": "9.0.7",
     "@types/node": "^25.0.3",
-    "@rigour-labs/studio": "6.7.10"
+    "@rigour-labs/studio": "6.8.0"
   },
   "scripts": {
     "build": "tsc && pnpm bundle-studio",