@tyroneross/build-loop 0.35.0 → 0.36.0

package/hooks/route_guard.py

@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# route_guard.py — keep build/fix/refactor prompts routed to build-loop instead
+# of being hijacked by another plugin's coercive SessionStart injection
+# (notably superpowers:brainstorming, whose using-superpowers skill injects a
+# "brainstorming first, you MUST" block every session and out-ranks build-loop
+# in the model's skill routing).
+#
+# Two modes, one classifier (single source of truth for the build-signal regex):
+#
+#   prompt-submit  (UserPromptSubmit) — classify the submitted prompt, persist a
+#                  verdict to .build-loop/routing/last-verdict.json, and — only
+#                  when superpowers is installed and the prompt is build-shaped —
+#                  inject a short authoritative routing note. Fires AFTER all
+#                  SessionStart injections already sit in context, so it wins on
+#                  salience without a SessionStart-vs-SessionStart ordering race.
+#
+#   pre-skill      (PreToolUse, matcher "Skill") — if the model is about to invoke
+#                  superpowers:brainstorming while the current turn's verdict is
+#                  "build", DENY with a reason that redirects to build-loop. This
+#                  is the deterministic layer: it does not depend on the model
+#                  routing correctly; it catches the miss at the tool boundary.
+#
+# Design notes:
+#   * Fail-open ALWAYS. Any error -> emit nothing meaningful, exit 0. A routing
+#     guard must never break a session. See memory reference_hooks_minimal_path_failopen.
+#   * Advisory-by-design for legitimate ideation: a prompt that explicitly asks
+#     to brainstorm/ideate classifies as passthrough, so an intentional
+#     brainstorming request is never blocked ("named override").
+#   * Opt out with BUILD_LOOP_ROUTE_GUARD=off (mirrors RALLY_HOOKS=off).
+
+import glob
+import json
+import os
+import re
+import sys
+import time
+
+VERDICT_TTL_SECONDS = 2 * 60 * 60  # a verdict older than this can never block
+GUARDED_SKILLS = {"superpowers:brainstorming"}
+
+# Build / fix / refactor intent — mirrors build-loop's own SKILL trigger vocab.
+_BUILD_RE = re.compile(
+    r"\b(build|implement|creat(e|ing)|add(ing)?|ship|wire\s*up|wire|integrat(e|ing)|"
+    r"refactor|migrat(e|ing)|rewrit(e|ing)|replac(e|ing)|scaffold|set\s*up|"
+    r"fix(ing)?|broken|debug|doesn'?t\s+work|isn'?t\s+(work|load|display)|"
+    r"not\s+(work|load|display|render)|should\s+(show|display|be)|needs?\s+to|make\s+it)\b",
+    re.IGNORECASE,
+)
+
+# Explicit ideation intent — user WANTS open-ended thinking. Suppresses routing
+# even if build verbs are also present ("named override").
+_IDEATION_RE = re.compile(
+    r"\b(brainstorm(ing)?|ideat(e|ion)|explore\s+ideas?|think\s+through|"
+    r"weigh\s+(the\s+)?options|options\s+for|what\s+should|help\s+me\s+decide|"
+    r"pros\s+and\s+cons|design\s+options|figure\s+out\s+what)\b",
+    re.IGNORECASE,
+)
+
+ROUTING_NOTE = (
+    "[build-loop routing] This looks like a build/fix/refactor task. Enter via "
+    "/build-loop:build-loop, which runs its own assess->plan phases. Do NOT "
+    "auto-invoke superpowers:brainstorming (or other superpowers process skills) "
+    "for this unless the user names it explicitly."
+)
+
+DENY_REASON = (
+    "build-loop owns build/fix/refactor routing in this repo, and the current "
+    "prompt was classified as a build task (not an explicit ideation request). "
+    "Route via /build-loop:build-loop instead of superpowers:brainstorming. If "
+    "the user actually asked to brainstorm, re-read the prompt and proceed; if "
+    "this guard is unwanted, set BUILD_LOOP_ROUTE_GUARD=off."
+)
+
+
+def _read_stdin():
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def _is_build(prompt: str) -> bool:
+    if not prompt:
+        return False
+    if _IDEATION_RE.search(prompt):
+        return False
+    return bool(_BUILD_RE.search(prompt))
+
+
+def _project_dir(payload) -> str:
+    return (
+        os.environ.get("CLAUDE_PROJECT_DIR")
+        or payload.get("cwd")
+        or os.getcwd()
+    )
+
+
+def _verdict_path(payload):
+    proj = _project_dir(payload)
+    if not proj:
+        return None
+    return os.path.join(proj, ".build-loop", "routing", "last-verdict.json")
+
+
+def _superpowers_installed() -> bool:
+    home = os.path.expanduser("~")
+    patterns = [
+        os.path.join(home, ".claude", "plugins", "cache", "*", "superpowers"),
+        os.path.join(home, ".claude", "plugins", "*", "superpowers"),
+        os.path.join(home, ".claude", "plugins", "*superpowers*"),
+    ]
+    for pat in patterns:
+        if glob.glob(pat):
+            return True
+    return False
+
+
+def _emit(obj):
+    try:
+        sys.stdout.write(json.dumps(obj))
+    except Exception:
+        sys.stdout.write("{}")
+
+
+def mode_prompt_submit(payload):
+    prompt = payload.get("prompt", "") or ""
+    is_build = _is_build(prompt)
+
+    # Persist verdict for the pre-skill guard (best-effort).
+    path = _verdict_path(payload)
+    if path:
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w") as fh:
+                json.dump(
+                    {
+                        "verdict": "build" if is_build else "passthrough",
+                        "ts": int(time.time()),
+                        "prompt": prompt[:200],
+                    },
+                    fh,
+                )
+        except Exception:
+            pass
+
+    # Proactively bias routing only when there's a real conflict to resolve.
+    if is_build and _superpowers_installed():
+        _emit(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": ROUTING_NOTE,
+                }
+            }
+        )
+    else:
+        sys.stdout.write("{}")
+
+
+def mode_pre_skill(payload):
+    tool = payload.get("tool_name") or payload.get("tool") or ""
+    if tool != "Skill":
+        sys.stdout.write("{}")
+        return
+
+    tool_input = payload.get("tool_input") or {}
+    skill = (tool_input.get("skill") or tool_input.get("name") or "").strip()
+    if skill not in GUARDED_SKILLS:
+        sys.stdout.write("{}")
+        return
+
+    # Only deny when the current turn was classified as a build task.
+    path = _verdict_path(payload)
+    verdict = None
+    if path and os.path.exists(path):
+        try:
+            with open(path) as fh:
+                data = json.load(fh)
+            if int(time.time()) - int(data.get("ts", 0)) <= VERDICT_TTL_SECONDS:
+                verdict = data.get("verdict")
+        except Exception:
+            verdict = None
+
+    if verdict == "build":
+        _emit(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": DENY_REASON,
+                }
+            }
+        )
+    else:
+        sys.stdout.write("{}")
+
+
+def main():
+    # Escape hatch + hard fail-open wrapper.
+    if os.environ.get("BUILD_LOOP_ROUTE_GUARD", "").lower() == "off":
+        sys.stdout.write("{}")
+        return
+    try:
+        mode = sys.argv[1] if len(sys.argv) > 1 else ""
+        payload = _read_stdin()
+        if mode == "prompt-submit":
+            mode_prompt_submit(payload)
+        elif mode == "pre-skill":
+            mode_pre_skill(payload)
+        else:
+            sys.stdout.write("{}")
+    except Exception:
+        # Never break a session over a routing hint.
+        sys.stdout.write("{}")
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session-start-extensions.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+set -u
+PY="$(command -v python3 || true)"; [ -z "$PY" ] && exit 0
+ROOT="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}"
+N="$("$PY" "$ROOT/scripts/extensions_pending_count.py" 2>/dev/null || echo 0)"
+if [ "${N:-0}" -gt 0 ] 2>/dev/null; then
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"build-loop: %s pending extension draft(s) await review — run: python3 %s/scripts/extensions_approve.py --list"}}\n' "$N" "$ROOT"
+fi
+exit 0

