forge-orkes 0.71.0 → 0.73.1

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

@@ -0,0 +1,487 @@
+#!/usr/bin/env sh
+# Fixture suite for .forge/checks/forge-roadmap-check.sh (m-39, plan-01, phase 71).
+#
+# Contract under test (locked interface — do not re-derive):
+#   forge-roadmap-check.sh [<roadmap-file>]     # default: <git-root>/.forge/roadmap.yml
+#   stdout: ok=clean                            # no findings
+#           finding=<rule>:<detail>              # one line per problem
+#   rule ∈ missing-field | duplicate-phase-id | dangling-phase-ref | orphan-phase
+#        | bad-milestone-dir | dangling-wave-ref
+#   exit: 0 = ok=clean; 1 = findings; 2 = bad invocation (missing/unreadable file)
+#
+#   Required fields — milestone entry: id, name, phases (non-empty: an empty
+#                     list — `phases: []` — 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 phases predate it) —
+#   validated only when present (bad-milestone-dir rule); absence never a finding.
+#
+# Unlike forge-hold-check.sh/forge-check-lint.sh, this check reads ONE YAML file,
+# not a diff — fixtures are plain files under mktemp -d (one throwaway git repo
+# for the no-arg default-path case only).
+#
+# Usage:
+#   ./.forge/checks/tests/forge-roadmap-check.test.sh                # all cases
+#   ./.forge/checks/tests/forge-roadmap-check.test.sh duplicate-id   # one tag
+# Filter tags: clean missing-field duplicate-id refs milestone-dir waves malformed invocation
+#
+# RED-phase friendly: missing helper → every selected case FAILS, suite exits
+# non-zero, no abort. Exits 0 iff every selected case passes AND at least one
+# case block was selected (a typo'd tag must not exit green). Self-cleans.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../forge-roadmap-check.sh"
+FILTER="${1:-}"
+
+[ -x "$HELPER" ] || printf 'NOTE: %s missing or not executable — RED phase, every selected case below should FAIL\n' "$HELPER" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+SELECTED=0
+
+want_tag() {
+  if [ -z "$FILTER" ] || [ "$FILTER" = "$1" ]; then
+    SELECTED=$((SELECTED + 1))
+    return 0
+  fi
+  return 1
+}
+
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+
+# run_check <fixture-path> -> sets OUT (stdout) and RC (exit status)
+run_check() {
+  OUT="$("$HELPER" "$1" 2>"$ROOT/stderr")"
+  RC=$?
+}
+
+assert_exit() {
+  # $1=case-label $2=expected-code
+  if [ "$RC" = "$2" ]; then pass "$1 (exit $2)"; else fail "$1 (exit expected $2, got $RC)"; fi
+}
+
+assert_finding() {
+  # $1=case-label $2=exact-expected-line
+  if printf '%s\n' "$OUT" | grep -qF "$2"; then
+    pass "$1 (found: $2)"
+  else
+    fail "$1 (missing expected line: $2 -- got: $OUT)"
+  fi
+}
+
+assert_no_finding_matching() {
+  # $1=case-label $2=grep-pattern that must NOT appear
+  if printf '%s\n' "$OUT" | grep -qE "$2"; then
+    fail "$1 (unexpected finding matching: $2 -- got: $OUT)"
+  else
+    pass "$1 (no finding matching: $2)"
+  fi
+}
+
+assert_clean() {
+  # $1=case-label
+  if [ "$OUT" = "ok=clean" ]; then pass "$1 (ok=clean)"; else fail "$1 (expected ok=clean, got: $OUT)"; fi
+}
+
+# ---------------------------------------------------------------------------
+# Fixture bodies
+# ---------------------------------------------------------------------------
+
+# A minimal, fully well-formed roadmap. Phase 2 deliberately carries NO
+# milestone_dir -- doubles as the milestone-dir negative control (absence of
+# the optional field must never raise a finding).
+write_clean() {
+  cat >"$1" <<'EOF'
+roadmap:
+  milestones:
+    - id: 1
+      name: "Alpha"
+      phases: [1, 2]
+    - id: 2
+      name: "Beta"
+      phases: [3]
+
+  phases:
+    - id: 1
+      name: "alpha-one"
+      milestone_dir: "milestone-1/1-alpha-one"
+      goal: "User can alpha"
+      requirements: [FR-001]
+      dependencies: []
+      integration_checkpoint: false
+      success_criteria:
+        - "does the thing"
+      estimated_hours: 1
+      status: pending
+    - id: 2
+      name: "alpha-two"
+      goal: "User can alpha two"
+      requirements: [FR-002]
+      dependencies: [1]
+      success_criteria:
+        - "does thing two"
+      estimated_hours: 1
+      status: pending
+    - id: 3
+      name: "beta-one"
+      milestone_dir: "milestone-2/3-beta-one"
+      goal: "User can beta"
+      requirements: [FR-003]
+      dependencies: []
+      success_criteria:
+        - "does beta"
+      estimated_hours: 2
+      status: pending
+
+  waves:
+    1: [1, 3]
+    2: [2]
+EOF
+}
+
+# One well-formed phase entry (id 1, under milestone 1), field-complete --
+# the SINGLE source fixture every single-mutation case derives from via sed
+# (a required-field change edits this one body, not N copies).
+write_phase_template() {
+  cat >"$1" <<'EOF'
+roadmap:
+  milestones:
+    - id: 1
+      name: "Alpha"
+      phases: [1]
+
+  phases:
+    - id: 1
+      name: "alpha-one"
+      milestone_dir: "milestone-1/1-alpha-one"
+      goal: "User can alpha"
+      requirements: [FR-001]
+      dependencies: []
+      integration_checkpoint: false
+      success_criteria:
+        - "does the thing"
+      estimated_hours: 1
+      status: pending
+
+  waves:
+    1: [1]
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# clean
+# ---------------------------------------------------------------------------
+if want_tag clean; then
+  f="$ROOT/clean.yml"; write_clean "$f"
+  run_check "$f"
+  assert_exit "clean: well-formed roadmap" 0
+  assert_clean "clean: well-formed roadmap"
+  assert_no_finding_matching "clean: phase-2 has no milestone_dir" "bad-milestone-dir:2:"
+
+  # Quoted m-33-style milestone id + matching milestone_dir — 8 live milestones
+  # use this shape; an unquote/bare_num regression must not mass-false-positive.
+  f="$ROOT/clean-quoted-id.yml"
+  cat >"$f" <<'EOF'
+roadmap:
+  milestones:
+    - id: "m-33"
+      name: "Quoted id"
+      phases: [4]
+
+  phases:
+    - id: 4
+      name: "quoted-one"
+      milestone_dir: "milestone-33/4-quoted-one"
+      goal: "Quoted milestone ids resolve"
+      requirements: [FR-001]
+      dependencies: []
+      success_criteria:
+        - "stays clean"
+      estimated_hours: 1
+      status: pending
+
+  waves:
+    1: [4]
+EOF
+  run_check "$f"
+  assert_exit "clean: quoted m-33-style milestone id" 0
+  assert_clean "clean: quoted m-33-style milestone id"
+
+  # Trailing "# comment" on id lines (both milestone and phase) must not corrupt
+  # the captured id — pre-fix this false-fired bad-milestone-dir for every phase
+  # of the commented milestone (reproduced at m-39 review).
+  f="$ROOT/clean-id-comment.yml"
+  write_phase_template "$f"
+  sed -i.bak 's/^    - id: 1$/    - id: 1  # renumbered at rebase/' "$f"
+  run_check "$f"
+  assert_exit "clean: trailing comment on id lines" 0
+  assert_clean "clean: trailing comment on id lines"
+
+  # Block-style and wrapped flow phases: lists are real claims — pre-fix both
+  # parsed as empty and false-fired orphan-phase per phase.
+  f="$ROOT/clean-block-phases.yml"
+  cat >"$f" <<'EOF'
+roadmap:
+  milestones:
+    - id: 1
+      name: "Alpha"
+      phases:
+        - 1
+        - 2
+    - id: 2
+      name: "Beta"
+      phases: [2,
+        3]
+
+  phases:
+    - id: 1
+      name: "alpha-one"
+      goal: "User can alpha"
+      requirements: [FR-001]
+      dependencies: []
+      success_criteria:
+        - "does the thing"
+      estimated_hours: 1
+      status: pending
+    - id: 2
+      name: "alpha-two"
+      goal: "User can alpha two"
+      requirements: [FR-002]
+      dependencies: [1]
+      success_criteria:
+        - "does thing two"
+      estimated_hours: 1
+      status: pending
+    - id: 3
+      name: "beta-one"
+      goal: "User can beta"
+      requirements: [FR-003]
+      dependencies: []
+      success_criteria:
+        - "does beta"
+      estimated_hours: 2
+      status: pending
+
+  waves:
+    1: [1, 2, 3]
+EOF
+  run_check "$f"
+  assert_exit "clean: block-style + wrapped flow phase lists" 0
+  assert_clean "clean: block-style + wrapped flow phase lists"
+fi
+
+# ---------------------------------------------------------------------------
+# missing-field (phase side): delete one required field line at a time
+# ---------------------------------------------------------------------------
+if want_tag missing-field; then
+  for field in name goal requirements dependencies estimated_hours status; do
+    f="$ROOT/missing-phase-$field.yml"
+    write_phase_template "$f"
+    sed -i.bak "/^      $field:/d" "$f"
+    run_check "$f"
+    assert_exit "missing-field phase:$field" 1
+    assert_finding "missing-field phase:$field" "finding=missing-field:phase:1:$field"
+  done
+
+  # success_criteria is a two-line block field (key + one list item)
+  f="$ROOT/missing-phase-success_criteria.yml"
+  write_phase_template "$f"
+  sed -i.bak '/^      success_criteria:/,/^        - /d' "$f"
+  run_check "$f"
+  assert_exit "missing-field phase:success_criteria" 1
+  assert_finding "missing-field phase:success_criteria" "finding=missing-field:phase:1:success_criteria"
+
+  # milestone side: name, phases
+  f="$ROOT/missing-milestone-name.yml"
+  write_phase_template "$f"
+  sed -i.bak '/^      name: "Alpha"/d' "$f"
+  run_check "$f"
+  assert_exit "missing-field milestone:name" 1
+  assert_finding "missing-field milestone:name" "finding=missing-field:milestone:1:name"
+
+  f="$ROOT/missing-milestone-phases.yml"
+  write_phase_template "$f"
+  sed -i.bak '/^      phases: \[1\]/d' "$f"
+  run_check "$f"
+  assert_exit "missing-field milestone:phases" 1
+  assert_finding "missing-field milestone:phases" "finding=missing-field:milestone:1:phases"
+
+  # phases present but EMPTY — the "(non-empty)" half of the requirement:
+  # phases: [] must raise the same missing-field finding, not pass silently.
+  f="$ROOT/empty-milestone-phases.yml"
+  write_phase_template "$f"
+  sed -i.bak 's/^      phases: \[1\]$/      phases: []/' "$f"
+  run_check "$f"
+  assert_exit "missing-field milestone:phases empty list" 1
+  assert_finding "missing-field milestone:phases empty list" "finding=missing-field:milestone:1:phases"
+fi
+
+# ---------------------------------------------------------------------------
+# duplicate-id: the REAL live m-34/m-36 shape (id 63 claimed by two phases).
+# Kept literal — this fixture IS the incident, not a derived mutation.
+# ---------------------------------------------------------------------------
+if want_tag duplicate-id; then
+  f="$ROOT/duplicate-id.yml"
+  cat >"$f" <<'EOF'
+roadmap:
+  milestones:
+    - id: 36
+      name: "FORGE.md context diet"
+      phases: [63]
+    - id: 34
+      name: "Origin-first upgrading"
+      phases: [63]
+
+  phases:
+    - id: 63
+      name: "context-diet"
+      milestone_dir: "milestone-36/63-context-diet"
+      goal: "FORGE.md slimmed"
+      requirements: [FR-191]
+      dependencies: []
+      success_criteria:
+        - "wc -c <= 35840"
+      estimated_hours: 3
+      status: pending
+    - id: 63
+      name: "origin-upgrade-bin"
+      milestone_dir: "milestone-34/63-origin-upgrade-bin"
+      goal: "Non-interactive upgrade bin"
+      requirements: [FR-184]
+      dependencies: []
+      success_criteria:
+        - "upgrade --yes --json exits 0"
+      estimated_hours: 4
+      status: pending
+
+  waves:
+    1: [63]
+EOF
+  run_check "$f"
+  assert_exit "duplicate-id: real m-34/m-36 id-63 shape" 1
+  assert_finding "duplicate-id: real m-34/m-36 id-63 shape" "finding=duplicate-phase-id:63:milestone-36/63-context-diet,milestone-34/63-origin-upgrade-bin"
+fi
+
+# ---------------------------------------------------------------------------
+# refs: dangling-phase-ref (milestone claims a nonexistent phase) + orphan-phase
+# — both derived from a source fixture by single-line sed mutation
+# ---------------------------------------------------------------------------
+if want_tag refs; then
+  f="$ROOT/dangling-ref.yml"
+  write_phase_template "$f"
+  sed -i.bak 's/^      phases: \[1\]$/      phases: [1, 99]/' "$f"
+  run_check "$f"
+  assert_exit "refs: dangling-phase-ref" 1
+  assert_finding "refs: dangling-phase-ref" "finding=dangling-phase-ref:milestone:1:phase:99"
+
+  # orphan: drop phase 2 from the clean fixture's claims — phase 2 still exists,
+  # no milestone claims it. Phase 2 carries no milestone_dir, so this also
+  # covers the "(none)" detail branch of the orphan finding.
+  f="$ROOT/orphan-phase.yml"
+  write_clean "$f"
+  sed -i.bak 's/^      phases: \[1, 2\]$/      phases: [1]/' "$f"
+  run_check "$f"
+  assert_exit "refs: orphan-phase" 1
+  assert_finding "refs: orphan-phase" "finding=orphan-phase:2:(none)"
+fi
+
+# ---------------------------------------------------------------------------
+# milestone-dir: bad prefix fires; absent field never fires (negative control)
+# — both derived from the template by single-line sed mutation
+# ---------------------------------------------------------------------------
+if want_tag milestone-dir; then
+  f="$ROOT/bad-milestone-dir.yml"
+  write_phase_template "$f"
+  sed -i.bak 's|milestone-1/1-alpha-one|milestone-99/1-alpha-one|' "$f"
+  run_check "$f"
+  assert_exit "milestone-dir: bad prefix" 1
+  assert_finding "milestone-dir: bad prefix" "finding=bad-milestone-dir:1:milestone-99/1-alpha-one"
+
+  f="$ROOT/no-milestone-dir.yml"
+  write_phase_template "$f"
+  sed -i.bak '/^      milestone_dir:/d' "$f"
+  run_check "$f"
+  assert_exit "milestone-dir: absent field stays clean" 0
+  assert_clean "milestone-dir: absent field stays clean"
+fi
+
+# ---------------------------------------------------------------------------
+# waves: a wave referencing a phase id absent from phases:
+# — derived from the template by single-line sed mutation
+# ---------------------------------------------------------------------------
+if want_tag waves; then
+  f="$ROOT/dangling-wave.yml"
+  write_phase_template "$f"
+  sed -i.bak 's/^    1: \[1\]$/    1: [1, 99]/' "$f"
+  run_check "$f"
+  assert_exit "waves: dangling-wave-ref" 1
+  assert_finding "waves: dangling-wave-ref" "finding=dangling-wave-ref:1:99"
+fi
+
+# ---------------------------------------------------------------------------
+# malformed: a field mis-indented one level shallow -- proves the parser is
+# structural (indentation-keyed), not a flat "key: value anywhere" grep. A
+# flat grep would still find "success_criteria:" text in the file and wrongly
+# pass; the structural walk must NOT associate it with phase 1 at the wrong depth.
+# ---------------------------------------------------------------------------
+if want_tag malformed; then
+  f="$ROOT/malformed-indent.yml"
+  cat >"$f" <<'EOF'
+roadmap:
+  milestones:
+    - id: 1
+      name: "Alpha"
+      phases: [1]
+
+  phases:
+    - id: 1
+      name: "alpha-one"
+      goal: "User can alpha"
+      requirements: [FR-001]
+      dependencies: []
+    success_criteria:
+        - "does the thing"
+      estimated_hours: 1
+      status: pending
+
+  waves:
+    1: [1]
+EOF
+  run_check "$f"
+  assert_exit "malformed: mis-indented success_criteria" 1
+  assert_finding "malformed: mis-indented success_criteria" "finding=missing-field:phase:1:success_criteria"
+fi
+
+# ---------------------------------------------------------------------------
+# invocation: missing/unreadable file -> exit 2, nothing on stdout;
+# no-arg default resolves <git-root>/.forge/roadmap.yml
+# ---------------------------------------------------------------------------
+if want_tag invocation; then
+  run_check "$ROOT/does-not-exist.yml"
+  assert_exit "invocation: nonexistent file" 2
+  if [ -z "$OUT" ]; then pass "invocation: empty stdout on bad invocation"; else fail "invocation: expected empty stdout, got: $OUT"; fi
+  if [ -s "$ROOT/stderr" ]; then pass "invocation: diagnostic on stderr"; else fail "invocation: expected a diagnostic on stderr"; fi
+
+  # default no-arg path inside a throwaway git repo (the only git use in this suite)
+  if command -v git >/dev/null 2>&1; then
+    d="$ROOT/defrepo"
+    mkdir -p "$d/.forge"
+    git init -q "$d"
+    write_clean "$d/.forge/roadmap.yml"
+    OUT="$(cd "$d" && "$HELPER" 2>"$ROOT/stderr")"
+    RC=$?
+    assert_exit "invocation: no-arg resolves git-root roadmap" 0
+    assert_clean "invocation: no-arg resolves git-root roadmap"
+  else
+    printf 'NOTE: git unavailable — skipping no-arg default-path case\n' >&2
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+printf '\n%d selected case block(s): %d passed, %d failed\n' "$SELECTED" "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ] && [ "$SELECTED" -gt 0 ]

package/template/.forge/templates/hold-config.yml

@@ -32,3 +32,18 @@ deploy_paths: []
 # deleted-assertion scope when set — default there is EVERY test file in the diff).
 gating_tests: []
   # - "tests/e2e/*"
+
+# OPTIONAL run-waiver binding — the Environment-gated hold waiver (default OFF).
+# When set and a hold has fired (and no operator PR approval waives it), the
+# check queries the host for a SUCCESSFUL run of this workflow on the repo's
+# DEFAULT branch whose run title carries the PR head SHA (the workflow's
+# run-name templates the sha input in — activate .forge/templates/waive-hold.yml
+# as .github/workflows/waive-hold.yml, gated by a `hold-waiver` Environment
+# whose required reviewer is the operator). Match → the hold passes, annotated
+# with the run URL. FAIL-CLOSED on every leg: unconfigured, API unreachable,
+# no matching run, run/config ref != default branch, stale/superseded SHA → the
+# hold stands. Applies to the HOLD CHECK ONLY — never lint or CI test checks.
+# CI needs `actions: read` on the token; see docs/merge-floor-checks.md §5.
+# waiver:
+#   workflow: waive-hold.yml    # workflow file under .github/workflows/
+#   ref: main                   # MUST equal the repo's default branch

package/template/.forge/templates/project.yml

@@ -155,6 +155,16 @@ models:
 #                                    #   phone-spawned sessions act without prompts — opt in only where the
 #                                    #   phone lane carries the same trust as an attended terminal.
 
+# attribution:                       # OPT-IN Driven-by attribution (hold-waiver patch) — default OFF.
+#   driven_by: true                  # When true, the merge-floor check-quality lint
+#                                    # (.forge/checks/forge-check-lint.sh) requires every non-merge PR
+#                                    # commit to carry a `Driven-by: <email>` trailer (optional trailing
+#                                    # session ref allowed) — the durable per-commit record of the driving
+#                                    # human, whatever identity authors the commit. Read from the BASE side
+#                                    # of the PR diff (a PR cannot disable it for itself; this file is on
+#                                    # the hold check's protected paths, so flipping it holds for operator
+#                                    # review). Absent/false → rule fully off, zero behavior change.
+
 risks:                              # What could go wrong?
   - risk: ""
     mitigation: ""

package/template/.forge/templates/state/desire-path.yml

@@ -1,46 +1,16 @@
-# Forge Desire-Path Observation — APPEND-ONLY
-#
-# One observation = one new file under state/desire-paths/. NEVER edit an
-# existing observation in place and NEVER keep a mutable occurrence counter —
-# that is what used to make state/index.yml conflict across worktrees.
-#
-# Filename: state/desire-paths/{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml
-#   e.g.   state/desire-paths/2026-06-10-recurring_friction-m7-uncommitted-state.yml
-# The date+type+milestone+slug make the name unique, so concurrent agents in
-# different worktrees only ever ADD files — git never has to merge content.
-#
-# Occurrence counts are DERIVED: the `forge` skill globs this directory and
-# groups by (type + normalized note). A pattern appearing in 3+ files is a
-# candidate for framework evolution, surfaced at `forge` boot — the single
-# review owner (see ADR-012).
-#
-# SCOPE decides where a 3+ pattern's fix lands:
-#   project   = fix targets user-owned files (constitution.md, design-system.md,
-#               context.md). Stays in-project.
-#   framework = fix targets Forge's own skills/templates. Eligible for UPSTREAM
-#               transport — forge review writes a portable block to
-#               state/desire-paths/upstream/ and (when gh + forge.upstream_repo
-#               are available) offers a GH issue against the Forge repo.
-# Lazy migration: a file with no `scope` is read as `project`.
+# Forge Desire-Path Observation — one file per observation
+# Copy to .forge/state/desire-paths/{YYYY-MM-DD}-{type}-{milestone}-{slug}.yml
+# Append-only: never edit an existing observation file; recurrence is derived
+# by globbing (type + normalized note), not a counter. See FORGE.md § state/desire-paths/.
 
-type: ""                 # deviation_pattern | tier_override | skipped_step |
-                         # recurring_friction | agent_struggle | user_correction
-scope: ""                # project | framework — set AT CAPTURE by the writing
-                         # skill, from the file its suggested fix targets.
-                         # Absent ⇒ project (lazy migration).
-suggestion_target: ""    # optional: the skill/file the fix would touch
-                         # (e.g. "planning/executing skills", "constitution.md")
-milestone: ""            # e.g. "m7" (or "global" if not milestone-scoped)
-skill: ""                # skill that observed it (executing, planning, verifying, ...)
-first_seen: null         # ISO 8601 date this observation was recorded
-related_files: []        # source files involved, if any
-note: ""                 # one-line description — the grouping key for occurrence counts
-
-# Optional type-specific detail (fill what applies to `type`):
-detail:
-  detected: ""           # tier_override: what Forge detected
-  overridden_to: ""      # tier_override: what the user chose
-  rule: null             # deviation_pattern: 1 | 2 | 3
-  correction: ""         # user_correction: the repeated correction
-  failure_pattern: ""    # agent_struggle: how the task fails
-  step: ""               # skipped_step: the step skipped
+type: ""                              # recurring_friction | agent_struggle | user_correction (etc. — free-form, grouped by exact string)
+date: ""                              # ISO 8601 date the observation was made, e.g. "2026-07-23"
+milestone: ""                         # milestone id, or a short label for non-milestone work (e.g. "quick-task (...)")
+scope: project                        # project | framework — absent ⇒ project (this repo only; framework ⇒ upstream-eligible per ADR-012)
+suggestion_target: ""                 # the file/skill this observation would change if acted on
+note: >
+  What was observed — concrete enough that a future review can judge recurrence
+  (same type + normalized note) without re-reading the original session.
+suggestion: >
+  What to do about it, if a fix is proposed. Omit this key when the observation
+  has no concrete suggestion yet.

package/template/.forge/templates/waive-hold.yml

@@ -0,0 +1,63 @@
+# waive-hold — Environment-gated hold waiver (TEMPLATE — hold-waiver patch,
+# operator-ruled 2026-07-22; see docs/merge-floor-checks.md).
+#
+# This file is a TEMPLATE shipped in .forge/templates/ — it is NOT an active
+# workflow here. To activate on a consuming repo:
+#   1. Create the `hold-waiver` Environment (repo Settings → Environments) with
+#      the operator as required reviewer. No secrets, no branch restriction.
+#   2. Copy this file to .github/workflows/waive-hold.yml on the DEFAULT branch.
+#   3. Bind it in .forge/hold-config.yml:
+#        waiver:
+#          workflow: waive-hold.yml
+#          ref: <default-branch>
+#
+# How it waives: the operator dispatches this workflow (phone-friendly) with the
+# held PR's full 40-char head SHA. The `environment: hold-waiver` gate parks the
+# run until the operator approves it — the approval IS the recorded human act
+# (D-9: lowering a hold is an explicit recorded act; Environment approvals have
+# no self-approval ban). On approval the run executes and succeeds; run-name
+# templates the SHA into the run's display title, which is exactly what
+# forge-hold-check.sh's run-waiver channel matches on (workflow path + default-
+# branch ref + success conclusion + head SHA in the title). A new push to the PR
+# changes its head SHA, so an old waiver run stops matching — waive per SHA.
+#
+# The job's body IS the record: it validates the input and asserts the SHA is
+# the head of an open PR (a run for a random SHA waives nothing anyway — the
+# assert just keeps the record clean). It deploys NOTHING and needs NO secrets —
+# only the default GITHUB_TOKEN, read-only.
+name: waive-hold
+run-name: "waive-hold sha=${{ inputs.sha }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: "Full 40-char head SHA of the held PR this waiver approves"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  record-waiver:
+    runs-on: ubuntu-latest
+    environment: hold-waiver   # the gate: required reviewer = the operator
+    env:
+      SHA: ${{ inputs.sha }}   # env-var indirection — the input never lands in script text
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: Validate SHA format (full 40-char hex, nothing else)
+        run: |
+          printf '%s\n' "$SHA" | grep -qE '^[0-9a-f]{40}$' \
+            || { printf 'waive-hold: sha input must be a full 40-char lowercase hex SHA, got: %s\n' "$SHA"; exit 1; }
+      - name: Assert the SHA is the head of an open PR
+        run: |
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/commits/$SHA/pulls" \
+            --jq "[.[] | select(.state == \"open\" and .head.sha == \"$SHA\")][0].number")"
+          if [ -z "$pr_number" ] || [ "$pr_number" = "null" ]; then
+            printf 'waive-hold: %s is not the head SHA of any OPEN pull request — refusing to record a waiver\n' "$SHA"
+            exit 1
+          fi
+          printf 'waive-hold: recorded — approved waiver for open PR #%s at head %s\n' "$pr_number" "$SHA"