@codedology/code-forge 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,91 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-10-04
+
+### Added
+
+- Per-provider session limit `review.provider_concurrency` (defaults anthropic 4, openai 2, xai 2) and rate-limit
+  backoff: a rate-limited session waits about 2 s, then about 6 s (±30 %), before retrying the same step, instead of
+  retrying at once. New in-process keyed locks and semaphores (`src/util/locks.mjs`) prepare parallel review.
+- Parallel review in the worker: `review.parallel_tickets` (1–16, default 3) review tickets run at once, oldest first.
+  The same file is never reviewed twice at once; a block's budget row and its one L3 rung are taken under a block lock;
+  a crashed ticket never stops the others; on stop, running tickets finish. `run reload` can change the pool size. `1`
+  keeps the serial behaviour.
+- `code-forge doctor` shows a `review concurrency` row (tickets at once and provider slots); maintainers can measure the
+  pool with `npm run bench:review` (6 fake 2 s reviews: about 12 s at 1, about 4 s at 3).
+
+### Changed
+
+- Skill: a plan that passed `plan check` is shown to the owner for approval in the harness's plan mode (Claude Code:
+  EnterPlanMode → plan file → ExitPlanMode); no block is dispatched before that approval.
+- `budget.usd` holds when sessions start together: each session reserves its estimated cost under one lock (after taking
+  its provider slot) and releases it when its row is written or it fails. A refusal caused by running sessions says how
+  much they hold and this session's estimate; a session whose estimate alone is above the budget says so.
+- `code-forge review` enqueues every file first, then waits on all of them together under ONE deadline for the whole run
+  (`--max`, default 900 s, now a run deadline, not per file), prints each result on stderr as it finishes, and keeps the
+  final table in file order. At most 8 wait children run at once.
+
+### Fixed
+
+- `code-forge facts` verified nothing: delegates echo claims as `<kind>: <token>` and every answer was dropped as "no
+  answer". Answers now match by that form or by fact id (one answer per claim); a check that breaks the read-only rules,
+  or a silent command (`test`, `grep -q`), marks only that claim unverifiable with the reason instead of refusing the
+  whole sheet; the `<cli> <subcommand> --help | grep -c -- <flag>` check is allowed only for CLIs the brief names, never
+  interpreters or launchers.
+- Two files of one block could both take the block's single L3 patch rung (the rung was recorded only when the patch
+  check saved); a pending `next: patch` on a sibling file now counts as used.
+
+## [0.4.0] — 2026-10-02
+
+### Added
+
+- `budget.usd` per run: every session row carries an estimated `usd`; at 80% one warning, at 100% no new session starts
+  (fail closed if the spend cannot be read). `report` shows running totals for open blocks and per run; `run status`
+  shows spent and budget; `ledger add coder --usd` records cloud or manual coder spend.
+- `code-forge run reload --run <r>`: re-read `.code-forge.yml` mid-run without stopping blocks. Queued reviews keep the
+  old config, new ones use the new one; keys fixed for the run are refused by name; a signed `run.reload` row lists the
+  changed key paths (never values). Coders may not run it.
+- `block close --report <file>`: a coder report without a `reviewed <path> ticket <id>` line for every changed file
+  counts as FAILED (new `skill/templates/coder-brief.md`).
+- Error reports: `logs report --with-doctor` adds a cleaned setup check; each logged error lists the names of the last 5
+  commands (no flags or values); recovered problems are logged as warnings (1Password retry, review retry, System 1
+  fallback, budget at 80%), shown by `logs` and `logs summary`, and included in a report only with `--include-warnings`.
+  `CODE_FORGE_NO_ERROR_LOG=1` turns all of it off.
+- Known fixes: `logs report` checks a shipped table of fixed errors and, on an older version, tells you to upgrade
+  instead of filing (`--force` files anyway). An `error-triage` GitHub Action labels error reports by fingerprint,
+  comments once when the error is already fixed, and writes a weekly count. Maintainers record fixes with `npm run
+  known-fix -- add`.
+
+### Changed
+
+- Escalation and review cost rules from the first real run: after one review round that leaves 2+ warnings (or any
+  critical), the next fix climbs one level (`escalation.*`); docs and contract blocks code at L1 or higher
+  (`levels.coder_floor_docs`); risk 0–1 gets a single reviewer (`review.single_reviewer_max_risk`); docs blocks skip
+  multimodel review unless `review.multimodel_for_docs` is set.
+- `plan check` refuses a block whose level does not match its recorded lane (`jev ask lane --block <id> [--plan
+  <file>]`, or `--rules` without Jev) and prints the lane per block. The plan author gets the exact required headings
+  from one shared list; a close heading at the right position is accepted with a WARN. `jev ask` now writes to the
+  project's ledger slug (it used to default to `code-forge`).
+
+### Fixed
+
+- `validate` rejects an effort the level's provider cannot take (for example `xhigh` on an openai level), for levels and
+  fallback entries, instead of failing when the session starts. The builders share one list of allowed efforts, and
+  messages never repeat an unknown value.
+- Stuck review sessions: a session that times out is retried once before the review is reported unavailable;
+  `review.session_timeout_s` now defaults to 300; the ledger note keeps a cleaned stderr tail and the stdout event types
+  (never stdout text) so a hang can be diagnosed; a live worker with a fresh heartbeat is never reported as
+  `worker_down`.
+- `ledger tail -n <count>` limits the output (only `--n` worked). Jev score criteria keys must be exactly 0..n, with a
+  clear error otherwise.
+
+### Security
+
+- Codex (openai) is refused for closed-book roles — reviewer, judge, S2 and plan author — because it always has a shell
+  that can read files. `validate`, `resolve` and `doctor` say so. Set `review.allow_open_book_codex: true` to accept
+  that risk and keep using it (with warnings). Codex coders are unchanged.
+
 ## [0.3.2] — 2026-10-01
 
 ### Fixed

