forge-orkes 0.53.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.53.0",
+  "version": "0.56.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/hooks/forge-release-fold.sh

@@ -0,0 +1,458 @@
+#!/usr/bin/env sh
+# forge-release-fold — the fold-of-record: unit-id → release_state, computed
+# from git truth alone (m-30, plan 50-01). Generalizes the wu-done.sh stub:
+# where wu-done answers the single `done` predicate, this fold answers the
+# full release ladder for a unit — unmerged → merged → validated — and each
+# rung REQUIRES the one below it (validated requires merged, always checked
+# first). No committed file stores release_state; this script recomputes it
+# on every call, so a stored copy can never stick.
+#
+#   forge-release-fold.sh <unit-id> [--sha <sha>] [--main <ref>] [--project <path>]
+#
+#     unit-id            m-{N} (milestone unit).
+#     --sha <sha>        landed commit to fold over (skips resolution below).
+#     --main <ref>       the mainline ref. Default: main.
+#     --project <path>   operate on the repo at <path> (any dir inside it).
+#                        Default: the repo containing the CWD.
+#
+# Landed-sha resolution when --sha is absent (the unit's stable identity):
+#   (1) live branch recorded for the unit — MAIN-TREE
+#       .forge/state/milestone-{N}.yml lifecycle.worktree_branch, else
+#       MAIN-TREE .forge/streams/m-{N}.yml runtime.branch → that branch's tip
+#       (when the ref exists).
+#   (2) no live branch, state file tracked in main's tree → the LAST COMMIT
+#       TOUCHING that state file on main. NEVER main's moving tip (operator
+#       ruling 2026-07-16): a tip-resolving fold flaps off as soon as main
+#       advances past the sign-off. Containment (phase 51) checks against
+#       THIS stable sha.
+#   (3) unknown in both → exit 2 — the fold cannot ask the question, so it
+#       never emits a false verdict.
+#
+# merged = `git merge-base --is-ancestor <sha> <main-ref>`.
+#
+# Validation is dispatched on forge.validation_event from the project's
+# .forge/project.yml (default: in_session_signoff; promotion_approval is the
+# opt-in host-truth binding, plan 51-01). Under in_session_signoff, applied
+# only when merged, in order:
+#   (a) signoff tag: refs/tags/signoff/<unit-id> verifies via verify-signoff.sh
+#       (allowed signers from git config gpg.ssh.allowedSignersFile) against
+#       the resolved landed sha → validated reason=signed-off. A tag that
+#       FAILS verification yields nothing — fall through to the YAML routes.
+#       verify-signoff exit 2 (unconfigured) → route unavailable, silent.
+#   (b) main-tree milestone current.human_verified set and non-null
+#       → validated (today's YAML mechanism, preserved honestly).
+#   (c) main-tree current.status == complete → validated reason=legacy-complete
+#       (the FORGE.md grandfather — pre-gate closed milestones never
+#       retro-invalidate).
+#   (d) none of the above → merged (reason=bad-signature when a signoff tag
+#       exists but its signature failed, else reason=no-signoff).
+#
+# Under promotion_approval (B4 rev 2 — CI-signed tag, verified OFFLINE), the
+# promotion artifact is the ONLY validation route — the YAML/signoff routes
+# above never apply (host truth, not repo-side files). Tag pattern FROZEN
+# 2026-07-16: promotion/{sha}, {sha} = the full DEPLOY sha the host-side
+# Environment-approved job signed off (not per-unit). Verification is
+# CONTAINMENT, not tip-equality (operator ruling 2026-07-16): enumerate tags
+# by the pattern's prefix; a candidate validates the unit iff its SSH
+# signature verifies against the promotion allowed-signers AND the unit's
+# landed sha is an ancestor of the tag's target commit. First verified
+# containing tag → validated reason=promotion-approved. Otherwise merged with
+# reason=not-contained (a verified tag exists, unit outside it) |
+# bad-signature (candidates exist, none verify — unsigned/lightweight/
+# wrong-key lookalikes land here) | no-approval (no candidate tags at all).
+# Binding config (forge.promotion.*): tag_pattern (default promotion/{sha}),
+# allowed_signers (path; empty ⇒ git config gpg.ssh.allowedSignersFile).
+#
+# ALL milestone/stream YAML reads go through `git show <main-ref>:<path>` —
+# never the working tree. An agent-writable working-tree edit must not flip
+# the render (contract F7-F9). The validation MODE (project.yml) is a
+# working-tree read — that file is protected-path-held per the contract. The
+# promotion allowed-signers FILE (the signature root-of-trust) is likewise
+# read main-tree when it is tracked in main (see validate_promotion_approval)
+# — an in-repo signers file must not be forgeable from the working tree.
+#
+# stdout (machine-parseable, nothing else):
+#   release_state=unmerged reason=not-on-main
+#   release_state=merged reason=<no-signoff|no-approval|bad-signature|not-contained>
+#   release_state=validated [reason=<signed-off|legacy-complete|promotion-approved>]
+# Human-readable detail goes to stderr.
+#
+# Exit codes (mirrors wu-done.sh):
+#   0  a state was computed — ANY of the three. unmerged is an answer, not
+#      an error.
+#   2  bad invocation / unknown unit / unconfigured mode — no verdict emitted.
+#
+# Portable: POSIX sh + git + awk/sed. No network calls anywhere (NFR-030) —
+# works in a repo with no remote at all.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VERIFY="$SCRIPT_DIR/verify-signoff.sh"
+
+usage() {
+  printf 'usage: forge-release-fold.sh <unit-id> [--sha <sha>] [--main <ref>] [--project <path>]\n' >&2
+  exit 2
+}
+
+# --- helpers -------------------------------------------------------------
+
+# yaml_get <content> <block> <key> — scalar value of a 2-space-indented key
+# inside a top-level block. Strips trailing `# comments`. Prints the raw
+# value (possibly empty); never fails.
+yaml_get() {
+  printf '%s\n' "$1" | awk -v blk="$2" -v key="$3" '
+    /^[^ \t]/ { inblk = (index($0, blk ":") == 1) }
+    inblk && index($0, "  " key ":") == 1 {
+      val = substr($0, length(key) + 4)
+      sub(/[ \t]#.*$/, "", val)
+      if (val ~ /^[ \t]*#/) val = ""
+      gsub(/^[ \t]+/, "", val); gsub(/[ \t]+$/, "", val)
+      print val
+      exit
+    }
+  '
+}
+
+# unquote <value> — strip one layer of surrounding double or single quotes.
+unquote() {
+  uq="$1"
+  uq="${uq#\"}"; uq="${uq%\"}"
+  uq="${uq#"'"}"; uq="${uq%"'"}"
+  printf '%s\n' "$uq"
+}
+
+yaml_scalar() { # <content> <block> <key> — yaml_get + unquote
+  unquote "$(yaml_get "$1" "$2" "$3")"
+}
+
+# yaml_sub_get <content> <block> <subblock> <key> — scalar value of a 4-space-
+# indented key inside a 2-space-indented sub-block of a top-level block
+# (e.g. forge: → promotion: → tag_pattern:). Same comment-stripping contract
+# as yaml_get; never fails.
+yaml_sub_get() {
+  printf '%s\n' "$1" | awk -v blk="$2" -v sb="$3" -v key="$4" '
+    /^[^ \t]/ { inblk = (index($0, blk ":") == 1); insb = 0 }
+    inblk && /^  [^ \t]/ { insb = (index($0, "  " sb ":") == 1) }
+    insb && index($0, "    " key ":") == 1 {
+      val = substr($0, length(key) + 6)
+      sub(/[ \t]#.*$/, "", val)
+      if (val ~ /^[ \t]*#/) val = ""
+      gsub(/^[ \t]+/, "", val); gsub(/[ \t]+$/, "", val)
+      print val
+      exit
+    }
+  '
+}
+
+yaml_sub_scalar() { # <content> <block> <subblock> <key> — yaml_sub_get + unquote
+  unquote "$(yaml_sub_get "$1" "$2" "$3" "$4")"
+}
+
+# hv_is_set <milestone-yaml> — prints "set" iff current.human_verified is
+# populated: a non-empty non-null scalar, or an empty value followed by an
+# indented child block (`at:` etc.). Literal null/~ or absence is NOT set.
+hv_is_set() {
+  printf '%s\n' "$1" | awk '
+    /^[^ \t]/ { incur = (index($0, "current:") == 1); look = 0 }
+    incur && index($0, "  human_verified:") == 1 {
+      val = substr($0, 19)
+      sub(/[ \t]#.*$/, "", val)
+      if (val ~ /^[ \t]*#/) val = ""
+      gsub(/[ \t"]/, "", val)
+      if (val == "") { look = 1; next }
+      if (val != "null" && val != "~") print "set"
+      exit
+    }
+    look {
+      if ($0 ~ /^[ \t]*$/) next
+      if ($0 ~ /^    /) print "set"
+      exit
+    }
+  '
+}
+
+# --- argument parsing ------------------------------------------------------
+
+unit=""
+sha_arg=""
+main_ref="main"
+project="."
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --sha) shift; sha_arg="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --sha=*) sha_arg="${1#*=}"; shift ;;
+    --main) shift; main_ref="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --main=*) main_ref="${1#*=}"; shift ;;
+    --project) shift; project="${1:-}"; [ $# -gt 0 ] && shift || usage ;;
+    --project=*) project="${1#*=}"; shift ;;
+    -*) printf 'forge-release-fold: unknown option: %s\n' "$1" >&2; usage ;;
+    *)
+      if [ -z "$unit" ]; then unit="$1"; shift
+      else printf 'forge-release-fold: unexpected argument: %s\n' "$1" >&2; usage; fi
+      ;;
+  esac
+done
+
+[ -n "$unit" ] || usage
+case "$unit" in
+  m-*) ;;
+  *) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
+esac
+num="${unit#m-}"
+case "$num" in
+  ''|*[!0-9]*) printf 'forge-release-fold: unit-id must be m-<N>, got: %s\n' "$unit" >&2; usage ;;
+esac
+
+# --- repo + main ref -------------------------------------------------------
+
+if ! root="$(git -C "$project" rev-parse --show-toplevel 2>/dev/null)"; then
+  printf 'forge-release-fold: not a git repository: %s\n' "$project" >&2
+  exit 2
+fi
+
+if ! git -C "$root" rev-parse -q --verify "$main_ref^{commit}" >/dev/null 2>&1; then
+  printf 'forge-release-fold: cannot resolve main ref: %s\n' "$main_ref" >&2
+  exit 2
+fi
+
+state_path=".forge/state/milestone-$num.yml"
+stream_path=".forge/streams/$unit.yml"
+
+# MAIN-TREE state read — never the working tree. Empty when not tracked.
+state_yaml=""
+if git -C "$root" cat-file -e "$main_ref:$state_path" 2>/dev/null; then
+  state_yaml="$(git -C "$root" show "$main_ref:$state_path")"
+fi
+
+# --- landed-sha resolution ---------------------------------------------------
+
+# (1) live branch recorded for the unit (main-tree reads only).
+branch=""
+if [ -n "$state_yaml" ]; then
+  branch="$(yaml_scalar "$state_yaml" lifecycle worktree_branch)"
+  case "$branch" in null|'~') branch="" ;; esac
+fi
+if [ -z "$branch" ]; then
+  if git -C "$root" cat-file -e "$main_ref:$stream_path" 2>/dev/null; then
+    stream_yaml="$(git -C "$root" show "$main_ref:$stream_path")"
+    branch="$(yaml_scalar "$stream_yaml" runtime branch)"
+    case "$branch" in null|'~') branch="" ;; esac
+  fi
+fi
+
+sha=""
+if [ -n "$sha_arg" ]; then
+  if ! sha="$(git -C "$root" rev-parse -q --verify "$sha_arg^{commit}" 2>/dev/null)"; then
+    printf 'forge-release-fold: --sha does not resolve to a commit: %s\n' "$sha_arg" >&2
+    exit 2
+  fi
+else
+  if [ -n "$branch" ]; then
+    if tip="$(git -C "$root" rev-parse -q --verify "refs/heads/$branch^{commit}" 2>/dev/null)"; then
+      sha="$tip"
+    fi
+  fi
+  # (2) tracked-only → last commit touching the state file on main — the
+  # stable identity. NEVER the moving tip of main (anti-flap ruling).
+  if [ -z "$sha" ] && [ -n "$state_yaml" ]; then
+    if landed="$(git -C "$root" log -1 --format=%H "$main_ref" -- "$state_path" 2>/dev/null)" \
+        && [ -n "$landed" ]; then
+      sha="$landed"
+    fi
+  fi
+  # (3) unknown unit → exit 2, no verdict.
+  if [ -z "$sha" ]; then
+    printf 'forge-release-fold: unknown unit %s — no live branch recorded and %s is not tracked in %s\n' \
+      "$unit" "$state_path" "$main_ref" >&2
+    exit 2
+  fi
+fi
+
+# --- rung 1: merged? ---------------------------------------------------------
+# validated REQUIRES merged — checked first, always. An unmerged unit is
+# unmerged no matter what any approval artifact says.
+
+if ! git -C "$root" merge-base --is-ancestor "$sha" "$main_ref" 2>/dev/null; then
+  printf 'release_state=unmerged reason=not-on-main\n'
+  exit 0
+fi
+
+# --- rung 2: validation, dispatched on the binding mode ----------------------
+
+validate_in_session_signoff() {
+  tag_fail=""
+  tag_ref="refs/tags/signoff/$unit"
+
+  # (a) signoff-tag route: verify-signoff machinery, when usable. The fold
+  # constructs the invocation itself: --head is the landed sha it resolved;
+  # --evidence is extracted from the tag body (the signature + head checks
+  # are the real gate — a self-consistent evidence line cannot mismatch).
+  if git -C "$root" rev-parse -q --verify "$tag_ref" >/dev/null 2>&1 && [ -x "$VERIFY" ]; then
+    signers="$(git -C "$root" config --get gpg.ssh.allowedSignersFile 2>/dev/null || true)"
+    if [ -n "$signers" ]; then
+      # Tag message body: strip headers up to the first blank line, stop at
+      # the embedded signature block (same parse as verify-signoff.sh).
+      tag_msg="$(git -C "$root" cat-file -p "$tag_ref" \
+        | awk 'f{ if ($0 ~ /-----BEGIN SSH SIGNATURE-----/) exit; print } /^$/{ f=1 }')"
+      tag_evidence="$(printf '%s\n' "$tag_msg" | sed -n 's/^evidence: *//p' | head -1)"
+      if [ -n "$tag_evidence" ]; then
+        # if-guarded so errexit never aborts on a non-zero verify verdict.
+        if vout="$( (cd "$root" && "$VERIFY" "$unit" --head "$sha" \
+              --evidence "$tag_evidence" --allowed-signers "$signers") 2>/dev/null)"; then
+          vrc=0
+        else
+          vrc=$?
+        fi
+        if [ "$vrc" -eq 0 ]; then
+          printf 'release_state=validated reason=signed-off\n'
+          exit 0
+        elif [ "$vrc" -eq 1 ] && [ "$vout" = "reason=bad-signature" ]; then
+          tag_fail="bad-signature"
+        fi
+        # vrc 2 (unconfigured) or other exit-1 reasons (stale, mismatch):
+        # the tag route yields nothing — fall through to the YAML routes.
+      fi
+    fi
+  fi
+
+  # (b) human_verified route — main-tree read (git show), never working tree.
+  if [ -n "$state_yaml" ] && [ "$(hv_is_set "$state_yaml")" = "set" ]; then
+    printf 'release_state=validated\n'
+    exit 0
+  fi
+
+  # (c) legacy-complete grandfather — pre-gate closed milestones stay valid.
+  if [ -n "$state_yaml" ]; then
+    status="$(yaml_scalar "$state_yaml" current status)"
+    if [ "$status" = "complete" ]; then
+      printf 'release_state=validated reason=legacy-complete\n'
+      exit 0
+    fi
+  fi
+
+  # (d) merged, not validated.
+  if [ -n "$tag_fail" ]; then
+    printf 'release_state=merged reason=%s\n' "$tag_fail"
+  else
+    printf 'release_state=merged reason=no-signoff\n'
+  fi
+  exit 0
+}
+
+validate_promotion_approval() {
+  # Binding config — same working-tree project.yml read as the mode itself
+  # (protected-path-held per the contract). Pattern FROZEN: promotion/{sha}.
+  tag_pattern="$(yaml_sub_scalar "$project_yml" forge promotion tag_pattern)"
+  [ -n "$tag_pattern" ] || tag_pattern="promotion/{sha}"
+  case "$tag_pattern" in
+    *'{sha}'*) ;;
+    *)
+      printf 'forge-release-fold: forge.promotion.tag_pattern must contain {sha}, got: %s\n' "$tag_pattern" >&2
+      exit 2
+      ;;
+  esac
+  prefix="${tag_pattern%%\{sha\}*}"
+
+  # Allowed signers: the CI key's public half (committed, public keys only).
+  # Empty ⇒ git config gpg.ssh.allowedSignersFile. Neither → unconfigured
+  # mode, exit 2 — never a false verdict.
+  signers="$(yaml_sub_scalar "$project_yml" forge promotion allowed_signers)"
+  case "$signers" in null|'~') signers="" ;; esac
+  if [ -z "$signers" ]; then
+    signers="$(git -C "$root" config --get gpg.ssh.allowedSignersFile 2>/dev/null || true)"
+  fi
+  if [ -z "$signers" ]; then
+    printf 'forge-release-fold: promotion_approval is unconfigured — set forge.promotion.allowed_signers or git config gpg.ssh.allowedSignersFile\n' >&2
+    exit 2
+  fi
+  case "$signers" in
+    /*) ;;
+    *) signers="$root/$signers" ;;
+  esac
+
+  # Root-of-trust hardening — read the signers CONTENT from main-tree when the
+  # file is tracked in main, exactly like every milestone/stream field above
+  # (header invariant: the working tree is never the fold's source of truth).
+  # Without this, an agent that appends its own public key to the WORKING-TREE
+  # copy of the committed signers file, then mints an own-key-signed promotion
+  # tag, forges `validated` — and because boot re-renders through this same
+  # fold, the forgery would PERSIST across boots (defeating the F7-F9
+  # self-correction the whole trust story leans on). A signers path OUTSIDE the
+  # repo (absolute host path, or the git-config fallback pointing outside) is
+  # host-managed — trusted as-is, not agent-writable in the threat model.
+  case "$signers" in
+    "$root"/*)
+      signers_rel="${signers#"$root"/}"
+      if git -C "$root" cat-file -e "$main_ref:$signers_rel" 2>/dev/null; then
+        signers_main="$(mktemp)"
+        trap 'rm -f "$signers_main"' EXIT INT TERM
+        git -C "$root" show "$main_ref:$signers_rel" > "$signers_main"
+        signers="$signers_main"
+      fi
+      # In-repo but NOT tracked in main → untracked/git-ignored host file:
+      # left as-is (same trust as before; no tracked copy to prefer).
+      ;;
+  esac
+
+  # Enumerate candidate tags by the frozen pattern's prefix; first verified
+  # CONTAINING tag validates (a promotion approves a deploy sha; every unit
+  # whose landed sha is an ancestor of it is covered — never tip-equality).
+  saw_candidate=0
+  saw_verified=0
+  for tag in $(git -C "$root" tag -l "${prefix}*"); do
+    saw_candidate=1
+    # Offline SSH-signature verification: explicit -c gpg.format=ssh +
+    # allowedSignersFile so a scrubbed environment can still verify — the
+    # verify-signoff.sh:120-135 invocation, reused verbatim (no shared-lib
+    # extraction for 3 lines; Article III).
+    if git -C "$root" -c gpg.format=ssh -c "gpg.ssh.allowedSignersFile=$signers" \
+          tag -v "$tag" >/dev/null 2>&1; then
+      saw_verified=1
+      if git -C "$root" merge-base --is-ancestor "$sha" "$tag^{commit}" 2>/dev/null; then
+        printf 'release_state=validated reason=promotion-approved\n'
+        exit 0
+      fi
+    fi
+  done
+
+  # No verified containing tag. Most-specific reason wins: a genuine tag that
+  # simply doesn't cover this unit (not-contained) beats lookalike noise
+  # (bad-signature) beats silence (no-approval).
+  if [ "$saw_verified" -eq 1 ]; then
+    printf 'release_state=merged reason=not-contained\n'
+  elif [ "$saw_candidate" -eq 1 ]; then
+    printf 'release_state=merged reason=bad-signature\n'
+  else
+    printf 'release_state=merged reason=no-approval\n'
+  fi
+  exit 0
+}
+
+# Validation MODE comes from the project's working-tree config (the mode file
+# is protected-path-held per the contract); every FIELD read above/below is
+# main-tree only. Default when absent: in_session_signoff.
+project_yml=""
+if [ -f "$root/.forge/project.yml" ]; then
+  project_yml="$(cat "$root/.forge/project.yml")"
+fi
+validation_event="$(yaml_scalar "$project_yml" forge validation_event)"
+[ -n "$validation_event" ] || validation_event="in_session_signoff"
+
+# Single dispatch point — both arms of the B3 binding.
+case "$validation_event" in
+  in_session_signoff)
+    validate_in_session_signoff
+    ;;
+  promotion_approval)
+    validate_promotion_approval
+    ;;
+  *)
+    printf 'forge-release-fold: unknown validation_event: %s\n' "$validation_event" >&2
+    exit 2
+    ;;
+esac
+
+# Unreachable — every dispatch branch exits. Defensive: never fall off the
+# end into an implicit success with no verdict printed.
+exit 2

package/template/.claude/hooks/forge-slice-notify.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env sh
+# forge-slice-notify.sh <type> <payload> — the DEFAULT notify channel for
+# forge-slice-runner.sh. Delivers a §8 ping to the operator's phone via the
+# PushNotification agent tool through a thin headless `claude -p` micro-call, and
+# ALSO appends the ping to a local log so a suppressed/undelivered push is never
+# silently lost.
+#
+# The runner calls this as `${FORGE_SLICE_NOTIFY:-forge-slice-notify.sh} <type>
+# <payload>`; the whole channel is swappable via that env (tests use notify-stub.sh).
+#
+#   type     one of the §8 surface: ambiguity | irreversible | fork | budget | done
+#            (plus `halt`, the failure slice-end). The runner has already validated
+#            the type before calling; this script just delivers it.
+#   payload  the ping body. For a design `fork` it is a PATH to a sketch/mockup the
+#            operator LOOKS AT (§8) — passed through so the notification names the file.
+#
+# BEST-EFFORT by contract: this must exit 0 even when delivery is impossible (no
+# `claude` on PATH, no CLAUDE_CODE_OAUTH_TOKEN, the tool suppressed while the
+# operator is active). The runner treats a non-zero exit as a best-effort miss, not
+# a slice failure — so never hard-fail here.
+#
+# ── DEFERRED phone-delivery caveat (context.md M29, 2026-07-15) ───────────────
+# A PushNotification SENT from a DETACHED one-shot `claude -p` returns success but
+# may NOT buzz the phone — this is the Claude-app Remote-Control DEVICE-pairing
+# side (an ephemeral unpaired session), not this code. It is a known open item,
+# fixed later. The channel is swappable precisely so that fix can land without
+# touching the runner. Escalate only if delivery turns out to need Remote-Control
+# state a detached runner cannot satisfy.
+# ──────────────────────────────────────────────────────────────────────────────
+set -eu
+
+TYPE="${1:-note}"
+PAYLOAD="${2:-}"
+
+# 1) Durable local record — always, before any delivery attempt. Never lost even
+#    if the phone channel is down. Default location travels with the slice.
+LOG="${FORGE_SLICE_NOTIFY_LOG:-${FORGE_SLICE_WORK_DIR:-.}/notify.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+printf '%s\t%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$TYPE" "$PAYLOAD" >> "$LOG" 2>/dev/null || true
+
+# 2) Best-effort phone delivery via PushNotification. Skip cleanly if headless
+#    `claude` or its credential is absent (dev boxes, CI) — that is a miss, not a
+#    failure. A design fork's payload is a path, so name it in the body.
+LAUNCHER="${FORGE_SLICE_NOTIFY_LAUNCHER:-claude}"
+if command -v "$LAUNCHER" >/dev/null 2>&1 \
+   && { [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] || [ -n "${ANTHROPIC_API_KEY:-}" ]; }; then
+  _title="Forge slice: ${TYPE}"
+  case "$TYPE" in
+    fork) _body="Design fork — review the sketch: ${PAYLOAD}" ;;
+    done) _body="Slice complete. ${PAYLOAD}" ;;
+    *)    _body="${PAYLOAD}" ;;
+  esac
+  # One-shot: ask the headless agent to fire PushNotification with the title/body.
+  printf 'Send a push notification with title "%s" and body "%s". Use only the PushNotification tool; do nothing else.\n' \
+    "$_title" "$_body" \
+  | "$LAUNCHER" -p \
+      --allowedTools PushNotification \
+      --permission-mode bypassPermissions \
+      --output-format json \
+      >/dev/null 2>&1 \
+    || printf 'forge-slice-notify: push delivery best-effort miss for %s (logged locally at %s)\n' "$TYPE" "$LOG" >&2
+else
+  printf 'forge-slice-notify: no headless claude/credential — %s ping logged locally only (%s)\n' "$TYPE" "$LOG" >&2
+fi
+
+exit 0