@codedology/code-forge 0.7.6 → 0.8.0

package/src/cli/context.mjs

@@ -0,0 +1,175 @@
+/**
+ * `code-forge context pack --run <id> --block <id> [--json]` (block B63a; issue #13 item 5, issue
+ * #10 item 2). Builds the coder context pack of one block from the `context` key of the project's
+ * LIVE `.code-forge.yml` in the main tree (not the run-start snapshot: `context` is not authority)
+ * — see `src/context/pack.mjs` for the sections, the order and the line cap — and writes it to
+ * `<run root>/context/<block>.md`. The run root comes from the run's own config snapshot
+ * (`tmp.root` is fixed for the run), as for the worker. The orchestrator sends the pack's text with
+ * every coder task.
+ *
+ * Prints two lines: the path, then `tokens ~<n>` (the review packets' bytes / 4 estimate); with
+ * `--json` one line `{"path":…,"tokens":…,"lines":…,"cut":…,"sha256":…}`. Each pack written
+ * appends a signed `context.pack {block, path, sha256, tokens, lines, cut}` ledger row — unless
+ * the block's last verified `context.pack` row has the same sha256 and path (same pack: no row,
+ * same output). The ledger is read before anything is written. The new text goes to a temp file
+ * first; the signed row is appended while it is still there, and only then is it renamed over
+ * `<block>.md`. A row that cannot be appended removes only the temp file, so an earlier pack stays
+ * as it was and nothing was written. A rename that fails after the row was appended says so.
+ *
+ * Exit codes: 0 written, 1 refused (no `context` key, a rules or lessons file missing or outside
+ * the repository, a bad `context` value, a control character, an unknown run or block, a file or
+ * ledger write that fails), 2 usage. Never runs any command it lists.
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { assemblePack, ContextError, contextSettings, packTokens, readSources } from '../context/pack.mjs';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
+import { runRootFor } from '../session/spawn.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { configInForce } from '../state/config-snapshot.mjs';
+import { StateError } from '../state/paths.mjs';
+import { readRun, writeSigned } from '../state/run.mjs';
+import { loadKey, verifyRow } from '../state/signer.mjs';
+import { assertBlockId, mainRootOf, WorkerError } from '../worker/ticket.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge context pack --run <id> --block <id> [--json]\n';
+
+/** @param {unknown} err @returns {string} the fs error's code (or message) for a one-line refusal. */
+const fsCode = (err) => /** @type {NodeJS.ErrnoException} */ (err)?.code ?? (err instanceof Error ? err.message : 'error');
+
+/**
+ * @typedef {object} ContextDeps
+ * @property {{write: (s: string) => unknown}} [stdout]
+ * @property {{write: (s: string) => unknown}} [stderr]
+ * @property {(row: Record<string, any>) => Promise<unknown>} [appendRow] - the ledger append
+ *   (default: the project's ledger file).
+ */
+
+/**
+ * The last verified `context.pack` row of this run and block, or null.
+ * @param {string} runId @param {string} slug @param {string} block
+ * @returns {Promise<Record<string, any> | null>}
+ */
+async function lastPackRow(runId, slug, block) {
+  const rows = (await readAllRows(slug)).filter((r) => r?.event === 'context.pack' && r.run === runId && r.block === block);
+  if (rows.length === 0) return null;
+  const key = await loadKey(runId);
+  const valid = rows.filter((r) => verifyRow(r, key).ok);
+  return valid.length > 0 ? valid[valid.length - 1] : null;
+}
+
+/**
+ * @param {string[]} args @param {ContextDeps} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runContext(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const [sub, ...rest] = args;
+  if (sub !== 'pack') {
+    writeSafe(stderr, USAGE);
+    return 2;
+  }
+  try {
+    const { flags, positionals } = parseFlags(rest, { values: ['run', 'block'], booleans: ['json'] });
+    if (positionals.length > 0 || typeof flags.run !== 'string' || typeof flags.block !== 'string') throw new StateError('usage', 'context pack needs --run and --block');
+    const runId = flags.run;
+    let block;
+    try {
+      block = assertBlockId(flags.block);
+    } catch {
+      throw new StateError('usage', `--block: ${JSON.stringify(flags.block)} is not a block id`);
+    }
+    const record = await readRun(runId);
+    const entry = record.blocks?.[block];
+    if (!entry) throw new ContextError('no-block', `run ${runId} has no block ${block}`);
+    // rules and lessons come from the MAIN tree, never from a block worktree; so does the config
+    const repoRoot = await mainRootOf(record.workspace);
+    // only `context` is read LIVE (it is not authority)
+    const loaded = await loadProjectConfig(repoRoot);
+    if (!loaded.ok) throw new ContextError('bad-config', loaded.message);
+    const live = /** @type {Record<string, any>} */ (loaded.config);
+    const settings = contextSettings(live);
+    if (settings === null) throw new ContextError('no-context', 'the config has no context key: add context (rules, lessons, commands, max_lines) to .code-forge.yml');
+    const sources = readSources(repoRoot, settings);
+    const { text, lines, cut } = assemblePack({
+      settings,
+      sources,
+      block: {
+        run: runId,
+        block,
+        level: entry.level ?? null,
+        owned: Array.isArray(entry.owned_files) ? entry.owned_files : [],
+        tests: Array.isArray(entry.test_files) ? entry.test_files : null,
+        worktree: entry.worktree && typeof entry.worktree.path === 'string' ? { path: entry.worktree.path, branch: entry.worktree.branch } : null,
+      },
+    });
+    const sha256 = createHash('sha256').update(text).digest('hex');
+    const tokens = packTokens(text);
+    // the run root from the run's own snapshot (`tmp.root` is fixed for the run, as the worker
+    // made it); a record from before snapshots has none, and the live value is all there is
+    const snapshot = configInForce(record) ?? live;
+    const tmpRoot = typeof snapshot?.tmp?.root === 'string' ? snapshot.tmp.root : undefined;
+    let runRoot;
+    try {
+      runRoot = runRootFor(runId, tmpRoot);
+    } catch (err) {
+      throw new ContextError('no-run-root', `the run root cannot be used (${err instanceof Error ? err.message : 'error'})`);
+    }
+    const dir = path.join(runRoot, 'context');
+    const file = path.join(dir, `${block}.md`);
+    // every ledger read and check happens BEFORE the file is touched: a refusal here writes nothing
+    const last = await lastPackRow(runId, record.project, block);
+    const needsRow = last === null || last.sha256 !== sha256 || last.path !== file;
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeFileSync(tmp, text, { mode: 0o600 });
+    } catch (err) {
+      rmSync(tmp, { force: true });
+      throw new ContextError('write-failed', `cannot write ${file} (${fsCode(err)})`);
+    }
+    // the row first, while the new text is only in the temp file: a failed append leaves the
+    // earlier pack (if any) exactly as it was
+    if (needsRow) {
+      const append = deps.appendRow ?? ((/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project }));
+      try {
+        await writeSigned(runId, append, { event: 'context.pack', block, path: file, sha256, tokens, lines, cut });
+      } catch (err) {
+        rmSync(tmp, { force: true });
+        writeSafe(stderr, `context: the context.pack ledger row could not be written (${err instanceof Error ? err.message : 'error'}); nothing was written\n`);
+        return 1;
+      }
+    }
+    try {
+      renameSync(tmp, file);
+    } catch (err) {
+      rmSync(tmp, { force: true });
+      const after = needsRow ? 'its context.pack ledger row was already written' : 'nothing was written';
+      writeSafe(stderr, `context: cannot write ${file} (${fsCode(err)}); ${after}\n`);
+      return 1;
+    }
+    if (flags.json === true) writeSafe(stdout, `${JSON.stringify({ path: file, tokens, lines, cut, sha256 })}\n`);
+    else writeSafe(stdout, `${file}\ntokens ~${tokens}\n`);
+    return 0;
+  } catch (thrown) {
+    if (thrown instanceof StateError && thrown.code === 'usage') {
+      writeSafe(stderr, `context: ${thrown.message}\n${USAGE}`);
+      return 2;
+    }
+    if (thrown instanceof ContextError || thrown instanceof StateError || thrown instanceof WorkerError) {
+      writeSafe(stderr, `context: ${thrown.message}; nothing was written\n`);
+      return 1;
+    }
+    throw thrown;
+  }
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function context(args) {
+  return runContext(args);
+}

