@codedology/code-forge 0.1.0

package/src/decide/author-loop.mjs

@@ -0,0 +1,90 @@
+/**
+ * The author loop's SHAPE (plan §3.7, O18) — types and pure loop-continuation logic only. The
+ * actual `code-forge author` session runner (spawning a fresh L3 closed-book session, writing the
+ * draft to `plans_dir`, printing questions to the human, collecting answers, re-invoking with
+ * `--draft`/`--answers`) is B9's `src/session/author.mjs` (C3: "no `s2.mjs` here" — likewise no
+ * session-spawning code here). What belongs to the DECISION layer is the deterministic question
+ * of "is this loop done", which B9's runner calls after every round instead of re-deriving the
+ * same rule inline.
+ *
+ * §3.7, verbatim: "stop when `questions[]` is empty or contains only non-blocking items the human
+ * chose to skip." Read literally (fix round 1, review finding "spec deviation"): a BLOCKING
+ * question in the latest round keeps the loop going, full stop — there is no "skip" path for a
+ * blocking item, and `skippedIds` never clears one. Only a NON-blocking item can be cleared, and
+ * only by being in `skippedIds` (the human explicitly chose to skip it — an item the human simply
+ * hasn't looked at yet does NOT count). A blocking question stops being "in the latest round" only
+ * because a LATER `author` call, given the human's real answer, omitted it — that happens upstream
+ * of this module, in B9's loop.
+ */
+
+/**
+ * @typedef {object} AuthorQuestion
+ * @property {string} id
+ * @property {string} question
+ * @property {string[]} [options]
+ * @property {string} [why]
+ * @property {boolean} blocking
+ */
+
+/**
+ * Validates the one shape this module actually depends on — FAILS CLOSED (review finding "fails
+ * open"): `questions[]` is parsed LLM JSON, so a missing/typo'd `blocking` field must be a loud
+ * `TypeError`, never a silent "treat as non-blocking" that could let the loop stop while a real
+ * blocking question sits unanswered.
+ * @param {any} q
+ * @returns {asserts q is AuthorQuestion}
+ */
+function assertQuestionShape(q) {
+  if (q === null || typeof q !== 'object') {
+    throw new TypeError('author-loop: each question must be an object');
+  }
+  if (typeof q.id !== 'string' || q.id.length === 0) {
+    throw new TypeError('author-loop: question.id must be a non-empty string');
+  }
+  if (typeof q.blocking !== 'boolean') {
+    throw new TypeError(`author-loop: question ${JSON.stringify(q.id)}.blocking must be a boolean, got ${typeof q.blocking}`);
+  }
+}
+
+/**
+ * @param {any} questions - untrusted (parsed `author` JSON output); validated per-item, not just
+ *   `Array.isArray` — see {@link assertQuestionShape}.
+ * @returns {AuthorQuestion[]}
+ */
+export function blockingQuestions(questions) {
+  if (!Array.isArray(questions)) {
+    throw new TypeError('blockingQuestions: questions must be an array');
+  }
+  questions.forEach(assertQuestionShape);
+  return questions.filter((q) => q.blocking === true);
+}
+
+/**
+ * @param {any} questions - the LATEST round's `questions[]` from `author`'s output.
+ * @param {Iterable<string>} [skippedIds] - NON-blocking ids the human explicitly chose to skip
+ *   this round. Never clears a blocking id (§3.7 — see the module header).
+ * @returns {boolean} `true` when the loop should stop.
+ */
+export function isAuthorLoopDone(questions, skippedIds = []) {
+  if (!Array.isArray(questions)) {
+    throw new TypeError('isAuthorLoopDone: questions must be an array');
+  }
+  if (questions.length === 0) {
+    return true;
+  }
+  questions.forEach(assertQuestionShape);
+  const skipped = skippedIds instanceof Set ? skippedIds : new Set(skippedIds);
+  return questions.every((q) => !q.blocking && skipped.has(q.id));
+}
+
+/**
+ * The blocking questions still standing in the way of stopping — under §3.7 that is EVERY
+ * blocking question in `questions[]` (a blocking item is never "resolved" by a skip set; see the
+ * module header). Kept as its own export, distinct from {@link blockingQuestions}, for the
+ * call-site clarity of "what must the human still answer before this loop can finish".
+ * @param {any} questions
+ * @returns {AuthorQuestion[]}
+ */
+export function remainingBlockingQuestions(questions) {
+  return blockingQuestions(questions);
+}