package/hooks/session-start-git-hooks.sh

@@ -1,7 +1,11 @@
 #!/usr/bin/env bash
 # SPDX-License-Identifier: Apache-2.0
 # Auto-install build-loop git hooks on session start (idempotent).
-# Installs: pre-push (push-HOLD gate).
+# Installs: pre-push (deploy-HOLD gate + deterministic pre-push TEST gate, composed
+# in one hook body — the test gate added per the 2026-06-29 RCA so new sessions get
+# the prevent-before-merge control automatically) + the artifact-guard pre-commit segment
+# (regenerate-and-restage checked-in artifacts; block undeclared third-party
+# imports — chained so it coexists with the rally-point private-slug segment).
 # Skips silently when: not inside a git repo, Python unavailable, hook
 # source not found, or a foreign (non-build-loop) pre-push is already
 # installed (requires --force to overwrite; we never force on auto-install).
@@ -9,4 +13,5 @@ PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-$PWD}}"
 cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 0
 git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 python3 "${PLUGIN_ROOT}/scripts/install_git_hooks.py" --install >/dev/null 2>&1 || true
+python3 "${PLUGIN_ROOT}/scripts/artifact_guard.py" --install-hook >/dev/null 2>&1 || true
 exit 0

package/hooks/session-start-rally-point.sh

