@getarbiter/cli 0.5.0

package/dist/templates/frontend/design-tokens.json.ejs

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://tr.designtokens.org/format/",
+  "$description": <%- JSON.stringify(`Design tokens for ${projectName} — W3C DTCG format (semantic layer only). Generated by arbiter #1127.`) %>,
+
+  "color": {
+    "$description": "Semantic color tokens. Components reference these only — never raw palette values (INV-105).",
+
+    "bg": {
+      "primary": { "$value": "#ffffff", "$type": "color" },
+      "secondary": { "$value": "#f5f5f5", "$type": "color" },
+      "elevated": { "$value": "#fafafa", "$type": "color" },
+      "overlay": { "$value": "rgba(0, 0, 0, 0.5)", "$type": "color" },
+      "inverse": { "$value": "#1a1a1a", "$type": "color" }
+    },
+
+    "text": {
+      "primary": { "$value": "#1a1a1a", "$type": "color" },
+      "secondary": { "$value": "#666666", "$type": "color" },
+      "disabled": { "$value": "#999999", "$type": "color" },
+      "inverse": { "$value": "#ffffff", "$type": "color" },
+      "link": { "$value": "#0066cc", "$type": "color" },
+      "error": { "$value": "#cc0000", "$type": "color" },
+      "success": { "$value": "#007700", "$type": "color" },
+      "warning": { "$value": "#cc7700", "$type": "color" }
+    },
+
+    "border": {
+      "default": { "$value": "#dddddd", "$type": "color" },
+      "strong": { "$value": "#aaaaaa", "$type": "color" },
+      "focus": { "$value": "#0066cc", "$type": "color" },
+      "error": { "$value": "#cc0000", "$type": "color" }
+    },
+
+    "interactive": {
+      "primary": { "$value": "#0066cc", "$type": "color" },
+      "primary-hover": { "$value": "#0052a3", "$type": "color" },
+      "primary-active": { "$value": "#004080", "$type": "color" },
+      "primary-text": { "$value": "#ffffff", "$type": "color" },
+      "secondary": { "$value": "#f5f5f5", "$type": "color" },
+      "secondary-hover": { "$value": "#e8e8e8", "$type": "color" },
+      "secondary-text": { "$value": "#1a1a1a", "$type": "color" },
+      "danger": { "$value": "#cc0000", "$type": "color" },
+      "danger-hover": { "$value": "#a30000", "$type": "color" },
+      "danger-text": { "$value": "#ffffff", "$type": "color" }
+    },
+
+    "surface": {
+      "card": { "$value": "#ffffff", "$type": "color" },
+      "card-hover": { "$value": "#f9f9f9", "$type": "color" },
+      "tooltip": { "$value": "#1a1a1a", "$type": "color" },
+      "tooltip-text": { "$value": "#ffffff", "$type": "color" }
+    },
+
+    "status": {
+      "error-bg": { "$value": "#fff0f0", "$type": "color" },
+      "success-bg": { "$value": "#f0fff0", "$type": "color" },
+      "warning-bg": { "$value": "#fffbf0", "$type": "color" },
+      "info-bg": { "$value": "#f0f8ff", "$type": "color" }
+    }
+  },
+
+  "space": {
+    "$description": "Spacing scale tokens.",
+    "xs": { "$value": "4px", "$type": "dimension" },
+    "sm": { "$value": "8px", "$type": "dimension" },
+    "md": { "$value": "16px", "$type": "dimension" },
+    "lg": { "$value": "24px", "$type": "dimension" },
+    "xl": { "$value": "32px", "$type": "dimension" },
+    "2xl": { "$value": "48px", "$type": "dimension" },
+    "3xl": { "$value": "64px", "$type": "dimension" }
+  },
+
+  "radius": {
+    "$description": "Border radius tokens.",
+    "sm": { "$value": "4px", "$type": "dimension" },
+    "md": { "$value": "8px", "$type": "dimension" },
+    "lg": { "$value": "12px", "$type": "dimension" },
+    "full": { "$value": "9999px", "$type": "dimension" }
+  },
+
+  "typography": {
+    "$description": "Font size and weight tokens.",
+    "size": {
+      "xs": { "$value": "12px", "$type": "dimension" },
+      "sm": { "$value": "14px", "$type": "dimension" },
+      "base": { "$value": "16px", "$type": "dimension" },
+      "lg": { "$value": "18px", "$type": "dimension" },
+      "xl": { "$value": "20px", "$type": "dimension" },
+      "2xl": { "$value": "24px", "$type": "dimension" },
+      "3xl": { "$value": "30px", "$type": "dimension" }
+    },
+    "weight": {
+      "normal": { "$value": 400, "$type": "number" },
+      "medium": { "$value": 500, "$type": "number" },
+      "semibold": { "$value": 600, "$type": "number" },
+      "bold": { "$value": 700, "$type": "number" }
+    }
+  },
+
+  "shadow": {
+    "$description": "Elevation shadow tokens.",
+    "sm": { "$value": "0 1px 2px rgba(0,0,0,0.1)", "$type": "shadow" },
+    "md": { "$value": "0 4px 6px rgba(0,0,0,0.1)", "$type": "shadow" },
+    "lg": { "$value": "0 10px 15px rgba(0,0,0,0.1)", "$type": "shadow" },
+    "xl": { "$value": "0 20px 25px rgba(0,0,0,0.15)", "$type": "shadow" }
+  }
+}

