@codedology/code-forge 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -6,6 +6,29 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.7.3] — 2026-10-08
+
+### Added
+
+- Review: a packet whose answer fails the schema twice is retried once on `review.second_levels.<level>` when configured
+  (signed `review.schema_fallback` row; never in consensus mode; budget and closed-book rules apply), and every schema
+  miss logs a structural diagnosis of the answer (`review.schema_invalid`: keys, types, schema errors or the parse error
+  offset, never the text); the autopilot binnacle shows each fallback as an incident (issue #2).
+
+## [0.7.2] — 2026-10-07
+
+### Changed
+
+- review.budgets.full_in defaults to 32,000 tokens (was 12,000), and a Markdown file whose diff alone is still over it
+  is reviewed section by section (cut at its headings, outside fenced code; approved only when every section is;
+  findings as S<section>.<id>; rechecks split the same way) instead of split_required. Only a section that alone is over
+  the budget keeps the file split_required (issue #2).
+
+### Fixed
+
+- A split_required result lost its size: the signed result, the ledger review.result row, review-file --wait (now stop:
+  split_required) and code-forge review output now carry tokens_in and budget (issue #2).
+
 ## [0.7.1] — 2026-10-07
 
 ### Fixed

package/README.md

@@ -12,6 +12,20 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 
 Next release:
 
+- **A model that keeps failing the answer format gets a stand-in.** When a reviewer's answer
+  fails the schema twice on the same packet and you set `review.second_levels` for that level, the
+  worker retries that packet once with the second model, and the ledger records it. Each failed
+  answer's shape (its keys, types and schema errors, never its text) is logged, so you can see
+  what went wrong.
+
+In 0.7.2:
+
+- **Long documents get reviewed.** The packet budget (`review.budgets.full_in`) is now 32,000
+  tokens, and a Markdown file still too large is reviewed section by section instead of refused;
+  a `split_required` result now says its size and the budget.
+
+In 0.7.1:
+
 - **Short clean reviews count.** A clean pass (no findings, every hunk acknowledged, a summary)
   needs only 40 output tokens on any diff size, so a correct short "no defect" review is no
   longer refused as `too_short`.

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 56,
+  "block_count": 58,
   "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": {
@@ -762,6 +762,38 @@
         "B52"
       ],
       "note": "root-added 2026-10-07; GitHub issue #6; also amends src/review/engine.mjs (smallDiff removed), schema/code-forge.schema.json, docs/reference/config.md, docs/how-it-works.md, skill/references/review.md"
+    },
+    "B54": {
+      "title": "Long documents get reviewed (issue #2): review.budgets.full_in defaults to 32000; a Markdown file whose diff is still over the budget is reviewed section by section (hunks cut at headings outside fenced code and front matter, sections packed within the budget, every section packet built and checked before any session, approved only when every section is, findings as S<n>.<id>, rechecks sectioned the same way); a split_required result carries tokens_in, budget and section",
+      "wave": 12,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/sections.mjs",
+        "test/review/sections.test.mjs",
+        "test/review/sections-guard.test.mjs",
+        "test/worker/split-size.test.mjs"
+      ],
+      "depends_on": [
+        "B53"
+      ],
+      "note": "root-added 2026-10-08; GitHub issue #2 note of 2026-10-02 (25k-token brief never reviewed); also amends src/review/{packet,engine,fixloop}.mjs, src/worker/{engine,loop}.mjs, src/cli/{review,review-file}.mjs, schema/code-forge.schema.json, docs/reference/config.md, docs/how-it-works.md, skill/references/review.md"
+    },
+    "B55": {
+      "title": "Schema-miss fallback (issue #2): a review answer that fails the schema twice on the same packet (same run, file, content, packet text, level and role) is retried once on review.second_levels.<level> (its ladder minus the failed model and, for closed-book roles, minus Codex unless allowed) behind a signed review.schema_fallback row written before the spawn; never in consensus mode; tokens of both sessions summed; every miss logs a structural diagnosis (review.schema_invalid: bytes, kind, keys and types, schema errors, never the text); the autopilot binnacle shows each fallback",
+      "wave": 12,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/review/schema-fallback.mjs",
+        "src/util/diagnostic-tail.mjs",
+        "test/review/schema-fallback.test.mjs",
+        "test/worker/schema-fallback-wiring.test.mjs"
+      ],
+      "depends_on": [
+        "B54"
+      ],
+      "note": "root-added 2026-10-08; GitHub issue #2 note of 2026-10-06; also amends src/review/{engine,fixloop,validate-review}.mjs, src/worker/engine.mjs, src/session/spawn.mjs (stderr tail moved to util), src/autopilot/binnacle.mjs, test fakes, docs/how-it-works.md, skill/references/review.md"
     }
   }
 }

package/docs/reference/config.md

