autonomous-sdlc-harness 0.6.2 → 0.6.3

package/templates/scripts/lib/harness-run-lib.sh

@@ -5,7 +5,9 @@
 # routes an inbox filename to its engine and branch (`hr_inbox_route_var`),
 # derives a branch name from a title (`hr_derive_branch`), judges whether a
 # path lies strictly inside the state directory's scratch directory
-# (`hr_scratch_path_var`), places a dropped
+# (`hr_scratch_path_var`), answers whether the progress comment is on
+# (`hr_progress_comments`) and which main phases a flow-progress ledger records
+# as through (`hr_ledger_phases`), places a dropped
 # artifact in a working copy and commits and pushes it, and derives the
 # anchors (main checkout, work root, worktree directory, repo slug,
 # state-dir paths) the scripts would otherwise each re-derive slightly
@@ -87,7 +89,10 @@
 #      file is ever removed.
 #   4. THE ARTIFACT PLACEMENT writes one artifact into a working copy. Fence:
 #      the caller-named `<worktree>/<rel>`, its parent directories and that
-#      path's index entry, plus whatever the two caller-named wrappers do.
+#      path's index entry, plus whatever the two caller-named wrappers do, plus
+#      one write of its own: `hr_push_landed`'s fetch, which force-writes
+#      `refs/remotes/origin/<branch>` in `<worktree>`, made only after a failed
+#      landing, to name the commit the remote moved to.
 #      Written only by `hr_place_artifact`, `hr_commit_placed` and
 #      `hr_push_landed`.
 #
@@ -96,6 +101,11 @@
 #   HR_REMOTE_WORKFLOW_RUN_FILE mirrors  WORKFLOW_RUN_FILE
 #   HR_REMOTE_STATE_ARTIFACT    mirrors  STATE_ARTIFACT_NAME
 #
+# MIRROR OF `plugin/instructions/autonomous_pause_and_ledger.md` →
+# `### 1.3 Templates`, which owns the flow-progress ledger's two header forms
+# and its entry ids; `hr_ledger_phases` codes both, so renaming an id or a
+# header form there is an edit here.
+#
 # A caller that calls no `hr_lane_*`, `hr_registry_init`, `hr_registry_set`,
 # `hr_remote_record_init`, `hr_registry_lock`, `hr_registry_unlock`, `hr_remote_status_write`,
 # `hr_remote_bundle_write`, `hr_remote_bundle_restore`, `hr_remote_move_aside`, `hr_place_artifact`,
