@codedology/code-forge 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -6,6 +6,33 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.7.7] — 2026-10-11
+
+### Added
+
+- Brief-only mode (B59, issue #13 item 2): run start --mode brief writes a signed run.mode {mode: brief, plan: none}
+  row; the mode is fixed for the run. In a brief run, block open without --level takes the lane from the rules
+  (fallbackLane) over the owned entries, --lines and proof.tiers.high.paths of the run config snapshot, and writes a
+  signed decision row {question: lane, source: rules, facts} before dispatch; an explicit --level wins. report prints
+  the mode of each run in its text output (not in --json or --export). --mode plan or no flag keeps the old behaviour.
+
+## [0.7.6] — 2026-10-11
+
+### Added
+
+- review.external {required, name} (B58, issue #11): an owner-approved outside reviewer replaces the local per-file
+  review. Read only from the run-start config snapshot (run reload refuses to change it; run start refuses required:
+  true without a name) and signed as a review.external row; block close then skips the per-file review check (also
+  not_approved) and writes a signed gate.reviews_waived {by: config, reviewer} row just before block.close, only when
+  the block closes, with no TTY and under autopilot. Unowned, proof, no_changes, transcript, orphans and closeBlock
+  checks still refuse. block open and block claim refuse an owned entry that covers .code-forge.yml. Without the key
+  nothing changes.
+
+### Changed
+
+- block open, block claim and block close now read the run's config snapshot; a snapshot that does not match its hash
+  refuses them with config-snapshot, with or without review.external (B58).
+
 ## [0.7.5] — 2026-10-08
 
 ### Fixed

package/README.md

@@ -12,6 +12,21 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 
 Next release:
 
+- **Work from a brief, with no plan.** `run start --mode brief` marks the run as brief-only.
+  Then `block open` without `--level` picks the lane from the rules: the owned files,
+  `--lines` and `proof.tiers.high.paths`. A signed `decision` row records it with
+  `source: rules`. `--level` still wins, and `report` shows the mode of each run.
+
+In 0.7.6:
+
+- **An outside reviewer can replace the local review.** Set `review.external: {required: true,
+  name: <reviewer>}` in `.code-forge.yml`. `block close` then skips the per-file review check
+  and writes a signed `gate.reviews_waived` row with `by: config`. It needs no TTY and works
+  under autopilot. All other close checks still run. The key is fixed at `run start`, and a
+  coder can never own `.code-forge.yml`.
+
+In 0.7.5:
+
 - **An owned directory owns the files inside it, everywhere.** A block that owns `src/feature`
   now owns `src/feature/a.swift` for `block open`, `block claim`, `block rebase`, the scope gate,
   proof and the review worker, not only for `block close`. `block open` refuses a second block

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 60,
+  "block_count": 62,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -823,6 +823,33 @@
         "B56"
       ],
       "note": "root-added 2026-10-08; found while fixing GitHub issue #2 (B52); also amends src/state/{registry,block}.mjs, src/review/gate-check.mjs, src/cli/{block,proof,plan}.mjs, src/proof/{export,tiers}.mjs, src/worker/engine.mjs, src/session/plan-check.mjs, tests, docs/how-it-works.md, skill/references/code.md"
+    },
+    "B58": {
+      "title": "Outside reviewer (issue #11, #13 item 1): config key review.external {required, name}, read only from the run-start config snapshot (immutable, run reload refuses it), signed review.external row at run start; block close skips the per-file review check and writes a signed gate.reviews_waived {by: config, reviewer} row just before block.close, only when the block closes; unowned, proof, no_changes, transcript and closeBlock checks still refuse; block open and block claim refuse an owned entry that covers .code-forge.yml; run start refuses required: true without a name",
+      "wave": 13,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/review/external.test.mjs"
+      ],
+      "depends_on": [
+        "B57"
+      ],
+      "note": "root-added 2026-10-11; GitHub issue #13 adoption plan (plans/adoption-13/plan.md); also amends src/state/{config-snapshot,run,block}.mjs, src/cli/block.mjs, schema/code-forge.schema.json, docs/reference/config.md, docs/{how-it-works,concepts}.md, skill/references/{review,decisions,code}.md, test/config/schema-coverage.test.mjs"
+    },
+    "B59": {
+      "title": "Brief-only mode (issue #13 item 2): run start --mode brief writes a signed run.mode {mode: brief, plan: none} row and stores the mode (fixed for the run); in a brief run block open without --level takes the lane from fallbackLane over facts built from the owned entries, --lines and proof.tiers.high.paths of the run config snapshot (src/decide/lane-facts.mjs) and writes a signed decision row {question: lane, source: rules, facts} before dispatch; an explicit --level wins; outside brief mode nothing changes; report prints the run mode per run in its text output (not a 14th section); no task verb",
+      "wave": 13,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "src/decide/lane-facts.mjs",
+        "test/state/brief-mode.test.mjs"
+      ],
+      "depends_on": [
+        "B58"
+      ],
+      "note": "root-added 2026-10-11; GitHub issue #13 adoption plan (plans/adoption-13/plan.md); also amends src/state/{run,block,config-snapshot}.mjs, src/cli/{run,block,report}.mjs, src/ledger/report.mjs, src/review/engine.mjs (shared migration/policy path checks), docs/{how-it-works,concepts}.md, skill/SKILL.md, skill/references/plan.md"
     }
   }
 }

package/docs/reference/config.md