package/dist/templates/frontend/vrt-setup.md.ejs

@@ -0,0 +1,83 @@
+# Visual Regression Testing — Setup Guide
+
+<!-- arbiter-managed: frontend-quality (#1127) -->
+
+**Framework:** <%= (typeof frontend !== 'undefined' && frontend && frontend.framework) ? frontend.framework : 'the frontend framework' %>
+**Tool:** Vitest Browser Mode + Playwright (`toMatchScreenshot`)
+**Baseline location:** `__tests__/screenshots/`
+
+---
+
+## Quick Start
+
+### 1. Install peer dependencies
+
+```bash
+npm install -D @vitest/browser playwright
+npx playwright install chromium
+```
+
+### 2. Write a component test
+
+Create `src/components/MyComponent.browser.test.ts`:
+
+```typescript
+import { test, expect } from 'vitest'
+import { render } from '@testing-library/dom'  // or vue / svelte / react equivalent
+
+test('MyComponent — visual snapshot', async () => {
+  const { container } = render('<my-component title="Hello" />')
+  await expect(container).toMatchScreenshot('my-component-default')
+})
+```
+
+### 3. Capture baselines (first run)
+
+```bash
+npx vitest --config vitest.browser.config.ts --update-snapshots
+```
+
+Baselines are written to `__tests__/screenshots/`. Commit them.
+
+### 4. Run VRT in CI
+
+```bash
+npx vitest --config vitest.browser.config.ts
+```
+
+Fails if any component's rendered output differs from its baseline by more than the pixelmatch threshold.
+
+---
+
+## Configuration
+
+The VRT threshold and baseline directory are set in `vitest.browser.setup.ts`:
+
+```typescript
+// vitest.browser.setup.ts
+import { expect } from 'vitest'
+expect.extend({
+  toMatchScreenshot: (el, name) =>
+    // pixelmatch threshold: 0.1 = 10% pixel difference tolerance
+    screenshotMatcher(el, name, { threshold: 0.1, baselineDir: '__tests__/screenshots' }),
+})
+```
+
+---
+
+## Governance
+
+- VRT is triggered by the `16-frontend-quality.yml` CI workflow on PR.
+- No baseline pre-generated at arbiter init — you must capture baselines after first render.
+- A failing VRT is a **blocking** gate: do not merge visual regressions without intentional baseline update.
+- For layout/visual changes: update baselines and include screenshots in the PR description.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Screenshot diffs on CI font rendering | Pin to a specific Playwright version; use `--headless=new` |
+| Flaky layout shifts | Add `await page.waitForLoadState('networkidle')` before snapshot |
+| Baseline stale after design change | Run `--update-snapshots` and commit the new baselines |

package/dist/templates/githooks/commit-msg.ejs

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# commit-msg: validates the commit message against Conventional Commits.
+# Two layers:
+#   1. Universal regex (works on every stack, no Node required) — #355
+#   2. Richer commitlint validation when Node + commitlint are available
+#
+# Bypass: messages starting with "Merge " or "Revert " (auto-generated by
+# git for merge commits and `git revert`) skip both layers.
+set -e
+
+# Read first line using bash builtin (avoids dependency on `head`).
+IFS= read -r MSG < "$1" || true
+
+# Bypass for merge/revert commits (auto-generated by git)
+if [[ "$MSG" =~ ^(Merge|Revert)\  ]]; then
+  exit 0
+fi
+
+# Layer 1: Conventional Commits regex enforcement.
+# Types match @commitlint/config-conventional (11) plus 'cluster' for
+# arbiter's batch-merge convention. Scope is permissive ([^)]+) so things
+# like (#123), (W3A), (deps-dev), (#262-#270) all pass; Layer 2 enforces
+# stricter scope rules where commitlint is installed.
+if [[ ! "$MSG" =~ ^(build|chore|ci|cluster|docs|feat|fix|perf|refactor|revert|style|test)(\([^\)]+\))?!?:[[:space:]].+ ]]; then
+  echo "commit-msg rejected: subject must look like 'type(scope): description'"
+  echo "  types: build|chore|ci|cluster|docs|feat|fix|perf|refactor|revert|style|test"
+  echo "  scope: optional, parenthesized free text"
+  echo "  Got: $MSG"
+  exit 1
+fi
+
+# Layer 2: richer commitlint validation is optional on every stack. Only run it
+# when this repository supplies both a configuration and a local executable.
+COMMITLINT_CONFIG_FOUND=false
+for COMMITLINT_CONFIG in \
+  commitlint.config.js commitlint.config.cjs commitlint.config.mjs commitlint.config.ts \
+  .commitlintrc .commitlintrc.json .commitlintrc.yml .commitlintrc.yaml \
+  .commitlintrc.js .commitlintrc.cjs .commitlintrc.mjs .commitlintrc.ts; do
+  if [ -f "$COMMITLINT_CONFIG" ]; then
+    COMMITLINT_CONFIG_FOUND=true
+    break
+  fi
+done
+
+if [ "$COMMITLINT_CONFIG_FOUND" = false ] && [ -f package.json ] && \
+  grep -Eq '"commitlint"[[:space:]]*:' package.json; then
+  COMMITLINT_CONFIG_FOUND=true
+fi
+
+if [ "$COMMITLINT_CONFIG_FOUND" = false ]; then
+  echo "commit-msg layer 2 skipped: commitlint config missing"
+  exit 0
+fi
+
+if [ ! -x node_modules/.bin/commitlint ]; then
+  echo "commit-msg layer 2 skipped: commitlint not installed"
+  exit 0
+fi
+
+node_modules/.bin/commitlint --edit "$1"