@@ -96,7 +96,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.judge_sees_diff` | boolean |  | `false` |  |
 | `review.budgets` | object |  | — |  |
 | `review.budgets.quick_in` | integer |  | `6000` | min 1 |
-| `review.budgets.full_in` | integer |  | `12000` | min 1 |
+| `review.budgets.full_in` | integer |  | `32000` | min 1; Packet budget in tokens (bytes / 4) for a full, lens A/B or recheck review session. A diff alone over it is split_required, except a Markdown file, which is reviewed section by section (B54). |
 | `review.budgets.judge_in` | integer |  | `8000` | min 1 |
 | `review.budgets.out` | integer |  | `1200` | min 1 |
 | `review.context` | object |  | — |  |

package/package.json

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

package/schema/code-forge.schema.json

@@ -117,7 +117,7 @@
           "additionalProperties": false,
           "properties": {
             "quick_in": { "type": "integer", "minimum": 1, "default": 6000 },
-            "full_in": { "type": "integer", "minimum": 1, "default": 12000 },
+            "full_in": { "type": "integer", "minimum": 1, "default": 32000, "description": "Packet budget in tokens (bytes / 4) for a full, lens A/B or recheck review session. A diff alone over it is split_required, except a Markdown file, which is reviewed section by section (B54)." },
             "judge_in": { "type": "integer", "minimum": 1, "default": 8000 },
             "out": { "type": "integer", "minimum": 1, "default": 1200 }
           }

package/skill/references/review.md

@@ -15,11 +15,11 @@ The topology is decided in one place (`planSessions`). Consensus (§6) runs only
 
 ## §3 Isolation and the packet
 
-Every reviewer, recheck, judge and S2 session runs with cwd = a fresh empty temp dir under the run's temp root and the packet **on stdin** — a no-tools session never opens a path and the packet never enters argv. Packet order is fixed so provider prompt caching applies: lens, project rules digest (≤ 60 lines), facts-sheet excerpt for the symbols in the diff, context, diff. Context: a file at or under `review.context.whole_file_max_lines` travels whole; above it each hunk carries ± `review.context.hunk_context_lines` lines; over `review.budgets.full_in` the context shrinks to ± `review.context.min_context_lines`, then the digest is trimmed, never the diff; a diff alone over budget ⇒ `split_required`. The closed-book rule is in every lens: judge only what is in the packet; a file you cannot see goes in `needs_file`, and the worker attaches it (read-only, trimmed) for **one** more round.
+Every reviewer, recheck, judge and S2 session runs with cwd = a fresh empty temp dir under the run's temp root and the packet **on stdin** — a no-tools session never opens a path and the packet never enters argv. Packet order is fixed so provider prompt caching applies: lens, project rules digest (≤ 60 lines), facts-sheet excerpt for the symbols in the diff, context, diff. Context: a file at or under `review.context.whole_file_max_lines` travels whole; above it each hunk carries ± `review.context.hunk_context_lines` lines; over `review.budgets.full_in` the context shrinks to ± `review.context.min_context_lines`, then the digest is trimmed, never the diff; a diff alone over budget ⇒ `split_required`, with `tokens_in` and `budget` in the result, its ledger `review.result` row and the `review-file --wait` answer (`stop: split_required`) — except a Markdown file (`.md`, `.markdown`), which is reviewed **section by section**: the diff is cut at its headings (`#`..`######`, not inside fenced code), consecutive sections share a packet while it fits, every section packet runs the file's whole plan with its own stub guard, the file is approved only when every section is, and findings are merged with ids `S<section>.<id>`; a recheck over budget is split the same way, each open finding listed in its own section's packet. A section that alone is over budget keeps the file `split_required` (with that `section`), and so does a deleted Markdown file or one with no heading (fail-safe: one section); nothing is ever truncated. The closed-book rule is in every lens: judge only what is in the packet; a file you cannot see goes in `needs_file`, and the worker attaches it (read-only, trimmed) for **one** more round.
 
 ## §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 (a clean pass — `passed: true`, no findings, a non-blank summary — needs only 40, whatever the diff size). 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.
+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 (a clean pass — `passed: true`, no findings, a non-blank summary — needs only 40, whatever the diff size). 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**; `review-file` on the same content re-runs the same packet once, then the file stays unreviewed and the block cannot close. Every `schema` miss leaves a signed `review.schema_invalid` row with a structural diagnosis of the answer — its size and kind (`json`, `not-json`, `empty`), its top-level keys and their types, and the schema errors (path, keyword, message), or the parse error and its byte offset — never the answer's text. At a packet's **second** `schema` miss (same run, file, content hash, packet text, level and role — the first try plus that re-run), the worker tries the packet ONCE on `review.second_levels.<level>` when the owner configured one, and writes a signed `review.schema_fallback {lens, role, level, packet_hash, from_provider, from_model, to, to_provider, to_model, attempts, refused?}` row first (no row written ⇒ no try; any earlier row for the packet at that level ⇒ no try). Its first model that is not the failed one — and, for a closed-book role, not Codex unless `review.allow_open_book_codex` — runs (`refused: same-model` or `refused: closed-book` when there is none). The session's tokens are both sessions'. Its answer goes through the same stub guard; a valid one is a normal answer, a failed one leaves the file unavailable. Never in consensus mode; `budget.usd` refuses it like any session. Without a second level only the diagnosis row is new. 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)
 