@@ -117,6 +117,9 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.provider_concurrency.openai` | integer |  | `2` | min 1 |
 | `review.provider_concurrency.xai` | integer |  | `2` | min 1 |
 | `review.parallel_tickets` | integer |  | `3` | min 1; max 16; B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap. |
+| `review.external` | object |  | — |  |
+| `review.external.required` | boolean |  | `false` | B58: true ⇒ block close skips the local per-file review checks (and the --report ticket check), with no terminal and under autopilot, and writes a signed gate.reviews_waived {by: config} row. Unowned changes, proof, no_changes and the transcript grep still refuse. No block may own .code-forge.yml. |
+| `review.external.name` | string |  | — | minLength 1; B58: the outside reviewer, written in the review.external and gate.reviews_waived rows. Required when required is true: run start refuses a missing or blank name. |
 | `engine` | enum: `auto`, `solo`, `harness`, `subprocess` |  | `"auto"` |  |
 | `harnesses` | array<string> |  | — |  |
 | `harness` | object |  | — |  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/schema/code-forge.schema.json

@@ -153,7 +153,16 @@
             "xai": { "type": "integer", "minimum": 1, "default": 2 }
           }
         },
-        "parallel_tickets": { "type": "integer", "minimum": 1, "maximum": 16, "default": 3, "description": "B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap." }
+        "parallel_tickets": { "type": "integer", "minimum": 1, "maximum": 16, "default": 3, "description": "B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap." },
+        "external": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "B58: an outside reviewer reviews each block. Set it before run start; run reload refuses to add, remove or change it.",
+          "properties": {
+            "required": { "type": "boolean", "default": false, "description": "B58: true ⇒ block close skips the local per-file review checks (and the --report ticket check), with no terminal and under autopilot, and writes a signed gate.reviews_waived {by: config} row. Unowned changes, proof, no_changes and the transcript grep still refuse. No block may own .code-forge.yml." },
+            "name": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "B58: the outside reviewer, written in the review.external and gate.reviews_waived rows. Required when required is true: run start refuses a missing or blank name." }
+          }
+        }
       }
     },
     "engine": { "type": "string", "enum": ["auto", "solo", "harness", "subprocess"], "default": "auto" },

package/skill/SKILL.md

@@ -11,7 +11,7 @@ You are the **orchestrator**: the session that invoked this skill. You dispatch,
 
 1. `forge validate` — exit 0, or stop and show the refusal (it names the key, never the value).
 2. `forge doctor --quick` — config, links, key resolution. On the first run of a day run `forge doctor` in full and read its `engine` row and its `signer: same-user boundary only` row (`references/security.md`).
-3. `forge run start` — prints `run <id> started · engine <e> · worker pid <n>`. The engine is `solo`, `harness` or `subprocess` (`engine: auto` picks; `subprocess` only by explicit config). No engine ⇒ the four-line stop text in `references/degraded.md` §1 is printed and you stop. Keep `<id>`: every later verb takes `--run <id>`.
+3. `forge run start` — prints `run <id> started · engine <e> · worker pid <n>`. The engine is `solo`, `harness` or `subprocess` (`engine: auto` picks; `subprocess` only by explicit config). No engine ⇒ the four-line stop text in `references/degraded.md` §1 is printed and you stop. Keep `<id>`: every later verb takes `--run <id>`. A small change with briefs and no plan starts with `forge run start --mode brief` instead (`references/plan.md` §6); the mode is fixed for the run.
 4. When the engine is not `solo`, print the banner of `references/degraded.md` §2 once.
 
 ## §1 Invocation and state

package/skill/references/code.md

@@ -10,7 +10,7 @@ The coder then forecasts **cases** (tests) and **lines**. Compute the floor your
 
 ## §3 Dispatch — what the brief contains
 
-`forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> --brief <file> [--attempt <n>] [--base <sha>] [--kind code|docs|contract] --lines <n>` records the base sha, the owned files (overlap with another active block ⇒ refused; an owned entry with no glob character — `*`, `?`, `{` — owns that path and every path below it, so `src/feature` owns `src/feature/a.swift` but not `src/featureX/a.swift`, and `src/feature` overlaps `src/feature/x.swift` or `src` in another block — unless the entry is a regular file in the workspace at `block open` (or `block claim`): then it owns only itself, recorded as `owned_kinds`, and every later check reads that answer; a glob owns what it matches, and a brace entry `src/{a,b}` is a glob, so `src/a` owns nothing below it; no trailing `/`), the block kind (declared, else detected — `decisions.md` §5), the level (a docs/contract block below `levels.coder_floor_docs`, default L1, is raised to it and the CLI prints the floor), the clauses with their test ids and the forecast, writes the ledger `dispatch` row and prints the pointer `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>` (≤ 200 B). Call it before every spawn, in every engine. A docs block that owns a glob (`docs/**`) must declare `--kind docs`: a glob is judged by its literal ending, so undeclared it counts as `code`. The brief file carries, in this order:
+`forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> --brief <file> [--attempt <n>] [--base <sha>] [--kind code|docs|contract] --lines <n>` records the base sha, the owned files (overlap with another active block ⇒ refused; an owned entry with no glob character — `*`, `?`, `{` — owns that path and every path below it, so `src/feature` owns `src/feature/a.swift` but not `src/featureX/a.swift`, and `src/feature` overlaps `src/feature/x.swift` or `src` in another block — unless the entry is a regular file in the workspace at `block open` (or `block claim`): then it owns only itself, recorded as `owned_kinds`, and every later check reads that answer; a glob owns what it matches, and a brace entry `src/{a,b}` is a glob, so `src/a` owns nothing below it; no trailing `/`), the block kind (declared, else detected — `decisions.md` §5), the level (a docs/contract block below `levels.coder_floor_docs`, default L1, is raised to it and the CLI prints the floor), the clauses with their test ids and the forecast, writes the ledger `dispatch` row and prints the pointer `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>` (≤ 200 B). Call it before every spawn, in every engine. `--level` may be left out only in a brief-mode run (`plan.md` §6: the rules pick the lane from the owned entries, `--lines` and `proof.tiers.high.paths`, and a signed `decision` row with `source: rules` records it) or when autopilot recorded a level; otherwise its absence is a usage error. A docs block that owns a glob (`docs/**`) must declare `--kind docs`: a glob is judged by its literal ending, so undeclared it counts as `code`. The brief file carries, in this order:
 
 1. `id`, `title`, the level, `owned_files` ("edit ONLY these"), the acceptance clauses with test ids, `test_command`.
 2. The reply contract: `ACK <sha8> lines=<n>` before any tool call; the facts diff; the forecast.
@@ -41,7 +41,7 @@ The coder's report is a claim sheet. The gate reproduces each number in the meas
 | rows genuine | the MAC of every gate-relevant row verifies; the live worker matches the pinned pid |
 | nothing left open | no unruled `late_findings` (a ruling clears only a warning or nit ruled `nit`; a critical late finding needs the human's waiver); no file at `review_cap` without a signed `review.waived` row |
 
-`--no-require-reviews` is the human's way out, written as its own audit row. The human runs it themselves at a terminal: it asks for a yes, has no `--yes`, exits 2 unless stdin and stdout are both terminals, lifts `no_changes` and is refused while an autopilot grant is active — so never run it for them; tell them the command when they say so in chat. A finding counts only under the gate's own configuration; a tautology (an expected value computed by the code under test) is a finding. Reproduce disclosures: a coder that reports its own rule break did the hard part.
+`--no-require-reviews` is the human's way out, written as its own audit row. The human runs it themselves at a terminal: it asks for a yes, has no `--yes`, exits 2 unless stdin and stdout are both terminals, lifts `no_changes` and is refused while an autopilot grant is active — so never run it for them; tell them the command when they say so in chat. The owner's other way out is `review.external` in the config before `run start` (`review.md` §1): the gate then skips the review rows and the report's ticket ids and writes `gate.reviews_waived {by: config}`; every other check, `no_changes` included, still applies. A finding counts only under the gate's own configuration; a tautology (an expected value computed by the code under test) is a finding. Reproduce disclosures: a coder that reports its own rule break did the hard part.
 
 ## §6 Budget — the stop is the feature (R6)
 

package/skill/references/decisions.md

@@ -50,6 +50,6 @@ A fresh L3 session receives the failure evidence — the last attempt's diff, th
 
 ## §7 What reaches the human
 
-`next = stop`, `review.over_budget`, an orphan file or `unowned_change`, a `not_approved` critical finding, `--no-require-reviews`, `worker_down`, `review_cap`, `redecompose`, `ask_human`, a security question, consensus unavailable, and one budget raise per run. Everything else is decided by S1, S2 or the rules above and recorded. A change to a rule, limit or check is never decided here: it always reaches the owner (`rules-core.md` R17).
+`next = stop`, `review.over_budget`, an orphan file or `unowned_change`, a `not_approved` critical finding, `--no-require-reviews`, `worker_down`, `review_cap`, `redecompose`, `ask_human`, a security question, consensus unavailable, and one budget raise per run. The owner has two ways out of the per-file review gate: `--no-require-reviews` at a terminal, or `review.external.required: true` with the outside reviewer's `name`, set in `.code-forge.yml` before `run start` (`review.md` §1). You never choose either one. Everything else is decided by S1, S2 or the rules above and recorded. A change to a rule, limit or check is never decided here: it always reaches the owner (`rules-core.md` R17).
 
 **Autopilot:** while a grant is active, a warning or nit waiver, one extra round at `review_cap` and a coder level go first to the delegate (`forge autopilot ask`, then `forge autopilot waive|round|level --decision <id>` only when it acted, `autopilot.md` §2). Never delegated: `next = stop`, `ask_human`, a security question, a critical finding, a budget raise, `redecompose` — they wait for the owner (`autopilot.md` §5).

package/skill/references/ledger.md

@@ -4,7 +4,7 @@
 
 Every row has the run, the block, the event and a timestamp; the ones the block gate relies on carry `mac` (`security.md` §3). Useful fields: `level`, `provider`, `model`, `effort`, `fallback_step` (every spawn), `role ∈ {coder, reviewer, judge, s2, author, facts}`, `trigger` (escalations), `source ∈ {jev, rules, s2, s2-fallback, shadow}` (decisions), `depth_unconstrained` / `depth_chosen` / `degrade_step` and `context_mode ∈ {whole, hunks, minimal, recheck}` (reviews), `round` and `kind ∈ {full, recheck, patch_check, sweep}` (rounds), `isolation ∈ {export, lock}` (proof), `l3_patch`, `l3_fallback`, `overspend`. **Tokens are facts, dollars are estimates**: `tokens_source: reported` when the CLI's JSON carries usage, else `estimated`. File paths in rows are relative to the repository root.
 
-Events you will read most: `run.start`, `run.stop {reason}`, `run.end`, `dispatch`, `gate.red`, `review.plan`, `review.round`, `review.done`, `review.approved`, `review.unavailable {reason}`, `review.late_finding`, `review.waived {by: human}`, `review.budget`, `forecast.cases_exceeded`, `proof`, `outcome`, `block.rebase`, `block.orphan`, `ledger.tamper`, `worker.replaced`, `facts.built`, `tmp.swept`.
+Events you will read most: `run.start`, `run.mode {mode: brief, plan: none}` (a brief-mode run, `plan.md` §6), `review.external {required, reviewer}` (the owner's outside reviewer, `review.md`), `run.stop {reason}`, `run.end`, `dispatch`, `gate.red`, `review.plan`, `review.round`, `review.done`, `review.approved`, `review.unavailable {reason}`, `review.late_finding`, `review.waived {by: human}`, `gate.reviews_waived {by: human | config}` (`by: config` from `review.external`), `decision {question: lane, source: rules}` (a brief-mode `block open` without `--level`), `review.budget`, `forecast.cases_exceeded`, `proof`, `outcome`, `block.rebase`, `block.orphan`, `ledger.tamper`, `worker.replaced`, `facts.built`, `tmp.swept`.
 
 ## §2 `forge report --slug <slug> [--json] [--export <dir>]`
 

package/skill/references/plan.md

@@ -52,3 +52,15 @@ Never treat a chat summary of the plan as the approval step, and never start `fo
 ## §5 Cost
 
 One L0 session per plan for the facts (typically a claim list of 40–80 items) and one L3 session per author round; `forge report --slug <slug>` shows both as `facts $` and coder/review splits.
+
+## §6 Brief mode — briefs, no plan
+
+For a small change whose blocks are clear from their briefs (a fix, a doc pass, one or two blocks with no ordering to argue about), skip §0–§4: `forge run start --mode brief`. The run record stores `mode: brief` and the ledger gets one signed `run.mode {mode: brief, plan: none}` row right after `run.start`; the mode is fixed for the run (`run reload` never changes it) and `forge report` lists each run as `brief` or `plan`. Plan mode (`--mode plan`, or no flag) is the default and is unchanged. There is no separate verb for a task: each block is still `forge block open` with its brief, owned files and acceptance clauses, and is closed by the same gate.
+
+In a brief-mode run `forge block open <id> --run <r> --owned <paths…> --acceptance <file> --brief <file> --lines <n>` may leave out `--level`: the lane then comes from the deterministic rules (the `--rules` fallback of `jev ask lane`), over these facts only —
+
+- an owned entry under `proof.tiers.high.paths` of the run's config snapshot (or a directory entry above one), a migration path, or a policy/middleware path ⇒ `L2`;
+- else more than 4 owned entries or more than 200 estimated changed lines (`--lines`) ⇒ `L1`;
+- else `L0` (a docs or contract block is still raised to `levels.coder_floor_docs`).
+
+`block open` writes one signed `decision {question: lane, answer: <lane>, source: rules}` row naming the block, then the `dispatch` row, and prints `(rules lane)` after the level. An explicit `--level` still wins and writes no decision row. Give `--lines` whenever you can: without it the size rule sees only the number of owned entries. Outside brief mode a missing `--level` with no autopilot level stays a usage error, and `--lines` stays the forecast it always was.

package/skill/references/review.md

@@ -4,6 +4,8 @@
 
 `forge review-file <path> --block <id> --run <r>` enqueues a ticket and returns `{ticket, status: queued}` in under a second; `forge review-file --wait <ticket> [--max 90s]` polls it. The worker computes the diff itself against the base sha `forge block open` recorded: tracked changes plus untracked files, filtered by `owned_files` for the review and unfiltered for the scope check. A coder that never calls `review-file` gains nothing: the block gate refuses any changed or new file without a signed `review.approved` row for its final content hash. The reviewer is always a new OS process (R1, R10) — identical under Solo, a harness subagent, a detached CLI process, or a human typing.
 
+**The owner's two ways out of the per-file review.** (1) `forge block close <id> --no-require-reviews`, typed by the owner at a terminal (`code.md` §5). (2) `review.external: {required: true, name: <reviewer>}` in `.code-forge.yml`, set before `run start`, when an outside reviewer reviews each block (B58). With `required: true`, `run start` refuses a missing or blank `name`, and writes a signed `review.external` row with the reviewer's name. `run reload` refuses to add, remove or change the key. With the key, `block close` does not check the review rows (a `not_approved` file included) or the report's ticket ids, needs no terminal and works under an autopilot grant. When the block closes, it writes a signed `gate.reviews_waived {by: config, reviewer}` row just before `block.close`; a refused close writes no such row. Unowned changes, `unproven`, `no_changes`, the transcript grep and the registry's orphans still refuse. No block may own `.code-forge.yml` while the key is on: `block open` and `block claim` refuse it. `block open`, `block claim` and `block close` read the run's config snapshot to find the key, so a snapshot that does not match its hash refuses them with `config-snapshot`, with or without the key. Never set or remove the key yourself: it is the owner's decision.
+
 ## §2 Depth by risk (adaptive mode)
 
 The topology is decided in one place (`planSessions`). Consensus (§6) runs only when `review.multimodel` is on **and** the file's risk is above `review.single_reviewer_max_risk` (default 1) **and** the block is not a `docs`/`contract` block (`decisions.md` §5) unless `review.multimodel_for_docs` is true (default false). Everything else is adaptive, below. Why: a consensus review of a four-file docs block cost $16.70 — review cost dominates, and a low-risk file gains nothing from a second provider.

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.7.5"
+PINNED_VERSION="0.7.7"
 set -eu
 
 self="$0"

package/src/cli/block.mjs

@@ -50,11 +50,28 @@
  * FAILED: no review-file ticket id for <files>` (skipped under `--no-require-reviews`, the human's
  * way out). It runs after the review rows and reuses their file set (listed once).
  *
+ * B58 (issue #11): `review.external.required: true` in the run's config snapshot (the owner set it
+ * before `run start`; `run reload` refuses to change it) is the owner's non-interactive way out
+ * when an outside reviewer reviews the block: the per-file review checks and the `--report` ticket
+ * check are skipped, with no TTY and under an active autopilot grant, and a signed
+ * `gate.reviews_waived {by: config, reviewer: <name>}` row is written just before `block.close`,
+ * only when the block closes. Everything
+ * else still refuses — `unowned_change`, `unproven`, `no_changes`, the transcript grep and
+ * `closeBlock`'s own rows. With `--no-require-reviews` the human path runs exactly as without the key.
+ *
  * B47: `block open` without `--level` takes the level `autopilot level` chose for the block (the
  * latest `autopilot.level` row of the run for it whose MAC verifies, `autopilotLevel`); with
  * neither it is a usage error (`no --level given and no autopilot level recorded for <id>`). An
  * explicit `--level` always wins; a repeated or valueless `--level` is a usage error as before.
  *
+ * B59: in a brief-mode run (`run start --mode brief`), `block open` without `--level` takes the
+ * lane from the §3.5 rules (`fallbackLane`) over facts built from the owned entries, `--lines`
+ * (estimated changed lines) and `proof.tiers.high.paths` of the run's config snapshot
+ * (`laneFacts`), and writes one signed `decision {question: lane, source: rules}` row naming the
+ * block, then the `dispatch` row (`openBlock`; neither when the open is refused). An explicit
+ * `--level` still wins, with no decision row. Outside brief mode `--lines` stays the forecast it
+ * always was, and no `--level` without an autopilot level is the usage error above.
+ *
  * `--acceptance` is a YAML/JSON list of `{clause, tests: [test ids…]}`. `block close` runs B8's
  * rows of the gate (worker pin, MACs, orphans); the gate rows owned by later blocks join it
  * through `closeBlock`'s `extraChecks`.
@@ -64,9 +81,12 @@ import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYAML } from 'yaml';
 import { approvalCheckText, expiryChecks } from '../autopilot/limits.mjs';
+import { fallbackLane } from '../decide/fallback-rules.mjs';
+import { laneFacts } from '../decide/lane-facts.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { attemptBlock, claimPath, closeBlock, openBlock, rebaseBlock, repoTop, stopBlock } from '../state/block.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { configInForce, externalReviewer } 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';
@@ -131,8 +151,25 @@ export async function runBlock(args, deps = {}) {
     }
 
     if (sub === 'open') {
-      // B47: no --level ⇒ the level autopilot chose for the block (a signed autopilot.level row)
-      const level = typeof flags.level === 'string' ? flags.level : await autopilotLevel(runId, id, record);
+      // an explicit --level wins; B59: else in a brief-mode run the rules lane; B47: else the level
+      // autopilot chose for the block (a signed autopilot.level row)
+      /** @type {{lane: string, facts: ReturnType<typeof laneFacts>} | null} */
+      let rules = null;
+      /** @type {string | null} */
+      let level;
+      // B59: only the rules lane parses --lines this early; every other open parses it where it
+      // always was (after the level check and --attempt), so its errors keep their pre-B59 order
+      /** @type {number | null | undefined} */
+      let lines;
+      if (typeof flags.level === 'string') {
+        level = flags.level;
+      } else if (record.mode === 'brief') {
+        lines = intFlag(flags.lines, 'lines') ?? null;
+        rules = rulesLane(record, /** @type {string[]} */ (flags.owned), lines);
+        level = rules.lane;
+      } else {
+        level = await autopilotLevel(runId, id, record);
+      }
       if (level === null) throw new StateError('usage', `no --level given and no autopilot level recorded for ${id}`);
       const acceptance = parseYAML(await readFile(/** @type {string} */ (flags.acceptance), 'utf8'), { prettyErrors: false });
       let brief;
@@ -150,14 +187,15 @@ export async function runBlock(args, deps = {}) {
         acceptance,
         attempt: intFlag(flags.attempt, 'attempt'),
         base: typeof flags.base === 'string' ? flags.base : undefined,
-        lines: intFlag(flags.lines, 'lines') ?? null,
+        lines: lines === undefined ? (intFlag(flags.lines, 'lines') ?? null) : lines,
         brief,
+        ...(rules ? { decision: { question: 'lane', answer: rules.lane, source: 'rules', facts: rules.facts } } : {}),
         ...(typeof flags.kind === 'string' ? { kind: flags.kind } : {}),
         cfg: await openConfig(record.workspace),
         writeRow,
       });
       const raised = block.level !== level ? ` (${block.kind} floor, asked ${level})` : '';