package/README.md

@@ -3,10 +3,45 @@
 A CLI (`code-forge`) plus one Agent Skill that runs the **plan → harden → code → review** pipeline
 for cross-model, parallel, evidence-gated feature delivery — on Claude Code, Codex, Grok, and Solo.
 
-> **Status:** built block by block from a maintainer-only design plan. The CLI, decision layer,
-> review engine, worker, proof policy and installer are landed; the Agent Skill under `skill/` and
-> the shipped example repo under `examples/` land in later blocks (see
-> `docs/reference/blocks.json` for what has landed and what is still pending).
+> **Status:** published on npm. The CLI, the decision layer, the review engine, the worker, the
+> proof policy, the installer, the Agent Skill under `skill/` and the example repo under
+> `examples/` have all landed (`docs/reference/blocks.json` lists every build block). What changed
+> in each version is in [CHANGELOG.md](CHANGELOG.md).
+
+## What's new
+
+- **Parallel review.** The worker reviews `review.parallel_tickets` files at once (default 3), with
+  a session limit per provider (`review.provider_concurrency`), backoff on rate limits, and
+  `budget.usd` still holding. `code-forge review` now waits on all files under one `--max`
+  deadline and prints each result as it finishes. `code-forge doctor` shows the numbers.
+
+## What's new in 0.4
+
+- **Cost control.** Set `budget.usd` per run: one warning at 80%, no new session at 100%. Every
+  session row carries an estimated `usd`; `report` and `run status` show the spend, and
+  `ledger add coder --usd` records spend code-forge did not see.
+- **Cheaper, faster fixes.** One review round that leaves 2 or more warnings climbs the coder one
+  level (`escalation.*`). Docs and contract blocks code at L1 or higher and skip multimodel review;
+  a file with risk 0–1 gets one reviewer (`review.single_reviewer_max_risk`).
+- **Change the config mid-run.** `code-forge run reload --run <id>` re-reads `.code-forge.yml`
+  without stopping open blocks.
+- **Stricter plans.** `plan check` refuses a block whose level is not the lane recorded with
+  `jev ask lane --block <id>` (or `--rules` without Jev), and prints the lane of every block.
+  `block close --report <file>` fails a coder report that does not name a review ticket per file.
+- **Codex is refused for closed-book roles** (reviewer, judge, System 2, plan author): it always
+  has a shell. See [Security model](#security-model).
+- **Steadier reviews.** A timed-out review session is retried once; `review.session_timeout_s`
+  defaults to 300; a live worker with a fresh heartbeat is never reported down.
+- **Better error reports.** `logs report --with-doctor` adds a cleaned setup check; errors list the
+  last 5 command names; recovered problems are logged as warnings; an error that a newer version
+  fixes tells you to upgrade instead of filing it.
+- **Earlier checks.** `validate` refuses an effort the level's provider cannot take (for example
+  `xhigh` on an openai level), so nothing fails when the session starts.
+
+Fixed in 0.3.1 and 0.3.2: Claude reviewer sessions no longer fail at once on the `--json-schema`
+flag; Grok answers are read from Grok's own answer envelope; Jev `score` questions (such as `risk`)
+no longer fall back to rules; and a clean review of a tiny diff (20 added lines or fewer) needs only
+40 output tokens, so it is no longer refused as `too_short`.
 
 ## What ships
 
