@tyroneross/build-loop 0.35.0 → 0.36.0

package/agents/root-cause-investigator.md

@@ -2,6 +2,8 @@
 name: root-cause-investigator
 description: Use this agent when a debugging symptom needs deep causal analysis beyond surface-level diagnosis. Builds a causal tree (not a single chain) to explore multiple potential root causes in parallel. Flags when investigation reaches external/environmental boundaries or when internet research is needed. Examples - "why does this keep failing", "what's the real cause", "dig deeper into this error", "this fix didn't stick".
 model: inherit
+tier: inherit
+segment: inherit
 color: red
 tools: ["Read", "Grep", "Bash", "Glob", "WebSearch"]
 ---
@@ -30,6 +32,8 @@ Instead, build a **causal tree**: at each level, identify ALL plausible causes,
 
 ## Your Core Responsibilities
 
+> **Durable post-failure RCA:** for the blameless durable-lever pass (creation+escape paths, action-strength hierarchy, lever+actuator, regression artifact, spread check), delegate to the shared `references/root-cause-analysis/` suite. This skill/agent finds and fixes the live issue; that suite is the post-failure prevention layer.
+
 1. Build a causal tree — at each node, identify multiple possible causes before pursuing any
 2. Investigate branches by evidence strength, not by order of appearance
 3. Determine when the real root cause is found (it explains ALL symptoms)
@@ -66,6 +70,12 @@ SYMPTOM: API returns empty array for search
 - If I ruled out my first guess, what would I investigate next?
 - Could this be caused by something upstream? Downstream? Environmental?
 
+**Trace two distinct axes, not one chain — creation and escape:**
+- **Creation** — why did the defect exist at all? (its origin)
+- **Escape** — why did no control catch it before it reached the surface? (the detection gap)
+
+A bug often needs both fixed, and a single chain nudges toward fixing only one. Worked example: a value was computed wrong (`int(dict)→0` — *creation*) AND the test injected that value by hand, so the gate's blindness to the real shape never surfaced (*escape*). Fixing only the gate, or only the writer, leaves half the bug live.
+
 ### Step 3: Prioritize — Rank Branches by Evidence
 
 Before investigating any branch, quickly assess each:
