@rigour-labs/cli 7.0.0-rc.1 → 7.0.0-rc.10

package/dist/cli.js

@@ -237,13 +237,21 @@ program
     .option('--instructions', 'With --team: also write AGENTS.md, and a one-line CLAUDE.md that imports it, where the project has none')
     .option('--no-semantic', 'Skip installing semantic search (recall and pattern matching then use keywords)')
     .option('--no-brief', 'Do not brief the agent with the team\'s rules and lessons (on by default: from each session\'s first prompt, and on the first edit of each file)')
+    .option('--report-only', 'A team\'s first week: the edit check, the stop review and the push gate (git\'s pre-push hook too) say what they would block and block nothing. A real credential is still refused. With --team, for everyone (rigour.yml)')
+    .option('--block', 'Make the gates block again after --report-only')
     .action(async (options) => {
+    if (options.reportOnly && options.block) {
+        console.error('Choose one: --report-only or --block.');
+        process.exit(2);
+    }
     await setupCommand(process.cwd(), options);
 });
 program
     .command('doctor')
     .description('Check that Rigour is wired up and firing here, and that the install is healthy')
     .option('--clean-cache', 'Remove context-cache rows Rigour no longer reads, and shrink the database when the disk has room')
+    .option('--merge-state', 'Merge what a home ending in .rigour from before 6.11.1 left over into the live state directory (a dry run; add --yes)')
+    .option('--yes', 'With --merge-state: do it')
     .action(async (options) => {
     await doctorCommand(options);
 });
@@ -406,7 +414,9 @@ program
     .option('--include-bots', 'With --list: also list candidates only review bots raised (hidden by default)')
     .option('--promote <id>', 'Accept a candidate as a lesson (recorded as your decision)')
     .option('--reject <id>', 'Reject a candidate or lesson: the judges are told this team decided against it')
-    .option('--why <text>', 'Why, recorded with --promote or --reject')
+    .option('--not-a-rule <id>', 'Drop a candidate that is a one-off for its pull request, not a practice either way: never served, the judges are told nothing')
+    .option('--take-back <id>', 'Take back the last decision on a lesson (promote, reject or not a rule): a candidate again; the decision stays in its history')
+    .option('--why <text>', 'Why, recorded with --promote, --reject, --not-a-rule or --take-back')
     .option('--scope <id>', 'Set how far a lesson reaches, with --to: its file, its folder, or every change (a team standard); recorded as your decision')
     .option('--to <reach>', 'With --scope: file, folder or repo')
     .option('--use-wording <id>', 'Take the corrected wording a newer version suggests for a lesson you decided (the old wording is kept as evidence)')

package/dist/commands/doctor.d.ts

@@ -2,6 +2,8 @@ export declare function detectInstallKind(binaryPath: string): string;
 export declare function hasVersionShadowing(versions: string[]): boolean;
 export declare function doctorCommand(options?: {
     cleanCache?: boolean;
+    mergeState?: boolean;
+    yes?: boolean;
 }, cwd?: string): Promise<void>;
 /** This repository first: is each part of Rigour wired up, and did it fire this week. */
 export declare function printRepoSetup(cwd: string): Promise<void>;

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs';
 import { execFileSync } from 'child_process';
-import { cleanContextCache, deadCacheRows, loadSettings, resolveDeepOptions, getCachedModel, legacyStateNote, rigourUserDir, SidecarProvider } from '@rigour-labs/core';
+import { applyStateMerge, cleanContextCache, deadCacheRows, loadSettings, resolveDeepOptions, getCachedModel, legacyStateNote, planStateMerge, rigourUserDir, SidecarProvider } from '@rigour-labs/core';
 import { checkRepoSetup } from './repo-setup.js';
 import { configMigrations } from './setup-migrations.js';
 import { selfTestCommand, selfTestGitPushHook } from './hooks-git.js';