@@ -88,28 +123,28 @@ usage line.
 | `tools` | `code-forge tools [--json]` · `code-forge tools install [<id>…] [--yes] [--dry-run]` — see and install the recommended tools (claude, codex, gemini, grok, op, solo) |
 | `validate` | `code-forge validate [--file <path>]` |
 | `resolve` | `code-forge resolve <L0\|L1\|L2\|L3>` |
-| `run` | `code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]` · `run start --reattach --run <id>` · `run status --run <id>` · `run end --run <id>` |
-| `block` | `code-forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file>` · `block attempt\|rebase\|claim\|close\|stop\|waive …` (§4.9; `waive` is human-only) |
+| `run` | `code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]` · `run start --reattach --run <id> [--worker-pid <pid>]` · `run status --run <id>` (with spent and budget USD) · `run reload --run <id>` (re-read `.code-forge.yml` mid-run) · `run end --run <id>` |
+| `block` | `code-forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code\|docs\|contract]` · `block attempt\|rebase <id> --run <r>` · `block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews]` · `block claim <id> <path> --run <r>` · `block stop <id> --run <r> --reason <text>` · `block waive <id> <finding-id> --run <r> --file <path> --reason <text>` (human-only) |
 | `worker` | `code-forge worker --run <id> [--cwd <dir>] [--poll-ms <n>] [--once]` — started detached by `run start`, never by a coder |
 | `review` | `code-forge review [--base <ref>] [--files <path…>] [--acceptance <file> \| --intent "<text>"] [--run <id>] [--max <seconds>] [--json] [--keep-run]` — review only: no coder, no proof, never closes a block |
-| `review-file` | `code-forge review-file <path> --block <id> [--run <id>]` (enqueue) · `review-file --wait <ticket> [--max <seconds>s]` (poll) |
-| `spawn` | `code-forge spawn --level L<n> --role <role> --brief <file> [--schema <file>] [--cwd <dir>] [--run <id>] [--block <id>] [--timeout <s>] [--background]` |
-| `s2` | `code-forge s2 --packet <file.json> [--run <id>] [--block <id>] [--timeout <s>]` |
-| `author` | `code-forge author --job plan\|harden --brief <file> [--facts <file>] [--draft <file>] [--answers <file>] [--out <file>] [--run <id>] [--timeout <s>]` |
-| `facts` | `code-forge facts --brief <file> [--sources <path>…] [--out <file>] [--run <id>] [--timeout <s>]` |
-| `plan` | `code-forge plan check <plan-file> [--facts <sheet>]` |
-| `proof` | `code-forge proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]` · `proof export\|lock\|unlock\|restore <block> --run <r>` |
+| `review-file` | `code-forge review-file <path> --block <id> [--run <id>]` (enqueue) · `review-file --wait <ticket> [--max <seconds>s]` (poll, default 90s; still running at `--max` prints `status: pending, reason: wait_timeout`) |
+| `spawn` | `code-forge spawn --level L0\|L1\|L2\|L3 --role <role> --brief <file> [--schema <file>] [--cwd <dir>] [--run <id>] [--block <id>] [--timeout <seconds>] [--background]` |
+| `s2` | `code-forge s2 --packet <file.json> [--run <id>] [--block <id>] [--timeout <seconds>]` |
+| `author` | `code-forge author --job plan\|harden --brief <file> [--facts <file>] [--draft <file>] [--answers <file>] [--out <file>] [--run <id>] [--timeout <seconds>]` |
+| `facts` | `code-forge facts --brief <file> [--sources <path>…] [--out <file>] [--run <id>] [--timeout <seconds>]` |
+| `plan` | `code-forge plan check <plan-file> [--facts <sheet>] [--slug <slug>]` — every block's level must be the lane recorded by `jev ask lane --block <id>`; prints `lanes: B1 L1 (rules) · …` |
+| `proof` | `code-forge proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]` · `proof export <block> --run <r> [--remove]` · `proof lock\|unlock\|restore <block> --run <r>` · `proof red-green <block> --run <r> --test <file[::case]> [--mechanism revert\|assertion-deletion]` |
 | `gates` | `code-forge gates detect\|run\|secret-scan\|safe-edit\|scope\|acceptance\|transcript-grep --cwd <dir> …` |