@@ -122,7 +132,7 @@ Add environment findings as branches in the causal tree with `evidence_type: "en
 
 Stop investigating a branch when you reach one of:
 
-- **Actionable system cause**: A concrete, fixable control failure (missing check, weak contract, ambiguous ownership, stale model/cache, missing feedback, wrong assumption) with evidence
+- **Actionable system cause that passes the counterfactual**: A concrete, fixable control failure (missing check, weak contract, ambiguous ownership, stale model/cache, missing feedback, wrong assumption) with evidence — **and it is not closed until the named lever + actuator would have prevented, detected, or contained THIS exact failure before it reached the surface.** State this as a one-line counterfactual with the evidence that the lever fires on the *real* input, not a hand-constructed one. A control that is "actionable" but dormant on the real signal — a rule that exists yet never fires on the actual phrasing/shape that triggered the bug — does NOT close the branch. (Observed: a shipped `activation-map-required` rule was dormant on 2 of its 4 motivating phrasings; the counterfactual is the test that catches that.)
 - **External boundary**: The cause is outside the codebase (OS behavior, library bug, third-party API change) — document and flag
 - **Depth limit**: After 5 levels deep on any branch, the problem may be architectural — report findings and recommend broader investigation
 - **All branches pruned**: Every plausible cause has been rejected with evidence — the symptom may have an unusual or environmental cause. Flag for user input
@@ -167,6 +177,28 @@ Common traps where surface-level diagnosis stops too early:
 | "The component re-renders" | Why does the dependency change? | Object identity not stable across renders |
 | "It works locally but not in CI" | What differs between environments? | Missing env var in CI config |
 
+## Fix Strength — Prefer the Stronger Control (W3)
+
+When you name the `prevention_control`, prefer the strongest *feasible* rung — do not default to "add a detect-gate." Strength order, strongest first:
+
+1. **eliminate** — remove the failure mode entirely (delete the code path / dependency)
+2. **impossible-state** — make the invalid state unrepresentable (normalize at the *writer* so the bad shape can never exist, vs. coercing at the gate)
+3. **automated-block** — a gate that hard-fails the bad input before it propagates
+4. **detect** — surface/alert on the bad state after it occurs
+5. **contain** — limit blast radius (isolate, validate, monitor, degrade gracefully, escalate, or accept residual risk *explicitly*)
+6. **decision-support** — give a human the signal to decide
+7. **docs** — record the hazard for future readers
+
+Name the rung you chose in `fix_strength` and, if you did not pick the strongest, say why it was infeasible. **Never** route a dependency you don't own to "ignore it" — route it to isolate / validate / monitor / degrade / escalate / accept-residual-risk-explicitly.
+
+## Root-Cause Layer — Classify the Origin (W4)
+
+For each confirmed root cause, classify its true origin layer (where the defect was *born*, not where the symptom surfaced) as exactly one of:
+
+`input-data` · `requirements-spec` · `prompt-instruction` · `model-reasoning` · `tool-api` · `state-memory-cache` · `orchestration-workflow` · `permission-security` · `test-eval-gate` · `observability-alerting` · `human-handoff-process` · `external-dependency`
+
+A multi-root tree carries one layer per confirmed branch. This field lets `recurring-pattern-detector` surface a project-shaped blind spot (e.g. three `test-eval-gate` roots across runs → fixtures are the systemic weak point) that free-text `root_cause` cannot cluster.
+
 ## Output Format
 
 Return a structured JSON assessment:
@@ -183,8 +215,13 @@ Return a structured JSON assessment:
   },
   "tradeoffs": "What the fix improves, what it risks, and what it does not solve",
   "impact": "User impact, engineering impact, recurrence risk",
-  "prevention_control": "Durable control: test, verifier, lint, trace, smoke gate, protocol, memory, or routing rule",
+  "prevention_control": "Durable control: test, verifier, lint, trace, smoke gate, protocol, memory, or routing rule — at the strongest feasible rung (see Fix Strength)",
   "system_control_failure": "The first controllable system control that failed or was missing",
+  "counterfactual": "If <lever+actuator> had existed, it would have <prevented|detected|contained> this because <evidence the lever fires on the REAL input, not a hand-constructed one>",
+  "creation_path": "Why the defect existed at all — the origin axis",
+  "escape_path": "Why no control caught it before the surface — the detection axis",
+  "fix_strength": "eliminate | impossible-state | automated-block | detect | contain | decision-support | docs — the rung of prevention_control; if not the strongest, why the stronger rung was infeasible",
+  "root_cause_layer": "input-data | requirements-spec | prompt-instruction | model-reasoning | tool-api | state-memory-cache | orchestration-workflow | permission-security | test-eval-gate | observability-alerting | human-handoff-process | external-dependency",
   "failure_map": [
     "User-visible symptom",
     "Immediate technical failure",

package/agents/scope-auditor.md

@@ -2,6 +2,8 @@
 name: scope-auditor
 description: Read-only Plan→Execute boundary check. For every commit that changes a public function/component/type signature, traces every caller-site outside the commit's owned-files, then either confirms `internal_only: true` or appends the missing caller files to the appropriate commit's owned-files list. Prevents the "fan-out scope-blindness" defect class observed in round-2 of dispatch-pattern testing (example-app 2026-05-07).
 model: fable
+tier: frontier
+segment: governance_evaluation
 tools: ["Read", "Grep", "Glob"]
 ---
 

package/agents/security-reviewer.md

@@ -15,6 +15,8 @@ description: |
   assistant: "I'll use the security-reviewer agent — diff vs OWASP Web A01/A03 + LLM06 + ASI03 — and emit a structured findings report."
   </example>
 model: fable
+tier: frontier
+segment: governance_evaluation
 color: red
 tools: ["Read", "Grep", "Glob"]
 ---
@@ -91,6 +93,7 @@ Severity rules:
 1. Read `.build-loop/state.json.triggers`. If `riskSurfaceChange` is not true, emit `{"findings": [], "skipped_reason": "..."}` and stop.
 2. Read `.build-loop/goal.md` and `.build-loop/intent.md` — orient on what was supposed to change.
 3. Load `Skill("build-loop:security-methodology")`. Read the cross-source matrix and the detection-pattern files for the OWASP layer that applies (LLM Top 10 always; Agentic Top 10 when an agent or tool was added; Web Top 10 when an HTTP endpoint changed).
+3b. **Required route-auth enumeration (LO-5, A01).** When any HTTP endpoint changed, do not sample — **walk every** `app/api/**/route.ts` (or framework equivalent) mutating/DDL handler and confirm each has an auth guard that **fails closed** when its secret env is unset (the `token !== process.env.X` bypass: if `X` is undefined the check passes). This access-control sweep is the counterpart to `database-assessor`'s destructive-FK sweep — neither lens is a superset (atomize-ai 2026-06-30: 8 A/B runs here missed a destructive cascade; a DB-RCA missed 4 unauth routes). Lead findings with a blast-radius verdict per the methodology's SC-1 default.
 4. Get the file list from the orchestrator's dispatch packet. Read each changed file; do not scan files outside the chunk.
 5. For each change, walk the table above. When a row matches, draft a finding with mandatory fields below.
 6. Cross-reference each finding against `skills/security-methodology/references/cross-source-matrix.md` to assign `mapped_risks`. If no row in the matrix applies, the finding is not security — drop it (other agents handle non-security drift).

package/agents/self-improvement-architect.md

@@ -15,6 +15,8 @@ description: |
   assistant: "I'll use the self-improvement-architect agent to draft the agent definition."
   </example>
 model: sonnet
+tier: code
+segment: generative_reasoning
 color: cyan
 tools: ["Read", "Write", "Edit", "Glob", "Grep", "Skill"]
 ---

package/agents/synthesis-critic.md

@@ -15,6 +15,8 @@ description: |
   assistant: "I'll use the synthesis-critic agent to read the diff against the claimed copy_tone register and empty-state pattern, returning a JSON verdict (pass | flag) without blocking."
   </example>
 model: sonnet
+tier: code
+segment: governance_evaluation
 color: cyan
 tools: ["Read", "Glob", "Grep"]
 ---

package/agents/transcript-pattern-miner.md

@@ -21,6 +21,8 @@ description: |
   assistant: "I'll use the transcript-pattern-miner agent. Section 5 of its report is a rotation tracker — truncated previews, first-seen and last-seen dates, project context."
   </example>
 model: haiku
+tier: pattern
+segment: generative_reasoning
 color: cyan
 tools: ["Bash", "Read"]
 ---

package/agents/ui-validator.md

@@ -15,6 +15,8 @@ description: |
   assistant: "I'll use the ui-validator agent — build-loop's owned UI validation path — and return route-level evidence without routing through IBR."
   </example>
 model: sonnet
+tier: code
+segment: agentic_execution
 color: blue
 tools: ["Read", "Bash", "Grep", "Glob"]
 ---

package/bin/build-loop-install.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+// SPDX-License-Identifier: Apache-2.0
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+
+function usage() {
+  return `build-loop-install
+
+Install build-loop from this npm package into local agent caches.
+
+Usage:
+  build-loop-install [options]
+
+Options:
+  --host <all|claude|codex>   Agent host cache to sync (default: all)
+  --project <slug>            Ensure a project memory scaffold
+  --memory-dest <path>        Override build-loop memory root
+  --skip-memory               Do not bootstrap build-loop memory
+  --dry-run                   Show cache sync actions without writing
+  --no-verify                 Skip post-sync cache verification
+  --allow-non-mac             Suppress the macOS platform warning
+  --json                      Emit one machine-readable JSON result
+  -h, --help                  Show help
+`;
+}
+
+function parseArgs(argv) {
+  const args = {
+    host: "all",
+    projects: [],
+    memoryDest: null,
+    skipMemory: false,
+    dryRun: false,
+    noVerify: false,
+    allowNonMac: false,
+    json: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) {
+        throw new Error(`${arg} requires a value`);
+      }
+      return argv[i];
+    };
+
+    if (arg === "-h" || arg === "--help") {
+      args.help = true;
+    } else if (arg === "--host") {
+      args.host = next();
+    } else if (arg === "--project") {
+      args.projects.push(next());
+    } else if (arg === "--memory-dest") {
+      args.memoryDest = next();
+    } else if (arg === "--skip-memory") {
+      args.skipMemory = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--no-verify") {
+      args.noVerify = true;
+    } else if (arg === "--allow-non-mac") {
+      args.allowNonMac = true;
+    } else if (arg === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+
+  if (!["all", "claude", "codex"].includes(args.host)) {
+    throw new Error("--host must be one of: all, claude, codex");
+  }
+
+  return args;
+}
+
+function findPython() {
+  for (const candidate of ["python3", "python"]) {
+    const probe = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+    if (probe.status === 0) {
+      return candidate;
+    }
+  }
+  throw new Error("python3 is required to install build-loop");
+}
+
+function parseJsonMaybe(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch (_err) {
+    return trimmed;
+  }
+}
+
+function runStep(label, command, commandArgs, options) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: root,
+    encoding: "utf8",
+  });
+
+  const step = {
+    label,
+    command: [command, ...commandArgs],
+    exitCode: result.status,
+    ok: result.status === 0,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+
+  if (options.json) {
+    step.parsedStdout = parseJsonMaybe(step.stdout);
+    return step;
+  }
+
+  process.stdout.write(`\n== ${label} ==\n`);
+  if (step.stdout) {
+    process.stdout.write(step.stdout);
+    if (!step.stdout.endsWith("\n")) process.stdout.write("\n");
+  }
+  if (step.stderr) {
+    process.stderr.write(step.stderr);
+    if (!step.stderr.endsWith("\n")) process.stderr.write("\n");
+  }
+  if (!step.ok) {
+    process.stderr.write(`${label} failed with exit ${step.exitCode}\n`);
+  }
+  return step;
+}
+
+function syncArgs({ host, source, args }) {
+  const cmd = [
+    path.join(root, "scripts", "sync_plugin_cache.py"),
+    "--source",
+    source,
+    "--host",
+    host,
+    "--marketplace",
+    "build-loop",
+    "--dirty",
+  ];
+  if (args.dryRun) cmd.push("--dry-run");
+  if (args.noVerify) cmd.push("--no-verify");
+  if (args.json) cmd.push("--json");
+  return cmd;
+}
+
+function memoryArgs(args) {
+  const cmd = [path.join(root, "scripts", "install_memory.py")];
+  if (args.memoryDest) {
+    cmd.push("--dest", args.memoryDest);
+  }
+  for (const project of args.projects) {
+    cmd.push("--ensure-project", project);
+  }
+  return cmd;
+}
+
+function hostsFor(host) {
+  return host === "all" ? ["claude", "codex"] : [host];
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${usage()}`);
+    return 2;
+  }
+
+  if (args.help) {
+    process.stdout.write(usage());
+    return 0;
+  }
+
+  const python = findPython();
+  const steps = [];
+  const codexArtifact = path.join(root, "plugin-artifacts", "codex");
+
+  if (process.platform !== "darwin" && !args.allowNonMac && !args.json) {
+    process.stderr.write(
+      "warning: this installer is optimized for macOS agent cache paths; continuing on this platform.\n"
+    );
+  }
+
+  for (const host of hostsFor(args.host)) {
+    const source = host === "codex" && fs.existsSync(codexArtifact) ? codexArtifact : root;
+    steps.push(
+      runStep(`sync ${host} plugin cache`, python, syncArgs({ host, source, args }), args)
+    );
+  }
+
+  if (!args.skipMemory && !args.dryRun) {
+    steps.push(runStep("bootstrap build-loop memory", python, memoryArgs(args), args));
+  } else if (args.dryRun && !args.json) {
+    process.stdout.write("\n== bootstrap build-loop memory ==\nskipped during --dry-run\n");
+  }
+
+  const payload = {
+    ok: steps.every((step) => step.ok),
+    packageRoot: root,
+    platform: process.platform,
+    host: args.host,
+    memory: args.skipMemory ? "skipped" : args.dryRun ? "dry-run-skipped" : "bootstrapped",
+    steps,
+  };
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  }
+
+  return payload.ok ? 0 : 1;
+}
+
+try {
+  process.exitCode = main();
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exitCode = 1;
+}

