@codedology/code-forge 0.7.6 → 0.7.7

package/CHANGELOG.md

@@ -6,6 +6,16 @@ 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

package/README.md

@@ -12,6 +12,13 @@ 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

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 61,
+  "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": {
@@ -836,6 +836,20 @@
         "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.7.6",
+  "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/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.

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/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.6"
+PINNED_VERSION="0.7.7"
 set -eu
 
 self="$0"

package/src/cli/block.mjs

@@ -64,6 +64,14 @@
  * 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`.
@@ -73,10 +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 { externalReviewer } from '../state/config-snapshot.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';
@@ -141,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;
@@ -160,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;
@@ -344,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,7 +11,7 @@
  * 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';
@@ -299,10 +299,16 @@ function refuseConfigOwner(owned, kinds, guarded) {
  * 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}>}
  */
@@ -313,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 });
@@ -345,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 };

package/src/state/config-snapshot.mjs

@@ -154,22 +154,31 @@ export function snapshotFor(record, ticket) {
 }
 
 /**
- * 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.
+ * 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 {string | null}
+ * @returns {Record<string, any> | null}
  * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
  */
-export function externalReviewer(record) {
-  let snap;
+export function configInForce(record) {
   try {
-    snap = snapshotFor(record, '');
+    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`);
   }
-  const external = snap?.config.review?.external;
+}
+
+/**
+ * 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() : '';

package/src/state/run.mjs

@@ -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,8 @@ 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;
@@ -172,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) } : {}),
@@ -185,6 +194,7 @@ 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 });