autonomous-sdlc-harness 0.4.2 → 0.6.0

package/templates/scripts/scratch-run.sh

@@ -42,16 +42,14 @@
 #
 # THE REFUSAL IS THE WHOLE OF THE SAFETY — over WHICH FILE, and over nothing
 # else, per the paragraph above. This script executes what it is given, so the
-# only thing standing between it and an arbitrary FILE is the path test below: the argument is rejected outright if it carries `..` or any
-# character outside `A-Za-z0-9._/-`, and what is left must resolve strictly
-# inside `<repo_root>/<state_dir>/scratch/`. A relative argument resolves against
-# `<repo_root>`; an absolute one is compared as given. Both sides of the
-# comparison are resolved PHYSICALLY (`cd … && pwd -P`), so a symlinked directory
-# planted inside the scratch tree cannot name a target outside it, and a target
-# that is itself a symlink is refused rather than followed. The `..` test rejects
-# the two characters anywhere in the argument rather than only a whole segment —
-# strictly stronger, and free, because nothing in that directory depends on a
-# file's name.
+# only thing standing between it and an arbitrary FILE is the path test: the
+# argument must resolve strictly inside `<repo_root>/<state_dir>/scratch/`, and a
+# `..`, a character outside `A-Za-z0-9._/-`, the scratch directory itself or a
+# symlinked target is refused. A relative argument resolves against
+# `<repo_root>`; an absolute one is compared as given. The test is
+# `hr_scratch_path_var` in `lib/harness-run-lib.sh`, shared with
+# `remote-run.sh discard`; the refusal reasons, and why each is refused, are the
+# ones that function names.
 #
 # THE INTERPRETER COMES FROM THE FILE'S OWN EXTENSION. The table is below, and it
 # is the only place it is stated. NOT from the detected preset, on two grounds
@@ -123,7 +121,8 @@
 #   0-N  the file ran; this is its own exit status, unmodified
 #   64   usage error — no file argument
 #   65   path refused — a `..`, a character outside `A-Za-z0-9._/-`, a symlink,
-#        or a target that does not resolve inside <state_dir>/scratch/
+#        the scratch directory itself, or a target that does not resolve
+#        inside <state_dir>/scratch/
 #   66   the extension has no interpreter in the table below
 #   67   the file is not there, or is not a readable regular file
 #   68   the run-time context could not be established — the shared library is
@@ -146,6 +145,7 @@
 #   outside         scripts/scratch-run.sh harness.config.json          -> exit 65
 #   traversal       scripts/scratch-run.sh sdlc-harness/scratch/../../harness.config.json
 #                                                                       -> exit 65
+#   itself          scripts/scratch-run.sh sdlc-harness/scratch/.       -> exit 65
 #   unknown ext     mv probe.py probe.pl; same call                     -> exit 66
 #   shell probe     mv probe.py probe.sh; same call                     -> exit 66
 #   absent file     scripts/scratch-run.sh sdlc-harness/scratch/nope.py -> exit 67
@@ -173,11 +173,6 @@ set -uo pipefail
 # the table's supported extensions in the message.
 SCRATCH_INTERPRETERS='py:python3 js:node mjs:node cjs:node rb:ruby dart:dart php:php'
 
-# The one directory under `<state_dir>` a file may be run out of. Spelled once
-# here, mirroring the `scratch` row of `STATE_DIR_ENTRIES` in
-# `cli/src/generators/stateDir.ts`.
-SCRATCH_SUBDIR='scratch'
-
 # The library is reached by a path computed from this script's own location — no
 # session root and no runtime-substituted token is assumed.
 hr_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/harness-run-lib.sh"
@@ -195,20 +190,6 @@ if [ "$#" -lt 1 ] || [ -z "${1-}" ]; then
 fi
 requested="$1"
 
-# --- The path tests, on the argument AS GIVEN, before anything is resolved.
-case "$requested" in
-  *..*)
-    echo "scratch-run.sh: '$requested' carries '..' — refusing, a scratch path names no parent" >&2
-    exit 65
-    ;;
-esac
-case "$requested" in
-  *[!A-Za-z0-9._/-]*)
-    echo "scratch-run.sh: '$requested' carries a character outside A-Za-z0-9._/- — refusing" >&2
-    exit 65
-    ;;
-esac
-
 # The repository is THIS FILE's own checkout, never the caller's directory: the
 # three forms the permission profile emits include a sibling worktree's own copy,
 # and each copy must answer for the checkout it belongs to whatever directory the
