@codedology/code-forge 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -6,6 +6,20 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [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,12 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 
 Next release:
 
+- **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": 57,
   "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,22 @@
         "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"
     }
   }
 }

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.2",
   "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,7 +15,7 @@ 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)
 

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.2"
 set -eu
 
 self="$0"

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,15 @@
  *     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;
+ *  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,7 +40,8 @@ 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 { assertRowPath } from '../worker/ticket.mjs';
@@ -215,34 +224,99 @@ export async function reviewFile(input, deps) {
   };
 
   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 });
+      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 };
 }
 
 /**

package/src/review/fixloop.mjs

@@ -47,7 +47,17 @@
  * with no context at all, exceed the budget) is deterministic — re-running the round would build
  * the same packet — so it is TERMINAL, never a retry: `stopped`, `next: {action: 'stop', reason:
  * <packet.status>}`, and the gate-relevant `review.cap` row (the gate then refuses the file's open
- * findings until a human waives them or the file is reviewed again).
+ * findings until a human waives them or the file is reviewed again). The stop carries the packet's
+ * `tokens_in` and `budget` (and a Markdown section's heading as `section`) in `next` and in the
+ * `review.cap` row (B54).
+ *
+ * Markdown sections (B54): a Markdown file whose recheck packet is over the budget is rechecked
+ * SECTION BY SECTION (`sections.mjs`, `packRecheck`: packets sized with their open-findings list)
+ * instead: one recheck session per section packet, each listing only the open findings that fall
+ * in it (`sectionOf`: the spanning or nearest section), each through the stub guard (its
+ * own `reviewed_hunks`). A finding closes only when ITS section's session resolves it; new
+ * findings get ids `S<section>.<id>`; any section session unavailable ⇒ `retry` of the whole
+ * round. A section still over the budget alone ⇒ the terminal stop above (`split_required`).
  *
  * A session that fails the stub guard is `unavailable`, and a failed write of a gate-relevant row
  * (`review.late_finding`, `review.round`, `review.cap`) is `ledger_write_failed`: either way the
@@ -64,7 +74,8 @@ import { verifyRow } from '../state/signer.mjs';
 import { decisionProblem, grantCoverProblem } from './gate-check.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
-import { assemblePacket, assertPacketPath, readFileDiff } from './packet.mjs';
+import { assemblePacket, assertPacketPath, diffOnlyTokens, readFileDiff } from './packet.mjs';
+import { isMarkdownFile, packSections, sectionFindings, sectionGroups, sectionOf } from './sections.mjs';
 import { cameFromJudge, resolvedBand, triageFindings } from './triage.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
@@ -78,6 +89,9 @@ import { spawnWithTimeoutRetry } from './session-retry.mjs';
  * @property {string} [level] - the level the next fix is coded at.
  * @property {string | null} [trigger] - the escalation trigger that moved the level, if any.
  * @property {string} [reason] - `review_cap`, `l3_patch_exhausted`, a non-ok packet status (`split_required`), … for `stop`; the stub-guard reason for `retry`.
+ * @property {number} [tokens_in] - a `split_required` stop: the estimated tokens of the diff-only packet (B54).
+ * @property {number} [budget] - a `split_required` stop: the packet budget it exceeded (B54).
+ * @property {string} [section] - a `split_required` stop of a Markdown recheck: the heading of the section that alone is over (B54).
  */
 
 /**
@@ -93,7 +107,7 @@ import { spawnWithTimeoutRetry } from './session-retry.mjs';
  * @property {boolean} l3_rung_used - the block's L3 rung (rule 5 or 6) was used — once per block.
  * @property {'open' | 'complete' | 'stopped'} status
  * @property {NextStep | null} next
- * @property {{context_mode: string, context_lines: number} | null} [last_packet] - the last recheck packet's context.
+ * @property {{context_mode: string, context_lines: number} | null} [last_packet] - the last recheck round's context: one packet's, or over a Markdown recheck's section packets the summed lines and the one mode they share, else `mixed` (B54).
  * @property {'full' | 'recheck' | 'patch_check' | null} [pending_kind] - the round to re-run after a `retry`.
  */
 
@@ -123,6 +137,58 @@ async function note(deps, row) {
   }
 }
 
