forgedock 1.7.0 → 1.8.0

package/scripts/check-spec-markers.sh

@@ -87,9 +87,11 @@ MARKER_REGISTRY="
   BATCH_MEMBERS
   BENCH_SCORECARD
   BLOCKED_ON_HUMAN_MERGE
+  BODY
   BUILDER
   CALIBRATION_CHECK
   CARD
+  CLASS
   CHECKPOINT
   CLAIM
   CLAIM_RELEASED
@@ -100,6 +102,7 @@ MARKER_REGISTRY="
   DECISION_RECORD
   DECOMPOSED
   DESIGN
+  DISPATCH
   DISPATCHER
   DOSSIER_UPDATED
   ENGINE_FALLBACK
@@ -187,28 +190,29 @@ while IFS= read -r file; do
     content="${markerline#*:}"
 
     # Skip allowlisted lines
-    if echo "$content" | grep -qF "$ALLOWLIST_TOKEN"; then
+    if [[ "$content" == *"$ALLOWLIST_TOKEN"* ]]; then
       continue
     fi
 
     # Skip markers that are inside code spans (backtick-quoted) — those are docs examples
     # Heuristic: if the FORGE:TYPE appears between backticks on the same line, skip it
     # We check for backtick on either side of the FORGE: marker
-    if echo "$content" | grep -qE "\`[^\`]*FORGE:[A-Z_]"; then
+    if [[ "$content" =~ \`[^\`]*FORGE:[A-Z_] ]]; then
       continue
     fi
 
     # Extract the full marker string after FORGE: — everything up to a space, -->, or end
     # This captures compound markers like REVIEW-AGENT:material-change
-    full_marker=$(echo "$content" | grep -oE 'FORGE:[A-Z][A-Z0-9_:-]*' | head -1 | sed 's/^FORGE://')
+    [[ "$content" =~ FORGE:([A-Z][A-Z0-9_:-]*) ]] || continue
+    full_marker="${BASH_REMATCH[1]}"
 
     [ -z "$full_marker" ] && continue
 
     # Extract PRIMARY type: part before the first - or : separator
-    primary_type=$(echo "$full_marker" | sed 's/[-:].*//')
+    primary_type="${full_marker%%[-:]*}"
 
     # Validate primary type against registry
-    if ! echo "$primary_type" | grep -qE "$REGISTRY_PATTERN"; then
+    if ! [[ "$primary_type" =~ $REGISTRY_PATTERN ]]; then
       echo "HIGH | $file:$lineno | unknown FORGE: marker 'FORGE:${full_marker}' (primary type '${primary_type}') — not in registry" >&2
       VIOLATIONS=$((VIOLATIONS + 1))
     fi
@@ -242,21 +246,27 @@ if [ -d "$WORKFLOWS_DIR" ]; then
       LINENO=$((LINENO + 1))
 
       # Skip allowlisted lines
-      if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then
+      if [[ "$line" == *"$ALLOWLIST_TOKEN"* ]]; then
         continue
       fi
 
       # Skip comment lines
-      if echo "$line" | grep -qE '^[[:space:]]*#'; then
+      if [[ "$line" =~ ^[[:space:]]*# ]]; then
         continue
       fi
 
       # Strip bash ${VAR} and $VAR patterns before checking for template placeholders
       # so that ELAPSED in "${ELAPSED}s" doesn't false-positive as {ELAPSED}
-      stripped=$(echo "$line" | sed 's/\${\([^}]*\)}/BASH_VAR/g; s/\$[A-Za-z_][A-Za-z0-9_]*/BASH_VAR/g')
-
-      if echo "$stripped" | grep -qE "$PLACEHOLDER_PATTERN"; then
-        placeholder=$(echo "$stripped" | grep -oE "$PLACEHOLDER_PATTERN" | head -1)
+      stripped="$line"
+      while [[ "$stripped" =~ \$\{[^}]*\} ]]; do
+        stripped="${stripped/"${BASH_REMATCH[0]}"/BASH_VAR}"
+      done
+      while [[ "$stripped" =~ \$[A-Za-z_][A-Za-z0-9_]* ]]; do
+        stripped="${stripped/"${BASH_REMATCH[0]}"/BASH_VAR}"
+      done
+
+      if [[ "$stripped" =~ $PLACEHOLDER_PATTERN ]]; then
+        placeholder="${BASH_REMATCH[0]}"
         echo "HIGH | $wf_file:$LINENO | unsubstituted placeholder '$placeholder' in workflow" >&2
         VIOLATIONS=$((VIOLATIONS + 1))
       fi

package/scripts/checkbox-sections.test.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# checkbox-sections.test.sh — Regression tests for the close-path classifier.
+#
+# Usage: bash scripts/checkbox-sections.test.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+extract_block() {
+  awk '/^FENCE_COUNT=/{printing=1} printing{print} /^SUBISSUE_ITEMS=/{exit}' "$1"
+}
+
+extract_classifier() {
+  awk '
+    /^CHECKBOX_SECTIONS=.*awk .$/ { printing=1; next }
+    printing && /^\047\)$/ { exit }
+    printing { print }
+  ' "$1"
+}
+
+CLOSE_BLOCK=$(extract_block "$ROOT/commands/work-on/close.md")
+INLINE_BLOCK=$(extract_block "$ROOT/commands/work-on.md")
+[[ "$CLOSE_BLOCK" == "$INLINE_BLOCK" ]] || {
+  printf 'FAIL: mirrored classifier blocks differ\n' >&2
+  exit 1
+}
+
+CLOSE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on/close.md")
+INLINE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on.md")
+[[ "$CLOSE_CLASSIFIER" == "$INLINE_CLASSIFIER" ]] || {
+  printf 'FAIL: mirrored classifier implementations differ\n' >&2
+  exit 1
+}
+
+if grep -q 'echo "\$BODY\|echo "\$BODY_STRIPPED' \
+  "$ROOT/commands/work-on/close.md" "$ROOT/commands/work-on.md"; then
+  printf 'FAIL: arbitrary issue bodies must be piped with printf, not echo\n' >&2
+  exit 1
+fi
+
+grep -Fq 'Keep the structural computation above and its consuming multi-phase guard' "$ROOT/commands/work-on.md" || {
+  printf 'FAIL: Phase 6A sync invariant must cover the consuming guard\n' >&2
+  exit 1
+}
+grep -Fq 'The guard is `CHECKBOX_SECTIONS >= 2 OR SUBISSUE_ITEMS > 0`' "$ROOT/commands/work-on.md" || {
+  printf 'FAIL: Phase 6A must document the Phase C1 guard\n' >&2
+  exit 1
+}
+grep -Fq 'if [ "${CHECKBOX_SECTIONS:-0}" -ge 2 ] || [ "${SUBISSUE_ITEMS:-0}" -gt 0 ]; then' "$ROOT/commands/work-on/close.md" || {
+  printf 'FAIL: Phase C1 multi-phase guard changed unexpectedly\n' >&2
+  exit 1
+}
+
+SETEXT_BODY=$'Phase One\n=========\n- [x] complete\n\nPhase Two\n---------\n- [ ] remaining'
+[[ "$(printf '%s\n' "$SETEXT_BODY" | awk "$CLOSE_CLASSIFIER")" == "2" ]] || {
+  printf 'FAIL: setext phases must count as two sections\n' >&2
+  exit 1
+}
+
+SINGLE_BODY=$'## Acceptance Criteria\n- [ ] complete this work'
+[[ "$(printf '%s\n' "$SINGLE_BODY" | awk "$CLOSE_CLASSIFIER")" == "1" ]] || {
+  printf 'FAIL: one checkbox-bearing section must remain single-phase\n' >&2
+  exit 1
+}
+
+printf 'PASS: mirrored classifier supports setext section boundaries\n'

package/scripts/extract-affected-files.sh

@@ -7,7 +7,7 @@
 #   extract-affected-files.sh <issue_number> "-R <owner/repo>"   (single pre-joined token also accepted)
 #
 # Output (stdout):
-#   Line 1:   PROVENANCE=affected-files-section | body-fallback | none | error
+#   Line 1:   PROVENANCE=contract-deliverables | affected-files-section | body-fallback | none | error
 #   Line 2+:  one extracted file path per line (zero lines when PROVENANCE=none or error)
 #
 # Exit codes:
@@ -16,12 +16,39 @@
 #       that files were found).
 #   2 — Usage error (missing issue number, malformed -R value).
 #
-# Extraction rules (forge#2436):
+# Extraction rules (forge#2436, extended forge#2848):
+#   0. Highest-confidence path — the issue's FORGE:CONTRACT comment (if one exists),
+#      scoped to ONLY its own "### Deliverables" section. A contract deliverables table
+#      states *intent to change* ("I will edit this file"), whereas an investigation's
+#      Affected Files list and especially a raw issue body routinely name files as
+#      *context* ("this interacts with X", "similar to the check in Y"). Preferring the
+#      contract is what stops a cohort of issues that merely cite the same file from
+#      being serialized against each other (forge#2848).
+#      -> PROVENANCE=contract-deliverables
+#
+#      TEMPORAL CAVEAT — do not over-claim this source: FORGE:CONTRACT is posted at
+#      *build* time (work-on/build.md Phase B2), which is AFTER /orchestrate Phase 3
+#      builds the DAG. On a cold first-pass plan no contract exists yet, so this path is
+#      inert by construction. It pays off only on the paths that re-extract later: wake /
+#      re-plan after compaction, mid-batch re-derivation (phase-4-execution.md's DONE-arm
+#      DROP handling), and IN_PROGRESS predecessors built in an earlier wave or session.
+#
+#      FALL-THROUGH RULE (load-bearing — see forge#2848 risk table): a contract that
+#      exists but whose Deliverables section yields ZERO paths MUST fall through to the
+#      INVESTIGATOR path below. A contract is an *upgrade* over the investigator source,
+#      never a replacement for it — blackholing to `none` here would fire Layer 4's
+#      conservative serialization for exactly the mid-batch issues this change exists to
+#      un-serialize, i.e. the bug being fixed, inverted. Note this is deliberately NOT
+#      the same shape as the INVESTIGATOR->body relationship in rule 2, which does NOT
+#      fall through on zero files (see rule 2's own note, forge#2382).
 #   1. Primary path — the issue's FORGE:INVESTIGATOR comment (if one exists), scoped to
 #      ONLY its own "### Affected Files" section. Capture stops at the next markdown
 #      heading of any level, so paths mentioned in "### Evidence", "### Root Cause",
 #      "### Related Issues", etc. are never collected.
 #      -> PROVENANCE=affected-files-section
+#      NOTE (forge#2382): unlike rule 0, an INVESTIGATOR comment that EXISTS but yields
+#      zero paths does NOT fall through to rule 2 — an investigation that scoped its own
+#      Affected Files section to nothing is a confirmed-empty result, not a missing one.
 #   2. Fallback path — used ONLY when no FORGE:INVESTIGATOR comment exists at all.
 #      Scoped to a deliverables-shaped heading in the raw issue body:
 #      "## Affected Files", "## Deliverables", or "### Files to change". Capture stops
@@ -126,6 +153,20 @@ fi
 # deeper sub-heading inside a deliverables section still closes capture
 # rather than leaking into unrelated prose.
 # --------------------------------------------------------------------------- #
+extract_contract_section() {
+  # forge#2848 — same sentinel shape as the two helpers below, targeting the
+  # FORGE:CONTRACT comment's "### Deliverables" table. The `/^### Deliverables/`
+  # heading and the awk sentinel are the ones already proven in-tree at
+  # commands/work-on/build.md:218 and :258; only the path-extraction step differs
+  # (this script uses grep -oE via extract_paths, never build.md's grep -oP —
+  # forge#2436 removed the PCRE dependency on purpose, see extract_paths below).
+  awk '
+    /^### Deliverables/ { p=1; next }
+    /^#/ { p=0 }
+    p { print }
+  ' <<< "$1"
+}
+
 extract_investigator_section() {
   awk '
     /^### Affected Files/ { p=1; next }
@@ -152,13 +193,49 @@ extract_paths() {
   grep -oE "$EXT_REGEX" <<< "$1" 2>/dev/null | tr -d '`' | sort -u || true
 }
 
-# --------------------------------------------------------------------------- #
-# Primary path: FORGE:INVESTIGATOR comment, scoped to its own Affected Files section
-# --------------------------------------------------------------------------- #
 PROVENANCE="none"
 FILES=""
 GH_CALL_FAILED=0
 
+# --------------------------------------------------------------------------- #
+# Highest-confidence path: FORGE:CONTRACT comment, scoped to its own Deliverables
+# section (forge#2848). Runs AHEAD of the INVESTIGATOR path because a deliverables
+# table states intent to change, while an Affected Files list may name files that
+# are merely relevant. See rule 0 in the header for the temporal caveat (a contract
+# only exists post-build, so this is inert on a cold first-pass plan).
+#
+# Uses the same `if ! VAR=$(cmd); then GH_CALL_FAILED=1; fi` idiom as the calls
+# below — never `|| true` — so a failed contract fetch stays distinguishable from
+# "no contract exists" and can still escalate to PROVENANCE=error if nothing else
+# recovers real data (forge#2504).
+# --------------------------------------------------------------------------- #
+if ! CONTRACT_BODY=$(gh api "repos/${REPO}/issues/${NUM}/comments" \
+  --jq '[.[] | select(.body | contains("FORGE:CONTRACT"))] | last | .body // ""' 2>/dev/null); then
+  GH_CALL_FAILED=1
+  echo "WARNING: gh api call failed while fetching comments for issue #$NUM (repo: $REPO) — cannot confirm whether a FORGE:CONTRACT comment exists; treating as inconclusive, not empty" >&2
+  CONTRACT_BODY=""
+fi
+
+if [[ -n "$CONTRACT_BODY" ]]; then
+  SCOPED=$(extract_contract_section "$CONTRACT_BODY")
+  FILES=$(extract_paths "$SCOPED")
+  if [[ -n "$FILES" ]]; then
+    PROVENANCE="contract-deliverables"
+  fi
+fi
+
+# --------------------------------------------------------------------------- #
+# Primary path: FORGE:INVESTIGATOR comment, scoped to its own Affected Files section
+#
+# Guarded on `-z "$FILES"` so the contract path above FALLS THROUGH when it yielded
+# zero paths (no contract, no Deliverables section, or a deliverables table naming no
+# recognized file extension). The guard wraps the whole INVESTIGATOR/body block from
+# the outside, leaving the INVESTIGATOR->body-fallback relationship inside it
+# byte-identical — that inner relationship deliberately does NOT fall through on zero
+# files (forge#2382), and this change must not alter it.
+# --------------------------------------------------------------------------- #
+if [[ -z "$FILES" ]]; then
+
 # NOTE: deliberately no `| tail -1` here — `gh api --jq`'s raw-string output
 # for a multi-line `.body` field embeds literal newlines, so isolating "the
 # last comment" by taking the last output LINE would instead truncate to
@@ -215,6 +292,9 @@ else
     fi
   fi
 fi
+fi  # end contract fall-through guard (forge#2848) — the INVESTIGATOR/body block
+    # above is intentionally left un-indented so it stays byte-identical to its
+    # pre-forge#2848 form; only the surrounding guard is new.
 
 # forge#2504: only escalate to "error" when neither path yielded real data AND
 # at least one gh call genuinely failed along the way. A failed primary call

package/scripts/extract-affected-files.test.sh

@@ -28,18 +28,38 @@ trap cleanup EXIT
 
 # --------------------------------------------------------------------------- #
 # Mock `gh` — intercepts:
-#   gh api repos/<repo>/issues/<num>/comments --jq '...'   -> cat $MOCK_GH_COMMENTS (if set+exists, else empty)
-#   gh issue view <num> -R <repo> --json body --jq '...'   -> cat $MOCK_GH_BODY (if set+exists, else empty)
+#   gh api .../comments --jq '...FORGE:CONTRACT...'      -> cat $MOCK_GH_CONTRACT (if set+exists, else empty)
+#   gh api .../comments --jq '...FORGE:INVESTIGATOR...'  -> cat $MOCK_GH_COMMENTS (if set+exists, else empty)
+#   gh issue view <num> -R <repo> --json body --jq '...'  -> cat $MOCK_GH_BODY (if set+exists, else empty)
 # Any other invocation is a test setup error.
 #
+# forge#2848: the two `gh api` call sites hit the same endpoint and differ only in
+# their --jq selector, so the mock dispatches on which FORGE marker the selector
+# names. This keeps the contract source and the investigator source independently
+# fixturable — required to assert the contract-beats-investigator ordering rule.
+#
 # forge#2504: MOCK_GH_COMMENTS_FAIL=1 / MOCK_GH_BODY_FAIL=1 force the respective
 # call site to simulate a genuine `gh` failure (non-zero exit, nothing on
 # stdout) instead of a "call succeeded, empty/no-match result" — this is the
 # distinction extract-affected-files.sh must now surface as PROVENANCE=error.
+# MOCK_GH_CONTRACT_FAIL=1 does the same for the contract fetch alone; note that
+# MOCK_GH_COMMENTS_FAIL=1 fails BOTH `gh api` call sites, which is the faithful
+# simulation of a real network/auth/rate-limit outage (a real outage does not
+# selectively spare one of two calls to the same endpoint).
 # --------------------------------------------------------------------------- #
 cat > "$TMP_BIN/gh" <<'MOCK'
 #!/usr/bin/env bash
 if [[ "$1" == "api" ]]; then
+  if [[ "$*" == *"FORGE:CONTRACT"* ]]; then
+    if [[ "${MOCK_GH_CONTRACT_FAIL:-}" == "1" || "${MOCK_GH_COMMENTS_FAIL:-}" == "1" ]]; then
+      echo "mock gh api: simulated failure (network error / rate limit)" >&2
+      exit 1
+    fi
+    if [[ -n "${MOCK_GH_CONTRACT:-}" && -f "${MOCK_GH_CONTRACT:-}" ]]; then
+      cat "$MOCK_GH_CONTRACT"
+    fi
+    exit 0
+  fi
   if [[ "${MOCK_GH_COMMENTS_FAIL:-}" == "1" ]]; then
     echo "mock gh api: simulated failure (network error / rate limit)" >&2
     exit 1
@@ -320,6 +340,138 @@ MOCK_GH_COMMENTS_FAIL=1 MOCK_GH_BODY="$BODY_SCOPED" assert_output \
   "forge#2504: primary gh api call fails but fallback succeeds with real files -> body-fallback, not error" \
   "body-fallback" "bin/engine.mjs,bin/engine/phases.mjs" 2506 -R test/repo
 
+# --------------------------------------------------------------------------- #
+# Scenario 12 (forge#2848): FORGE:CONTRACT comment present with a real
+# "### Deliverables" table -> PROVENANCE=contract-deliverables. Paths named in
+# the contract's OTHER sections ("### Proposed Approach", "### Out of Scope")
+# must be ignored — same heading-scoping guarantee the investigator path has.
+# --------------------------------------------------------------------------- #
+CONTRACT_FULL="$TMP_FIXTURES/contract_full.txt"
+cat > "$CONTRACT_FULL" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+**Task type**: Bug Fix
+
+### Proposed Approach
+
+Mirrors the approach already taken in `bin/approach-only-context.mjs`.
+
+### Deliverables
+
+| File | Change | Why |
+|------|--------|-----|
+| `scripts/real-target.sh` | rewrite the parser | the actual defect |
+| `bin/real-target.mjs` | update the caller | keeps the pair in sync |
+
+### Out of Scope
+
+Anything under `bin/out-of-scope-file.mjs`.
+EOF
+
+unset MOCK_GH_COMMENTS MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_FULL" assert_output \
+  "forge#2848: FORGE:CONTRACT ### Deliverables -> contract-deliverables, ignores Approach/Out-of-Scope paths" \
+  "contract-deliverables" "bin/real-target.mjs,scripts/real-target.sh" 2848 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 13 (forge#2848 ORDERING rule): both a FORGE:CONTRACT and a
+# FORGE:INVESTIGATOR comment exist, and they name DIFFERENT files. The contract
+# must win — a deliverables table states intent to change, while an Affected
+# Files list may name files that are merely relevant. This is the assertion that
+# pins the provenance precedence order; without it the two sources could silently
+# swap with no test failure.
+# --------------------------------------------------------------------------- #
+INV_DIFFERENT="$TMP_FIXTURES/inv_different.txt"
+cat > "$INV_DIFFERENT" <<'EOF'
+<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+### Affected Files
+
+1. `scripts/investigator-guess.sh` — suspected
+2. `bin/investigator-guess.mjs` — suspected
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_FULL" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 ordering: contract beats investigator when both exist and disagree" \
+  "contract-deliverables" "bin/real-target.mjs,scripts/real-target.sh" 2849 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 14 (forge#2848 FALL-THROUGH rule — load-bearing): a FORGE:CONTRACT
+# exists but yields ZERO paths. It must fall through to the INVESTIGATOR path,
+# NOT blackhole to PROVENANCE=none. Blackholing here would fire Layer 4's
+# conservative serialization for exactly the mid-batch issues this change exists
+# to un-serialize (the bug being fixed, inverted — see the forge#2848 risk table).
+# Two zero-yield shapes are covered: no "### Deliverables" heading at all, and a
+# Deliverables section that names no recognized file path.
+# --------------------------------------------------------------------------- #
+CONTRACT_NO_DELIV="$TMP_FIXTURES/contract_no_deliv.txt"
+cat > "$CONTRACT_NO_DELIV" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+### Proposed Approach
+
+Prose only, mentioning `bin/should-not-be-extracted.mjs` as context.
+
+### Out of Scope
+
+Everything else.
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_NO_DELIV" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 fall-through: contract with no ### Deliverables section -> falls through to affected-files-section" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2850 -R test/repo
+
+CONTRACT_EMPTY_DELIV="$TMP_FIXTURES/contract_empty_deliv.txt"
+cat > "$CONTRACT_EMPTY_DELIV" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+### Deliverables
+
+| File | Change | Why |
+|------|--------|-----|
+| (documentation-only, no code paths) | n/a | n/a |
+
+### Out of Scope
+
+Everything else.
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_EMPTY_DELIV" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 fall-through: contract Deliverables naming no recognized path -> falls through to affected-files-section" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2851 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 15 (forge#2848 x forge#2504): the CONTRACT fetch specifically fails
+# while every other source is legitimately empty. Must yield PROVENANCE=error,
+# not none — the new call site doubles the gh failure surface, so its own
+# GH_CALL_FAILED wiring needs its own assertion rather than riding on the
+# investigator call's coverage.
+# --------------------------------------------------------------------------- #
+unset MOCK_GH_CONTRACT MOCK_GH_COMMENTS MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT_FAIL=1 assert_output \
+  "forge#2848: contract gh api call fails, no other usable source -> PROVENANCE=error, not none" \
+  "error" "" 2852 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 16 (forge#2848 x forge#2504): the CONTRACT fetch fails but the
+# investigator path succeeds with real files. A gh failure must never suppress
+# or overwrite data actually recovered by a subsequent successful call — same
+# invariant Scenario 11 asserts for the primary/fallback pair.
+# --------------------------------------------------------------------------- #
+unset MOCK_GH_CONTRACT MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT_FAIL=1 MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848: contract fetch fails but investigator succeeds with real files -> affected-files-section, not error" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2853 -R test/repo
+
+unset MOCK_GH_CONTRACT_FAIL
+
 # --------------------------------------------------------------------------- #
 # Summary
 # --------------------------------------------------------------------------- #