@@ -65,6 +65,8 @@ export async function doctorCommand(options = {}, cwd = process.cwd()) {
     console.log(chalk.bold.cyan('\nRigour Doctor\n'));
     if (options.cleanCache)
         return cleanCache();
+    if (options.mergeState)
+        return mergeState(!!options.yes);
     await printRepoSetup(cwd);
     console.log(semanticStatusLine(cwd) + '\n');
     await printPushGate(cwd);
@@ -151,7 +153,7 @@ export async function printRepoSetup(cwd) {
     // Settings an older Rigour wrote that no longer mean what they say: loud, since nothing else reports them.
     for (const migration of configMigrations(cwd)) {
         console.log(`  ${chalk.red('✘')} ${chalk.red(migration.problem)}`);
-        console.log(chalk.dim(`      fix: ${migration.automatic ? 'rigour setup' : 'edit rigour.yml'}`));
+        console.log(chalk.dim(`      fix: ${migration.automatic ? 'rigour setup --team' : 'edit rigour.yml'}`));
     }
     console.log('');
 }
@@ -174,6 +176,25 @@ async function printPushGate(cwd) {
         console.log(chalk.dim(`  - ${step}`));
     console.log(test.ok ? chalk.green('  ✓ The push gate holds under a real git push.\n') : chalk.red('  ✘ The push gate does not hold.\n'));
 }
+/** `--merge-state`: what an old home ending in .rigour left outside the live state directory, merged in; a dry run unless --yes. */
+function mergeState(yes) {
+    const plan = planStateMerge();
+    if (!plan)
+        return void console.log(chalk.green('Nothing to merge: Rigour keeps its state in one directory here.\n'));
+    console.log(`Live state: ${plan.live}\nLeft over in: ${plan.outer}\n`);
+    for (const step of plan.steps) {
+        console.log(step.action === 'move'
+            ? `  move   ${step.rel} into the live directory`
+            : `  keep the live ${step.rel}; rename the left-over one to ${path.basename(step.to)}`);
+    }
+    if (plan.steps.some(step => path.basename(step.from) === 'rigour.db' && step.action === 'aside')) {
+        console.log(chalk.yellow('\n  rigour.db is in both: the live one stays in use and the left-over one is kept, renamed, not merged row by row. Its old memory and lessons are not in the live database.'));
+    }
+    if (!yes)
+        return void console.log(chalk.dim('\nNothing changed (a dry run). To do it: rigour doctor --merge-state --yes. Nothing is deleted or overwritten.\n'));
+    applyStateMerge(plan.steps);
+    console.log(chalk.green(`\nMerged: ${plan.steps.length} entr${plan.steps.length === 1 ? 'y' : 'ies'}. Nothing was deleted.\n`));
+}
 async function printDatabaseHealth() {
     const dead = await deadCacheRows().catch(() => null);
     if (!dead)

package/dist/commands/hooks-git.js

@@ -13,6 +13,7 @@ import { execFileSync, spawnSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { pinnedHomeEnv } from '@rigour-labs/core/profile';
 import { pushGate } from './hooks-push.js';
 const MARK = 'rigour hooks push --git';
 /**
@@ -101,18 +102,19 @@ export async function selfTestGitPushHook(rigourCommand) {
         git(clone, ['commit', '-qm', 'base']);
         git(clone, ['push', '-q', '-u', 'origin', 'HEAD:main']);
         git(clone, ['checkout', '-qb', 'feature']);
+        // The clone is in the temp folder, where another profile may match: the pushes keep this repository's home.
         const installed = installGitPushHook(clone, rigourCommand);
         steps.push(`hook ${installed.action} at ${installed.path}`);
         fs.writeFileSync(path.join(clone, 'src/util.ts'), 'export const used = 1;\nexport const forgotten = 2;\n');
         git(clone, ['commit', '-qam', 'adds an export nothing uses']);
-        const refused = spawnSync('git', ['push', 'origin', 'feature'], { cwd: clone, encoding: 'utf8', env: { ...process.env, RIGOUR_TELEMETRY: '0' } });
+        const refused = spawnSync('git', ['push', 'origin', 'feature'], { cwd: clone, encoding: 'utf8', env: { ...pinnedHomeEnv(), RIGOUR_TELEMETRY: '0' } });
         const refusedRef = gitOutput(remote, ['rev-parse', '--verify', '-q', 'refs/heads/feature']);
         if (refused.status === 0 || refusedRef)
             return { ok: false, steps: [...steps, `FAIL: a push with an unused export went through (git exit ${refused.status}; remote has feature: ${!!refusedRef})\n${(refused.stderr || '').trim().slice(-600)}`] };
         steps.push(`a push with an unused export was refused (git exit ${refused.status}); the remote has no feature branch`);
         fs.writeFileSync(path.join(clone, 'src/util.ts'), 'export const used = 1;\n');
         git(clone, ['commit', '-qam', 'fix']);
-        const accepted = spawnSync('git', ['push', 'origin', 'feature'], { cwd: clone, encoding: 'utf8', env: { ...process.env, RIGOUR_TELEMETRY: '0' } });
+        const accepted = spawnSync('git', ['push', 'origin', 'feature'], { cwd: clone, encoding: 'utf8', env: { ...pinnedHomeEnv(), RIGOUR_TELEMETRY: '0' } });
         const acceptedRef = gitOutput(remote, ['rev-parse', '--verify', '-q', 'refs/heads/feature']);
         if (accepted.status !== 0 || acceptedRef !== gitOutput(clone, ['rev-parse', 'HEAD']))
             return { ok: false, steps: [...steps, `FAIL: the fixed push did not land (git exit ${accepted.status})\n${(accepted.stderr || '').trim().slice(-600)}`] };

package/dist/commands/hooks-push.js

@@ -18,6 +18,7 @@ import os from 'os';
 import path from 'path';
 import { appendTaskEvent, branchBase, branchFailures, captureHumanEdits, diffFromGit, hookGoalDescription, itemLine, recordGoal, mergeBaseOf, resolveReviewer, reviewChange, reviewerCapReached, reviewerInputs, reviewerBlocks, runReviewer, runToolchain, startBackgroundReview, } from '@rigour-labs/core';
 import { loadHookConfig } from './hooks-stop.js';
+import { REPORT_ONLY_PREFIX, reportOnly } from './report-only.js';
 export async function hooksPushCommand(stdin, fallbackCwd) {
     const payload = parse(stdin);
     const command = String(payload.tool_input?.command ?? '');
@@ -62,9 +63,13 @@ export async function pushGate(dir) {
         return { exitCode: 0, message: await backgroundReviewNote(repo, branch.mainRef, config) };
     const log = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-push-')), 'gates.log');
     fs.writeFileSync(log, failures.log.join('\n\n'));
+    const against = `${path.basename(repo)} against ${branch.mainRef.replace(/^refs\/(remotes\/|heads\/)/, '')} (full output: ${log})`;
+    // A team's first week: the push goes ahead, and the agent and the terminal are told what would have stopped it.
+    if (reportOnly(repo, config))
+        return { exitCode: 0, message: [`${REPORT_ONLY_PREFIX} the push would have been blocked: ${failures.lines.length} check(s) failed for ${against}:`, ...failures.lines].join('\n') };
     return {
         exitCode: 2,
-        message: [`Push blocked: ${failures.lines.length} check(s) failed for ${path.basename(repo)} against ${branch.mainRef.replace(/^refs\/(remotes\/|heads\/)/, '')} (full output: ${log}). Fix each, then push again:`, ...failures.lines].join('\n'),
+        message: [`Push blocked: ${failures.lines.length} check(s) failed for ${against}. Fix each, then push again:`, ...failures.lines].join('\n'),
     };
 }
 async function gates(repo, base, mainRef, config) {

package/dist/commands/hooks-stop.js

@@ -20,6 +20,7 @@ import { execFileSync } from 'child_process';
 import fs from 'fs-extra';
 import path from 'path';
 import yaml from 'yaml';
+import { REPORT_ONLY_PREFIX, reportOnly } from './report-only.js';
 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);
@@ -42,7 +43,13 @@ export async function hooksStopCommand(tool, stdin, fallbackCwd) {
     if (attempt > STOP_MAX_ATTEMPTS)
         return '';
     try {
-        const decision = await stopReview(cwd, config ?? await loadHookConfig(cwd), attempt, sessionBaseline(cwd, session));
+        const loaded = config ?? await loadHookConfig(cwd);
+        const review = await stopReview(cwd, loaded, attempt, sessionBaseline(cwd, session));
+        // A team's first week: what would have held the agent is said, and the agent finishes (report-only.ts).
+        const reporting = review.block && reportOnly(cwd, loaded);
+        if (reporting)
+            process.stderr.write(`${REPORT_ONLY_PREFIX} the agent would have been held to fix:\n${review.message}\n`);
+        const decision = reporting ? { ...review, block: false } : review;
         const nothing = decision.reviewedFiles.length === 0;
         appendAgentEvent(cwd, { type: 'stop_review', tool, session, blocked: decision.block, blocking: decision.blocking, against: decision.against, ...(decision.held.length ? { findings: decision.held.slice(0, 20) } : {}), ...(nothing ? { nothing_to_review: true } : {}) });
         appendTaskEvent(cwd, { kind: 'stop-review', agent: tool, session, blocked: decision.block, blocking: decision.blocking, files: decision.reviewedFiles });
@@ -66,7 +73,7 @@ export async function hooksStopCommand(tool, stdin, fallbackCwd) {
         recordTaught(cwd, session, fresh);
         if (!decision.block) {
             clearStopAttempts(cwd, session);
-            return guidance.length ? blockWith(tool, teamMessage(guidance)) : '';
+            return guidance.length && !reportOnly(cwd, loaded) ? blockWith(tool, teamMessage(guidance)) : '';
         }
         return blockWith(tool, guidance.length ? `${decision.message}\n\n${teamMessage(guidance)}` : decision.message);
     }

package/dist/commands/hooks.d.ts

@@ -34,6 +34,8 @@ export interface HooksCheckOptions {
 }
 /** This CLI, pinned to its version, as a hook runs it (`npx --yes @rigour-labs/cli@6.6.6`). */
 export declare function pinnedCliCommand(): string;
+/** Every project file Rigour's hooks are written to, for every agent: what a team commits when it installs Rigour. */
+export declare function projectHookPaths(): string[];
 /**
  * The personal install's agent hooks, once per machine (personal.ts): every agent's user-level
  * config, each command guarded so it runs only in a repository switched on with `rigour setup`.

package/dist/commands/hooks.js

@@ -21,6 +21,7 @@ import { isRigourScript, mergeHooksInto, recordCreated } from './install-record.
 import { agentHome, asUserLevel, installedAgents } from './personal.js';
 import { hookStdin } from './hook-input.js';
 import { loadHookConfig } from './hooks-stop.js';
+import { REPORT_ONLY_PREFIX, reportOnly } from './report-only.js';
 function getHookCliVersion() {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     const packagePath = path.resolve(thisDir, '../../package.json');
@@ -382,6 +383,11 @@ const GENERATORS = {
     cline: generateClineHooks,
     windsurf: generateWindsurfHooks,
 };
+/** Every project file Rigour's hooks are written to, for every agent: what a team commits when it installs Rigour. */
+export function projectHookPaths() {
+    const checker = resolveCheckerCommand();
+    return [...new Set(Object.keys(GENERATORS).flatMap(tool => GENERATORS[tool](checker, true).map(file => file.path)))];
+}
 // ── File writing ─────────────────────────────────────────────────────
 function printDryRun(files) {
     console.log(chalk.cyan('\nDry run — files that would be created:\n'));
@@ -803,6 +809,8 @@ export async function hooksCheckCommand(cwd, options = {}) {
         result: await runHookChecker({ cwd: group.root, files: group.files, timeout_ms: Number.isFinite(timeout) ? timeout : 5000, agentId }),
     })));
     const result = mergeHookResults(runs.map(r => r.result));
+    // A team's first week: the findings are said, and the edit goes through (report-only.ts).
+    const blocking = !!options.block && !(await Promise.all(runs.map(async (run) => reportOnly(run.root, await loadHookConfig(run.root).catch(() => undefined))))).some(Boolean);
     const counted = { agent: cursorMode ? 'cursor' : agentId };
     countUsage('hook_check', 1, counted);
     for (const failure of result.failures)
@@ -822,8 +830,8 @@ export async function hooksCheckCommand(cwd, options = {}) {
             }),
             logStudioEvent(root, {
                 type: 'hook_check', requestId, outcome, status: repoResult.status, agentId,
-                // Only a --block hook stops the edit; without it the findings are reported and the agent carries on.
-                blocked: !!options.block && repoResult.status === 'fail',
+                // Only a --block hook stops the edit; without it (or in report-only) the findings are reported and the agent carries on.
+                blocked: blocking && repoResult.status === 'fail',
                 files: repoFiles, summary: `${repoFiles.length} file(s), ${repoResult.failures.length} finding(s)`,
                 findings: repoResult.failures.slice(0, 10).map(f => ({ gate: f.gate, file: f.file, line: f.line, message: f.message, severity: f.severity })),
             }),