package/src/cli/gates.mjs

@@ -7,7 +7,24 @@
  *   gates detect --cwd <dir>
  *   gates run --cwd <dir> [--slug <slug>] [--timeout-ms <n>] [--run <r> --block <id>]
  *     (with --run/--block the gates run behind the proof lock, `runGatesGuarded`: another block
- *     holding the lock ⇒ `{"result":"proof.busy","holder":…}` and exit 1)
+ *     holding the lock ⇒ `{"result":"proof.busy","holder":…}` and exit 1. B60: a gate argv item
+ *     that is exactly `{test_files}` runs the block's related tests, or is dropped for the full
+ *     suite — over `gates.full_suite_threshold_files` owned files (globs and directories count
+ *     the tracked and new (not ignored) files they cover), no test file known, or no --run/--block (`reason: no_tests`);
+ *     that gate's result and `gate.red` row, and the `gate.done` row, carry `scope: related|full`
+ *     with `test_count` or `reason: threshold|no_tests`, and with --run/--block the rows name `run`
+ *     and `block`. A gate given as `{argv, env}` runs with those variables, shown by name only
+ *     (`env_keys`). code-forge never prints or records an env value. Gate env is not a secret
+ *     store. Child output is masked only for values of 8 or more characters.
+ *     B62b: for a block with a worktree (`proof.isolation: worktree`) the gates run in that tree —
+ *     at the workspace's place in it (`blockTree`) — and `{test_files}` and the threshold count
+ *     the files there. The gates are detected in the tree and configured by the main workspace's
+ *     `.code-forge.yml`. `--cwd` may be left out, or must name the workspace's place in the tree:
+ *     the tree's top level when the workspace is the repository's top level, else the same
+ *     subdirectory of the tree (then the tree's top level is refused too). Any other `--cwd`, and
+ *     any `--cwd=<dir>` argument, is refused (exit 2, nothing run). A tree that is gone, malformed or off its branch is refused
+ *     with exit 1 (the message on stderr, no gate run, no row). The JSON output and the `gate.red` and
+ *     `gate.done` rows then carry `worktree: <tree path>`.)
  *   gates secret-scan --cwd <dir> --file <path> [--file <path> ...]
  *   gates safe-edit --cwd <dir> --base <sha>
  *   gates scope --cwd <dir> --base <sha>
