autonomous-sdlc-harness 0.1.0

package/templates/scripts/scratch-run.sh

@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# scratch-run.sh — run ONE file that lives under `<state_dir>/scratch/`, in the
+# interpreter that file's own extension names, and refuse every other path.
+#
+# WHAT IT IS FOR. The two things a dispatched agent otherwise has no permitted
+# route to do: a LANGUAGE PROBE — run a few lines in the project's own language
+# before the code that would answer the question exists — and a MUTATION CHECK —
+# break an implementation on purpose to prove a new test fails. Without a route
+# the agent either reaches for an interpreter and is refused, or silently
+# downgrades a claim it meant to verify from *executed* to *reasoned*.
+#
+# WHY A WRAPPER EXISTS AT ALL. Same reason as its siblings: an invocation of a
+# script path under the configured scripts directory is allow-listed literally in
+# three forms by the generated permission profile (this file's row in
+# `cli/src/generators/outerLoopScripts.ts` carries `agentInvocable: true`) and is
+# auto-allowed by the script-allowlist guard — a script under that directory
+# whose basename is not on the 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`. A bare `python3 …` command line is
+# matched statically by neither and draws a prompt an unattended run cannot
+# answer. This basename is deliberately NOT on that deny list, and its absence
+# there is the decision that makes the guard route cover this script from the
+# first run, whether or not the profile has been regenerated.
+#
+# WHAT THIS DOES NOT CONTAIN. The first argument is a path and every remaining
+# argument is forwarded to the file, so nothing here takes an inline program — no
+# `-c`, no `-e`, no `bash -c`. That fence is over WHICH FILE RUNS and over nothing
+# the file does. A probe is a program the agent composed one tool call earlier and
+# it runs with the session's own privileges, so everything the generated profile's
+# `deny` floor and its `ask` list, and the script-allowlist guard's
+# `DENY_SCRIPT_BASENAMES`, withhold from a COMMAND STRING is reachable from inside
+# one — directly, or one `subprocess` / `child_process` call further on. Do not
+# read the file/string distinction as a capability boundary: it costs an extra
+# tool call. The layer that still holds is the `pre-push` git hook, because git
+# runs it however git was invoked, subprocess included — the ranking
+# `plugin/docs/AUTONOMOUS_FLOW_WHITEBOARD.md`'s protected-branch bullet states.
+# The two mitigations that do apply are narrower than containment and are named as
+# what they are: `<state_dir>/scratch/` is gitignored by its contents, so nothing
+# run from here reaches a commit, and the agent instructions require a MUTATION
+# CHECK to be reverted before the task's own verification runs.
+#
+# 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.
+#
+# 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
+# that both survive reading `DETECTION_PRESET_NAMES` (`cli/src/config/model.ts`).
+# A preset covers the repository's LAYOUT rather than its toolchain: some names in
+# `DETECTION_PRESET_NAMES` imply a language and others imply none, and which
+# language a repository is actually probed in is settled by `commandFamilies`
+# (`cli/src/detect/presets.ts`), not by the preset. So a preset-derived entry
+# reads the wrong field — silent wherever the preset names no toolchain, and
+# wrong wherever a probe's language is not the one the preset implies. And it
+# would be the wrong SHAPE regardless: a preset-derived profile entry
+# is a `Bash(<interpreter>:*)` grant over every command line that interpreter can
+# be handed, which is the breadth the profile `_README`'s package-manager
+# paragraph refuses — while this table grants nothing at all, the reachability
+# coming from this script's own row. NOT from a configuration key either: the
+# family that answered IS recorded, as `detection.commandFamily`, and this table
+# is still not derived from it — a family id answers which toolchain answered for
+# the command keys, not what interpreter a scratch file needs, and a
+# family-derived entry would be the same over-broad `Bash(<interpreter>:*)` grant
+# that paragraph refuses. An extension the table
+# does not carry is refused by name, listing the ones that are — never guessed,
+# and never run under `sh`.
+#
+# WHAT THAT COSTS, STATED RATHER THAN LEFT TO BE DISCOVERED. The table is a CLOSED
+# seven-extension set with NO ADOPTER EXTENSION POINT: no configuration key, no
+# flag, and the file ships fixed. Its `<extension>:<interpreter>` shape is a SINGLE
+# token run as `exec "$interpreter" "$target" "$@"`, so it cannot express a
+# two-word toolchain invocation — `go run`, `cargo`, `dotnet script`. THAT is what
+# bounds the set, and it bounds it by TOOLCHAIN rather than by adoption: the
+# stacks with no probe route here are the ones whose file is not run by a single
+# token — Go, Rust, .NET, Swift, the JVM and Android, C++. Every language a
+# `commandFamilies` function (`cli/src/detect/presets.ts`) covers that DOES run a
+# source file as `<token> <file>` is carried: Node, Python, Ruby, Dart and PHP.
+# Where an adoption's language is not one this table carries there is no probe
+# route here at all, and what an agent has instead is the evidence downgrade
+# `plugin/agents/layer-implementer.md` requires of it (its *An evidence downgrade
+# is recorded* paragraph) — the claim recorded as reasoned rather than executed.
+# Widening the set to a two-word toolchain is a decision for a later round,
+# carried as a residual in `docs/outer-loop-verification.md` §4.
+#
+# THE RUN MUST NEVER SEE A FILE FROM HERE IN A COMMIT. `<state_dir>/scratch/` is
+# ignored by its CONTENTS — the managed block in the generated `.gitignore`, with
+# a negation for that directory's own README — so a probe cannot be committed by
+# accident. The other half of that duty belongs to the agent rather than to this
+# script: a MUTATION CHECK is REVERTED before the task's own verification runs,
+# because the committer will see that suite and it has to be clean.
+#
+# IT IS DELIBERATELY NOT A WRAPPER. It carries no adopter command line — it is
+# not a `WRAPPER_SCRIPTS` row, answers to no `commands.*` key, and has no
+# `{{command}}` for `init` to inline. Like every outer-loop script it ships fixed
+# and reads `harness.config.json` at run time.
+#
+# IT PRINTS NOTHING OF ITS OWN ON THE RUN PATH. The file's stdout and stderr are
+# the answer, and a caller reading a probe's output must not have to filter a
+# wrapper's verdict line out of it — the opposite of the project-command
+# wrappers, whose one verdict line is their contract. Every refusal, and only a
+# refusal, prints `scratch-run.sh: …` on stderr.
+#
+# Usage: scratch-run.sh <file-under-state-dir-scratch> [<arg>...]
+#   <file>     the file to run; relative to <repo_root>, or absolute
+#   <arg>...   forwarded to that file, unchanged
+#
+# Exit map a caller can switch on. A run passes the file's OWN status through
+# untouched, so the refusal codes cannot be exclusive — a probe is free to exit
+# 65. The reliable signal that NOTHING ran is the `scratch-run.sh:` line on
+# stderr; the codes are for telling one refusal from another:
+#
+#   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/
+#   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
+#        unreadable, this is not a git repository, `harness.config.json` could
+#        not be resolved, or the scratch directory has never been materialized
+#   69   the interpreter the extension names is not on PATH
+#
+# 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":"main","stateDir":"sdlc-harness/","layers":[],"commands":{}}' > "$d/harness.config.json"
+#   mkdir -p "$d/sdlc-harness/scratch"
+#   printf 'import sys\nprint("ok", sys.argv[1:])\n' > "$d/sdlc-harness/scratch/probe.py"
+#   cp -R <scripts_dir>/. "$d/scripts/"   # this file and its lib/
+#
+#   the probe       (cd "$d" && scripts/scratch-run.sh sdlc-harness/scratch/probe.py a b)
+#                   -> prints `ok ['a', 'b']`, exit 0
+#   its own status  a probe ending `sys.exit(7)`                        -> exit 7
+#   absolute form   scripts/scratch-run.sh "$d/sdlc-harness/scratch/probe.py"  -> runs
+#   outside         scripts/scratch-run.sh harness.config.json          -> exit 65
+#   traversal       scripts/scratch-run.sh sdlc-harness/scratch/../../harness.config.json
+#                                                                       -> 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
+#   unresolvable    printf 'x' > "$d/harness.config.json"; same call    -> exit 68
+
+# Deliberately no `-e`: every refusal below is an explicit `exit`, and an
+# implicit one would skip the message that says what was refused and why.
+set -uo pipefail
+
+# --- THE INTERPRETER TABLE, stated once: `<extension>:<interpreter>`, space
+# separated. Both readers below derive from this one string — the lookup, and
+# the refusal message that lists what is supported — so there is no second list
+# to keep in step with it. Matching is exact and case-sensitive: `.PY` is an
+# extension this table does not carry, and a guess is worse than a refusal.
+#
+# THE ONE EXTENSION THIS TABLE OMITS ON PURPOSE IS `.sh`. Not for containment —
+# WHAT THIS DOES NOT CONTAIN above says why a `.py` probe reaches a shell one
+# `subprocess` call further on — but because it is the row reachable by fewer
+# routes than the rest, buying nothing the others do not. The script-allowlist
+# guard requires EVERY `.sh` token in a command to resolve under the scripts
+# directory, so `bash <scripts_dir>/scratch-run.sh <state_dir>/scratch/probe.sh`
+# carries a second one that does not, and falls through to the permission system:
+# it would run on the profile entry alone, drawing a prompt on an adoption whose
+# guard route covers every other row. A shell probe is refused by name here, with
+# 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"
+if [ ! -r "$hr_lib" ]; then
+  echo "scratch-run.sh: cannot read '$hr_lib' — refusing to run anything" >&2
+  exit 68
+fi
+# shellcheck source=lib/harness-run-lib.sh
+. "$hr_lib"
+
+if [ "$#" -lt 1 ] || [ -z "${1-}" ]; then
+  echo "scratch-run.sh: no file argument" >&2
+  echo "  usage: scratch-run.sh <file-under-state-dir-scratch> [<arg>...]" >&2
+  exit 64
+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
+# caller stood in.
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(hr_repo_root "$script_dir")"
+if [ -z "$repo_root" ]; then
+  echo "scratch-run.sh: '$script_dir' is not inside a git repository — refusing to run anything" >&2
+  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
+    exit 65
+    ;;
+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
+if [ ! -f "$target" ] || [ ! -r "$target" ]; then
+  echo "scratch-run.sh: '$target' is not a readable regular file" >&2
+  exit 67
+fi
+
+# --- The interpreter, from the extension and from nothing else.
+base="$(basename "$target")"
+case "$base" in
+  ?*.*) extension="${base##*.}" ;;
+  *) extension="" ;;
+esac
+
+interpreter=""
+supported=""
+for entry in $SCRATCH_INTERPRETERS; do
+  if [ "${entry%%:*}" = "$extension" ]; then interpreter="${entry#*:}"; fi
+  if [ -z "$supported" ]; then supported=".${entry%%:*}"; else supported="$supported .${entry%%:*}"; fi
+done
+
+if [ -z "$interpreter" ]; then
+  echo "scratch-run.sh: '$base' has no interpreter for extension '${extension:-<none>}'" >&2
+  echo "  the table carries: $supported" >&2
+  exit 66
+fi
+
+if ! command -v "$interpreter" >/dev/null 2>&1; then
+  echo "scratch-run.sh: '$interpreter' (for .$extension) is not on PATH — nothing was run" >&2
+  exit 69
+fi
+
+# The file, then the caller's remaining arguments, and nothing else. `exec` is
+# what makes this script's exit status the file's own, with nothing added.
+shift
+exec "$interpreter" "$target" "$@"

