@mmerterden/multi-agent-pipeline 11.0.0 → 11.2.0

package/CHANGELOG.md

@@ -14,6 +14,58 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [11.2.0] - 2026-07-07
+
+Skill mining + an install-safety fix.
+
+- **Fix (data-loss): `install.js` no longer clobbers user-owned rules.** `rules/`
+  is authored/evolved locally and is deliberately never synced back to the repo
+  (privacy). The installer used to `wipe + copy` it on every update, which
+  reverted local edits (including the git attribution rule). Rules now install
+  write-if-missing: new baseline rules are added, existing local rules are
+  preserved untouched. New `copyDir({ skipExisting })` option backs this.
+- **Two skills mined from the corporate iOS toolkit and genericized into
+  `ai-common-engineering-toolkit` (v0.1.2):**
+  - `skill-creator` — the house rules for authoring skills (description-first
+    discovery, lean SKILL.md as an index, progressive disclosure, reference vs
+    workflow vs tool layers, no-prefix naming, grow-from-failure), with a
+    template, pre-ship checklist, good/bad examples, and a multi-architect audit
+    script. All corporate references scrubbed.
+  - `backlog` — a deferred-work registry where every deferred job lands with its
+    full spec + origin + unblock condition (deferred -> ready -> in-progress ->
+    done, never deleted), so deferral never means loss.
+
+## [11.1.0] - 2026-07-07
+
+Harness-hardening pass: four techniques adapted from studying cross-harness agent
+operating systems, all additive and opt-in.
+
+- **Guard hooks (`agent-guard.sh`)** — a new PreToolUse Bash gate that turns two
+  prompt-level rules into deterministic, OS-enforced blocks: AI/assistant
+  attribution in a commit message, and force-push to a protected branch
+  (main/master/develop). Fail-open on any internal error, never executes the
+  inspected command (decision core is `agent-guard.py`, shlex-tokenized only),
+  no network, no secret output. Wired into `install/templates/claude-hooks.json`
+  alongside the existing secret scan; `multi-agent:setup` offers to merge it.
+  Backed by `smoke-agent-guard.sh` (19 behavioral cases incl. injection safety).
+- **Config-hygiene gate (`scan-agent-config.sh`)** — a dependency-free, read-only
+  audit of the shipped config surface (hook templates, preferences template,
+  agent defs, MCP helper scripts) for hardcoded secrets, permission-bypass flags,
+  eval-bearing hook commands, blanket `Bash(*)` allows, and pipe-to-shell /
+  unpinned-npx install patterns. Runs in the release VERIFY step; blocks on any
+  HIGH finding. Backed by `smoke-config-hygiene.sh` (real surface clean +
+  planted-bad detection).
+- **Autopilot circuit-breaker** — `refs/features/autopilot-circuit-breaker.md`
+  defines the sanctioned autopilot pause: halt and hand back to the user on a
+  no-progress stall, an identical repeated failure, a rework storm, cost drift
+  past the `costBudget` ceiling, or a merge/rebase conflict. Continuing
+  unattended off the happy path is the less safe choice.
+- **Three technique skills** added to `ai-common-engineering-toolkit`
+  (v0.1.1): `council` (multi-voice adversarial decision), `search-first`
+  (research-before-coding with an adopt/extend/compose/build matrix), and
+  `agent-introspection-debugging` (capture -> diagnose -> contained-recovery ->
+  report, with an honesty guard against fake auto-heal claims).
+
 ## [11.0.0] - 2026-07-07
 
 Breaking: the two issue creators `generate-task` and `generate-bug` are merged

package/install/_common.mjs

