@codedology/code-forge 0.3.1 → 0.4.0

package/skill/references/adapters/solo.md

@@ -22,7 +22,7 @@ Solo adds spawn, watch, timers, scratchpads, locks and `kv` on top of the CLI; i
 5. **Wake channels, event-driven, never fixed polls:** record your own pid once (`whoami` → `kv_set("forge:orchestrator_pid")`); coders that can call Solo carry the push contract (post-sentinel `kv_set("block:<id>", …)` + `timer_set(1s, body, delivery_process_id=<your pid>)`); for every group arm `timer_fire_when_idle_any([coders], max_wait≈20–25 min, delivery_process_id=<your pid>)` right after the launch gate (idle-any ignores already-idle processes, so arm while they are provably running); keep one long dead-man fallback per 30–40 min with an L0 triage first. On wake: sentinel ⇒ gate; no sentinel and active again ⇒ re-arm; no sentinel and idle ⇒ parked, intervene now.
 6. Completion = `search_output(pattern="===BLOCK <id> COMPLETE===")`, last occurrence (the `kv` key is the truncation backup). Completion is not closure.
 7. **Review rounds, with the coder still alive.** The coder ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket; read the ledger (`forge ledger tail --slug <slug>`) for what is still open — a `fix_now` finding, a `pending` ticket, a file never submitted. Each open finding is a fix round sent to the **warm coder** by `send_input` (the findings by id, `<<<EOM>>>`), which fixes and re-runs `review-file` on that file; round ≥ 2 re-checks only the fix hunks (`review.md` §5). **One ladder** (`decisions.md` §5): a stall or exhausted rounds *below L2* climbs one level — close this coder and respawn a fresh one at the higher level with the open findings and the fix history in its brief; **the respawn keeps the per-file round count**, the cap does not reset. L2 is the highest running level: a trigger at L2, or the four-round cap on a file, goes to the **L3 rung once** — a fresh L3 patch session, never this coder and never a coder at L3 — and if findings stay open after the `patch_check` round the file is `stopped: review_cap` for the human. No other path exists.