package/skill/scripts/forge

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

package/src/autopilot/binnacle.mjs

@@ -39,7 +39,7 @@ export const LOG_FILE = 'autopilot-log.md';
 export const NONE_YET = 'none yet';
 
 /** The ledger events (besides every `autopilot.*`) that belong to the log and the timeline. */
-const EXTRA_EVENTS = Object.freeze(['block.close', 'review.session_timeout', 'worker.down', 'worker.replaced', 'ledger.tamper', 'budget.refused', 'gate.red', 'gate.done']);
+const EXTRA_EVENTS = Object.freeze(['block.close', 'review.session_timeout', 'review.schema_fallback', 'worker.down', 'worker.replaced', 'ledger.tamper', 'budget.refused', 'gate.red', 'gate.done']);
 
 /** @typedef {Record<string, any>} Row */
 /** @typedef {{home?: string | null, cwd?: string | null}} ScrubCtx */
@@ -146,6 +146,8 @@ function describe(row) {
       return { event: 'Block closed', detail: `status ${row.status ?? 'unknown'}${short(first(row.commit, row.sha, row.commit_sha)) ? ` · commit ${short(first(row.commit, row.sha, row.commit_sha))}` : ''}`, link: first(row.pr_url, row.pr) };
     case 'review.session_timeout':
       return { event: 'Review session timed out', detail: `${row.lens ?? row.role ?? 'session'} · attempt ${u(row.attempt)} · ${row.retried === true ? 'retried' : 'gave up'}`, link: null };
+    case 'review.schema_fallback':
+      return { event: 'Review answer off-schema twice', detail: `${row.lens ?? row.role ?? 'session'} · ${u(row.from_model, 'unknown model')} → ${u(row.to_model, 'unknown model')} · ${typeof row.refused === 'string' ? `refused (${u(row.refused)})` : 'retried once'}`, link: null };
     case 'worker.down':
       return { event: 'Worker down', detail: 'the pinned worker is not running', link: null };
     case 'worker.replaced':
@@ -181,6 +183,31 @@ export function buildFullLog({ runId, rows, scrubCtx }) {
 /** @param {Row} row @returns {string} the subject line of an event, e.g. ` · b1 · src/a.mjs`. */
 const where = (row) => `${str(row.block) ? ` · ${u(row.block)}` : ''}${str(row.file) ? ` · ${u(row.file)}` : ''}`;
 
+/**
+ * B55: what the owner does about a refused second-level try, by refusal. `schema-fallback.mjs`
+ * writes `closed-book` (every model left is Codex for a closed-book role) and `same-model`
+ * (nothing but the failed model is configured). No writer puts `budget` in this row today — the
+ * budget gate refuses inside the spawn and writes its own `budget.refused` row — so `budget` is
+ * shown only when a row carries it; any other string gets the generic fix.
+ */
+const SCHEMA_FALLBACK_FIX = Object.freeze({
+  'closed-book': 'Set a second level that can run closed-book (not Codex), or review the file by hand.',
+  'same-model': 'Set review.second_levels to a different model than the one that failed, or review the file by hand.',
+  budget: 'Raise the budget (only you can) or review the file by hand.',
+});
+
+/**
+ * The incident of a `review.schema_fallback` row (B55): retried once, or refused and why.
+ * @param {Row} r @param {string | null} time
+ * @returns {{time: string | null, what: string, effect: string, fix: string}}
+ */
+function schemaFallbackIncident(r, time) {
+  const what = `A ${r.lens ?? r.role ?? 'review'} answer failed the schema twice on the same packet (${u(r.from_model, 'unknown model')})`;
+  if (typeof r.refused !== 'string') return { time, what, effect: `It was retried once on the second level (${u(r.to_model, 'unknown model')}).`, fix: "Check the file's next review result." };
+  const fix = Object.hasOwn(SCHEMA_FALLBACK_FIX, r.refused) ? SCHEMA_FALLBACK_FIX[/** @type {keyof typeof SCHEMA_FALLBACK_FIX} */ (r.refused)] : 'Review the file by hand.';
+  return { time, what, effect: `The second-level try was refused (${u(r.refused)}); the review stays unavailable.`, fix };
+}
+
 /**
  * @param {Row[]} blockRows rows of one block @param {Row | undefined} entry its run-record entry
  * @param {string} id
@@ -285,6 +312,7 @@ export function buildBinnacle({ runId, rows, record, now, scrubCtx = scrubCtxOf(
   for (const { row, time } of mine) {
     const r = row;
     if (r.event === 'review.session_timeout') incidents.push({ time, what: `A ${r.lens ?? r.role ?? 'review'} session timed out (attempt ${u(r.attempt)})`, effect: r.retried === true ? 'It was retried.' : 'No retry left; the review was marked unavailable.', fix: r.retried === true ? 'None needed unless it repeats.' : 'Run the review again.' });
+    else if (r.event === 'review.schema_fallback') incidents.push(schemaFallbackIncident(r, time));
     else if (r.event === 'worker.down' || r.event === 'worker.replaced') incidents.push({ time, what: r.event === 'worker.down' ? 'The pinned worker was down' : 'The pinned worker was replaced', effect: 'Reviews wait until the worker is back.', fix: 'Restart the worker for this run.' });
     else if (r.event === 'ledger.tamper') incidents.push({ time, what: `A ledger check failed for block ${r.block ?? 'unknown'}`, effect: 'The block was stopped.', fix: 'Look at the block before reopening it.' });
     else if (r.event === 'autopilot.issue_failed') incidents.push({ time, what: `The waiver issue for ${u(r.finding, 'unknown finding')} in ${u(r.file, 'unknown file')} could not be opened`, effect: 'The waiver stands without an issue.', fix: 'Open the tracking issue by hand.' });

package/src/cli/review-file.mjs

@@ -11,7 +11,9 @@
  * A done result that is not approved and carries open findings adds `fix_list` (what the coder
  * fixes before re-running `review-file <path>`, which is then a round-2 recheck of the fix hunks,
  * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) — the coder
- * stops and reports; only the orchestrator and the human act on it.
+ * stops and reports; only the orchestrator and the human act on it. A `split_required` result
+ * (the packet is over `review.budgets.full_in`) adds `stop: split_required` with `tokens_in` and
+ * `budget` (always; null when unknown) and a Markdown `section` — never for another result (B54); a Markdown file gets there only when one of its sections alone is too large.
  *
  * Everything is a file read/write inside the workspace (a sandboxed coder has no network). The
  * path is given relative to the current directory and stored relative to the REPOSITORY ROOT
@@ -80,6 +82,12 @@ export function fixList(result) {
     }));
   }
   if (typeof result.stopped === 'string') out.stop = result.stopped;
+  else if (result.status === 'split_required') out.stop = 'split_required';
+  // B54: a split_required stop (only) says how large the packet was, the budget, and the section
+  if (out.stop === 'split_required') {
+    const fin = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    Object.assign(out, { tokens_in: fin(result.tokens_in), budget: fin(result.budget), ...(typeof result.section === 'string' ? { section: result.section } : {}) });
+  }
   return out;
 }
 

package/src/cli/review.mjs

@@ -204,7 +204,9 @@ function lastJSON(text) {
 
 /**
  * @typedef {{file: string, result: 'approved' | 'unchanged' | 'findings' | 'stopped' | 'unavailable', reason: string | null,
- *   findings: Array<{id: unknown, severity: unknown, lines: string, claim: string, fix: string}>}} FileOutcome
+ *   findings: Array<{id: unknown, severity: unknown, lines: string, claim: string, fix: string}>,
+ *   tokens_in?: number | null, budget?: number | null, section?: string}} FileOutcome - `tokens_in`/`budget`
+ *   (null when unknown; and a Markdown `section`): a `split_required` stop's packet size, only then (B54).
  */
 
 /**
@@ -222,8 +224,11 @@ export function classify(file, waited) {
   if (!r || typeof r !== 'object') return out('unavailable', 'unreadable result');
   if (r.approved === true) return out('approved', null);
   if (r.status === 'no_change') return out('unchanged', null);
-  if (r.status === 'stopped') return out('stopped', String(r.stopped ?? 'stopped'));
-  if (r.status === 'split_required') return out('stopped', 'split_required');
+  // B54: a split_required stop (only) says how large the packet was and what the budget is
+  const fin = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const size = { tokens_in: fin(r.tokens_in), budget: fin(r.budget), ...(typeof r.section === 'string' ? { section: r.section } : {}) };
+  if (r.status === 'stopped') return { ...out('stopped', String(r.stopped ?? 'stopped')), ...(r.stopped === 'split_required' ? size : {}) };
+  if (r.status === 'split_required') return { ...out('stopped', 'split_required'), ...size };
   if (r.status === 'reviewed' && findings.length > 0) return out('findings', null);
   return out('unavailable', String(r.reason ?? r.status ?? 'not approved'));
 }
@@ -231,6 +236,9 @@ export function classify(file, waited) {
 /** @param {FileOutcome} o @returns {string} */
 function label(o) {
   if (o.result === 'findings') return `${o.findings.length} finding${o.findings.length === 1 ? '' : 's'}`;
+  if (o.result === 'stopped' && o.reason === 'split_required' && Number.isFinite(o.tokens_in) && Number.isFinite(o.budget)) {
+    return `${o.result}: ${o.reason} (~${o.tokens_in} tokens, budget ${o.budget}${o.section ? `; section ${JSON.stringify(o.section)}` : ''})`;
+  }
   if (o.result === 'stopped' || o.result === 'unavailable') return `${o.result}: ${o.reason}`;
   return o.result;
 }

package/src/review/engine.mjs

@@ -19,7 +19,21 @@
  *     request with a non-repo-relative path is refused (`needs_file-refused`, never approval);
  *  6. a session that ends in `timeout` is spawned ONCE more on the same packet and level
  *     (`session-retry.mjs`, B30); a second timeout is `unavailable: timeout`. The summary's
- *     `attempts` says how many ran.
+ *     `attempts` says how many ran;
+ *  6b. a session whose answer fails the schema logs it (`review.schema_invalid`, the raw answer
+ *     redacted); at the packet's second such miss it is tried ONCE on `review.second_levels.<level>`
+ *     when the owner configured one (`schema-fallback.mjs`, B55; never in consensus mode).
+ *     The summary then carries `schema_fallback: {level, provider, model}` (`level`:
+ *     `review.second_levels.<level>`), the second level's own provider/model, and `tokens_in` /
+ *     `tokens_out` summed over both sessions;
+ *  7. a diff alone over the packet budget is `split_required` (with `tokens_in` and `budget`) —
+ *     except a Markdown file (B54), which is reviewed SECTION BY SECTION (`sections.mjs`): every
+ *     section packet runs the whole plan above (its own sessions, judge and stub guard, its own
+ *     `review.plan` row with `section`), in file order, stopping at the first one that is not
+ *     reviewed (the file is then `unavailable`). The file is approved only when EVERY section is;
+ *     the findings of all sections are merged with ids `S<section>.<id>`, every session summary
+ *     names its `section`, and `sections` lists them. A section that alone is still over the
+ *     budget keeps the file `split_required` (plus `section`: its heading) — never truncated.
  * Approval (until B12b's triage lands) = the final answer (the judge's in dual/consensus mode, else
  * the single reviewer's) passed the guard, says `passed: true`, and carries no `critical` or
  * `warning` finding.
@@ -32,9 +46,11 @@ import { resolveLevel } from '../config/known-ids.mjs';
 import { blockKind, isDocsKind } from '../decide/escalation.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
 import { tierFor } from '../proof/tiers.mjs';
-import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, readFileDiff } from './packet.mjs';
+import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
+import { isMarkdownFile, packSections, sectionFindings, sectionGroups } from './sections.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
+import { afterSchemaMiss, logSecondLevelMiss } from './schema-fallback.mjs';
 import { assertRowPath } from '../worker/ticket.mjs';
 
 /**
@@ -152,7 +168,10 @@ export function rulesRisk({ file, plusCount, cfg }) {
  *   session (`spawnSession` opts minus the worker-pinned ones); a per-call `cfg` selects another
  *   provider's level for the same slot (consensus).
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow] - ledger rows
- *   (`review.plan`, `review.unavailable`); a failed write never fails the review.
+ *   (`review.plan`, `review.unavailable`, `review.schema_invalid`, `review.schema_fallback`); a
+ *   failed write never fails the review (a failed `review.schema_fallback` write means no try).
+ * @property {import('./schema-fallback.mjs').SchemaHistory} [schemaHistory] - B55: the packet's
+ *   signed schema-miss history (the worker's); absent ⇒ no second-level try.
  */
 
 /** @param {ReviewDeps} deps @param {Record<string, any>} row */
@@ -194,11 +213,13 @@ export async function reviewFile(input, deps) {
   if (diff.diffText.trim().length === 0) return { status: 'no_change', approved: false, ...head, sessions: [] };
   mkdirSync(workDir, { recursive: true, mode: 0o700 });
   const min = minTokensOut(cfg);
+  // B55: never in consensus mode — its providers (two reviewers, the judge) are the check itself
+  const schemaFallback = plan.mode !== 'consensus';
 
   /** @param {SessionSpec} spec @param {{text: string, hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet */
   const run = async (spec, packet) => {
     /** @type {Record<string, any>} */
-    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, cfg });
+    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, cfg, schemaFallback });
     const needs = summary.review?.needs_file;
     if (spec.role === 'reviewer' && summary.status === 'ok' && Array.isArray(needs) && needs.length > 0) {
       const paths = safeNeeds(needs);
@@ -209,59 +230,131 @@ export async function reviewFile(input, deps) {
         extra = null;
       }
       if (extra === null) return { ...summary, status: 'unavailable', reason: 'needs_file-refused', review: null };
-      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, cfg })), needs_file_round: true };
+      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, cfg, schemaFallback })), needs_file_round: true };
     }
     return summary;
   };
 
   const reviewers = plan.sessions.filter((s) => s.role === 'reviewer');