-| `jev` | `code-forge jev ask <question-id> --state <file.json> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]` |
-| `keys` | `code-forge keys list \| set <name> [--op <ref>] \| test <name> [--ref <ref>] \| remove <name>` |
-| `ledger` | `code-forge ledger calibration\|outcome\|tail --slug <slug> …` |
-| `report` | `code-forge report --slug <slug> [--json] [--export <dir>]` |
+| `jev` | `code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>] [--block <id>] [--plan <file>] [--rules]` — `--rules` answers `lane`, `risk` or `security_sensitive` without Jev; writes to the project's ledger slug |
+| `keys` | `code-forge keys list \| set <name> [--op <item-id\|link\|op://ref>] \| test <name> [--ref <ref>] \| remove <name>` |
+| `ledger` | `code-forge ledger tail --slug <slug> [--n\|-n <count>]` · `ledger calibration --slug <slug> [--question <id>]` · `ledger outcome --slug <slug> --pr <n> --ci red\|green\|reverted` · `ledger outcome --slug <slug> --scan-git [--cwd <dir>] [--days <n>]` · `ledger add coder --run <r> --block <b> --usd <n> [--note "..."]` |
+| `report` | `code-forge report --slug <slug> [--json] [--export <dir>]` — 13 sections, then the spend per run (open blocks included) and the total |
 | `models` | `code-forge models [--refresh --from-cli-caches]` |
 | `list` | `code-forge list` |
 | `remove` | `code-forge remove [<harness>] [--scope project\|global]` |
 | `upgrade` | `code-forge upgrade [--source <path>]` |
-| `logs` | `code-forge logs [--last N] [--json]` · `logs summary [--days N] [--json]` · `logs clear [--yes]` · `logs path` — the local error log (`~/.code-forge/logs/errors.jsonl`) |
-| `logs report` | `code-forge logs report [--last N] [--kind K] [--verb V] [--note "text"] [--dry-run] [--yes]` — share selected errors as a public GitHub issue; you see the full text first and say yes once |
+| `logs` | `code-forge logs [--last N] [--json]` · `logs summary [--days N] [--json]` · `logs clear [--yes]` · `logs path` — the local error log (`~/.code-forge/logs/errors.jsonl`): errors, warnings, and `[fixed in X.Y.Z]` marks |
+| `logs report` | `code-forge logs report [--last N] [--kind K] [--verb V] [--note "text"] [--include-warnings] [--with-doctor] [--no-ai] [--allow-old] [--force] [--dry-run] [--yes]` — share selected errors as a public GitHub issue; you see the full text first and say yes once. An error a newer version fixes is not filed unless `--force` |
 | `help` / `version` | `code-forge --help` (or no verb) · `code-forge --version` |
 
 `run`, `block`, `worker`, `spawn`, `s2`, `author`, `facts` and `review-file` are what the Agent
@@ -128,6 +163,18 @@ CLI verbs like any other and every one of them is exercised by this package's ow
 - **A forbidden-command list** stops a coder from starting its own worker, waiving a review, or
   running other orchestrator-only actions — rendered into each provider's own deny-list mechanism
   (`--disallowedTools` for Claude, an execpolicy rules file plus prose for Codex).