+/**
+ * Token counts over a round's sessions: a missing count (null/undefined) adds nothing, and no
+ * count at all stays null (one session without usage ⇒ null, as before B54).
+ * @param {number | null | undefined} a @param {number | null | undefined} b @returns {number | null}
+ */
+export const sum = (a, b) => (typeof a !== 'number' ? (typeof b === 'number' ? b : null) : typeof b === 'number' ? a + b : a);
+
+/**
+ * The round's `last_packet` over its recheck packets (B54): the context lines add up; the context
+ * mode is the packets' one mode when they all agree, else `mixed`.
+ * @param {{context_mode: string, context_lines: number} | null} info
+ * @param {{contextMode: string, contextLines: number}} packet
+ * @returns {{context_mode: string, context_lines: number}}
+ */
+export function mergePacketInfo(info, packet) {
+  if (info === null) return { context_mode: packet.contextMode, context_lines: packet.contextLines };
+  return { context_mode: info.context_mode === packet.contextMode ? info.context_mode : 'mixed', context_lines: info.context_lines + packet.contextLines };
+}
+
+/**
+ * Pack a Markdown recheck into section packets (B54), each sized with {@link recheckTokens} over
+ * its own diff and its own open findings. Each open finding belongs to ONE heading group — the one
+ * `sectionOf` picks over the groups (spanning, else nearest) — and is sized and listed in the
+ * packet that holds that group, so sizing and listing never disagree. No group at all (no hunk,
+ * or hunks that do not parse one to one) ⇒ `split_required` at the whole size, never sectioned;
+ * a finding no packet holds is listed in the LAST packet — every open finding is listed once.
+ * @param {import('./packet.mjs').FileDiff} diff @param {Finding[]} open @param {number} budget
+ * @returns {{status: 'ok', sections: Array<import('./sections.mjs').Section & {open: Finding[]}>} | {status: 'split_required', tokensIn: number, budget: number, section: string | null}}
+ */
+export function packRecheck(diff, open, budget) {
+  const groups = sectionGroups(diff);
+  if (groups === null || groups.length === 0) return { status: 'split_required', tokensIn: recheckTokens(diff, open), budget, section: null };
+  /** @type {Map<Finding, number>} */
+  const keyOf = new Map();
+  for (const f of open) {
+    const at = sectionOf(groups, f);
+    if (at >= 0) keyOf.set(f, groups[at].key);
+  }
+  /** @param {ReadonlyArray<number>} keys @returns {Finding[]} the open findings of those groups, in order. */
+  const openIn = (keys) => open.filter((f) => keyOf.has(f) && keys.includes(/** @type {number} */ (keyOf.get(f))));
+  const packed = packSections({ diff, budget, measure: (part, set) => recheckTokens(part, openIn(set.map((g) => g.key))) });
+  if (packed.status !== 'ok') return packed;
+  const sections = packed.sections.map((sec) => ({ ...sec, open: openIn(sec.keys) }));
+  if (sections.length === 0) return { status: 'split_required', tokensIn: recheckTokens(diff, open), budget, section: null };
+  // defensive: a finding no packet holds goes to the last packet (it is sized there by the check
+  // every packet passes before any session) — never dropped, never closed unseen
+  const listed = new Set(sections.flatMap((sec) => sec.open));
+  const last = /** @type {(typeof sections)[number]} */ (sections.at(-1));
+  for (const f of open) if (!listed.has(f)) last.open.push(f);
+  return { status: 'ok', sections };
+}
+
 /** @param {unknown} v @param {number} d @returns {number} `v` when a non-negative integer, else `d`. */
 const int = (v, d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
 
@@ -247,6 +313,25 @@ export async function fixHunkDiff({ file, previous, current, workDir }) {
   }
 }
 
+/** The heading of the open-findings list a recheck packet ends with. */
+const OPEN_FINDINGS_HEAD = '## open findings\n';
+
+/** @param {Finding} f @returns {string} the finding's line in a recheck packet's open-findings list. */
+export const openFindingLine = (f) => `- ${f.id} (${f.severity}, lines ${f.line_start}-${f.line_end}): ${f.claim ?? ''}`;
+
+/** @param {ReadonlyArray<Finding>} open @returns {string} the open-findings list a recheck packet ends with. */
+const openFindingsText = (open) => `${OPEN_FINDINGS_HEAD}${open.length > 0 ? open.map(openFindingLine).join('\n') : '(none)'}\n`;
+
+/**
+ * The size a recheck packet is held to (B54): its diff-only `recheck` packet (the measure behind
+ * `split_required`) plus the open-findings list `buildRecheckPacket` appends. Section packing and
+ * the check before any session use this ONE function.
+ * @param {import('./packet.mjs').FileDiff} diff @param {ReadonlyArray<Finding>} open @returns {number}
+ */
+export function recheckTokens(diff, open) {
+  return diffOnlyTokens({ diff, lens: 'recheck' }) + Math.ceil(Buffer.byteLength(openFindingsText(open)) / 4);
+}
+
 /**
  * The recheck packet: the `recheck` lens on the fix hunks (hunk form, never the whole file), then
  * the open findings by id. Over budget ⇒ `minimal` (see the module doc).
@@ -255,8 +340,7 @@ export async function fixHunkDiff({ file, previous, current, workDir }) {
 export function buildRecheckPacket({ diff, open, cfg, contextMode = 'recheck', rulesDigest, factsExcerpt }) {
   const packet = assemblePacket({ diff, lens: 'recheck', cfg, contextMode, rulesDigest, factsExcerpt });
   if (packet.status !== 'ok') return packet;
-  const listed = open.map((f) => `- ${f.id} (${f.severity}, lines ${f.line_start}-${f.line_end}): ${f.claim ?? ''}`);
-  const text = `${packet.text}## open findings\n${listed.length > 0 ? listed.join('\n') : '(none)'}\n`;
+  const text = `${packet.text}${openFindingsText(open)}`;
   return { ...packet, text, tokensIn: packet.tokensIn + Math.ceil(Buffer.byteLength(text.slice(packet.text.length)) / 4) };
 }
 
@@ -373,14 +457,20 @@ function retry(state, kind, reason) {
  * not written, the open set stays as it was, and the gate-relevant `review.cap` row goes through
  * the must-write path — a failed write is a `retry`, never a silent stop.
  * @param {FileState} state @param {LoopDeps} deps
- * @param {'full' | 'recheck' | 'patch_check'} kind @param {string} file @param {string} reason
+ * @param {'full' | 'recheck' | 'patch_check'} kind @param {string} file
+ * @param {{status: string, tokensIn?: number, budget?: number, section?: string | null}} packet - the non-ok packet (a Markdown section names its heading).
  * @returns {Promise<FileState>}
  */