-8. **Close** only when every changed file has a signed `review.approved` row: the re-measurement of `code.md` §5, then `forge block close <id> --run <r>` — the transcript grep reads the Solo output. Closing with a file still unreviewed is a human decision, audited: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, or `forge block close … --no-require-reviews`.
+8. **Close** only when every changed file has a signed `review.approved` row: the re-measurement of `code.md` §5, then `forge block close <id> --run <r> --report <file>` (the coder's final report) — the transcript grep reads the Solo output. Closing with a file still unreviewed is a human decision, audited: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, or `forge block close … --no-require-reviews`.
 9. **Reap after the close**: `close_process` the coder and confirm `lock_status` shows no lease before the next group. Locks: a coder that can call Solo holds `lock_acquire` on its file area while editing; coders that cannot never overlap another block.
 
 ## §4 Latency overlaps (standing)

package/skill/references/adapters/subprocess.md

@@ -8,7 +8,7 @@ Never selected automatically (`degraded.md` §1). Coders are detached CLI proces
 
 ## §2 Completion and evidence
 
-The coder's stdout is captured; completion is the **last** `===BLOCK <id> COMPLETE===` or `===BLOCK <id> FAILED: <reason>===` line in it (a quoted sentinel inside a sentence never matches). Process exit without a sentinel is a failed block. Then the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --transcript <captured stdout>` — the transcript grep runs on the capture. A coder that hangs is killed at `--timeout` together with its process group; the pid entry is cleared.
+The coder's stdout is captured; completion is the **last** `===BLOCK <id> COMPLETE===` or `===BLOCK <id> FAILED: <reason>===` line in it (a quoted sentinel inside a sentence never matches). Process exit without a sentinel is a failed block. Then the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --transcript <captured stdout> --report <captured stdout>` — the transcript grep runs on the capture. A coder that hangs is killed at `--timeout` together with its process group; the pid entry is cleared.
 
 ## §3 What the coder's sandbox looks like per provider
 

package/skill/references/code.md

@@ -10,12 +10,13 @@ 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>] --lines <n>` records the base sha, the owned files (overlap with another active block ⇒ refused), the level, 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. 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), 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:
 
 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.
 3. The file loop: *after you finish each file in `owned_files` (tests written and green) run `forge review-file <path> --block <id> --run <r>`; before the next file run `forge review-file --wait <ticket> [--max 90s]` and act on the packet.* A `worker_down` answer ⇒ print `===BLOCK <id> FAILED: worker down===` (never approval).
-4. The project's own rules digest (`CLAUDE.md`/`AGENTS.md`, ≤ 60 lines), the forbidden list verbatim (`security.md` §2), and the sentinel contract: `===BLOCK <id> COMPLETE===` followed by the test summary and `git diff --stat`, or `===BLOCK <id> FAILED: <reason>===`.
+4. The project's own rules digest (`CLAUDE.md`/`AGENTS.md`, ≤ 60 lines), the forbidden list verbatim (`security.md` §2), and the sentinel contract: `===BLOCK <id> COMPLETE===` followed by the test summary, `git diff --stat` and one `reviewed <path> ticket <ticket-id>` line per changed file, or `===BLOCK <id> FAILED: <reason>===`.
+5. **FAILED unless** (`templates/coder-brief.md`): a final report — first attempt or fix round — that does not list the `review-file` ticket id of every changed file counts as FAILED whatever its sentinel says. Pass the report to the gate with `forge block close <id> --run <r> --report <file>`; it refuses `coder report FAILED: no review-file ticket id for <files>`.
 
 The brief never mentions `block waive`, keys, or `~/.code-forge/runs/`. The coder process gets no Jev key (the System 1 model's key, `keys.jev`) and no signer key.
 
@@ -30,7 +31,7 @@ The coder's report is a claim sheet. The gate reproduces each number in the meas
 | claim | re-measured by |
 |---|---|
 | only owned paths touched | file set = tracked changes ∪ untracked, minus other active blocks' owned sets ⊆ `owned_files`; anything else is an orphan that stops every gate until `forge block claim <id> <path> --run <r>` or the human deletes it |
-| every file reviewed | a **signed** `review.approved` row for the current content hash of every changed or new file, or an architect-ruled disposition to a named successor block |
+| every file reviewed | the report names a `review-file` ticket id per changed file (`--report`, which the orchestrator always passes) and a **signed** `review.approved` row for the current content hash of every changed or new file, or an architect-ruled disposition to a named successor block |
 | tests green | every gate command run once in the export, each exit status read |
 | clauses covered | every clause names ≥ 1 test id; each test exists and passed in this run; S1 `scope` on the hunks outside the named tests says `false` |
 | test count | the filtered run's delta equals the new tests' own count |

package/skill/references/continuity.md

@@ -29,3 +29,7 @@ Symptoms: a PR flips to conflicting, or its diff suddenly shows the whole stack;
 - **Duplicate-append is the common conflict** in append-only files: read every hunk anyway — one in four is a genuinely different block.
 - **Prove with a tree comparison:** `git diff <pre> <post>` empty when the merge reconciles history only; `git merge-base --is-ancestor`; the line count back to block size. Merged ≠ in the default branch: check both.
 - **Re-run classifiers and forecasts after any base change**: a size or hot-file figure taken across a stale base is not a number.
+
+## §4 A config change mid-run
+
+Edit `.code-forge.yml`, then `forge run reload --run <id>`. It validates the file (an invalid one is refused, nothing changes), prints the changed key paths — never values — and writes a signed `run.reload` row with the old and new snapshot hashes; no change prints `no config change` and writes nothing. Open blocks stay open at their attempt numbers; review tickets already queued finish on the config they were enqueued with, new tickets use the new one, and the worker picks it up without a restart. `project.slug`, `engine`, `tmp.root`, `keys`, `system1.key` and `version` are fixed for the run: a change to one is refused by name — put it back, or end the run and start a new one. Never `block stop` + `run end` + `run start` + `block open --attempt n+1` for a config change.

package/skill/references/decisions.md

@@ -6,7 +6,7 @@ Deterministic tools answer facts (gates, diffs, counts). **System 1 (S1)** answe
 
 | id | type | fires | answers |
 |---|---|---|---|
-| `lane` | choice | plan, per block; code, on re-decomposition | `L0` trivial · `L1` a plain feature following an existing pattern · `L2` money, dates, tenancy, migrations, concurrency, unknown failure · `split` too large or two concerns. **L3 is not a lane** |
+| `lane` | choice | plan, per block (`--block <id>`: `plan check` reads it); code, on re-decomposition | `L0` trivial · `L1` a plain feature following an existing pattern · `L2` money, dates, tenancy, migrations, concurrency, unknown failure · `split` too large or two concerns. **L3 is not a lane** |
 | `risk` | score 0–3 | plan, per block; code, per finished file | `0` cosmetic · `1` wrong behaviour, easy to notice and revert · `2` silent wrong data for some users · `3` silent wrong money or a cross-tenant leak |
 | `security_sensitive` | yes/no | plan, per block; code, per file unless path floors already forced `high` | touches authentication, authorization, tenancy, secrets, money movement or webhook verification |
 | `next` | choice | code, after each attempt's tool gate | `complete` all green, tests added or `no_new_tests_reason` given · `retry` a contained failure the same coder fixes in one more attempt · `escalate` repeated or spreading failures, or a risky area · `stop` the evidence contradicts the brief — the human decides |
@@ -33,10 +33,13 @@ No key ⇒ a banner at run start; 401 ⇒ stop; 422 ⇒ stop with the request id
 1. **Attempts:** attempts at the current level equal `escalation.retries_per_level` and not green ⇒ +1 level, whatever S1 said (`retries`).
 2. **Review rounds:** `escalation.review_rounds_per_level` exhausted with an open `fix_now` ⇒ +1 level (`review_rounds`).
 3. **Review stall:** a re-check round whose open `fix_now` set did not strictly shrink ⇒ +1 level at once (`review_stall`, `review.md` §5).
-4. **Security floor, at dispatch:** `security_sensitive` ⇒ first-attempt level `min(max(lane, L1) + 1, L2)` (`security`).
+3a. **Heavy rounds:** below L2, `escalation.after_rounds_with_warnings` (default 1) rounds at the current level whose open `fix_now` set holds ≥ `escalation.warning_threshold` (default 2) warnings or any `critical` ⇒ +1 level at once (`review_warnings`). A cheap coder that fails a round with several warnings climbs; it never spends three rounds at the same level. At L2 it does not fire — the L3 rung keeps its own triggers (rules 2, 3, 6). `after_rounds_with_warnings: 0` turns it off.
+4. **Security floor, at dispatch:** `security_sensitive` ⇒ first-attempt level `min(max(lane, L1) + 1, L2)` (`security`). Then the **docs floor**: a `docs` or `contract` block (below) is never dispatched under `levels.coder_floor_docs` (default L1) — `forge block open` raises the level and the `dispatch` row carries `requested_level` and `trigger: docs_floor`. L0 never codes docs or contracts.
 5. **S2 ruling:** S1 `next = escalate` is never acted on directly — it goes to S2 as a check (`s2_ruling`); S1 `next = stop` ⇒ the human.
 6. **Review cap:** `review.max_rounds_per_file` reached on a file with an open `fix_now` ⇒ the L3 rung for that file, once per block, always as a patch whatever `escalation.l3_mode` says (`review_cap`); checked last, only when no rule above returned an action this attempt.
 
+**Block kind.** `forge block open --kind code|docs|contract` declares it; without the flag it is detected from the owned paths: every path ends in `.md .mdx .markdown .rst .adoc` ⇒ `docs` (`.txt` is not docs: `requirements.txt`); every path is docs or a contract (`*.schema.json|yaml|yml`, `.proto`, `.graphql`, `.gql`, `.avsc`, `*.openapi.json|yaml|yml`, or a `.json/.yaml/.yml` under a `schema/`, `schemas/`, `contract/` or `contracts/` directory) and one is a contract ⇒ `contract`; anything else ⇒ `code`. A glob is judged by its literal ending, so a block owning `docs/**` declares its kind. The kind is recorded in the run record and drives the docs floor (rule 4) and the review topology (`review.md` §2).
+
 **The ceiling constraint (not a ranked rule).** *Never skip a level* constrains every rule above: a "+1 level" is always the next level, and **the highest running level is L2**. When rule 1, 2 or 3 fires at L2 there is no coding level above, and the **L3 rung** takes over (§6): a patch session, never a coder at L3 — the block continues at L2 afterwards. `escalation.stop_at` = L3 (fixed) names that rung, not a level a coder runs at; `l3_mode: code` is the only way a coder runs at L3, and it is not the default. The rung is one per block from either source (a trigger at L2 or the review cap, rule 6): a second hit from either always `stop`s (`review_cap` for the cap; the ceiling reason for the trigger), so `stop_at` means something in every mode. A fresh coder spawned by a level climb inherits the file's round count: the cap counts rounds per file, not per coder.
 
 **Own-family adjudication (R9).** When the orchestrator and the coder share a model family, every ruling the orchestrator makes about that coder's work is a judgement inside the family: it is written as a ledger row named as such, and it is asymmetric — the orchestrator may **accept** a finding alone; it may **not dismiss, defer or waive** one. Dismissals, cap raises and scope changes go to the architect (an L3 session) or the human.

package/skill/references/ledger.md

@@ -8,11 +8,17 @@ Events you will read most: `run.start`, `run.stop {reason}`, `run.end`, `dispatc
 
 ## §2 `forge report --slug <slug> [--json] [--export <dir>]`
 
-Terminal output in this version. Sections: cost per completed block (per level and lane, split review / coder / S1+S2 / facts / proof time) · lane distribution · escalations per block with `trigger` · S1 calls per block · S2 rate and overrule rate per question · the review budget table with `missed_after_degrade` per degrade step · review depth and context-mode distribution, findings by category and severity · fix rounds per file, rounds that stalled, files stopped at `review_cap` · `review.unavailable` by reason · proof time per block · forecast vs actual lines and cases with the measured lines-per-case · blocks stopped at L3 · `overspend` and `l3_fallback` counts · runs stopped for `no_engine`. `--export <dir>` writes one JSON file per section — the durable dataset a future UI reads.
+Terminal output in this version. Sections: cost per block — completed and still open, with `completed` and the count of unknown-price sessions (per level and lane, split review / coder / S1+S2 / facts / proof time) · lane distribution · escalations per block with `trigger` · S1 calls per block · S2 rate and overrule rate per question · the review budget table with `missed_after_degrade` per degrade step · review depth and context-mode distribution, findings by category and severity · fix rounds per file, rounds that stalled, files stopped at `review_cap` · `review.unavailable` by reason · proof time per block · forecast vs actual lines and cases with the measured lines-per-case · blocks stopped at L3 · `overspend` and `l3_fallback` counts · runs stopped for `no_engine`. `--export <dir>` writes one JSON file per section — the durable dataset a future UI reads. After the sections the terminal output prints the spend per run (open blocks included) and the total.
 
 ## §3 Live views
 
-`forge ledger tail --slug <slug> [--n <count>]` prints the last rows — the orchestrator's live view when no Solo process list exists. `forge run status --run <id>` prints the run record: active blocks, orphans, whether the worker is pinned.
+`forge ledger tail --slug <slug> [--n <count> | -n <count>]` prints the last rows — the orchestrator's live view when no Solo process list exists. `forge run status --run <id>` prints the run record: active blocks, orphans, whether the worker is pinned, and `spent_usd` / `budget_usd` / `unknown_usd_sessions`.
+
+## §3.1 Spend and `budget.usd`
+
+Every `session` row carries `usd` (tokens × the static price table) or `usd: null, usd_unknown: true` when the provider/level has no price — never a guess; a `session.background` coder's price is always unknown. Spend code-forge never saw (a cloud or hand-run coder) goes in with `forge ledger add coder --run <r> --block <b> --usd <n> [--note "..."]`, a signed `session` row with `manual: true`. With `budget.usd` set, every session spawn first sums the run's spend: at 80 % one `budget.warning` row and one stderr line per run; at 100 % the session is refused (`budget.usd 20.00 reached (spent 20.13); raise budget.usd or end the run`), a `budget.refused` row is written, nothing is spawned, and a review reports `review.unavailable {reason: budget}`. A budget whose spend cannot be read refuses too (fail closed).
+
+Known limits, accepted: unknown-price sessions and `session.background` coders add **0** to the spent total — record their real cost with `forge ledger add coder --usd <n>`; `forge run status` shows `unknown_usd_sessions` and prints `N sessions have no known price; the budget does not count them` when N > 0. Two sessions spawned at the same moment can each write a `budget.warning` row (a rare duplicate; the warning still means the same thing).
 
 ## §4 Calibration — `forge ledger calibration --slug <slug> [--question <id>]`
 

package/skill/references/plan.md

@@ -13,7 +13,7 @@ Run `forge facts --brief <brief> [--sources <path>...] --out <plans_dir>/<slug>.
 
 ## §1 The author job
 
-`forge author --job plan --brief <brief> --facts <sheet> --out <plan>` runs a fresh L3 closed-book session (empty cwd, the packet on stdin) and returns `{draft, questions[], cost}`. It refuses without `--facts` (exit 2, `facts sheet required: run forge facts first`) and refuses a sheet older than the brief. The draft follows `templates/plan.md`; its §0 **is** the facts sheet, verbatim, and it must contain the section "Acceptance clauses the facts sheet cannot back" — `none` when empty, never absent.
+`forge author --job plan --brief <brief> --facts <sheet> --out <plan>` runs a fresh L3 closed-book session (empty cwd, the packet on stdin) and returns `{draft, questions[], cost}`. It refuses without `--facts` (exit 2, `facts sheet required: run forge facts first`) and refuses a sheet older than the brief. The draft follows `templates/plan.md`; its §0 **is** the facts sheet, verbatim, and it must contain the section "Acceptance clauses the facts sheet cannot back" — `none` when empty, never absent. The author's packet carries the exact required headings from the same list `plan check` reads (`src/session/plan-sections.mjs`).
 
 ## §2 Decomposition — what every block carries
 
@@ -22,7 +22,7 @@ Run `forge facts --brief <brief> [--sources <path>...] --out <plans_dir>/<slug>.
 | `id`, `title` | one deliverable per block |
 | `owned_files` | exact paths or disjoint globs; a glob never contains `[ ] ( ) ! + @` (an exact path may); pairwise disjoint across blocks that can run together |
 | `depends_on` | acyclic; a block imports only modules of blocks it depends on — a batch-mate's module is a `next = stop` |
-| `level` | the S1 `lane` answer (`L0` trivial · `L1` a plain feature following a pattern · `L2` money, dates, tenancy, migrations, concurrency · `split` too large or two concerns); **L3 is not a lane** |
+| `level` | the S1 `lane` answer recorded for the block — `forge jev ask lane --block <id> --plan <plan> --state <file>`, or `--rules` (the deterministic fallback) when Jev is unavailable; never a block category (`L0` trivial · `L1` a plain feature following a pattern · `L2` money, dates, tenancy, migrations, concurrency · `split` too large or two concerns); **L3 is not a lane** |
 | `acceptance` | clauses that each name ≥ 1 test id; a clause citing a flag, path, version or API cites a VERIFIED fact id or sits in the unbackable list with a tolerance naming this block |
 | `cases`, `lines` | forecasts: `cases = 2 × counted clauses`, `lines = 26 × cases` with a floor of 1 200 for a greenfield block and 500 for an amendment; above `budget.block_cases` or `budget.block_lines` the block is split in the plan, never "split-ready" |
 | `test_command` | a quoted glob or an explicit file list, never a bare directory |
@@ -36,7 +36,7 @@ Every clause of the parent's acceptance maps to exactly one block; an unmapped c
 
 ## §4 The deterministic exit — `forge plan check <plan> [--facts <sheet>]`
 
-Prints every failing row by name and exits 1 on any of: an acceptance clause with a claim token that resolves to no VERIFIED fact and no tolerance row (`unbackable clause without tolerance: <block> <clause>`); a missing caller map or a block absent from it; a block without `cases` and `lines`; a forecast above `budget.block_cases` / `budget.block_lines` without a named split; overlapping `owned_files` in one wave; a cyclic `depends_on` or an import of a batch-mate; a glob with `[ ] ( ) ! + @`; more than `caps.coders` concurrent blocks in a slot; `questions[]` still open; the facts sheet's sha absent from the draft. Green ⇒ set `status: hardened` after the harden job (`harden.md`), never before.
+Prints every failing row by name and exits 1 on any of: an acceptance clause with a claim token that resolves to no VERIFIED fact and no tolerance row (`unbackable clause without tolerance: <block> <clause>`); a missing caller map or a block absent from it; a block without `cases` and `lines`; a forecast above `budget.block_cases` / `budget.block_lines` without a named split; overlapping `owned_files` in one wave; a cyclic `depends_on` or an import of a batch-mate; a glob with `[ ] ( ) ! + @`; more than `caps.coders` concurrent blocks in a slot; `questions[]` still open; the facts sheet's sha absent from the draft; a block whose level has no recorded lane, or differs from it (`block <id>: level L2 differs from the recorded lane L1 (jev)`). A required section under a near-miss heading at its template position (§0.x, §3) passes with a `WARN` naming the exact heading. stdout ends with the lane recorded per block (`lanes: B1 L1 (jev) · B2 L0 (rules)`). Green ⇒ set `status: hardened` after the harden job (`harden.md`), never before.
 
 ## §5 Cost
 

package/skill/references/review.md

@@ -4,11 +4,13 @@
 
 `forge review-file <path> --block <id> --run <r>` enqueues a ticket and returns `{ticket, status: queued}` in under a second; `forge review-file --wait <ticket> [--max 90s]` polls it. The worker computes the diff itself against the base sha `forge block open` recorded: tracked changes plus untracked files, filtered by `owned_files` for the review and unfiltered for the scope check. A coder that never calls `review-file` gains nothing: the block gate refuses any changed or new file without a signed `review.approved` row for its final content hash. The reviewer is always a new OS process (R1, R10) — identical under Solo, a harness subagent, a detached CLI process, or a human typing.
 
-## §2 Depth by risk (adaptive mode, `review.multimodel` off)
+## §2 Depth by risk (adaptive mode)
+
+The topology is decided in one place (`planSessions`). Consensus (§6) runs only when `review.multimodel` is on **and** the file's risk is above `review.single_reviewer_max_risk` (default 1) **and** the block is not a `docs`/`contract` block (`decisions.md` §5) unless `review.multimodel_for_docs` is true (default false). Everything else is adaptive, below. Why: a consensus review of a four-file docs block cost $16.70 — review cost dominates, and a low-risk file gains nothing from a second provider.
 
 1. Tools on the file first: lint, types, the file's own tests. Red ⇒ `tools_red` back to the coder, no model review, ledger `gate.red`.
 2. S1 `risk` (path floors first; `confidence < check` ⇒ S2 picks the depth).
-3. Planned depth: `risk < 1` ⇒ one L2 `quick` · `1 ≤ risk < 2` ⇒ one L2 `full` · `risk ≥ 2` ⇒ two blind L2 sessions (lens A correctness, lens B contracts and security) plus an L3 judge that reads the two reports — and the diff only when `review.judge_sees_diff` is true.
+3. Planned depth: `risk < 1` ⇒ one L2 `quick` · `1 ≤ risk < 2`, or `risk ≤ review.single_reviewer_max_risk` ⇒ one L2 `full`, no judge · otherwise two blind L2 sessions (lens A correctness, lens B contracts and security) plus an L3 judge that reads the two reports — and the diff only when `review.judge_sees_diff` is true.
 4. Triage: findings from a single L2 session go to S1 `defect` (`thresholds.findings.fix` fix now · mid-band batched to one L3 ruling per file · below `thresholds.findings.nit` a nit). Findings that come from a judge are final.
 
 ## §3 Isolation and the packet
@@ -17,7 +19,7 @@ Every reviewer, recheck, judge and S2 session runs with cwd = a fresh empty temp
 
 ## §4 The stub guard — what counts as a review (R11)
 
-A result is a review only if the process exited 0, the JSON validates against the finding schema, `reviewed_hunks` equals the packet's hunk headers exactly and in order, and the output has at least `review.min_tokens_out` tokens. Anything else is ledger `review.unavailable` (`exit`, `schema`, `hunks_mismatch`, `too_short`, `timeout`) and **is not approval**; the worker retries once on the level's fallback, then the file stays unreviewed and the block cannot close. A session that hangs is killed at `review.session_timeout_s`, process group and all.
+A result is a review only if the process exited 0, the JSON validates against the finding schema, `reviewed_hunks` equals the packet's hunk headers exactly and in order, and the output has at least `review.min_tokens_out` tokens. Anything else is ledger `review.unavailable` (`exit`, `schema`, `hunks_mismatch`, `too_short`, `timeout`, `budget` — the run reached `budget.usd`, `ledger.md` §3.1) and **is not approval**; the worker retries once on the level's fallback, then the file stays unreviewed and the block cannot close. A session that hangs is killed at `review.session_timeout_s` (default 300), process group and all, and is spawned once more on the same packet and level; only a second timeout is `unavailable: timeout`. Each timed-out attempt leaves a `review.session_timeout` ledger note with the last 4 KB of its stderr (redacted, never the packet) and only the byte count and last event types of its stdout.
 
 ## §5 The convergence rule — bounded fix rounds (R15)
 
@@ -26,14 +28,15 @@ Per file, per block:
 1. Round 1 is the tiered review of §2 on the full packet.
 2. **Round n ≥ 2 reviews only the fix hunks**: the diff between the content hash reviewed in round n−1 and the current content, ± `review.context.hunk_context_lines`, plus the open findings by id (`review.recheck_scope: fix_hunks`, the default; `file` re-sends the whole packet for a consumer that wants it). The `recheck` lens answers `resolved[]` per finding — S1 `resolved` at or above `thresholds.findings.resolved` closes it, else the fresh L2 recheck decides — and may raise a new finding **only inside a fix hunk**; a finding outside becomes a `late_finding`, ruled at block close (`review.late_findings: sweep`; `block` makes it block the round).
 3. **Strictly shrinking**: the open `fix_now` set after round n is smaller than after round n−1, counting closures minus new in-hunk findings. Equal or larger ⇒ `review_stall` (rule 2b), a trigger at once.
-4. **Ladder**: the running ceiling is `min(L2, escalation.stop_at)` — L3 is never a *running* level. A trigger — rule 1 (`retries`), rule 2 (`escalation.review_rounds_per_level` exhausted with an open `fix_now`) or rule 2b (`review_stall`) — below the ceiling climbs one level, coded by a fresh session with the open findings and the fix history in its brief (an L1 block's rounds 3–4 run at L2). At the ceiling — an L2 block, or an L1 block that has climbed to L2 — it takes the **L3 rung**: a patch ≤ 80 lines, owned files only, reviewed as a `patch_check` round outside the cap. Under `escalation.l3_mode: code` (opt-in) the rung is instead one L3 coding turn. Either way the rung fires **once per block** and the same post-patch order follows it. After it, in order: `patch_check` clean ⇒ complete; open set not smaller than before the patch ⇒ `stopped: l3_patch_exhausted` (`review_stall`); round ≥ `review.max_rounds_per_file` ⇒ `stopped: review_cap`; otherwise the fixes continue at L2 with `rounds_at_level` reset and the patch in the brief. Any later trigger in that block stops with its named reason (`l3_patch_exhausted`, `review_cap`) and never patches again.
+3a. **Heavy rounds climb at once** (`review_warnings`, `decisions.md` §5 rule 3a): below L2, a round — round 1 included — that leaves ≥ `escalation.warning_threshold` (2) warnings or any `critical` open, `escalation.after_rounds_with_warnings` (1) times at the current level, climbs one level for the next fix. One round with a stronger model is faster and cheaper than three with a cheap one. The per-file cap (step 5) stays the outer limit.
+4. **Ladder**: the running ceiling is `min(L2, escalation.stop_at)` — L3 is never a *running* level. A trigger — rule 1 (`retries`), rule 2 (`escalation.review_rounds_per_level` exhausted with an open `fix_now`), rule 2b (`review_stall`) or step 3a (`review_warnings`) — below the ceiling climbs one level, coded by a fresh session with the open findings and the fix history in its brief (an L1 block's rounds 3–4 run at L2). At the ceiling — an L2 block, or an L1 block that has climbed to L2 — it takes the **L3 rung**: a patch ≤ 80 lines, owned files only, reviewed as a `patch_check` round outside the cap. Under `escalation.l3_mode: code` (opt-in) the rung is instead one L3 coding turn. Either way the rung fires **once per block** and the same post-patch order follows it. After it, in order: `patch_check` clean ⇒ complete; open set not smaller than before the patch ⇒ `stopped: l3_patch_exhausted` (`review_stall`); round ≥ `review.max_rounds_per_file` ⇒ `stopped: review_cap`; otherwise the fixes continue at L2 with `rounds_at_level` reset and the patch in the brief. Any later trigger in that block stops with its named reason (`l3_patch_exhausted`, `review_cap`) and never patches again.
 5. **Cap — four rounds per file** (`review.max_rounds_per_file`, default 4, range 2–6). Round 4 still open ⇒ the L3 rung if the block has not used it (same post-patch order as step 4), else `stopped: review_cap`. A stop means the block cannot close, the ledger lists the open findings, and the human decides — fix by hand, `forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>` (a signed `review.waived` row, `by: human`), or re-decompose. The coder never sees a `waive` verb; it is on the forbidden list.
 6. **Block-close sweep**: `forge block close` batches the `late_findings` per file to one L3 judge ruling (`fix_now | nit`); a `fix_now` opens a round on that file at the block's current level and counts toward its cap.
 7. Ledger: one `review.round` row per round with `open_before`, `closed`, `new_in_hunks`, `late`, `open_after`; `forge report` prints rounds per file and rounds that stalled.
 
 Rechecks are never degraded by the budget: a round-2+ packet is already the minimum.
 
-## §6 Consensus mode (`review.multimodel` on)
+## §6 Consensus mode (`review.multimodel` on, risk above `review.single_reviewer_max_risk`, not a docs/contract block unless `review.multimodel_for_docs`)
 
 Two L2 reviewers, one per effective provider (`resolve(L2)` and `review.second_levels`), each a fresh blind session with the `full` lens; then a fresh L3 judge **from the third provider** reads the two reports and returns the findings plus `agreement: both|A-only|B-only`. The judge's `fix_now` list is final. Second provider unavailable at run start ⇒ `consensus unavailable: <reason>`; ask the human once per run whether to continue adaptive, stop when non-interactive. Rechecks run on the provider that raised the finding; §5 applies unchanged.
 

package/skill/references/security.md

@@ -6,7 +6,7 @@
 
 ## §2 The forbidden list — one list, rendered per CLI at spawn, grepped from every transcript
 
-`gh pr ready|merge|close` and base retargets · `git push --force*` · `git reset --hard` · `git checkout --` · `git restore` · `git clean` · `git stash` · `git branch -D` · `git rm` · `rm -rf` outside `.code-forge/` · any argv containing a `production.markers` token or a `production.names` name · any read or write of `~/.code-forge/runs/` · `forge worker`, `run start` and `block waive` from a coder (also via `npx`) · any write under `.code-forge/reviews/` or `.code-forge/queue/*.done`.
+`gh pr ready|merge|close` and base retargets · `git push --force*` · `git reset --hard` · `git checkout --` · `git restore` · `git clean` · `git stash` · `git branch -D` · `git rm` · `rm -rf` outside `.code-forge/` · any argv containing a `production.markers` token or a `production.names` name · any read or write of `~/.code-forge/runs/` · `forge worker`, `run start`, `run reload` and `block waive` from a coder (also via `npx`) · any write under `.code-forge/reviews/` or `.code-forge/queue/*.done`.
 
 Rendered into every coder spawn as the CLI's own deny rules (path rules widen a directory to `<dir>/**`; a read-write path denies read, edit and write); carried verbatim in the brief; refused by the package's own process spawner; and at block close the transcript (captured stdout, the harness log, or the Solo output) is grepped for the forbidden verbs **and paths** — a hit is a `rule_break` row that fails the gate. Where a CLI cannot load a rules file, `doctor` says so and the transcript grep remains the detector.
 
@@ -24,6 +24,8 @@ Rendered into every coder spawn as the CLI's own deny rules (path rules widen a
 
 Reviewer, recheck, judge, S2, author and facts sessions run in print mode with the provider's own isolation flags, cwd = an empty temp dir under the run's temp root, and the packet on stdin; `doctor` proves that no project document is visible (it asks the reviewer builder to echo the first line of the project's rules file and expects nothing) and that the coder builder cannot read a known file outside the workspace (`claude: path deny rules not honoured` when it can). The facts delegate gets read-only shell tools with every write verb denied.
 
+Codex has no mode without a shell: `-s read-only` still lets it read any absolute path. So openai is refused for reviewer, judge, S2 and author. `validate` warns, `resolve` prints `closed_book: "refused"`, the spawner refuses the session (an openai fallback is skipped), and `doctor` FAILs the isolation row with `codex cannot run closed-book yet: it always has a shell; use anthropic or xai for reviewer, judge, S2 and plan author`. Coders and the facts delegate still run on Codex. The opt-in `review.allow_open_book_codex: true` (default off) lets Codex run those roles with its read-only argv; `validate` then warns `codex reviewer is not closed-book: it can read files on this machine (review.allow_open_book_codex)`, `resolve` prints `closed_book: "open-book (allowed)"`, and `doctor` runs the isolation probe and reports WARN.
+
 ## §5 What the package itself never does
 
 No telemetry (`telemetry: off`, reserved). No `postinstall`. No secret in argv — a keychain write goes through stdin. Temp dirs live under one per-run root and are swept by the next `run start`; the reaper kills only processes this package registered whose start time still matches — never a foreign pid. Every child `git` runs with inherited `GIT_*` variables stripped, so a gate invoked from a hook still sees the right repository.

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.3.1"
+PINNED_VERSION="0.4.0"
 set -eu
 
 self="$0"

package/skill/templates/coder-brief.md

@@ -0,0 +1,36 @@
+# Block `<id>` — `<title>` (coder brief)
+
+| field | value |
+|---|---|
+| level | `L<n>` (the lane recorded by `forge jev ask lane --block <id>`) |
+| owned_files | `<paths…>` — edit ONLY these |
+| acceptance | `<clause (test ids)>` · … |
+| test_command | `<quoted glob or explicit file list>` |
+
+## Reply contract
+
+1. `ACK <sha8> lines=<n>` before any tool call.
+2. Your facts diff: every contradiction between this brief and the code, in one message.
+3. Your forecast: cases and lines.
+
+## The file loop
+
+After you finish each file in `owned_files` (tests written and green) run `forge review-file <path> --block <id> --run <r>`; before the next file run `forge review-file --wait <ticket> [--max 90s]` and act on the packet. A `worker_down` answer ⇒ print `===BLOCK <id> FAILED: worker down===` (never approval).
+
+## Final report — FAILED unless it lists the ticket ids
+
+End with `===BLOCK <id> COMPLETE===`, the test summary and `git diff --stat`, then one line per changed file:
+
+`reviewed <path> ticket <ticket-id>`
+
+**FAILED unless:** the report lists the `review-file` ticket id of every changed file. A report with no ticket ids, or one that misses a changed file, counts as FAILED whatever its sentinel says: the orchestrator treats it as `===BLOCK <id> FAILED: no review-file ticket ids===` and `forge block close <id> --run <r> --report <file>` refuses it (`coder report FAILED: no review-file ticket id for <files>`). "All findings addressed" is not a report.
+
+Or `===BLOCK <id> FAILED: <reason>===`.
+
+## Fix-round brief (round ≥ 2, or a respawn after a climb)
+
+The open findings by id, the fix history, the files they sit in. Fix only those hunks, then run `forge review-file <path> --block <id> --run <r>` and `--wait` on **every file the round changed** — a fix the reviewer never saw is not a fix. The final report follows the same rule: one `reviewed <path> ticket <ticket-id>` line per file changed in the round, or the round counts as FAILED.
+
+## Project rules
+
+<!-- the project's rules digest (≤ 60 lines) and the forbidden list verbatim (`references/security.md` §2); what a brief never carries is in `references/code.md` §3 -->

package/skill/templates/plan.md

@@ -29,6 +29,8 @@ Chosen approach and why · rejected alternatives (one line each) · the project
 |---|---|---|---|---|---|---|---|---|---|
 | B1 | … | L1 | — | `src/x.mjs`, `test/x.test.mjs` | 12 | 1 200 | (1) … (`test/x.test.mjs`, F3) · (2) … | `node --test 'test/x/**/*.test.mjs'` | … |
 
