forgedock 1.3.0 → 1.4.0

package/packages/protocol/src/phases.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical FORGE pipeline phase table — single source of truth for phase ids
+ * (in dispatch order) and the exact marker/label strings that indicate each
+ * phase has committed.
+ *
+ * Consumers: `bin/engine/phases.mjs` (the authoritative engine gate) and
+ * `bin/hooks/interactive-engine.mjs` (the interactive-session SubagentStop
+ * hook) both import this module instead of hand-declaring their own copies
+ * of the marker strings. Before this module existed, the two files carried
+ * independent literal copies of the same strings and drifted out of sync at
+ * least twice (forge#1669 established the strict `:COMPLETE` gate for
+ * `context`/`architect`; forge#2375/PR#2395 then had to hand-patch the hook's
+ * copy back into agreement with the engine's). See forge#2378.
+ *
+ * `completionMarker` values are sourced from `RESERVED_TYPES[*].completionSentinel`
+ * wherever that reserved annotation type exists (INVESTIGATOR, CONTEXT,
+ * ARCHITECT, BUILDER) — so the reserved-annotation registry in `types.js` and
+ * this phase registry cannot drift apart for those four phases; there is
+ * exactly one literal declaration of each of those marker strings in the
+ * entire codebase, in `types.js`.
+ *
+ * `review` and `close` have no corresponding `RESERVED_TYPES` entry with a
+ * matching sentinel today (`REVIEWER` has no `completionSentinel` defined in
+ * spec §4.1; `close` is gated on a GitHub *label*, not a comment annotation),
+ * so those two are declared directly in this file — still single-sourced
+ * across the two consumers, just not additionally derived from `types.js`.
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES } from './types.js';
+
+/** Phase ids, in canonical dispatch order (mirrors `commands/work-on.md`'s
+ * "Universal Phase Dispatcher" table and `bin/engine/phases.mjs`'s `PHASES`
+ * array).
+ *
+ * `decompose` and `remediate` (forge#2379) are branch phases, not part of the
+ * six-phase linear happy path — `decompose` is reached only when `investigate`
+ * signals `DECOMPOSE:YES`, and `remediate` only when `review` escalates to
+ * `needs-human`. They are still declared here, in the exact same array
+ * position `bin/engine/phases.mjs`'s `PHASES` array declares them, because
+ * `scripts/check-phase-registry-drift.mjs` requires the two lists to match
+ * index-for-index — see that file's own doc comment. */
+export const PHASE_IDS = ['investigate', 'decompose', 'context', 'architect', 'build', 'review', 'remediate', 'close'];
+
+/**
+ * @typedef {Object} PhaseMarkerEntry
+ * @property {string} [completionMarker] - marker/sentinel string (or label, for `close`)
+ *   whose presence means this phase has committed.
+ * @property {string} [invalidMarker] - (investigate only) marks the issue INVALID.
+ * @property {string} [decomposedMarker] - (investigate only) marks the issue DECOMPOSED.
+ * @property {string} [partialMarker] - sentinel for an interrupted/partial annotation.
+ * @property {string} [presenceMarker] - bare annotation-opener substring, used only by
+ *   phases whose completion is non-critical (see `context` below) — presence alone
+ *   (without `:COMPLETE`) is enough to report a soft/visible skip rather than a hard fail.
+ * @property {string} [completionLabel] - a GitHub issue *label* (not a comment marker)
+ *   whose presence means this phase has committed. Only `close` uses this form.
+ */
+
+/** @type {Object.<string, PhaseMarkerEntry>} */
+export const PHASE_MARKERS = {
+  investigate: {
+    completionMarker: RESERVED_TYPES.INVESTIGATOR.completionSentinel, // 'INVESTIGATION:COMPLETE'
+    invalidMarker: 'INVESTIGATION:INVALID',
+    decomposedMarker: 'DECOMPOSE:YES',
+  },
+  // forge#2379: `decompose` actually runs work-on/decompose (sub-issue
+  // fan-out) once `investigate` hands off on `DECOMPOSE:YES` — see
+  // bin/engine/phases.mjs's `decompose` phase entry for the handoff mechanics.
+  decompose: {
+    completionMarker: RESERVED_TYPES.DECOMPOSED.completionSentinel, // 'FORGE:DECOMPOSED:COMPLETE'
+  },
+  context: {
+    completionMarker: RESERVED_TYPES.CONTEXT.completionSentinel, // 'FORGE:CONTEXT:COMPLETE'
+    partialMarker: RESERVED_TYPES.CONTEXT.partialSentinel, // 'FORGE:CONTEXT:PARTIAL'
+    // Bare presence marker: context is documented as non-critical (spec §7) — a
+    // missing completion marker is a visible skip, not a hard fail. Only
+    // bin/engine/phases.mjs's `context.detectOutcome` uses this bare form;
+    // `context.reconcile` (and everything in interactive-engine.mjs) uses the
+    // strict `completionMarker` above. Do not collapse these two fields.
+    presenceMarker: `FORGE:${RESERVED_TYPES.CONTEXT.type}`, // 'FORGE:CONTEXT'
+  },
+  architect: {
+    completionMarker: RESERVED_TYPES.ARCHITECT.completionSentinel, // 'FORGE:ARCHITECT:COMPLETE'
+    partialMarker: RESERVED_TYPES.ARCHITECT.partialSentinel, // 'FORGE:ARCHITECT:PARTIAL'
+  },
+  build: {
+    completionMarker: RESERVED_TYPES.BUILDER.completionSentinel, // 'FORGE:BUILDER:COMPLETE'
+  },
+  review: {
+    // No RESERVED_TYPES entry defines this sentinel (REVIEWER has no
+    // completionSentinel in spec §4.1) — declared directly here.
+    completionMarker: 'FORGE:REVIEWER:MERGED',
+  },
+  // forge#2379: `remediate` re-drives a needs-human PR (commands/work-on/remediate.md).
+  // Posted to BOTH the PR and the linked issue (Phase M8) — bin/engine/phases.mjs's
+  // `remediate` phase reads it off the issue, consistent with every other phase here.
+  remediate: {
+    completionMarker: RESERVED_TYPES.REMEDIATION.completionSentinel, // 'FORGE:REMEDIATION:COMPLETE'
+  },
+  close: {
+    // A GitHub label, not a comment marker — see `completionLabel` above.
+    completionLabel: 'workflow:merged',
+  },
+};

