@codedology/code-forge 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,66 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [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
+
+- Jev: `score` questions (such as `risk`) send their criteria as a list indexed by score. Jev refused the keyed object
+  with 422, so `doctor`'s Jev check failed and every `risk` call silently fell back to rules.
+- Review: on a small diff (20 added lines or fewer), a clean pass (passed, no findings, every hunk acknowledged) needs
+  only 40 output tokens instead of `review.min_tokens_out`, so a correct short review of a tiny file is no longer
+  refused as `too_short`. Any finding, or a larger diff, keeps the full floor.
+
 ## [0.3.1] — 2026-10-01
 
 ### Fixed

package/README.md

@@ -3,10 +3,38 @@
 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 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 +116,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 +156,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 +175,22 @@ 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 |
+
+`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 +209,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": 40,
   "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,158 @@
       ],
       "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"
     }
   }
 }

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,11 @@ 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. |
 | `engine` | enum: `auto`, `solo`, `harness`, `subprocess` |  | `"auto"` |  |
 | `harnesses` | array<string> |  | — |  |
 | `harness` | object |  | — |  |
@@ -140,6 +146,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.1",
+  "version": "0.4.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,7 @@
     "scripts",
     "!scripts/release.mjs",
     "!scripts/changelog.mjs",
+    "!scripts/known-fix.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -39,7 +40,8 @@
     "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"
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",

package/schema/code-forge.schema.json

@@ -36,7 +36,8 @@
         "L0": { "$ref": "#/$defs/level" },
         "L1": { "$ref": "#/$defs/level" },
         "L2": { "$ref": "#/$defs/level" },
-        "L3": { "$ref": "#/$defs/level" }
+        "L3": { "$ref": "#/$defs/level" },
+        "coder_floor_docs": { "type": "string", "enum": ["L0", "L1", "L2"], "default": "L1" }
       }
     },
     "orchestrator": { "$ref": "#/$defs/levelName" },
@@ -85,7 +86,9 @@
         "retries_per_level": { "type": "integer", "minimum": 0, "default": 2 },
         "review_rounds_per_level": { "type": "integer", "minimum": 0, "default": 2 },
         "stop_at": { "type": "string", "const": "L3", "default": "L3" },
-        "l3_mode": { "type": "string", "enum": ["patch", "code"], "default": "patch" }
+        "l3_mode": { "type": "string", "enum": ["patch", "code"], "default": "patch" },
+        "after_rounds_with_warnings": { "type": "integer", "minimum": 0, "default": 1 },
+        "warning_threshold": { "type": "integer", "minimum": 1, "default": 2 }
       }
     },
     "review": {
@@ -93,6 +96,8 @@
       "additionalProperties": false,
       "properties": {
         "multimodel": { "type": "boolean", "default": false },
+        "multimodel_for_docs": { "type": "boolean", "default": false },
+        "single_reviewer_max_risk": { "type": "number", "minimum": 0, "maximum": 3, "default": 1 },
         "second_provider": { "anyOf": [{ "$ref": "#/$defs/provider" }, { "type": "null" }], "default": null },
         "second_levels": {
           "anyOf": [
@@ -133,10 +138,11 @@
         },
         "min_tokens_out": { "type": "integer", "minimum": 1, "default": 120 },
         "batch_small_files": { "type": "boolean", "default": true },
-        "session_timeout_s": { "type": "integer", "minimum": 1, "default": 600 },
+        "session_timeout_s": { "type": "integer", "minimum": 1, "default": 300 },
         "max_rounds_per_file": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 },
         "recheck_scope": { "type": "string", "enum": ["fix_hunks", "file"], "default": "fix_hunks" },
-        "late_findings": { "type": "string", "enum": ["sweep", "block"], "default": "sweep" }
+        "late_findings": { "type": "string", "enum": ["sweep", "block"], "default": "sweep" },
+        "allow_open_book_codex": { "type": "boolean", "default": false, "description": "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." }
       }
     },
     "engine": { "type": "string", "enum": ["auto", "solo", "harness", "subprocess"], "default": "auto" },
@@ -228,6 +234,11 @@
         "block_tokens_soft": { "type": "integer", "minimum": 1 },
         "block_tokens_hard": { "type": "integer", "minimum": 1 },
         "run_usd_soft": { "type": "number", "minimum": 0 },
+        "usd": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "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%."
+        },
         "block_cases": { "type": "integer", "minimum": 10, "default": 80 }
       }
     },

package/skill/SKILL.md

@@ -18,7 +18,7 @@ You are the **orchestrator**: the session that invoked this skill. You dispatch,
 
 `/code-forge plan|harden|code|full [brief file | plan file]`. No job given ⇒ infer it: a brief ⇒ `plan`; a plan whose header says `status: planned` ⇒ `harden`; `status: hardened` ⇒ `code`. `full` runs the three in order with one human checkpoint after `harden`.
 
-State lives in the plan file's header — `facts → planned → hardened → coding → done` — and in the run record: `forge run status --run <id>` prints the active blocks, `forge ledger tail --slug <slug>` the last rows. Takeover after a lost session: `references/continuity.md`.
+State lives in the plan file's header — `facts → planned → hardened → coding → done` — and in the run record: `forge run status --run <id>` prints the active blocks, `forge ledger tail --slug <slug>` the last rows. Takeover after a lost session: `references/continuity.md`. A config change mid-run (a model swap, the review topology) is `forge run reload --run <id>` — never `block stop` + `run end` + `run start` (`references/continuity.md` §4).
 
 ## §2 Roles by level (never by model name)
 
@@ -27,7 +27,7 @@ State lives in the plan file's header — `facts → planned → hardened → co
 | facts delegate | L0 | read-only tools, empty cwd | `forge facts` |
 | coder | the lane S1 picks (L0–L2); climbs one rung per escalation | the project tree | the engine adapter |
 | reviewer, recheck | L2 | closed-book, empty cwd, packet on stdin | the worker |
-| judge, S2, author | L3 | closed-book, one turn | the worker, `forge s2`, `forge author` |
+| judge, S2, author | L3 | closed-book, one turn (never Codex: `references/security.md` §4) | the worker, `forge s2`, `forge author` |
 | L3 rung | L3 | a patch ≤ 80 lines, once per block | `forge spawn --level L3 --role coder` |
 
 `forge resolve L<n>` prints what a level resolves to (provider, model, effort, fallback); `forge models` lists the catalog. With `review.multimodel` on, the second reviewer is another provider's L2 and the judge comes from a third provider.
@@ -36,12 +36,12 @@ State lives in the plan file's header — `facts → planned → hardened → co
 
 1. `forge facts --brief <brief> --out <plans_dir>/<slug>.facts.md` — an L0 delegate checks every claim with a read-only command. You read the sheet; you never read the sources yourself (`references/plan.md` §0).
 2. `forge author --job plan --brief <brief> --facts <sheet> --out <plan>` — refuses without `--facts` (exit 2) and refuses a sheet older than the brief. The draft's §0 is the sheet, verbatim.
-3. Harden: `forge author --job harden --brief <brief> --facts <sheet> --draft <plan> --answers <file>` until `questions[]` is empty. The human answers; you relay, never answer for them (`references/harden.md`). Exit gate: `forge plan check <plan>` green.
-4. Per block, in dispatch order, never more than `caps.coders` alive: `forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> --brief <file> --lines <n>` prints the pointer `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>`. Send the pointer per the engine's adapter — `solo` → `references/adapters/solo.md`, `harness` → `references/adapters/claude-code.md`, `subprocess` → `references/adapters/subprocess.md` — and wait for `ACK <sha8> lines=<n>`.
+3. Harden: `forge author --job harden --brief <brief> --facts <sheet> --draft <plan> --answers <file>` until `questions[]` is empty. The human answers; you relay, never answer for them (`references/harden.md`). Before the exit gate, record each block's lane: `forge jev ask lane --block <id> --plan <plan> --state <file>` (`--rules` without Jev); the plan's level must equal it. Exit gate: `forge plan check <plan>` green, with a lane for every block on its `lanes:` line (`references/plan.md`).
+4. Per block, in dispatch order, never more than `caps.coders` alive: `forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> --brief <file> --lines <n> [--kind code|docs|contract]` prints the pointer `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>`. Send the pointer per the engine's adapter — `solo` → `references/adapters/solo.md`, `harness` → `references/adapters/claude-code.md`, `subprocess` → `references/adapters/subprocess.md` — and wait for `ACK <sha8> lines=<n>`.
 5. The coder's first message is its **facts diff**, then its forecast (cases and lines, `templates/block-record.md`), then code, file by file: after each file `forge review-file <path> --block <id> --run <r>`, then `forge review-file --wait <ticket>` before the next file. Rounds ≥ 2 re-check only the fix hunks (`references/review.md`).
 6. `===BLOCK <id> COMPLETE===` or `===BLOCK <id> FAILED: <reason>===` ends the coder's turn. Its report is a claim sheet: re-measure it (`references/code.md` §5).
-7. `forge block close <id> --run <r>` is the gate: a signed `review.approved` row per changed file, gates green, every clause covered, forecast vs actual, no `rule_break`. Red ⇒ `references/decisions.md` (S1 `next`, escalation). Green ⇒ one commit for the block in the project's house style; `forge block rebase <id> --run <r>` first when HEAD moved.
-8. `forge run end --run <r>` when every block is `done`; `forge report --slug <slug>` prints cost per block, escalations and review rounds.
+7. `forge block close <id> --run <r> --report <coder report>` is the gate: a report without a `reviewed <path> ticket <id>` line per changed file is FAILED; a signed `review.approved` row per changed file, gates green, every clause covered, forecast vs actual, no `rule_break`. Red ⇒ `references/decisions.md` (S1 `next`, escalation). Green ⇒ one commit for the block in the project's house style; `forge block rebase <id> --run <r>` first when HEAD moved.
+8. `forge run end --run <r>` when every block is `done`; `forge report --slug <slug>` prints cost per block, escalations, review rounds and the spend per run (`budget.usd`, `references/ledger.md` §3.1).
 
 ## §4 Hard rules (the headings of `references/rules-core.md`)
 
@@ -68,7 +68,7 @@ State lives in the plan file's header — `facts → planned → hardened → co
 |---|---|
 | decomposing, forecasting, `plan check` | `references/plan.md`, `templates/plan.md`, `templates/facts-sheet.md` |
 | the author loop and the tranche gate | `references/harden.md` |
-| briefing a coder, the block gate, the PR contract, Definition of Done | `references/code.md`, `templates/block-record.md` |
+| briefing a coder, the block gate, the PR contract, Definition of Done | `references/code.md`, `templates/coder-brief.md`, `templates/block-record.md` |
 | review depth, packets, the convergence rule, `block waive` | `references/review.md` |
 | System 1 / System 2, thresholds, escalation, the L3 rung | `references/decisions.md` |
 | proof tiers, red→green, the measurement export | `references/proof.md` |

package/skill/references/adapters/claude-code.md

@@ -12,7 +12,7 @@ The harness's `Agent` tool runs the coder as a subagent; everything else — the
 
 The tool return is the completion signal; the report must begin with `ACK <sha8>` and end with `===BLOCK <id> COMPLETE===` (+ test summary + `git diff --stat`) or `===BLOCK <id> FAILED: <reason>===`. A report without the sentinel is a failed block, never a partial success.
 
-**Between completion and close come the review rounds.** The subagent ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket inside its turn, so most rounds happen before the sentinel; when the tool returns, first drain every `pending` ticket with `forge review-file --wait <ticket>` yourself — a pending ticket is a review in flight, not an open finding, and waiting on it costs no round. Then only an open `fix_now` finding, or a file the coder never submitted, starts a fix round (each one counts toward the file's cap): dispatch a new `Agent` call at the level the ladder says (`review.md` §5 — the coder is gone with its tool return, so the fix brief carries the open findings and the fix history) and it runs `review-file` again on the fixed file. Rounds are bounded: four rounds per file, then the L3 rung once, then `stopped: review_cap` for the human. Only when every changed file has a signed `review.approved` row do you run the re-measurement of `code.md` §5 and `forge block close <id> --run <r>` — the transcript grep reads `.code-forge/runs/<run>/<block>.log`; pass `--transcript <file>` when the harness saved the subagent's transcript elsewhere. Closing with a file still unreviewed is a human decision: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, or `forge block close … --no-require-reviews`, both audited as their own rows.
+**Between completion and close come the review rounds.** The subagent ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket inside its turn, so most rounds happen before the sentinel; when the tool returns, first drain every `pending` ticket with `forge review-file --wait <ticket>` yourself — a pending ticket is a review in flight, not an open finding, and waiting on it costs no round. Then only an open `fix_now` finding, or a file the coder never submitted, starts a fix round (each one counts toward the file's cap): dispatch a new `Agent` call at the level the ladder says (`review.md` §5 — the coder is gone with its tool return, so the fix brief carries the open findings and the fix history) and it runs `review-file` again on the fixed file. Rounds are bounded: four rounds per file, then the L3 rung once, then `stopped: review_cap` for the human. Only when every changed file has a signed `review.approved` row do you run the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --report <file>` (the subagent's final report, saved to a file) — the transcript grep reads `.code-forge/runs/<run>/<block>.log`; pass `--transcript <file>` when the harness saved the subagent's transcript elsewhere. Closing with a file still unreviewed is a human decision: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, or `forge block close … --no-require-reviews`, both audited as their own rows.
 
 ## §3 What is lost and what is not