@codedology/code-forge 0.7.7 → 0.8.0

package/src/gates/owned-count.mjs

@@ -0,0 +1,66 @@
+/**
+ * B60: how many FILES a block owns, for `gates.full_suite_threshold_files`.
+ *
+ * The owned entries are resolved against the workspace's tracked and new (not ignored) files
+ * (`git ls-files -z --cached --others --exclude-standard`, argv only) with the B57
+ * ownership rule (`ownsFile`, state/registry.mjs): a directory entry counts every such file below it, a glob counts its matches, a file counts once. Each file is counted
+ * once however many entries cover it. An entry that covers none of them (a path the block will
+ * create) counts as 1. Outside a git repository every entry counts as 1; any other git failure
+ * (a timeout, a spawn error, git failing inside a repository) gives `Infinity`, so the full suite
+ * runs (`reason: threshold`) rather than a guess.
+ *
+ * {@link countOwnedFiles} is the pure rule; {@link ownedFileCount} reads the files from git.
+ */
+import os from 'node:os';
+import { ownsFile } from '../state/registry.mjs';
+import { exec } from '../util/exec.mjs';
+
+const GIT_TIMEOUT_MS = 30000;
+
+/**
+ * The number of files `owned` covers among `files`, each counted once, plus 1 for every entry
+ * that covers none of them.
+ * @param {ReadonlyArray<string>} owned
+ * @param {ReadonlyArray<string>} tracked - the workspace's files
+ * @param {Record<string, string>} [kinds] - the block's `owned_kinds`
+ * @returns {number}
+ */
+export function countOwnedFiles(owned, tracked, kinds) {
+  const covered = new Set();
+  let notThere = 0;
+  for (const entry of owned) {
+    const hits = tracked.filter((file) => ownsFile([entry], file, kinds));
+    if (hits.length === 0) notThere += 1;
+    for (const file of hits) covered.add(file);
+  }
+  return covered.size + notThere;
+}
+
+/** `process.env` minus every inherited `GIT_*`, with no system/global config, messages in English. */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) env[key] = value;
+  }
+  env.LC_ALL = 'C'; // the "not a git repository" message is matched below
+  return env;
+}
+
+/** The files `git ls-files` lists: tracked (`--cached`) and new, not ignored (`--others --exclude-standard`). */
+const LS_FILES_ARGV = Object.freeze(['git', 'ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+
+/**
+ * {@link countOwnedFiles} over the tracked and new (not ignored) files of the workspace at `cwd`.
+ * Not a git repository: every entry counts 1. Any other failure: `Infinity` (the full suite runs).
+ * @param {string} cwd
+ * @param {ReadonlyArray<string>} owned
+ * @param {Record<string, string>} [kinds]
+ * @returns {Promise<number>}
+ */
+export async function ownedFileCount(cwd, owned, kinds) {
+  const res = await exec([...LS_FILES_ARGV], { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result === 'ok') return countOwnedFiles(owned, res.stdout.split('\0').filter((f) => f.length > 0), kinds);
+  if (!res.timedOut && res.code === 128 && /not a git repository/i.test(res.stderr)) return countOwnedFiles(owned, [], kinds);
+  return Number.POSITIVE_INFINITY;
+}

package/src/gates/run.mjs

@@ -7,10 +7,13 @@
  */
 
 import { exec } from '../util/exec.mjs';
+import { registerSecret } from '../util/redact.mjs';
+import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } from './expand.mjs';
 
 /** @typedef {import('./detect.mjs').Gate} Gate */
 /** @typedef {import('./detect.mjs').GateCommand} GateCommand */
 /** @typedef {import('./detect.mjs').DetectedGates} DetectedGates */
+/** @typedef {import('./expand.mjs').TestScope} TestScope */
 
 /**
  * @typedef {object} GateResult
@@ -22,26 +25,35 @@ import { exec } from '../util/exec.mjs';
  * @property {number | null} code
  * @property {string} stdout
  * @property {string} stderr
+ * @property {'related'|'full'} [scope] - B60: only on a gate whose argv has the `{test_files}` item.
+ * @property {number} [test_count] - B60: with `scope: related`, how many test files it ran.
+ * @property {'threshold'|'no_tests'} [reason] - B60: with `scope: full`, why the item was dropped.
+ * @property {string[]} [env_keys] - B60: only on a gate given with a non-empty `env`: the variable
+ *   NAMES, sorted (the values are never in a result).
  */
 
 /** Fixed run order — always all four, regardless of an earlier one's result. */
 const GATE_ORDER = /** @type {const} */ (['test', 'lint', 'types', 'format']);
 
 /**
- * A gate command is either a plain argv array or `{argv, failOnStdout: true}` (detect.mjs's
- * `GateCommand`, e.g. `gofmt -l` which always exits 0). Normalized here so the run loop below has
- * one shape to deal with.
+ * A gate command is either a plain argv array or `{argv, failOnStdout?, env?}` (detect.mjs's
+ * `GateCommand`: `failOnStdout` for `gofmt -l`, which always exits 0; B60 `env` from the config).
+ * Normalized here so the run loop below has one shape to deal with.
  * @param {GateCommand} command
- * @returns {{argv: string[], failOnStdout: boolean}}
+ * @returns {{argv: string[], failOnStdout: boolean, env: Record<string, string> | null}}
  */
 function normalizeCommand(command) {
-  if (Array.isArray(command)) return { argv: command, failOnStdout: false };
-  return { argv: command.argv, failOnStdout: command.failOnStdout === true };
+  if (Array.isArray(command)) return { argv: command, failOnStdout: false, env: null };
+  return { argv: command.argv, failOnStdout: command.failOnStdout === true, env: envOf(command) }; // `env: {}` is no env
 }
 
 /**
+ * B60: `opts.scope` is the block's {@link TestScope} (`testScope`, gates/expand.mjs); a gate argv
+ * item that is exactly `{test_files}` expands to its files, or is dropped for a full run. Left out,
+ * no test file is known (`scope: full, reason: no_tests`). A gate with `env` runs with those
+ * variables added to the inherited environment; a gate with neither runs exactly as before B60.
  * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate}} gates
- * @param {{cwd: string, timeoutMs?: number}} opts
+ * @param {{cwd: string, timeoutMs?: number, scope?: TestScope}} opts
  * @returns {Promise<{results: GateResult[], allOk: boolean}>}
  */
 export async function runGates(gates, opts) {
@@ -49,24 +61,49 @@ export async function runGates(gates, opts) {
     throw new TypeError('runGates: gates must be an object with test/lint/types/format');
   }
   const { cwd, timeoutMs = 300000 } = opts ?? {};
+  const scope = opts?.scope ?? NO_BLOCK_SCOPE; // null falls back too
   if (typeof cwd !== 'string' || cwd.length === 0) {
     throw new TypeError('runGates: opts.cwd must be a non-empty string');
   }
 
+  // B60: gate env is not a secret store. Its values are never put in a result (only `env_keys`);
+  // a value of 8+ characters is also masked in the child's own output (a shorter one would mask
+  // unrelated text — `MODE=test` vs `npm test`)
+  for (const value of maskableEnvValues(gates)) registerSecret(value);
+  // Every gate is normalized and expanded BEFORE any runs, so a bad gate throws with nothing run.
+  // B60: config validation refuses a gate whose only item is {test_files}; the empty-argv check
+  // is the guard for one that reaches here anyway: it names the gate, not an opaque spawn error.
+  const planned = GATE_ORDER.map((gate) => {
+    const command = gates[gate] ?? null;
+    if (command === null) return { gate, command: null };
+    const normalized = normalizeCommand(command);
+    const { argv, scoped } = expandArgv(normalized.argv, scope);
+    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once '{test_files}' is dropped for the full suite — put the test command before it`);
+    return { gate, command: { argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } };
+  });
   /** @type {GateResult[]} */
   const results = [];
-  for (const gate of GATE_ORDER) {
-    const command = gates[gate] ?? null;
+  for (const { gate, command } of planned) {
     if (command === null) {
       results.push({ gate, argv: null, skipped: true, ok: true, code: null, stdout: '', stderr: '' });
       continue;
     }
-    const { argv, failOnStdout } = normalizeCommand(command);
+    const { argv, scoped, failOnStdout, env } = command;
     // Each command is run and its exit status read on its own — never `&&`-chained with the
     // next, so a red gate is reported red without swallowing the gates that follow it.
-    const res = await exec(argv, { cwd, timeoutMs });
+    const res = await exec(argv, env ? { cwd, timeoutMs, env: { ...process.env, ...env } } : { cwd, timeoutMs });
     const ok = res.result === 'ok' && (!failOnStdout || res.stdout.trim().length === 0);
-    results.push({ gate, argv, skipped: false, ok, code: res.code, stdout: res.stdout, stderr: res.stderr });
+    results.push({
+      gate,
+      argv,
+      skipped: false,
+      ok,
+      code: res.code,
+      stdout: res.stdout,
+      stderr: res.stderr,
+      ...(scoped ? scopeFields(scope) : {}),
+      ...(env ? { env_keys: Object.keys(env).sort() } : {}),
+    });
   }
   return { results, allOk: results.every((r) => r.ok) };
 }

package/src/install/wizard/answers.mjs

@@ -58,8 +58,9 @@ export function linkDirsFromManifests(cwd) {
 
 /**
  * The proof profile is decided from the project, not from the gate detector's stack name alone:
- * `detectGates` (B5) names only `php-pest`, so a Laravel app on PHPUnit reaches here as `node`
- * (its Vite `package.json`) or `unknown` — `composer.json` + `artisan` is Laravel either way.
+ * `detectGates` names a Laravel app `php-pest` or `php-phpunit` only once its runner is installed
+ * (`vendor/bin/…`); before that it reaches here as `node` (its Vite `package.json`) or `unknown` —
+ * `composer.json` + `artisan` is Laravel either way.
  * @param {string} stack - `detectGates().stack`
  * @param {string} cwd
  * @returns {string} the proof profile: `laravel`, `php`, `node`, `python`, `rust`, `go` or `unknown`.
@@ -274,6 +275,11 @@ function gateArgv(gate) {
   return null;
 }
 
+/**
+ * A gate as the config holds it: an argv, `{argv, env}` (B60, kept from an existing config), or none.
+ * @typedef {string[] | {argv: string[], env?: Record<string, string>} | null} GateValue
+ */
+
 /**
  * @typedef {object} Answers
  * @property {'current'|'recommended'} tools
@@ -289,9 +295,13 @@ function gateArgv(gate) {
  * @property {{mode: 'auto'} | {mode: 'ref', ref: string} | {mode: 'none'}} jev
  * @property {string} engine
  * @property {number|null} solo_project
- * @property {{test: string[]|null, lint: string[]|null, types: string[]|null, format: string[]|null}} gates
+ * @property {{test: GateValue, lint: GateValue, types: GateValue, format: GateValue}} gates
  * @property {{high: string[], isolation: string, link_dirs: string[], copy_untracked: string[]}} proof
  * @property {boolean} doctor
+ * @property {boolean} coder_may_push - `autonomy.coder_may_push` (B65; default false).
+ * @property {boolean} coder_may_open_draft_pr - `autonomy.coder_may_open_draft_pr` (B65; default
+ *   false). `resolveAnswers` sets it false whenever `coder_may_push` is false, except for an
+ *   explicit `--coder-may-open-draft-pr yes`, which `runInit` refuses (exit 2): a draft PR needs a push.
  */
 
 /**
@@ -300,10 +310,15 @@ function gateArgv(gate) {
  * @typedef {{gates: Record<string, 'flag'|'existing'|'detected'>, proof: Record<string, 'flag'|'existing'|'detected'|'default'>}} Origins
  */
 
-/** The answer keys in step order. */
+/**
+ * The answer keys in the order they are settled: `askAnswers` asks the two autonomy keys last of
+ * its questions (after `solo_project`); gates and proof come later, in the settings step, and
+ * `doctor` is never asked (only `--skip-doctor` sets it).
+ */
 export const ANSWER_KEYS = Object.freeze([
   'tools', 'yes_tools', 'harnesses', 'scope', 'method', 'provider', 'levels', 'refresh_models',
-  'multimodel', 'second_provider', 'jev', 'engine', 'solo_project', 'gates', 'proof', 'doctor',
+  'multimodel', 'second_provider', 'jev', 'engine', 'solo_project', 'coder_may_push',
+  'coder_may_open_draft_pr', 'gates', 'proof', 'doctor',
 ]);
 
 /**
@@ -382,6 +397,20 @@ export function resolveAnswers(ctx, existing, user, given) {
   set('solo_project', user?.solo?.project_id, () => null);
   if (lastFlag('solo_project')) override('solo_project', lastFlag('solo_project').value);
 
+  // B65: push and draft-PR autonomy default to no; a re-run proposes the existing booleans.
+  const exAutonomy = ex.autonomy && typeof ex.autonomy === 'object' ? ex.autonomy : {};
+  /** @param {unknown} b @returns {boolean|undefined} */
+  const bool = (b) => (typeof b === 'boolean' ? b : undefined);
+  set('coder_may_push', bool(exAutonomy.coder_may_push), () => false);
+  const pushFlag = lastFlag('coder_may_push');
+  if (pushFlag) override('coder_may_push', pushFlag.value);
+  set('coder_may_open_draft_pr', bool(exAutonomy.coder_may_open_draft_pr), () => false);
+  const draftFlag = lastFlag('coder_may_open_draft_pr');
+  if (draftFlag) override('coder_may_open_draft_pr', draftFlag.value);
+  // A draft PR needs a push: with push no, a kept draft-PR yes follows to no. Only an explicit
+  // `--coder-may-open-draft-pr yes` stays true here — `runInit` refuses that combination.
+  if (!v.coder_may_push && sources.coder_may_open_draft_pr !== 'flag') v.coder_may_open_draft_pr = false;
+
   // Gates and proof are never asked (B24): each value comes from a flag, else the existing
   // config, else the project. `origins` records which, per gate and per proof key. A gate the
   // existing config left blank is filled when the project now shows one; a set gate is kept.

package/src/install/wizard/flags.mjs

@@ -6,7 +6,8 @@
  * **Q16 = cut (Ricardo, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
  * v1.2 `--no-nightly` flag is gone and `--proof` takes only the keys the schema still has
  * (`isolation`, `high`, `link_dirs`, `copy_untracked`). With `-g` and `-p` counted as two flags
- * (two tokens that each set the scope answer) there are 19 answer flags.
+ * (two tokens that each set the scope answer) there are 21 answer flags: B65 added
+ * `--coder-may-push` and `--coder-may-open-draft-pr` (`yes`/`no`, default no).
  *
  * Parsing is strict: an unknown flag, a missing value, a repeated single-value flag or a bad value
  * is a usage error. Error messages name the flag, never the value given (a user can paste a key
@@ -46,6 +47,8 @@ export const ANSWER_FLAGS = Object.freeze({
   '--gate': 'gates',
   '--proof': 'proof',
   '--skip-doctor': 'doctor',
+  '--coder-may-push': 'coder_may_push',
+  '--coder-may-open-draft-pr': 'coder_may_open_draft_pr',
 });
 
 const BOOLEAN_FLAGS = new Set(['-g', '-p', '--copy', '--refresh-models', '--no-jev', '--skip-doctor', '--no-interaction']);
@@ -190,6 +193,10 @@ function convert(flag, value) {
       if (argv.length === 0) throw new UsageError('--gate: empty command');
       return { name, argv };
     }
+    case '--coder-may-push':
+    case '--coder-may-open-draft-pr':
+      if (value !== 'yes' && value !== 'no') throw new UsageError(`${flag} must be yes or no`);
+      return value === 'yes';
     case '--proof': {
       const [key, raw] = keyValue('--proof', value);
       if (!PROOF_KEYS.includes(key)) throw new UsageError(`--proof: key must be one of ${PROOF_KEYS.join(', ')}`);

package/src/install/wizard/project-file.mjs

@@ -55,6 +55,8 @@ export function generatedConfig(a, ctx, jevRef) {
     isolation: a.proof.isolation,
     export: { link_dirs: [...a.proof.link_dirs], copy_untracked: [...a.proof.copy_untracked] },
   };
+  // B65: always both keys, also when both are false, so the file states the choice
+  cfg.autonomy = { coder_may_push: a.coder_may_push === true, coder_may_open_draft_pr: a.coder_may_push === true && a.coder_may_open_draft_pr === true };
   return cfg;
 }
 

package/src/install/wizard/run.mjs

@@ -59,6 +59,7 @@ export const USAGE = [
   '  [--harness a,b] [-g|-p] [--copy] [--provider P] [--level Ln=model[:effort][@provider]]…',
   '  [--refresh-models] [--multimodel on|off] [--second-provider P]',
   '  [--jev-ref <item-id|link|op://…> | --jev-env NAME | --no-jev] [--engine auto|solo|harness] [--solo-project N]',
+  '  [--coder-may-push yes|no] [--coder-may-open-draft-pr yes|no]',
   '  [--gate name=cmd]… [--proof isolation=export|lock | high=a,b | link_dirs=a,b | copy_untracked=a,b]… [--skip-doctor]',
 ].join('\n');
 
@@ -230,6 +231,11 @@ export async function runInit(args, deps = {}) {
       ui = deps.ui ?? /** @type {any} */ (await import('@clack/prompts'));
       await askAnswers(values, sources, ctx, ui);
     }
+    // B65: a draft PR needs a push. `resolveAnswers` and `askAnswers` turn a kept draft-PR yes to
+    // no when push is no, so a yes left here came from the flag: refused.
+    if (values.coder_may_open_draft_pr && !values.coder_may_push) {
+      throw new InitFailure(2, '--coder-may-open-draft-pr yes needs autonomy.coder_may_push yes — a draft PR needs a push; pass --coder-may-push yes or drop the flag. Nothing written.');
+    }
 
     // Gates and proof are never asked (B24): the summary says what was found and what is blank.
     // A person sees it now, before anything is written; agent mode gets it in the JSON line.

package/src/install/wizard/steps.mjs

@@ -62,6 +62,8 @@ export const HINTS = Object.freeze({
   judge: 'The judge settles disagreements between the two reviewers.',
   engine: 'auto uses Solo when present, otherwise the subagents of the current harness.',
   solo_project: 'The Solo project that coder processes run in; leave blank for none.',
+  coder_may_push: 'No: the coder hands back its branch and you (or the orchestrator) push it.',
+  coder_may_open_draft_pr: 'Only after an independent review passes; marking it ready and merging stay with you.',
   jev: 'Jev is the small fast classifier behind System 1; skip uses rules only.',
   env: 'That variable must hold the key whenever code-forge runs.',
   paste: 'The key goes to the OS key store; the config keeps only a reference.',
@@ -69,6 +71,10 @@ export const HINTS = Object.freeze({
   apply: 'Only the listed keys change; your other edits stay.',
 });
 
+/** B65: the two autonomy questions, asked last among the answers (default no). */
+export const PUSH_QUESTION = 'May a coder push its block branch on its own?';
+export const DRAFT_PR_QUESTION = 'May a coder open a draft PR on its own?';
+
 /** The one-line hints of the "Customize now" questions, in the order they are asked (B24). */
 export const SETTING_HINTS = Object.freeze({
   test: 'the command that runs your tests; the block cannot close if it fails (blank = no test gate)',
@@ -205,6 +211,16 @@ export async function askAnswers(values, sources, ctx, ui) {
     const typed = await answer(ui, ui.text({ message: withHint('Solo project id (blank: none)', HINTS.solo_project), initialValue: values.solo_project === null ? '' : String(values.solo_project) }));
     values.solo_project = /^[1-9]\d{0,9}$/.test(String(typed).trim()) ? Number(String(typed).trim()) : null;
   }
+  // B65: push first; a draft PR needs a push, so with push no the draft-PR question is not asked
+  // and its answer is no (a `--coder-may-open-draft-pr yes` flag is then refused by `runInit`).
+  if (open('coder_may_push')) {
+    values.coder_may_push = (await answer(ui, ui.confirm({ message: withHint(PUSH_QUESTION, HINTS.coder_may_push), initialValue: values.coder_may_push === true }))) === true;
+  }
+  if (values.coder_may_push && open('coder_may_open_draft_pr')) {
+    values.coder_may_open_draft_pr = (await answer(ui, ui.confirm({ message: withHint(DRAFT_PR_QUESTION, HINTS.coder_may_open_draft_pr), initialValue: values.coder_may_open_draft_pr === true }))) === true;
+  } else if (open('coder_may_open_draft_pr')) {
+    values.coder_may_open_draft_pr = false;
+  }
   return values;
 }
 
@@ -240,16 +256,20 @@ export async function askProjectSettings(values, origins, ui) {
   const changed = [];
   for (const name of GATE_NAMES) {
     if (origins.gates[name] === 'flag') continue;
-    const gates = /** @type {Record<string, string[]|null>} */ (values.gates);
+    const gates = /** @type {Record<string, import('./answers.mjs').GateValue>} */ (values.gates);
     const current = gates[name];
+    // B60: a gate kept as {argv, env} is edited by its argv; its env is kept (and never shown).
+    const currentArgv = /** @type {string[] | null} */ (Array.isArray(current) || !current ? current : current.argv);
     const typed = await answer(ui, ui.text({
       message: withHint(`Gate ${name} (blank or "none": no gate)`, SETTING_HINTS[/** @type {keyof typeof SETTING_HINTS} */ (name)]),
-      initialValue: current ? current.join(' ') : '',
+      initialValue: currentArgv ? currentArgv.join(' ') : '',
     }));
     const text = String(typed ?? '').trim();
+    // blank or "none" turns the gate off: a gate kept as {argv, env} then loses its env too
     const next = text === '' || text === 'none' ? null : shellWords(text);
-    if (JSON.stringify(next) !== JSON.stringify(current)) changed.push(`gates.${name}`);
-    gates[name] = next;
+    if (JSON.stringify(next) === JSON.stringify(currentArgv)) continue;
+    changed.push(`gates.${name}`);
+    gates[name] = next && current && !Array.isArray(current) ? { ...current, argv: next } : next;
   }
   const proof = values.proof;
   /** @param {'high'|'link_dirs'|'copy_untracked'} key @param {string} message @param {string} path */

package/src/install/wizard/summary.mjs

@@ -46,7 +46,10 @@ const STACK_MARKER = Object.freeze({ rust: 'Cargo.toml', python: 'pyproject.toml
 
 /**
  * @typedef {object} Setting
- * @property {unknown} value - what is written to the config.
+ * @property {unknown} value - the value shown (a gate: its argv). The config file is written from
+ *   `values.gates`, not from here, so a `{argv, env}` gate keeps its env.
+ * @property {string[]} [env_keys] - B60: a gate given as `{argv, env}` with a non-empty env: the
+ *   variable NAMES, sorted (never the values).
  * @property {'flag'|'existing'|'detected'|'default'} source
  * @property {string} note - where it came from, or why it is blank, in the summary's words.
  */
@@ -115,7 +118,12 @@ export function summarizeSettings(values, origins, ctx) {
 
   for (const name of GATE_NAMES) {
     const key = SETTING_KEYS[/** @type {keyof typeof SETTING_KEYS} */ (name)];
-    const argv = values.gates[/** @type {keyof typeof values.gates} */ (name)];
+    const command = values.gates[/** @type {keyof typeof values.gates} */ (name)];
+    // B60: a gate given as {argv, env} is summarised by its argv and its env NAMES, never the values;
+    // an empty env counts as none
+    const envKeys = command && !Array.isArray(command) && command.env && Object.keys(command.env).length > 0 ? Object.keys(command.env).sort() : null;
+    const envNote = envKeys ? ` (env: ${envKeys.join(', ')})` : '';
+    const argv = /** @type {string[] | null} */ (Array.isArray(command) || !command ? command : command.argv);
     const source = origins.gates[name] ?? 'detected';
     let note;
     if (argv === null || argv === undefined || argv.length === 0) {
@@ -123,12 +131,12 @@ export function summarizeSettings(values, origins, ctx) {
       else if (source === 'existing') note = 'empty in .code-forge.yml';
       else note = GATE_MISSING[/** @type {keyof typeof GATE_MISSING} */ (name)];
       blank.push(key);
-      lines.push(`  ${name}: blank — ${note}`);
+      lines.push(`  ${name}: blank${envNote} — ${note}`);
     } else {
       note = source === 'detected' ? gateEvidence(ctx.detected.stack, name, argv, ctx.cwd) : keptFrom(source, '--gate');
-      lines.push(`  ${name}: ${shown(argv)} (from ${note})`);
+      lines.push(`  ${name}: ${shown(argv)}${envNote} (from ${note})`);
     }
-    settings[key] = { value: argv, source, note };
+    settings[key] = { value: argv, source, note, ...(envKeys ? { env_keys: envKeys } : {}) };
   }
 
   const found = new Map(linkDirsFromManifests(ctx.cwd).map((e) => [e.dir, e.manifests]));

package/src/ledger/export.mjs

@@ -1,5 +1,5 @@
 /**
- * `report --export <dir>` — writes one JSON file per report section (plan §6.2: "13 sections").
+ * `report --export <dir>` — writes one JSON file per report section (plan §6.2; 14 sections since B66).
  */
 
 import { mkdir, writeFile } from 'node:fs/promises';

package/src/ledger/outside-review.mjs

@@ -0,0 +1,164 @@
+/**
+ * B66 (issue #13 item 8): outside review rounds per PR, next to what code-forge spent on the PR's
+ * blocks. Pure helpers, no I/O:
+ *
+ *  - `parseOutsideReviewArgs` reads `ledger outside-review --run <r> --pr <n> --rounds <n>
+ *    --findings <n> [--link <url>] [--block <id>]…` (the verb in `src/cli/ledger.mjs` does the
+ *    run lookup, the block check, the redaction and the signed write);
+ *  - `buildOutsideReview` builds the `outside_review` report section from the ledger rows and the
+ *    `cost_per_block` entries (`src/ledger/report.mjs` passes them in, so the PR cost is computed
+ *    by the SAME function the `cost_per_block` section uses);
+ *  - `outsideReviewLines` renders the section as terminal text.
+ *
+ * Row: `outside_review {run, pr, rounds, findings, link (or null), blocks: [ids]}`. A later row for
+ * the same PR replaces the earlier one in every reader (the latest row in ledger order wins); the
+ * ledger itself stays append-only.
+ */
+
+import { roundUsd } from './spend.mjs';
+
+export const OUTSIDE_REVIEW_EVENT = 'outside_review';
+
+export const OUTSIDE_REVIEW_USAGE =
+  'usage: code-forge ledger outside-review --run <r> --pr <n> --rounds <n> --findings <n> [--link <url>] [--block <id>]...';
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const POSITIVE_INT = /^[1-9]\d*$/;
+const NON_NEGATIVE_INT = /^(0|[1-9]\d*)$/;
+const LINK = /^https?:\/\/\S+$/;
+const MAX_LINK_CHARS = 2048;
+
+/** @param {unknown} n @returns {boolean} */
+const isCount = (n) => Number.isSafeInteger(n) && /** @type {number} */ (n) >= 0;
+
+const SINGLE_FLAGS = new Set(['--run', '--pr', '--rounds', '--findings', '--link']);
+
+/**
+ * @typedef {{run: string, pr: number, rounds: number, findings: number, link: string | null, blocks: string[]}} OutsideReviewArgs
+ */
+
+/**
+ * @param {string} raw @param {RegExp} shape @returns {number | null}
+ */
+function parseShapedInt(raw, shape) {
+  if (!shape.test(raw)) return null;
+  const n = Number(raw);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/**
+ * Parse the verb's flags (everything after `outside-review`). Every flag but `--block` is given at
+ * most once; `--block` may repeat (duplicates collapsed, first-seen order kept). Any other token,
+ * a flag with no value, a missing required flag or a value of the wrong shape is a usage error.
+ * The link is returned as given — the caller redacts it once the run key is registered.
+ * @param {string[]} args
+ * @returns {{ok: true, value: OutsideReviewArgs} | {ok: false, message: string}}
+ */
+export function parseOutsideReviewArgs(args) {
+  /** @type {Record<string, string>} */
+  const single = {};
+  /** @type {string[]} */
+  const blocks = [];
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    const value = args[i + 1];
+    // the position only, never the token: a stray value (a loose URL) may carry a secret
+    if (flag !== '--block' && !SINGLE_FLAGS.has(flag)) return { ok: false, message: `unknown argument at position ${i + 1}` };
+    if (value === undefined || value.startsWith('--')) return { ok: false, message: `${flag} requires a value` };
+    if (flag === '--block') {
+      if (!blocks.includes(value)) blocks.push(value);
+      continue;
+    }
+    if (Object.hasOwn(single, flag)) return { ok: false, message: `${flag} is given more than once` };
+    single[flag] = value;
+  }
+  for (const flag of ['--run', '--pr', '--rounds', '--findings']) {
+    if (!Object.hasOwn(single, flag)) return { ok: false, message: `${flag} is required` };
+  }
+  const run = single['--run'];
+  if (!RUN_ID.test(run)) return { ok: false, message: '--run must be a run id (letters, digits, ".", "_", "-")' };
+  const pr = parseShapedInt(single['--pr'], POSITIVE_INT);
+  if (pr === null) return { ok: false, message: '--pr must be a positive integer' };
+  const rounds = parseShapedInt(single['--rounds'], NON_NEGATIVE_INT);
+  if (rounds === null) return { ok: false, message: '--rounds must be a non-negative integer' };
+  const findings = parseShapedInt(single['--findings'], NON_NEGATIVE_INT);
+  if (findings === null) return { ok: false, message: '--findings must be a non-negative integer' };
+  let link = null;
+  if (Object.hasOwn(single, '--link')) {
+    link = single['--link'];
+    if (link.length > MAX_LINK_CHARS) return { ok: false, message: `--link is longer than ${MAX_LINK_CHARS} characters` };
+    if (!LINK.test(link)) return { ok: false, message: '--link must be an https:// or http:// URL with no whitespace' };
+  }
+  return { ok: true, value: { run, pr, rounds, findings, link, blocks } };
+}
+
+/** @param {string[]} blocks @returns {string} */
+const blockList = (blocks) => (blocks.length > 0 ? blocks.join(', ') : '-');
+
+/**
+ * The verb's one stdout line.
+ * @param {{pr: number, rounds: number, findings: number, blocks: string[]}} row @returns {string}
+ */
+export function outsideReviewRecordedLine({ pr, rounds, findings, blocks }) {
+  return `outside_review pr ${pr} · rounds ${rounds} · findings ${findings} · blocks ${blockList(blocks)}\n`;
+}
+
+/**
+ * @typedef {{pr: number, rounds: number, findings: number, link: string | null, blocks: string[], code_forge_usd: number, unknown_usd_sessions: number}} OutsideReviewEntry
+ */
+
+/**
+ * The `outside_review` report section: one entry per PR (the latest `outside_review` row for it,
+ * by ledger order), sorted by PR number ascending. `code_forge_usd` sums `totalUsd` of the
+ * `cost_per_block` entries of the row's run whose block the row names; `unknown_usd_sessions` sums
+ * their `unknownUsdSessions` (those sessions count 0 in the dollars). `[]` with no rows.
+ * @param {Array<Record<string, any>>} rows - shadow rows already removed.
+ * @param {Array<{run: string | null, block: string, totalUsd: number, unknownUsdSessions: number}>} costEntries - the `cost_per_block` section.
+ * @returns {OutsideReviewEntry[]}
+ */
+export function buildOutsideReview(rows, costEntries) {
+  /** @type {Map<number, Record<string, any>>} */
+  const latest = new Map();
+  for (const row of rows) {
+    if (row.event !== OUTSIDE_REVIEW_EVENT || !Number.isSafeInteger(row.pr) || row.pr <= 0) continue;
+    // a row whose counts are not 0-or-more safe integers is skipped (the verb never writes one)
+    if (!isCount(row.rounds) || !isCount(row.findings)) continue;
+    latest.set(row.pr, row);
+  }
+  return [...latest.values()]
+    .sort((a, b) => a.pr - b.pr)
+    .map((row) => {
+      const blocks = Array.isArray(row.blocks) ? row.blocks.filter((b) => typeof b === 'string') : [];
+      const run = typeof row.run === 'string' ? row.run : null;
+      // a row with no string run matches no cost entry (never the null-run entries): 0 and 0 unknown
+      const mine = run === null ? [] : costEntries.filter((e) => e.run === run && blocks.includes(e.block));
+      const usd = mine.reduce((sum, e) => sum + e.totalUsd, 0);
+      return {
+        pr: row.pr,
+        rounds: row.rounds,
+        findings: row.findings,
+        link: typeof row.link === 'string' ? row.link : null,
+        blocks,
+        // rounded as `cost_per_block` rounds its dollars (4 decimals)
+        code_forge_usd: roundUsd(usd),
+        unknown_usd_sessions: mine.reduce((sum, e) => sum + e.unknownUsdSessions, 0),
+      };
+    });
+}
+
+/** @param {number} n @param {string} word @returns {string} */
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * Terminal text of the section: `outside review: none` with no entry, else one line per PR.
+ * @param {OutsideReviewEntry[]} section @returns {string}
+ */
+export function outsideReviewLines(section) {
+  if (section.length === 0) return 'outside review: none\n';
+  return section
+    .map((e) => {
+      const unknown = e.unknown_usd_sessions > 0 ? ` (+${e.unknown_usd_sessions} unknown)` : '';
+      return `PR #${e.pr} · ${plural(e.rounds, 'outside round')} · ${plural(e.findings, 'finding')} · code-forge $${e.code_forge_usd.toFixed(2)}${unknown} · ${blockList(e.blocks)}\n`;
+    })
+    .join('');
+}