autonomous-sdlc-harness 0.5.0 → 0.6.0

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

@@ -3,7 +3,9 @@
 # the repository it is operating on, reads that repository's
 # `harness.config.json` at run time, answers "is this branch protected?",
 # routes an inbox filename to its engine and branch (`hr_inbox_route_var`),
-# derives a branch name from a title (`hr_derive_branch`), places a dropped
+# 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
 # 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
@@ -594,9 +596,10 @@ hr_config_load() {
   # which is what lets an explicitly EMPTY list read as a configured set rather
   # than as an absent one.
   #
-  # A `phases.*` 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` as a value it refuses (2).
+  # 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).
   out=$(jq -n -r '
     def s($k; $v):
       if $v == null then empty
@@ -631,6 +634,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("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),
       s("protectedBranches.present";
         try (if (.protectedBranches | type) == "array" then "1" else null end) catch null),
@@ -918,6 +923,53 @@ hr_forge() {
   return 2
 }
 
+# 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
+# NOTHING: the answer is the status, as `hr_phase_enabled`'s is. 0 = both
+# `true`; 1 = either `false` or unset; 2 = the configuration is unresolvable or
+# either value is not a boolean — refused rather than guessed about.
+hr_docs_retrieval_applies() {
+  local root="${1-}" status
+  hr_phase_enabled "$root" docs
+  status=$?
+  [ "$status" -eq 0 ] || return "$status"
+  hr_cfg_scalar_var "docs.retrieval" || return 1
+  case "$HR_CFG_VALUE" in
+    true) return 0 ;;
+    false) return 1 ;;
+  esac
+  return 2
+}
+
+# `docs.retrievalBackend` — which runtime the docs-retrieval index uses:
+# `typescript` or `python`. THE ONE READER OF THE KEY IN THIS FAMILY, and the
+# shell mirror of `cli/src/config/model.ts` → `RETRIEVAL_BACKENDS` /
+# `DEFAULT_RETRIEVAL_BACKEND`: change the enum there and here together. Schema
+# default `typescript`, so an absent key prints `typescript` and 1 is never
+# returned; a `docs` parent of the wrong type (`"docs": "x"`) reads as absent
+# too, because `hr_config_load`'s `try … catch` nulls that key alone — refusing
+# that shape is the schema's job. 2 — printing nothing — when the configuration
+# is unresolvable or the value is outside the enum, a refusal rather than a
+# guess. It does NOT consult `phases.docs` / `docs.retrieval`: the key is read
+# only inside the gate, so a caller asks `hr_docs_retrieval_applies` first and
+# calls this only on its status 0.
+hr_docs_retrieval_backend() {
+  local root="${1-}"
+  hr_config_load "$root" || return 2
+  if ! hr_cfg_scalar_var "docs.retrievalBackend"; then
+    printf 'typescript\n'
+    return 0
+  fi
+  case "$HR_CFG_VALUE" in
+    typescript|python)
+      printf '%s\n' "$HR_CFG_VALUE"
+      return 0
+      ;;
+  esac
+  return 2
+}
+
 # ---------------------------------------------------------------------------
 # Inbox routing — the one owner of the drop filename patterns.
 # ---------------------------------------------------------------------------
@@ -1140,6 +1192,92 @@ hr_state_path() {
   fi
 }
 