-      const chosen = typeof flags.level === 'string' ? '' : ' (autopilot level)';
+      const chosen = typeof flags.level === 'string' ? '' : rules ? ' (rules lane)' : ' (autopilot level)';
       out(`block ${id} open · ${block.level}${raised}${chosen} · ${block.kind} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}\n`);
       out(`${pointer ?? 'brief: none given (--brief <file>)'}\n`);
       return 0;
@@ -201,6 +239,9 @@ export async function runBlock(args, deps = {}) {
           return 1;
         }
       }
+      // B58: the owner's other way out — `review.external.required` in the run's config snapshot
+      // (set before `run start`, immutable): no TTY, allowed under autopilot, the human flag wins
+      const external = reviewsWaived ? null : externalReviewer(record);
       const rows = (await readAllRows(record.project)).filter((row) => row.run === runId);
       // B52: ONE path base and ONE listing, memoised as a promise and shared by every check. The
       // base is the repository top level: the worker signs every review row with a repo-root-
@@ -265,8 +306,9 @@ export async function runBlock(args, deps = {}) {
           unowned: scope?.unowned ?? [],
           // B52: an old ledger's review.result rows are judged by their signed result files
           resultFiles: await resultFilesFor({ repoRoot: top, runId, block: id, rows }),
-          files: reviewsWaived ? [] : fileSet,
-          // B52: nothing changed and nothing reviewed is never a pass (the owner's way out is --no-require-reviews)
+          files: reviewsWaived || external !== null ? [] : fileSet,
+          // B52: nothing changed and nothing reviewed is never a pass (the owner's way out is
+          // --no-require-reviews); B58: `review.external` does not lift it
           noChanges: !reviewsWaived && fileSet.length === 0,
           // B20: high-tier files need a proven red→green row; `--no-require-reviews` does not lift it
           proofFiles: fileSet,
@@ -275,7 +317,7 @@ export async function runBlock(args, deps = {}) {
       });
       // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
       const report = async () => {
-        if (typeof flags.report !== 'string' || reviewsWaived) return { ok: true };
+        if (typeof flags.report !== 'string' || reviewsWaived || external !== null) return { ok: true };
         let text;
         try {
           text = await readFile(flags.report, 'utf8');
@@ -286,7 +328,10 @@ export async function runBlock(args, deps = {}) {
         const missing = missingReviewTickets(text, fileSet.map((f) => f.file));
         return missing.length === 0 ? { ok: true } : { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
       };
-      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews, report] });
+      // B58: the config waiver row is written by `closeBlock` under the run lock, just before
+      // `block.close` and only when every other check passed — never by a refused close
+      const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
+      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews, report], closeRows });
       (result.ok ? out : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
       return result.ok ? 0 : 1;
     }