@@ -59,7 +59,7 @@ export function ensureDir(dir) {
  * @param {{ exclude?: Array<string|RegExp>, useSymlinks?: boolean }} [opts]
  */
 export function copyDir(src, dest, opts = {}) {
-  const { exclude = [], useSymlinks = false } = opts;
+  const { exclude = [], useSymlinks = false, skipExisting = false } = opts;
   if (useSymlinks) {
     symlinkDir(src, dest);
     return;
@@ -69,6 +69,14 @@ export function copyDir(src, dest, opts = {}) {
     return;
   }
   ensureDir(dest);
+  // skipExisting: never overwrite a file that already exists in dest. Used for
+  // user-owned trees (rules/) so an update adds new baseline files but preserves
+  // the user's locally-evolved copies. cpSync with force:false + errorOnExist:false
+  // silently skips existing files.
+  if (skipExisting) {
+    cpSync(src, dest, { recursive: true, force: false, errorOnExist: false });
+    return;
+  }
   if (exclude.length === 0) {
     cpSync(src, dest, { recursive: true, force: true });
     return;

package/install/claude.mjs

@@ -108,9 +108,18 @@ function installRules(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing rules...");
   const rulesSrc = join(pipelineSrc, "rules");
   if (!existsSync(rulesSrc)) return;
-  wipeDir(dest);
-  copyDir(rulesSrc, dest, { useSymlinks });
-  console.log(`    -> ${countFiles(rulesSrc)} files copied to ${dest}`);
+  // rules/ is USER-OWNED: users evolve their global rules locally and the sync
+  // deliberately never pushes rules/ back to the repo (privacy). So an update
+  // must NOT wipe+overwrite them (that reverts local edits, including the git
+  // attribution rule). Install only files that do not already exist; leave the
+  // user's existing rules untouched. (Symlink mode is a dev choice and keeps its
+  // link-replace behavior.)
+  if (useSymlinks) {
+    copyDir(rulesSrc, dest, { useSymlinks });
+  } else {
+    copyDir(rulesSrc, dest, { skipExisting: true });
+  }
+  console.log(`    -> rules present (existing local rules preserved)`);
 }
 
 function installSchemas(pipelineSrc, dest, useSymlinks) {

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make the secret scan a HARD pre-commit gate (exit 2 blocks the commit) rather than an advisory step. This is the one gate that is naturally a PreToolUse hook: it scans the staged diff with no extra arguments. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with run-specific arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Two gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop). Both scripts are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -10,6 +10,23 @@
             "command": "bash $HOME/.claude/scripts/pre-commit-check.sh",
             "timeout": 15,
             "statusMessage": "Scanning staged changes for secrets..."
+          },
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking commit for attribution..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git push:*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking push safety..."
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "11.0.0",
+  "version": "11.2.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md

@@ -0,0 +1,32 @@
+# Feature: Autopilot Circuit-Breaker
+
+**Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
+
+**Gated by `prefs.global.autopilotCircuitBreaker`** (default: enabled; thresholds tunable). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
+
+## Trip conditions
+
+Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry, no extra model calls.
+
+| # | Trigger | Detection | Default threshold |
+|---|---|---|---|
+| 1 | **No-progress stall** | two consecutive phase checkpoints with no forward transition (same `phase` + `step` + `reworkCount`, no new artifact/commit) | 2 checkpoints |
+| 2 | **Identical repeated failure** | same normalized build-error signature, or the same Phase 4 finding fingerprint, recurs across consecutive Phase 3 rework cycles | 2 cycles |
+| 3 | **Rework storm** | Phase 4 -> Phase 3 rework cycles exceed the cap (distinct from the build-retry cap) | `maxReworkCycles` = 3 |
+| 4 | **Cost drift** | cumulative spend crosses the `costBudget` ceiling, or the projected next-phase spend would exceed it, after model-fallback has already downgraded | `costBudget` ceiling |
+| 5 | **Merge/rebase conflict** | Phase 6 push blocked by a conflict that requires history reconciliation | any conflict |
+
+Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
+
+## Action on trip
+
+1. Set `agent-state.json.circuitBreaker = {tripped: true, trigger: <#>, detail, checkpoint}` and flip `autopilot` handling to paused (the run does not continue unattended).
+2. Emit one actionable line per the progress contract: what tripped, the evidence (error signature / cycle count / spend vs ceiling), and the single next action (`resume #N` after a fix, or `kill #N`).
+3. Never auto-resolve the underlying cause  -  no force-anything, no conflict auto-merge, no budget self-raise. The breaker hands control back; it does not paper over the problem.
+4. `resume #N` clears the tripped flag and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
+
+## Why this is the right autopilot exception
+
+Autopilot's contract is "no interaction on the happy path." The circuit-breaker fires only off the happy path, where continuing unattended is the *less* safe choice: repeating a proven-broken action, or spending past a ceiling the user set, is not autonomy, it is a runaway. Halting with a precise reason is cheaper than the tokens (and trust) a silent loop burns.
+
+Inspired by autonomous-loop operators that gate on explicit stop conditions (no-progress, identical-stack-trace repetition, cost drift, conflict blocking), adapted to this pipeline's phase/rework/state model.

package/pipeline/commands/multi-agent/refs/phases/modes.md

@@ -35,6 +35,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 - Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
 - Kill/Purge confirmations -> destructive operations always ask
 - Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
+- **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
 - **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
 
 **State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.

package/pipeline/commands/multi-agent/refs/picker-contract.md

@@ -56,6 +56,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hook is the one HARD blocking gate: the secret scan runs on every `git commit` and a non-zero exit blocks it. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. Only the secret scan is naturally a PreToolUse hook (it needs no run-specific arguments) - the other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Two ship, both needing no run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop). Both are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

package/pipeline/commands/multi-agent/sync.md

@@ -148,7 +148,7 @@ If nothing is stale → report "All targets up to date" and stop.
 5. **Files NOT synced** (local-only, may contain personal data):
    - `~/.claude/multi-agent-preferences.json`
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
-   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh` and `build-stack-plugins.mjs` (generic, synced)
+   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
 
 6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
@@ -256,7 +256,7 @@ When invoked with the `release` argument:
 
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
-2. VERIFY        Personal data scan -> 0 results
+2. VERIFY        Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH
 3. LINT + TEST   ESLint + smoke tests
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}

package/pipeline/scripts/agent-guard.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Decision core for agent-guard.sh (see that file for the hook contract).
+
+Reads the PreToolUse payload JSON on stdin and prints exactly one decision:
+  BLOCK_ATTRIB | BLOCK_FORCE | OK
+
+Never executes the command. shlex.split only tokenizes shell-like text; a
+`$(...)` in the command is a literal token, never a subshell. Any error prints
+OK (fail-open) so a guard bug cannot break a legitimate tool call.
+"""
+import json
+import os
+import re
+import shlex
+import sys
+
+# --- Rule data (extend here; this is the hookify-style rule surface) ----------
+PROTECTED = {"main", "master", "develop"}
+REMOTES = {"origin", "upstream"}
+ATTRIBUTION = re.compile(
+    r"co-authored-by:\s*(claude|anthropic|opus|sonnet|haiku|fable)"
+    r"|noreply@anthropic\.com"
+    r"|generated with\s+.*claude"
+    r"|\U0001F916\s*generated"
+    r"|claude code <",
+    re.IGNORECASE,
+)
+FORCE = re.compile(r"(^|\s)(--force(\b|$)|--force-with-lease|-\S*f\S*)(\s|$)")
+
+
+def decide(cmd: str) -> str:
+    low = cmd.lower()
+
+    # Rule 1: AI attribution inside a git commit.
+    if re.search(r"git\s+commit", low) and ATTRIBUTION.search(cmd):
+        return "BLOCK_ATTRIB"
+
+    # Rule 2: force-push to a protected branch.
+    if re.search(r"git\s+push", low) and FORCE.search(cmd):
+        try:
+            toks = shlex.split(cmd)
+        except Exception:
+            toks = cmd.split()
+        if any(t in PROTECTED or t.split(":")[-1] in PROTECTED for t in toks):
+            return "BLOCK_FORCE"
+        # non-flag args after `push`; only a remote (or nothing) means a bare push
+        args, seen = [], False
+        for t in toks:
+            if t == "push":
+                seen = True
+                continue
+            if seen and not t.startswith("-"):
+                args.append(t)
+        nonremote = [a for a in args if a not in REMOTES]
+        if not nonremote and os.environ.get("CUR_BRANCH", "") in PROTECTED:
+            return "BLOCK_FORCE"
+
+    return "OK"
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+        cmd = (data.get("tool_input") or {}).get("command", "")
+        if not isinstance(cmd, str) or not cmd:
+            print("OK")
+            return
+        print(decide(cmd))
+    except Exception:
+        print("OK")
+
+
+if __name__ == "__main__":
+    main()

package/pipeline/scripts/agent-guard.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# agent-guard.sh  -  PreToolUse Bash guard for the multi-agent pipeline.
+#
+# Turns two prompt-level rules into deterministic, OS-enforced gates:
+#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude,
+#      "Generated with Claude Code", robot emoji, Anthropic no-reply address).
+#   2. No force-push to a protected branch (main / master / develop).
+#
+# Contract (Claude Code PreToolUse hook):
+#   - Reads the tool-call JSON on stdin: {"tool_input":{"command":"..."}, ...}.
+#   - Exit 2  -> BLOCK the tool call (reason on stderr, shown to the model).
+#   - Exit 0  -> allow.
+#
+# Safety design (fail-OPEN):
+#   - The command string is ONLY parsed/pattern-matched, NEVER executed or eval'd
+#     (the decision core is agent-guard.py; shlex tokenizes without running).
+#   - Any internal error (bad JSON, missing python3/helper, empty input) -> exit 0.
+#     A guard bug must never break a legitimate tool call.
+#   - No network, no file writes, no secret values printed.
+#   - The single exec is a read-only `git rev-parse` to learn the current branch.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+HELPER="$HERE/agent-guard.py"
+[ -f "$HELPER" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+PAYLOAD="$(cat 2>/dev/null || true)"
+[ -z "$PAYLOAD" ] && exit 0
+
+CUR_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+DECISION="$(printf '%s' "$PAYLOAD" | CUR_BRANCH="$CUR_BRANCH" python3 "$HELPER" 2>/dev/null || true)"
+
+case "$DECISION" in
+  BLOCK_ATTRIB)
+    echo "BLOCKED by agent-guard: the commit message carries AI/assistant attribution." >&2
+    echo "Remove any 'Co-Authored-By: Claude', 'Generated with Claude Code', robot-emoji, or" >&2
+    echo "anthropic no-reply trailer. Commits are authored solely as the user's git identity." >&2
+    exit 2 ;;
+  BLOCK_FORCE)
+    echo "BLOCKED by agent-guard: force-push to a protected branch (main/master/develop) is not allowed." >&2
+    echo "Rewriting shared history is a data-loss risk. Push a normal commit, or force-push a feature branch." >&2
+    exit 2 ;;
+  *)
+    exit 0 ;;
+esac

package/pipeline/scripts/build-stack-plugins.mjs

@@ -36,7 +36,7 @@ const EXTERNAL = join(PIPE_ROOT, 'pipeline/skills/shared/external');
 const DRY = args.includes('--dry-run');
 
 const COMMON_PLUGIN = 'ai-common-engineering-toolkit';
-const COMMON_SKILLS = ['accessibility-compliance-accessibility-audit', 'firebase', 'humanizer'];
+const COMMON_SKILLS = ['accessibility-compliance-accessibility-audit', 'firebase', 'humanizer', 'council', 'search-first', 'agent-introspection-debugging', 'skill-creator', 'backlog'];
 
 // Apple/Xcode-only skills that match no stack pattern → iOS plugin only.
 const APPLE_ONLY = [

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -5,12 +5,12 @@
 .claude/multi-agent-preferences.json	1
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	174
+.claude/scripts	180
 .claude/settings.json	1
-.claude/skills	560
+.claude/skills	572
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	24
 .copilot/schemas	23
-.copilot/scripts	174
-.copilot/skills	598
+.copilot/scripts	180
+.copilot/skills	609

package/pipeline/scripts/scan-agent-config.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# scan-agent-config.sh  -  config-hygiene gate for the shipped agent surface.
+#
+# Audits the config the pipeline SHIPS (install templates, preferences template,
+# agent definitions, MCP helper scripts) for security problems before release:
+#   HIGH   - hardcoded secrets; hook commands that eval/execute inspected input;
+#            permission bypass flags baked into a shipped template.
+#   MEDIUM - unpinned/remote-install supply-chain patterns (curl|bash, npx -y);
+#            blanket Bash(*) permission allow.
+#
+# Read-only. Never prints a secret value (reports file + rule only). Self-contained
+# (no external scanner dependency). Exit 1 if any HIGH finding, else 0.
+#
+# Inspired by config-audit tools like ecc-agentshield, but rewritten as a
+# first-party, dependency-free gate over this repo's own shipped surface.
+
+set -uo pipefail
+
+# ROOT defaults to the repo root; SCAN_ROOT overrides it (used by the smoke test
+# to point at a fixture tree of planted-bad configs).
+ROOT="${SCAN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+HIGH=0; MED=0
+high() { HIGH=$((HIGH+1)); echo "  [HIGH]   $1"; }
+med()  { MED=$((MED+1));  echo "  [MEDIUM] $1"; }
+
+# Shipped config surface (globs expanded safely; missing paths are skipped).
+TARGETS=()
+add() { [ -e "$1" ] && TARGETS+=("$1"); }
+add "$ROOT/install/templates/claude-hooks.json"
+add "$ROOT/install/templates/copilot-instructions.md"
+add "$ROOT/pipeline/preferences-template.json"
+for f in "$ROOT"/pipeline/agents/*.md; do add "$f"; done
+for f in "$ROOT"/pipeline/skills/figma-common/figma-setup/scripts/*.py \
+         "$ROOT"/pipeline/skills/figma-ios/figma-to-component/scripts/*.py; do add "$f"; done
+add "$ROOT/pipeline/scripts/agent-guard.sh"
+add "$ROOT/pipeline/scripts/pre-commit-check.sh"
+
+rel() { echo "${1#$ROOT/}"; }
+
+echo "→ scanning ${#TARGETS[@]} shipped config files"
+
+for f in "${TARGETS[@]}"; do
+  [ -f "$f" ] || continue
+  r="$(rel "$f")"
+
+  # --- HIGH: hardcoded secrets (high-signal prefixes only; report file, not value)
+  if grep -EqI '(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{60,}|xox[baprs]-[A-Za-z0-9-]{12,}|sk_live_[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{35}|npm_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----' "$f" 2>/dev/null; then
+    high "hardcoded secret / token in $r"
+  fi
+  if grep -Eq '"type"[[:space:]]*:[[:space:]]*"service_account"' "$f" 2>/dev/null; then
+    high "embedded service-account JSON in $r"
+  fi
+
+  # --- HIGH: permission bypass baked into a shipped template
+  if grep -Eq 'skipDangerousModePermissionPrompt"?[[:space:]]*:[[:space:]]*true|--dangerously-skip-permissions|"permissions"[[:space:]]*:[[:space:]]*"?(allow-all|bypass)' "$f" 2>/dev/null; then
+    high "permission bypass flag in shipped template: $r"
+  fi
+
+  # --- MEDIUM: blanket Bash allow
+  if grep -Eq '"Bash\(\*\)"|"Bash\(:\*\)"|Bash\(\*:\*\)' "$f" 2>/dev/null; then
+    med "blanket Bash(*) permission in $r"
+  fi
+
+  # --- MEDIUM: remote-install supply-chain patterns
+  if grep -Eq 'curl[^|]*\|[[:space:]]*(sudo[[:space:]]+)?(ba)?sh|wget[^|]*\|[[:space:]]*(ba)?sh' "$f" 2>/dev/null; then
+    med "pipe-to-shell remote install (curl|bash) in $r"
+  fi
+  if grep -Eq '(^|[^A-Za-z])npx[[:space:]]+-y[[:space:]]|npx[[:space:]]+--yes[[:space:]]' "$f" 2>/dev/null; then
+    med "unpinned 'npx -y' auto-install in $r"
+  fi
+done
+
+# --- HIGH: hook commands must only invoke vetted scripts, never inline eval -----
+HOOKS="$ROOT/install/templates/claude-hooks.json"
+if [ -f "$HOOKS" ] && command -v python3 >/dev/null 2>&1; then
+  bad="$(python3 - "$HOOKS" <<'PY' 2>/dev/null || true
+import json, re, sys
+try:
+    t = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+bad = []
+for _event, entries in (t.get("hooks") or {}).items():
+    for e in entries:
+        for h in e.get("hooks", []):
+            c = h.get("command", "")
+            # allow only: `bash $HOME/.claude/scripts/<name>` (our vetted scripts)
+            if not re.fullmatch(r'bash \$HOME/\.claude/scripts/[A-Za-z0-9._-]+', c.strip()):
+                bad.append(c)
+            if re.search(r'\beval\b|\$\(|`', c):
+                bad.append(c)
+print("\n".join(bad))
+PY
+)"
+  if [ -n "$bad" ]; then
+    high "hooks template has a non-vetted or eval-bearing hook command"
+  fi
+fi
+
+echo ""
+echo "══ config-hygiene: $HIGH high, $MED medium ══"
+if [ "$HIGH" -gt 0 ]; then
+  echo "FAIL: high-severity config findings must be fixed before release."
+  exit 1
+fi
+exit 0

package/pipeline/scripts/smoke-agent-guard.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# smoke-agent-guard.sh  -  behavioral contract for the agent-guard PreToolUse hook.
+#
+# Verifies the guard blocks (exit 2) AI-attribution commits and force-push to a
+# protected branch, allows (exit 0) everything else, fails open on bad input, and
+# NEVER executes the inspected command (injection safety).
+#
+# Runs the guard from the repo copy in a throwaway git repo whose branch we set,
+# so the "bare push on a protected branch" path is exercised deterministically.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+GUARD="$ROOT/pipeline/scripts/agent-guard.sh"
+command -v python3 >/dev/null 2>&1 || { echo "error: python3 required" >&2; exit 127; }
+[ -f "$GUARD" ] || { echo "FAIL: agent-guard.sh missing at $GUARD" >&2; exit 1; }
+[ -f "$ROOT/pipeline/scripts/agent-guard.py" ] || { echo "FAIL: agent-guard.py missing" >&2; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+# throwaway repo on a protected branch so `git rev-parse` inside the guard = main
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+# init on main WITH a commit so `git rev-parse --abbrev-ref HEAD` resolves to main
+# (an unborn branch reports HEAD, which would not exercise the bare-push path)
+( cd "$WORK" \
+  && git init -q \
+  && git symbolic-ref HEAD refs/heads/main \
+  && git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init ) 2>/dev/null
+
+J() { python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$1"; }
+run() { # label  expected-exit  command-string
+  local got
+  ( cd "$WORK" && printf '%s' "$(J "$3")" | bash "$GUARD" >/dev/null 2>&1 )
+  got=$?
+  if [ "$got" = "$2" ]; then pass "[$got] $1"; else fail "expected $2 got $got: $1"; fi
+}
+
+echo "→ blocks (exit 2)"
+run "commit Co-Authored-By: Claude" 2 'git commit -m "x
+
+Co-Authored-By: Claude <noreply@anthropic.com>"'
+run "commit robot-emoji"            2 'git commit -m "x
+
+🤖 Generated with Claude Code"'
+run "push --force origin main"      2 'git push --force origin main'
+run "push -f origin develop"        2 'git push -f origin develop'
+run "push --force-with-lease master" 2 'git push --force-with-lease origin master'
+run "bare push -f on main"          2 'git push -f'
+
+echo "→ allows (exit 0)"
+run "normal commit"                 0 'git commit -m "feat: normal"'
+run "push no force"                 0 'git push origin main'
+run "force push feature branch"     0 'git push --force origin feature/DEMO-1'
+run "force push tag"                0 'git push -f origin v1.2.3'
+run "non-git command"               0 'ls -la /tmp'
+run "empty command"                 0 ''
+
+echo "→ fail-open on bad input"
+( cd "$WORK" && printf 'not-json{' | bash "$GUARD" >/dev/null 2>&1 ); [ $? -eq 0 ] && pass "malformed json -> allow" || fail "malformed json blocked"
+( cd "$WORK" && printf '' | bash "$GUARD" >/dev/null 2>&1 ); [ $? -eq 0 ] && pass "empty stdin -> allow" || fail "empty stdin blocked"
+
+echo "→ injection safety (inspected command must NOT execute)"
+SENT="$WORK/sentinel"; : > "$SENT"
+( cd "$WORK" && printf '%s' "$(J "git commit -m \"\$(rm -f '$SENT')\"")" | bash "$GUARD" >/dev/null 2>&1 )
+[ -f "$SENT" ] && pass "sentinel survived (no execution)" || fail "sentinel deleted - command executed"
+
+echo ""
+echo "══ agent-guard smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-autopilot-circuit-breaker.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# smoke-autopilot-circuit-breaker.sh  -  wiring contract for the autopilot
+# circuit-breaker feature: the doc exists, enumerates the five trip conditions,
+# and is referenced from the modes "what never skips" list.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOC="$ROOT/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md"
+MODES="$ROOT/pipeline/commands/multi-agent/refs/phases/modes.md"
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+[ -f "$DOC" ] && pass "feature doc exists" || fail "feature doc missing"
+[ -f "$MODES" ] && pass "modes doc exists" || fail "modes doc missing"
+
+echo "→ five trip conditions documented"
+for t in "No-progress stall" "Identical repeated failure" "Rework storm" "Cost drift" "Merge/rebase conflict"; do
+  grep -Fq "$t" "$DOC" && pass "trigger: $t" || fail "trigger missing: $t"
+done
+
+echo "→ action + safety invariants"
+grep -Fq "resume" "$DOC" && pass "documents resume path" || fail "no resume path"
+grep -Eiq "never auto-resolve|does not paper over|no force-anything" "$DOC" && pass "no-self-heal invariant present" || fail "missing no-self-heal invariant"
+
+echo "→ wired into modes 'what never skips'"
+grep -Fq "autopilot-circuit-breaker.md" "$MODES" && pass "modes references the feature doc" || fail "modes does not reference the feature"
+grep -Fiq "Circuit-breaker" "$MODES" && pass "modes lists circuit-breaker under never-skip" || fail "modes missing circuit-breaker bullet"
+
+echo ""
+echo "══ autopilot-circuit-breaker smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]