+`level` is the lane recorded for the block by `forge jev ask lane --block <id>` (or `--rules`), never a category; `forge plan check` refuses any other.
+
 Split rule: `cases = 2 × clauses`, `lines = 26 × cases` (floor 1 200 greenfield, 500 amendment); above `budget.block_cases` or `budget.block_lines` the block is split here. A glob in `owned_files` never contains `[ ] ( ) ! + @`.
 
 ## §3 Caller map

package/src/cli/block.mjs

@@ -3,7 +3,7 @@
  * `block open` before every spawn in every engine; it prints the brief pointer (≤ 200 bytes).
  *
  *   block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file>
- *              [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <forecast>]
+ *              [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <forecast>] [--kind code|docs|contract]
  *   block attempt <id> --run <r>
  *   block rebase <id> --run <r> [--head <ref>]
  *   block claim <id> <path> --run <r>
@@ -11,7 +11,7 @@
  *   block stop <id> --run <r> --reason <text>
  *   block waive <id> <finding-id> --run <r> --file <path> --reason <text>   (human-only, §4.9)
  *
- * `block close [--transcript <file>] [--no-require-reviews]` also runs B12b's review rows
+ * `block close [--transcript <file>] [--report <file>] [--no-require-reviews]` also runs B12b's review rows
  * (`review/gate-check.mjs`): a signed `review.approved` row for the current content hash of every
  * changed owned file (deletions included) — `--no-require-reviews` is the human's way out, is
  * forbidden to coders (`mergeForbidden`), and leaves a signed `gate.reviews_waived {by: human}`