package/dist/templates/githooks/pre-commit.ejs

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# pre-commit: runs L1 gate before each commit
+set -e
+
+# Phase guard: refuse commits during preflight or plan phases. Distinguish an absent document
+# (fresh tree → allow) from a corrupt one (→ fail closed) so corruption can't silently bypass.
+_phase=$(node -e "const f=require('fs'),p='.claude/.task/status.json';if(!f.existsSync(p)){process.stdout.write('unknown')}else{try{process.stdout.write(JSON.parse(f.readFileSync(p,'utf-8')).phase||'unknown')}catch{process.stdout.write('corrupt')}}" 2>/dev/null || echo "unknown")
+case "$_phase" in
+  preflight|plan)
+    echo "ERROR: cannot commit during phase=$_phase. Run: arbiter task advance --to red" >&2
+    exit 1
+    ;;
+  corrupt)
+    echo "ERROR: .claude/.task/status.json is corrupt — fix or delete it before committing." >&2
+    exit 1
+    ;;
+  red)
+    # #2051: a genuine RED commit contains a test that FAILS — the L1 gate blocks
+    # exactly the commit `arbiter task record-red` must point at. The deadlock is
+    # resolved for that one commit shape only: phase=red AND every staged path is a
+    # test. Anything else (source staged alongside, or any other phase) still runs the
+    # gate, and the GREEN commit that follows runs it over the whole tree.
+    # ponytail: path-name heuristic for "is a test" — language-agnostic, and tight enough
+    # to reject latest/protest/testing, but a genuine source file named src/.../test.ts
+    # would ride along gate-free in this one commit. Upgrade path: ask the project's test
+    # config for its test globs. Bounded by the GREEN commit's whole-tree gate.
+    _staged_red=$(git diff --cached --name-only)
+    if [ -n "$_staged_red" ] && ! printf '%s\n' "$_staged_red" |
+      grep -qivE '(^|[^[:alpha:]])(tests?|specs?)([^[:alpha:]]|$)'; then
+      echo "[pre-commit] phase=red, staged paths are tests only — L1 gate skipped so the failing RED test can land (#2051)."
+      _skip_gate=1
+    fi
+    ;;
+esac
+
+<% if (language === 'typescript') { %>
+if [ ! -d "node_modules" ]; then
+  echo "Skipping pre-commit: node_modules not installed. Run npm install."
+  exit 0
+fi
+<% } else { %>
+if ! command -v node >/dev/null 2>&1; then
+  echo "Skipping pre-commit: node not found. Install Node.js to enable git hooks."
+  exit 0
+fi
+<% } %>
+
+# Unset git hook env vars so nested git calls in scripts work correctly.
+unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_OBJECT_DIRECTORY GIT_COMMON_DIR
+
+# gold-align (#1506 yamllint / #1507 shellcheck): mirror the CI config-lint lane
+# locally so YAML/shell style defects fail before CI, not after a round-trip. Each
+# linter is best-effort-on-absence (skip with a note when the tool isn't installed,
+# matching the node/node_modules guards above) but BLOCKING when present.
+_staged=$(git diff --cached --name-only --diff-filter=ACM)
+if command -v shellcheck >/dev/null 2>&1; then
+  _sh=$(echo "$_staged" | grep -E '\.sh$' || true)
+  if [ -n "$_sh" ]; then
+    echo "$_sh" | xargs shellcheck --severity=warning || exit 1
+  fi
+fi
+if command -v yamllint >/dev/null 2>&1; then
+  _yml=$(echo "$_staged" | grep -E '\.ya?ml$' | grep -v '^\.github/workflows/' || true)
+  if [ -n "$_yml" ]; then
+    if [ -f .yamllint.yml ] || [ -f .yamllint.yaml ] || [ -f .yamllint ]; then
+      echo "$_yml" | xargs yamllint || exit 1
+    else
+      echo "$_yml" | xargs yamllint -d relaxed || exit 1
+    fi
+  fi
+fi
+# #2051: the RED commit is exempt from the gate only — lint and secret scanning above
+# still applied to it.
+if [ "${_skip_gate:-0}" = "1" ]; then
+  exit 0
+fi
+<% if (language === 'typescript') { %>
+
+# Vite/vitest (v5+) cannot handle '#' in the project root path — it treats '#'
+# as a URL fragment and mangles all module IDs. Worktrees named '#NNN' trigger
+# this. Rsync to a temporary '#'-free path and run the gate from there.
+if [[ "$PWD" == *"#"* ]]; then
+  ORIG_DIR="$(pwd)"
+  TMP_DIR=$(mktemp -d /tmp/arbiter-hook-XXXXXX)
+  trap 'rm -rf "$TMP_DIR"' EXIT
+  rsync -a --exclude .git --exclude node_modules --exclude dist . "$TMP_DIR/"
+  ln -sfn "$ORIG_DIR/node_modules" "$TMP_DIR/node_modules"
+  cd "$TMP_DIR"
+  # Reserved: consumed by check-all when worktree-aware gate lands
+  ARBITER_HOOK_GIT_CWD="$ORIG_DIR" node scripts/check-all.mjs L1
+  exit $?
+fi
+<% } %>
+
+node scripts/check-all.mjs L1