@@ -839,7 +847,7 @@ export async function hooksCheckCommand(cwd, options = {}) {
             })
                 .join('\n');
             process.stdout.write(JSON.stringify({
-                continue: !options.block, // block mode = stop, otherwise warn
+                continue: !blocking, // block mode = stop, otherwise warn
                 user_message: `⚠️ Rigour: ${result.failures.length} issue(s) found:\n${messages}`,
             }));
         }
@@ -858,9 +866,10 @@ export async function hooksCheckCommand(cwd, options = {}) {
             const loc = failure.line ? `:${failure.line}` : '';
             process.stderr.write(`[rigour/${failure.gate}] ${failure.file}${loc}: ${failure.message}\n`);
         }
-        if (options.block) {
+        if (blocking)
             process.exitCode = 2;
-        }
+        else if (options.block)
+            process.stderr.write(`${REPORT_ONLY_PREFIX} the edit would have been blocked for the above.\n`);
     }
 }
 /** One verdict for a hook call that checked files in several repositories. */

package/dist/commands/learn-reviews.d.ts

@@ -4,6 +4,8 @@ export interface LearnReviewsOptions {
     limit?: string;
     promote?: string;
     reject?: string;
+    notARule?: string;
+    takeBack?: string;
     why?: string;
     list?: boolean;
     /** With --list: also list candidates only review bots raised (hidden by default, and counted). */

package/dist/commands/learn-reviews.js

@@ -18,6 +18,10 @@ export async function learnReviewsCommand(cwd, options) {
         return decide(cwd, options.promote, 'accepted', options.why);
     if (options.reject)
         return decide(cwd, options.reject, 'rejected', options.why);
+    if (options.notARule)
+        return decide(cwd, options.notARule, 'not-a-rule', options.why);
+    if (options.takeBack)
+        return decide(cwd, options.takeBack, 'took-back', options.why);
     if (options.list)
         return list(cwd, options.json, options.includeBots);
     if (options.useWording)
@@ -81,7 +85,7 @@ function list(cwd, json, includeBots) {
         console.log('No review lessons yet. Run `rigour learn-reviews`.');
 }
 function printLesson(l) {
-    const label = { verified: chalk.green('lesson   '), candidate: chalk.yellow('candidate'), rejected: chalk.red('rejected ') };
+    const label = { verified: chalk.green('lesson   '), candidate: chalk.yellow('candidate'), rejected: chalk.red('rejected '), dropped: chalk.dim('not a rule') };
     const prs = [...new Set(l.evidence.map(e => `#${e.pr}`))].join(', ');
     const by = chalk.dim(`${l.promotedBy ? ` [${l.promotedBy}]` : ''}${l.scope ? ` [${l.scope === 'repo' ? 'every change' : 'its folder'}]` : ''}`);
     console.log(`${label[l.state]} ${chalk.dim(l.id)} ${l.file || '(no file)'}: ${l.text}${by} ${chalk.dim(`(${prs})`)}`);
@@ -199,17 +203,32 @@ function useWording(cwd, id) {
     console.log(chalk.green(`✔ Now reads: ${lesson.text}`));
 }
 /** A person's decision, kept as evidence with who made it (their git email) and why. */
+/** What each decision tells the person it did. */
+const DECIDED = {
+    accepted: text => chalk.green(`✔ A lesson now: ${text}`),
+    rejected: text => chalk.yellow(`✔ Rejected: ${text}. The judges are told this team decided against it.`),
+    'not-a-rule': text => chalk.dim(`✔ Not a rule (a one-off for that pull request): ${text}. Never served, and the judges are told nothing.`),
+    'took-back': text => chalk.yellow(`✔ Taken back, a candidate again: ${text}. The earlier decision is kept in its history.`),
+};
 function decide(cwd, id, decision, why) {
     const by = deciderOrExit(cwd);
     if (!by)
         return;
-    const lesson = decideLesson(cwd, id, decision, by, why);
+    let lesson;
+    try {
+        lesson = decideLesson(cwd, id, decision, by, why);
+    }
+    catch (e) {
+        console.error(chalk.red(e.message));
+        process.exitCode = 1;
+        return;
+    }
     if (!lesson) {
         console.error(chalk.red(`No lesson ${id}.`));
         process.exitCode = 1;
         return;
     }
-    console.log(decision === 'accepted' ? chalk.green(`✔ A lesson now: ${lesson.text}`) : chalk.yellow(`✔ Rejected: ${lesson.text}. The judges are told this team decided against it.`));
+    console.log(DECIDED[decision](lesson.text));
 }
 /** The repository's rigour.yml, or the defaults when it cannot be read (no rigour.yml is the defaults already). */
 async function teamConfig(cwd) {

package/dist/commands/profile.js

@@ -2,8 +2,9 @@
  * `rigour profile list|which|add`: one machine, many organizations (core utils/profile.ts).
  */
 import chalk from 'chalk';
-import { profileFor, profilesPath, readProfiles, writeProfiles } from '@rigour-labs/core/profile';
-import { rigourUserDir } from '@rigour-labs/core';
+import path from 'path';
+import { expandHome, profileFor, profilesPath, readProfiles, writeProfiles } from '@rigour-labs/core/profile';
+import { homeFor, rigourUserDir } from '@rigour-labs/core';
 export function profileListCommand() {
     const profiles = readProfiles();
     if (profiles.length === 0)
@@ -19,6 +20,15 @@ export function profileWhichCommand(cwd) {
     console.log(profile ? `${chalk.bold(profile.name)} (matched ${cwd})` : chalk.dim('No profile matches here: Rigour uses its default home.'));
     console.log(chalk.dim(`  home: ${rigourUserDir()}`));
 }
+/**
+ * A new profile's home, as one directory: a home ending in .rigour with no state nested in it is that folder's parent,
+ * so the state is that folder itself (user-state.ts homeFor). One with state nested in it (a home from before 6.11.1)
+ * is kept as given, where the live state is.
+ */
+function profileHomeFor(home) {
+    const full = path.resolve(expandHome(home));
+    return path.basename(full) === '.rigour' ? homeFor(full) : home;
+}
 export function profileAddCommand(name, options) {
     const list = (value) => (value ?? '').split(',').map(v => v.trim()).filter(Boolean);
     const teamParts = [options.organization, options.team, options.actor];
@@ -27,7 +37,7 @@ export function profileAddCommand(name, options) {
     const profile = {
         name,
         match: list(options.match),
-        ...(options.home ? { home: options.home } : {}),
+        ...(options.home ? { home: profileHomeFor(options.home) } : {}),
         ...(options.organization ? {
             team: {
                 organization: options.organization, team: options.team, actor: options.actor,
@@ -41,4 +51,6 @@ export function profileAddCommand(name, options) {
         throw new Error('--match needs at least one path or remote (github.com/acme/*).');
     writeProfiles([...readProfiles().filter(p => p.name !== name), profile]);
     console.log(chalk.green(`Profile ${name} saved to ${profilesPath()}.`));
+    if (profile.home)
+        console.log(chalk.dim(`  Its state: ${path.join(homeFor(path.resolve(expandHome(profile.home))), '.rigour')}`));
 }

package/dist/commands/repo-setup.js

@@ -32,11 +32,13 @@ export async function checkRepoSetup(cwd, now = new Date(), toolCalls, installed
         { name: 'Windsurf', config: read('.windsurf/hooks.json') + home('.codeium/windsurf/hooks.json') },
     ].filter(a => a.config);
     const mcpConfig = read('.mcp.json') + read('.cursor/mcp.json') + home('.claude.json') + home('.cursor/mcp.json');
-    const version = versionCheck(agents.map(a => a.config).join('\n'), mcpConfig, installed);
+    // The repository's own committed install: only `rigour setup --team` changes it (a plain setup leaves it as committed).
+    const setup = !personal && /rigour/i.test(agents.map(a => a.config).join('\n')) ? 'rigour setup --team' : 'rigour setup';
+    const version = versionCheck(agents.map(a => a.config).join('\n'), mcpConfig, installed, setup);
     return [
         configCheck(cwd, personal),
-        editCheck(agents, now, events),
-        stopCheck(agents.map(a => a.config).join('\n'), now, events),
+        editCheck(agents, now, events, setup),
+        stopCheck(agents.map(a => a.config).join('\n'), now, events, setup),
         mcpCheck(mcpConfig, now, calls),
         ...(version ? [version] : []),
         prCheck(cwd),
@@ -47,7 +49,7 @@ export async function checkRepoSetup(cwd, now = new Date(), toolCalls, installed
  * (`@rigour-labs/cli@6.12.4`), so an upgrade reaches them only when `rigour setup` rewrites the pin.
  * Nothing to say when nothing pins a version (a source checkout runs its own build).
  */
-function versionCheck(hooks, mcp, installed) {
+function versionCheck(hooks, mcp, installed, setup) {
     const pins = (text, pkg) => [...new Set([...text.matchAll(new RegExp(`@rigour-labs/${pkg}@([0-9A-Za-z.-]+)`, 'g'))].map(m => m[1]))];
     const hookPins = pins(hooks, 'cli');
     const mcpPins = pins(mcp, 'mcp');
@@ -62,7 +64,7 @@ function versionCheck(hooks, mcp, installed) {
         ...mcpPins.filter(v => v !== installed).map(v => (/^\d+$/.test(v) || v === 'latest' ? `the MCP server floats on @${v}` : `the MCP server runs ${v}`)),
     ];
     return stale.length
-        ? { id: 'version', name, state: 'broken', detail: `${stale.join(', ')}; installed is ${installed}`, fix: 'rigour setup' }
+        ? { id: 'version', name, state: 'broken', detail: `${stale.join(', ')}; installed is ${installed}`, fix: setup }
         : { id: 'version', name, state: 'working', detail: installed };
 }
 function configCheck(cwd, personal) {
@@ -73,22 +75,22 @@ function configCheck(cwd, personal) {
         : { id: 'config', name: 'Project settings', state: 'missing', detail: 'No rigour.yml: Rigour uses its defaults', fix: 'rigour setup' };
 }
 /** One check for every agent's edit hook: events do not say which agent fired them, so counts are not split. */
-function editCheck(agents, now, events) {
+function editCheck(agents, now, events, setup) {
     const wired = agents.filter(a => a.config.includes('hooks check'));
     const name = wired.length ? `Checks ${listOf(wired.map(a => a.name))} as it writes` : 'Checks your agent as it writes';
     if (wired.length === 0)
-        return { id: 'edit', name, state: 'missing', detail: 'No edit hook configured', fix: 'rigour setup' };
+        return { id: 'edit', name, state: 'missing', detail: 'No edit hook configured', fix: setup };
     const broken = wired.find(a => isOldEditHook(a.config));
     if (broken) {
         // setup rewrites Rigour's own entries where they live (the project, or the machine for a personal install).
-        return { id: 'edit', name, state: 'broken', detail: `The ${broken.name} hook is the old form: it reads a variable the agent never sets, so no edit is checked`, fix: 'rigour setup' };
+        return { id: 'edit', name, state: 'broken', detail: `The ${broken.name} hook is the old form: it reads a variable the agent never sets, so no edit is checked`, fix: setup };
     }
     return fired('edit', name, events.filter(e => e.type === 'hook_check'), now, 'edit checks');
 }
-function stopCheck(config, now, events) {
+function stopCheck(config, now, events, setup) {
     const name = 'Stops an agent finishing with a known bug';
     if (!config.includes('hooks stop'))
-        return { id: 'stop', name, state: 'missing', detail: 'No stop hook configured', fix: 'rigour setup' };
+        return { id: 'stop', name, state: 'missing', detail: 'No stop hook configured', fix: setup };
     return fired('stop', name, events.filter(e => e.type === 'stop_review'), now, 'finish checks');
 }
 function mcpCheck(mcpJson, now, calls) {

package/dist/commands/report-only.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from '@rigour-labs/core';
+/** What a gate says instead of blocking. */
+export declare const REPORT_ONLY_PREFIX = "Rigour (report only; nothing was blocked, `rigour setup --block` makes it block):";
+/**
+ * Whether this repository's gates only report. The team's rigour.yml decides when it says either way: an explicit
+ * `hooks.report_only: false` is a floor a person's switch never lowers, as with the reviewer's caps. Unset, the
+ * person's switch applies.
+ */
+export declare function reportOnly(cwd: string, config?: Config): boolean;
+/** What a person's switch says where the team's rigour.yml requires blocking. */
+export declare const TEAM_REQUIRES_BLOCKING = "Rigour: report-only is on for this clone, but the team's rigour.yml requires blocking here (hooks.report_only: false), so the gates block.";
+/** Sets or clears the person's switch for this repository; false outside a git repository. */
+export declare function setReportOnlyHere(cwd: string, on: boolean): boolean;

package/dist/commands/report-only.js

@@ -0,0 +1,45 @@
+/**
+ * Report-only: a team's first week. Every gate (the edit check, the stop review, the push gate, git's pre-push hook
+ * included) says what it would have blocked and lets the work through; `rigour setup --block` makes them block.
+ * The scan for credentials before a tool call is not one of them and keeps denying a real secret.
+ *
+ * Read at run time, so the hook commands never change between the first week and after: from rigour.yml
+ * (`hooks.report_only`, a team's choice, written by `rigour setup --team --report-only`) or from a marker in the
+ * repository's git directory (a person's, written by `rigour setup --report-only`, never in the working tree).
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const MARKER = 'rigour-report-only';
+/** What a gate says instead of blocking. */
+export const REPORT_ONLY_PREFIX = 'Rigour (report only; nothing was blocked, `rigour setup --block` makes it block):';
+function markerPath(cwd) {
+    const common = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd, encoding: 'utf8' });
+    return common.status === 0 ? path.join(common.stdout.trim(), MARKER) : undefined;
+}
+/**
+ * Whether this repository's gates only report. The team's rigour.yml decides when it says either way: an explicit
+ * `hooks.report_only: false` is a floor a person's switch never lowers, as with the reviewer's caps. Unset, the
+ * person's switch applies.
+ */
+export function reportOnly(cwd, config) {
+    const team = config?.hooks?.report_only;
+    const marker = markerPath(cwd);
+    const personal = !!marker && fs.existsSync(marker);
+    if (team === false && personal)
+        process.stderr.write(`${TEAM_REQUIRES_BLOCKING}\n`);
+    return team ?? personal;
+}
+/** What a person's switch says where the team's rigour.yml requires blocking. */
+export const TEAM_REQUIRES_BLOCKING = "Rigour: report-only is on for this clone, but the team's rigour.yml requires blocking here (hooks.report_only: false), so the gates block.";
+/** Sets or clears the person's switch for this repository; false outside a git repository. */
+export function setReportOnlyHere(cwd, on) {
+    const marker = markerPath(cwd);
+    if (!marker)
+        return false;
+    if (on)
+        fs.writeFileSync(marker, 'Rigour reports and never blocks here (rigour setup --report-only). `rigour setup --block` makes it block.\n');
+    else
+        fs.rmSync(marker, { force: true });
+    return true;
+}

package/dist/commands/semantic.js

@@ -4,6 +4,7 @@
  * meaning. `rigour setup` installs it unless asked not to, or the disk is too full; nothing else
  * ever does, so a hook or an MCP call never waits on a download.
  */
+import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { execa } from 'execa';
 import fs from 'fs';
@@ -51,13 +52,24 @@ function freeBytes(dir) {
         return undefined;
     }
 }
+/** What semantic search takes on disk, as measured per platform after setup's pruning (semantic-runtime.ts). */
+const SIZE = 'about 250 MB on Linux, 280 MB on macOS';
+/** A person at a terminal, not a script, a pipe or CI. */
+function interactive() {
+    return !!process.stdin.isTTY && !!process.stdout.isTTY && !process.env.CI;
+}
 /** The setup step, as a person reads it. */
 export async function setupSemantic(cwd) {
     if (locateTransformers(cwd)) {
         console.log(chalk.green('✔ Semantic search is on (local embeddings)'));
         return;
     }
-    console.log(chalk.dim('Installing semantic search: about 250 MB on Linux, 280 MB on macOS, once for every Rigour version on this machine (skip with --no-semantic)...'));
+    // A person at a terminal says yes before a download this size; a script or CI installs as before (--no-semantic skips it).
+    if (interactive() && !await confirm({ message: `Install semantic search? ${SIZE}, once for every Rigour version on this machine. It lets recall and "is there already a helper for this?" work by meaning.`, default: true })) {
+        console.log(chalk.yellow('Semantic search is off. Recall and pattern matching use keywords until `rigour setup` installs it.'));
+        return;
+    }
+    console.log(chalk.dim(`Installing semantic search: ${SIZE}, once for every Rigour version on this machine (skip with --no-semantic)...`));
     const result = await ensureSemanticRuntime(cwd);
     if (result.state === 'installed' || result.state === 'present')
         console.log(chalk.green('✔ Semantic search is on (local embeddings)'));

package/dist/commands/setup.d.ts

@@ -4,5 +4,9 @@ export interface SetupOptions {
     brief?: boolean;
     team?: boolean;
     instructions?: boolean;
+    /** A team's first week: every gate says what it would have blocked and blocks nothing (report-only.ts). */
+    reportOnly?: boolean;
+    /** Every gate blocks again (clears report-only). */
+    block?: boolean;
 }
 export declare function setupCommand(cwd?: string, options?: SetupOptions): Promise<void>;