@@ -27,6 +27,12 @@
  * but does not load or validate refuses the close (a typo must never drop a high path), and a
  * base that is missing or not a commit of the workspace refuses it too (`git-failed`).
  *
+ * B36: `--report <file>` is the coder's final report. The check is enforced when `--report` is
+ * given (the orchestrator always passes it, `skill/references/code.md` §3): a changed owned file
+ * whose `review-file` ticket id the report does not name refuses the close with `coder report
+ * FAILED: no review-file ticket id for <files>` (skipped under `--no-require-reviews`, the human's
+ * way out). It runs after the review rows and reuses their file set (listed once).
+ *
  * `--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`.
@@ -49,14 +55,15 @@ import { validateConfig } from '../config/validate.mjs';
 import { migrateConfig } from '../config/migrate.mjs';
 import { exec } from '../util/exec.mjs';
 import { gitChildEnv } from '../worker/ticket.mjs';
+import { missingReviewTickets } from '../engines/sentinel.mjs';
 
 const USAGE =
-  'usage: code-forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>]\n' +
-  '       code-forge block attempt|rebase|close <id> --run <r> · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
+  'usage: 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]\n' +
+  '       code-forge 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>\n' +
   '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>\n';
 
 const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'];
-const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript'];
+const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
 
 /**
  * @param {string[]} args
@@ -106,9 +113,12 @@ export async function runBlock(args, deps = {}) {
         base: typeof flags.base === 'string' ? flags.base : undefined,
         lines: intFlag(flags.lines, 'lines') ?? null,
         brief,
+        ...(typeof flags.kind === 'string' ? { kind: flags.kind } : {}),
+        cfg: await openConfig(record.workspace),
         writeRow,
       });
-      out(`block ${id} open · ${block.level} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}\n`);
+      const raised = block.level !== flags.level ? ` (${block.kind} floor, asked ${flags.level})` : '';
+      out(`block ${id} open · ${block.level}${raised} · ${block.kind} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}\n`);
       out(`${pointer ?? 'brief: none given (--brief <file>)'}\n`);
       return 0;
     }
@@ -141,6 +151,11 @@ export async function runBlock(args, deps = {}) {
       if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
       const rows = (await readAllRows(record.project)).filter((row) => row.run === runId);
       const reviewsWaived = flags['no-require-reviews'] === true;
+      // the block's file set is listed once and shared by the review and report checks; a failure
+      // there is the usual `git-failed` refusal
+      /** @type {ReturnType<typeof blockFileSet> | undefined} */
+      let fileSetOnce;
+      const blockFiles = () => (fileSetOnce ??= blockFileSet({ repoRoot: record.workspace, base: entry.base_sha, owned: entry.owned_files, matchOwned: (f) => findOverlap(entry.owned_files, [f]) !== null }));
       const reviews = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
         if (transcript === null) {
@@ -151,7 +166,7 @@ export async function runBlock(args, deps = {}) {
         if (reviewsWaived) await writeSigned(runId, writeRow, { event: 'gate.reviews_waived', block: id, by: 'human' });
         // B20: the high paths come first — a base the workspace does not know refuses the close here
         const highPaths = await highPathsAt(record.workspace, entry.base_sha);
-        const fileSet = await blockFileSet({ repoRoot: record.workspace, base: entry.base_sha, owned: entry.owned_files, matchOwned: (f) => findOverlap(entry.owned_files, [f]) !== null });
+        const fileSet = await blockFiles();
         return {
           block: id,
           runId,
@@ -164,7 +179,20 @@ export async function runBlock(args, deps = {}) {
           highPaths,
         };
       });
-      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews] });
+      // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
+      const report = async () => {
+        if (typeof flags.report !== 'string' || reviewsWaived) return { ok: true };
+        let text;
+        try {
+          text = await readFile(flags.report, 'utf8');
+        } catch {
+          return { ok: false, reason: 'coder report FAILED: --report cannot be read' };
+        }
+        const files = await blockFiles();
+        const missing = missingReviewTickets(text, files.map((f) => f.file));
+        return missing.length === 0 ? { ok: true } : { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
+      };
+      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews, report] });
       (result.ok ? out : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
       return result.ok ? 0 : 1;
     }