package/packages/protocol/src/types.js

@@ -86,6 +86,23 @@ export const RESERVED_TYPES = {
     requiredFields: ['Verdict'],
     verdictValues: ['APPROVED', 'CHANGES_REQUESTED', 'COMMENTED'],
   },
+  /**
+   * REMEDIATION — paper trail for a needs-human PR re-driven by
+   * commands/work-on/remediate.md. Posted to BOTH the PR and the linked
+   * issue (Phase M8) once the re-gate outcome (AUTO-LANDED /
+   * HELD-AWAITING-MERGE / RE-ESCALATED / UNFIXABLE) is known. Added in
+   * forge#2379 to single-source the completion sentinel that
+   * bin/engine/phases.mjs's `remediate` phase gates on. <!-- Added: forge#2379 -->
+   */
+  REMEDIATION: {
+    type: 'REMEDIATION',
+    category: Category.LIFECYCLE,
+    completionSentinel: 'FORGE:REMEDIATION:COMPLETE',
+    partialSentinel: null,
+    inlineValue: false,
+    requiredFields: [],
+    reGateOutcomeValues: ['AUTO-LANDED', 'HELD-AWAITING-MERGE', 'RE-ESCALATED', 'UNFIXABLE'],
+  },
   TRAJECTORY: {
     type: 'TRAJECTORY',
     category: Category.LIFECYCLE,

package/scripts/check-admission-parity.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * CI parity check: bin/engine/admission.mjs's `CASCADE_PRESETS` table is the
+ * typed, unit-tested reference implementation of the cascade admission
+ * policy (forge#2234). The logic actually EXECUTED at runtime is a
+ * hand-written bash/yq mirror in commands/orchestrate/phase-4-execution.md's
+ * Step 4A.pre `case "$CASCADE_POLICY_NAME" in ... esac` block — the two are
+ * kept in sync by hand, with no automated check catching divergence
+ * (forge#2340). This script closes that gap: it imports the real
+ * `CASCADE_PRESETS` table and diffs it against the values parsed out of the
+ * bash mirror, failing non-zero on any mismatch.
+ *
+ * Usage: node scripts/check-admission-parity.mjs
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..");
+const ADMISSION_MJS_PATH = path.join(REPO_ROOT, "bin/engine/admission.mjs");
+const SPEC_PATH = path.join(REPO_ROOT, "commands/orchestrate/phase-4-execution.md");
+
+/**
+ * Parse a single bash literal captured from the mirror's case arm into the
+ * same JS types `CASCADE_PRESETS` uses (number | "unlimited" | boolean).
+ * @param {string} raw
+ */
+function parseBashValue(raw) {
+  const trimmed = raw.trim().replace(/^"(.*)"$/, "$1");
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "unlimited") return "unlimited";
+  const n = Number(trimmed);
+  return Number.isFinite(n) && trimmed !== "" ? n : trimmed;
+}
+
+/**
+ * Extract each `PRESET_*` assignment from a single case-arm body.
+ * @param {string} body - text between `{name})` and the arm's `;;`
+ */
+function parseArmBody(body) {
+  const get = (key) => {
+    const m = body.match(new RegExp(`${key}=("?[^;"]*"?)`));
+    return m ? parseBashValue(m[1]) : undefined;
+  };
+  return {
+    maxGeneration: get("PRESET_MAX_GEN"),
+    tokenBudget: get("PRESET_TOKEN_BUDGET"),
+    deferOnBatchGated: get("PRESET_DEFER_GATED"),
+    keywordHeuristic: get("PRESET_KEYWORD"),
+    p3SameFileDefer: get("PRESET_P3_SAME_FILE"),
+  };
+}
+
+/**
+ * Isolate the `case "$CASCADE_POLICY_NAME" in ... esac` block and return a
+ * map of arm-name -> resolved preset object. The wildcard `*` fallback arm
+ * is excluded (it re-declares "balanced", not a distinct preset name).
+ */
+function extractBashMirrorPresets(specText) {
+  const caseMatch = specText.match(/case "\$CASCADE_POLICY_NAME" in([\s\S]*?)\nesac/);
+  if (!caseMatch) {
+    return null;
+  }
+  const caseBlock = caseMatch[1];
+
+  const armRe = /\n\s*([a-zA-Z0-9_*]+)\)([\s\S]*?);;/g;
+  const presets = {};
+  let m;
+  while ((m = armRe.exec(caseBlock))) {
+    const [, name, body] = m;
+    if (name === "*") continue; // wildcard fallback arm — not a named preset
+    presets[name] = parseArmBody(body);
+  }
+  return presets;
+}
+
+async function main() {
+  let admissionModule;
+  try {
+    // pathToFileURL is required for cross-platform dynamic import() of an absolute
+    // path — a bare Windows path like "C:\..." is not a valid ESM specifier and
+    // throws ERR_UNSUPPORTED_ESM_URL_SCHEME ("Only URLs with a scheme in: file,
+    // data, and node are supported"). POSIX absolute paths import fine either way,
+    // but file:// URLs work identically on both, so always convert.
+    admissionModule = await import(pathToFileURL(ADMISSION_MJS_PATH));
+  } catch (err) {
+    console.error(`ERROR: failed to import ${ADMISSION_MJS_PATH}: ${err.message}`);
+    process.exit(1);
+  }
+  const { CASCADE_PRESETS } = admissionModule;
+  if (!CASCADE_PRESETS) {
+    console.error(`ERROR: ${ADMISSION_MJS_PATH} does not export CASCADE_PRESETS — has it been renamed?`);
+    process.exit(1);
+  }
+
+  let specText;
+  try {
+    specText = readFileSync(SPEC_PATH, "utf8");
+  } catch (err) {
+    console.error(`ERROR: failed to read ${SPEC_PATH}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const bashPresets = extractBashMirrorPresets(specText);
+  if (!bashPresets) {
+    console.error(
+      `ERROR: could not locate the case "$CASCADE_POLICY_NAME" in ... esac bash mirror block in ${SPEC_PATH}.`,
+    );
+    console.error(
+      "       (parity check has nothing to compare admission.mjs against — has the mirror been renamed or restructured?)",
+    );
+    process.exit(1);
+  }
+
+  let failed = false;
+  const mjsNames = Object.keys(CASCADE_PRESETS);
+  const bashNames = Object.keys(bashPresets);
+
+  for (const name of mjsNames) {
+    if (!(name in bashPresets)) {
+      console.error(
+        `MISMATCH: preset "${name}" exists in admission.mjs CASCADE_PRESETS but has no matching bash case arm in ${SPEC_PATH}`,
+      );
+      failed = true;
+      continue;
+    }
+    const mjsPreset = CASCADE_PRESETS[name];
+    const bashPreset = bashPresets[name];
+    for (const key of Object.keys(mjsPreset)) {
+      if (mjsPreset[key] !== bashPreset[key]) {
+        console.error(
+          `MISMATCH: preset "${name}".${key} — admission.mjs=${JSON.stringify(mjsPreset[key])} bash-mirror=${JSON.stringify(bashPreset[key])}`,
+        );
+        failed = true;
+      }
+    }
+  }
+
+  for (const name of bashNames) {
+    if (!(name in CASCADE_PRESETS)) {
+      console.error(
+        `MISMATCH: bash case arm "${name}" in ${SPEC_PATH} has no matching preset in admission.mjs CASCADE_PRESETS`,
+      );
+      failed = true;
+    }
+  }
+
+  if (failed) {
+    console.error("");
+    console.error(
+      "admission.mjs CASCADE_PRESETS and the phase-4-execution.md bash mirror have drifted out of sync.",
+    );
+    console.error(
+      "Update both together — see the admission.mjs module docstring and phase-4-execution.md Step 4A.pre ('Cascade admission policy resolution').",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `OK: admission.mjs CASCADE_PRESETS matches the phase-4-execution.md bash mirror for: ${mjsNames.join(", ")}`,
+  );
+}
+
+main();

package/scripts/check-command-side-effects.sh

@@ -14,11 +14,17 @@
 #     Gists created by the pipeline MUST be secret — --public exposes private repo
 #     titles, root causes, and file paths to the world. (Ref: forge#1587)
 #
-#   Class B — Side-effect verbs in sections with no DRY_RUN/governor guard (diff-aware):
+#   Class B — Side-effect verbs in code blocks with no DRY_RUN/governor guard (diff-aware):
 #     When added lines introduce a side-effect verb (gh issue create, gh pr merge,
 #     git push, gh issue edit|comment, --auto-merge, --add/remove-label) inside a
-#     code block in a section that has no guard expression (DRY_RUN, GOVERNOR,
-#     --dry-run) anywhere in that section's code blocks, the change is flagged.
+#     code block that has no guard expression (DRY_RUN, GOVERNOR, --dry-run)
+#     anywhere in THAT SAME code block, the change is flagged. Guard/side-effect
+#     correlation is scoped to the individual fenced code block, not the whole
+#     section — a guard mentioned in an unrelated code block elsewhere in the
+#     same section (before or after the flagged verb) does not silence the
+#     finding. (Ref: forge#2289 — a decoy guard anywhere in the section, in any
+#     code block, previously silenced detection of an actually-unguarded side
+#     effect in a different block of that same section.)
 #     Operates on the diff (GITHUB_BASE_SHA or HEAD^) to avoid flagging legacy corpus.
 #     (Ref: forge#1609 — signal-planner.md DRY_RUN guard placed after the create it guards)
 #
@@ -99,45 +105,99 @@ class_a_scan() {
   local HAS_GIST=0
   local BLOCK_LINES=""
   local BLOCK_START=0
-  local LINENO=0
-  local line PUBLIC_LINENO ACTUAL_LINE
+  local LN=0
+  local line PUBLIC_LN ACTUAL_LINE IS_FENCE IS_BARE
+
+  # flush_a_block — evaluate the currently-accumulated block's HAS_GIST/
+  # BLOCK_LINES state for a 'gh gist create/edit --public' violation, then
+  # reset it. Defined inside class_a_scan (not at file scope) so it shares
+  # this invocation's `local` variables via bash's dynamic scoping — the same
+  # mechanism Class B's flush_block() relies on for its own loop-local state.
+  # Called from two sites: (1) the existing fence-close path below, when a
+  # bare fence brings IN_CB back to 0, and (2) once more, defensively, after
+  # the read loop ends — covering a file that ends with an unterminated
+  # fence (IN_CB still > 0 at EOF), which previously discarded any
+  # accumulated violation silently. (forge#2289 added the equivalent
+  # end-of-file flush for Class B only; this closes the same gap in Class A.)
+  flush_a_block() {
+    if [ "$HAS_GIST" -eq 1 ] && echo "$BLOCK_LINES" | grep -qE '^[[:space:]]*--public([[:space:]]|$)'; then
+      # Find the line number of --public within the block
+      PUBLIC_LN=$(echo "$BLOCK_LINES" | grep -n '^[[:space:]]*--public' | head -1 | cut -d: -f1)
+      ACTUAL_LINE=$((BLOCK_START + PUBLIC_LN))
+      if ! echo "$BLOCK_LINES" | grep -qF "$ALLOWLIST_TOKEN"; then
+        echo "HIGH | $file | line ~$ACTUAL_LINE | Class A: 'gh gist create/edit --public' in code block — gists MUST be secret (omit --public); --public exposes private repo data. (forge#1587)" >&2
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    fi
+    HAS_GIST=0
+    BLOCK_LINES=""
+  }
 
   while IFS= read -r line; do
-    LINENO=$((LINENO + 1))
+    LN=$((LN + 1))
+
+    # Fence detection is anchored to line-start (ignoring leading whitespace).
+    # IN_CB is a true nesting-DEPTH counter, not a 0/1 flag: a fence line
+    # carrying an info string (e.g. a nested ```bash) while already inside a
+    # block opens one more nesting level (increment); a bare fence (nothing
+    # after the backticks but optional trailing whitespace) closes exactly
+    # one level (decrement). The accumulated block is only evaluated once
+    # depth returns to 0 — i.e. once the OUTERMOST fence has actually closed,
+    # not merely an inner one. A binary flag cannot distinguish "still inside
+    # the outer fence, past an inner fence's close" from "outside all
+    # fences"; depth tracking can. (forge#2210 fixed anchoring/info-string-is-
+    # content; forge#2288 adds true depth so 2+ nesting levels close correctly.)
+    IS_FENCE=0
+    IS_BARE=0
+    if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+      IS_FENCE=1
+      if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+        IS_BARE=1
+      fi
+    fi
 
-    if echo "$line" | grep -qF "$FENCE"; then
-      if [ "$IN_CB" -eq 0 ]; then
+    if [ "$IN_CB" -eq 0 ]; then
+      if [ "$IS_FENCE" -eq 1 ]; then
         IN_CB=1
         HAS_GIST=0
         BLOCK_LINES=""
-        BLOCK_START=$LINENO
-      else
-        # End of code block — check if it had both gh gist and --public
-        if [ "$HAS_GIST" -eq 1 ] && echo "$BLOCK_LINES" | grep -qE '^[[:space:]]*--public([[:space:]]|$)'; then
-          # Find the line number of --public within the block
-          PUBLIC_LINENO=$(echo "$BLOCK_LINES" | grep -n '^[[:space:]]*--public' | head -1 | cut -d: -f1)
-          ACTUAL_LINE=$((BLOCK_START + PUBLIC_LINENO))
-          if ! echo "$BLOCK_LINES" | grep -qF "$ALLOWLIST_TOKEN"; then
-            echo "HIGH | $file | line ~$ACTUAL_LINE | Class A: 'gh gist create/edit --public' in code block — gists MUST be secret (omit --public); --public exposes private repo data. (forge#1587)" >&2
-            VIOLATIONS=$((VIOLATIONS + 1))
-          fi
-        fi
-        IN_CB=0
-        HAS_GIST=0
-        BLOCK_LINES=""
+        BLOCK_START=$LN
       fi
       continue
     fi
 
-    if [ "$IN_CB" -eq 1 ]; then
+    # IN_CB >= 1 — inside a block, possibly nested.
+    if [ "$IS_FENCE" -eq 1 ]; then
+      if [ "$IS_BARE" -eq 1 ]; then
+        IN_CB=$((IN_CB - 1))
+      else
+        IN_CB=$((IN_CB + 1))
+      fi
+      if [ "$IN_CB" -eq 0 ]; then
+        # Fully closed (outermost fence) — evaluate the accumulated block now.
+        flush_a_block
+        continue
+      fi
+      # Still inside (nested transition) — the fence line itself is block content.
       BLOCK_LINES="${BLOCK_LINES}${line}
 "
-      # Check if this line has gh gist create/edit (even with line continuation \)
-      if echo "$line" | grep -qE 'gh[[:space:]]+gist[[:space:]]+(create|edit)'; then
-        HAS_GIST=1
-      fi
+      continue
+    fi
+
+    # Regular content line while inside (at any depth).
+    BLOCK_LINES="${BLOCK_LINES}${line}
+"
+    # Check if this line has gh gist create/edit (even with line continuation \)
+    if echo "$line" | grep -qE 'gh[[:space:]]+gist[[:space:]]+(create|edit)'; then
+      HAS_GIST=1
     fi
   done < "$file"
+
+  # Defensive final flush — evaluates any block state left accumulated if the
+  # file ended with an unterminated fence (IN_CB never returned to 0). A
+  # no-op if the last block already closed and was flushed above. Mirrors
+  # Class B's identical end-of-file `flush_block` call. (forge#2305)
+  flush_a_block
 }
 
 while IFS= read -r file; do
@@ -185,64 +245,119 @@ else
         continue
       fi
 
-      # Parse the full file to map sections → (has_guard, has_side_effect_in_added_lines)
+      # Parse the full file to map code blocks → (has_guard, has_side_effect_in_added_lines).
+      # SECTION is tracked only as a human-readable label for the violation message —
+      # it plays NO role in guard/side-effect correlation. Correlation is scoped to
+      # the individual fenced code block (BLOCK_* state), reset on every block open
+      # and evaluated on every block close, so a guard mentioned in a different code
+      # block — even one earlier or later in the very same section — cannot silence
+      # an unguarded side effect in another block. (forge#2289)
       IN_CB=0
       SECTION="(top)"
-      SECTION_HAS_GUARD=0
-      SECTION_HAS_ADDED_SE=0
-      SECTION_SE_LINE=0
-      SECTION_SE_VERB=""
-      LINENO=0
-
-      flush_and_reset() {
-        local new_heading="$1"
-        if [ "$SECTION_HAS_ADDED_SE" -eq 1 ] && [ "$SECTION_HAS_GUARD" -eq 0 ]; then
-          echo "HIGH | $file | line $SECTION_SE_LINE | Class B: side-effect '$SECTION_SE_VERB' added to section '$SECTION' which has no DRY_RUN/governor guard — add guard before this line or wrap in DRY_RUN check" >&2
+      BLOCK_HAS_GUARD=0
+      BLOCK_HAS_ADDED_SE=0
+      BLOCK_SE_LINE=0
+      BLOCK_SE_VERB=""
+      LN=0
+
+      flush_block() {
+        # Evaluate and reset the current code block's guard/side-effect state.
+        # Called whenever a fenced code block's outermost fence closes (depth
+        # returns to 0), and once more, defensively, at end-of-file to cover a
+        # malformed/unterminated block (mirrors the pre-forge#2289 behavior of
+        # unconditionally evaluating accumulated state before resetting).
+        if [ "$BLOCK_HAS_ADDED_SE" -eq 1 ] && [ "$BLOCK_HAS_GUARD" -eq 0 ]; then
+          echo "HIGH | $file | line $BLOCK_SE_LINE | Class B: side-effect '$BLOCK_SE_VERB' added in section '$SECTION' with no DRY_RUN/governor guard in the same code block — add a guard inside this code block or wrap the effect in a DRY_RUN check" >&2
           VIOLATIONS=$((VIOLATIONS + 1))
         fi
-        SECTION="$new_heading"
-        SECTION_HAS_GUARD=0
-        SECTION_HAS_ADDED_SE=0
-        SECTION_SE_LINE=0
-        SECTION_SE_VERB=""
-        IN_CB=0
+        BLOCK_HAS_GUARD=0
+        BLOCK_HAS_ADDED_SE=0
+        BLOCK_SE_LINE=0
+        BLOCK_SE_VERB=""
       }
 
       while IFS= read -r line; do
-        LINENO=$((LINENO + 1))
+        LN=$((LN + 1))
+
+        # Code block fence — checked BEFORE the heading test so IN_CB reflects
+        # this line's actual state. IN_CB is a true nesting-DEPTH counter, not
+        # a 0/1 flag: a fence line carrying an info string (e.g. nested
+        # ```bash) encountered while already inside a block opens one more
+        # nesting level (increment); a bare fence (nothing after the
+        # backticks) closes exactly one level (decrement). Heading detection
+        # below only fires once depth returns to 0 — i.e. once we are outside
+        # ALL fences, not merely an inner one. A binary flag cannot
+        # distinguish "still inside the outer fence, past an inner fence's
+        # close" from "outside all fences"; this is exactly the gap that let
+        # embedded `## Step N` headers inside one continuous outer code block
+        # (e.g. commands/review-pr-agents/spec-cli.md) be misdetected as real
+        # section boundaries. (forge#2210 fixed anchoring/info-string-is-
+        # content for a single nesting level; forge#2288 adds true depth so
+        # 2+ nesting levels close correctly.)
+        IS_FENCE=0
+        IS_BARE=0
+        if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+          IS_FENCE=1
+          if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+            IS_BARE=1
+          fi
+        fi
+
+        if [ "$IN_CB" -eq 0 ]; then
+          if [ "$IS_FENCE" -eq 1 ]; then
+            IN_CB=1
+            continue
+          fi
 
-        # Section heading reset
-        if echo "$line" | grep -qE '^#{1,4}[[:space:]]+'; then
-          heading=$(echo "$line" | sed 's/^#*[[:space:]]*//' | sed 's/[[:space:]]*$//')
-          flush_and_reset "$heading"
+          # Section heading — label-only update (forge#2210). This no longer
+          # flushes guard/side-effect state: that state is now block-scoped
+          # (forge#2289) and is always already at rest here, since this branch
+          # is only reached when IN_CB is 0 — i.e. any block that was open has
+          # already been closed and flushed at its own fence-close below.
+          if echo "$line" | grep -qE '^#{1,6}[[:space:]]+'; then
+            heading=$(echo "$line" | sed 's/^#*[[:space:]]*//' | sed 's/[[:space:]]*$//')
+            SECTION="$heading"
+            continue
+          fi
           continue
         fi
 
-        # Code block fence
-        if echo "$line" | grep -qF "$FENCE"; then
-          [ "$IN_CB" -eq 0 ] && IN_CB=1 || IN_CB=0
+        # IN_CB >= 1 — inside a block, possibly nested.
+        if [ "$IS_FENCE" -eq 1 ]; then
+          if [ "$IS_BARE" -eq 1 ]; then
+            IN_CB=$((IN_CB - 1))
+          else
+            IN_CB=$((IN_CB + 1))
+          fi
+          if [ "$IN_CB" -eq 0 ]; then
+            # Outermost fence just closed — evaluate this block's guard/SE
+            # correlation now, before starting the next block. (forge#2289)
+            flush_block
+          fi
           continue
         fi
 
-        if [ "$IN_CB" -eq 1 ]; then
-          if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then continue; fi
+        # Content line while inside (at any depth).
+        if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then continue; fi
 
-          # Check for guard
-          echo "$line" | grep -qE "$GUARD_PATTERN" && SECTION_HAS_GUARD=1
+        # Check for guard — scoped to THIS code block only (forge#2289)
+        echo "$line" | grep -qE "$GUARD_PATTERN" && BLOCK_HAS_GUARD=1
 
-          # Check if this line is in the diff's added lines AND has a side-effect verb
-          if [ "$SECTION_HAS_ADDED_SE" -eq 0 ] && echo "$line" | grep -qE "$SIDE_EFFECT_PATTERN"; then
-            # Is this specific line in the added content?
-            if echo "$ADDED_CONTENT" | grep -qF "${line:0:80}" 2>/dev/null; then
-              SECTION_HAS_ADDED_SE=1
-              SECTION_SE_LINE=$LINENO
-              SECTION_SE_VERB=$(echo "$line" | grep -oE "$SIDE_EFFECT_PATTERN" | head -1 || echo "side-effect")
-            fi
+        # Check if this line is in the diff's added lines AND has a side-effect verb
+        if [ "$BLOCK_HAS_ADDED_SE" -eq 0 ] && echo "$line" | grep -qE "$SIDE_EFFECT_PATTERN"; then
+          # Is this specific line in the added content?
+          if echo "$ADDED_CONTENT" | grep -qF "${line:0:80}" 2>/dev/null; then
+            BLOCK_HAS_ADDED_SE=1
+            BLOCK_SE_LINE=$LN
+            BLOCK_SE_VERB=$(echo "$line" | grep -oE "$SIDE_EFFECT_PATTERN" | head -1 || echo "side-effect")
           fi
         fi
       done < "$file"
 
-      flush_and_reset "(end-of-file)"
+      # Defensive final flush — evaluates any block state left accumulated if
+      # the file ended with an unterminated fence (malformed input); a no-op
+      # if the last block already closed and was flushed above.
+      flush_block
 
     done <<< "$CHANGED_SPECS"
   fi