@@ -15,31 +32,39 @@
  *   gates transcript-grep --file <path>
  */
 
+import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { writeSafe, redactJSON } from '../util/redact.mjs';
 import { appendRow } from '../ledger/write.mjs';
 import { loadProjectConfig } from '../config/load.mjs';
 import { detectGates } from '../gates/detect.mjs';
+import { printableGates, thresholdOf } from '../gates/expand.mjs';
 import { runGates } from '../gates/run.mjs';
 import { runGatesGuarded } from '../proof/lock.mjs';
+import { blockTree } from '../proof/worktree.mjs';
+import { readRun } from '../state/run.mjs';
+import { StateError } from '../state/paths.mjs';
 import { scanFiles } from '../gates/secret-scan.mjs';
 import { checkSafeEdit } from '../gates/safe-edit.mjs';
 import { computeFileSet } from '../gates/scope.mjs';
 import { checkAcceptance, parseTapPassed } from '../gates/acceptance.mjs';
 import { checkTranscript } from '../gates/transcript-grep.mjs';
 
+/** B60: the gate env rule, in the same words as the schema and proof.md. */
+const GATE_ENV_RULE = 'code-forge never prints or records an env value. Gate env is not a secret store. Child output is masked only for values of 8 or more characters.';
+
 /**
  * Auto-detected gates (`detectGates`), overridden per-key by an on-disk `.code-forge.yml`'s
  * `gates.{test,lint,types,format}` when that key is explicitly present — a project that already
  * confirmed/edited its gates at `init` step 7 (plan §2 step 7) is authoritative over the table.
  * A missing/unparseable config file is not an error here: detection alone is a valid answer.
  * @param {string} cwd
- * @returns {Promise<import('../gates/detect.mjs').DetectedGates>}
+ * @param {Record<string, any> | null} configured - the config's `gates` section ({@link configuredGates}).
+ * @returns {import('../gates/detect.mjs').DetectedGates}
  */