package/templates/scripts/setup-worktree.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# setup-worktree.sh — bootstrap the checkout this script sits in, so a run can
+# start in it: link the machine-local files a fresh working copy cannot carry in
+# git, install the committed pre-push backstop for THIS working copy, install
+# dependencies and build.
+#
+# WHO RUNS IT. create-worktree.sh, immediately after it adds a working copy —
+# and a person, by hand, on a checkout that predates a configuration change.
+# Every step is idempotent, so re-running it is the supported repair. It is not
+# meant to be run by a dispatched agent: it is not agent-invocable, it has no
+# entry in the generated permission profile, and it should not get one — it
+# installs dependencies and writes git configuration, which are not decisions an
+# agent takes. That is a CALLING CONVENTION, NOT A GATE. Its basename is not on
+# the script-allowlist guard's `DENY_SCRIPT_BASENAMES`, and that guard grants
+# independently of the profile, so an agent that invokes this path under
+# `scriptsDir` is auto-allowed today — but only in a PLAIN invocation: that
+# guard's construct scan withholds the allow, silently, from any command
+# carrying `$(…)`, 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`. Adding the basename to
+# `DENY_SCRIPT_BASENAMES` is what would make the convention enforced.
+#
+# THE FIVE STEPS, AND WHAT EACH DOES WHEN ITS INPUT IS ABSENT.
+#
+#   1. Version manager. A stack that pins its toolchain through a version
+#      manager needs that manager's init file sourced before anything installs.
+#      Point `HARNESS_VERSION_MANAGER_INIT` at that file (in the watcher's
+#      environment, or in the operator's shell profile) and it is sourced here.
+#      Unset, or naming a file that is not readable, is a SILENT no-op: most
+#      projects have no such file and a note about it every run is noise.
+#   2. The machine-local client env file. When the MAIN checkout has
+#      `<appDir>/.env` and this checkout has none, it is SYMLINKED — one file,
+#      one place, and gitignored on both sides by the managed `.gitignore`
+#      block's `<appDir>/.env` rule, which is what leaves a freshly bootstrapped
+#      working copy showing nothing at all in `git status --porcelain`. There is
+#      no configuration key for it, and `clientEnvPrefix` is not one (it is
+#      review vocabulary — the prefix a build tool requires before exposing a
+#      variable to a client bundle — not a path), so the existence test IS the
+#      condition. An adopter whose stack needs a different machine-local file
+#      adds it here: this script is theirs from `init` on, and a re-run never
+#      overwrites it.
+#   3. The test-account credentials at `qa.credentialsPath`, symlinked from the
+#      main checkout by the same rule. NEVER copied: the file is sensitive and
+#      gitignored, and a symlink keeps the secret in one place and keeps the
+#      working copy clean. No key configured means nothing is attempted.
+#   4. The pre-push backstop at `githooksDir`, installed for this working copy
+#      alone (see the note at the step itself). A missing hook file is a skip
+#      with one line, so a checkout that predates the hook still bootstraps.
+#   5. `commands.depInstall`, then `commands.build`, each run from the
+#      repository root. An UNSET key is skipped with one printed line rather
+#      than being an error — a project with no build step is ordinary. A build
+#      is skipped when the dependency install failed, because a build on a
+#      failed install only produces a second, less clear failure.
+#
+# THE REFERENCE TOOLCHAIN IS NOT BOOTSTRAPPED HERE. A project that mirrors a
+# reference implementation lists that implementation's own commands in
+# `parity.toolchainCommands`, which the review phase runs and reports deferred
+# when they are unavailable in an isolated working copy. Installing them is not
+# part of preparing a working copy, and doing it here would make every bootstrap
+# depend on a toolchain most steps never use.
+#
+# WHY NO `set -e`, AND WHY ITS CALLER HAS ONE. Each step's outcome is decided
+# here — skip, warn, or fail — and `-e` would turn the ordinary "this key is not
+# configured" into an abort. Failures are accumulated instead and reported in
+# the exit status, which is what create-worktree.sh's `set -e` then acts on: a
+# working copy whose dependencies did not install is not pushed as if it had.
+#
+# FAIL CLOSED ON A CONFIGURATION IT CANNOT READ. Every path and command below is
+# configured, and none has a remembered fallback, so an absent or unreadable
+# `harness.config.json` is a refusal that changes nothing — not a bootstrap that
+# guesses where the hooks are.
+#
+# Usage: setup-worktree.sh
+#   No arguments. The checkout is this script's own location, not $PWD, because
+#   the caller runs it from wherever it happens to be.
+#
+# Exit map:
+#
+#   0  every step ran or was deliberately skipped
+#   1  refusal (the library or the configuration could not be read), or a step
+#      that was meant to run failed — the message above the exit says which
+#
+# REPRO — reproduce any decision by hand, against a throwaway fixture:
+#
+#   w=$(mktemp -d); d="$w/demo"; git init -q -b trunk "$d"; mkdir -p "$d/githooks"
+#   printf '#!/usr/bin/env bash\nexit 0\n' > "$d/githooks/pre-push"
+#   printf '%s' '{"version":1,"defaultBranch":"trunk","stateDir":"sdlc-harness/","githooksDir":"githooks","layers":[],"commands":{"depInstall":"printf x > deps.marker"}}' > "$d/harness.config.json"
+#   mkdir -p "$d/scripts/lib"   # copy this script + lib/ there
+#
+#   ordinary        bash "$d/scripts/setup-worktree.sh"
+#                   -> exit 0; "$d/deps.marker" exists; the build step prints its
+#                      skip line; `git -C "$d" config --worktree core.hooksPath`
+#                      is "$d/githooks"
+#   no hook file    rm "$d/githooks/pre-push"; re-run -> exit 0 with a skip line
+#   env symlink     printf 'K=v\n' > "$(git -C "$d" worktree list --porcelain |
+#                     head -1 | sed 's/^worktree //')/.env"
+#                   -> a sibling working copy's .env is a SYMLINK to that file;
+#                      one that already has its own .env is left untouched
+#   unresolvable    printf 'x' > "$d/harness.config.json"; re-run -> exit 1,
+#                   nothing installed and no git configuration written
+
+set -uo pipefail
+
+hr_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/harness-run-lib.sh"
+if [ ! -r "$hr_lib" ]; then
+  echo "setup-worktree.sh: cannot read '$hr_lib' — refusing to bootstrap" >&2
+  exit 1
+fi
+# shellcheck source=lib/harness-run-lib.sh
+. "$hr_lib"
+
+# The checkout being bootstrapped is where THIS FILE lives — never $PWD, which
+# belongs to whoever invoked it.
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+top="$(hr_repo_root "$script_dir")" || top=""
+if [ -z "$top" ]; then
+  echo "setup-worktree.sh: '$script_dir' is not inside a git repository — refusing to bootstrap" >&2
+  exit 1
+fi
+
+# Warm the library's cache once, unsubstituted, and refuse here rather than
+# letting each reader below fail separately with its own message.
+cfg_status=0
+hr_config_load "$top" || cfg_status=$?
+if [ "$cfg_status" -ne 0 ]; then
+  echo "setup-worktree.sh: cannot resolve '$top/harness.config.json' — refusing to bootstrap" >&2
+  echo "  (no configuration there, invalid JSON, more than one document, no defaultBranch, or jq missing/older than 1.5)" >&2
+  exit 1
+fi
+
+# The main checkout is where every machine-local file has its single source: a
+# working copy created by git carries only tracked content.
+main_repo="$(hr_main_repo "$top")" || main_repo=""
+[ -n "$main_repo" ] || main_repo="$top"
+
+status=0
+
+# --- 1. Version manager, if this machine uses one. -------------------------
+vm_init="${HARNESS_VERSION_MANAGER_INIT:-}"
+if [ -n "$vm_init" ] && [ -r "$vm_init" ]; then
+  echo "setup-worktree.sh: sourcing version-manager init '$vm_init'"
+  # shellcheck source=/dev/null
+  . "$vm_init" || echo "setup-worktree.sh: version-manager init returned non-zero — continuing" >&2
+fi
+
+# --- 2. The machine-local client env file. ---------------------------------
+# `appDir` is repo-relative and defaults to `.`; joining it as `<root>/.` would
+# work but reads badly in every message below, so normalize it once.
+app_dir="$(hr_app_dir "$top")" || app_dir="."
+if [ "$app_dir" = "." ]; then
+  app_here="$top"
+  app_main="$main_repo"
+else
+  app_here="$top/$app_dir"
+  app_main="$main_repo/$app_dir"
+fi
+
+if [ -e "$app_here/.env" ]; then
+  : # this checkout has its own; never overwrite it
+elif [ -f "$app_main/.env" ]; then
+  if ln -s "$app_main/.env" "$app_here/.env"; then
+    echo "setup-worktree.sh: linked $app_here/.env -> $app_main/.env"
+  else
+    echo "setup-worktree.sh: could not link $app_here/.env — continuing" >&2
+  fi
+fi
+
+# --- 3. The test-account credentials, linked and never copied. -------------
+qa_creds="$(hr_qa_creds_path "$top")" || qa_creds=""
+if [ -n "$qa_creds" ]; then
+  if [ ! -e "$top/$qa_creds" ] && [ -f "$main_repo/$qa_creds" ]; then
+    mkdir -p "$(dirname "$top/$qa_creds")"
+    if ln -s "$main_repo/$qa_creds" "$top/$qa_creds"; then
+      echo "setup-worktree.sh: linked $top/$qa_creds -> $main_repo/$qa_creds"
+    else
+      echo "setup-worktree.sh: could not link $top/$qa_creds — continuing" >&2
+    fi
+  fi
+fi
+
+# --- 4. The pre-push backstop, for THIS working copy. ----------------------
+# All working copies of a repository share one `.git/config`, so a plain
+# `git config core.hooksPath` would write a single value every one of them
+# reads — while each has its own committed hooks directory at a DIFFERENT
+# absolute path. The value written here is therefore ABSOLUTE and
+# WORKTREE-SCOPED, so each working copy resolves to its own tracked hook.
+# Idempotent: both the `config` writes and the `chmod` are no-ops on a re-run.
+hooks_rel="$(hr_githooks_dir "$top")" || hooks_rel=""
+hooks_dir="$top/$hooks_rel"
+if [ -n "$hooks_rel" ] && [ -f "$hooks_dir/pre-push" ]; then
+  chmod +x "$hooks_dir/pre-push" || true
+  # NOTE: `extensions.worktreeConfig true` is a one-way, REPOSITORY-GLOBAL
+  # switch — once enabled it changes config resolution for EVERY working copy
+  # sharing this `.git`, including older ones that have not re-run this script.
+  # It is safe here because `core.hooksPath` is the only worktree-scoped value
+  # and every active working copy re-runs this script; keep that invariant if
+  # you add another `--worktree` setting.
+  if git -C "$top" config extensions.worktreeConfig true &&
+    git -C "$top" config --worktree core.hooksPath "$hooks_dir"; then
+    echo "setup-worktree.sh: pre-push hook installed (core.hooksPath -> $hooks_dir)"
+  else
+    echo "setup-worktree.sh: could not point core.hooksPath at $hooks_dir — this working copy has no pre-push backstop" >&2
+    status=1
+  fi
+else
+  echo "setup-worktree.sh: no pre-push hook at $hooks_dir — skipping hook install" >&2
+fi
+
+# --- 5. Dependencies, then the build. --------------------------------------
+# Run one configured command from the repository root. `commands.*` holds a raw
+# command LINE (the wrapper form is only used for the keys that have wrappers),
+# so it is evaluated — in a subshell, so the `cd` and anything the command sets
+# stay inside it, and in THIS shell's `eval` rather than a fresh `bash -c` so a
+# version manager's shell function from step 1 is still in scope.
+run_configured() {
+  local key="$1" label="$2" cmd cmd_status
+  cmd="$(hr_command "$top" "$key")"
+  cmd_status=$?
+  # The unresolvable case is tested FIRST: it also prints nothing, so folding it
+  # into the empty-value test would report a configuration this script could not
+  # read as an ordinary project with no such step.
+  if [ "$cmd_status" -eq 2 ]; then
+    echo "setup-worktree.sh: cannot resolve commands.$key — skipping $label" >&2
+    return 1
+  fi
+  if [ "$cmd_status" -ne 0 ] || [ -z "$cmd" ]; then
+    echo "setup-worktree.sh: commands.$key is not set — skipping $label"
+    return 0
+  fi
+  echo "setup-worktree.sh: $label: $cmd"
+  (
+    cd "$top" || exit 1
+    eval "$cmd"
+  )
+  cmd_status=$?
+  if [ "$cmd_status" -ne 0 ]; then
+    echo "setup-worktree.sh: $label failed (exit $cmd_status)" >&2
+    return 1
+  fi
+  return 0
+}
+
+deps_ok=1
+if ! run_configured depInstall "dependency install"; then
+  deps_ok=0
+  status=1
+fi
+
+if [ "$deps_ok" -eq 1 ]; then
+  if ! run_configured build "build"; then
+    status=1
+  fi
+else
+  echo "setup-worktree.sh: skipping build — the dependency install did not succeed" >&2
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "setup-worktree.sh: bootstrap complete for $top"
+else
+  echo "setup-worktree.sh: bootstrap finished with failures for $top (see above)" >&2
+fi
+exit "$status"