@@ -176,6 +204,21 @@ export async function runBlock(args, deps = {}) {
   return 2;
 }
 
+/**
+ * The project config for `block open`'s coder floor (B34): the loaded `.code-forge.yml`, or
+ * undefined when there is none or it does not load — the floor then takes its default (L1), the
+ * safe side.
+ * @param {string} workspace @returns {Promise<Record<string, any> | undefined>}
+ */
+async function openConfig(workspace) {
+  try {
+    const loaded = await loadProjectConfig(workspace);
+    return loaded.ok && loaded.config ? loaded.config : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The block's coder transcript: `--transcript`, else the run record's `blocks.<id>.transcript`
  * (workspace-relative), else `.code-forge/runs/<run>/<id>.log`; null when none exists.

package/src/cli/jev.mjs

@@ -5,6 +5,19 @@
  * `src/decide/**` directly rather than shelling out to this verb).
  *
  *   jev ask <id> --state <file.json> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]
+ *           [--block <id>] [--plan <file>] [--rules]
+ *
+ * B36: `--block` records the block the answer is for (and `--plan` the plan file's base name) on
+ * the decision row — `plan check` refuses a block whose level is not the lane recorded this way.
+ * `--rules` answers `lane`, `risk` or `security_sensitive` with the deterministic fallback rules
+ * (`decide/fallback-rules.mjs`, for a run without Jev): the state file is then an object carrying
+ * all six fallback facts (`filesChanged`, `linesAdded` numbers; `touchesMigration`,
+ * `touchesPolicyOrMiddleware`, `pathFloorHit` booleans; `keywordsFound` a string list) — a missing
+ * or mistyped one is a usage error naming it, with nothing recorded. `system1.disable` still
+ * applies. No key is resolved, no request is sent, and the row says `source: 'rules'`.
+ * The ledger slug is `--slug`, else `project.slug`, else the directory-name slug `run` and
+ * `author` use (`slugFor`; B36 — it used to fall back to `code-forge`). An unknown flag is a usage
+ * error.
  *
  * Resolves the Jev key through B2's chain (`resolveKey`, earlier batch — the seam rule allows a
  * Wave 1 module to import a block in an earlier batch statically), asks Jev, runs the answer