package/src/decide/escalation.mjs

@@ -0,0 +1,262 @@
+/**
+ * Escalation precedence — deterministic (plan §3.6, O10, R1; v1.3 adds rule 2b `review_stall`
+ * and rule 6 `review_cap`, §4.11). "Evaluated in this order after every attempt; the first rule
+ * that fires wins":
+ *
+ *   1. Attempt counter — attempts at the current level == `retries_per_level` (2) and not green
+ *      ⇒ +1 level, whatever S1 said (`trigger: 'retries'`).
+ *   2b. Review stall (v1.3) — a re-check round whose open `fix_now` set did NOT strictly shrink
+ *      (`reviewRoundStalled` below) ⇒ +1 level IMMEDIATELY (`trigger: 'review_stall'`), checked
+ *      BEFORE rule 2's own round-exhaustion counter — a block need not exhaust
+ *      `review_rounds_per_level` to escalate on a stalled round.
+ *   2. Review rounds — `review_rounds_per_level` (2) exhausted with an open `fix_now` finding
+ *      ⇒ +1 level (`trigger: 'review_rounds'`).
+ *   3. Security floor (DISPATCH time only) — `security_sensitive == true` ⇒ first-attempt level
+ *      = `min(max(lane, L1) + 1, L2)` (`trigger: 'security'`). This is the one rule that fires
+ *      before the first attempt, not after one — `dispatchLevel()` below is its own entry point,
+ *      never folded into `escalationAfterAttempt()`.
+ *   4. S2 ruling — S1 `next = escalate` is never acted on directly; it goes to S2 as a check
+ *      (`trigger: 's2_ruling'`, `action: 's2_check'`). S1 `next = stop` routes straight to the
+ *      human (`action: 'stop'`).
+ *   5. Never skip a level; `stop_at: L3` is fixed. L3 is never a RUNNING level (R1: "the L3 rung
+ *      is a patch, not bulk coding"; the block continues at L2): the running ceiling is
+ *      `MAX_RUNNING_LEVEL` (L2), or `stop_at` when lower. When rule 1, 2b or 2 fires AND the block
+ *      is already at the running ceiling, there IS no "+1 level" to go to. R1's L3 rung takes
+ *      over instead: `escalation.l3_mode: 'patch'` (default) routes to a fresh L3
+ *      session that returns a PATCH, never a whole feature (`action: 'l3_rung', mode: 'patch'`).
+ *      `l3_mode: 'code'` keeps D4 literal — the block keeps coding at L3 ONCE more
+ *      (`action: 'escalate', level: 'L3'`), no patch machinery. Either way, a SECOND ceiling hit
+ *      on the same block (`l3RungAlreadyUsed`) always `stop`s (fix round 1: `l3_mode: 'code'`
+ *      used to have no end state at all — the caller resets its attempt counter, so rules 1/2
+ *      would fire again every `retriesPerLevel` failures forever, never honouring `stop_at`).
+ *      A `stop_at` below L3 (schema-rejected; defensive) has no rung: at its ceiling ⇒ `stop`
+ *      (`reason: 'stop_at'`).
+ *   6. Review cap (v1.3) — `review.max_rounds_per_file` (default 4) reached on a file with an
+ *      open `fix_now` finding ⇒ the L3 patch rung for THAT FILE, once (`trigger: 'review_cap'`,
+ *      `action: 'l3_rung', mode: 'patch'` — always `'patch'`, regardless of `l3Mode`: a round-cap
+ *      breach is a fix-scale problem, never a whole re-code). It shares the SAME
+ *      `l3RungAlreadyUsed` flag as rule 5 — the plan's L3 rung is one per block, not one per
+ *      trigger — so a second breach from EITHER rule 5 or rule 6 always `stop`s
+ *      (`reason: 'review_cap'`). Checked last: it only matters when rules 1/2b/2/4 did not
+ *      already return an action this attempt.
+ *
+ * Rules 1, 2b, 2, 4 and 6 are the six *triggered* rules of the precedence table (each carries its
+ * own `trigger` name); rule 5 is the ceiling guard folded into `finalizeEscalate` below, not a
+ * seventh trigger.
+ */
+
+/** Level order, low to high. `escalation.stop_at` is schema-fixed to `'L3'` (B1's `checkStopAtNotL3`). */
+export const LEVEL_ORDER = Object.freeze(['L0', 'L1', 'L2', 'L3']);
+
+/**
+ * @param {string} level
+ * @returns {number}
+ * @throws {TypeError} for anything not one of `LEVEL_ORDER`.
+ */
+export function levelIndex(level) {
+  const i = LEVEL_ORDER.indexOf(level);
+  if (i === -1) {
+    throw new TypeError(`levelIndex: unknown level ${JSON.stringify(level)} (expected one of ${LEVEL_ORDER.join(', ')})`);
+  }
+  return i;
+}
+
+/**
+ * @param {string} current
+ * @param {string} [stopAt]
+ * @returns {string} `current`'s successor, capped at `stopAt` — never skips a level, never
+ *   exceeds the ceiling (rule 5's "never skip a level" half; the "at the ceiling" half lives in
+ *   `escalationAfterAttempt`'s `finalizeEscalate`).
+ */
+export function nextLevelCapped(current, stopAt = 'L3') {
+  const capIndex = levelIndex(stopAt);
+  return LEVEL_ORDER[Math.min(levelIndex(current) + 1, capIndex)];
+}
+
+/**
+ * Rule 3's arithmetic: `min(max(lane, L1) + 1, L2)`.
+ * @param {string} lane - `'L0'|'L1'|'L2'` (§O10: "L3 is not a lane").
+ * @returns {string}
+ */
+export function securityFloorLevel(lane) {
+  const idx = Math.min(Math.max(levelIndex(lane), levelIndex('L1')) + 1, levelIndex('L2'));
+  return LEVEL_ORDER[idx];
+}
+
+/**
+ * Rule 3, at dispatch time only — call this once per block, before the first attempt.
+ * @param {{lane: string, securitySensitive: boolean}} ctx
+ * @returns {{level: string, trigger: 'security'|null}}
+ */
+export function dispatchLevel({ lane, securitySensitive }) {
+  if (securitySensitive) {
+    return { level: securityFloorLevel(lane), trigger: 'security' };
+  }
+  return { level: lane, trigger: null };
+}
+
+/**
+ * Rule 4's floor: `next = 'escalate'` (and `'stop'`) must never be acted on directly by the
+ * orchestrator — both always route through this module's rule 4, never straight to "continue as
+ * S1 said" even when `thresholds.decide()` reported `decided: true` for the `next` question.
+ * @param {string} next
+ * @returns {boolean}
+ */
+export function mustRouteNextThroughEscalation(next) {
+  return next === 'escalate' || next === 'stop';
+}
+
+/**
+ * Rule 2b's shrink test (v1.3, §4.11): a re-check round's open `fix_now` count must be STRICTLY
+ * less than the previous round's. Equal or larger ⇒ the round stalled.
+ * @param {number} openBefore - open `fix_now` count entering this round.
+ * @param {number} openAfter - open `fix_now` count after this round's fixes + recheck.
+ * @returns {boolean} true when the round did NOT strictly shrink (a stall).
+ */
+export function reviewRoundStalled(openBefore, openAfter) {
+  return openAfter >= openBefore;
+}
+
+/**
+ * The highest level a block CODES at (R1, D4, §0.7: "the L3 rung is a patch, not bulk coding";
+ * §3.6: after the patch "the block continues at L2"). L3 is never a running level — it is only
+ * the one-shot rung that `finalizeEscalate` returns once the block is at this ceiling.
+ */
+export const MAX_RUNNING_LEVEL = 'L2';
+
+/**
+ * @param {string} stopAt - `escalation.stop_at`.
+ * @returns {string} the running ceiling: `MAX_RUNNING_LEVEL`, lowered to `stopAt` when that is
+ *   lower (defensive — B1's schema fixes `stop_at` to `'L3'`).
+ */
+export function runningCeiling(stopAt = 'L3') {
+  return LEVEL_ORDER[Math.min(levelIndex(MAX_RUNNING_LEVEL), levelIndex(stopAt))];
+}
+
+/**
+ * Rules 1, 2b and 2 share this: below the running ceiling ⇒ +1 level (never to L3); at the
+ * running ceiling ⇒ rule 5, the block's one L3 rung (R1), then `stop`.
+ * @param {'retries'|'review_rounds'|'review_stall'} trigger
+ * @param {string} currentLevel
+ * @param {string} stopAt
+ * @param {'patch'|'code'} l3Mode
+ * @param {boolean} l3RungAlreadyUsed - the L3 rung was already used once on THIS block, in
+ *   EITHER mode and from either rule 5 or rule 6 (one rung per block, not per trigger). A second
+ *   hit always stops.
+ * @returns {EscalationResult}
+ */
+function finalizeEscalate(trigger, currentLevel, stopAt, l3Mode, l3RungAlreadyUsed) {
+  const ceiling = runningCeiling(stopAt);
+  if (levelIndex(currentLevel) < levelIndex(ceiling)) {
+    return { trigger, action: 'escalate', level: nextLevelCapped(currentLevel, ceiling) };
+  }
+  // At (or, after an `l3_mode: code` turn, above) the running ceiling: rule 5.
+  if (stopAt !== 'L3') {
+    // `stop_at` below L3 forbids any L3 session, so there is no rung to take (§3.6 fixes
+    // `stop_at: L3`; this only guards a hand-built ctx).
+    return { trigger, action: 'stop', reason: 'stop_at' };
+  }
+  if (l3RungAlreadyUsed) {
+    return { trigger, action: 'stop', reason: l3Mode === 'code' ? 'l3_code_exhausted' : 'l3_patch_exhausted' };
+  }
+  if (l3Mode === 'code') {
+    // D4 literal: ONE coding turn at L3 (the caller resets its attempt counter); the next
+    // ceiling hit falls into the `l3RungAlreadyUsed` branch above and stops.
+    return { trigger, action: 'escalate', level: 'L3' };
+  }
+  return { trigger, action: 'l3_rung', mode: 'patch' };
+}
+
+/**
+ * @typedef {object} EscalationCtx
+ * @property {number} [attemptsAtLevel]
+ * @property {number} [retriesPerLevel] - `escalation.retries_per_level`, default 2.
+ * @property {boolean} [gateGreen] - whether the block's gate is green on this attempt.
+ * @property {number} [reviewRoundsAtLevel]
+ * @property {number} [reviewRoundsPerLevel] - `escalation.review_rounds_per_level`, default 2.
+ * @property {boolean} [openFixNowFinding] - an unresolved `fix_now` finding remains open.
+ * @property {boolean} [reviewStall] - rule 2b (v1.3, §4.11): this round's open `fix_now` set did
+ *   NOT strictly shrink (see `reviewRoundStalled`). Checked, and fires, before rule 2's own
+ *   `reviewRoundsAtLevel` counter is exhausted.
+ * @property {'complete'|'retry'|'escalate'|'stop'|undefined} [s1Next] - S1's `next` answer.
+ * @property {string} [currentLevel] - REQUIRED at runtime (checked below, throws when absent);
+ *   optional in this typedef only so a deliberately-invalid `{}` type-checks in a test that
+ *   proves the runtime check fires.
+ * @property {string} [stopAt] - `escalation.stop_at`, default `'L3'`.
+ * @property {'patch'|'code'} [l3Mode] - `escalation.l3_mode`, default `'patch'` (R1).
+ * @property {boolean} [l3RungAlreadyUsed] - the L3 rung (ceiling, rule 5, OR the file's review
+ *   cap, rule 6) was already used once before on THIS block, from either source. A second hit
+ *   always `stop`s — the plan's L3 rung is one per block, not one per trigger.
+ * @property {number} [roundsAtFile] - rule 6 (v1.3, §4.11): total review rounds run on this file
+ *   so far, counted across every level — unlike `reviewRoundsAtLevel`, this is never reset by a
+ *   level escalation.
+ * @property {number} [maxRoundsPerFile] - `review.max_rounds_per_file`, default 4 (schema
+ *   minimum 2, maximum 6; B1.1).
+ *
+ * @typedef {object} EscalationResult
+ * @property {'retries'|'review_stall'|'review_rounds'|'s2_ruling'|'review_cap'|null} trigger
+ * @property {'escalate'|'s2_check'|'stop'|'l3_rung'|'none'} action
+ * @property {string} [level]
+ * @property {string} [mode]
+ * @property {string} [reason]
+ */
+
+/**
+ * Rules 1, 2b, 2, 4 and 6 (rule 3 is `dispatchLevel`; rule 5 is the ceiling guard inside
+ * `finalizeEscalate`), evaluated in the documented order — the first rule that fires wins.
+ * @param {EscalationCtx} ctx
+ * @returns {EscalationResult}
+ */
+export function escalationAfterAttempt(ctx) {
+  const {
+    attemptsAtLevel = 0,
+    retriesPerLevel = 2,
+    gateGreen = false,
+    reviewRoundsAtLevel = 0,
+    reviewRoundsPerLevel = 2,
+    openFixNowFinding = false,
+    reviewStall = false,
+    s1Next,
+    currentLevel,
+    stopAt = 'L3',
+    l3Mode = 'patch',
+    l3RungAlreadyUsed = false,
+    roundsAtFile = 0,
+    maxRoundsPerFile = 4,
+  } = ctx;
+
+  if (typeof currentLevel !== 'string') {
+    throw new TypeError('escalationAfterAttempt: ctx.currentLevel is required');
+  }
+
+  // Rule 1: attempt counter.
+  if (attemptsAtLevel >= retriesPerLevel && !gateGreen) {
+    return finalizeEscalate('retries', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);
+  }
+  // Rule 2b: review stall — fires immediately, ahead of rule 2's own round-exhaustion counter.
+  if (reviewStall && openFixNowFinding) {
+    return finalizeEscalate('review_stall', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);
+  }
+  // Rule 2: review rounds.
+  if (reviewRoundsAtLevel >= reviewRoundsPerLevel && openFixNowFinding) {
+    return finalizeEscalate('review_rounds', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);
+  }
+  // Rule 4: S2 ruling.
+  if (s1Next === 'escalate') {
+    return { trigger: 's2_ruling', action: 's2_check' };
+  }
+  if (s1Next === 'stop') {
+    return { trigger: 's2_ruling', action: 'stop' };
+  }
+  // Rule 6: review cap — the file's absolute round count, independent of the escalation level.
+  // Always `patch` (never `l3Mode: 'code'`): a round-cap breach is a fix-scale problem. Shares
+  // `l3RungAlreadyUsed` with rule 5's ceiling guard (one L3 rung per block, not per trigger).
+  if (roundsAtFile >= maxRoundsPerFile && openFixNowFinding) {
+    if (l3RungAlreadyUsed) {
+      return { trigger: 'review_cap', action: 'stop', reason: 'review_cap' };
+    }
+    return { trigger: 'review_cap', action: 'l3_rung', mode: 'patch' };
+  }
+  // No rule fired this attempt.
+  return { trigger: null, action: 'none' };
+}