@@ -327,6 +372,19 @@ async function confirmNoReviews(runId, id, deps) {
   return ui.isCancel(go) || go !== true ? 'cancelled' : 'confirmed';
 }
 
+/**
+ * B59: the rules lane for a brief-mode block — `fallbackLane` over the facts of its owned entries,
+ * the `--lines` estimate and the snapshot's `proof.tiers.high.paths` (none for a record from
+ * before snapshots).
+ * @param {Record<string, any>} record @param {string[]} owned @param {number | null} lines
+ * @returns {{lane: string, facts: ReturnType<typeof laneFacts>}}
+ */
+function rulesLane(record, owned, lines) {
+  const high = configInForce(record)?.proof?.tiers?.high?.paths;
+  const facts = laneFacts({ owned, lines, highPaths: high });
+  return { lane: fallbackLane(facts), facts };
+}
+
 /**
  * B47: the level `autopilot level` chose for the block — the latest `autopilot.level` row of this
  * run for it whose MAC verifies — or null when there is none.

package/src/cli/report.mjs

@@ -1,10 +1,12 @@
 /**
  * `code-forge report [--slug <slug>] [--json] [--export <dir>]` (plan §6.2, R4). Terminal output
- * only, plus an optional `--export <dir>` that writes the same 13 sections as JSON files.
+ * only, plus an optional `--export <dir>` that writes the same 13 sections as JSON files. The
+ * terminal output ends with the spend per run (B33) and the mode of each run (B59: brief or plan);
+ * both are text only, never in `--json` or `--export`, so the 13 pinned sections stay as they are.
  */
 
 import { writeSafe } from '../util/redact.mjs';