-async function resolveGates(cwd) {
+function resolveGates(cwd, configured) {
   const detected = detectGates(cwd);
-  const loaded = await loadProjectConfig(cwd);
-  const configured = loaded.ok && loaded.config?.gates && typeof loaded.config.gates === 'object' ? loaded.config.gates : null;
   if (!configured) return detected;
   return {
     stack: detected.stack,
@@ -50,6 +75,16 @@ async function resolveGates(cwd) {
   };
 }
 
+/**
+ * The on-disk `.code-forge.yml`'s `gates` section, or null when there is none (or it does not load).
+ * @param {string} cwd
+ * @returns {Promise<Record<string, any> | null>}
+ */
+async function configuredGates(cwd) {
+  const loaded = await loadProjectConfig(cwd);
+  return loaded.ok && loaded.config?.gates && typeof loaded.config.gates === 'object' ? loaded.config.gates : null;
+}
+
 /**
  * `production.markers`/`production.names` from an on-disk config, merged into the forbidden list
  * `transcript-grep` scans with — absent/unparseable config yields no extra tokens.
@@ -91,7 +126,8 @@ function flagValue(args, flag) {
  * go through `flagValue(...) ?? process.cwd()`, which cannot tell "absent" from "malformed" apart
  * and silently ran gates in the wrong directory for the latter).
  * @param {string[]} args @param {(s: string) => void} err @param {string} label
- * @returns {{ok: true, value: string} | {ok: false}}
+ * `given` says whether `--cwd` was on the command line (`value` is then its value, not the default).
+ * @returns {{ok: true, value: string, given: boolean} | {ok: false}}
  */
 function resolveCwd(args, err, label) {
   const flag = readOptionalFlag(args, '--cwd');
@@ -99,7 +135,7 @@ function resolveCwd(args, err, label) {
     err(`${label}: --cwd requires a value\n`);
     return { ok: false };
   }
-  return { ok: true, value: flag.value ?? process.cwd() };
+  return { ok: true, value: flag.value ?? process.cwd(), given: flag.value !== undefined };
 }
 
 /** @param {string[]} args @param {string} flag @returns {string[]} every value of a repeatable flag. */
@@ -111,6 +147,51 @@ function repeatedFlagValues(args, flag) {
   return values;
 }
 
+/**
+ * B62b: the worktree the block `blockId` of run `runId` works in, with the run's main workspace;
+ * null for a block without one. A run or block that cannot be read is null too: the proof lock
+ * (`runGatesGuarded`) refuses it with its own message.
+ * @param {string} runId @param {string} blockId
+ * @returns {Promise<{tree: import('../proof/worktree.mjs').BlockTree, workspace: string} | null>}
+ * @throws {import('../state/paths.mjs').StateError} a `worktree-*` code when the recorded tree is
+ *   malformed, gone or unusable; the message names the block and run and says no gate was run.
+ */
+async function blockWorktree(runId, blockId) {
+  let record;
+  try {
+    record = await readRun(runId);
+  } catch {
+    return null;
+  }
+  let tree;
+  try {
+    tree = await blockTree(record.workspace, record.blocks?.[blockId]);
+  } catch (thrown) {
+    if (thrown instanceof StateError) throw new StateError(thrown.code, `block ${blockId} of run ${runId}: ${thrown.message}; no gate was run`);
+    throw thrown;
+  }
+  return tree ? { tree, workspace: record.workspace } : null;
+}
+
+/** @param {string} p @returns {string} the realpath of `p`, or `p` resolved when it does not exist. */
+function realOrResolved(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * B60: the scope fields of a `{test_files}` gate's result (`scope` with `test_count` or `reason`),
+ * or none for any other gate.
+ * @param {Record<string, any>} result @returns {Record<string, any>}
+ */
+function scopeOf({ scope, test_count: testCount, reason }) {
+  if (scope === undefined) return {};
+  return scope === 'related' ? { scope, test_count: testCount } : { scope, reason };
+}
+
 /**
  * @param {string[]} args
  * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
@@ -121,7 +202,11 @@ export async function runGatesVerb(args, deps = {}) {
   const out = (/** @type {object} */ value) => writeSafe(stdout, `${redactJSON(value)}\n`);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
   const usage = () =>
-    err('usage: code-forge gates detect|run|secret-scan|safe-edit|scope|acceptance|transcript-grep --cwd <dir> [...]\n');
+    err(
+      'usage: code-forge gates detect|run|secret-scan|safe-edit|scope|acceptance|transcript-grep --cwd <dir> [...]\n' +
+        `  gates run: an argv item exactly {test_files} runs the block's related tests (needs --run and --block); over gates.full_suite_threshold_files owned files, or with no test file known, the full suite runs.\n` +
+        `  gates run: a gate may be {argv, env}. ${GATE_ENV_RULE}\n`,
+    );
 
   const [sub] = args;
 
@@ -129,14 +214,16 @@ export async function runGatesVerb(args, deps = {}) {
     if (sub === 'detect') {
       const cwdArg = resolveCwd(args, err, 'gates detect');
       if (!cwdArg.ok) return 2;
-      out(await resolveGates(cwdArg.value));
+      const gates = resolveGates(cwdArg.value, await configuredGates(cwdArg.value));
+      // B60: a gate given with env is printed with its variable NAMES (`env_keys`), never the values
+      out(printableGates(gates));
       return 0;
     }
 
     if (sub === 'run') {
       const cwdArg = resolveCwd(args, err, 'gates run');
       if (!cwdArg.ok) return 2;
-      const cwd = cwdArg.value;
+      let cwd = cwdArg.value;
 
       const timeoutFlag = readOptionalFlag(args, '--timeout-ms');
       if (!timeoutFlag.ok) {
@@ -165,10 +252,28 @@ export async function runGatesVerb(args, deps = {}) {
         return 2;
       }
 
-      const gates = await resolveGates(cwd);
+      // B62b: a block with a worktree runs its gates in that tree, configured by the main workspace
+      const placed = runFlag.value !== undefined && blockFlag.value !== undefined ? await blockWorktree(runFlag.value, blockFlag.value) : null;
+      if (placed) {
+        // `--cwd=<dir>` is no form of --cwd: for a worktree block it is refused, never ignored
+        const joined = args.find((a) => a.startsWith('--cwd='));
+        if (joined !== undefined) {
+          err(`gates run: block ${blockFlag.value} of run ${runFlag.value} works in its worktree ${placed.tree.workspace}, not in ${joined} — drop it (--cwd=<dir> is not read as --cwd); no gate was run\n`);
+          return 2;
+        }
+        if (cwdArg.given && realOrResolved(cwd) !== realOrResolved(placed.tree.workspace)) {
+          err(`gates run: block ${blockFlag.value} of run ${runFlag.value} works in its worktree ${placed.tree.workspace}, not in --cwd ${cwd} — drop --cwd (or give the worktree); no gate was run\n`);
+          return 2;
+        }
+        cwd = placed.tree.workspace;
+      }
+      const configured = await configuredGates(placed ? placed.workspace : cwd); // loaded once: the gates and the threshold
+      const gates = resolveGates(cwd, configured);
+      const inTree = placed ? { worktree: placed.tree.path } : {};
       let ran;
       if (runFlag.value !== undefined && blockFlag.value !== undefined) {
-        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+        const threshold = thresholdOf(configured?.full_suite_threshold_files);
+        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, threshold, ...(timeoutMs ? { timeoutMs } : {}) });
         if (guarded.result === 'proof.busy') {
           out({ result: 'proof.busy', holder: /** @type {{holder: string}} */ (guarded).holder });
           return 1;
@@ -180,14 +285,19 @@ export async function runGatesVerb(args, deps = {}) {
       const { results, allOk } = ran;
 
       if (slug) {
+        // B60: with --run/--block the rows name the run and the block, so the run's binnacle reads them
+        const owner = runFlag.value !== undefined ? { run: runFlag.value, block: blockFlag.value, ...inTree } : {};
         for (const result of results) {
           if (!result.skipped && !result.ok) {
-            await appendRow({ event: 'gate.red', gate: result.gate, code: result.code }, { slug });
+            await appendRow({ ...owner, event: 'gate.red', gate: result.gate, code: result.code, ...scopeOf(result) }, { slug });
           }
         }
-        await appendRow({ event: 'gate.done', stack: gates.stack, all_ok: allOk }, { slug });
+        // B60: one scope per run (every `{test_files}` gate shares it), named on gate.done too;
+        // without --run/--block that is `scope: full, reason: no_tests`
+        const scoped = results.find((r) => r.scope !== undefined);
+        await appendRow({ ...owner, event: 'gate.done', stack: gates.stack, all_ok: allOk, ...(scoped ? scopeOf(scoped) : {}) }, { slug });
       }
-      out({ stack: gates.stack, results, allOk });
+      out({ stack: gates.stack, ...inTree, results, allOk });
       return allOk ? 0 : 1;
     }
 

package/src/cli/ledger.mjs

@@ -8,18 +8,26 @@
  *   ledger outcome --pr <n> --ci red|green|reverted --slug <slug>
  *   ledger tail --slug <slug> [--n <count> | -n <count>]
  *   ledger add coder --run <r> --block <b> --usd <n> [--note "..."]
+ *   ledger outside-review --run <r> --pr <n> --rounds <n> --findings <n> [--link <url>] [--block <id>]...
  *
  * B33: `ledger add coder` records manual/cloud coder spend (a session code-forge never saw) as a
  * signed `session` row (`role: coder, manual: true, usd, cost_source: manual`) in the run's
  * ledger, so `report` and the `budget.usd` check count it. The slug is the run record's project.
+ *
+ * B66: `ledger outside-review` records the rounds and findings of an outside review of one PR as a
+ * signed `outside_review` row in the run's project ledger (the `report` section `outside_review`
+ * puts it next to the code-forge cost of the PR's blocks). An orchestrator/human verb, never a
+ * coder one. A later call for the same PR replaces the earlier row in every reader.
  */
 
-import { writeSafe } from '../util/redact.mjs';
 import { buildCalibration } from '../ledger/calibration.mjs';
 import { recordCiOutcome, reviewedEntriesFromRows, scanGitAndRecord } from '../ledger/outcome.mjs';
+import { OUTSIDE_REVIEW_EVENT, OUTSIDE_REVIEW_USAGE, outsideReviewRecordedLine, parseOutsideReviewArgs } from '../ledger/outside-review.mjs';
 import { roundUsd, runSpend } from '../ledger/spend.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { readRun, writeSigned } from '../state/run.mjs';
+import { loadKey } from '../state/signer.mjs';
+import { redact, writeSafe } from '../util/redact.mjs';
 
 /**
  * @param {string[]} args @param {string} flag
@@ -63,10 +71,11 @@ export async function runLedger(args, deps = {}) {
   const { stdout = process.stdout, stderr = process.stderr } = deps;
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
-  const usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]  (tail: [--n|-n <count>]) | add coder --run <r> --block <b> --usd <n> [--note "..."]\n');
+  const usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]  (tail: [--n|-n <count>]) | add coder --run <r> --block <b> --usd <n> [--note "..."] | outside-review --run <r> --pr <n> --rounds <n> --findings <n> [--link <url>] [--block <id>]...\n');
 
   const [sub] = args;
   if (sub === 'add') return addSpend(args.slice(1), { out, err });
+  if (sub === 'outside-review') return addOutsideReview(args.slice(1), { out, err });
   const slug = flagValue(args, '--slug');
   if (!slug) {
     usage();
@@ -245,6 +254,41 @@ async function addSpend(args, { out, err }) {
   }
 }
 
+/**
+ * `ledger outside-review --run <r> --pr <n> --rounds <n> --findings <n> [--link <url>]
+ * [--block <id>]...` (B66). Usage errors exit 2, an unknown run or block exits 1; both write nothing.
+ * The run key is loaded (and so registered as a secret) BEFORE the link is redacted.
+ * @param {string[]} args - after `outside-review`.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io
+ * @returns {Promise<number>}
+ */
+async function addOutsideReview(args, { out, err }) {
+  const parsed = parseOutsideReviewArgs(args);
+  if ('message' in parsed) {
+    err(`ledger outside-review: ${parsed.message}\n${OUTSIDE_REVIEW_USAGE}\n`);
+    return 2;
+  }
+  const { run, pr, rounds, findings, link, blocks } = parsed.value;
+  try {
+    const record = await readRun(run);
+    const known = record.blocks && typeof record.blocks === 'object' ? record.blocks : {};
+    const unknown = blocks.find((id) => !Object.hasOwn(known, id));
+    if (unknown !== undefined) {
+      err(`ledger outside-review: block ${JSON.stringify(unknown)} is not a block of run ${run}; nothing written\n`);
+      return 1;
+    }
+    await loadKey(run);
+    const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+    const row = { event: OUTSIDE_REVIEW_EVENT, pr, rounds, findings, link: link === null ? null : redact(link), blocks };
+    await writeSigned(run, writeRow, row);
+    out(outsideReviewRecordedLine(row));
+    return 0;
+  } catch (thrown) {
+    err(`ledger outside-review: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function ledger(args) {
   return runLedger(args);

package/src/cli/proof.mjs

@@ -20,6 +20,13 @@
  * `export` reads `proof.export.{link_dirs,copy_untracked}` from the workspace's `.code-forge.yml`
  * (defaults §1.3) and writes a signed `proof` row `isolation: export`; `lock`/`unlock` write
  * `isolation: lock` rows (B6 writer, B8 signer).
+ *
+ * B62b: for a block with a worktree, `export` and `red-green` read the block's files, the test
+ * and the base in its tree (`blockTree`, against the tree's `base_sha`) and measure in an export
+ * built FROM the tree into the main tree's `.code-forge/export/<block>` — never in the tree, which
+ * is left exactly as it was. The config still comes from the main tree. A recorded tree that is
+ * gone or malformed refuses (exit 1, `…; no proof was run`). `lock`, `unlock`, `restore` and
+ * `export --remove` touch only the run's lock and that export directory, as before.
  */
 
 import { lstat } from 'node:fs/promises';
@@ -35,6 +42,7 @@ import { DEFAULT_COPY_UNTRACKED, DEFAULT_LINK_DIRS, buildExport, exportDirFor, r
 import { acquireProofLock, lockHolder, releaseProofLock } from '../proof/lock.mjs';
 import { MECHANISMS, readJournal, restoreJournal, runRedGreen } from '../proof/red-green.mjs';
 import { tierFor } from '../proof/tiers.mjs';
+import { blockTree } from '../proof/worktree.mjs';
 import { blockFileSet, repoRelativePath } from '../review/gate-check.mjs';
 import { ownsFile } from '../state/registry.mjs';
 
@@ -117,23 +125,53 @@ async function configAt(cwd) {
 }
 
 /**
- * Build the block's measurement export and write its signed `proof` row (`step: export`).
- * @param {{runId: string, record: Record<string, any>, blockId: string, block: Record<string, any>, config: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ * @typedef {object} ProofPlace
+ * @property {string} dir - where the block's files, its test and its base are read: the workspace,
+ *   or the workspace's place in the block's worktree.
+ * @property {string} base - the block's `base_sha`, or its tree's.
+ * @property {string | null} tree - the block's worktree, null without one.
+ */
+
+/**
+ * B62b: where a block's proof is measured. A block without a worktree: the workspace and the
+ * block's base, as before. A block with one: its tree (`blockTree`) and the tree's `base_sha`. A
+ * recorded tree that is gone or malformed refuses (exit 1), as `gates run` does.
+ * @param {string} runId @param {Record<string, any>} record @param {string} blockId @param {Record<string, any>} block
+ * @returns {Promise<ProofPlace>}
+ * @throws {StateError} `worktree-*`
+ */
+async function proofPlace(runId, record, blockId, block) {
+  let wt;
+  try {
+    wt = await blockTree(record.workspace, block);
+  } catch (thrown) {
+    if (thrown instanceof StateError) throw new StateError(thrown.code, `block ${blockId} of run ${runId}: ${thrown.message}; no proof was run`);
+    throw thrown;
+  }
+  return wt === null ? { dir: record.workspace, base: block.base_sha, tree: null } : { dir: wt.workspace, base: wt.base_sha, tree: wt.path };
+}
+
+/**
+ * Build the block's measurement export and write its signed `proof` row (`step: export`). A block
+ * with a worktree is exported FROM its tree, into the main tree's `.code-forge/export/<block>`: the
+ * tree itself is never written to, and its row names it (`worktree`).
+ * @param {{runId: string, record: Record<string, any>, blockId: string, block: Record<string, any>, place: ProofPlace, config: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
  */
-async function exportAndRecord({ runId, record, blockId, block, config, writeRow }) {
+async function exportAndRecord({ runId, record, blockId, block, place, config, writeRow }) {
   const exp = await buildExport({
-    cwd: record.workspace,
+    cwd: place.dir,
     blockId,
-    baseSha: block.base_sha,
+    baseSha: place.base,
     owned: block.owned_files,
     ownedKinds: block.owned_kinds,
     linkDirs: config?.proof?.export?.link_dirs ?? DEFAULT_LINK_DIRS,
     copyUntracked: config?.proof?.export?.copy_untracked ?? DEFAULT_COPY_UNTRACKED,
+    exportRoot: place.tree === null ? undefined : path.dirname(exportDirFor(record.workspace, blockId)),
   });
   await recordProof({
     runId,
     writeRow,
-    row: { block: blockId, isolation: 'export', step: 'export', base_sha: exp.base, restored: exp.restored, untracked: exp.untracked },
+    row: { block: blockId, isolation: 'export', step: 'export', base_sha: exp.base, restored: exp.restored, untracked: exp.untracked, ...(place.tree === null ? {} : { worktree: place.tree }) },
   });
   return exp;
 }
@@ -193,6 +231,9 @@ export async function runProof(args, deps = {}) {
       const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
 
       if (sub === 'lock') {
+        // B62b: a block with its own tree never measures under the lock (see red-green)
+        const recorded = record.blocks?.[blockId]?.worktree;
+        if (recorded !== undefined && recorded !== null) throw new StateError('usage', `block ${blockId} is proven in an export built from its tree; proof lock does not apply`);
         out({ locked: await acquireProofLock({ runId, blockId, writeRow }) });
         return 0;
       }
@@ -210,8 +251,10 @@ export async function runProof(args, deps = {}) {
         return 0;
       }
       const config = await configAt(record.workspace);
-      if (config?.proof?.isolation === 'lock') throw new StateError('isolation-lock', 'proof.isolation is lock — use proof lock instead of an export');
-      out(await exportAndRecord({ runId, record, blockId, block, config, writeRow }));
+      const place = await proofPlace(runId, record, blockId, block);
+      // a block with its own tree is always proven in an export made from it (see red-green)
+      if (place.tree === null && config?.proof?.isolation === 'lock') throw new StateError('isolation-lock', 'proof.isolation is lock — use proof lock instead of an export');
+      out(await exportAndRecord({ runId, record, blockId, block, place, config, writeRow }));
       return 0;
     }
 
@@ -232,17 +275,20 @@ export async function runProof(args, deps = {}) {
       const record = await readRun(runId);
       const block = record.blocks?.[blockId];
       if (block?.status !== 'open') throw new StateError('no-block', `block ${blockId} is not open in run ${runId}`);
-      await assertTestFile(record.workspace, file);
+      const place = await proofPlace(runId, record, blockId, block);
+      await assertTestFile(place.dir, file);
       const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
       const config = await configAt(record.workspace);
-      const isolation = config?.proof?.isolation === 'lock' ? 'lock' : 'export';
+      // A block with its own tree is always proven in an export made from that tree (never in the
+      // tree itself, never under the lock), whatever the config says; otherwise lock or export.
+      const isolation = place.tree !== null ? 'export' : config?.proof?.isolation === 'lock' ? 'lock' : 'export';
       if (isolation === 'lock' && (await lockHolder(runId)) !== blockId) {
         throw new StateError('proof.busy', `proof.isolation is lock — run code-forge proof lock ${blockId} --run ${runId} first`);
       }
       // `revert` puts every changed non-test owned file back to base; `assertion-deletion` touches only the test.
       const changed = await blockFileSet({
-        repoRoot: record.workspace,
-        base: block.base_sha,
+        repoRoot: place.dir,
+        base: place.base,
         owned: block.owned_files,
         matchOwned: (f) => ownsFile(block.owned_files, f, block.owned_kinds),
       });
@@ -250,12 +296,12 @@ export async function runProof(args, deps = {}) {
       if (mechanism === 'revert' && sources.length === 0) {
         throw new StateError('usage', `block ${blockId} changed no non-test source file to revert — use --mechanism assertion-deletion`);
       }
-      const exp = isolation === 'export' ? await exportAndRecord({ runId, record, blockId, block, config, writeRow }) : null;
+      const exp = isolation === 'export' ? await exportAndRecord({ runId, record, blockId, block, place, config, writeRow }) : null;
       if (exp) await assertTestFile(exp.dir, file); // the test must also be where it runs (owned, or tracked at base)
       const result = await runRedGreen({
-        workDir: exp ? exp.dir : record.workspace,
-        repoDir: record.workspace,
-        base: block.base_sha,
+        workDir: exp ? exp.dir : place.dir,
+        repoDir: place.dir,
+        base: place.base,
         argv,
         test: { file, ...(testCase === undefined ? {} : { case: testCase }), characterization: mechanism === 'assertion-deletion' },
         sources,