-  const packets = reviewers.map((spec) => assemblePacket({ diff, lens: spec.lens, rulesDigest: input.rulesDigest, factsExcerpt: input.factsExcerpt, cfg }));
-  const split = packets.find((p) => p.status === 'split_required');
-  if (split) return { status: 'split_required', approved: false, ...head, tokens_in: split.tokensIn, budget: split.budget, sessions: [] };
-  const firstPacket = /** @type {any} */ (packets[0]);
-  await note(deps, { event: 'review.plan', depth_unconstrained: plan.depth, depth_chosen: plan.depth, degrade_step: 0, risk, context_mode: firstPacket?.contextMode ?? null, forecast_tokens: packets.reduce((n, p) => n + p.tokensIn, 0) });
-  const done = await Promise.all(reviewers.map((spec, i) => run(spec, /** @type {any} */ (packets[i]))));
-  const sessions = done.map(publicSummary);
-  const failed = done.find((s) => s.status !== 'ok');
-  if (failed) {
-    await note(deps, { event: 'review.unavailable', reason: failed.reason, lens: failed.lens });
-    return { status: 'unavailable', reason: failed.reason, approved: false, ...head, sessions };
-  }
-
-  let final = done[0];
   const judgeSpec = plan.sessions.find((s) => s.role === 'judge');
