autonomous-sdlc-harness 0.1.0

package/templates/scripts/cleanup-merged-worktrees.sh

@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+# cleanup-merged-worktrees.sh — housekeeping: remove the sibling working copy and
+# the local branch of a run whose pull request was merged and whose remote branch
+# was then deleted.
+#
+# THE TRIGGER IS AN UPSTREAM THAT IS GONE. After `git fetch --prune`, git marks a
+# local branch whose remote counterpart no longer exists as `[gone]` — visible as
+# `git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/`.
+# That is exactly the merge-the-pull-request-then-delete-the-remote-branch flow,
+# so it is the signal this sweep acts on, and it is the only one. For each such
+# branch it
+#
+#   1. removes the working copy checked out on it (`git worktree remove --force`;
+#      a failure is reported and the sweep continues, because a directory left
+#      behind is a smaller problem than a sweep that stops half-way through the
+#      set), then
+#   2. force-deletes the local branch (`git branch -D`),
+#
+# and then runs `git worktree prune` to drop the administrative records of
+# working copies whose directories are already gone.
+#
+# WHERE IT RUNS. In the MAIN checkout, always — that is where every working copy
+# and every branch of this repository is administered, and where the run registry
+# and the configuration live. The script derives that anchor rather than assuming
+# it, so it behaves identically whether it is started from the main checkout or
+# from a sibling working copy that is about to be swept away.
+#
+# THE THREE REFUSALS. It never touches
+#
+#   * a PROTECTED branch — the set resolved at run time from this repository's
+#     `harness.config.json` (`protectedBranches`, or that key's schema default,
+#     unioned with `defaultBranch`), through lib/harness-run-lib.sh. There is no
+#     list of branch names in this file: one written here would delete branches
+#     an adopter had protected, the moment their configuration named anything
+#     else;
+#   * the branch the MAIN checkout itself has checked out, nor the main
+#     checkout's own directory;
+#   * a branch with an ACTIVE RUN — one whose record in the run registry
+#     (`<state_dir>/autonomous_logs/registry.json`, shaped
+#     `{"runs": {"<branch>": {"status": …}}}`) says `running`, `parked` or
+#     `paused`. All three own a working copy the watcher will come back to: a
+#     parked run is waiting for a clarification answer and a paused one for a
+#     RESUME sentinel, and `worktree remove --force` would discard the pause
+#     note the resumed engine is pointed at.
+#
+# CAVEAT: `: gone` + force-delete also catches an ABANDONED branch whose remote
+# was deleted WITHOUT merging — its unmerged local commits would be lost. For a
+# strict merge-then-delete-remote flow this is a non-issue. Use --dry-run to
+# preview.
+#
+# `--dry-run` IS THE PREVIEW, AND IT DELETES NOTHING. It reports the branch (and
+# the working copy) each decision would remove; no branch is deleted, no working
+# copy removed, and it does not even `worktree prune`. It is NOT read-only: the
+# `fetch --prune` that establishes which upstreams are gone runs first either
+# way, so remote-tracking refs for deleted upstreams are removed and FETCH_HEAD
+# is written. Preview the decisions, not the repository's ref state.
+#
+# FAIL CLOSED, AND HERE THAT MEANS DELETING NOTHING. This is the most destructive
+# script in the set — `git branch -D` and `git worktree remove --force` are not
+# recoverable from this side — so every input it cannot resolve ends the run
+# instead of being worked around:
+#
+#   * the shared library, or `<repo_root>/harness.config.json`, cannot be read
+#     (absent, unreadable, invalid JSON, more than one document, no
+#     `defaultBranch`, or `jq` missing or older than 1.5) — it cannot prove any
+#     branch is unprotected;
+#   * the registry file is present and cannot be read as a registry (unreadable,
+#     invalid JSON, or no `.runs` wrapper) — it cannot prove any branch is idle.
+#     A registry that is simply ABSENT is a different answer and not an error: a
+#     repository the watcher has never run in has no registry, and no active run
+#     either. But a registry that is there in a shape this cannot enumerate is
+#     refused rather than read as "nothing is running", because that misreading
+#     is a deleted branch with a run still writing to it;
+#   * the protected-branch answer for a specific branch comes back unresolvable
+#     mid-sweep.
+#
+# Each of those prints one line and exits 0 having deleted nothing. Exit 0
+# because this sweep is housekeeping invoked from a loop that must keep running,
+# and a refusal is a successful refusal.
+#
+# WHO RUNS IT. The watcher, on its own schedule, and a person by hand. NEVER a
+# dispatched agent: the script-allowlist guard withholds the permit rather than
+# granting one (its basename is on that guard's deny list, and being on it means
+# the guard stays silent), and the generated permission profile emits no rule for
+# this script either — so an agent that tries to run it gets a prompt it cannot
+# answer, never a permit. Nothing about that is negotiable — an agent asked to
+# change one file has no business deleting branches.
+#
+# Usage: cleanup-merged-worktrees.sh [--dry-run]
+#   --dry-run   report what would be removed; remove nothing
+#
+# Exit map a caller can switch on:
+#
+#   0  the sweep ran, or refused and deleted nothing (the message says which)
+#   1  usage error — an unrecognized or extra argument. Nothing was read and
+#      nothing was deleted; in particular a misspelled `--dry-run` is refused
+#      here rather than silently becoming a real sweep
+#
+# REPRO — reproduce any decision by hand, against a throwaway fixture:
+#
+#   w=$(mktemp -d); b="$w/origin.git"; git init -q --bare "$b"
+#   d="$w/demo"; git init -q -b trunk "$d"; git -C "$d" remote add origin "$b"
+#   printf '%s' '{"version":1,"projectName":"demo","defaultBranch":"trunk","protectedBranches":["trunk","release/*"],"stateDir":"sdlc-harness/","layers":[],"commands":{}}' > "$d/harness.config.json"
+#   mkdir -p "$d/scripts/lib"   # copy this script + lib/ there
+#   git -C "$d" add -A && git -C "$d" commit -qm seed
+#   git -C "$d" push -q -u origin trunk
+#   for r in feat_gone feat_live release/1.0; do git -C "$d" branch "$r"; \
+#     git -C "$d" push -q -u origin "$r"; done
+#   git -C "$d" worktree add -q "$w/demo-feat_gone" feat_gone
+#   git -C "$b" branch -q -D feat_gone; git -C "$b" branch -q -D release/1.0
+#
+#   preview       bash "$d/scripts/cleanup-merged-worktrees.sh" --dry-run
+#                 -> names feat_gone and its working copy; `git -C "$d" branch`
+#                    is unchanged and "$w/demo-feat_gone" is still there
+#   sweep         bash "$d/scripts/cleanup-merged-worktrees.sh"
+#                 -> "$w/demo-feat_gone" removed and feat_gone deleted;
+#                    feat_live untouched (its upstream is not gone) and
+#                    release/1.0 untouched (protected, though it IS gone)
+#   active run    mkdir -p "$d/sdlc-harness/autonomous_logs"
+#                 printf '%s' '{"runs":{"feat_gone":{"status":"running"}}}' \
+#                   > "$d/sdlc-harness/autonomous_logs/registry.json"
+#                 -> the skip line for feat_gone; nothing deleted (same with
+#                    "parked" and "paused")
+#   unresolvable  printf 'x' > "$d/harness.config.json"
+#                 -> one line, exit 0, nothing deleted
+#   offline       git -C "$d" remote set-url origin /nonexistent.git
+#                 -> the fetch message, exit 0, nothing deleted
+
+set -uo pipefail
+
+# The library is reached by a path computed from this script's own location — no
+# session root and no runtime-substituted token is assumed. Not finding it is a
+# refusal: without it there is no protected set to check a branch against.
+hr_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/harness-run-lib.sh"
+if [ ! -r "$hr_lib" ]; then
+  echo "cleanup-merged-worktrees.sh: cannot read '$hr_lib' — refusing to delete anything"
+  exit 0
+fi
+# shellcheck source=lib/harness-run-lib.sh
+. "$hr_lib"
+
+dry_run=0
+case "${1:-}" in
+  --dry-run)
+    dry_run=1
+    shift
+    ;;
+  '') ;;
+  *)
+    echo "cleanup-merged-worktrees.sh: unrecognized argument '$1'" >&2
+    echo "  usage: cleanup-merged-worktrees.sh [--dry-run]" >&2
+    exit 1
+    ;;
+esac
+if [ "$#" -gt 0 ]; then
+  echo "cleanup-merged-worktrees.sh: unexpected extra arguments" >&2
+  echo "  usage: cleanup-merged-worktrees.sh [--dry-run]" >&2
+  exit 1
+fi
+
+# --- Anchors. Derived, never remembered: this copy of the script may be sitting
+# in the main checkout or in a sibling working copy of the same repository.
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+top="$(hr_repo_root "$script_dir")" || top=""
+if [ -z "$top" ]; then
+  echo "cleanup-merged-worktrees.sh: '$script_dir' is not inside a git repository — refusing to delete anything"
+  exit 0
+fi
+
+# The sweep administers working copies and branches, so it runs in the MAIN
+# checkout. Unlike its siblings this one does NOT fall back to the checkout it
+# was started from: if the main-checkout probe does not answer, the working-copy
+# enumeration below cannot be trusted either, and the closed outcome is to stop.
+main_repo="$(hr_main_repo "$top")" || main_repo=""
+if [ -z "$main_repo" ]; then
+  echo "cleanup-merged-worktrees.sh: could not determine the main checkout of '$top' — refusing to delete anything"
+  exit 0
+fi
+
+# Warm the library's per-process cache once, unsubstituted, and make the
+# fail-closed decision here rather than letting each reader fail separately.
+cfg_status=0
+hr_config_load "$main_repo" || cfg_status=$?
+if [ "$cfg_status" -ne 0 ]; then
+  echo "cleanup-merged-worktrees.sh: cannot resolve '$main_repo/harness.config.json' — refusing to delete anything"
+  echo "  (no configuration there, invalid JSON, more than one document, no defaultBranch, or jq missing/older than 1.5)"
+  exit 0
+fi
+
+# --- The active-run set. A HARD PRECONDITION, not a best-effort read: the
+# question it answers is whether a branch about to be force-deleted has a run
+# writing to it.
+registry="$(hr_state_path "$main_repo" autonomous_logs/registry.json)" || registry=""
+if [ -z "$registry" ]; then
+  echo "cleanup-merged-worktrees.sh: could not derive the run registry path — refusing to delete anything"
+  exit 0
+fi
+
+active=""
+if [ -e "$registry" ]; then
+  if [ ! -r "$registry" ]; then
+    echo "cleanup-merged-worktrees.sh: '$registry' is not readable — refusing to delete anything"
+    exit 0
+  fi
+  # Enumerated through the `.runs` wrapper the whole flow writes and reads. A
+  # document without it is a registry this cannot enumerate, so `jq` fails and
+  # the refusal below fires — which is the point: reading such a file as "no
+  # active runs" would delete a branch a run is still working on.
+  if ! active="$(jq -r '.runs | to_entries[] | select(.value.status == "running" or .value.status == "parked" or .value.status == "paused") | .key' "$registry" 2>/dev/null)"; then
+    echo "cleanup-merged-worktrees.sh: '$registry' could not be read as a run registry — refusing to delete anything"
+    exit 0
+  fi
+fi
+
+# Refresh remote-tracking refs so a deleted upstream becomes `[gone]`. A failed
+# fetch (offline, or an unreachable remote) skips this round rather than sweeping
+# on stale tracking information, which would report every branch as gone.
+if ! git -C "$main_repo" fetch --prune --quiet 2>/dev/null; then
+  echo "cleanup-merged-worktrees.sh: fetch --prune failed (offline?); skipping this round"
+  exit 0
+fi
+
+current_branch="$(hr_current_branch "$main_repo")"
+
+# The working copy checked out on <branch>, from the porcelain listing. Parsed
+# line-wise rather than by whitespace fields, because a working copy's path may
+# contain spaces. Prints nothing when there is none.
+worktree_for_branch() {
+  local branch="${1-}" list line current=""
+  [ -n "$branch" ] || return 0
+  list="$(git -C "$main_repo" worktree list --porcelain 2>/dev/null)" || return 0
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) current="${line#worktree }" ;;
+      "branch refs/heads/$branch")
+        printf '%s\n' "$current"
+        return 0
+        ;;
+    esac
+  done <<EOF
+$list
+EOF
+  return 0
+}
+
+# One record per local branch as `<name><TAB><upstream track>`; the tab keeps the
+# two apart without splitting on whitespace.
+gone_list="$(git -C "$main_repo" for-each-ref --format='%(refname:short)%09%(upstream:track)' refs/heads/ 2>/dev/null)" || gone_list=""
+
+nl="
+"
+tab=$'\t'
+cleaned=0
+
+# Fed by a here-document rather than a pipeline, so `cleaned` is counted in THIS
+# shell — a `|` would run the loop in a subshell and the total would always be 0.
+while IFS= read -r record; do
+  [ -n "$record" ] || continue
+  branch="${record%%"$tab"*}"
+  track="${record#*"$tab"}"
+  [ -n "$branch" ] || continue
+  [ "$track" = "[gone]" ] || continue
+
+  hr_branch_is_protected "$main_repo" "$branch"
+  protected=$?
+  case "$protected" in
+    0) continue ;;
+    2)
+      # The configuration resolved a moment ago, so this is it changing under a
+      # running sweep. Stop; do not fall through to a delete.
+      echo "cleanup-merged-worktrees.sh: cannot tell whether '$branch' is protected — stopping; nothing further deleted"
+      exit 0
+      ;;
+  esac
+
+  if [ "$branch" = "$current_branch" ]; then
+    continue
+  fi
+
+  # Newline-delimited membership: the registry enumeration returns one branch per
+  # line, so both the haystack and the needle are wrapped in newlines. Matching
+  # on spaces instead would only ever recognize the first and last entry.
+  case "$nl$active$nl" in
+    *"$nl$branch$nl"*)
+      echo "cleanup-merged-worktrees.sh: skip '$branch' (active run)"
+      continue
+      ;;
+  esac
+
+  wt="$(worktree_for_branch "$branch")"
+
+  if [ "$dry_run" -eq 1 ]; then
+    if [ -n "$wt" ]; then
+      echo "cleanup-merged-worktrees.sh: [dry-run] would delete branch '$branch' and remove worktree $wt"
+    else
+      echo "cleanup-merged-worktrees.sh: [dry-run] would delete branch '$branch'"
+    fi
+    continue
+  fi
+
+  if [ -n "$wt" ] && [ "$wt" != "$main_repo" ]; then
+    # git's own message is captured and reported rather than printed raw, so a
+    # failure names the directory a person now has to remove by hand.
+    if err="$(git -C "$main_repo" worktree remove --force "$wt" 2>&1 >/dev/null)"; then
+      echo "cleanup-merged-worktrees.sh: removed worktree $wt"
+    else
+      echo "cleanup-merged-worktrees.sh: FAILED to remove worktree $wt: ${err:-no error output} — the directory may be left behind; remove it by hand"
+    fi
+  fi
+
+  if git -C "$main_repo" branch -D "$branch" >/dev/null 2>&1; then
+    echo "cleanup-merged-worktrees.sh: deleted merged branch '$branch'"
+    cleaned=$((cleaned + 1))
+  else
+    echo "cleanup-merged-worktrees.sh: could not delete branch '$branch' — left in place"
+  fi
+done <<EOF
+$gone_list
+EOF
+
+if [ "$dry_run" -eq 0 ]; then
+  git -C "$main_repo" worktree prune 2>/dev/null || true
+  if [ "$cleaned" -gt 0 ]; then
+    echo "cleanup-merged-worktrees.sh: $cleaned merged branch(es) removed"
+  fi
+fi
+exit 0