-import { buildReport, buildSpend } from '../ledger/report.mjs';
+import { buildReport, buildRunModes, buildSpend } from '../ledger/report.mjs';
 import { exportReportSections } from '../ledger/export.mjs';
 import { readAllRows } from '../ledger/write.mjs';
 
@@ -61,6 +63,7 @@ export async function runReport(args, deps = {}) {
       out(`== ${name} ==\n${JSON.stringify(data, null, 2)}\n`);
     }
     out(spendLines(buildSpend(rows)));
+    out(modeLines(buildRunModes(rows)));
     return 0;
   } catch (err_) {
     err(`report: ${err_?.message ?? String(err_)}\n`);
@@ -81,6 +84,17 @@ export function spendLines({ runs, total }) {
   return `${lines.join('\n')}\n`;
 }
 
+/**
+ * B59: the mode of each run (`brief` or `plan`), after the spend — text only, never in `--json`
+ * or `--export`. Empty (no header) when the ledger has no run.
+ * @param {ReturnType<typeof buildRunModes>} modes
+ * @returns {string}
+ */
+export function modeLines(modes) {
+  if (modes.length === 0) return '';
+  return `${['run mode:', ...modes.map((m) => `  run ${m.run}: ${m.mode}`)].join('\n')}\n`;
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function report(args) {
   return runReport(args);

package/src/cli/run.mjs

@@ -2,7 +2,7 @@
  * `code-forge run start|status|end` (plan §4.9). The orchestrator runs these; a coder never does
  * (`run start` is on the forbidden list, ★ `code-forge-worker-from-coder`).
  *
- *   run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]
+ *   run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] [--mode plan|brief]
  *   run start --reattach --run <id> [--worker-pid <pid>]
  *   run status --run <id>     (B33: includes spent_usd / budget_usd / unknown_usd_sessions)
  *   run reload --run <id>
@@ -14,6 +14,12 @@
  * queue announces (`repinWorker`). Called as `runRun(args, deps)` without `deps.startWorker` (the
  * state tests), no worker is launched and none is pinned unless `--worker-pid` is given.
  *
+ * B59 `--mode brief`: a run with briefs and no plan. The mode is stored in the run record and on a
+ * signed `run.mode {mode: brief, plan: none}` row, and it is fixed for the run (`run reload` never
+ * touches it); `block open` without `--level` then takes the lane from the rules. `--mode plan`
+ * (the default) changes nothing; any other value, or `--mode` on any other verb or with
+ * `--reattach`, is a usage error (exit 2).
+ *
  * B35 `run reload`: re-read and validate the workspace's `.code-forge.yml` and replace the run's
  * config snapshot (`reloadRun`) — no `block stop` / `run end` / `run start` cycle. An invalid
  * config or a change to a key that is fixed for the run is refused with nothing changed. It prints
@@ -29,7 +35,7 @@ import { budgetUsdOf, runSpend } from '../ledger/spend.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
-import { endRun, processStartTime, readRun, reattachWorker, startRun, stopPinnedWorker } from '../state/run.mjs';
+import { endRun, processStartTime, readRun, reattachWorker, RUN_MODES, startRun, stopPinnedWorker } from '../state/run.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { sweepRoots, tmpBase } from '../util/tmp.mjs';
 import { launchWorker, repinWorker } from '../worker/loop.mjs';
@@ -101,9 +107,12 @@ export async function runRun(args, deps = {}) {
     return 2;
   }
   try {
-    const { flags } = parseFlags(rest, { values: ['run', 'cwd', 'engine', 'worker-pid'], booleans: ['reattach'] });
+    const { flags } = parseFlags(rest, { values: ['run', 'cwd', 'engine', 'worker-pid', 'mode'], booleans: ['reattach'] });
     const runId = typeof flags.run === 'string' ? flags.run : undefined;
     const workerPid = intFlag(flags['worker-pid'], 'worker-pid');
+    const mode = typeof flags.mode === 'string' ? flags.mode : undefined;
+    if (mode !== undefined && (sub !== 'start' || flags.reattach)) throw new StateError('usage', '--mode is set once, by a new run start (the mode is fixed for the run)');
+    if (mode !== undefined && !RUN_MODES.includes(mode)) throw new StateError('usage', `--mode must be one of ${RUN_MODES.join(', ')}`);
 
     if (sub === 'start' && flags.reattach) {
       if (!runId) throw new StateError('usage', 'run start --reattach needs --run');
@@ -129,7 +138,7 @@ export async function runRun(args, deps = {}) {
       const engine = typeof flags.engine === 'string' ? flags.engine : undefined;
       const tmpRoot = typeof loaded.config?.tmp?.root === 'string' ? loaded.config.tmp.root : undefined;
       await sweepRoots({ root: tmpBase(tmpRoot) }); // dead runs' temp roots and orphans (§9.6, V12)
-      let record = await startRun({ workspace, project, config: loaded.config, engine, runId, workerPid, writeRow: ledgerWriter(project), probe });
+      let record = await startRun({ workspace, project, config: loaded.config, engine, mode, runId, workerPid, writeRow: ledgerWriter(project), probe });
       if (!record.worker && startWorker) {
         const launched = await startWorker({ runId: record.run_id, workspace });
         const startedAt = await (probe ?? processStartTime)(launched.pid); // what the stop below re-checks against
@@ -141,7 +150,8 @@ export async function runRun(args, deps = {}) {
           throw thrown;
         }
       }
-      out(`run ${record.run_id} started · engine ${record.engine} · worker ${record.worker ? `pid ${record.worker.pid}` : 'not pinned'}\n`);
+      const brief = record.mode === 'brief' ? ' · mode brief (no plan)' : '';
+      out(`run ${record.run_id} started · engine ${record.engine}${brief} · worker ${record.worker ? `pid ${record.worker.pid}` : 'not pinned'}\n`);
       if (!record.worker) err('run start: no worker pinned — start the worker, then `run start --reattach --run <id> --worker-pid <pid>`\n');
       return 0;
     }
@@ -211,7 +221,7 @@ async function reloadVerb(runId, { out, err }) {
 }
 
 const USAGE =
-  'usage: code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] | start --reattach --run <id> [--worker-pid <pid>] | status --run <id> | reload --run <id> | end --run <id>\n';
+  'usage: code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>] [--mode plan|brief] | start --reattach --run <id> [--worker-pid <pid>] | status --run <id> | reload --run <id> | end --run <id>\n';
 
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function run(args) {

package/src/decide/lane-facts.mjs

@@ -0,0 +1,41 @@
+/**
+ * B59: the facts `fallbackLane` (./fallback-rules.mjs) needs, built from what a brief-mode
+ * `block open` knows before any code exists: the block's owned entries, the estimated changed
+ * lines (`--lines`) and `proof.tiers.high.paths` from the run's config snapshot. Pure — no disk,
+ * no git; the caller reads the snapshot.
+ *
+ *   filesChanged              the number of distinct owned entries (a directory entry counts once)
+ *   linesAdded                `--lines`, 0 when not given
+ *   touchesMigration          an owned entry names a migration (`isMigrationPath`)
+ *   touchesPolicyOrMiddleware an owned entry names a policy or middleware (`isPolicyPath`)
+ *   pathFloorHit              a high path owns an owned entry, or an owned entry owns a high path
+ *                             (a directory entry above a high path counts: its files are in scope)
+ *
+ * The migration and policy checks are case-insensitive SUBSTRING matches anywhere in the path
+ * (`src/migrationHelper.ts` is a migration path), the same patterns the §3.5 review rules use
+ * (`rulesRisk` in src/review/engine.mjs calls these two functions).
+ */
+
+import { ownsFile } from '../state/registry.mjs';
+
+/** A path the §3.5 rules treat as a migration. @param {string} file @returns {boolean} */
+export const isMigrationPath = (file) => /migration/i.test(file);
+
+/** A path the §3.5 rules treat as a policy or middleware. @param {string} file @returns {boolean} */
+export const isPolicyPath = (file) => /polic(y|ies)|middleware/i.test(file);
+
+/**
+ * @param {{owned: ReadonlyArray<string>, lines?: number | null, highPaths?: unknown}} input
+ *   `highPaths` that is not an array (absent, null) means no high paths.
+ * @returns {Required<Omit<import('./fallback-rules.mjs').FallbackFacts, 'keywordsFound'>>}
+ */
+export function laneFacts({ owned, lines = null, highPaths = [] }) {
+  const high = (Array.isArray(highPaths) ? highPaths : []).filter((p) => typeof p === 'string' && p.length > 0);
+  return {
+    filesChanged: new Set(owned).size,
+    linesAdded: lines ?? 0,
+    touchesMigration: owned.some(isMigrationPath),
+    touchesPolicyOrMiddleware: owned.some(isPolicyPath),
+    pathFloorHit: owned.some((entry) => ownsFile(high, entry) || high.some((h) => ownsFile([entry], h))),
+  };
+}

package/src/ledger/report.mjs

@@ -12,7 +12,7 @@
  * coder/reviewer/judge/s2/author/facts spend (plus `ledger add coder` manual rows and
  * `session.background` rows, whose price is unknown); its dollars come from `./spend.mjs`
  * (`usd`, else `cost_usd`, else ESTIMATED from its tokens × `./prices.mjs`); `review.done` {block,file,context_mode,findings_by_severity,round}; `decision`
- * {block,question,source}; `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
+ * {block,question,source}; `run.start` {run}; `run.mode` {run,mode,plan} (B59, `buildRunModes`); `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
  * `review.unavailable` {block,reason}; `proof` {block,duration_ms}; `run.stop` {reason}.
  */
 
@@ -60,6 +60,20 @@ export function buildSpend(rows) {
   return { runs: spendByRun(acted), total: sumSpend(acted) };
 }
 
+/**
+ * B59: the mode of every run with a `run.start` row, in ledger order — `brief` when the run has a
+ * `run.mode {mode: brief}` row, else `plan` (a run with no `run.mode` row is a plan run). Like the
+ * spend, it is terminal text only (`src/cli/report.mjs`): it is not in `--json` or `--export`, so
+ * the pinned `SECTION_NAMES` sections stay exactly as they are.
+ * @param {Array<Record<string, any>>} rows
+ * @returns {Array<{run: string, mode: 'brief' | 'plan'}>}
+ */
+export function buildRunModes(rows) {
+  const brief = new Set(rows.filter((r) => r.event === 'run.mode' && r.mode === 'brief' && typeof r.run === 'string').map((r) => r.run));
+  const runs = [...new Set(rows.filter((r) => r.event === 'run.start' && typeof r.run === 'string').map((r) => r.run))];
+  return runs.map((run) => ({ run, mode: brief.has(run) ? 'brief' : 'plan' }));
+}
+
 /**
  * Cost per block — completed AND still open (B33: a running total while the block is open):
  * review $ / coder $ / S1+S2 $ / facts $ / proof ms, `completed` (any `block.close` row) and

package/src/review/engine.mjs

@@ -51,6 +51,7 @@ import path from 'node:path';
 import { resolveLevel } from '../config/known-ids.mjs';
 import { blockKind, isDocsKind } from '../decide/escalation.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
+import { isMigrationPath, isPolicyPath } from '../decide/lane-facts.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
@@ -152,8 +153,8 @@ export function rulesRisk({ file, plusCount, cfg }) {
     pathFloorHit,
     filesChanged: 1,
     linesAdded: plusCount,
-    touchesMigration: /migration/i.test(file),
-    touchesPolicyOrMiddleware: /polic(y|ies)|middleware/i.test(file),
+    touchesMigration: isMigrationPath(file),
+    touchesPolicyOrMiddleware: isPolicyPath(file),
   });
 }
 

package/src/state/block.mjs

@@ -11,12 +11,14 @@
  * B12) — this module never imports them (C17).
  */
 
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { createReadStream, existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
+import { DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
+import { externalReviewer } from './config-snapshot.mjs';
 import { ownedKinds, pathKind } from './owned-kinds.mjs';
 import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
 import { StateError } from './paths.mjs';
@@ -254,6 +256,39 @@ function activeBlocks(record) {
   return Object.fromEntries(Object.entries(record.blocks).filter(([, b]) => b.status === 'open'));
 }
 
+/**
+ * B58: with `review.external.required` set in the run's snapshot, the project's `.code-forge.yml`
+ * is the owner's switch past the local per-file review, so no block may own it. These are the
+ * spellings an owned entry may match it by: relative to the workspace and, for a workspace in a
+ * subdirectory, relative to the repository top level (the close gate matches both, `ownsAt`).
+ * Empty when the key is not set.
+ * @param {Record<string, any>} record @returns {Promise<string[]>}
+ * @throws {StateError} `config-snapshot`, `git-failed`
+ */
+async function guardedConfigPaths(record) {
+  if (externalReviewer(record) === null) return [];
+  const top = await repoTop(record.workspace);
+  // the repo-top spelling `<prefix>/.code-forge.yml` may also match a different file of the same
+  // name under the workspace (`<ws>/<prefix>/.code-forge.yml`): that over-match only refuses more,
+  // never less, and is the one `ownsAt` gives the close gate
+  const prefix = path.relative(top, realpathSync(record.workspace)).split(path.sep).join('/');
+  return prefix === '' ? [DEFAULT_CONFIG_FILENAME] : [DEFAULT_CONFIG_FILENAME, `${prefix}/${DEFAULT_CONFIG_FILENAME}`];
+}
+
+/**
+ * B58: refuse an owned entry that owns one of `guarded` (B57's rule, `ownsFile`: the exact path,
+ * a directory above it, or a glob that matches it).
+ * @param {ReadonlyArray<string>} owned @param {import('./registry.mjs').OwnedKinds} kinds @param {ReadonlyArray<string>} guarded
+ * @throws {StateError} `config-owned`
+ */
+function refuseConfigOwner(owned, kinds, guarded) {
+  for (const entry of owned) {
+    if (guarded.some((file) => ownsFile([entry], file, kinds))) {
+      throw new StateError('config-owned', `owned entry ${JSON.stringify(entry)} covers the project's ${DEFAULT_CONFIG_FILENAME}; no block may own it while review.external.required is true`);
+    }
+  }
+}
+
 /**
  * `block open` — refuses a second open of the same id and any owned set that overlaps another
  * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast and the
@@ -262,10 +297,18 @@ function activeBlocks(record) {
  * and the dispatch row carry the floor level, and the row adds `requested_level` and
  * `trigger: 'docs_floor'`. B52: the entry also records `tree_at_open` ({@link treeAtOpen}), the
  * tree's changes at open, which `block close` reads to tell the coder's changes from earlier ones.
+ * B58: with `review.external.required` set, an owned entry that owns the project's config is
+ * refused (`config-owned`, {@link refuseConfigOwner}).
+ * B59: `decision` (the rules lane of a brief-mode block) is written as a signed `decision` row
+ * naming the block, with `decisionId` (default a fresh UUID) as its `decision_id`, just before the
+ * `dispatch` row — under the same lock, so a refused open writes neither. Its `answer` is the
+ * requested lane and must equal `level` (else `bad-decision`, nothing written); the docs floor may
+ * still raise the dispatched level, and the dispatch row then names the lane as `requested_level`.
  * @param {{
  *   runId: string, id: string, level: string, owned: string[], acceptance: unknown,
  *   attempt?: number, base?: string, lines?: number, brief?: {path: string, content: Buffer | string},
  *   kind?: string, cfg?: Record<string, any>, writeRow: WriteRow, now?: Date,
+ *   decision?: {question: 'lane', answer: string, source: 'rules', facts: Record<string, unknown>}, decisionId?: string,
  * }} opts
  * @returns {Promise<{block: Record<string, any>, pointer: string | null}>}
  */
@@ -276,6 +319,7 @@ export async function openBlock(opts) {
   if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
   if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
   if (opts.kind !== undefined && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${BLOCK_KINDS.join(', ')}`);
+  if (opts.decision && opts.decision.answer !== level) throw new StateError('bad-decision', `the decision answer ${opts.decision.answer} is not the requested level ${level}`);
   const owned = assertOwned(opts.owned);
   const acceptance = assertAcceptance(opts.acceptance);
   const kind = blockKind({ owned, declared: opts.kind });
@@ -284,15 +328,19 @@ export async function openBlock(opts) {
 
   // B52: the tree is stamped BEFORE the run lock (hashing can be slow; other block commands must
   // not wait on it); under the lock the base is resolved again and must be the one stamped against
-  const { workspace } = await readRun(runId);
+  const before = await readRun(runId);
+  const { workspace } = before;
   const stampedBase = await resolveCommit(opts.base ?? 'HEAD', workspace);
   const treeOpen = await treeAtOpen(workspace, stampedBase);
+  // B58: `review.external` cannot change mid-run, so the record read here decides
+  const guarded = await guardedConfigPaths(before);
 
   const block = await mutateRun(runId, null, writeRow, async (record) => {
     if (record.blocks[id]?.status === 'open') throw new StateError('already-open', `block ${id} is already open`);
     // B57: what each exact owned entry is on disk, under the lock (as `block claim`) — a regular
     // file owns only itself, here and in every later check
     const kinds = ownedKinds(record.workspace, owned);
+    refuseConfigOwner(owned, kinds, guarded);
     for (const [otherId, other] of Object.entries(activeBlocks(record))) {
       const pair = findOverlap(owned, other.owned_files, { kindsA: kinds, kindsB: other.owned_kinds });
       if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
@@ -304,7 +352,10 @@ export async function openBlock(opts) {
     const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
     return {
       result: entry,
-      rows: [{ event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
+      rows: [
+        ...(opts.decision ? [{ ...opts.decision, event: 'decision', decision_id: opts.decisionId ?? randomUUID(), block: id }] : []),
+        { event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines },
+      ],
     };
   });
   return { block, pointer };
@@ -347,13 +398,17 @@ export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
  * glob, and when another open block owns it — or anything it would own: the claimed path becomes an
  * owned entry, so it is checked with `findOverlap` (B57: an entry owns the paths below it too,
  * unless it is a regular file now — its kind is recorded in `owned_kinds` as at `block open`).
+ * B58: with `review.external.required` set, a path that owns the project's config is refused
+ * (`config-owned`), as at `block open`.
  * @param {{runId: string, id: string, file: string, writeRow: WriteRow}} opts
  */
 export async function claimPath({ runId, id, file, writeRow }) {
   assertOwned([file]);
   if (!isExactEntry(file)) throw new StateError('bad-owned', `block claim takes one exact path, not a glob (${JSON.stringify(file)})`);
+  const guarded = await guardedConfigPaths(await readRun(runId));
   await mutateRun(runId, id, writeRow, (record, block) => {
     const kinds = { [file]: pathKind(record.workspace, file) };
+    refuseConfigOwner([file], kinds, guarded);
     for (const [otherId, other] of Object.entries(activeBlocks(record))) {
       const pair = otherId === id ? null : findOverlap([file], other.owned_files, { kindsA: kinds, kindsB: other.owned_kinds });
       if (pair) throw new StateError('overlap', `${file} overlaps ${pair[1]} owned by open block ${otherId}`);
@@ -396,15 +451,18 @@ export async function stopBlock({ runId, id, reason, writeRow, event = 'block.st
  * stopped); the block's signed `dispatch` row must exist and verify, and every other
  * gate-relevant row of the block must verify ⇒ else `ledger.tamper` (block stopped); then
  * `extraChecks`; finally, UNDER the run lock, orphans in the registry ⇒ refused (block stays
- * open), else closed.
+ * open), else closed. B58: `closeRows` are signed and written under that same lock just before
+ * `block.close`, and only when the block closes — a row that records why it may close is never
+ * left behind by a refused close.
  * @param {{
  *   runId: string, id: string, rows: Record<string, any>[], writeRow: WriteRow,
  *   livePid?: number, probe?: import('./run.mjs').StartTimeProbe,
  *   extraChecks?: Array<() => Promise<{ok: boolean, reason?: string}>>,
+ *   closeRows?: Record<string, any>[],
  * }} opts
  * @returns {Promise<{ok: boolean, status: 'closed' | 'stopped' | 'open', reason?: string, event?: string}>}
  */
-export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, extraChecks = [] }) {
+export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, extraChecks = [], closeRows = [] }) {
   const record = await readRun(runId);
   if (record.blocks[id]?.status !== 'open') throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
 
@@ -442,6 +500,6 @@ export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, ex
     block.status = 'closed';
     /** @type {CloseResult} */
     const closed = { ok: true, status: 'closed' };
-    return { result: closed, rows: [{ event: 'block.close', block: id, status: 'complete' }] };
+    return { result: closed, rows: [...closeRows, { event: 'block.close', block: id, status: 'complete' }] };
   });
 }

package/src/state/config-snapshot.mjs

@@ -18,6 +18,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { StateError } from './paths.mjs';
 
 /**
  * Keys that cannot change mid-run, each with why. A change to one is refused by `run reload`
@@ -30,6 +31,9 @@ export const IMMUTABLE_KEYS = Object.freeze({
   'tmp.root': "the worker's run temp root is created at run start",
   keys: 'the worker resolves keys once, at start',
   'system1.key': 'the worker resolves the Jev key once, at start',
+  // B58: the owner's switch past the local per-file review is set before the run starts or not at
+  // all, so nobody turns it on (or off) mid-run
+  'review.external': 'the outside reviewer is fixed by the owner before the run starts',
 });
 
 /** @param {unknown} v @returns {boolean} what `JSON.stringify` drops from an object. */
@@ -148,3 +152,35 @@ export function snapshotFor(record, ticket) {
   if (!isMapping(config) || configHash(config) !== hash) throw new Error('config-snapshot');
   return { hash, config };
 }
+
+/**
+ * The config snapshot in force for the run (no ticket pin), or null for a record from before
+ * snapshots.
+ * @param {Record<string, any>} record
+ * @returns {Record<string, any> | null}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function configInForce(record) {
+  try {
+    return snapshotFor(record, '')?.config ?? null;
+  } catch (thrown) {
+    if (!(thrown instanceof Error) || thrown.message !== 'config-snapshot') throw thrown;
+    throw new StateError('config-snapshot', `run ${record.run_id}: the config snapshot in force does not match its hash`);
+  }
+}
+
+/**
+ * B58: the outside reviewer named by the snapshot in force when `review.external.required` is
+ * true; null otherwise (key absent, `required` false, or a record from before snapshots). The key
+ * is immutable ({@link IMMUTABLE_KEYS}), so this is the value `run start` stored.
+ * @param {Record<string, any>} record
+ * @returns {string | null}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function externalReviewer(record) {
+  const external = configInForce(record)?.review?.external;
+  if (!isMapping(external) || external.required !== true) return null;
+  // required without a usable name is no switch at all (the schema refuses it; this is the floor)
+  const name = typeof external.name === 'string' ? external.name.trim() : '';
+  return name === '' ? null : name; // trimmed: no row ever carries padding
+}

package/src/state/run.mjs

@@ -16,7 +16,7 @@ import { mkdir, readFile, rename, rmdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { exec } from '../util/exec.mjs';
 import { StateError, assertRunId, assertWorkspaceOutsideRuns, mirrorPath, newRunId, runRecordPath, runsDir } from './paths.mjs';
-import { changedKeyPaths, configHash, IMMUTABLE_KEYS, immutableChanges, initialConfigState } from './config-snapshot.mjs';
+import { changedKeyPaths, configHash, externalReviewer, IMMUTABLE_KEYS, immutableChanges, initialConfigState } from './config-snapshot.mjs';
 import { generateKey, loadKey, signRow } from './signer.mjs';
 
 /** @typedef {(row: Record<string, any>) => Promise<unknown>} WriteRow */
@@ -132,11 +132,17 @@ async function pinWorker(workerPid, probe) {
   return { pid: workerPid, started_at: startedAt };
 }
 
+/** B59: the run modes `run start --mode` takes; `plan` is the default and is never recorded. */
+export const RUN_MODES = Object.freeze(['plan', 'brief']);
+
 /**
  * `run start`: record + key + worker pin + ledger `run.start`, all under the run lock. An
  * existing run id is refused before anything is written (its key and record stay untouched).
+ * B59: `mode: 'brief'` (a run with briefs and no plan) is stored in the record as `mode` and
+ * written as a signed `run.mode {mode: 'brief', plan: 'none'}` row right after `run.start`; `plan`
+ * or no mode leaves the record and the rows exactly as before. Nothing changes the mode later.
  * @param {{
- *   workspace: string, project: string, config?: Record<string, any>, engine?: string,
+ *   workspace: string, project: string, config?: Record<string, any>, engine?: string, mode?: string,
  *   runId?: string, workerPid?: number, orchestratorPid?: number, soloPid?: string | null,
  *   writeRow: WriteRow, probe?: StartTimeProbe, now?: Date,
  * }} opts
@@ -149,6 +155,14 @@ export async function startRun(opts) {
     throw new StateError('bad-project', 'project slug must match /^[a-z0-9][a-z0-9-]*$/ (config key project.slug)');
   }
   const workspace = assertWorkspaceOutsideRuns(opts.workspace);
+  if (opts.mode !== undefined && !RUN_MODES.includes(opts.mode)) throw new StateError('usage', `--mode must be one of ${RUN_MODES.join(', ')}`);
+  const brief = opts.mode === 'brief';
+  // B58: the schema lets `review.external` stand without a name while `required` is off; on, the
+  // reviewer must be named — refused before anything is written
+  const external = config.review?.external;
+  if (external?.required === true && (typeof external.name !== 'string' || external.name.trim() === '')) {
+    throw new StateError('external-no-name', 'review.external.required is true but review.external.name is missing or blank');
+  }
   const worker = await pinWorker(opts.workerPid, probe);
   const record = {
     version: 1,
@@ -166,6 +180,7 @@ export async function startRun(opts) {
     status: 'active',
     blocks: {},
     orphans: [],
+    ...(brief ? { mode: 'brief' } : {}),
     // B35: the config snapshot the worker reviews with (`run reload` replaces it). Only when the
     // caller passed the loaded config: a record without it keeps the worker on its boot config.
     ...(opts.config !== undefined ? { config: initialConfigState(config) } : {}),
@@ -179,6 +194,10 @@ export async function startRun(opts) {
     await generateKey(runId);
     await saveRun(record);
     await writeSigned(runId, writeRow, { event: 'run.start', engine: record.engine, worker_pinned: worker !== null });
+    if (brief) await writeSigned(runId, writeRow, { event: 'run.mode', mode: 'brief', plan: 'none' });
+    // B58: the owner's outside reviewer is on the ledger from the first row of the run on
+    const reviewer = externalReviewer(record);
+    if (reviewer !== null) await writeSigned(runId, writeRow, { event: 'review.external', required: true, reviewer });
     return record;
   });
 }
@@ -198,8 +217,8 @@ export async function startRun(opts) {
  * Fixed keys ({@link IMMUTABLE_KEYS}): every one that changed is refused at once
  * (`immutable-key`, nothing written). A record from before snapshots (no `config`) is checked
  * against what it does store: `engine` and the ledger slug (`effectiveSlug`, computed by the
- * caller the same way `run start` did); it then gets its first snapshot, `changed_keys: null`,
- * `old_hash: null`.
+ * caller the same way `run start` did), and B58's `review.external.required` must not turn true;
+ * it then gets its first snapshot, `changed_keys: null`, `old_hash: null`.
  *
  * No change (same hash) ⇒ nothing written, no row. Otherwise the record is saved FIRST (it is the
  * source of truth), then one signed `run.reload` row: the changed key PATHS (never values) and
@@ -238,6 +257,9 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
       frozen = [];
       if (effectiveSlug !== undefined && effectiveSlug !== current.project) frozen.push('project.slug');
       if (typeof current.engine === 'string' && (config.engine ?? 'auto') !== current.engine) frozen.push('engine');
+      // B58: a run started without the key has none to keep — turning it on now is a change; an
+      // entry that leaves it off (`required` false or absent, as the schema default) is not
+      if (config.review?.external?.required === true) frozen.push('review.external');
     }
     if (frozen.length > 0) {
       const why = frozen.map((key) => `${key} cannot change mid-run (${IMMUTABLE_KEYS[/** @type {keyof typeof IMMUTABLE_KEYS} */ (key)]})`);