forge-orkes 0.70.0 → 0.72.2

package/template/.forge/checks/forge-roadmap-check.sh

@@ -20,12 +20,18 @@
 #   exit: 0 = ok=clean; 1 = one or more findings; 2 = bad invocation (missing/unreadable file)
 #
 # Required fields (confirmed against the live file — zero false positives today):
-#   milestone entry: id, name, phases (non-empty)
+#   milestone entry: id, name, phases (non-empty — an empty list, `phases: []` or a
+#   block-style key with no items, raises missing-field:milestone:<id>:phases)
 #   phase entry:     id, name, goal, requirements, dependencies, success_criteria,
 #                    estimated_hours, status
 #   milestone_dir is DELIBERATELY not required — 17/65 live phase entries predate
 #   the nested-layout convention. Validated only when present (bad-milestone-dir).
 #
+# A milestone's phases: list is parsed in all three shapes YAML allows here:
+# one-line flow ([1, 2]), wrapped flow ([1,\n  2]), and block style (- 1 items).
+# Trailing "# comment" text on id/milestone_dir/phases lines is stripped before
+# capture (mirrors forge-check-lint.sh strip_comment).
+#
 # Pure POSIX sh + awk. No git-repo dependency (reads the file directly, unlike the
 # diff-scoped forge-hold-check.sh/forge-check-lint.sh). Collects every finding in
 # one pass before deciding exit code — a single run surfaces everything wrong.