package/commands/run.md

@@ -1,5 +1,5 @@
 ---
-description: "The single entry for any coding task — build, fix, refactor, optimize, research, or test. Auto-routes to the right mode; you don't pick."
+description: "The one build-loop command. Describe anything in plain language — build, fix, debug, optimize, research, test, root-cause, retrospective, plan, PRD — and it routes automatically. You never pick a mode."
 argument-hint: "[--parallel] [goal description]"
 ---
 

package/hooks/git/pre-commit

@@ -0,0 +1,40 @@
+#!/bin/sh
+# build-loop:artifact-guard-pre-commit
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# Drift-prevention pre-commit. Two scoped guards (systems-not-discipline):
+#   1. artifact_guard --staged: when a checked-in generated artifact's watched
+#      source paths are staged, regenerate + re-stage it so drift cannot be
+#      committed (architecture diagram, Codex plugin artifact; registry-driven).
+#   2. import_manifest_lint: block a commit that adds an undeclared third-party
+#      import (the pyyaml-outage class), only when a .py file is staged.
+# The artifact guard is scoped to staged watched paths; the import lint
+# runs only when a .py is staged. Set BL_ARTIFACT_ADVISORY=1 to warn instead
+# of regenerate/block (covers BOTH guards). Unrelated commits run nothing.
+#
+# Installed (chained, coexisting with other pre-commit segments — e.g. the
+# rally-point private-slug guard) by:
+#   python3 scripts/artifact_guard.py --install-hook
+# Auto-installed on session start via hooks/session-start-git-hooks.sh.
+# --- BEGIN build-loop artifact-guard pre-commit ---
+BL_AG_TOP="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -n "$BL_AG_TOP" ] && [ -f "$BL_AG_TOP/scripts/artifact_guard.py" ]; then
+  python3 "$BL_AG_TOP/scripts/artifact_guard.py" --staged || exit 1
+  if [ -f "$BL_AG_TOP/scripts/import_manifest_lint.py" ] && \
+     git diff --cached --name-only | grep -q '\.py$'; then
+    if [ "${BL_ARTIFACT_ADVISORY:-0}" = "1" ]; then
+      python3 "$BL_AG_TOP/scripts/import_manifest_lint.py" || true
+    else
+      python3 "$BL_AG_TOP/scripts/import_manifest_lint.py" --quiet
+      bl_imp_rc=$?
+      # Block only on a real finding (exit 1). Exit 2 means the lint itself
+      # could not run (e.g. interpreter < 3.11, no tomllib) — fail open with
+      # the message already on stderr rather than block an unrelated commit;
+      # the non-bypassable pytest.yml step remains the hard backstop.
+      [ "$bl_imp_rc" -eq 1 ] && exit 1
+    fi
+  fi
+fi
+# --- END build-loop artifact-guard pre-commit ---
+exit 0

