forgedock 1.3.0 → 1.5.0

package/packages/protocol/src/validate.js

@@ -6,7 +6,7 @@
  * Checks:
  *   - Completion sentinel presence (§3.2) — for types that define one
  *   - Required field presence (§4.1 per-type field tables)
- *   - Required field enum values (Verdict, Confidence, Severity, Task Type)
+ *   - Required field enum values (Verdict, Confidence, Severity, Task Type, Re-gate outcome)
  *   - Inline-value non-empty (§3.4)
  *   - CARD inline-value decodability + sha8 integrity (§4.2 — see card.js)
  *   - Partial sentinel marking (§3.3) — generates a warning, not an error
@@ -129,5 +129,28 @@ export function validate(annotation) {
     }
   }
 
+  // REMEDIATION-specific enum validation (forge#2450): the Re-gate outcome field is
+  // optional at the required-field-presence layer (it is absent until
+  // commands/work-on/remediate.md's Phase M8 posts it), but when present its value
+  // must come from the single-sourced registry list — not a second hardcoded copy.
+  //
+  // Phase M8 posts this field as "**Re-gate outcome**: ${RE_GATE_OUTCOME} ${OUTCOME_DETAIL}"
+  // (see commands/work-on/remediate.md), so the parsed field value carries trailing free-text
+  // detail (e.g. "AUTO-LANDED to staging"), not just the bare outcome token. Only the leading
+  // token is the actual outcome — extract it the same way bin/engine/phases.mjs's own
+  // `/\*\*Re-gate outcome\*\*:\s*([A-Z-]+)/` regex does, so real production annotations with
+  // trailing detail text are not falsely rejected.
+  if (type === 'REMEDIATION') {
+    const reGateOutcome = fields['Re-gate outcome'];
+    if (reGateOutcome) {
+      const outcomeToken = reGateOutcome.match(/^([A-Z-]+)/)?.[1] ?? reGateOutcome;
+      if (!typeDef.reGateOutcomeValues.includes(outcomeToken)) {
+        errors.push(
+          `Invalid Re-gate outcome "${outcomeToken}" — must be one of: ${typeDef.reGateOutcomeValues.join(', ')}`,
+        );
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors, warnings };
 }

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

package/scripts/check-phase-registry-drift.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * CI drift check: bin/engine/phases.mjs's `PHASES` array (the authoritative
+ * engine phase table) must have exactly the same phase-id list, in the same
+ * order, as packages/protocol/src/phases.js's `PHASE_IDS` — the single-source
+ * registry both bin/engine/phases.mjs and bin/hooks/interactive-engine.mjs
+ * import their marker strings from (forge#2378).
+ *
+ * This does NOT re-validate the marker *strings* themselves — both consumer
+ * files import the registry directly, so a string-level mismatch between them
+ * is now structurally impossible (there is exactly one literal declaration of
+ * each marker, in packages/protocol/src/phases.js / types.js). What CAN still
+ * drift is the *phase-id list itself*: someone adds/removes/reorders a phase
+ * in bin/engine/phases.mjs's PHASES array without updating the registry's
+ * PHASE_IDS (or vice versa). This script catches that.
+ *
+ * Usage: node scripts/check-phase-registry-drift.mjs
+ * Exit codes: 0 = no drift, 1 = drift detected, 2 = usage/import error.
+ */
+
+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, "..");
+
+async function main() {
+  let registryModule;
+  let phasesModule;
+  try {
+    registryModule = await import(
+      pathToFileURL(path.join(REPO_ROOT, "packages/protocol/src/phases.js")).href
+    );
+  } catch (err) {
+    console.error(`ERROR: failed to import packages/protocol/src/phases.js: ${err.message}`);
+    process.exit(2);
+  }
+  try {
+    phasesModule = await import(
+      pathToFileURL(path.join(REPO_ROOT, "bin/engine/phases.mjs")).href
+    );
+  } catch (err) {
+    console.error(`ERROR: failed to import bin/engine/phases.mjs: ${err.message}`);
+    process.exit(2);
+  }
+
+  const registryIds = registryModule.PHASE_IDS;
+  const enginePhaseIds = (phasesModule.PHASES || []).map((p) => p.id);
+
+  if (!Array.isArray(registryIds)) {
+    console.error("ERROR: packages/protocol/src/phases.js did not export a PHASE_IDS array.");
+    process.exit(2);
+  }
+  if (!Array.isArray(enginePhaseIds) || enginePhaseIds.length === 0) {
+    console.error("ERROR: bin/engine/phases.mjs did not export a non-empty PHASES array.");
+    process.exit(2);
+  }
+
+  const drifted =
+    registryIds.length !== enginePhaseIds.length ||
+    registryIds.some((id, i) => id !== enginePhaseIds[i]);
+
+  if (drifted) {
+    console.error("ERROR: phase-id list drift detected between the registry and the engine.");
+    console.error(`  packages/protocol/src/phases.js PHASE_IDS: ${JSON.stringify(registryIds)}`);
+    console.error(`  bin/engine/phases.mjs PHASES ids:          ${JSON.stringify(enginePhaseIds)}`);
+    console.error("  Update packages/protocol/src/phases.js's PHASE_IDS to match bin/engine/phases.mjs's");
+    console.error("  PHASES array (or vice versa) so the two stay single-sourced. See forge#2378.");
+    process.exit(1);
+  }
+
+  // Verify every id in PHASE_IDS has a corresponding key in PHASE_MARKERS.
+  // The empty-marker check below iterates Object.entries(PHASE_MARKERS), which
+  // only visits keys that actually exist on the object — a phase id that is
+  // entirely absent from PHASE_MARKERS (as opposed to present-but-empty) never
+  // appears in that iteration, so it would pass silently here and only surface
+  // later as a runtime TypeError in bin/engine/phases.mjs (e.g.
+  // `PHASE_MARKERS.someId.completionMarker` on an undefined `someId` entry).
+  // Catch that gap explicitly before the empty-marker check below.
+  const phaseMarkers = registryModule.PHASE_MARKERS || {};
+  const missingKeys = registryIds.filter(
+    (id) => !Object.prototype.hasOwnProperty.call(phaseMarkers, id)
+  );
+  if (missingKeys.length > 0) {
+    console.error(
+      `ERROR: PHASE_MARKERS is missing an entry entirely for: ${missingKeys.join(", ")}`
+    );
+    console.error(
+      "  Add a corresponding key to packages/protocol/src/phases.js's PHASE_MARKERS for each id above."
+    );
+    process.exit(1);
+  }
+
+  // Also verify every registry marker entry that has a `completionMarker` or
+  // `completionLabel` field is a non-empty string — catches an accidental
+  // undefined/null slipping in (e.g. a typo'd RESERVED_TYPES key whose
+  // completionSentinel is null) which would otherwise fail silently at
+  // has(blob, undefined) → substring "undefined" never matches, masking a
+  // real bug as "phase never completes".
+  const emptyMarkers = [];
+  for (const [phaseId, entry] of Object.entries(phaseMarkers)) {
+    const marker = entry.completionMarker ?? entry.completionLabel;
+    if (typeof marker !== "string" || marker.length === 0) {
+      emptyMarkers.push(phaseId);
+    }
+  }
+  if (emptyMarkers.length > 0) {
+    console.error(
+      `ERROR: PHASE_MARKERS entries with no usable completionMarker/completionLabel: ${emptyMarkers.join(", ")}`
+    );
+    process.exit(1);
+  }
+
+  console.log("OK: phase-id list and marker registry are consistent (no drift detected).");
+  process.exit(0);
+}
+
+main();

package/scripts/check-spec-markers.sh

@@ -117,6 +117,8 @@ MARKER_REGISTRY="
   KNOWLEDGE_GIST
   LEARNED
   LEARNED_RULES
+  LEASE
+  LEASE_RELEASED
   LEDGER_INDEXED
   MEMORY_INDEX
   MEMORY_INDEXED
@@ -135,6 +137,7 @@ MARKER_REGISTRY="
   PUSH_BLOCKED_EMPTY_BRANCH
   PUSH_FAILED
   REMEDIATION
+  REREVIEW_SKIPPED
   REVIEW
   REVIEWER
   REVIEW_ROUTE