+- **Closed-book reviews.** Reviewers, judges, System 2 and the plan author see the packet and
+  nothing else: Claude runs them with no tools, Grok with every tool denied. Codex (provider
+  `openai`) has no mode without a shell, so code-forge refuses it for those roles: `validate`
+  warns, `resolve` marks the level `closed_book: "refused"`, `doctor` fails its isolation row, and
+  the session is never started. Codex coders are unchanged. `review.allow_open_book_codex: true`
+  accepts the risk and keeps Codex in those roles, with a warning on every surface.
+- **The error log stays on your machine.** A failed verb is logged to
+  `~/.code-forge/logs/errors.jsonl` with flag names but never flag values, and with home folder,
+  project, emails, `op://` references and 1Password item IDs replaced. `logs report` cleans the
+  text twice (built-in rules, then an AI check), stops on anything that looks like a key, shows
+  you the full issue and sends nothing without your yes. `CODE_FORGE_NO_ERROR_LOG=1` turns the log,
+  the warnings and the command list off. Every field is listed in [docs/privacy.md](docs/privacy.md).
 - **No mutation testing.** Neither this package's own tests nor the product it ships run mutation
   testing (Ricardo's ruling R14/Q16, 2026-09-25). Proof is plain unit and feature tests with exact
   assertions, plus a red→green runner that proves a new test fails before the fix and passes after.
@@ -135,7 +182,24 @@ CLI verbs like any other and every one of them is exercised by this package's ow
 ## Configuration reference
 
 `schema/code-forge.schema.json` is the source of truth for `.code-forge.yml`.
-`docs/reference/config.md` is generated from it:
+[docs/reference/config.md](docs/reference/config.md) lists every key with its type and default.
+Keys added for 0.4:
+
+| Key | Default | What it does |
+|---|---|---|
+| `budget.usd` | none | per-run spend stop in USD: one warning at 80%, no new session at 100% |
+| `escalation.after_rounds_with_warnings` | `1` | rounds with many warnings at one level before the coder climbs (`0` turns it off) |
+| `escalation.warning_threshold` | `2` | how many open warnings make a round "heavy" (any critical counts too) |
+| `levels.coder_floor_docs` | `L1` | the lowest level that codes a docs or contract block |
+| `review.single_reviewer_max_risk` | `1` | at or below this risk a file gets one reviewer and no judge |
+| `review.multimodel_for_docs` | `false` | let docs and contract blocks use multimodel review too |
+| `review.allow_open_book_codex` | `false` | let Codex run reviewer, judge, System 2 and plan author anyway |
+| `review.session_timeout_s` | `300` | a review session that runs longer is killed and retried once |
+| `review.parallel_tickets` | `3` | review tickets the worker runs at once (1 to 16); `1` reviews one file at a time |
+| `review.provider_concurrency` | anthropic `4`, openai `2`, xai `2` | review sessions at once per provider |
+
+`code-forge block open … --kind code|docs|contract` sets a block's kind when its file endings do
+not say it. The reference page is generated:
 
 ```bash
 node scripts/gen-config-doc.mjs          # regenerate docs/reference/config.md
@@ -154,4 +218,7 @@ Node >= 22 required (ruling R7). No build step — the package ships plain ESM `
 by Node. `docs/reference/blocks.json` maps each build block to the files it owns and what it
 depends on, kept in sync with the maintainer's design plan.
 
-Releasing: record changes with `npm run changelog -- <type> "<text>"`, then `npm run release -- <patch|minor|major|x.y.z> [--dry-run]` bumps, commits and tags (it never pushes or publishes). See [docs/releasing.md](docs/releasing.md).
+Releasing: record changes with `npm run changelog -- <type> "<text>"` and fixed error reports with
+`npm run known-fix -- add <fp> <version> "<summary>"`, then `npm run release -- <patch|minor|major|x.y.z> [--dry-run]`
+bumps, commits and tags (it never pushes or publishes). Publish with `npm publish` from your
+machine, then push the tag: CI only creates the GitHub release. See [docs/releasing.md](docs/releasing.md).

package/bin/code-forge.mjs

@@ -14,7 +14,7 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { clearErrorKind, reportErrorKind, takeErrorKind } from '../src/util/error-kind.mjs';
 import { maybeHint } from '../src/util/error-hint.mjs';
-import { captureStderr, writeVerbFailure } from '../src/util/error-log.mjs';
+import { captureStderr, noteVerb, writeVerbFailure } from '../src/util/error-log.mjs';
 import { redact } from '../src/util/redact.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -98,6 +98,11 @@ export async function run(argv) {
 
   const modulePath = path.join(CLI_DIR, `${verb}.mjs`);
 
+  // B37: the verb and its known subcommand word (never a flag or a value) join the last-5 list in
+  // `~/.code-forge/logs/breadcrumbs.json`; an error logged below names the commands before it.
+  // Best effort, never throws (CODE_FORGE_NO_ERROR_LOG=1 turns it off).
+  await noteVerb(verb, rest).catch(() => false);
+
   // B27: a verb that exits non-zero or throws is logged to `~/.code-forge/logs/errors.jsonl`
   // (scrubbed; never throws; never changes the exit code). The kind a verb reports is cleared
   // first, and stderr is recorded only while the verb runs (the message is its last text).

package/docs/README.md

@@ -9,9 +9,9 @@ disagree, the verb is right: each verb prints its own usage line when its argume
 | # | Page | Read it when you want to… |
 |---|---|---|
 | 1 | [overview.md](overview.md) | know what code-forge is, the problem it solves, who it is for, and what it is not |
-| 2 | [concepts.md](concepts.md) | look up a word: block, level, lane, tier, S1/S2, waiver, ledger… |
+| 2 | [concepts.md](concepts.md) | look up a word: block, level, lane, tier, S1/S2, waiver, ledger, budget, block kind, closed book, known fix… |
 | 3 | [how-it-works.md](how-it-works.md) | follow the full workflow from a brief to a closed block, and see who does what and where state lives |
-| 4 | [getting-started.md](getting-started.md) | install it, answer `init`, run `doctor`, and try the first commands |
+| 4 | [getting-started.md](getting-started.md) | install it, answer `init`, run `doctor`, try the first commands, and read or report errors (`code-forge logs`) |
 | 5 | [tutorial-first-test.md](tutorial-first-test.md) | run one real end-to-end test: build the code-forge marketing site in a new repo |
 | 5a | [review-only.md](review-only.md) | only review code you already wrote: a branch, uncommitted work or some files, with CI exit codes |
 | 6 | [examples/marketing-site/brief.md](examples/marketing-site/brief.md) | copy the brief the tutorial uses |
@@ -24,11 +24,12 @@ then 5a.
 
 | Page | What it is |
 |---|---|
+| [../CHANGELOG.md](../CHANGELOG.md) | what changed in each version; `## [Unreleased]` is the next one |
 | [reference/config.md](reference/config.md) | every `.code-forge.yml` key, its type and default. Generated from `schema/code-forge.schema.json` |
 | [reference/blocks.json](reference/blocks.json) | the build blocks of this package and what each one owns |
 | [marketing/code-forge-story.md](marketing/code-forge-story.md) | the marketing content bank (copy, lessons, what not to claim) |
-| [privacy.md](privacy.md) | what the local error log holds, every cleaning rule, the AI check, and how to turn the log off or delete it |
-| [releasing.md](releasing.md) | for maintainers: record changes (`npm run changelog`), cut a release with one command (`npm run release`), GitHub Releases, what stays manual |
+| [privacy.md](privacy.md) | what the local error log holds (errors, warnings, the last command names), every cleaning rule, the AI check, the setup check (`--with-doctor`), known fixes, and how to turn the log off or delete it |
+| [releasing.md](releasing.md) | for maintainers: record changes (`npm run changelog`) and known fixes (`npm run known-fix`), cut a release with one command (`npm run release`), publish by hand, GitHub Releases, the error-triage Action |
 | [`skill/SKILL.md`](../skill/SKILL.md) and [`skill/references/`](../skill/references/) | the Agent Skill the orchestrator follows. The deepest and most exact description of the rules |
 
 ## Conventions in these pages

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 30,
+  "block_count": 46,
   "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": {
@@ -371,6 +371,241 @@
       ],
       "depends_on": ["B27"],
       "note": "root-added 2026-10-01; not in the v1.3 §10.4 table"
+    },
+    "B29": {
+      "title": "Effort checked per provider: one shared PROVIDER_EFFORTS list for builders and validate (rule 15); messages never echo an unknown value",
+      "wave": 7,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/engines/efforts.mjs",
+        "test/engines/efforts.test.mjs"
+      ],
+      "depends_on": [
+        "B4.1"
+      ],
+      "note": "root-added 2026-10-02 from issue #2 field notes"
+    },
+    "B30": {
+      "title": "Review session hangs: one automatic retry on timeout, default timeout 300 s, cleaned stderr tail and stdout event types in a ledger note, worker heartbeat so --wait never reports worker_down for a live worker",
+      "wave": 7,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/session-retry.mjs",
+        "test/review/session-retry.test.mjs",
+        "test/worker/heartbeat.test.mjs"
+      ],
+      "depends_on": [
+        "B12c"
+      ],
+      "note": "root-added 2026-10-02 from issue #2 field notes; review cap reached, rulings in the local plan"
+    },
+    "B31": {
+      "title": "ledger tail -n, Jev score criteria keys must be 0..n, test hardening for PRs #3 and #4",
+      "wave": 7,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/decide/questions.mjs",
+        "test/decide/questions.test.mjs",
+        "test/review/validate-review.test.mjs"
+      ],
+      "depends_on": [
+        "B12a"
+      ],
+      "note": "root-added 2026-10-02"
+    },
+    "B32": {
+      "title": "Codex is refused for closed-book roles (reviewer, judge, S2, plan author): no proven no-tools mode; opt-in review.allow_open_book_codex with warnings",
+      "wave": 8,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/config/closed-book.mjs",
+        "test/config/closed-book.test.mjs"
+      ],
+      "depends_on": [
+        "B4.1"
+      ],
+      "note": "root-added 2026-10-02 from issue #2"
+    },
+    "B33": {
+      "title": "Session USD on every row, report running totals, budget.usd stop per run (80% warning, fail closed), ledger add coder --usd, run status spend",
+      "wave": 8,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/ledger/spend.mjs",
+        "test/ledger/spend.test.mjs",
+        "test/session/budget.test.mjs",
+        "test/state/budget.test.mjs"
+      ],
+      "depends_on": [
+        "B6"
+      ],
+      "note": "root-added 2026-10-02 from issue #2"
+    },
+    "B34": {
+      "title": "Escalation after a heavy review round, docs/contract coder floor L1, single reviewer for low risk, no multimodel for docs",
+      "wave": 8,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/decide/escalation.mjs",
+        "test/decide/escalation.test.mjs"
+      ],
+      "depends_on": [
+        "B12c"
+      ],
+      "note": "root-added 2026-10-02 from the owner rules in issue #2"
+    },
+    "B35": {
+      "title": "run reload: re-read config mid-run, pin queued tickets to the old snapshot, refuse fixed keys, signed run.reload row",
+      "wave": 8,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/state/config-snapshot.mjs",
+        "test/state/reload.test.mjs",
+        "test/worker/config-reload.test.mjs"
+      ],
+      "depends_on": [
+        "B11"
+      ],
+      "note": "root-added 2026-10-02 from issue #2"
+    },
+    "B36": {
+      "title": "plan check: levels must match a recorded lane (jev or rules, per block and plan); one shared source for required headings with a strict near-miss WARN; coder reports fail closed without review-file ticket ids (block close --report)",
+      "wave": 8,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/session/plan-sections.mjs",
+        "test/session/plan-sections.test.mjs",
+        "skill/templates/coder-brief.md"
+      ],
+      "depends_on": [
+        "B12c"
+      ],
+      "note": "root-added 2026-10-02 from issue #2 notes 12-14"
+    },
+    "B37": {
+      "title": "Error reports: --with-doctor setup check, breadcrumbs of the last 5 commands, warning lines for recovered problems (1Password retry, review retry, S1 fallback, budget 80%)",
+      "wave": 9,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/util/breadcrumbs.mjs",
+        "test/util/breadcrumbs.test.mjs",
+        "test/util/warnings.test.mjs"
+      ],
+      "depends_on": [
+        "B28"
+      ],
+      "note": "root-added 2026-10-02"
+    },
+    "B38": {
+      "title": "Known fixes table (logs report says upgrade instead of filing; regression note), known-fix maintainer script, error-triage GitHub Action (fp labels, one known-fix comment, weekly counts)",
+      "wave": 9,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/util/known-fixes.mjs",
+        "src/util/known-fixes.json",
+        "scripts/known-fix.mjs",
+        ".github/workflows/error-triage.yml",
+        "test/util/known-fixes.test.mjs",
+        "test/known-fix.test.mjs",
+        "test/error-triage.test.mjs"
+      ],
+      "depends_on": [
+        "B37"
+      ],
+      "note": "root-added 2026-10-02"
+    },
+    "B39": {
+      "title": "facts: match answers that echo the packet form or by fact_id, one row per claim; a rule-breaking check marks only its claim UNVERIFIABLE; narrow subcommand-help form (brief-named CLIs, no interpreters or launchers); silent commands never VERIFIED",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/session/facts.mjs",
+        "src/cli/facts.mjs",
+        "test/session/facts.test.mjs"
+      ],
+      "depends_on": [
+        "B12c"
+      ],
+      "note": "root-added 2026-10-03; found by running code-forge facts on its own repo"
+    },
+    "B40": {
+      "title": "Keyed locks, per-provider session limit (review.provider_concurrency), rate-limit backoff",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/util/locks.mjs",
+        "test/util/locks.test.mjs",
+        "test/session/provider-limit.test.mjs"
+      ],
+      "depends_on": [
+        "B39"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B41": {
+      "title": "Budget reservation under concurrency: slot first, then check + reserve estimated cost under one lock",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/ledger/spend-concurrency.test.mjs"
+      ],
+      "depends_on": [
+        "B40"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B42": {
+      "title": "Worker ticket pool: review.parallel_tickets, same-file rule, block lock for budget row and L3 rung, sibling patch counts as rung used",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/worker/pool.test.mjs"
+      ],
+      "depends_on": [
+        "B41"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B43": {
+      "title": "code-forge review enqueues all files, waits together under one deadline, at most 8 waiters",
+      "wave": 10,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "test/cli/review-parallel.test.mjs"
+      ],
+      "depends_on": [
+        "B42"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B44": {
+      "title": "Parallel review docs, doctor review-concurrency row, bench:review (N=1 vs N=3)",
+      "wave": 10,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "scripts/bench-review.mjs",
+        "test/bench-review.test.mjs"
+      ],
+      "depends_on": [
+        "B43"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
     }
   }
 }