package/templates/scripts/commit-on-branch.sh

@@ -0,0 +1,288 @@
+#!/usr/bin/env bash
+# commit-on-branch.sh — the deterministic commit wrapper every unattended commit
+# point calls: stage exactly the paths it was given, refuse a branch this
+# repository's own configuration protects, and commit with the message supplied
+# as ordinary positional arguments.
+#
+# WHY A WRAPPER EXISTS AT ALL. An unattended run cannot answer a permission
+# prompt, so a command that draws one is a silent stall rather than a refusal.
+# `git commit -m "$(…)"` draws one twice over: a command carrying a shell
+# expansion (`$VAR` / `${…}` / `$(…)`) cannot be matched statically, so it
+# reaches the commit branch-guard (`plugin/hooks/git-commit-branch-guard.sh`),
+# which is fail-closed and answers `ask` for anything it could not read — and a
+# `$(…)` in the message defeats a literal allow entry as well. An invocation of
+# a SCRIPT PATH has neither problem: `bash <scripts_dir>/commit-on-branch.sh …`
+# is allow-listed in three literal forms by the generated permission profile,
+# is auto-allowed by the script-allowlist guard (a script resolving under the
+# configured scripts directory whose basename is not on that guard's deny list,
+# in a command carrying none of `$(…)`, a backtick, `|`, `<`, a braced form
+# other than a bare `${IDENT}`, or a `>` that is neither a descriptor
+# duplication (`2>&1`, `>&2`, `2>&-`) nor a redirection to the literal
+# `/dev/null` — which is what the rule below enforces),
+# and is never matched by the commit guard's parser — even when the path or the
+# arguments carry expansions. So the caller's command line carries NO heredoc
+# and NO `$(…)`: the subject and every body paragraph are ordinary positional
+# arguments and this script builds the commit from repeated `-m` flags itself.
+#
+# SAFETY-CRITICAL CONSEQUENCE. Not reaching the commit branch-guard also means
+# not reaching its protected-branch refusal, so this script MUST make that
+# decision itself — and it makes it from `<repo_root>/harness.config.json` at
+# run time, through `lib/harness-run-lib.sh`, never from a list of branch names
+# written into this file. A remembered list enforces the wrong set the moment
+# `protectedBranches` changes, and enforces nothing at all in a repository whose
+# integration branch is named something else. The library answers three states —
+# protected, not protected, unresolvable — and all three are closed here.
+#
+# LOUD-FAILURE CONTRACT (the KEY difference from push-branch.sh). push-branch.sh
+# makes every failure non-fatal because a stale remote is tolerable. A commit
+# caller cannot tolerate that ambiguity: if a commit did NOT land, the caller
+# must NOT proceed as if it did. A non-git directory, a detached HEAD, a
+# configuration that cannot be resolved, a protected-branch refusal and a
+# git-level hook failure are therefore all non-zero exits. Exit-code map a
+# caller can switch on:
+#
+#   0  commit landed (the new short SHA is printed to stdout)
+#   1  usage error / non-git directory / detached HEAD / the configuration could
+#      not be resolved / `git commit` failed (a hook, or any commit-time check)
+#   2  protected-branch refusal (no staging, no commit)
+#   3  nothing to commit (the paths staged cleanly and produced no staged
+#      change) — a DISTINCT, non-crashing status so a caller can tell "nothing
+#      staged" apart from a protected-branch refusal or a hook failure
+#
+# WHAT IT NEVER DOES. It never pushes (that is push-branch.sh, called as a
+# SEPARATE statement — an `if …; then push; fi` block is a compound the guards
+# do not cover and stalls an unattended run). It never flips a plan checkbox:
+# callers own that. It never stages anything it was not given — no `git add -A`,
+# no `git add .`. It never passes `--no-verify` or any other hook-skip flag, and
+# it never retries a failed commit.
+#
+# STAGING POLICY, AND THE ONE TRAP IN IT. Only the explicit paths passed before
+# `--` are staged, one `git add -- <path>` each. A path that does not exist is
+# skip-with-warning rather than a hard error, and that tolerance is what lets
+# callers pass their paths UNCONDITIONALLY: an optional-but-absent one (an empty
+# per-finding folder, say) must not fail the commit, and a caller-side
+# `if [ -d … ]; then` existence check would reintroduce the stall described
+# under WHY A WRAPPER EXISTS AT ALL — a shell conditional cannot be matched
+# statically, so it reaches the fail-closed guards and an unattended run cannot
+# answer the prompt it draws. Callers were deliberately stripped of those
+# checks; do not restore one. THE TRAP: a path that was DELETED does not
+# exist either, so passing the exact deleted path stages nothing and the
+# deletion is silently left out of the commit. Pass the PARENT DIRECTORY of a
+# deletion instead — `git add -- <dir>` stages the removal. This is source
+# behaviour carried across deliberately rather than fixed: the existence check
+# is what keeps an absent optional path from failing a commit, and it is checked
+# against `<repo_top>/<path>` — the same base `git -C <top> add` resolves
+# against — so a path is staged if and only if it is the one git would resolve.
+#
+# MESSAGE ARGUMENTS, AND THE BYTES ONE MAY NOT CARRY. The subject and every body
+# line arrive as ordinary shell arguments, so none of them may carry `$(…)`, a
+# backtick, `|`, `>`, `<`, or a braced expansion other than a bare `${IDENT}`.
+# Two independent reasons, either one fatal on its own. THE SHELL: inside the
+# caller's double quotes `$(…)` and a backtick are substituted before this
+# script is reached, and any `$` spelling is expanded — so a `$`, a backtick or
+# a placeholder meant as TEXT is not text by the time it lands. THE GUARD: the
+# script-allowlist guard (`autonomous-script-allowlist-guard.sh`, shipped with the
+# plugin)
+# scans the WHOLE command string for `$(…)`, a backtick, `|`, `<`, a braced form
+# other than a bare `${IDENT}`, and a `>` that is neither a descriptor
+# duplication (`2>&1`, `>&2`, `2>&-`) nor a redirection to the literal
+# `/dev/null`, and silences the invocation on a match, which is the permission
+# prompt described under WHY A WRAPPER EXISTS AT ALL and, unattended, a stall.
+# That scanned set is the set above minus the two `>` shapes a MESSAGE cannot
+# be, which is why the rule here stays whole-byte for `>`. The guard reads the
+# raw string, so quoting and escaping rescue nothing: `|`, `<` and a prose `>`
+# are inert to the shell inside quotes and still silence the command, and an
+# escaped backtick matches exactly as a bare one does. The ONE admitted
+# expansion is a bare `${IDENT}`,
+# bought back by the guard's narrowed `${` arm because the corpus's canonical
+# subject spells its branch token that way — it is allowed AND expanded, so pass
+# it only when expansion is what you want. THIS SCRIPT ENFORCES NONE OF THIS: it
+# validates no message, rewrites no message, and builds the commit from repeated
+# `-m` flags exactly as given. The constraint binds the CALLER, and the caller's
+# own contract states what to do with a title that cannot satisfy it.
+#
+# Usage: commit-on-branch.sh [--repo <repo-dir>] <path>... -- <subject> [<body-line>...]
+#   --repo <repo-dir>  worktree/repository to operate in (default: $PWD)
+#   <path>...          explicit paths to stage (before `--`); missing paths warn+skip
+#   --                 separates the stage-path list from the message lines
+#   <subject>          first token after `--` — the commit subject (`-m`); see
+#                      MESSAGE ARGUMENTS for the bytes it may not carry
+#   <body-line>...     each remaining token — one additional `-m` body paragraph,
+#                      under that same constraint
+#
+# REPRO — reproduce any decision by hand, against a throwaway fixture:
+#
+#   d=$(mktemp -d); git -C "$d" init -q -b feat_x
+#   printf '%s' '{"version":1,"defaultBranch":"trunk","protectedBranches":["trunk","release/*"],"stateDir":"sdlc-harness/","layers":[],"commands":{}}' > "$d/harness.config.json"
+#   printf 'x\n' > "$d/f.txt"
+#
+#   ordinary branch   commit-on-branch.sh --repo "$d" f.txt -- "feat: x" "body"
+#                     -> exit 0, prints the new short SHA
+#                     re-run with nothing changed                     -> exit 3
+#   protected branch  git -C "$d" checkout -q -b trunk; same call     -> exit 2,
+#                     and `git -C "$d" status --porcelain` is unchanged
+#   not in the set    git -C "$d" checkout -q -b main; same call      -> exit 0
+#                     (the set is configured, not remembered)
+#   unresolvable      printf 'x' > "$d/harness.config.json"; same call -> exit 1,
+#                     no commit
+#   deleted path      git -C "$d" rm -q f.txt; passing `f.txt`  -> the deletion is
+#                     NOT staged; pass its parent directory instead
+
+set -uo pipefail
+
+# The library is reached by a path computed from this script's own location, so
+# a copy that was moved with its `lib/` still finds it, and no session root or
+# runtime-substituted token is assumed.
+hr_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/harness-run-lib.sh"
+if [ ! -r "$hr_lib" ]; then
+  echo "commit-on-branch.sh: cannot read '$hr_lib' — refusing to commit" >&2
+  exit 1
+fi
+# shellcheck source=lib/harness-run-lib.sh
+. "$hr_lib"
+
+repo_dir="$PWD"
+
+# --- Parse args: optional --repo, then <path>... up to `--`, then message lines.
+paths=()
+msgs=()
+saw_sep=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --repo)
+      if [ "$#" -lt 2 ]; then
+        echo "commit-on-branch.sh: --repo requires a directory argument" >&2
+        exit 1
+      fi
+      repo_dir="$2"
+      shift 2
+      ;;
+    --)
+      saw_sep=1
+      shift
+      break
+      ;;
+    *)
+      paths+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [ "$saw_sep" -ne 1 ]; then
+  echo "commit-on-branch.sh: missing '--' separator before the commit message" >&2
+  echo "  usage: commit-on-branch.sh [--repo <dir>] <path>... -- <subject> [<body-line>...]" >&2
+  exit 1
+fi
+
+# Everything after `--` is the message: the first token is the subject, the rest
+# are additional body paragraphs.
+while [ "$#" -gt 0 ]; do
+  msgs+=("$1")
+  shift
+done
+
+if [ "${#msgs[@]}" -eq 0 ]; then
+  echo "commit-on-branch.sh: no commit subject after '--'" >&2
+  exit 1
+fi
+
+# Resolve the repository top. A non-git directory is a loud non-zero error (a
+# commit caller cannot tolerate "not a repository" the way a best-effort push
+# can).
+top="$(hr_repo_root "$repo_dir")"
+if [ -z "$top" ]; then
+  echo "commit-on-branch.sh: '$repo_dir' is not a git repository — refusing to commit" >&2
+  exit 1
+fi
+
+# Current branch. Empty => detached HEAD => loud refusal, no staging, no commit.
+branch="$(hr_current_branch "$top")"
+if [ -z "$branch" ]; then
+  echo "commit-on-branch.sh: detached HEAD — refusing to commit" >&2
+  exit 1
+fi
+
+# The protected-branch decision, from this repository's configuration. Called
+# unsubstituted so the library's per-process cache is warmed here and the
+# `$(hr_protected_patterns …)` in the refusal message below re-reads nothing.
+hr_branch_is_protected "$top" "$branch"
+protected=$?
+case "$protected" in
+  0)
+    # Name the resolved set as well as the branch: the adopter configured it, so
+    # a refusal that only names the branch cannot be acted on.
+    patterns="$(hr_protected_patterns "$top")" || patterns=""
+    protected_set=""
+    while IFS= read -r pattern; do
+      [ -n "$pattern" ] || continue
+      if [ -z "$protected_set" ]; then
+        protected_set="$pattern"
+      else
+        protected_set="$protected_set $pattern"
+      fi
+    done <<EOF
+$patterns
+EOF
+    echo "commit-on-branch.sh: branch '$branch' is protected — refusing to commit" >&2
+    echo "  protected set (from harness.config.json): $protected_set" >&2
+    exit 2
+    ;;
+  2)
+    # Fail closed. The configuration is what says which branches are protected,
+    # so a configuration that cannot be read is a branch that cannot be judged —
+    # and committing on it would be exactly the mutation this wrapper exists to
+    # gate.
+    echo "commit-on-branch.sh: cannot resolve '$top/harness.config.json' — refusing to commit" >&2
+    echo "  (no configuration there, invalid JSON, more than one document, no defaultBranch, or jq missing/older than 1.5)" >&2
+    exit 1
+    ;;
+esac
+
+# Stage ONLY the explicit paths — never `git add -A` / `git add .`. A missing
+# path is skip-with-warning, not a hard error. The count guard is required: on
+# bash 3.2 (the floor) `"${paths[@]}"` on an EMPTY array under `set -u` raises
+# `unbound variable` instead of expanding to nothing, which would abort a legal
+# zero-path call before it could reach the nothing-to-commit exit 3.
+if [ "${#paths[@]}" -gt 0 ]; then
+  for p in "${paths[@]}"; do
+    # The existence check MUST use the same base as the staging command below
+    # (`git -C "$top" add` resolves $p relative to $top, not the caller's cwd).
+    # Checking `$top/$p` only — never a cwd-relative $p — guarantees a path is
+    # staged if and only if it is the same path `git add` will resolve.
+    if [ ! -e "$top/$p" ]; then
+      echo "commit-on-branch.sh: path '$p' does not exist under '$top' — skipping" >&2
+      continue
+    fi
+    if ! git -C "$top" add -- "$p"; then
+      echo "commit-on-branch.sh: 'git add -- $p' failed — no commit made" >&2
+      exit 1
+    fi
+  done
+fi
+
+# Nothing staged => a distinct, dedicated non-zero status, so a caller can tell
+# this apart from a protected-branch refusal or a hook failure.
+if git -C "$top" diff --cached --quiet; then
+  echo "commit-on-branch.sh: nothing to commit" >&2
+  exit 3
+fi
+
+# Build the commit from repeated -m flags, WITHOUT `--no-verify` or any other
+# hook-skip flag, so the repository's own commit hooks still run.
+commit_args=()
+for m in "${msgs[@]}"; do
+  commit_args+=(-m "$m")
+done
+
+if ! git -C "$top" commit "${commit_args[@]}"; then
+  # A hook (or any other commit-time check) failed. Surface it loudly; do NOT
+  # retry, do NOT add --no-verify, do NOT leave a partial or bypassing commit.
+  echo "commit-on-branch.sh: 'git commit' failed (see output above) — no commit made" >&2
+  exit 1
+fi
+
+sha="$(git -C "$top" rev-parse --short HEAD)"
+echo "commit-on-branch.sh: committed $sha on $branch"
+exit 0