-  if (judgeSpec) {
-    const bySlot = Object.fromEntries(done.map((s) => [s.slot, s.review]));
-    const packet = assembleJudgePacket({ diff, reports: { A: bySlot.A, B: bySlot.B }, cfg });
-    final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, cfg });
-    sessions.push(publicSummary(final));
-    if (final.status !== 'ok') {
-      await note(deps, { event: 'review.unavailable', reason: final.reason, lens: 'judge' });
-      return { status: 'unavailable', reason: final.reason, approved: false, ...head, sessions };
+  /** @param {import('./packet.mjs').FileDiff} part */
+  const packetsFor = (part) => reviewers.map((spec) => assemblePacket({ diff: part, lens: spec.lens, rulesDigest: input.rulesDigest, factsExcerpt: input.factsExcerpt, cfg }));
+
+  /**
+   * The plan on one packet set (the whole file, or one Markdown section): reviewers, then the judge.
+   * @param {import('./packet.mjs').FileDiff} part @param {Array<Record<string, any>>} packets
+   * @param {Record<string, any>} [rowExtra] - added to the `review.plan` row (`section`).
+   * @returns {Promise<{status: 'reviewed' | 'unavailable', reason?: string, approved: boolean, summary?: string, findings?: Array<Record<string, any>>, sessions: Array<Record<string, any>>}>}
+   */
+  const reviewPart = async (part, packets, rowExtra = {}) => {
+    await note(deps, { event: 'review.plan', depth_unconstrained: plan.depth, depth_chosen: plan.depth, degrade_step: 0, risk, context_mode: packets[0]?.contextMode ?? null, forecast_tokens: packets.reduce((n, p) => n + p.tokensIn, 0), ...rowExtra });
+    const done = await Promise.all(reviewers.map((spec, i) => run(spec, /** @type {any} */ (packets[i]))));
+    const sessions = done.map(publicSummary);
+    const failed = done.find((s) => s.status !== 'ok');
+    if (failed) {
+      await note(deps, { event: 'review.unavailable', reason: failed.reason, lens: failed.lens, ...rowExtra });
+      return { status: 'unavailable', reason: failed.reason, approved: false, sessions };
     }
+    let final = done[0];
+    if (judgeSpec) {
+      const bySlot = Object.fromEntries(done.map((s) => [s.slot, s.review]));
+      const packet = assembleJudgePacket({ diff: part, reports: { A: bySlot.A, B: bySlot.B }, cfg });
+      final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, cfg, schemaFallback });
+      sessions.push(publicSummary(final));
+      if (final.status !== 'ok') {
+        await note(deps, { event: 'review.unavailable', reason: final.reason, lens: 'judge', ...rowExtra });
+        return { status: 'unavailable', reason: final.reason, approved: false, sessions };
+      }
+    }
+    const findings = final.review.findings;
+    const approved = final.review.passed === true && findings.every((/** @type {any} */ f) => f.severity === 'nit');
+    return { status: 'reviewed', approved, summary: final.review.summary, findings, sessions };
+  };
+
+  const packets = packetsFor(diff);
+  const split = /** @type {{status: 'split_required', tokensIn: number, budget: number} | undefined} */ (packets.find((p) => p.status === 'split_required'));
+  if (!split) {
+    const { status, reason, approved, summary, findings, sessions } = await reviewPart(diff, packets);
+    if (status !== 'reviewed') return { status, reason, approved: false, ...head, sessions };
+    return { status, approved, ...head, summary, findings, sessions };
+  }
+  if (!isMarkdownFile(diff.file)) return { status: 'split_required', approved: false, ...head, tokens_in: split.tokensIn, budget: split.budget, sessions: [] };
+
+  // B54: a Markdown file over the budget is reviewed section by section
+  /** @param {import('./packet.mjs').FileDiff} part @returns {number} the diff-only packet tokens, largest over the lenses. */
+  const measure = (part) => Math.max(...reviewers.map((spec) => diffOnlyTokens({ diff: part, lens: spec.lens })));
+  const packed = packSections({ diff, budget: split.budget, measure });
+  /**
+   * A `split_required` outcome, its size always numeric (measured here when the packet lacks it).
+   * @param {import('./packet.mjs').FileDiff} part @param {{tokensIn?: unknown, budget?: unknown}} over @param {string | null} section
+   */
+  const splitOutcome = (part, over, section) => ({
+    status: 'split_required',
+    approved: false,
+    ...head,
+    tokens_in: Number.isFinite(over.tokensIn) ? over.tokensIn : measure(part),
+    budget: Number.isFinite(over.budget) ? over.budget : split.budget,
+    ...(section ? { section } : {}),
+    sessions: [],
+  });
+  if (packed.status !== 'ok') {
+    // a named section is measured on its own diff, never the whole file's
+    const group = packed.section ? sectionGroups(diff)?.find((g) => g.heading === packed.section) : undefined;
+    return splitOutcome(group ? group.diff : diff, packed, packed.section);
+  }
+  // never approve with no section: no packet ⇒ no session ⇒ split_required at the whole size
+  if (packed.sections.length === 0) return splitOutcome(diff, split, null);
+  // every section packet is assembled BEFORE any session runs. Packing and `assemblePacket` share
+  // one measure, so with the real packer none is ever not `ok`: this is a DEFENSIVE guard (a test
+  // reaches it through a mocked packer) — one that is not `ok` stops the file as split_required,
+  // sized on that section's own diff
+  const sectionPackets = packed.sections.map((section) => packetsFor(section.diff));
+  for (const [i, set] of sectionPackets.entries()) {
+    const over = /** @type {{tokensIn?: unknown, budget?: unknown} | undefined} */ (set.find((p) => p.status !== 'ok'));
+    if (over) return splitOutcome(packed.sections[i].diff, over, packed.sections[i].headings[0] ?? '(before first heading)');
+  }
+  const sections = packed.sections.map((s) => ({ index: s.index, headings: s.headings, hunks: s.diff.hunks.length }));
+  /** @type {Array<Record<string, any>>} */
+  const sessions = [];
+  /** @type {Array<Record<string, any>>} */
+  const findings = [];
+  const summaries = [];
+  let approved = true;
+  for (const [i, section] of packed.sections.entries()) {
+    const part = await reviewPart(section.diff, sectionPackets[i], { section: section.index, sections: packed.sections.length });
+    sessions.push(...part.sessions.map((s) => ({ ...s, section: section.index })));
+    if (part.status !== 'reviewed') return { status: part.status, reason: part.reason, approved: false, ...head, sections, sessions };
+    approved = approved && part.approved;
+    findings.push(...sectionFindings(/** @type {Array<{id: string}>} */ (part.findings), section.index));
+    summaries.push(`S${section.index}: ${part.summary}`);
   }