package/docs/reference/config.md

@@ -53,6 +53,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `levels.L3.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
 | `levels.L3.fallback[].model` | string | yes | — | minLength 1 |
 | `levels.L3.fallback[].effort` | string |  | — |  |
+| `levels.coder_floor_docs` | enum: `L0`, `L1`, `L2` |  | `"L1"` |  |
 | `orchestrator` | enum: `L0`, `L1`, `L2`, `L3` |  | — |  |
 | `system1` | object |  | — |  |
 | `system1.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
@@ -83,8 +84,12 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `escalation.review_rounds_per_level` | integer |  | `2` | min 0 |
 | `escalation.stop_at` | const `"L3"` |  | `"L3"` |  |
 | `escalation.l3_mode` | enum: `patch`, `code` |  | `"patch"` |  |
+| `escalation.after_rounds_with_warnings` | integer |  | `1` | min 0 |
+| `escalation.warning_threshold` | integer |  | `2` | min 1 |
 | `review` | object |  | — |  |
 | `review.multimodel` | boolean |  | `false` |  |
+| `review.multimodel_for_docs` | boolean |  | `false` |  |
+| `review.single_reviewer_max_risk` | number |  | `1` | min 0; max 3 |
 | `review.second_provider` | enum: `anthropic`, `openai`, `xai` \| null |  | `null` |  |
 | `review.second_levels` | null \| object |  | `null` |  |
 | `review.closed_book` | const `true` |  | `true` |  |