@@ -220,53 +201,53 @@ if [ -z "$repo_root" ]; then
   exit 68
 fi
 
-# `<repo_root>/<state_dir>/scratch`, from this repository's configuration at run
-# time. The library folds "not adopted" and "unreadable" into one non-zero
-# answer, and both are closed here: a configuration that cannot be read is a
-# scratch directory that cannot be located.
-scratch_dir="$(hr_state_path "$repo_root" "$SCRATCH_SUBDIR")"
-if [ -z "$scratch_dir" ]; then
-  echo "scratch-run.sh: cannot resolve '$repo_root/harness.config.json' — refusing to run anything" >&2
-  echo "  (no configuration there, invalid JSON, more than one document, no defaultBranch, or jq missing/older than 1.5)" >&2
-  exit 68
-fi
-
-scratch_real="$(cd "$scratch_dir" 2>/dev/null && pwd -P)"
-if [ -z "$scratch_real" ]; then
-  echo "scratch-run.sh: '$scratch_dir' does not exist — re-run 'init' to materialize the state tree" >&2
-  exit 68
-fi
-
-# A relative argument resolves against <repo_root>; an absolute one is taken as
-# given. Neither can carry `..` by the test above.
-case "$requested" in
-  /*) candidate="$requested" ;;
-  *) candidate="${repo_root%/}/$requested" ;;
-esac
-
-candidate_dir="$(cd "$(dirname "$candidate")" 2>/dev/null && pwd -P)"
-if [ -z "$candidate_dir" ]; then
-  echo "scratch-run.sh: '$requested' names no existing directory under '$repo_root'" >&2
-  exit 67
-fi
-
-# STRICTLY INSIDE: the scratch directory itself or a directory beneath it, on the
-# physical path of both sides, so a symlinked directory in the tree cannot widen
-# the fence.
-case "$candidate_dir" in
-  "$scratch_real" | "$scratch_real"/*) ;;
-  *)
-    echo "scratch-run.sh: '$requested' resolves to '$candidate_dir', outside '$scratch_real' — refusing" >&2
-    echo "  a file is runnable here only from <state_dir>/$SCRATCH_SUBDIR/ (see that directory's README.md)" >&2
+# A configuration that cannot be read is a scratch directory that cannot be
+# located: both are closed here.
+hr_scratch_path_var "$repo_root" "$requested"
+case "$HR_SCRATCH_WHY" in
+  "") ;;
+  dotdot)
+    echo "scratch-run.sh: '$requested' carries '..' — refusing, a scratch path names no parent" >&2
+    exit 65
+    ;;
+  charset)
+    echo "scratch-run.sh: '$requested' carries a character outside A-Za-z0-9._/- — refusing" >&2
+    exit 65
+    ;;
+  outside)
+    echo "scratch-run.sh: '$requested' resolves to '$HR_SCRATCH_PARENT', outside '$HR_SCRATCH_DIR' — refusing" >&2
+    echo "  a file is runnable here only from <state_dir>/$HR_SCRATCH_SUBDIR/ (see that directory's README.md)" >&2
     exit 65
     ;;
+  itself)
+    echo "scratch-run.sh: '$requested' names the scratch directory itself — refusing" >&2
+    exit 65
+    ;;
+  symlink)
+    echo "scratch-run.sh: '$requested' is a symlink — refusing, its target is outside this script's judgement" >&2
+    exit 65
+    ;;
+  no-parent)
+    echo "scratch-run.sh: '$requested' names no existing directory under '$repo_root'" >&2
+    exit 67
+    ;;
+  no-config)
+    echo "scratch-run.sh: cannot resolve '$repo_root/harness.config.json' — refusing to run anything" >&2
+    echo "  (no configuration there, invalid JSON, more than one document, no defaultBranch, or jq missing/older than 1.5)" >&2
+    exit 68
+    ;;
+  no-scratch)
+    echo "scratch-run.sh: '$(hr_state_path "$repo_root" "$HR_SCRATCH_SUBDIR")' does not exist — re-run 'init' to materialize the state tree" >&2
+    exit 68
+    ;;
+  usage | *)
+    echo "scratch-run.sh: no file argument" >&2
+    echo "  usage: scratch-run.sh <file-under-state-dir-scratch> [<arg>...]" >&2
+    exit 64
+    ;;
 esac
 
-target="$candidate_dir/$(basename "$candidate")"
-if [ -L "$target" ]; then
-  echo "scratch-run.sh: '$requested' is a symlink — refusing, its target is outside this script's judgement" >&2
-  exit 65
-fi
+target="$HR_SCRATCH_TARGET"
 if [ ! -f "$target" ] || [ ! -r "$target" ]; then
   echo "scratch-run.sh: '$target' is not a readable regular file" >&2
   exit 67

package/templates/state-dir/README-root.md

@@ -2,7 +2,7 @@
 
 Everything the delivery flow writes and reads lives here: the task prompt a branch starts from, the plans made for it, the findings of every review round, the progress ledger a resumed run reads back, the end-of-run statistics, and the two long-lived ledgers at the root of this directory. **The tree is committed** — these artifacts are the record of how each branch was planned, reviewed and fixed, and a reviewer or a resumed run reads them out of the repository rather than out of one machine's scratch space.
 
-What git ignores is the machine-local part of it, and it is a short list: the run daemon's per-run transcripts, event logs and run registry under `<state_dir>/autonomous_logs/`; the prompts dropped into `<state_dir>/autonomous_inbox/`; the questions a parked run asks with the answers it is given, under `<state_dir>/clarifications/`; and the throwaway files an agent runs a probe or a mutation check from, under `<state_dir>/scratch/`; and the full output of each test-gate run, one log per round, under `<state_dir>/test_run_logs/`. All five are ignored **by their contents**, so the committed `README.md` in each survives the rule and the directory keeps its contract. Ignored with them are the stop, pause and dispatch-count files a run leaves flat at the root of this directory while it is in flight — a committed `STOP` being the one that would halt every run for everyone who clones, at a step whose own instruction forbids deleting the file.
+What git ignores is the machine-local part of it, and it is a short list: the run daemon's per-run transcripts, event logs and run registry under `<state_dir>/autonomous_logs/`; the prompts dropped into `<state_dir>/autonomous_inbox/`; the questions a parked run asks with the answers it is given, under `<state_dir>/clarifications/`; and the throwaway files an agent runs a probe or a mutation check from, with the directories the branch commands' GitHub route fetches a branch's remote state into, under `<state_dir>/scratch/`; and the full output of each test-gate run, one log per round, under `<state_dir>/test_run_logs/`. All five are ignored **by their contents**, so the committed `README.md` in each survives the rule and the directory keeps its contract. Ignored with them are the stop, pause and dispatch-count files a run leaves flat at the root of this directory while it is in flight — a committed `STOP` being the one that would halt every run for everyone who clones, at a step whose own instruction forbids deleting the file.
 
 **Do not rename this directory to a dot-name.** That is this tree's own hard constraint, not a preference. It is tempting to tidy the tree out of sight, and it is the one change that risks unattended operation: this tree has to be writable by an unattended run, and a dot-path is where a host reserves directories an unattended run may not write to — the measured case is the host's own `.claude/**`, where an unattended run completes reporting success with nothing written. The name is configured as `stateDir` in `harness.config.json`, which refuses a dot at the start of any of its path segments rather than trusting which dot-paths a given host reserves — so a value that only reaches a dot-directory by traversal is refused as well as a plainly dot-named one.
 

package/templates/state-dir/scratch/README.md

@@ -1,8 +1,10 @@
 # scratch/
 
-A throwaway file an agent writes so that it can **execute** something: a language probe, before the code that would answer the question exists, or a mutation check that breaks an implementation on purpose to prove a new test fails. It is a file in the project's own language, and the interpreter follows from its extension — `probe.py` is run as Python, `probe.mjs` as Node. **Nothing depends on its name.** This is the one directory in the tree where a file's name carries no contract, and the only reason to choose it with any care is that two dispatches in flight at once must not land on the same one.
+A throwaway file an agent writes so that it can **execute** something: a language probe, before the code that would answer the question exists, or a mutation check that breaks an implementation on purpose to prove a new test fails. It is a file in the project's own language, and the interpreter follows from its extension — `probe.py` is run as Python, `probe.mjs` as Node. **Nothing depends on a probe file's name.** A probe is the one file in the tree whose name carries no contract — the fetch directories below are the exception here — and the only reason to choose it with any care is that two dispatches in flight at once must not land on the same one.
 
-A file here is written by the dispatched implementer or reviewer that needs the answer. **Nothing reads it**, and the harness's scratch runner is the route the flow **provides** for executing it — the route to use, not the only one that exists. It lives for the length of one dispatch — the agent that wrote it is the last participant with a reason to care about it — so this directory's steady state is empty. Nothing rotates or archives it, which makes deleting it once the answer is in hand the whole of the housekeeping.
+The GitHub route of `/autonomous-sdlc-harness:branch-pause`, `-resume`, `-answer` and `-user-review` also fetches a branch's remote state into `<state_dir>/scratch/<command>-<branch_fold>/`, and removes that directory with `remote-run.sh discard` on every path. `<branch_fold>` is the branch with every character outside `A-Za-z0-9_-` replaced by `_` — `feat/recent_searches_panel` gives `branch-pause-feat_recent_searches_panel` — so the name is always one path segment `discard` accepts. Two branches that fold to the same name are safe: the second command finds the first's directory, stops on it as a leftover, and never shares or removes it.
+
+A probe file here is written by the dispatched implementer or reviewer that needs the answer. **Nothing reads it**, and the harness's scratch runner is the route the flow **provides** for executing it — the route to use, not the only one that exists. It lives for the length of one dispatch — the agent that wrote it is the last participant with a reason to care about it — so this directory's steady state is empty. Nothing rotates or archives it, which makes deleting it once the answer is in hand the whole of the housekeeping.
 
 Its contents are **machine-local and gitignored**: the directory is ignored by its contents rather than as a directory, and this README survives by an explicit negation, which makes it the only committed file here.
 

package/templates/state-dir/user_reviews/README.md

@@ -2,8 +2,8 @@
 
 Two kinds of file under one root, both suffixed by round: the operator's hands-on review of a finished branch at `<branch>_review[_<n>].md`, and the fix plan it produces — a `<branch>_fix_plan[_<N>].md` index plus one `finding_<K>.md` per finding — written by the fix-plan writer and worked through by the implementers, reviewers and committer. Round 1 is unsuffixed and later rounds carry `_2`, `_3`, … A fix plan takes the **same** round number as the review it was written from, and its per-finding folder mirrors its index suffix exactly. So a `<branch>_fix_plan_2.md` found alone is round 2: it was written from `<branch>_review_2.md` in this directory, and its findings sit in `<branch>_fix_plan_2/finding_<K>.md` beside it.
 
-The review is written by hand after the hands-on pass, in the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review.md` fixes — or dropped through the unattended loop, which copies it here under its original name before launching the fix flow. The fix plan is the fix-plan writer's: it discovers the latest review here, derives both output paths from that round, and writes the index to the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan.md` fixes with per-finding files shaped like `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan/finding_1.md`. The drafted plan is then graded by the plan-review gates before any of its fixes is implemented, and walked item by item by the fix loop.
+The review is written by hand after the hands-on pass, in the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review.md` fixes — or dropped through the unattended loop, which copies it here under its original name before launching the fix flow — or submitted on GitHub as a pull-request review requesting changes on the run's branch, which becomes the next round. Its layout — one section per review — every review requesting changes, and every other review that carries a summary — with a provenance line naming its state, each inline comment with its file, line, commit, author and diff hunk, and a closing marker line — is set by the `control` paragraph of `remote-run.sh`'s header in the configured scripts directory. The fix plan is the fix-plan writer's: it discovers the latest review here, derives both output paths from that round, and writes the index to the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan.md` fixes with per-finding files shaped like `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan/finding_1.md`. The drafted plan is then graded by the plan-review gates before any of its fixes is implemented, and walked item by item by the fix loop.
 
-The unattended drop deliberately does **not** commit the review — unlike a prompt or a checklist it is not a precondition of the first step, and the fix flow's own first commit stages the review beside the fix-plan index and its per-finding folder. Nothing supersedes either file afterwards: a further round is written beside them under the next suffix, and the accumulated rounds are the branch's hands-on-review history. The whole directory is committed with the branch, since no ignore rule reaches it.
+The unattended drop for a **local** run deliberately does **not** commit the review — unlike a prompt or a checklist it is not a precondition of the first step, and the fix flow's own first commit stages the review beside the fix-plan index and its per-finding folder. A round for a run executing on GitHub — dropped, sent by the local command, or arriving as a pull-request review — is committed as `chore: add user review for <branch>` and pushed before its dispatch, because a job boundary before the fix flow's own commit would lose it. Nothing supersedes either file afterwards: a further round is written beside them under the next suffix, and the accumulated rounds are the branch's hands-on-review history. The whole directory is committed with the branch, since no ignore rule reaches it.
 
 The mistake worth naming is guessing the round instead of resolving it. The suffix is the **next free** index in this directory — list it first. A second pass that restarts at the unsuffixed name writes over round 1's record with nothing to flag it, and because that record is already tracked, the overwrite also dirties the tree the flow expects clean. The unattended path refuses a same-name drop whose content differs and tells the operator to use the next suffix; a file placed here by hand gets no such guard.