@@ -600,10 +610,11 @@ hr_config_load() {
   # which is what lets an explicitly EMPTY list read as a configured set rather
   # than as an absent one.
   #
-  # A `phases.*` or `docs.retrieval` value that is not a boolean is emitted as
-  # `invalid`, so the string `"true"` — which `tostring` would otherwise make
-  # indistinguishable from `true` — reaches `hr_phase_enabled` or
-  # `hr_docs_retrieval_applies` as a value it refuses (2).
+  # A `phases.*`, `docs.retrieval` or `execution.progressComments` value that is
+  # not a boolean is emitted as `invalid`, so the string `"true"` — which
+  # `tostring` would otherwise make indistinguishable from `true` — reaches
+  # `hr_phase_enabled`, `hr_docs_retrieval_applies` or `hr_progress_comments` as
+  # a value it refuses (2).
   out=$(jq -n -r '
     def s($k; $v):
       if $v == null then empty
@@ -638,6 +649,8 @@ hr_config_load() {
       s("phases.qa";             try (.phases.qa     | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("phases.docs";           try (.phases.docs   | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("execution.target";      try .execution.target     catch null),
+      s("execution.progressComments";
+        try (.execution.progressComments | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("docs.retrievalBackend"; try .docs.retrievalBackend catch null),
       s("docs.retrieval";        try (.docs.retrieval | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("forge";                 try .forge                catch null),
@@ -927,6 +940,107 @@ hr_forge() {
   return 2
 }
 
+# `execution.progressComments` — whether a remote run keeps its progress
+# comment on the pull request. THE ONE READER OF THE KEY IN THIS FAMILY; a
+# script that needs it calls this. PRINTS NOTHING: the answer is the status, as
+# `hr_phase_enabled`'s is, except that an absent key is the schema default
+# `true`. 0 = `true` or absent; 1 = `false`; 2 = the configuration is
+# unresolvable or the value is not a boolean — refused rather than guessed about.
+hr_progress_comments() {
+  local root="${1-}"
+  hr_config_load "$root" || return 2
+  hr_cfg_scalar_var "execution.progressComments" || return 0
+  case "$HR_CFG_VALUE" in
+    true) return 0 ;;
+    false) return 1 ;;
+  esac
+  return 2
+}
+
+# ---------------------------------------------------------------------------
+# The flow-progress ledger — which of a run's four main phases it records as
+# through. A mirror of the plugin's ledger templates; see the header.
+# ---------------------------------------------------------------------------
+
+# 0 when every id after <settled> appears in <settled>, a space-delimited list
+# with a leading and trailing space; 1 otherwise.
+hr_ledger_all_settled() {
+  local settled="${1-}" id
+  shift
+  for id in "$@"; do
+    case "$settled" in
+      *" $id "*) ;;
+      *) return 1 ;;
+    esac
+  done
+  return 0
+}
+
+# Print `<engine> <round> <phase1> <phase2> <phase3> <phase4>` for the ledger at
+# <ledger_file> and return 0 — `<engine>` is `task` or `user_review`, `<round>`
+# the header's round or `-` for the task engine, each phase `done` or `pending`.
+# Return 1, printing nothing, when the file is missing or unreadable or its first
+# line is not a task-engine or user-review-engine header: any other ledger has
+# no phases to report.
+#
+# A phase is `done` when every id of its set is `[x]` or `[-]` (skipped before
+# the run began). An id absent from the file is NOT settled, so a malformed
+# ledger reads as `pending`, never as `done`. Phase 3 groups every end-of-branch
+# review with its fixes, QA and the run gates.
+hr_ledger_phases() {
+  local file="${1-}" line first=1 engine="" round="-" settled=" " rest id
+  local p1 p2 p3 p4 s1 s2 s3 s4
+  [ -n "$file" ] && [ -f "$file" ] && [ -r "$file" ] || return 1
+  while IFS= read -r line || [ -n "$line" ]; do
+    if [ "$first" -eq 1 ]; then
+      first=0
+      case "$line" in
+        *"(engine: task)"*)
+          engine="task"
+          ;;
+        *"(engine: user_review, round "*")"*)
+          engine="user_review"
+          round=${line#*"(engine: user_review, round "}
+          round=${round%%")"*}
+          case "$round" in
+            ''|*[!0-9]*) return 1 ;;
+          esac
+          ;;
+        *) return 1 ;;
+      esac
+      continue
+    fi
+    case "$line" in
+      "- [x] "*|"- [-] "*) ;;
+      *) continue ;;
+    esac
+    rest=${line#"- ["?"] "}
+    id=${rest%% *}
+    id=${id%.}
+    if [ -n "$id" ]; then settled="$settled$id "; fi
+  done < "$file"
+  [ -n "$engine" ] || return 1
+
+  if [ "$engine" = "task" ]; then
+    p1="P1 P2 P3"
+    p2="A"
+    p3="A1.5g A1.5f A2g A2f Bg Bm C C2g C2m C2f E G"
+    p4="D"
+  else
+    p1="R1 R2"
+    p2="R3"
+    p3="R4 RG"
+    p4="R5"
+  fi
+  # Unquoted on purpose: each set is a fixed list of space-free ids.
+  if hr_ledger_all_settled "$settled" $p1; then s1="done"; else s1="pending"; fi
+  if hr_ledger_all_settled "$settled" $p2; then s2="done"; else s2="pending"; fi
+  if hr_ledger_all_settled "$settled" $p3; then s3="done"; else s3="pending"; fi
+  if hr_ledger_all_settled "$settled" $p4; then s4="done"; else s4="pending"; fi
+  printf '%s %s %s %s %s %s\n' "$engine" "$round" "$s1" "$s2" "$s3" "$s4"
+  return 0
+}
+
 # Whether the docs phase's retrieval step runs: `phases.docs` and
 # `docs.retrieval` both `true`. The shell mirror of `cli/src/config/model.ts` →
 # `retrievalApplies`: change the predicate there and here together. PRINTS
@@ -1865,17 +1979,31 @@ hr_commit_placed() {
   return 0
 }
 
-# hr_push_landed <push_wrapper> <worktree> <branch> — run <push_wrapper>, then 0
-# only when `HEAD` and `refs/remotes/origin/<branch>` both resolve and are
-# equal; 1 otherwise. `push-branch.sh` exits 0 on every path, so its status is
-# never the answer.
+# hr_push_landed <push_wrapper> <worktree> <branch> — run <push_wrapper>, then
+# answer from refs alone, because `push-branch.sh` exits 0 on every path:
+#   0  landed: `HEAD` and `refs/remotes/origin/<branch>` resolve and are equal,
+#      before or after that fetch;
+#   2  the remote moved: after the failed landing, a fetch of
+#      `refs/remotes/origin/<branch>` succeeds and it names a commit that is not
+#      an ancestor of `HEAD`. `HR_PUSH_REMOTE_TIP` is set to its short id;
+#   1  anything else — the push was refused, the fetch failed, or a ref did not
+#      resolve.
+# It never retries and never rebases; the retry is `push-branch.sh`'s.
 hr_push_landed() {
   local wrapper="${1-}" worktree="${2-}" branch="${3-}" head upstream
+  HR_PUSH_REMOTE_TIP=""
   [ -n "$wrapper" ] && [ -n "$worktree" ] && [ -n "$branch" ] || return 1
   "$wrapper" "$worktree"
   head=$(git -C "$worktree" rev-parse --verify --quiet HEAD) || return 1
+  [ -n "$head" ] || return 1
+  upstream=$(git -C "$worktree" rev-parse --verify --quiet "refs/remotes/origin/$branch") \
+    && [ "$head" = "$upstream" ] && return 0
+  git -C "$worktree" fetch --quiet origin "+refs/heads/$branch:refs/remotes/origin/$branch" || return 1
   upstream=$(git -C "$worktree" rev-parse --verify --quiet "refs/remotes/origin/$branch") || return 1
-  [ -n "$head" ] && [ "$head" = "$upstream" ]
+  [ "$head" != "$upstream" ] || return 0
+  git -C "$worktree" merge-base --is-ancestor "$upstream" "$head" && return 1
+  HR_PUSH_REMOTE_TIP=$(git -C "$worktree" rev-parse --short "$upstream") || return 1
+  return 2
 }
 
 # ---------------------------------------------------------------------------
@@ -1946,8 +2074,7 @@ hr_push_landed() {
 #                           the counters that must survive a job boundary
 #   chain                   the writing job's OWN input `HARNESS_INPUT_CHAIN`, never
 #                           a value carried from an earlier bundle
-#   control_polled_at       the epoch second up to which the job checked for a
-#                           `harness pause <branch>` run, or empty
+#   control_polled_at       the lower bound of the next control poll, or empty
 #   decision                `continue` | `wait-poller` | `stop`
 #   detail                  one human-readable line
 #   run_id, run_url, written_at

package/templates/scripts/push-branch.sh

@@ -28,7 +28,13 @@
 # must NEVER abort the calling run — a stale remote is recoverable and a halted
 # run is not. That is why this script uses `set -uo pipefail` deliberately
 # WITHOUT `set -e`, and why even the fail-closed arm below exits 0: it refuses
-# to push, which is the closed outcome here, and says so.
+# to push, which is the closed outcome here, and says so. A push the remote
+# refused for any reason but a `[rejected]` ref is attempted up to
+# PUSH_ATTEMPTS times in all — waiting PUSH_RETRY_DELAY_SECS before the second
+# attempt and three times that before the third — and is still never fatal once
+# given up. PUSH_RETRY_DELAY_SECS is read from the environment as a test and
+# tuning seam: default 5, and anything but a non-negative integer falls back to
+# 5 with one line.
 #
 # DEFENCE IN DEPTH, NOT THE SOLE GUARD. The caller-agnostic backstop is the
 # committed pre-push hook `init` writes into the configured `githooksDir`, which
@@ -52,7 +58,11 @@
 #
 # WHAT IT NEVER DOES. It performs only a fast-forward push of already-committed
 # work: no `--force`, no `--force-with-lease`, no history-rewriting flag, no
-# commit of its own, and no non-zero exit.
+# commit of its own, and no non-zero exit. It never retries a push git reports
+# as `! [rejected]` (non-fast-forward, fetch first), and never fetches or
+# rebases: a push that lost a race fails loudly, which is the run-control rule
+# of record (docs/github-run-control.md -> "A push that loses a race fails
+# loudly, and is never fetched, rebased or retried").
 #
 # Usage: push-branch.sh [<repo-dir>]
 #   <repo-dir>  worktree/repository to operate in (default: $PWD)
@@ -73,9 +83,35 @@
 #                     -> exit 0, refusal message, nothing pushed
 #   push fails        git -C "$d" remote set-url origin /nonexistent.git
 #                     -> exit 0 with a visible failure line
+#   refused once      printf '%s\n' '#!/bin/sh' 'c="$GIT_DIR/refusals"' \
+#                       '[ -e "$c" ] && exit 0' ': > "$c"; exit 1' > "$b/hooks/pre-receive"
+#                     chmod +x "$b/hooks/pre-receive"
+#                     git -C "$d" commit -qm x --allow-empty
+#                     PUSH_RETRY_DELAY_SECS=0 push-branch.sh "$d"
+#                     -> exit 0, one "retrying" line, and `git -C "$b" rev-parse
+#                     feat_x` equals `git -C "$d" rev-parse HEAD`
+#   remote moved      c=$(mktemp -d); git clone -q -b feat_x "$b" "$c"
+#                     git -C "$c" commit -qm other --allow-empty; git -C "$c" push -q
+#                     git -C "$d" commit -qm mine --allow-empty; push-branch.sh "$d"
+#                     -> exit 0, a "(not retried)" line, one push attempt
 
 set -uo pipefail
 
+# Attempts in all, and the wait before the second; the third waits three times
+# that (EVERY FAILURE PATH IS NON-FATAL above).
+PUSH_ATTEMPTS=3
+PUSH_RETRY_DELAY_SECS="${PUSH_RETRY_DELAY_SECS:-5}"
+case "$PUSH_RETRY_DELAY_SECS" in
+  '' | *[!0-9]*)
+    echo "push-branch.sh: PUSH_RETRY_DELAY_SECS='$PUSH_RETRY_DELAY_SECS' is not a non-negative integer — using 5"
+    PUSH_RETRY_DELAY_SECS=5
+    ;;
+  *)
+    # Base 10, so a leading zero is not read as octal.
+    PUSH_RETRY_DELAY_SECS=$((10#$PUSH_RETRY_DELAY_SECS))
+    ;;
+esac
+
 # 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
 # non-fatal like everything else here.
@@ -125,16 +161,38 @@ esac
 # set it on the fly, so a branch with no upstream is still pushed. Fast-forward
 # only.
 if git -C "$top" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-  git -C "$top" push
+  push_cmd=(git -C "$top" push)
 else
-  git -C "$top" push --set-upstream origin "$branch"
+  push_cmd=(git -C "$top" push --set-upstream origin "$branch")
 fi
-push_status=$?
 
-if [ "$push_status" -eq 0 ]; then
-  echo "push-branch.sh: pushed $branch to origin"
-else
-  # Visible but non-blocking: a push problem must never abort the calling run.
-  echo "push-branch.sh: push failed for $branch (see output above)"
-fi
+# Every failure line keeps the `push failed for <branch>` prefix: logs and
+# Gate 12 records quote it.
+attempt=1
+delay="$PUSH_RETRY_DELAY_SECS"
+while :; do
+  push_out="$("${push_cmd[@]}" 2>&1)"
+  push_status=$?
+  # git writes its ref-status lines to stderr; keep them there.
+  [ -n "$push_out" ] && printf '%s\n' "$push_out" >&2
+
+  if [ "$push_status" -eq 0 ]; then
+    echo "push-branch.sh: pushed $branch to origin"
+    break
+  fi
+  # A here-string, not a pipe: `grep -q` exiting early would fail a pipeline
+  # under pipefail.
+  if grep -q '^ ! \[rejected\]' <<<"$push_out"; then
+    echo "push-branch.sh: push failed for $branch: origin has commits this branch does not (not retried)"
+    break
+  fi
+  if [ "$attempt" -ge "$PUSH_ATTEMPTS" ]; then
+    echo "push-branch.sh: push failed for $branch after $PUSH_ATTEMPTS attempts (see output above)"
+    break
+  fi
+  echo "push-branch.sh: push failed for $branch (attempt $attempt of $PUSH_ATTEMPTS); retrying in ${delay}s"
+  sleep "$delay"
+  attempt=$((attempt + 1))
+  delay=$((delay * 3))
+done
 exit 0