@@ -102,10 +107,16 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.block_budget_usd` | number \| null |  | `null` |  |
 | `review.min_tokens_out` | integer |  | `120` | min 1 |
 | `review.batch_small_files` | boolean |  | `true` |  |
-| `review.session_timeout_s` | integer |  | `600` | min 1 |
+| `review.session_timeout_s` | integer |  | `300` | min 1 |
 | `review.max_rounds_per_file` | integer |  | `4` | min 2; max 6 |
 | `review.recheck_scope` | enum: `fix_hunks`, `file` |  | `"fix_hunks"` |  |
 | `review.late_findings` | enum: `sweep`, `block` |  | `"sweep"` |  |
+| `review.allow_open_book_codex` | boolean |  | `false` | B32: let openai (Codex) run reviewer/judge/S2/author with its read-only sandbox, which can read files on this machine. Off: those sessions are refused. |
+| `review.provider_concurrency` | object |  | — |  |
+| `review.provider_concurrency.anthropic` | integer |  | `4` | min 1 |
+| `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. |
 | `engine` | enum: `auto`, `solo`, `harness`, `subprocess` |  | `"auto"` |  |
 | `harnesses` | array<string> |  | — |  |
 | `harness` | object |  | — |  |
@@ -140,6 +151,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `budget.block_tokens_soft` | integer |  | — | min 1 |
 | `budget.block_tokens_hard` | integer |  | — | min 1 |
 | `budget.run_usd_soft` | number |  | — | min 0 |