@@ -23,24 +36,74 @@ import path from 'node:path';
 import { buildQuestionPayload, isKnownQuestion, isQuestionDisabled } from '../decide/questions.mjs';
 import { askJev as realAskJev } from '../decide/jev-client.mjs';
 import { decide } from '../decide/thresholds.mjs';
+import { resolveDispatchQuestionsByRules } from '../decide/fallback-rules.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { appendRow as realAppendRow } from '../ledger/write.mjs';
 import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+
+const USAGE = 'usage: code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>] [--block <id>] [--plan <file>] [--rules]\n';
+
+/** The block id shape the run record uses (`state/block.mjs`). */
+const BLOCK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+
+/** Flags that take a value, and the one boolean flag. */
+const VALUE_FLAGS = Object.freeze(['--state', '--cwd', '--slug', '--key-ref', '--block', '--plan']);
+const BOOLEAN_FLAGS = Object.freeze(['--rules']);
+
+/**
+ * Strict flag walk over everything after `ask <id>`: a value flag takes the next token (never one
+ * that starts with `--`, so a bare `--slug --cwd x` never reads `--cwd` as the slug), a boolean
+ * flag takes none, and an unknown token, a repeated flag or a missing value is a usage error.
+ * @param {string[]} rest
+ * @returns {{ok: true, values: Record<string, string>, booleans: Set<string>} | {ok: false}}
+ */
+function parseAskFlags(rest) {
+  /** @type {Record<string, string>} */
+  const values = {};
+  const booleans = new Set();
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (BOOLEAN_FLAGS.includes(arg)) {
+      if (booleans.has(arg)) return { ok: false };
+      booleans.add(arg);
+      continue;
+    }
+    if (!VALUE_FLAGS.includes(arg) || Object.hasOwn(values, arg)) return { ok: false };
+    const next = rest[i + 1];
+    if (next === undefined || next.startsWith('--')) return { ok: false };
+    values[arg] = next;
+    i += 1;
+  }
+  return { ok: true, values, booleans };
+}
 