-  const findings = final.review.findings;
-  const approved = final.review.passed === true && findings.every((/** @type {any} */ f) => f.severity === 'nit');
-  return { status: 'reviewed', approved, ...head, summary: final.review.summary, findings, sessions };
+  return { status: 'reviewed', approved, ...head, summary: summaries.join('\n'), findings, sessions, sections };
 }
 
 /**
- * One session: packet file (0600, removed after), spawn, stub guard.
+ * One session: packet file (0600, removed after), spawn, stub guard — and, on a `schema` miss, the
+ * B55 second-level try (`schema-fallback.mjs`) on the same packet file before it is removed.
  * @param {SessionSpec} spec @param {string} text
  * @param {{hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet
- * @param {{deps: ReviewDeps, workDir: string, min: number, cfg: Record<string, any>}} env
+ * @param {{deps: ReviewDeps, workDir: string, min: number, cfg: Record<string, any>, schemaFallback?: boolean}} env -
+ *   `schemaFallback: false` (consensus mode: its providers ARE the check) never tries.
  */
-async function runOne(spec, text, packet, { deps, workDir, min }) {
+async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallback = true }) {
   const promptPath = path.join(workDir, `${spec.lens}-${randomBytes(6).toString('hex')}.md`);
   const base = { lens: spec.lens, role: spec.role, level: spec.level, slot: spec.slot, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn };
   writeFileSync(promptPath, text, { mode: 0o600 });
   /** @type {Record<string, any> | null} */
   let res = null;
   let attempts = 0;
-  try {
+  /** @type {import('./validate-review.mjs').Verdict} */
+  let verdict = { ok: false, reason: 'exit', detail: 'no session result' };
+  /** @type {{level: string, provider: string, model: string} | null} */
+  let fellBackTo = null;
+  /** @param {Record<string, any> | undefined} sessionCfg @param {number} done - attempts before this call. */
+  const attempt = (sessionCfg, done) =>
     // a `timeout` is spawned once more on the same packet and level (B30); a spawn that throws
     // (bad config, refused argv) is an `exit` failure, never approval
-    ({ res, attempts } = await spawnWithTimeoutRetry(
+    spawnWithTimeoutRetry(
       deps.spawn,
       {
         level: spec.level,
@@ -269,35 +362,88 @@ async function runOne(spec, text, packet, { deps, workDir, min }) {
         promptPath,
         schema: FINDING_SCHEMA,
         rowExtra: { lens: spec.lens, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn },
-        ...(spec.cfg ? { cfg: spec.cfg } : {}),
+        ...(sessionCfg ? { cfg: sessionCfg } : {}),
       },
       (row) => note(deps, row),
       (n) => {
-        attempts = n;
+        attempts = done + n;
       },
-    ));
-  } catch {
-    // defensive only: the helper never throws. If it ever did, it is still an `exit` failure,
-    // never approval, with the attempts it had reported so far (at least 1).
-    res = null;
-    attempts = Math.max(attempts, 1);
+    );
+  /** @type {number | null} the session's tokens: the first spawn's, plus a second-level try's */
+  let tokensIn = null;
+  /** @type {number | null} */
+  let tokensOut = null;
+  // the packet file is removed on every path, and only after the second-level try (which reads it)
+  try {
+    try {
+      ({ res, attempts } = await attempt(spec.cfg, 0));
+    } catch {
+      // defensive only: the helper never throws. If it ever did, it is still an `exit` failure,
+      // never approval, with the attempts it had reported so far (at least 1).
+      res = null;
+      attempts = Math.max(attempts, 1);
+    }
+    tokensIn = res?.usage?.tokens_in ?? null;
+    tokensOut = res?.usage?.tokens_out ?? null;
+    verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+    if (!verdict.ok && verdict.reason === 'schema') {
+      try {
+        const session = { lens: spec.lens, role: spec.role, level: spec.level };
+        const done = attempts;
+        // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
+        // (each helper handles its own failed write)
+        const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<ReviewDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
+        const second = await afterSchemaMiss({
+          res,
+          session,
+          packetText: text,
+          cfg: spec.cfg ?? cfg,
+          allowed: schemaFallback && !spec.cfg,
+          history: deps.schemaHistory,
+          writeRow: write,
+          spawnAt: (c) => attempt(c, done),
+        });
+        if (second) {
+          const secondVerdict = validateReview(second.res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+          res = second.res;
+          attempts = done + second.attempts;
+          fellBackTo = second.to;
+          verdict = secondVerdict;
+          tokensIn = addTokens(tokensIn, second.res?.usage?.tokens_in);
+          tokensOut = addTokens(tokensOut, second.res?.usage?.tokens_out);
+          if (!verdict.ok && verdict.reason === 'schema') await logSecondLevelMiss({ res, session, packetText: text, writeRow: write });
+        }
+      } catch {
+        // defensive only: the helpers never throw. If they ever did, the first session's result
+        // and its `schema` verdict stand (never turned into `exit`, never approval)
+      }
+    }
   } finally {
     rmSync(promptPath, { force: true });
   }
-  const verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
   const meta = {
     ...base,
     provider: res?.provider ?? null,
     model: res?.model ?? null,
     fallback_step: res?.fallback_step ?? 0,
     attempts,
-    tokens_in: res?.usage?.tokens_in ?? null,
-    tokens_out: res?.usage?.tokens_out ?? null,
+    ...(fellBackTo ? { schema_fallback: fellBackTo } : {}),
+    tokens_in: tokensIn,
+    tokens_out: tokensOut,
   };
   if (!verdict.ok) return { ...meta, status: 'unavailable', reason: verdict.reason, review: null };
   return { ...meta, status: 'ok', reason: null, review: verdict.review };
 }
 
+/**
+ * Two token counts added; a missing one (not a number) adds nothing, both missing ⇒ null.
+ * @param {unknown} a @param {unknown} b @returns {number | null}
+ */
+function addTokens(a, b) {
+  if (typeof a !== 'number') return typeof b === 'number' ? b : null;
+  return typeof b === 'number' ? a + b : a;
+}
+
 /** The per-session summary the worker signs: the answer's verdict and findings, never the packet. */
 function publicSummary(/** @type {Record<string, any>} */ s) {
   const { review, ...rest } = s;