+# Judge whether <path> resolves STRICTLY INSIDE `<root>/<state_dir>/scratch/`.
+# Usage: hr_scratch_path_var <root> <path> [<base>]
+#
+# Two callers, differing only in what they do with an accepted path:
+# `scratch-run.sh` executes a file there and `remote-run.sh discard` removes a
+# directory there. So this reports a keyword in `HR_SCRATCH_WHY` and leaves every
+# message and exit code to its caller.
+#
+# The rule, stated once:
+#   - `..` is refused ANYWHERE in the argument, not only as a whole segment —
+#     strictly stronger, and free, because nothing in that directory depends on
+#     a file's name. Then any character outside `A-Za-z0-9._/-` is refused. Both
+#     tests run on <path> as the caller received it, before anything resolves.
+#   - A relative <path> resolves against <base> when given, else <root>; an
+#     absolute one is taken as given.
+#   - Both sides of the comparison are resolved PHYSICALLY (`cd … && pwd -P`), so
+#     a symlinked directory planted inside the scratch tree cannot widen the
+#     fence. The target's parent must be the scratch directory or beneath it, and
+#     a basename of `.` (the scratch directory itself) is refused.
+#   - A target that is itself a symlink is refused rather than followed: its
+#     destination is outside this judgement. The target need not exist.
+#
+# Clears the other four, then sets: `HR_SCRATCH_SUBDIR` (`scratch`, mirroring the `scratch` row
+# of `STATE_DIR_ENTRIES` in `cli/src/generators/stateDir.ts`), `HR_SCRATCH_DIR`
+# (physical), `HR_SCRATCH_PARENT` (physical), `HR_SCRATCH_TARGET`
+# (`<parent>/<basename>`, the path a caller acts on) and `HR_SCRATCH_WHY`.
+# Status / `HR_SCRATCH_WHY`:
+#   0  accepted (WHY empty)
+#   1  refused — `dotdot`, `charset`, `outside`, `itself`, `symlink`
+#   2  the target's parent does not resolve — `no-parent`
+#   3  the scratch directory cannot be located — `no-config`, `no-scratch`
+#   4  <root> or <path> is empty — `usage`
+hr_scratch_path_var() {
+  local root="${1-}" path="${2-}" base="${3-}" scratch candidate name
+  HR_SCRATCH_DIR=""
+  HR_SCRATCH_PARENT=""
+  HR_SCRATCH_TARGET=""
+  HR_SCRATCH_WHY=""
+  HR_SCRATCH_SUBDIR='scratch'
+  if [ -z "$root" ] || [ -z "$path" ]; then
+    HR_SCRATCH_WHY="usage"
+    return 4
+  fi
+  case "$path" in
+    *..*) HR_SCRATCH_WHY="dotdot"; return 1 ;;
+  esac
+  case "$path" in
+    *[!A-Za-z0-9._/-]*) HR_SCRATCH_WHY="charset"; return 1 ;;
+  esac
+  scratch=$(hr_state_path "$root" "$HR_SCRATCH_SUBDIR")
+  if [ "$?" -ne 0 ] || [ -z "$scratch" ]; then
+    HR_SCRATCH_WHY="no-config"
+    return 3
+  fi
+  HR_SCRATCH_DIR=$(cd "$scratch" 2>/dev/null && pwd -P)
+  if [ -z "$HR_SCRATCH_DIR" ]; then
+    HR_SCRATCH_WHY="no-scratch"
+    return 3
+  fi
+  [ -n "$base" ] || base="$root"
+  case "$path" in
+    /*) candidate="$path" ;;
+    *) candidate="${base%/}/$path" ;;
+  esac
+  HR_SCRATCH_PARENT=$(cd "$(dirname "$candidate")" 2>/dev/null && pwd -P)
+  if [ -z "$HR_SCRATCH_PARENT" ]; then
+    HR_SCRATCH_WHY="no-parent"
+    return 2
+  fi
+  case "$HR_SCRATCH_PARENT" in
+    "$HR_SCRATCH_DIR" | "$HR_SCRATCH_DIR"/*) ;;
+    *) HR_SCRATCH_WHY="outside"; return 1 ;;
+  esac
+  name=$(basename "$candidate")
+  if [ "$name" = "." ]; then
+    HR_SCRATCH_WHY="itself"
+    return 1
+  fi
+  HR_SCRATCH_TARGET="$HR_SCRATCH_PARENT/$name"
+  if [ -L "$HR_SCRATCH_TARGET" ]; then
+    HR_SCRATCH_WHY="symlink"
+    return 1
+  fi
+  return 0
+}
+
 # The machine-local settings directory — one place an operator keeps values that
 # vary per machine rather than per repository, which is why it is not a config
 # key and not a repository file. Return 1 when there is no home to anchor it to.
@@ -1442,8 +1580,10 @@ hr_remote_record_init() {
 #   limit and readable in the Actions run list. GitHub documents no ref limit.
 #
 # THIS SECTION ONLY READS. It fetches nothing and creates no branch or file; a
-# caller that wants `origin` fresh fetches first. A registry is read only when
-# it already exists, because `hr_registry_get` creates an absent one.
+# caller that wants `origin` fresh fetches first. Given a <gh_cli>, it also asks
+# GitHub one read per candidate — the run workflow's runs under that name — and
+# still writes nothing. A registry is read only when it already exists, because
+# `hr_registry_get` creates an absent one.
 # ---------------------------------------------------------------------------
 
 # The two limits the rule above names.
@@ -1525,11 +1665,37 @@ EOF
   return 0
 }
 
-# Judge <name> against the listings `hr_branch_taken_lists_var` last read. The
-# answers and `HR_TAKEN_WHY` are `hr_branch_name_taken`'s.
+# hr_branch_run_history <root> <gh_cli> <name> — 0 when the run workflow
+# (`HR_REMOTE_WORKFLOW_RUN_FILE`) lists a run under <name>, 1 when it lists
+# none, 2 when <gh_cli> cannot run, exits non-zero, or answers anything but a
+# JSON array. Sets no `HR_` variable: the names are assigned inside the
+# subshell that `cd`s to <root>.
+#
+# GitHub keeps a deleted branch's runs listed under its name, and a later run
+# of that name inherits them: Gate 12 round 5 found run `36569531374` of the
+# deleted `feat_invoices` (`docs/development.md` → Gate 12 → Round 5, finding
+# 1). One bounded read per candidate, not one listing of every branch, because
+# a bounded all-branch listing could miss an old name. Bash 3.2 and jq 1.5.
+hr_branch_run_history() {
+  local root="${1-}" gh_cli="${2-}" name="${3-}" answer verdict
+  [ -n "$root" ] && [ -n "$gh_cli" ] && [ -n "$name" ] || return 2
+  answer=$(cd "$root" 2>/dev/null && hr_remote_names_var &&
+    "$gh_cli" run list --workflow "$HR_REMOTE_WORKFLOW_RUN_FILE" --branch "$name" --limit 1 --json databaseId 2>/dev/null) || return 2
+  verdict=$(printf '%s' "$answer" | jq -r 'if type == "array" then (if length > 0 then "history" else "none" end) else "other" end' 2>/dev/null) || return 2
+  case "$verdict" in
+    history) return 0 ;;
+    none) return 1 ;;
+  esac
+  return 2
+}
+
+# Judge <name> against the listings `hr_branch_taken_lists_var` last read, then,
+# given a <gh_cli>, against the run workflow's history — last, so the free local
+# checks answer first. The answers and `HR_TAKEN_WHY` are
+# `hr_branch_name_taken`'s.
 hr_branch_taken_judge() {
   local LC_ALL=C
-  local root="${1-}" name="${2-}" registry="${3-}" lower status nl
+  local root="${1-}" name="${2-}" registry="${3-}" gh_cli="${4-}" lower status nl
   nl='
 '
   HR_TAKEN_WHY=""
@@ -1557,18 +1723,29 @@ hr_branch_taken_judge() {
     HR_TAKEN_WHY="a run registry record"
     return 0
   fi
+  if [ -n "$gh_cli" ]; then
+    status=0
+    hr_branch_run_history "$root" "$gh_cli" "$name" || status=$?
+    case "$status" in
+      0) HR_TAKEN_WHY="a run of the run workflow listed under that name"; return 0 ;;
+      1) ;;
+      *) HR_TAKEN_WHY="the run history of $name could not be listed"; return 2 ;;
+    esac
+  fi
   return 1
 }
 
-# hr_branch_name_taken <root> <name> [<registry>] — 0 taken, 1 free, 2 cannot
-# tell. Sets `HR_TAKEN_WHY` to a short phrase naming the collision or the
-# failure. Taken: a protected name; a branch on `origin`, compared
-# case-insensitively; a local branch; under `<state_dir>` on
-# `origin/<defaultBranch>`, a directory named <name> or a file
-# `<name>_task_prompt.md`, `<name>_story_plan.md` or `<name>_docs.md` — which a
-# merged and deleted branch still leaves; a record in an existing <registry>.
+# hr_branch_name_taken <root> <name> [<registry>] [<gh_cli>] — 0 taken, 1 free,
+# 2 cannot tell. Sets `HR_TAKEN_WHY` to a short phrase naming the collision or
+# the failure. A caller with no registry passes `""` before <gh_cli>. Taken: a
+# protected name; a branch on `origin`, compared case-insensitively; a local
+# branch; under `<state_dir>` on `origin/<defaultBranch>`, a directory named
+# <name> or a file `<name>_task_prompt.md`, `<name>_story_plan.md` or
+# `<name>_docs.md` — which a merged and deleted branch still leaves; a record in
+# an existing <registry>; given a <gh_cli>, any run of the run workflow listed
+# under <name> (`hr_branch_run_history`), whose listing failing is a 2.
 hr_branch_name_taken() {
-  local root="${1-}" name="${2-}" registry="${3-}"
+  local root="${1-}" name="${2-}" registry="${3-}" gh_cli="${4-}"
   HR_TAKEN_WHY=""
   if [ -z "$root" ] || [ -z "$name" ]; then
     HR_TAKEN_WHY="no branch name to judge"
@@ -1576,20 +1753,21 @@ hr_branch_name_taken() {
   fi
   hr_config_load "$root" || :
   hr_branch_taken_lists_var "$root" || return 2
-  hr_branch_taken_judge "$root" "$name" "$registry"
+  hr_branch_taken_judge "$root" "$name" "$registry" "$gh_cli"
 }
 
-# hr_derive_branch <root> <text> <fallback> [<registry>] — print the derived name
-# and return 0; return 2, printing nothing, when a `taken` judgement could not
-# tell or no base routes back to itself; return 3, printing nothing, when every
-# suffix through `HR_BRANCH_SUFFIX_MAX` is taken. Never a guessed name.
+# hr_derive_branch <root> <text> <fallback> [<registry>] [<gh_cli>] — print the
+# derived name and return 0; return 2, printing nothing, when a `taken`
+# judgement could not tell or no base routes back to itself; return 3, printing
+# nothing, when every suffix through `HR_BRANCH_SUFFIX_MAX` is taken. Never a
+# guessed name. <gh_cli> reaches every judgement as `hr_branch_name_taken`'s.
 #
 # THE BASE MUST ROUTE BACK TO ITSELF: `hr_inbox_route_var` on each drop filename
 # a run of that name produces has to give the base as its branch, so no derived
 # name makes the inbox patterns ambiguous. A base that does not is replaced by
 # <fallback> once.
 hr_derive_branch() {
-  local root="${1-}" text="${2-}" fallback="${3-}" registry="${4-}"
+  local root="${1-}" text="${2-}" fallback="${3-}" registry="${4-}" gh_cli="${5-}"
   local base="" candidate suffix routes n status
   hr_branch_limits_var
   candidate=$(hr_branch_slug "$text") || candidate="$fallback"
@@ -1615,7 +1793,7 @@ hr_derive_branch() {
   n=1
   while :; do
     status=0
-    hr_branch_taken_judge "$root" "$candidate" "$registry" || status=$?
+    hr_branch_taken_judge "$root" "$candidate" "$registry" "$gh_cli" || status=$?
     case "$status" in
       1) printf '%s\n' "$candidate"; return 0 ;;
       2) return 2 ;;
@@ -1704,8 +1882,9 @@ hr_push_landed() {
 # names. Every name below is a variable `hr_remote_names_var` assigns, and it
 # also assigns `HR_REMOTE_WORKFLOW_RUN_FILE`, the run workflow's file name, for
 # the GitHub-route producers `hr_github_answer_route` and
-# `hr_github_resume_route`. Those two are mirrors of the header's table; no
-# function spells either one, or any other name here.
+# `hr_github_resume_route` and for the run-history probe `hr_branch_run_history`.
+# Those two are mirrors of the header's table; no function spells either one,
+# or any other name here.
 #
 #   <bundle>/status.json                 the job's record, fixed schema below
 #   <bundle>/clarifications/<branch>/    the whole branch directory, answered/ included