-const USAGE = 'usage: code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]\n';
+/** The six fallback facts `--rules` needs, each with its type (`decide/fallback-rules.mjs`). */
+const RULE_FACTS = Object.freeze({
+  filesChanged: 'number',
+  linesAdded: 'number',
+  touchesMigration: 'boolean',
+  touchesPolicyOrMiddleware: 'boolean',
+  pathFloorHit: 'boolean',
+  keywordsFound: 'string[]',
+});
 
 /**
- * @param {string[]} args @param {string} flag
- * @returns {{ok: true, value: string|undefined} | {ok: false}} same "flag given with no usable
- *   value is a usage error" contract as `ledger.mjs`'s `readOptionalFlag` — a bare `--slug --cwd x`
- *   must never silently read `--cwd` as `--slug`'s value.
+ * @param {unknown} state
+ * @returns {string[]} the fallback facts that are missing or of the wrong type (all six when the
+ *   state is not a plain object).
  */
-function readOptionalFlag(args, flag) {
-  const i = args.indexOf(flag);
-  if (i < 0) return { ok: true, value: undefined };
-  const next = args[i + 1];
-  if (next === undefined || next.startsWith('--')) return { ok: false };
-  return { ok: true, value: next };
+function badRuleFacts(state) {
+  if (state === null || typeof state !== 'object' || Array.isArray(state)) return Object.keys(RULE_FACTS);
+  const facts = /** @type {Record<string, unknown>} */ (state);
+  return Object.entries(RULE_FACTS)
+    .filter(([name, type]) => {
+      const v = facts[name];
+      if (type === 'number') return typeof v !== 'number' || !Number.isFinite(v) || v < 0;
+      if (type === 'boolean') return typeof v !== 'boolean';
+      return !Array.isArray(v) || !v.every((k) => typeof k === 'string');
+    })
+    .map(([name]) => name);
 }
 
 /**
@@ -82,14 +145,31 @@ export async function runJev(args, deps = {}) {
     return 2;
   }
 
-  const stateFlag = readOptionalFlag(args, '--state');
-  const cwdFlag = readOptionalFlag(args, '--cwd');
-  const slugFlag = readOptionalFlag(args, '--slug');
-  const keyRefFlag = readOptionalFlag(args, '--key-ref');
-  if (!stateFlag.ok || !cwdFlag.ok || !slugFlag.ok || !keyRefFlag.ok || !stateFlag.value) {
+  const parsed = parseAskFlags(args.slice(2));
+  if (!parsed.ok || parsed.values['--state'] === undefined) {
     err(USAGE);
     return 2;
   }
+  const stateFlag = { value: parsed.values['--state'] };
+  const cwdFlag = { value: parsed.values['--cwd'] };
+  const slugFlag = { value: parsed.values['--slug'] };
+  const keyRefFlag = { value: parsed.values['--key-ref'] };
+  const blockFlag = { value: parsed.values['--block'] };
+  const planFlag = { value: parsed.values['--plan'] };
+  if (blockFlag.value !== undefined && !BLOCK_ID.test(blockFlag.value)) {
+    err('jev ask: --block must be a block id (letters, digits, . _ -; at most 32 characters)\n');
+    return 2;
+  }
+  const rules = parsed.booleans.has('--rules');
+  /** @type {Record<string, unknown>} */
+  const scope = {
+    ...(blockFlag.value !== undefined ? { block: blockFlag.value } : {}),
+    ...(planFlag.value !== undefined ? { plan: path.basename(planFlag.value) } : {}),
+  };
+  if (rules && !['lane', 'risk', 'security_sensitive'].includes(id)) {
+    err(`jev ask: no rule answers "${id}" (--rules covers lane, risk, security_sensitive)\n`);
+    return 2;
+  }
   const cwd = cwdFlag.value ?? process.cwd();
 
   let state;
@@ -110,11 +190,28 @@ export async function runJev(args, deps = {}) {
     return 1;
   }
 
+  // the same ledger as the rest of the tool: --slug, else project.slug, else the directory name
+  const slug = slugFlag.value ?? slugFor(cfg, cwd);
+
   if (isQuestionDisabled(id, cfg)) {
     err(`jev ask: question "${id}" is disabled by system1.disable\n`);
     return 1;
   }
 
+  if (rules) {
+    const bad = badRuleFacts(state);
+    if (bad.length > 0) {
+      err(`jev ask: --rules needs the fallback facts in the --state object; missing or wrong type: ${bad.join(', ')}\n`);
+      return 2;
+    }
+    const byRules = resolveDispatchQuestionsByRules(state);
+    const value = byRules[/** @type {'lane'|'risk'|'security_sensitive'} */ (id)].value;
+    const decisionId = makeId();
+    await write({ event: 'decision', decision_id: decisionId, question: id, answer: value, source: 'rules', ...scope }, { slug });
+    out(`${JSON.stringify({ decision_id: decisionId, question: id, answer: value, source: 'rules', ...scope }, null, 2)}\n`);
+    return 0;
+  }
+
   const keyStore = store ?? (await createDefaultKeyStore(env));
   const keyRef = keyRefFlag.value ?? cfg?.keys?.jev;
   let resolved;
@@ -146,7 +243,6 @@ export async function runJev(args, deps = {}) {
     return 1;
   }
   const decision = decide(id, answer, cfg);
-  const slug = slugFlag.value ?? cfg?.project?.slug ?? 'code-forge';
   const decisionId = makeId();
 
   await write(
@@ -159,6 +255,7 @@ export async function runJev(args, deps = {}) {
       confidence: decision.confidence,
       margin: decision.margin,
       source: 'jev',
+      ...scope,
       tokens_in: result.usage?.input_tokens,
       tokens_out: result.usage?.output_tokens,
     },