@@ -51,6 +57,10 @@ function unquote(s) {
   gsub(/"/, "", s)
   return s
 }
+function strip_comment(s) {
+  sub(/[ \t]#.*$/, "", s)
+  return s
+}
 function bare_num(s,   n) {
   n = unquote(trim(s))
   if (n ~ /^m-/) n = substr(n, 3)
@@ -70,6 +80,7 @@ function finish_entry() {
     ph_mdir[ph_count] = cur_mdir
   }
   entry_open = 0
+  ph_collect = 0
   cur_id = ""; cur_fields = ""; cur_mdir = ""; cur_phaselist = ""
 }
 
@@ -107,13 +118,14 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   entry_type = (block == "milestones" ? "milestone" : "phase")
   val = $0
   sub(/^    - id:[ \t]*/, "", val)
-  cur_id = unquote(trim(val))
+  cur_id = unquote(trim(strip_comment(val)))
   cur_fields = " id "
   next
 }
 
 # 6-space field line inside an open entry
 (block == "milestones" || block == "phases") && entry_open && $0 ~ /^      [A-Za-z_]+:/ {
+  ph_collect = 0
   line = $0
   sub(/^      /, "", line)
   match(line, /^[A-Za-z_]+/)
@@ -122,17 +134,45 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   if (field == "milestone_dir") {
     val = line
     sub(/^milestone_dir:[ \t]*/, "", val)
-    cur_mdir = unquote(trim(val))
+    cur_mdir = unquote(trim(strip_comment(val)))
   }
   if (field == "phases" && entry_type == "milestone") {
-    rest = line
+    rest = strip_comment(line)
+    sub(/^phases:[ \t]*/, "", rest)
     if (match(rest, /\[[^]]*\]/)) {
       cur_phaselist = substr(rest, RSTART + 1, RLENGTH - 2)
+    } else if (rest ~ /^\[/) {
+      cur_phaselist = substr(rest, 2)
+      ph_collect = 1
+    } else if (rest == "") {
+      ph_collect = 2
     }
   }
   next
 }
 
+# wrapped flow list continuation: collect until the ] that closes phases: [...
+# (a new 6-space field line ends collection via the rule above — failsafe for
+# a bracket that never closes)
+block == "milestones" && entry_open && ph_collect == 1 && $0 ~ /^      / {
+  line = strip_comment($0)
+  if (match(line, /\]/)) {
+    cur_phaselist = cur_phaselist " " substr(line, 1, RSTART - 1)
+    ph_collect = 0
+  } else {
+    cur_phaselist = cur_phaselist " " line
+  }
+  next
+}
+
+# block-style list item under a bare "phases:" key: "        - 4"
+block == "milestones" && entry_open && ph_collect == 2 && $0 ~ /^        - / {
+  line = strip_comment($0)
+  sub(/^        - [ \t]*/, "", line)
+  cur_phaselist = cur_phaselist " " unquote(trim(line))
+  next
+}
+
 # any other 4-space line inside milestones:/phases: (not "- id:") -> malformed
 # dedent: closes the current entry without opening a new one.
 (block == "milestones" || block == "phases") && $0 ~ /^    [A-Za-z_-]/ {
@@ -140,13 +180,8 @@ block == "waves" && $0 ~ /^    [0-9]+:/ {
   next
 }
 
-END {
-  finish_entry()
-
-  required_ms = "name phases"
-  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
-
-  # 1. required fields
+# 1. required fields (+ non-empty phases list on milestones)
+function check_fields(   i, j, n, reqs, cnt, toks) {
   for (i = 1; i <= ms_count; i++) {
     n = split(required_ms, reqs, " ")
     for (j = 1; j <= n; j++) {
@@ -155,6 +190,15 @@ END {
         found++
       }
     }
+    if (index(ms_fields[i], " phases ") != 0) {
+      cnt = 0
+      n = split(ms_phaselist[i], toks, /[ ,]+/)
+      for (j = 1; j <= n; j++) if (trim(toks[j]) != "") cnt++
+      if (cnt == 0) {
+        print "finding=missing-field:milestone:" ms_id[i] ":phases"
+        found++
+      }
+    }
   }
   for (i = 1; i <= ph_count; i++) {
     n = split(required_ph, reqs, " ")
@@ -165,39 +209,60 @@ END {
       }
     }
   }
+}
 
-  # phase-id set + first-seen order tracking for duplicate detection
+# phase-id bookkeeping consumed by check_dups/check_refs/check_orphans:
+# dup_count (occurrences), dup_list (mdir detail per occurrence), phase_exists (set)
+function collect_phase_index(   i, id) {
   for (i = 1; i <= ph_count; i++) {
     id = ph_id[i]
-    phase_seen[id] = phase_seen[id] "" (phase_seen[id] == "" ? "" : ",")
     dup_list[id] = (dup_list[id] == "" ? "" : dup_list[id] ",") (ph_mdir[i] == "" ? "(none)" : ph_mdir[i])
     dup_count[id]++
     phase_exists[id] = 1
   }
+}
+
+# pre-pass: claimed_by[] must be fully populated before check_orphans reads it
+function collect_claimed(   i, j, m, claimed, pid) {
+  for (i = 1; i <= ms_count; i++) {
+    m = split(ms_phaselist[i], claimed, /[ ,]+/)
+    for (j = 1; j <= m; j++) {
+      pid = trim(claimed[j])
+      if (pid != "") claimed_by[pid] = 1
+    }
+  }
+}
 
-  # 2. duplicate phase ids
-  for (id in dup_count) {
-    if (dup_count[id] > 1) {
+# 2. duplicate phase ids — first-seen order over ph_id[] (stable across awk
+# impls, unlike for-in), one report per id via dup_reported[]
+function check_dups(   i, id) {
+  for (i = 1; i <= ph_count; i++) {
+    id = ph_id[i]
+    if (dup_count[id] > 1 && !(id in dup_reported)) {
+      dup_reported[id] = 1
       print "finding=duplicate-phase-id:" id ":" dup_list[id]
       found++
     }
   }
+}
 
-  # 3. dangling-phase-ref (milestone claims a phase id with no phase entry)
+# 3. dangling-phase-ref (milestone claims a phase id with no phase entry)
+function check_refs(   i, j, m, claimed, pid) {
   for (i = 1; i <= ms_count; i++) {
     m = split(ms_phaselist[i], claimed, /[ ,]+/)
     for (j = 1; j <= m; j++) {
       pid = trim(claimed[j])
       if (pid == "") continue
-      claimed_by[pid] = 1
       if (!(pid in phase_exists)) {
         print "finding=dangling-phase-ref:milestone:" ms_id[i] ":phase:" pid
         found++
       }
     }
   }
+}
 
-  # orphan-phase (phase entry claimed by zero milestones)
+# orphan-phase (phase entry claimed by zero milestones; reads claimed_by[])
+function check_orphans(   i, id) {
   for (i = 1; i <= ph_count; i++) {
     id = ph_id[i]
     if (!(id in claimed_by)) {
@@ -205,8 +270,10 @@ END {
       found++
     }
   }
+}
 
-  # 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+# 4. bad-milestone-dir (milestone_dir prefix must resolve to a real milestone id)
+function check_mdirs(   i, prefix, numeral) {
   for (i = 1; i <= ms_count; i++) {
     ms_numeral[bare_num(ms_id[i])] = 1
   }
@@ -222,8 +289,10 @@ END {
       }
     }
   }
+}
 
-  # 5. dangling-wave-ref
+# 5. dangling-wave-ref
+function check_waves(   i, j, m, wids, pid) {
   for (i = 1; i <= wave_count; i++) {
     m = split(wave_ids[i], wids, /[ ,]+/)
     for (j = 1; j <= m; j++) {
@@ -235,6 +304,22 @@ END {
       }
     }
   }
+}
+
+END {
+  finish_entry()
+
+  required_ms = "name phases"
+  required_ph = "name goal requirements dependencies success_criteria estimated_hours status"
+
+  check_fields()
+  collect_phase_index()
+  collect_claimed()
+  check_dups()
+  check_refs()
+  check_orphans()
+  check_mdirs()
+  check_waves()
 
   if (found + 0 == 0) {
     print "ok=clean"
@@ -243,4 +328,3 @@ END {
   exit 1
 }
 ' "$FILE"
-exit $?

package/template/.forge/checks/tests/forge-check-lint.test.sh

@@ -7,7 +7,7 @@
 #           lint=fail          + finding=<rule>:<file>[:<line>] lines
 #           lint=justified justify="<trailer line>"
 #                              + "finding=<rule>:<file>[:<line>] justified" lines
-#           rule ∈ cannot-fail|silent-fail|existence-only|deleted-assertion|feature-removal|skip-marker
+#           rule ∈ cannot-fail|silent-fail|existence-only|deleted-assertion|feature-removal|skip-marker|driven-by-missing
 #   exit:   0 = clean or justified; 1 = fail; 2 = bad invocation.
 #   Range MUST be three-dot BASE...HEAD; scanned against merge-base(BASE, HEAD).
 #
@@ -28,17 +28,24 @@
 #              allowlist: still fires, still needs the operator act, only the label
 #              changes (partial source shrink keeps the stricter deleted-assertion);
 #          skip-marker — added .only(/.skip(/it.skip/describe.only/xit(/xdescribe(/
-#              @pytest.mark.skip/t.Skip() line.
+#              @pytest.mark.skip/t.Skip() line;
+#          driven-by-missing — CONFIG-GATED, default OFF: when the BASE-side
+#              .forge/project.yml carries attribution.driven_by: true, every
+#              non-merge commit of merge-base..head must carry a
+#              Driven-by: <email> trailer (optional trailing session ref);
+#              finding's file slot = the offending commit's short SHA. Absent/
+#              false config = rule fully off. Base-side read: a PR cannot
+#              disable it for itself.
 #   Justification: a "Lint-Justify: <one line>" trailer in ANY commit message of
 #   merge-base..head (pure git). Lifts b/c/deleted-assertion/feature-removal/
-#   skip-marker → exit 0 lint=justified. NEVER lifts (a).
+#   skip-marker/driven-by-missing → exit 0 lint=justified. NEVER lifts (a).
 #
 # Offline by construction: remote-less mktemp fixture repos (NFR-032).
 #
 # Usage:
 #   ./.forge/checks/tests/forge-check-lint.test.sh                # all cases
 #   ./.forge/checks/tests/forge-check-lint.test.sh cannot-fail    # one tag
-# Filter tags: cannot-fail silent-fail existence-only deleted-assertion feature-removal skip-marker justify docs-only invocation
+# Filter tags: cannot-fail silent-fail existence-only deleted-assertion feature-removal skip-marker driven-by waiver-boundary justify docs-only invocation
 #
 # RED-phase friendly: missing helper → every selected case FAILS, suite exits
 # non-zero, no abort. Exits 0 iff every selected case passes. Self-cleans.
@@ -566,6 +573,121 @@ if running justify; then
   check "justify: trailer never saves a PR carrying rule a (exit 1)" "$RC" "1"
 fi
 
+# ---------------------------------------------------------------------------
+# driven-by — the config-gated Driven-by trailer rule (hold-waiver patch W2).
+# Default OFF; base-side project.yml attribution.driven_by: true turns it on.
+# ---------------------------------------------------------------------------
+if running driven-by; then
+  PROJ_ON='attribution:
+  driven_by: true'
+
+  # OFF (default): no config → a trailer-less commit is clean (zero behavior change)
+  R=$(new_repo db-off)
+  put "$R" src/app.js 'x'
+  pr "$R"
+  put "$R" src/app.js 'y'
+  run_lint "$R" 'main...pr'
+  check "driven-by OFF: no config, trailer-less commit is clean (exit 0)" "$RC" "0"
+  check_absent "driven-by OFF: no driven-by finding" "$OUT" "driven-by-missing"
+
+  # OFF (explicit false): rule stays off
+  R=$(new_repo db-false)
+  put "$R" .forge/project.yml 'attribution:
+  driven_by: false'
+  pr "$R"
+  put "$R" src/app.js 'y'
+  run_lint "$R" 'main...pr'
+  check "driven-by OFF: driven_by false stays off (exit 0)" "$RC" "0"
+
+  # ON: a commit missing the trailer fails, finding names its short SHA
+  R=$(new_repo db-on)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y'
+  DB_SHA="$(git -C "$R" rev-parse --short pr)"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: missing trailer fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: verdict" "$OUT" "lint=fail"
+  check_contains "driven-by ON: finding names the commit" "$OUT" "finding=driven-by-missing:$DB_SHA"
+
+  # ON: every commit carrying the trailer is clean (optional session ref allowed)
+  R=$(new_repo db-ok)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: zayne@zayne.co.za (session cse_01X)'
+  put "$R" src/app.js 'z' 'Driven-by: zayne@zayne.co.za'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: trailered commits are clean (exit 0)" "$RC" "0"
+  check "driven-by ON: verdict clean" "$OUT" "lint=clean"
+
+  # ON: a malformed trailer (no email shape) still fails
+  R=$(new_repo db-malformed)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: somebody'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: trailer without an email fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: malformed finding" "$OUT" "finding=driven-by-missing:"
+
+  # ON, mixed: one trailered + one bare commit → only the bare one is named
+  R=$(new_repo db-mixed)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Driven-by: zayne@zayne.co.za'
+  put "$R" src/other.js 'w'
+  DB_BARE="$(git -C "$R" rev-parse --short pr)"
+  DB_GOOD="$(git -C "$R" rev-parse --short pr~1)"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON mixed: bare commit fails (exit 1)" "$RC" "1"
+  check_contains "driven-by ON mixed: bare commit named" "$OUT" "finding=driven-by-missing:$DB_BARE"
+  check_absent "driven-by ON mixed: trailered commit not named" "$OUT" "finding=driven-by-missing:$DB_GOOD"
+
+  # Base-side gate: a PR that deletes the config cannot switch the rule off for itself
+  R=$(new_repo db-evade)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  git -C "$R" rm -q .forge/project.yml
+  git -C "$R" commit -qm "drop attribution config"
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: head-side config removal cannot evade (exit 1)" "$RC" "1"
+  check_contains "driven-by ON: evasion finding" "$OUT" "finding=driven-by-missing:"
+
+  # Lint-Justify lifts it (same operator-act channel as the other liftable rules)
+  R=$(new_repo db-justify)
+  put "$R" .forge/project.yml "$PROJ_ON"
+  pr "$R"
+  put "$R" src/app.js 'y' 'Lint-Justify: host-authored dependabot commit, attribution n/a'
+  run_lint "$R" 'main...pr'
+  check "driven-by ON: Lint-Justify lifts (exit 0)" "$RC" "0"
+  check_contains "driven-by ON: justified verdict" "$OUT" "lint=justified"
+  check_contains "driven-by ON: finding listed as justified" "$OUT" "finding=driven-by-missing:"
+fi
+
+# ---------------------------------------------------------------------------
+# waiver-boundary — the hold check's run-waiver binding must have ZERO effect
+# here: the waiver applies to the hold check only, never the lint.
+# ---------------------------------------------------------------------------
+if running waiver-boundary; then
+  R=$(new_repo wb)
+  put "$R" .forge/hold-config.yml 'version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main'
+  put "$R" "$WF" 'jobs: {}'
+  pr "$R"
+  put "$R" "$WF" 'jobs:
+  gate:
+    steps:
+      - run: exit 0'
+  run_lint "$R" 'main...pr'
+  check "waiver-boundary: hold waiver binding never lifts a lint finding (exit 1)" "$RC" "1"
+  check_contains "waiver-boundary: finding intact" "$OUT" "finding=cannot-fail:$WF"
+fi
+
 # ---------------------------------------------------------------------------
 # docs-only — acceptance 6: a status on every PR
 # ---------------------------------------------------------------------------

package/template/.forge/checks/tests/forge-hold-check.test.sh

@@ -25,6 +25,15 @@
 #                   suites)  (+config deploy_paths, gating_tests)
 #   Waiver: any --approvals login ∈ base-side config operators: → waived. Absent
 #   config / empty operators → NO waiver possible (raise-only safe default).
+#   Run-waiver (hold-waiver patch): OPTIONAL base-side `waiver: {workflow, ref}`
+#   binding — when a hold fired and no operator approval waives it, a host-queried
+#   run of that workflow waives iff ALL of: workflow path matches; run ref ==
+#   repo default branch (== configured ref); conclusion == success; display_title
+#   carries the PR head SHA. Output: hold=waived waiver_run=<url>. FAIL-CLOSED on
+#   every leg (unconfigured / gh missing / API unreachable / no match / wrong ref
+#   / config-ref drift / wrong path / non-success / superseded SHA → hold stands);
+#   unconfigured behavior is byte-identical to the pre-waiver check (no gh call).
+#   gh is env-overridable (FORGE_HOLD_GH) — fixtures stub it and stay offline.
 #
 # Builds throwaway git repos in mktemp dirs with NO remote configured anywhere —
 # offline by construction (NFR-032); any network dependency in the script breaks here.
@@ -32,7 +41,7 @@
 # Usage:
 #   ./.forge/checks/tests/forge-hold-check.test.sh              # all cases
 #   ./.forge/checks/tests/forge-hold-check.test.sh pain6        # one tag
-# Filter tags: irreversible structural pain6 waiver self-protect docs-only invocation multi
+# Filter tags: irreversible structural pain6 waiver run-waiver self-protect docs-only invocation multi
 #
 # RED-phase friendly (TDD): a missing/non-executable helper does NOT abort the
 # suite — every selected case FAILS with "(helper missing ...)" as the got-value
@@ -382,6 +391,162 @@ if running multi; then
   check_contains "multi: protected named" "$OUT" "fact=protected:.github/workflows/deploy.yml"
 fi
 
+# ---------------------------------------------------------------------------
+# run-waiver — the Environment-gated waiver run channel: pass-on-match plus a
+# neg-control per fail-closed leg. gh is stubbed offline via FORGE_HOLD_GH.
+# ---------------------------------------------------------------------------
+if running run-waiver; then
+  GH_STUB="$ROOT/gh-stub"
+  cat > "$GH_STUB" <<'STUB'
+#!/bin/sh
+# Offline gh stand-in for the run-waiver channel. Argv shapes the check uses:
+#   gh api repos/{owner}/{repo} --jq .default_branch
+#   gh api "repos/{owner}/{repo}/actions/workflows/<wf>/runs?..." --jq <projection>
+# Driven by env: STUB_DEFAULT_BRANCH (empty/unset => API failure, exit 1),
+# STUB_RUNS_FILE (TSV: conclusion, head_branch, path, html_url, display_title;
+# unset/missing => API failure), STUB_LOG (append argv per call when set).
+[ -n "${STUB_LOG:-}" ] && printf '%s\n' "$*" >> "$STUB_LOG"
+case "${2:-}" in
+  'repos/{owner}/{repo}')
+    [ -n "${STUB_DEFAULT_BRANCH:-}" ] || exit 1
+    printf '%s\n' "$STUB_DEFAULT_BRANCH" ;;
+  'repos/{owner}/{repo}/actions/workflows/'*)
+    [ -n "${STUB_RUNS_FILE:-}" ] && [ -f "$STUB_RUNS_FILE" ] || exit 1
+    cat "$STUB_RUNS_FILE" ;;
+  *) exit 1 ;;
+esac
+STUB
+  chmod +x "$GH_STUB"
+
+  CONFIG_WAIVER='version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main'
+
+  WURL='https://host.example/actions/runs/101'
+  WPATH='.github/workflows/waive-hold.yml'
+
+  new_waiver_repo() { # name, config → repo whose pr branch carries a migration (hold fires)
+    nw_d=$(new_repo "$1")
+    put "$nw_d" .forge/hold-config.yml "$2"
+    pr "$nw_d"
+    put "$nw_d" app/migrations/010_waiver.py 'alter table'
+    printf '%s\n' "$nw_d"
+  }
+
+  # pass-on-match: approved success run on the default branch, title carries head SHA
+  R=$(new_waiver_repo rw-pass "$CONFIG_WAIVER")
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.pass"
+  export FORGE_HOLD_GH="$GH_STUB" STUB_DEFAULT_BRANCH=main STUB_RUNS_FILE="$ROOT/runs.pass"
+  run_hold "$R" 'main...pr'
+  check "run-waiver: approved matching run waives (exit 0)" "$RC" "0"
+  check_contains "run-waiver: verdict annotates the run URL" "$OUT" "hold=waived waiver_run=$WURL"
+  check_contains "run-waiver: lists what it waived" "$OUT" "fact=irreversible:app/migrations/010_waiver.py waived"
+
+  # neg fail-closed leg: UNCONFIGURED — no waiver block: no gh call, and the
+  # blocked output is byte-identical to a run with no stub env at all.
+  R=$(new_waiver_repo rw-unconf "$CONFIG_OPS")
+  export STUB_LOG="$ROOT/gh.unconf.log"
+  : > "$STUB_LOG"
+  run_hold "$R" 'main...pr'
+  UNCONF_OUT="$OUT"
+  check "run-waiver neg (unconfigured): hold stands (exit 1)" "$RC" "1"
+  check "run-waiver neg (unconfigured): gh never invoked" "$(cat "$STUB_LOG")" ""
+  unset FORGE_HOLD_GH STUB_DEFAULT_BRANCH STUB_RUNS_FILE STUB_LOG
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (unconfigured): output byte-identical to pre-waiver check" "$OUT" "$UNCONF_OUT"
+
+  # neg fail-closed leg: gh MISSING (no host CLI at all)
+  R=$(new_waiver_repo rw-nogh "$CONFIG_WAIVER")
+  export FORGE_HOLD_GH="$ROOT/definitely-no-such-gh"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (gh missing): hold stands (exit 1)" "$RC" "1"
+  check_contains "run-waiver neg (gh missing): blocked verdict" "$OUT" "hold=blocked"
+
+  # neg fail-closed leg: API UNREACHABLE (default-branch query fails)
+  export FORGE_HOLD_GH="$GH_STUB" STUB_DEFAULT_BRANCH="" STUB_RUNS_FILE="$ROOT/runs.pass"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (API unreachable): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: NO MATCHING RUN (API reachable, zero runs)
+  : > "$ROOT/runs.empty"
+  export STUB_DEFAULT_BRANCH=main STUB_RUNS_FILE="$ROOT/runs.empty"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (no matching run): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: WRONG REF — the only success run rode a PR-branch copy
+  # of the workflow (gate strippable), not the default branch.
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tpr\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.wrongref"
+  export STUB_RUNS_FILE="$ROOT/runs.wrongref"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (wrong ref): PR-branch run cannot waive (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: CONFIG-REF DRIFT — configured ref != repo default branch
+  R=$(new_waiver_repo rw-drift 'version: 1
+operators: []
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: develop')
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.drift"
+  export STUB_RUNS_FILE="$ROOT/runs.drift"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (config-ref drift): waiver.ref != default branch (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: SUPERSEDED SHA — a new push after the approved run;
+  # the run's title carries the OLD head SHA, so it no longer matches.
+  R=$(new_waiver_repo rw-stale "$CONFIG_WAIVER")
+  OLD_SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$OLD_SHA" > "$ROOT/runs.stale"
+  put "$R" src/followup.js 'pushed after the waiver run'
+  export STUB_RUNS_FILE="$ROOT/runs.stale"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (superseded SHA): new push invalidates the waiver (exit 1)" "$RC" "1"
+  check_contains "run-waiver neg (superseded SHA): blocked verdict" "$OUT" "hold=blocked"
+
+  # neg fail-closed leg: WRONG WORKFLOW PATH — a same-shaped run of another workflow
+  R=$(new_waiver_repo rw-path "$CONFIG_WAIVER")
+  SHA=$(git -C "$R" rev-parse pr)
+  printf 'success\tmain\t.github/workflows/other.yml\t%s\twaive-hold sha=%s\n' "$WURL" "$SHA" > "$ROOT/runs.path"
+  export STUB_RUNS_FILE="$ROOT/runs.path"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (wrong workflow path): hold stands (exit 1)" "$RC" "1"
+
+  # neg fail-closed leg: NON-SUCCESS CONCLUSION — pending/rejected run never waives
+  printf 'failure\tmain\t%s\t%s\twaive-hold sha=%s\n' "$WPATH" "$WURL" "$SHA" > "$ROOT/runs.fail"
+  export STUB_RUNS_FILE="$ROOT/runs.fail"
+  run_hold "$R" 'main...pr'
+  check "run-waiver neg (non-success run): hold stands (exit 1)" "$RC" "1"
+
+  # channel precedence: an operator PR approval still waives on its own — the
+  # run-waiver channel is additive, not a replacement.
+  R=$(new_waiver_repo rw-op 'version: 1
+operators:
+  - zayne
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []
+waiver:
+  workflow: waive-hold.yml
+  ref: main')
+  AF=$(approvals rwop zayne)
+  export STUB_DEFAULT_BRANCH="" STUB_RUNS_FILE=""
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "run-waiver: operator approval still waives independently (exit 0)" "$RC" "0"
+  check_contains "run-waiver: operator verdict unchanged" "$OUT" "hold=waived waived_by=zayne"
+
+  unset FORGE_HOLD_GH STUB_DEFAULT_BRANCH STUB_RUNS_FILE STUB_LOG
+fi
+
 # ---------------------------------------------------------------------------
 # invocation — exit 2 on bad usage, never a false verdict
 # ---------------------------------------------------------------------------