Single-source the APS checkout under tmp/aps

There were up to four APS copies (tmp/aps, tmp/aps-spec, tmp/aps-fresh, and a
component-local client copy) and the briefing, wrappers, and runners disagreed
on which to use. Add ensure-aps.sh (ensure/update/reclone) as the one canonical
tmp/aps checkout, point the gherkin-parser wrapper, architect startup, and all
three acceptance runners at it, and update the architect cheat-sheet.

By specifier.

swarmforge/scripts/architect-startup.sh

@@ -17,7 +17,13 @@ ok()  { echo "  [ok]   $1"; pass=$((pass+1)); }
 bad() { echo "  [FAIL] $1"; fail=$((fail+1)); }
 
 echo "== Tool repos at latest upstream =="
-for d in tmp/aps-spec tmp/crap4javascript tmp/dry4javascript tmp/mutate4javascript; do
+# APS uses the single canonical checkout under tmp/aps; refresh it in place.
+if "$ROOT/swarmforge/scripts/ensure-aps.sh" --update >/dev/null 2>&1; then
+  ok "tmp/aps present"
+else
+  bad "tmp/aps ensure/update failed"
+fi
+for d in tmp/aps tmp/crap4javascript tmp/dry4javascript tmp/mutate4javascript; do
   if [ ! -d "$d/.git" ]; then
     bad "$d missing (reinstall per constitution)"; continue
   fi
@@ -56,13 +62,13 @@ fi
 
 echo "== APS Babashka tools =="
 if grep -q "usage: gherkin-parser" \
-    <<< "$(cd tmp/aps-spec && bb gherkin-parser 2>&1)"; then
+    <<< "$(cd tmp/aps && bb gherkin-parser 2>&1)"; then
   ok "gherkin-parser"
 else
   bad "gherkin-parser"
 fi
 if grep -qF -- "--runner-worker is required" \
-    <<< "$(cd tmp/aps-spec && bb gherkin-mutator 2>&1)"; then
+    <<< "$(cd tmp/aps && bb gherkin-mutator 2>&1)"; then
   ok "gherkin-mutator"
 else
   bad "gherkin-mutator"

swarmforge/scripts/ensure-aps.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Ensure the canonical Acceptance Pipeline Specification checkout at
+# <repo-root>/tmp/aps, and optionally update it to latest upstream.
+#
+# Usage:
+#   ensure-aps.sh            # ensure present only (no network if present)
+#   ensure-aps.sh --update   # fetch/reset to latest upstream default branch
+#   ensure-aps.sh --reclone  # delete and clone fresh
+#
+# Prints the checkout path on stdout. All APS consumers should use this path
+# (tmp/aps) so there is exactly one checkout.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+APS_URL="https://github.com/unclebob/Acceptance-Pipeline-Specification.git"
+
+mode="${1:-ensure}"
+case "$mode" in
+  ensure | --update | --reclone) ;;
+  *)
+    echo "usage: ensure-aps.sh [--update|--reclone]" >&2
+    exit 2
+    ;;
+esac
+
+common="$(git rev-parse --git-common-dir 2>/dev/null || true)"
+if [ -z "$common" ]; then
+  echo "ensure-aps: not in a git repository" >&2
+  exit 1
+fi
+common_abs="$(cd "$common" 2>/dev/null && pwd || true)"
+project_root="$(dirname "$common_abs")"
+APS_DIR="$project_root/tmp/aps"
+
+if [ "$mode" = "--reclone" ]; then
+  rm -rf "$APS_DIR"
+fi
+
+if [ ! -d "$APS_DIR/.git" ]; then
+  rm -rf "$APS_DIR"
+  mkdir -p "$(dirname "$APS_DIR")"
+  git clone --depth 1 "$APS_URL" "$APS_DIR" >&2
+elif [ "$mode" = "--update" ]; then
+  if git -C "$APS_DIR" fetch --depth 1 origin main:refs/remotes/origin/main >/dev/null 2>&1; then
+    git -C "$APS_DIR" reset --hard refs/remotes/origin/main >/dev/null 2>&1
+  elif git -C "$APS_DIR" fetch --depth 1 origin master:refs/remotes/origin/master >/dev/null 2>&1; then
+    git -C "$APS_DIR" reset --hard refs/remotes/origin/master >/dev/null 2>&1
+  else
+    echo "ensure-aps: update failed; using existing checkout" >&2
+  fi
+fi
+
+echo "$APS_DIR"

swarmforge/scripts/gherkin-parser

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Wrapper for the Babashka APS gherkin-parser task.
-# Delegates to the project-local APS checkout under ./tmp/aps-spec.
+# Delegates to the single canonical APS checkout under <repo-root>/tmp/aps.
 set -euo pipefail
 if [ "$#" -ne 2 ]; then
   echo "usage: gherkin-parser <feature-file> <json-output>" >&2
@@ -9,6 +9,6 @@ fi
 FEATURE_FILE="$(realpath -m "$1")"
 JSON_OUTPUT="$(realpath -m "$2")"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-APS_DIR="$(cd "$SCRIPT_DIR/../../tmp/aps-spec" && pwd)"
+APS_DIR="$("$SCRIPT_DIR/ensure-aps.sh")"
 cd "$APS_DIR"
 exec bb gherkin-parser "$FEATURE_FILE" "$JSON_OUTPUT"