@@ -38,7 +38,29 @@ else
         --workdir "$W" --tool claude_code --mode hook --start-watch >/dev/null 2>&1 || true
 fi
 
-# Step 3: advance cursor past probe's own writes (silent; same script, no VERBOSE).
+# Step 3: opportunistic reaper sweep — physical cleanup of over-TTL presence/claims/lead.
+# Fire-and-forget: never blocks, exit 0 preserved. Python fallback path (actuator).
+[ -f "$PKG/reaper.py" ] && python3 "$PKG/reaper.py" --workdir "$W" --apply >/dev/null 2>&1 || true
+
+# Step 4: advance cursor past probe's own writes (silent; same script, no VERBOSE).
 python3 "$PKG/hooks.py" session-start-advance --workdir "$W" 2>/dev/null || true
 
+# Step 5: on-PATH-vs-pin rally version staleness guard (lane E-a). This is
+# the control that would have caught the rally version-mismatch incident:
+# warn (never block) when the `rally` binary resolved from PATH is not the
+# version build-loop is pinned to. NON-BLOCKING + fail-open — on any error
+# (rally absent, python3 failure, unparseable output) this silently no-ops
+# and NEVER affects the hook's exit code.
+if command -v rally >/dev/null 2>&1; then
+    _rally_raw_ver="$(rally version 2>&1 | head -n1)"
+    _rally_on_path_ver="${_rally_raw_ver#rally }"
+    _rally_on_path_ver="${_rally_on_path_ver%%+*}"
+    _rally_on_path_ver="$(printf '%s' "$_rally_on_path_ver" | tr -d '[:space:]')"
+    _rally_pinned_ver="$(python3 "$PKG/binary_fetch.py" --print-pin 2>/dev/null | tr -d '[:space:]')"
+    if [ -n "$_rally_on_path_ver" ] && [ -n "$_rally_pinned_ver" ] \
+        && [ "$_rally_on_path_ver" != "$_rally_pinned_ver" ]; then
+        echo "[rally] WARN: on-PATH rally ${_rally_on_path_ver} != pinned ${_rally_pinned_ver} — run 'python3 scripts/rally_point/binary_fetch.py --force' to reconcile" >&2
+    fi
+fi
+
 exit 0