package/src/decide/fallback-rules.mjs

@@ -0,0 +1,172 @@
+/**
+ * Fallback when Jev is unavailable (plan §3.5, O9/O27) — `system1.fallback`, default `'rules'`.
+ * Layer 1 of that fallback: deterministic rules for `lane`, `risk` and `security_sensitive` (ALL
+ * THREE are always resolvable this way — "a rule that fires is final", so these three question
+ * ids never sit in the residue), and for `next` only "when the evidence is unambiguous". The
+ * plan's residue set — the questions rules cannot cover: `defect`, `resolved`, an AMBIGUOUS
+ * `next`, and `scope` — goes to S2 instead, tagged `source: 's2-fallback'` so §3.4's
+ * `> 6 non-fallback S2 calls per block ⇒ s2-heavy` counter never counts it.
+ *
+ * **Rule inputs are pre-computed facts, not raw diffs.** This module does no path-globbing, no
+ * git diffing, no gate-output parsing — that belongs to the caller (B5's gate/scope machinery,
+ * B9's evidence normalizer), which already has to do it anyway for the deterministic gate itself.
+ * Keeping these functions pure over a small fact object keeps them exhaustively unit-testable and
+ * decoupled from any one block's I/O.
+ */
+
+/** Keywords the plan names for the fallback rules (§3.5): "Money, Policy, Auth, Webhook, migration". */
+export const FALLBACK_KEYWORDS = Object.freeze(['Money', 'Policy', 'Auth', 'Webhook', 'migration']);
+
+/** Diff-size floor above which a change is at least L1 (§3.5). */
+export const LANE_SIZE_FILES_FLOOR = 4;
+export const LANE_SIZE_LINES_FLOOR = 200;
+
+/** `> 6 non-fallback S2 calls per block ⇒ s2-heavy` (§3.4). */
+export const S2_HEAVY_THRESHOLD = 6;
+
+/**
+ * @typedef {object} FallbackFacts
+ * @property {boolean} [pathFloorHit] - a changed path matches `proof.tiers.high.paths` (§3.5:
+ *   "Path floors ... ⇒ risk 3, security true").
+ * @property {number} [filesChanged]
+ * @property {number} [linesAdded]
+ * @property {boolean} [touchesMigration]
+ * @property {boolean} [touchesPolicyOrMiddleware]
+ * @property {string[]} [keywordsFound] - any of `FALLBACK_KEYWORDS` found in the task text/diff/paths.
+ */
+
+/**
+ * §3.5, verbatim: "diff size (> 200 added lines or > 4 files ⇒ **≥ L1**)". The "≥" only means
+ * something if the baseline BELOW that floor is lower than L1 — so a change that trips neither
+ * the migration/policy/path floor NOR the size floor is `'L0'` (trivial), and the size floor's
+ * whole job is to bump an otherwise-untagged-but-sizeable diff up to `'L1'` (fix round 1: the old
+ * version returned `'L1'` on BOTH the size branch and the fall-through default, making the size
+ * floor dead code and `'L0'` unreachable despite the JSDoc return type listing it).
+ * @param {FallbackFacts} facts
+ * @returns {'L0'|'L1'|'L2'} never `null` — lane is always rule-covered in fallback mode.
+ */
+export function fallbackLane(facts = {}) {
+  if (facts.touchesMigration || facts.touchesPolicyOrMiddleware || facts.pathFloorHit) {
+    return 'L2';
+  }
+  if ((facts.filesChanged ?? 0) > LANE_SIZE_FILES_FLOOR || (facts.linesAdded ?? 0) > LANE_SIZE_LINES_FLOOR) {
+    return 'L1';
+  }
+  return 'L0';
+}
+
+/**
+ * @param {FallbackFacts} facts
+ * @returns {0|1|2|3} never `null` — risk is always rule-covered in fallback mode.
+ */
+export function fallbackRisk(facts = {}) {
+  if (facts.pathFloorHit) return 3;
+  if (facts.touchesMigration || facts.touchesPolicyOrMiddleware) return 2;
+  if ((facts.filesChanged ?? 0) > LANE_SIZE_FILES_FLOOR || (facts.linesAdded ?? 0) > LANE_SIZE_LINES_FLOOR) return 1;
+  return 0;
+}
+
+/** Keywords whose presence, by themselves, mean the change touches a security-sensitive domain. */
+const SECURITY_KEYWORDS = Object.freeze(['Auth', 'Webhook', 'Money']);
+
+/**
+ * @param {FallbackFacts} facts
+ * @returns {boolean} never `null` — security_sensitive is always rule-covered in fallback mode.
+ */
+export function fallbackSecuritySensitive(facts = {}) {
+  if (facts.pathFloorHit) return true;
+  return (facts.keywordsFound ?? []).some((k) => SECURITY_KEYWORDS.includes(k));
+}
+
+/**
+ * Resolve the three ALWAYS-covered dispatch questions by rules alone — every entry is
+ * `source: 'rules'`, so a caller counting S2 calls over the result gets exactly 0.
+ * @param {FallbackFacts} facts
+ * @returns {{lane: {value: string, source: 'rules'}, risk: {value: number, source: 'rules'}, security_sensitive: {value: boolean, source: 'rules'}}}
+ */
+export function resolveDispatchQuestionsByRules(facts = {}) {
+  return {
+    lane: { value: fallbackLane(facts), source: 'rules' },
+    risk: { value: fallbackRisk(facts), source: 'rules' },
+    security_sensitive: { value: fallbackSecuritySensitive(facts), source: 'rules' },
+  };
+}
+
+/**
+ * @typedef {object} NextEvidence
+ * @property {boolean} allGreen - every gate (tests/lint/types/format) passed.
+ * @property {number} attempt
+ * @property {boolean} [spreading] - failures grew across attempts, or span more than one file/area.
+ * @property {boolean} [newTestsAdded]
+ * @property {string} [noNewTestsReason]
+ */
+
+/**
+ * `next`, "when the evidence is unambiguous" (§3.5) — the one rule-covered question that CAN be
+ * residue: an ambiguous case (spreading failures, or a later attempt with no clear single cause)
+ * returns `null`, and the caller must route it to S2 instead (`source: 's2-fallback'`).
+ * @param {NextEvidence} evidence
+ * @returns {'complete'|'retry'|null}
+ */
+export function fallbackNext(evidence) {
+  if (evidence.allGreen && (evidence.newTestsAdded || Boolean(evidence.noNewTestsReason))) {
+    return 'complete';
+  }
+  if (!evidence.allGreen && !evidence.spreading && (evidence.attempt ?? 1) <= 1) {
+    return 'retry';
+  }
+  return null;
+}
+
+/**
+ * @param {NextEvidence} evidence
+ * @returns {{value: 'complete'|'retry', source: 'rules'} | {value: null, source: 's2-fallback'}}
+ */
+export function resolveNextByRules(evidence) {
+  const value = fallbackNext(evidence);
+  return value === null ? { value: null, source: 's2-fallback' } : { value, source: 'rules' };
+}
+
+/**
+ * `defect`, `resolved` and `scope` have no rule at all — they are ALWAYS residue in fallback mode.
+ * @param {string} _id - one of `'defect'|'resolved'|'scope'`; accepted as a plain `string` (not
+ *   narrowed further) for call-site clarity/documentation only — this function ignores it.
+ * @returns {{value: null, source: 's2-fallback'}}
+ */
+export function alwaysResidue(_id) {
+  return { value: null, source: 's2-fallback' };
+}
+
+/**
+ * How many of `entries` actually require an S2 call — anything whose `source` isn't `'rules'`
+ * (a floor/keyword/size rule fired and answered outright) needs S2, whether that S2 call is a
+ * fallback residue (`'s2-fallback'`) or, later, an ordinary band check (`'s2'`). This is the
+ * literal "S2 call count" the plan's acceptance clause names: a batch resolved entirely by rules
+ * (the floor path) counts 0; a batch with one residue entry (e.g. an ambiguous `next`) counts 1.
+ * @param {{source: string}[]} entries
+ * @returns {number}
+ */
+export function countS2Calls(entries) {
+  return entries.filter((entry) => entry.source !== 'rules').length;
+}
+
+/**
+ * The `s2-heavy` counter (§3.4) counts only NON-fallback S2 calls — a `source: 's2-fallback'`
+ * call is exempt (§3.5): Jev being down for the whole run must not itself trip a "this block is
+ * asking S2 too much" flag.
+ * @param {string} source
+ * @returns {boolean}
+ */
+export function countsTowardS2Heavy(source) {
+  return source === 's2' || source === 's2-check' || source === 's2-decide';
+}
+
+/**
+ * @param {{source: string}[]} s2Calls - every S2 invocation recorded for one block, in order.
+ * @param {number} [threshold] - default `S2_HEAVY_THRESHOLD` (6).
+ * @returns {{count: number, heavy: boolean}} `count` is the NON-fallback tally only.
+ */
+export function evaluateS2Heavy(s2Calls, threshold = S2_HEAVY_THRESHOLD) {
+  const count = s2Calls.filter((call) => countsTowardS2Heavy(call.source)).length;
+  return { count, heavy: count > threshold };
+}