+| `budget.usd` | number |  | — | > 0; Per-run spend stop in USD (R6). Before every session spawn the run's estimated spend is checked: one warning at 80%, new sessions refused at 100%. |
 | `budget.block_cases` | integer |  | `80` | min 10 |
 | `autonomy` | object |  | — |  |
 | `autonomy.coder_may_open_draft_pr` | boolean |  | `true` |  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",
@@ -31,6 +31,8 @@
     "scripts",
     "!scripts/release.mjs",
     "!scripts/changelog.mjs",
+    "!scripts/known-fix.mjs",
+    "!scripts/bench-review.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -39,7 +41,9 @@
     "test": "CODE_FORGE_NO_LEAK=snapshot node --import ./test/helpers/isolate.mjs --test test/no-leak.test.mjs && node --import ./test/helpers/isolate.mjs --experimental-test-module-mocks --test 'test/**/*.test.mjs' && CODE_FORGE_NO_LEAK=final node --import ./test/helpers/isolate.mjs --test test/no-leak.test.mjs",
     "typecheck": "tsc --checkJs --noEmit",
     "release": "node scripts/release.mjs",
-    "changelog": "node scripts/changelog.mjs"
+    "changelog": "node scripts/changelog.mjs",
+    "known-fix": "node scripts/known-fix.mjs",
+    "bench:review": "node scripts/bench-review.mjs"
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",