-async function stopBeforeRound(state, deps, kind, file, reason) {
-  const row = { event: 'review.cap', file, round: state.round, reason, open: state.open.map((f) => f.id) };
+async function stopBeforeRound(state, deps, kind, file, packet) {
+  const reason = packet.status;
+  const size =
+    typeof packet.tokensIn === 'number' && typeof packet.budget === 'number'
+      ? { tokens_in: packet.tokensIn, budget: packet.budget, ...(typeof packet.section === 'string' ? { section: packet.section } : {}) }
+      : {};
+  const row = { event: 'review.cap', file, round: state.round, reason, open: state.open.map((f) => f.id), ...size };
   if (!(await mustNote(deps, row))) return retry(state, kind, 'ledger_write_failed');
   state.status = 'stopped';
-  state.next = { action: 'stop', reason };
+  state.next = { action: 'stop', reason, ...size };
   state.pending_kind = null;
   return state;
 }
@@ -434,34 +524,68 @@ export async function runRound(state, deps, opts = {}) {
       }
       draft.open = [];
       if (pending.length > 0) {
-        const packet = buildRecheckPacket({ diff, open: pending, cfg: deps.cfg, contextMode: s.scope === 'file' ? 'auto' : 'recheck', rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt });
-        // deterministic (the same hunks build the same packet): terminal, never a retry
-        if (packet.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, packet.status);
-        packetInfo = { context_mode: packet.contextMode, context_lines: packet.contextLines };
-        const session = await recheckSession(packet, deps);
-        tokensIn = session.tokens_in;
-        tokensOut = session.tokens_out;
-        if (!session.verdict.ok) {
-          await note(deps, { event: 'review.unavailable', file: current.rel, lens: 'recheck', reason: session.verdict.reason });
-          return retry(state, kind, session.verdict.reason ?? 'unavailable');
+        const contextMode = s.scope === 'file' ? 'auto' : 'recheck';
+        const whole = buildRecheckPacket({ diff, open: pending, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt });
+        /** @type {Array<{index: number | null, heading: string | null, diff: import('./packet.mjs').FileDiff, open: Finding[]}>} */
+        let parts = [{ index: null, heading: null, diff, open: pending }];
+        if (whole.status !== 'ok') {
+          // deterministic (the same hunks build the same packet): terminal, never a retry — except
+          // a Markdown file whose packet is `split_required`, rechecked section by section (B54);
+          // any other status stops as it always did
+          const packed = whole.status === 'split_required' && isMarkdownFile(current.rel) ? packRecheck(diff, pending, whole.budget) : null;
+          if (!packed || packed.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, packed ?? whole);
+          parts = packed.sections.map((sec) => ({ index: sec.index, heading: sec.headings[0], diff: sec.diff, open: sec.open }));
         }
-        const review = /** @type {Record<string, any>} */ (session.verdict.review);
-        const resolvedIds = new Set((review.resolved ?? []).filter((/** @type {any} */ r) => r?.resolved === true).map((/** @type {any} */ r) => r.id));
-        const stillOpen = pending.filter((f) => !resolvedIds.has(f.id));
-        closed += pending.length - stillOpen.length;
+        // EVERY packet is built and held to the budget BEFORE any session runs: a section over it
+        // stops the round as split_required (with its heading) before anything is spent
+        /** @type {Array<Record<string, any>>} */
+        const built = [];
+        for (const part of parts) {
+          if (part.index === null) {
+            built.push(whole);
+            continue;
+          }
+          const packet = buildRecheckPacket({ diff: part.diff, open: part.open, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt });
+          // a packet that fails to build stops with ITS status (and size, when it has one)
+          if (packet.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, { ...packet, section: part.heading });
+          const size = recheckTokens(part.diff, part.open);
+          if (size > whole.budget) return stopBeforeRound(state, deps, kind, current.rel, { status: 'split_required', tokensIn: size, budget: whole.budget, section: part.heading });
+          built.push(packet);
+        }
+        /** @type {Set<Finding>} the pending findings a session that LISTED them resolved */
+        const resolved = new Set();
         /** @type {Finding[]} */
         const inside = [];
         /** @type {Finding[]} */
         const blocking = [];
-        for (const f of /** @type {Finding[]} */ (review.findings ?? [])) {
-          if (insideHunks(f, diff.hunks)) {
-            inside.push(f);
-            continue;
+        for (const [i, part] of parts.entries()) {
+          const packet = /** @type {any} */ (built[i]);
+          packetInfo = mergePacketInfo(packetInfo, packet);
+          const session = await recheckSession(packet, deps);
+          tokensIn = sum(tokensIn, session.tokens_in);
+          tokensOut = sum(tokensOut, session.tokens_out);
+          if (!session.verdict.ok) {
+            await note(deps, { event: 'review.unavailable', file: current.rel, lens: 'recheck', reason: session.verdict.reason, ...(part.index === null ? {} : { section: part.index }) });
+            return retry(state, kind, session.verdict.reason ?? 'unavailable');
+          }
+          const review = /** @type {Record<string, any>} */ (session.verdict.review);
+          const resolvedIds = new Set((review.resolved ?? []).filter((/** @type {any} */ r) => r?.resolved === true).map((/** @type {any} */ r) => r.id));
+          // only the findings listed in THIS packet can be resolved by its session
+          for (const f of part.open) if (resolvedIds.has(f.id)) resolved.add(f);
+          const found = /** @type {Finding[]} */ (review.findings ?? []);
+          for (const f of part.index === null ? found : sectionFindings(found, part.index)) {
+            if (insideHunks(f, diff.hunks)) {
+              inside.push(f);
+              continue;
+            }
+            draft.late.push(f);
+            lateRows.push({ event: 'review.late_finding', file: current.rel, round: state.round + 1, finding: f.id, severity: f.severity, line_start: f.line_start, line_end: f.line_end, mode: s.late });
+            if (s.late === 'block' && f.severity !== 'nit') blocking.push(f);
           }
-          draft.late.push(f);
-          lateRows.push({ event: 'review.late_finding', file: current.rel, round: state.round + 1, finding: f.id, severity: f.severity, line_start: f.line_start, line_end: f.line_end, mode: s.late });
-          if (s.late === 'block' && f.severity !== 'nit') blocking.push(f);
         }
+        // every pending finding stays open unless the session that listed it resolved it
+        const stillOpen = pending.filter((f) => !resolved.has(f));
+        closed += pending.length - stillOpen.length;
         const triaged = await triageFindings({ file: current.rel, findings: inside, fromJudge: false, diffText: diff.diffText, cfg: deps.cfg, jev: deps.jev, rule: deps.rule, writeRow: deps.writeRow });
         newInHunks = triaged.fix_now.length;
         draft.open = [...stillOpen, ...triaged.fix_now, ...blocking];

package/src/review/packet.mjs

@@ -17,9 +17,10 @@
  * (`git diff --no-index -- /dev/null <file>`). A tracked file with no change yields no packet.
  *
  * Budget (§4.3): `review.budgets.full_in` (`quick_in` for the quick lens), in tokens estimated as
- * bytes / 4. A diff that alone exceeds it ⇒ `split_required`. Otherwise over budget ⇒ the context
- * shrinks to ± `min_context_lines` (`minimal`) FIRST, then the digest is trimmed from the end;
- * the diff is never cut.
+ * bytes / 4. A diff that alone exceeds it ⇒ `split_required` (a Markdown file is then reviewed
+ * section by section — `sections.mjs`, B54). Otherwise over budget ⇒ the context shrinks to
+ * ± `min_context_lines` (`minimal`) FIRST, then the digest is trimmed from the end; the diff is
+ * never cut.
  *
  * Path rule (V4): `file` is repo-root-relative; `./`, `../`, absolute values, symlinks and paths
  * under `.git/` or `.code-forge/` are refused with `bad-path` before git runs. So is anything git
@@ -40,7 +41,8 @@ export const LENSES = Object.freeze(['quick', 'full', 'recheck', 'A', 'B', 'judg
 /** The rules digest never exceeds this many lines (§4.3). */
 export const DIGEST_MAX_LINES = 60;
 
-export const DEFAULT_BUDGETS = Object.freeze({ quick_in: 6000, full_in: 12000, judge_in: 8000 });
+/** `full_in` was 12 000 until B54: a 1,590-line design brief (~25k tokens) was refused unreviewed. */
+export const DEFAULT_BUDGETS = Object.freeze({ quick_in: 6000, full_in: 32000, judge_in: 8000 });
 
 const LENS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'lenses');
 const GIT_TIMEOUT_MS = 30000;
@@ -191,9 +193,9 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   const lensText = loadLens(lens);
   const limit = budget ?? budgetFor(cfg, lens === 'quick' ? 'quick_in' : 'full_in');
   const hunkHeaders = diff.hunks.map((h) => h.header);
-  const diffSection = [`file: ${diff.file}`, 'hunks:', ...hunkHeaders.map((h) => `- ${h}`), '', diff.diffText.trimEnd()].join('\n');
-  const bare = render(lensText, [], '', '', diffSection);
-  if (estimateTokens(bare) > limit) return { status: 'split_required', tokensIn: estimateTokens(bare), budget: limit };
+  const diffSection = diffSectionOf(diff);
+  const bare = bareTokens(lensText, diffSection);
+  if (bare > limit) return { status: 'split_required', tokensIn: bare, budget: limit };
 
   let digest = splitLines(rulesDigest).slice(0, DIGEST_MAX_LINES);
   let ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: contextMode });
@@ -210,6 +212,29 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   return { status: 'ok', text, hunkHeaders, contextMode: ctx.mode, contextLines: ctx.lineCount, digestLines: digest.length, tokensIn, budget: limit, overBudget: tokensIn > limit };
 }
 
+/**
+ * The tokens of the diff-only packet (lens + diff, no digest, facts or context): what
+ * `assemblePacket` holds against the budget before it says `split_required`.
+ * @param {{diff: FileDiff, lens: string}} opts @returns {number}
+ */
+export function diffOnlyTokens({ diff, lens }) {
+  return bareTokens(loadLens(lens), diffSectionOf(diff));
+}
+
+/**
+ * The ONE measure behind `split_required` (`assemblePacket`) and section packing (`diffOnlyTokens`,
+ * B54), so the two can never disagree.
+ * @param {string} lensText @param {string} diffSection @returns {number}
+ */
+function bareTokens(lensText, diffSection) {
+  return estimateTokens(render(lensText, [], '', '', diffSection));
+}
+
+/** @param {FileDiff} diff @returns {string} the `## diff` section body. */
+function diffSectionOf(diff) {
+  return [`file: ${diff.file}`, 'hunks:', ...diff.hunks.map((h) => `- ${h.header}`), '', diff.diffText.trimEnd()].join('\n');
+}
+
 /**
  * @param {string} lensText @param {string[]} digest @param {string} facts @param {string} context
  * @param {string} diffSection

package/src/review/sections.mjs

@@ -0,0 +1,282 @@
+/**
+ * Markdown section packets (block B54, issue #2 field note).
+ *
+ * A Markdown file (`.md`, `.markdown`) whose diff ALONE is over the packet budget
+ * (`split_required`) is reviewed section by section instead of refused:
+ *  1. the headings of the CURRENT file are found (`#`..`######`, ATX; a heading inside a fenced
+ *     code block — ``` or ~~~ — is not one);
+ *  2. every hunk is cut at each heading line it carries on its new side (a context or `+` line), so
+ *     a new or rewritten document — ONE hunk — splits too. Each piece is a valid unified-diff hunk
+ *     with its own header (`@@ -a,b +c,d @@`, real line numbers on both sides); a hunk that holds no
+ *     heading keeps its own header. A piece with no `+`/`-` line joins its neighbour;
+ *  3. the pieces are grouped by the nearest preceding heading (lines before the first heading are
+ *     one group), and consecutive groups are packed, in file order, into section packets whose
+ *     diff-only packet stays within the budget — splits happen only at headings.
+ * One group that alone is still over the budget ⇒ the file stays `split_required` (with that
+ * group's `tokensIn` and its heading): nothing is ever truncated. A diff with no hunk, or whose
+ * hunks do not parse one to one, never yields a section: it is `split_required` too — and so,
+ * fail-safe, is a deleted file or one with no heading whose diff is over the budget (one group). Any other file keeps
+ * `split_required`. Pure functions: no I/O.
+ */
+
+import { parseDiff, splitLines } from './context.mjs';
+
+/** @typedef {import('./packet.mjs').FileDiff} FileDiff */
+
+/** @param {string} file @returns {boolean} whether `file` is reviewed by section when over budget. */
+export const isMarkdownFile = (file) => /\.(md|markdown)$/i.test(file);
+
+/** A fence opener/closer: up to 3 spaces, then 3+ backticks or tildes. */
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+/** An ATX heading: up to 3 spaces, 1–6 `#`, then a space/tab or the end of the line. */
+const HEADING_RE = /^ {0,3}#{1,6}(?:[ \t]|$)/;
+/** A heading is named in results by its text, cut at this many characters. */
+const HEADING_MAX = 120;
+
+/**
+ * The ATX headings of `content`, outside fenced code blocks and outside a YAML front matter block.
+ * @param {string | null} content @returns {Map<number, string>} 1-based line ⇒ the heading line, trimmed.
+ */
+export function markdownHeadings(content) {
+  /** @type {Map<number, string>} */
+  const out = new Map();
+  /** @type {{char: string, len: number} | null} */
+  let fence = null;
+  const lines = splitLines(content).map((raw) => (raw.endsWith('\r') ? raw.slice(0, -1) : raw)); // a CRLF file matches like an LF one
+  // YAML front matter (`---` on line 1 … a closing `---` or `...`) holds no heading
+  const close = lines[0] === '---' ? lines.findIndex((l, i) => i > 0 && (l === '---' || l === '...')) : -1;
+  lines.forEach((line, i) => {
+    if (i <= close) return;
+    const f = FENCE_RE.exec(line);
+    if (fence) {
+      // a closing fence: the same character, at least as long, nothing after it
+      if (f && f[1][0] === fence.char && f[1].length >= fence.len && f[2].trim() === '') fence = null;
+      return;
+    }
+    // a backtick fence whose info string carries a backtick is inline code, not a fence
+    if (f && !(f[1][0] === '`' && f[2].includes('`'))) {
+      fence = { char: f[1][0], len: f[1].length };
+      return;
+    }
+    if (HEADING_RE.test(line)) out.set(i + 1, line.trim().slice(0, HEADING_MAX));
+  });
+  return out;
+}
+
+/**
+ * @typedef {object} Piece - one hunk, or one heading-bounded part of a hunk.
+ * @property {number} key - the line of the nearest preceding heading (0 = before the first).
+ * @property {string | null} header - the original header line when the piece is the whole hunk.
+ * @property {number} oldCursor - the first old-side line the piece covers.
+ * @property {number} newCursor - the first new-side line the piece covers.
+ * @property {string[]} lines - the body lines (` `, `+`, `-`, `\`).
+ */
+
+/** @param {Piece} p @returns {boolean} whether the piece changes anything. */
+const changes = (p) => p.lines.some((l) => l.startsWith('+') || l.startsWith('-'));
+
+/** @param {Map<number, string>} headings @param {number} line @returns {number} the last heading at or before `line`, else 0. */
+function headingAtOrBefore(headings, line) {
+  let best = 0;
+  for (const h of headings.keys()) if (h <= line && h > best) best = h;
+  return best;
+}
+
+/**
+ * Cut one hunk at the heading lines on its new side.
+ * @param {{header: string, oldStart: number, oldLines: number, newStart: number, newLines: number}} hunk
+ * @param {string} headerLine - the hunk's header line as git printed it.
+ * @param {string[]} body @param {Map<number, string>} headings
+ * @returns {Piece[]}
+ */
+function cutHunk(hunk, headerLine, body, headings) {
+  let oldCursor = hunk.oldLines === 0 ? hunk.oldStart + 1 : hunk.oldStart;
+  let newCursor = hunk.newLines === 0 ? hunk.newStart + 1 : hunk.newStart;
+  const firstNew = body.length > 0 && (body[0].startsWith(' ') || body[0].startsWith('+'));
+  /** @type {Piece[]} */
+  const pieces = [{ key: headingAtOrBefore(headings, firstNew ? newCursor : newCursor - 1), header: headerLine, oldCursor, newCursor, lines: [] }];
+  for (const line of body) {
+    const onNew = line.startsWith(' ') || line.startsWith('+');
+    const current = /** @type {Piece} */ (pieces.at(-1));
+    if (onNew && headings.has(newCursor) && current.lines.some((l) => !l.startsWith('\\'))) {
+      pieces.push({ key: newCursor, header: null, oldCursor, newCursor, lines: [] });
+    }
+    /** @type {Piece} */ (pieces.at(-1)).lines.push(line);
+    if (line.startsWith(' ')) {
+      oldCursor += 1;
+      newCursor += 1;
+    } else if (line.startsWith('+')) {
+      newCursor += 1;
+    } else if (line.startsWith('-')) {
+      oldCursor += 1;
+    }
+  }
+  if (pieces.length === 1) return pieces;
+  // a piece that only carries context joins the next piece (or, when last, the previous one)
+  for (let i = 0; i < pieces.length && pieces.length > 1; ) {
+    const p = pieces[i];
+    if (changes(p)) {
+      i += 1;
+      continue;
+    }
+    const next = pieces[i + 1];
+    if (next) pieces[i + 1] = { ...next, oldCursor: p.oldCursor, newCursor: p.newCursor, lines: [...p.lines, ...next.lines] };
+    else pieces[i - 1].lines.push(...p.lines);
+    pieces.splice(i, 1);
+  }
+  for (const p of pieces) p.header = null;
+  if (pieces.length === 1) pieces[0].header = headerLine;
+  return pieces;
+}
+
+/** @param {Piece} p @returns {string} the piece's header line. */
+function headerOf(p) {
+  if (p.header !== null) return p.header;
+  const oldCount = p.lines.filter((l) => l.startsWith(' ') || l.startsWith('-')).length;
+  const newCount = p.lines.filter((l) => l.startsWith(' ') || l.startsWith('+')).length;
+  // an empty side names the line BEFORE the change, as git does (`-0,0` for a new file)
+  return `@@ -${oldCount === 0 ? p.oldCursor - 1 : p.oldCursor},${oldCount} +${newCount === 0 ? p.newCursor - 1 : p.newCursor},${newCount} @@`;
+}
+
+/**
+ * @typedef {object} SectionGroup
+ * @property {number} key - the heading line (0 = before the first heading).
+ * @property {string} heading - the heading line, or `(before first heading)`.
+ * @property {FileDiff} diff - the group's own diff (the file header, then its pieces).
+ */
+
+/**
+ * Split a Markdown file's diff into heading groups (steps 1–3 of the module doc, before packing).
+ * @param {FileDiff} diff
+ * @returns {SectionGroup[] | null} in file order (one group when the file has no heading; none when
+ *   the diff has no hunk); null when the `@@` lines of the text do not match `diff.hunks` one to
+ *   one — a hunk is never dropped silently.
+ */
+export function sectionGroups(diff) {
+  const headings = markdownHeadings(diff.content);
+  const all = diff.diffText.split('\n');
+  if (all.at(-1) === '') all.pop();
+  const first = all.findIndex((l) => l.startsWith('@@'));
+  if (first < 0) return diff.hunks.length === 0 ? [] : null;
+  const fileHeader = all.slice(0, first);
+  /** @type {Piece[]} */
+  const pieces = [];
+  let h = 0;
+  for (let i = first; i < all.length; ) {
+    let end = i + 1;
+    while (end < all.length && !all[end].startsWith('@@')) end += 1;
+    const hunk = diff.hunks[h];
+    if (!hunk || !all[i].startsWith(hunk.header)) return null;
+    h += 1;
+    pieces.push(...cutHunk(hunk, all[i], all.slice(i + 1, end), headings));
+    i = end;
+  }
+  if (h !== diff.hunks.length) return null;
+  /** @type {Array<{key: number, pieces: Piece[]}>} */
+  const groups = [];
+  for (const p of pieces) {
+    const last = groups.at(-1);
+    if (last && last.key === p.key) last.pieces.push(p);
+    else groups.push({ key: p.key, pieces: [p] });
+  }
+  return groups.map((g) => ({ key: g.key, heading: headings.get(g.key) ?? '(before first heading)', diff: diffOf(diff, fileHeader, g.pieces) }));
+}
+
+/**
+ * @param {FileDiff} diff @param {string[]} fileHeader @param {Piece[]} pieces
+ * @returns {FileDiff} the pieces as one file diff (the hunk list re-parsed from its own text).
+ */
+function diffOf(diff, fileHeader, pieces) {
+  const diffText = `${[...fileHeader, ...pieces.flatMap((p) => [headerOf(p), ...p.lines])].join('\n')}\n`;
+  return { file: diff.file, kind: diff.kind, diffText, content: diff.content, ...parseDiff(diffText) };
+}
+
+/**
+ * @typedef {object} Section
+ * @property {number} index - 1-based, in file order.
+ * @property {string[]} headings - the headings the section covers.
+ * @property {number[]} keys - the heading lines of its groups (0 = before the first heading).
+ * @property {FileDiff} diff
+ */
+
+/**
+ * Pack the heading groups into section packets within `budget` (step 3 of the module doc). A
+ * candidate's size is `measure(its diff, its groups)` (a recheck adds the open findings it lists
+ * for those groups). Never `ok` with no section: a diff with no hunk, or one whose hunks do not
+ * parse one to one, is `split_required` at `measure(diff, [])` with `section: null`.
+ * @param {{diff: FileDiff, budget: number, measure: (diff: FileDiff, groups: SectionGroup[]) => number}} opts -
+ *   `measure`: the packet tokens of a candidate (the largest over the session lenses).
+ * @returns {{status: 'ok', sections: Section[]} | {status: 'split_required', tokensIn: number, budget: number, section: string | null}}
+ */
+export function packSections({ diff, budget, measure }) {
+  const groups = sectionGroups(diff);
+  if (groups === null || groups.length === 0) return { status: 'split_required', tokensIn: measure(diff, []), budget, section: null };
+  /** @param {SectionGroup[]} set */
+  const size = (set) => measure(merge(diff, set), set);
+  /** @type {Section[]} */
+  const sections = [];
+  /** @type {SectionGroup[]} */
+  let open = [];
+  const flush = () => {
+    if (open.length === 0) return;
+    sections.push({ index: sections.length + 1, headings: open.map((g) => g.heading), keys: open.map((g) => g.key), diff: merge(diff, open) });
+    open = [];
+  };
+  for (const g of groups) {
+    const alone = size([g]);
+    if (alone > budget) return { status: 'split_required', tokensIn: alone, budget, section: g.heading };
+    if (open.length > 0 && size([...open, g]) > budget) flush();
+    open.push(g);
+  }
+  flush();
+  return { status: 'ok', sections };
+}
+
+/**
+ * @param {FileDiff} diff @param {SectionGroup[]} groups @returns {FileDiff} the groups as one diff.
+ */
+function merge(diff, groups) {
+  if (groups.length === 1) return groups[0].diff;
+  const bodies = groups.map((g) => {
+    const text = g.diff.diffText;
+    return text.slice(text.startsWith('@@') ? 0 : text.indexOf('\n@@') + 1);
+  });
+  const head = groups[0].diff.diffText;
+  const fileHeader = head.startsWith('@@') ? '' : head.slice(0, head.indexOf('\n@@') + 1);
+  const diffText = `${fileHeader}${bodies.join('')}`;
+  return { file: diff.file, kind: diff.kind, diffText, content: diff.content, ...parseDiff(diffText) };
+}
+
+/**
+ * Where an open finding is listed in a sectioned recheck (each open finding in exactly ONE packet).
+ * Contract: with at least one section, always a valid position — the section whose hunks span the
+ * finding's first line, else the nearest section by line distance (ties go to the earlier one), so
+ * a finding outside every section (a late finding kept open by `review.late_findings: block`, a
+ * line that moved in the fix) still lands in one; -1 only when `sections` is empty.
+ * @param {ReadonlyArray<{diff: FileDiff}>} sections @param {{line_start: number}} finding
+ * @returns {number} the position in `sections`, or -1.
+ */
+export function sectionOf(sections, finding) {
+  let best = -1;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  sections.forEach((s, i) => {
+    const start = Math.min(...s.diff.hunks.map((h) => h.newStart));
+    const end = Math.max(...s.diff.hunks.map((h) => h.newStart + Math.max(h.newLines, 1) - 1));
+    const line = finding.line_start;
+    const distance = line < start ? start - line : line > end ? line - end : 0;
+    if (distance < bestDistance) {
+      best = i;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+/**
+ * A section's findings with ids unique per file: `S<index>.<id>`.
+ * @template {{id: string}} F
+ * @param {ReadonlyArray<F>} findings @param {number} index @returns {F[]}
+ */
+export function sectionFindings(findings, index) {
+  return findings.map((f) => ({ ...f, id: `S${index}.${f.id}` }));
+}

package/src/worker/engine.mjs

@@ -15,7 +15,8 @@
  *    last round reviewed and the current content), with the open findings by id;
  *  - `next: patch` (the L3 rung at the cap) ⇒ the `patch_check` round; a `retry` re-runs its round;
  *  - `stopped` (`review_cap`, `l3_patch_exhausted`, `split_required`) ⇒ no session: the result
- *    repeats the stop — only the human moves on (§4.11 rule 5).
+ *    repeats the stop — only the human moves on (§4.11 rule 5). A `split_required` result (round 1
+ *    or a recheck stop) carries `tokens_in` and `budget` (B54).
  * The round's outcome: `approved: true` ONLY when the loop is `complete` AND its signed
  * `review.approved` row (keyed `run, block, file, content_hash` = the ticket's hash) was written;
  * else `findings` = the open fix list, `next` = what the orchestrator does (`fix` at `level`,
@@ -83,6 +84,10 @@ import { assertTicketId } from './ticket.mjs';
  * @property {string | null} [trigger] - `review_stall`, `review_rounds`, `review_cap`, or null.
  * @property {string} [stopped] - the stop reason (`review_cap`, `l3_patch_exhausted`, …).
  * @property {number} [late] - late findings recorded so far for the file.
+ * @property {number} [tokens_in] - `split_required` (or `stopped: split_required`): the estimated
+ *   tokens of the diff-only packet that was over the budget (B54).
+ * @property {number} [budget] - with `tokens_in`: the packet budget it exceeded (B54).
+ * @property {string} [section] - a Markdown file's section that alone is over the budget (B54).
  */
 
 /**
@@ -302,7 +307,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, blockKindOf, key,
     reopenForExtraRound(state, extraRounds, ctx.cfg);
 
     if (state.status === 'stopped') {
-      return { outcome: /** @type {ReviewOutcome} */ ({ ...loopFields(state, null), status: 'stopped', stopped: state.next?.reason ?? 'stopped', approved: false, engine: 'adaptive', sessions: [], findings: state.open }) };
+      return { outcome: /** @type {ReviewOutcome} */ ({ ...loopFields(state, null), status: 'stopped', stopped: state.next?.reason ?? 'stopped', ...stopSize(state), approved: false, engine: 'adaptive', sessions: [], findings: state.open }) };
     }
 
     /** @type {'full' | 'recheck' | 'patch_check'} */
@@ -404,7 +409,7 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     if (!approvalWritten) return { ...head, status: 'unavailable', reason: 'approval-not-written', approved: false };
     return { ...head, status: 'reviewed', approved: true, findings: [] };
   }
-  if (status === 'stopped') return { ...head, status: 'stopped', stopped: next?.reason ?? 'stopped', approved: false, findings: state.open };
+  if (status === 'stopped') return { ...head, status: 'stopped', stopped: next?.reason ?? 'stopped', ...stopSize(state), approved: false, findings: state.open };
   return { ...head, status: 'reviewed', approved: false, reason: 'findings-open', findings: state.open };
 }
 
@@ -457,6 +462,18 @@ function loopFields(state, kind) {
   return { round: state.round, ...(kind ? { kind } : {}), level: state.level, next: state.next, trigger: state.next?.trigger ?? null, late: state.late.length };
 }
 
+/**
+ * B54: a `split_required` stop's packet size (`tokens_in`, `budget` — null when unknown — and a
+ * Markdown `section`), from the state's `next`; nothing for any other stop.
+ * @param {import('../review/fixloop.mjs').FileState} state @returns {{tokens_in?: number | null, budget?: number | null, section?: string}}
+ */
+function stopSize(state) {
+  const next = state.next;
+  if (next?.reason !== 'split_required') return {};
+  const fin = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  return { tokens_in: fin(next.tokens_in), budget: fin(next.budget), ...(typeof next.section === 'string' ? { section: next.section } : {}) };
+}
+
 /**
  * S1 through `askJev` with the worker's key bound (the key stays in this process).
  * @param {string} key @returns {import('../review/triage.mjs').JevAsk}

package/src/worker/loop.mjs

@@ -159,6 +159,21 @@ export function loopResult(outcome) {
   return out;
 }
 
+/**
+ * B54: the packet size of a `split_required` outcome (round 1 `status: split_required`, or a
+ * recheck `stopped: split_required`) — and ONLY of one: `tokens_in` and `budget` always (null when
+ * not a finite number), plus the Markdown `section` that alone is over the budget when one is named. The result
+ * file and the ledger `review.result` row carry the same fields.
+ * @param {Record<string, any>} outcome @returns {Record<string, any>}
+ */
+export function packetSize(outcome) {
+  if (outcome.status !== 'split_required' && outcome.stopped !== 'split_required') return {};
+  return { tokens_in: finiteOrNull(outcome.tokens_in), budget: finiteOrNull(outcome.budget), ...(typeof outcome.section === 'string' ? { section: outcome.section } : {}) };
+}
+
+/** @param {unknown} v @returns {number | null} `v` when a finite number, else null. */
+export const finiteOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
 /**
  * B52: the verdict a result is recorded with (its signed file and its ledger row), always with
  * `approved` and `open`: `approved: true, open: []` only when the outcome said so AND it lists no
@@ -302,6 +317,7 @@ export async function createWorker(opts, deps = {}) {
         engine: outcome.engine,
         ...(typeof outcome.reason === 'string' ? { reason: outcome.reason } : {}),
         ...(Array.isArray(outcome.findings) ? { findings: outcome.findings } : {}),
+        ...packetSize(outcome),
         ...loopResult(outcome),
         sessions: outcome.sessions,
       };
@@ -387,6 +403,8 @@ export async function createWorker(opts, deps = {}) {
         ...(typeof result.reason === 'string' ? { reason: result.reason } : {}),
         ...(typeof result.trigger === 'string' ? { trigger: result.trigger } : {}),
         ...(typeof result.stopped === 'string' ? { stopped: result.stopped } : {}),
+        // B54: a split_required result says how far over the budget it was (the result file's fields)
+        ...packetSize(result),
       });
     } catch {
       // the signed result file stands; the gate reads it (§4.6)