package/hooks/test_session_start_rally_version.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+# Fixture-driven tests for the on-PATH-vs-pin rally version staleness guard
+# (lane E-a) added to session-start-rally-point.sh Step 5. This is the
+# control that would have caught the rally version-mismatch incident: the
+# guard must be NON-BLOCKING and fail-open in every case below — it must
+# NEVER affect the hook's exit code, whether rally is absent, matches the
+# pin, or is stale.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+SS_HOOK="${SCRIPT_DIR}/session-start-rally-point.sh"
+PKG="${REPO_ROOT}/scripts/rally_point"
+
+PASS=0
+FAIL=0
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
+
+# Resolve the REAL pinned version from binary_fetch.py so this test tracks
+# the pin instead of hardcoding a copy that can silently drift.
+PINNED_VER="$(python3 - <<PYEOF
+import sys
+sys.path.insert(0, "${REPO_ROOT}/scripts")
+from rally_point import binary_fetch as bf
+print(bf.PINNED_VERSION)
+PYEOF
+)"
+if [ -z "$PINNED_VER" ]; then
+  echo "FAIL: setup — could not resolve PINNED_VERSION from binary_fetch.py"
+  exit 1
+fi
+
+REPO=$(mktemp -d)
+APPS=$(mktemp -d)
+( cd "$REPO" && git init -q && git config user.email t@e.com && git config user.name t )
+export BUILD_LOOP_APPS_ROOT="$APPS"
+export BUILD_LOOP_BRIDGE_INTERNAL_ONLY=1
+export BUILD_LOOP_RALLY_POINT_SKIP_WATCH=1
+export CLAUDE_PROJECT_DIR="$REPO"
+
+STUBBIN=$(mktemp -d)
+# Isolated PATH: the stub bin dir first, then just enough of the real system
+# to run python3/git/bash — deliberately excludes any real `rally` that may
+# be installed on this machine's normal PATH (e.g. ~/.local/bin/rally).
+PYTHON3_DIR="$(dirname "$(command -v python3)")"
+GIT_DIR="$(dirname "$(command -v git)")"
+ISOLATED_PATH="$STUBBIN:$PYTHON3_DIR:$GIT_DIR:/usr/bin:/bin"
+
+write_stub_rally() {
+  # $1 = version string the stub's "version" subcommand should print
+  local ver="$1"
+  cat > "$STUBBIN/rally" <<STUBEOF
+#!/usr/bin/env bash
+if [ "\$1" = "version" ]; then
+  echo "rally ${ver}"
+fi
+exit 0
+STUBEOF
+  chmod +x "$STUBBIN/rally"
+}
+
+run_hook_stderr() {
+  PATH="$ISOLATED_PATH" bash "$SS_HOOK" 2>&1 1>/dev/null </dev/null
+}
+
+run_hook_rc() {
+  PATH="$ISOLATED_PATH" bash "$SS_HOOK" >/dev/null 2>&1 </dev/null
+  echo $?
+}
+
+# ---- Case 1: on-PATH version matches the pin -> no WARN, exit 0 --------
+write_stub_rally "${PINNED_VER}+deadbeef"
+ERR=$(run_hook_stderr)
+RC=$(run_hook_rc)
+if [ "$RC" -eq 0 ] && ! printf '%s' "$ERR" | grep -q "WARN"; then
+  pass "matching on-PATH version: no WARN, exit 0"
+else
+  fail "matching version case" "rc=$RC stderr='$ERR'"
+fi
+
+# ---- Case 2: on-PATH version mismatches the pin -> WARN line, exit 0 ---
+write_stub_rally "9.9.9+deadbeef"
+ERR=$(run_hook_stderr)
+RC=$(run_hook_rc)
+if [ "$RC" -eq 0 ] \
+    && printf '%s' "$ERR" | grep -q "\[rally\] WARN:" \
+    && printf '%s' "$ERR" | grep -q "9.9.9" \
+    && printf '%s' "$ERR" | grep -q "${PINNED_VER}"; then
+  pass "mismatched on-PATH version: WARN line present, exit 0"
+else
+  fail "mismatched version case" "rc=$RC stderr='$ERR'"
+fi
+
+# ---- Case 3: rally absent from PATH -> no crash, no WARN, exit 0 -------
+rm -f "$STUBBIN/rally"
+ERR=$(run_hook_stderr)
+RC=$(run_hook_rc)
+if [ "$RC" -eq 0 ] && ! printf '%s' "$ERR" | grep -q "WARN"; then
+  pass "rally absent from PATH: no crash, no WARN, exit 0"
+else
+  fail "rally absent case" "rc=$RC stderr='$ERR'"
+fi
+
+# ---- Case 4: rally on PATH but `rally version` itself errors (exit 1,
+# empty output) -> guard silently no-ops, exit 0 preserved. ---------------
+cat > "$STUBBIN/rally" <<'STUBEOF'
+#!/usr/bin/env bash
+exit 1
+STUBEOF
+chmod +x "$STUBBIN/rally"
+ERR=$(run_hook_stderr)
+RC=$(run_hook_rc)
+if [ "$RC" -eq 0 ] && ! printf '%s' "$ERR" | grep -q "WARN"; then
+  pass "rally version errors: no crash, no WARN, exit 0"
+else
+  fail "rally version error case" "rc=$RC stderr='$ERR'"
+fi
+
+echo "Results: ${PASS} passed, ${FAIL} failed"
+[ "$FAIL" -eq 0 ] || exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyroneross/build-loop",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",
     "access": "public"
@@ -8,6 +8,9 @@
   "description": "Multi-phase build orchestration with integrated debugging: assess, plan, execute, review, iterate.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "bin": {
+    "build-loop-install": "bin/build-loop-install.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
@@ -17,8 +20,10 @@
   },
   "files": [
     "dist",
+    "bin",
     "codex-skills",
     "plugin-artifacts/codex",
+    "assets",
     "commands",
     "skills",
     "scripts/_paths.py",
@@ -58,7 +63,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "prepublishOnly": "npm run build",
-    "test": "python3 -m unittest scripts/test_commit_state_check.py scripts/test_bridge_preflight.py scripts/test_mcp_registration.py && bash scripts/hooks/test_hooks.sh",
+    "test": "python3 -m unittest scripts/test_commit_state_check.py scripts/test_bridge_preflight.py scripts/test_mcp_registration.py scripts/test_build_loop_install_cli.py && bash scripts/hooks/test_hooks.sh",
     "benchmark": "node benchmark-scoring.js",
     "clean": "rm -rf dist",
     "plugin:prune-cache": "python3 scripts/prune_plugin_cache.py --source .",

package/plugin-artifacts/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "build-loop",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
   "author": {
     "name": "Tyrone Ross",