package/dist/templates/githooks/pre-push.ejs

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# pre-push: checks clean working tree, evidence freshness, and runs gate (T1+T2) before push
+set -e
+
+<% if (language === 'typescript') { %>
+if [ ! -d "node_modules" ]; then
+  echo "Skipping pre-push: node_modules not installed. Run npm install."
+  exit 0
+fi
+<% } else { %>
+if ! command -v node >/dev/null 2>&1; then
+  echo "Skipping pre-push: node not found. Install Node.js to enable git hooks."
+  exit 0
+fi
+<% } %>
+
+# Assert Node version matches .nvmrc (INV-53)
+if [ -f ".nvmrc" ]; then
+  NVMRC_MAJOR=$(cut -d. -f1 .nvmrc)
+  RUNTIME_MAJOR=$(node -e "process.stdout.write(process.version.slice(1).split('.')[0])")
+  if [ "$RUNTIME_MAJOR" != "$NVMRC_MAJOR" ]; then
+    echo "Error: Node major mismatch — runtime v${RUNTIME_MAJOR}.x, .nvmrc requires v${NVMRC_MAJOR}.x. Run: nvm use"
+    exit 1
+  fi
+fi
+
+# Unset git hook env vars so nested git calls in scripts work correctly.
+unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_OBJECT_DIRECTORY GIT_COMMON_DIR
+
+if [ -n "$(git status --porcelain | grep -v '^??')" ]; then
+  echo "Error: working tree has uncommitted changes. Commit or stash before pushing."
+  exit 1
+fi
+
+# ─── arbiter pre-push evidence-freshness gate (Port #4) ──────────────────────
+# Reject pushes whose .arbiter/evidence/ is older than the budget. Bypassable
+# via ARBITER_PREPUSH_BYPASS=true (exact match — loudly logged). Soften to
+# warn-only when the diff vs upstream is docs-only or low-risk.
+#
+# Env contract (TODO: parametrise prefix once `projectEnvPrefix` template var
+# lands; for now scaffolded projects inherit the ARBITER_ prefix):
+#   ARBITER_PREPUSH_MAX_AGE_MIN   integer minutes (default 240 = 4 h)
+#   ARBITER_PREPUSH_BYPASS        exact string 'true' bypasses; other truthy
+#                                 values warn and the gate still runs
+#   ARBITER_PREPUSH_BYPASS_REASON free-form string, recorded in bypass log
+#   ARBITER_PREPUSH_SKIP          exact string 'true' skips the freshness gate
+#                                 entirely (for nested hook invocations + tests)
+ARBITER_PREPUSH_EVIDENCE_DIR="${ARBITER_PREPUSH_EVIDENCE_DIR:-.arbiter/evidence}"
+ARBITER_PREPUSH_MAX_AGE_MIN="${ARBITER_PREPUSH_MAX_AGE_MIN:-240}"
+
+if [ "${ARBITER_PREPUSH_SKIP:-}" = "true" ]; then
+  : # explicit skip — no warning; used by nested hook recursion
+elif [ -d "$ARBITER_PREPUSH_EVIDENCE_DIR" ]; then
+  # bypass-log.jsonl excluded so a successful bypass doesn't self-reset the freshness window.
+  NEWEST_EPOCH=$(find "$ARBITER_PREPUSH_EVIDENCE_DIR" -type f \
+    -not -name 'bypass-log.jsonl' \
+    -printf '%T@\n' 2>/dev/null \
+    | sort -nr | head -n1 | cut -d. -f1)
+
+  if [ -z "$NEWEST_EPOCH" ]; then
+    : # empty evidence tree → treat as missing, skip the gate
+  else
+    NOW_EPOCH=$(date +%s)
+    AGE_MIN=$(( (NOW_EPOCH - NEWEST_EPOCH) / 60 ))
+
+    if [ "$AGE_MIN" -gt "$ARBITER_PREPUSH_MAX_AGE_MIN" ]; then
+      BYPASS_RAW="${ARBITER_PREPUSH_BYPASS:-}"
+      BYPASSED=false
+      if [ "$BYPASS_RAW" = "true" ]; then
+        # Loud bypass — exact 'true' only (mirrors scripts/lib/loud-bypass.mjs).
+        BR="$(git branch --show-current 2>/dev/null || echo unknown)"
+        TS="$(date -u +%FT%TZ)"
+        REASON="${ARBITER_PREPUSH_BYPASS_REASON:-unspecified}"
+        echo "arbiter-bypass env=ARBITER_PREPUSH_BYPASS branch=${BR} at=${TS} reason=\"${REASON}\"" >&2
+        mkdir -p "$ARBITER_PREPUSH_EVIDENCE_DIR"
+        BR="$BR" TS="$TS" REASON="$REASON" AGE_MIN="$AGE_MIN" BUDGET="$ARBITER_PREPUSH_MAX_AGE_MIN" \
+          node -e 'const e=process.env;process.stdout.write(JSON.stringify({env:"ARBITER_PREPUSH_BYPASS",branch:e.BR,ts:e.TS,value:"true",bypassed:true,reason:e.REASON,age_min:Number(e.AGE_MIN),budget_min:Number(e.BUDGET)})+"\n")' \
+          >> "$ARBITER_PREPUSH_EVIDENCE_DIR/bypass-log.jsonl"
+        BYPASSED=true
+      elif [ -n "$BYPASS_RAW" ]; then
+        echo "Warning: ARBITER_PREPUSH_BYPASS='${BYPASS_RAW}' is ambiguous; only the exact string 'true' bypasses. Proceeding with gate." >&2
+      fi
+
+      if [ "$BYPASSED" = "false" ]; then
+        UPSTREAM="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || echo '')"
+        if [ -z "$UPSTREAM" ]; then
+          if git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+            UPSTREAM="origin/main"
+          fi
+        fi
+
+        DOCS_ONLY=false
+        BACKEND_CHANGED=true
+        HIGH_RISK=true
+        if [ -n "$UPSTREAM" ] && [ -x "$(command -v node)" ] && [ -f "scripts/ci-classify-changes.mjs" ]; then
+          CLASSIFY_OUT=$(BASE_SHA="$UPSTREAM" HEAD_SHA=HEAD node scripts/ci-classify-changes.mjs 2>/dev/null || echo '')
+          if echo "$CLASSIFY_OUT" | grep -q '^  classify: docs_only=true'; then DOCS_ONLY=true; fi
+          if echo "$CLASSIFY_OUT" | grep -q '^  classify: backend_changed=false'; then BACKEND_CHANGED=false; fi
+          if echo "$CLASSIFY_OUT" | grep -q '^  classify: high_risk=false'; then HIGH_RISK=false; fi
+        fi
+
+        if [ "$DOCS_ONLY" = "true" ] || { [ "$BACKEND_CHANGED" = "false" ] && [ "$HIGH_RISK" = "false" ]; }; then
+          echo "Warning: .arbiter/evidence/ is ${AGE_MIN} min old (budget ${ARBITER_PREPUSH_MAX_AGE_MIN}). Low-risk change set → proceeding." >&2
+        else
+          echo "Error: .arbiter/evidence/ is ${AGE_MIN} min old (budget ${ARBITER_PREPUSH_MAX_AGE_MIN} min). Re-run the gate to refresh evidence, or set ARBITER_PREPUSH_BYPASS=true with ARBITER_PREPUSH_BYPASS_REASON='…' to force-push." >&2
+          exit 1
+        fi
+      fi
+    fi
+  fi
+fi
+# ─── end evidence-freshness gate ─────────────────────────────────────────────
+
+# ─── arbiter pre-push chain-batching gate (#2102) ────────────────────────────
+# Enforced half of the chain-batching advisory (`is_unbatched`): when
+# `.claude/.task/status.json` declares a non-empty `chainIds` (via
+# `arbiter task init --chain <id>` / `arbiter ship --chain <id>`), every id in
+# [taskId, ...chainIds] must have a commit in the push range before the push
+# is allowed. Fails CLOSED only on a genuine missing id — any other condition
+# (no status file, empty/absent chainIds, unreadable JSON, no push-range base)
+# is a silent no-op so this gate can never block an unrelated push.
+# Own push range, unconditional: the secret-scan PUSH_RANGE is computed inside an
+# EJS-conditional block, so this gate must derive its own range independently.
+if CHAIN_IDS="$(node -e '
+try {
+  const s = JSON.parse(require("fs").readFileSync(".claude/.task/status.json", "utf8"))
+  const c = Array.isArray(s.chainIds) ? s.chainIds : []
+  if (c.length === 0) process.exit(0)
+  const ids = [s.taskId, ...c].filter(Boolean).map((x) => String(x).replace(/^#/, ""))
+  process.stdout.write(ids.join(" "))
+} catch (e) { process.exit(0) }
+' 2>/dev/null)"; then
+  : # status read (the one-liner exits 0 on every fail-open path above)
+else
+  # FAIL-OPEN-INTENT: node unavailable — the chain gate is a silent no-op
+  CHAIN_IDS=""
+fi
+
+if [ -n "$CHAIN_IDS" ]; then
+  # #2334 — the BASE range, not the incremental one. This gate asks "does every chained id
+  # have a commit on this branch", which is a property of the branch, not of one push. With
+  # `@{u}..HEAD` preferred, the first push passes and every later push sees only the new
+  # commits — so it demands each id be named AGAIN in that increment, which cannot be
+  # satisfied. That made the chain feature unusable on any branch pushed more than once.
+  # `@{u}..HEAD` remains the fallback for a branch that has no base ref to compare against.
+  CHAIN_PUSH_RANGE=""
+  if git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+    CHAIN_PUSH_RANGE="origin/main..HEAD"
+  elif git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+    CHAIN_PUSH_RANGE="@{u}..HEAD"
+  fi
+
+  # FAIL-OPEN-INTENT: an unresolvable range must not block an unrelated push — the whole
+  # scan (including the hard-fail) only runs when the range log actually succeeds.
+  if [ -n "$CHAIN_PUSH_RANGE" ] && CHAIN_SUBJECTS="$(git log --format=%s "$CHAIN_PUSH_RANGE" 2>/dev/null)"; then
+    CHAIN_MISSING=""
+    for id in $CHAIN_IDS; do
+      printf '%s\n' "$CHAIN_SUBJECTS" | grep -Eq "#${id}([^0-9]|$)" || CHAIN_MISSING="$CHAIN_MISSING #${id}"
+    done
+    if [ -n "$CHAIN_MISSING" ]; then
+      echo "Error: chain batching (#2102) — no commit in the push range (${CHAIN_PUSH_RANGE}) references:${CHAIN_MISSING}" >&2
+      echo "Every id declared via --chain needs a commit naming it, e.g. a commit subject containing \"#1234\"." >&2
+      exit 1
+    fi
+  fi
+fi
+# ─── end chain-batching gate ─────────────────────────────────────────────────
+<% if (enableSecurityScanning) { %>
+# ─── pre-push secret scan (gitleaks, push-range scoped, #1319.9) ──────────────
+# Scope gitleaks to the commits actually being pushed (origin/<base>..HEAD or the
+# tracked upstream @{u}..HEAD) via --log-opts, NOT a full-tree `detect --source .`
+# scan. pre-commit already vetted staged content full-tree; the push gate only
+# needs to vet the new history. Skips with a warning when gitleaks is absent.
+if command -v gitleaks >/dev/null 2>&1; then
+  PUSH_RANGE=""
+  if git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+    PUSH_RANGE="@{u}..HEAD"
+  elif git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+    PUSH_RANGE="origin/main..HEAD"
+  fi
+  if [ -n "$PUSH_RANGE" ]; then
+    gitleaks detect --log-opts "$PUSH_RANGE" \
+      --config .gitleaks.toml \
+      --gitleaks-ignore-path suppressions/.gitleaksignore \
+      --no-banner --exit-code 1 \
+      || { echo "gitleaks: secrets detected in push range ${PUSH_RANGE} — push blocked"; exit 1; }
+  else
+    echo "gitleaks: no upstream/origin base to diff against — skipping push-range scan (pre-commit covers staged content)"
+  fi
+else
+  echo "WARNING: gitleaks not installed — skipping push-range secret scan (CI enforces it)"
+fi
+<% } %>
+
+# ─── reuse fresh green gate evidence (skip redundant rerun) ───────────────────
+# The heavy gate below is otherwise UNCONDITIONAL. If check-all.mjs already
+# stamped a GREEN L2 marker (.arbiter/gate-pass.json) that still BINDS this exact
+# tree, reuse it and skip the rerun. The decision lives in the shared verifier
+# (scripts/lib/gate-evidence.mjs), so this hook demands the same axes as every
+# other consumer: schema, level, TTL, commit, branch, checkout root, toolchain
+# fingerprint and working-tree content hash.
+# Fail-closed: a missing verifier / missing / malformed / non-binding stamp, or
+# any error at all → fall through and run the full gate exactly as before.
+#
+# TRUST BOUNDARY: local convenience, NOT a security control. The stamp is a plain
+# JSON file a local process could forge; it only gates whether a developer's own
+# machine reruns its own gate. CI re-runs the full gate independently and stays
+# authoritative regardless.
+if [ -f ".arbiter/gate-pass.json" ] && [ -f "scripts/lib/gate-evidence.mjs" ]; then
+  if REUSE_MSG=$(node scripts/lib/gate-evidence.mjs verify \
+       --min-level L2 --max-age-min "$ARBITER_PREPUSH_MAX_AGE_MIN" 2>/dev/null); then
+    echo "PRE-PUSH: reusing green $REUSE_MSG, skipping rerun"
+    exit 0
+  fi
+fi
+# ─── end green-evidence reuse ────────────────────────────────────────────────
+
+# ─── one gate per repo, foreground (#2427) ───────────────────────────────────
+# Both branches below launch the heavy gate through scripts/lib/gate-mutex.mjs,
+# which takes the SAME per-repo flock `arbiter gate-exec` takes. Two pushes (or a
+# push and an agent's gate) in one repo therefore serialise instead of trampling
+# each other's temp files and starving each other's test workers.
+#
+# The wrapper runs the gate in THIS process group — no setsid, no `&`, no detach
+# — so a Ctrl-C on the push reaches the gate, and a pid-targeted signal is
+# forwarded down the descendant tree. The gate additionally watches the pid that
+# launched it and aborts between checks if it is gone, which covers the one
+# signal nothing can forward: SIGKILL. That is the orphan that finished long
+# after its push died and stamped a green marker for a tree it never tested.
+ORIG_DIR="$(pwd -P)"
+<% if (language === 'typescript') { %>
+
+# Vite/vitest (v5+) cannot handle '#' in the project root path.
+# Use pwd -P (physical path) to detect symlink-based worktrees where $PWD
+# may not contain '#' even though the real path does.
+# Rsync to a '#'-free temp dir and run the gate from there.
+if [[ "$ORIG_DIR" == *"#"* ]]; then
+  TMP_DIR=$(mktemp -d /tmp/arbiter-hook-XXXXXX)
+  trap 'rm -rf "$TMP_DIR"' EXIT
+  rsync -a --exclude .git --exclude node_modules --exclude dist . "$TMP_DIR/"
+  ln -sfn "$ORIG_DIR/node_modules" "$TMP_DIR/node_modules"
+  cd "$TMP_DIR"
+  # --dir "$ORIG_DIR": the mutex key derives from the REAL repo's git-common-dir.
+  # Keying it off this rsync'd /tmp copy would mint a fresh key per push — a null
+  # mutex that serialises nothing.
+  ARBITER_HOOK_GIT_CWD="$ORIG_DIR" node scripts/lib/gate-mutex.mjs run --dir "$ORIG_DIR" -- node scripts/check-all.mjs gate --json "$ORIG_DIR/.arbiter/gate/local-result.json"
+  exit $?
+fi
+<% } %>
+
+node scripts/lib/gate-mutex.mjs run --dir "$ORIG_DIR" -- node scripts/check-all.mjs gate --json .arbiter/gate/local-result.json

package/dist/templates/githooks/setup-hooks.sh.ejs

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# setup-hooks.sh: configure git to use .githooks/ directory
+# Run once after cloning: bash scripts/setup-hooks.sh
+set -e
+
+git config core.hooksPath .githooks
+chmod +x .githooks/*
+echo "Git hooks installed from .githooks/ directory."

package/dist/templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Summary
+
+<!-- What does this PR do? Why? (1-3 bullets) -->
+
+## Changes
+
+<!-- Bullet list of what changed -->
+
+## Gate Checklist
+
+- [ ] `node scripts/check-all.mjs L1` passes
+- [ ] `node scripts/check-all.mjs L2` passes
+- [ ] No orphan TODOs (all TODO have task IDs)
+- [ ] No invariant violations (see AGENTS.md)
+- [ ] Tests added/updated for changed code
+- [ ] Commit messages follow convention: `type(scope): summary`
+
+## Pipeline Artifacts
+
+<!-- Optional: link relevant artifacts from CI pipeline -->
+
+| Artifact     | Link |
+| ------------ | ---- |
+| Spec / Plan  |      |
+| Review score |      |
+| Log          |      |
+
+## Test Plan
+
+<!-- How was this tested? What scenarios were covered? -->
+
+## Security Checklist
+
+<!-- L2/L3 projects: verify SECURE_CODING_CHECKLIST.md before merging -->
+
+- [ ] Reviewed `docs/SECURE_CODING_CHECKLIST.md` (if present in this project)
+- [ ] No deprecated endpoints added without `Sunset` header (RFC 8594) — N/A if no public API changes