package/templates/scripts/start-dev-server.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Written by `autonomous-sdlc-harness init`, and yours from there on: edit it freely, a re-run
+# keeps your copy. It is what `commands.devServer` invokes: it starts the development server in
+# the background, from the repository root, and prints the pid and the log path a caller needs.
+#
+# Usage: start-dev-server.sh [port] [argument...]
+# The port is optional and must be numeric when it is given; anything else is a usage error, so a
+# mistyped port can never be passed through as a flag. It reaches the command on one channel only,
+# exported as HARNESS_DEV_SERVER_PORT: it is shifted off before the remaining arguments are
+# forwarded, so the raw command line below is never handed the port positionally. A server that
+# takes its port only as an argument has to be given that variable on the raw line below.
+#
+# This wrapper may run a build to completion before it launches, on the pre-start line below; that
+# line is yours to edit like every other, and `:` there means there is nothing to run.
+#
+# Nothing here inspects the port. A stack whose server silently falls through to port+1 when the
+# port is taken has to be told not to, and this wrapper is where you tell it: add its strict-port
+# flag to the raw command line below, or make the command that line runs fail on a taken port. A
+# QA run that quietly moved to another port drives a different run's server.
+
+# Deliberately no `-e`, for the same reason as the other wrappers. No captured status either:
+# a development server does not exit while it is doing its job.
+set -uo pipefail
+
+# Exit with a diagnostic and no pid line: nothing is running, so there is nothing to report. A
+# function rather than an inline `echo … && exit 1`, because the command line below is handed the
+# caller's arguments and `exit` refuses extra ones — `init` writes a call to it as that line when
+# no command line resolved.
+harness_fail() {
+  echo "$1" >&2
+  exit 1
+}
+
+port="${1:-}"
+if [ -n "$port" ]; then
+  case "$port" in
+    *[!0-9]*)
+      harness_fail "{{name}}: usage: start-dev-server.sh [port] (port must be numeric, got '${port}')"
+      ;;
+  esac
+  shift
+  export HARNESS_DEV_SERVER_PORT="$port"
+fi
+
+# Anchor to the repository root, derived from this script's own location and never from the
+# caller's directory: `commands.*` are command lines run from the repository root and every path
+# in `harness.config.json` is repo-relative. `git -C` on the script's own directory answers with
+# the checkout this copy belongs to, so all three forms the permission profile emits — the
+# repo-relative one, its absolute twin and a sibling worktree's own copy — run at the root of the
+# checkout they were invoked out of, whatever directory the caller stood in.
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(git -C "$script_dir" rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$repo_root" ] || ! cd "$repo_root"; then
+  harness_fail "{{name}}: could not resolve a repository root from '${script_dir}' (is git on PATH?)"
+fi
+
+# A step that has to finish before the server is launched — for a server that serves what was last
+# compiled, the project's own build. Synchronous and above the launch deliberately: the line below
+# is backgrounded and its `$!` is what a caller kills, and a build chained into it with `&&` would
+# make that pid a subshell the kill does not reach past. `:` when there is nothing to run.
+{{prestart}} || harness_fail "{{name}}: the pre-start step failed, so the server was not launched"
+
+# $TMPDIR ends in a trailing slash on macOS; strip it so the path carries no doubled separator.
+# With no port the log is the `-default` one, which is also the only case two runs can share.
+tmp_dir="${TMPDIR:-/tmp}"
+tmp_dir="${tmp_dir%/}"
+log_file="${tmp_dir}/harness-dev-server-${port:-default}.log"
+
+# Backgrounded rather than `exec`ed, which is the one behaviour a QA phase cannot do without: it
+# needs this shell back to poll the port and it needs a pid of its own to stop the server with,
+# and it needs somewhere to read a startup failure from — which is why both streams go to the log.
+{{command}} "$@" >"$log_file" 2>&1 &
+pid=$!
+
+# The only failure this script reports: the launch itself did not happen. A server that started
+# but is not answering yet is success — see the readiness note below.
+#
+# Liveness is the test, not `[ -z "$pid" ]`: `$!` is assigned the moment the job is backgrounded,
+# before the command has been resolved, so it is set even for a command that does not exist and an
+# emptiness test can never fire. The brief settle is what makes the liveness test mean anything —
+# immediately after the `&` the child has not been reaped yet and `kill -0` succeeds for a command
+# that was never found. It is NOT a readiness wait: readiness belongs to the poll named at the foot
+# of this script, and this only has to outlast a command that dies on the spot. Lengthen it if your
+# command forks through a launcher slow enough to be missed here.
+sleep 0.3
+if ! kill -0 "$pid" 2>/dev/null; then
+  harness_fail "{{name}}: the development server exited immediately — see $log_file"
+fi
+
+# The one wrapper with no PASS/FAIL verdict, because a long-running process has no verdict to
+# give. It reports what a caller has to hold instead: the pid to check liveness and to stop, and
+# the log to read a failed start out of.
+echo "STARTING: {{name}} (pid $pid)"
+echo "LOG: $log_file"
+
+# Readiness is deliberately not probed here. The poll already ships as a plugin asset —
+# `scripts/poll-dev-server.sh`, which the QA phase runs against the port once this returns — and a
+# second implementation of it inside a wrapper an adopter edits is how the two come to disagree.
+exit 0