package/hooks/git/pre-push

@@ -20,19 +20,23 @@ Per ``man githooks``: pre-push receives ``<remote> <url>`` as argv, and four
 fields per ref on stdin: ``<local_ref> <local_sha> <remote_ref> <remote_sha>``.
 Exit non-zero → push is blocked.
 
-This hook:
+This hook runs TWO stages; either blocking stops the push:
 
 1. Locates the repo (git rev-parse) and adds ``<repo>/scripts`` to sys.path.
-2. Imports ``push_hold.evaluate_push``.
-3. Calls it with the stdin lines.
-4. On ``allow``/``bypass``: exit 0 (push proceeds).
-5. On ``block``: print the reason + release instructions to stderr, exit 1.
-6. On ANY internal exception (broken import, syntax error, OSError): log to
-   stderr and exit 0.  A broken hook MUST NOT permanently wedge the user's
-   ability to push — fail OPEN on internal errors, fail CLOSED on holds.
+2. STAGE 1 — deploy-HOLD: ``push_hold.evaluate_push``. On ``block`` print the
+   reason + release instructions to stderr and exit 1.
+3. STAGE 2 — deterministic TEST gate: ``prepush_test_gate.evaluate`` (added per
+   the 2026-06-29 L2 RCA — red commits kept reaching origin/main because the
+   deterministic suite ran only post-push in CI). On ``block`` print the failing
+   gate to stderr and exit 1. Stage 2 COMPOSES with — never replaces — stage 1.
+4. On ``allow``/``bypass`` from both stages: arm closeout, exit 0 (push proceeds).
+5. On ANY internal exception (broken import, syntax error, OSError) in EITHER
+   stage: log to stderr and exit 0.  A broken hook MUST NOT permanently wedge the
+   user's ability to push — fail OPEN on internal errors, fail CLOSED on a real
+   hold / a real deterministic test failure.
 
 The block-vs-fail-open distinction is the whole reason for the try/except
-wrapper below.  Do NOT collapse it into a bare ``raise``.
+wrappers below.  Do NOT collapse them into a bare ``raise``.
 """
 from __future__ import annotations
 
@@ -185,12 +189,33 @@ def main() -> int:
         except OSError as exc:
             return _fail_open(f"could not read stdin: {exc!r}", repo=repo)
 
+        # --- STAGE 1: deploy-HOLD gate ---
         verdict = push_hold.evaluate_push(repo, stdin_lines, env=os.environ)
         action = verdict.get("action", "allow")
         if action == "block":
             sys.stderr.write(_format_block_message(verdict))
             return int(verdict.get("exit_code") or 1)
-        # allow / bypass / anything else → exit 0.
+
+        # --- STAGE 2: deterministic TEST gate (composes with stage 1) ---
+        # Runs the fast deterministic gate subset (the integration-gate class CI
+        # also runs) and BLOCKS the push on a real failure.  Import + evaluate are
+        # wrapped so a missing/broken gate fails OPEN — a broken gate must never
+        # permanently wedge pushing (same contract as stage 1).  evaluate() itself
+        # never raises; this try/except backstops an import/attr error.
+        try:
+            import prepush_test_gate  # type: ignore
+
+            test_verdict = prepush_test_gate.evaluate(repo, stdin_lines, env=os.environ)
+            if test_verdict.get("action") == "block":
+                sys.stderr.write(prepush_test_gate.format_block_message(test_verdict))
+                return int(test_verdict.get("exit_code") or 1)
+        except Exception as exc:  # noqa: BLE001 — test-gate errors fail OPEN
+            sys.stderr.write(
+                "[build-loop pre-push] test gate internal error — "
+                f"allowing push: {exc!r}\n"
+            )
+
+        # Both stages passed (or the test gate failed open) → exit 0.
         # Arm the post-push closeout baton BEFORE the push completes — git has
         # no native client-side post-push hook, so the next session-start
         # drains the baton via ``python3 -m closeout --source post-push-armed``.

package/hooks/hooks.json

@@ -53,11 +53,38 @@
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/closeout.sh\" session-start </dev/null 2>/dev/null; exit 0",
             "timeout": 3000
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/session-start-extensions.sh\" </dev/null 2>/dev/null; exit 0",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/route-guard.sh\" prompt-submit 2>/dev/null || printf '{}'",
+            "timeout": 3000
           }
         ]
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/route-guard.sh\" pre-skill 2>/dev/null || printf '{}'",
+            "timeout": 3000
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [
@@ -120,6 +147,11 @@
             "command": "if [ -n \"$CLAUDE_TRANSCRIPT_PATH\" ]; then root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; nohup env PYTHONPATH=\"$root/scripts\" python3 -m scan_corrections --workdir \"$CLAUDE_PROJECT_DIR\" --transcript \"$CLAUDE_TRANSCRIPT_PATH\" --source stop-hook </dev/null >/dev/null 2>&1 & fi; printf '{}'",
             "timeout": 5000
           },
+          {
+            "type": "command",
+            "command": "if [ -n \"$CLAUDE_TRANSCRIPT_PATH\" ]; then root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; nohup env PYTHONPATH=\"$root/scripts\" python3 -m scan_findings --workdir \"$CLAUDE_PROJECT_DIR\" --transcript \"$CLAUDE_TRANSCRIPT_PATH\" --log-file \"${XDG_STATE_HOME:-$HOME/.local/state}/build-loop/findings-scan.log\" </dev/null >/dev/null 2>&1 & fi; printf '{}'",
+            "timeout": 5000
+          },
           {
             "type": "command",
             "command": "python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/state_finalize.py\" --workdir \"$CLAUDE_PROJECT_DIR\" --mark-incomplete-as-crashed </dev/null >/dev/null 2>&1; printf '{}'",
@@ -130,17 +162,22 @@
             "command": "root=\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"; hook=\"$root/scripts/hooks/stop_finalize.sh\"; if [ -x \"$hook\" ]; then \"$hook\"; else printf '{}'; fi",
             "timeout": 30000
           },
-          {
-            "type": "command",
-            "command": "if [ -f \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" ]; then python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" --workdir \"${CLAUDE_PROJECT_DIR}\" --hook; else printf '{}'; fi",
-            "timeout": 5000
-          },
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/hooks/closeout.sh\" stop 2>/dev/null; exit 0",
             "timeout": 6000
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" ]; then python3 \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}/scripts/commit_state_check.py\" --workdir \"${CLAUDE_PROJECT_DIR}\" --hook; else printf '{}'; fi",
+            "timeout": 5000
+          }
+        ]
       }
     ]
   }

package/hooks/pre-edit-architecture.sh

@@ -17,7 +17,7 @@
 #      mark `.build-loop/architecture/.enrich-needed` and EXIT — DEFER the
 #      actual enriched scan to the scout pass (OQ3); never run it inline.
 #   4. Else bail silently if file extension is not in the source-code
-#      allowlist (.py .ts .tsx .js .jsx .mjs .cjs). Doc-only edits (.md,
+#      allowlist (.py .ts .tsx .js .jsx .mjs .cjs .rs). Doc-only edits (.md,
 #      .txt, plain .json, images) never mark architecture stale or fire a scan.
 #   5. Resolve to repo-relative path; bail if not in file_map.
 #   5. Mark stale (always — even if a scan is in flight, orchestrator must see
@@ -50,7 +50,7 @@ STDIN_JSON=$(cat 2>/dev/null)
 REL_PATH=$(WORKDIR="$WORKDIR" FILE_MAP="$FILE_MAP" STDIN_JSON="$STDIN_JSON" python3 - <<'PYEOF' 2>/dev/null
 import json, os, sys
 from pathlib import Path
-ALLOWED_EXTS = {".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"}
+ALLOWED_EXTS = {".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs"}
 MANIFESTS = {
     "package.json", "package-lock.json", "pnpm-lock.yaml", "requirements.txt",
     "pyproject.toml", "uv.lock", "Cargo.toml", "Cargo.lock", "go.mod", "Gemfile",

package/hooks/route-guard.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# route-guard.sh — minimal-PATH wrapper for route_guard.py. Hooks run under a
+# stripped PATH, so resolve python via the shared resolver before dispatch.
+# Fail-open: if no python is available, emit an empty decision and exit 0 so a
+# routing hint can never break a session.
+#
+#   usage: route-guard.sh <prompt-submit|pre-skill>   (payload on stdin)
+
+root="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}"
+. "$root/hooks/_resolve_python.sh"
+[ -n "$_py" ] || { printf '{}'; exit 0; }
+exec "$_py" "$root/hooks/route_guard.py" "$@"