forge-orkes 0.42.0 → 0.46.0

package/template/.claude/hooks/block-dangerous-commands.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks destructive shell commands.
+# PreToolUse hook for Bash. Exit 2 = block. Exit 0 = allow.
+#
+# Deterministic belt-and-braces: this fires regardless of what the model decides,
+# so it catches the cases a model-driven skill (securing) would miss when skipped.
+#
+# Configurable via env:
+#   CLAUDE_PROTECTED_BRANCHES  comma list of branches push is refused to.
+#                              Default: main,master + git init.defaultBranch.
+#                              Set to "" (empty) to DISABLE the protected-branch
+#                              push check only — force-push, fs, db, and publish
+#                              guards still apply. Forge's own dev repo does this
+#                              because framework work legitimately lands on main.
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "jq is required for command protection hooks but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+contains_cmd() { printf '%s' "$COMMAND" | grep -qE "$1"; }
+contains_icmd() { printf '%s' "$COMMAND" | grep -qiE "$1"; }
+
+# ── Protected branch list ────────────────────────────────────────────────
+# Use ${VAR-default} (no colon) so an explicitly-empty value disables the check
+# while an unset value falls back to the default.
+DEFAULT_BRANCHES="main,master"
+if GIT_DEFAULT=$(git config --get init.defaultBranch 2>/dev/null) && [ -n "$GIT_DEFAULT" ]; then
+  DEFAULT_BRANCHES="$DEFAULT_BRANCHES,$GIT_DEFAULT"
+fi
+PROTECTED_BRANCHES="${CLAUDE_PROTECTED_BRANCHES-$DEFAULT_BRANCHES}"
+
+# ── Git push protections ────────────────────────────────────────────────
+if contains_cmd '(^|[;&|()]+[[:space:]]*)git[[:space:]]+push'; then
+  # Protected-branch checks are skipped when the list is empty.
+  if [ -n "$PROTECTED_BRANCHES" ]; then
+    BR_REGEX=$(printf '%s' "$PROTECTED_BRANCHES" | tr ',' '\n' | awk 'NF{printf "%s%s",sep,$0; sep="|"}')
+    # Explicit refspec to a protected branch (origin main, :main, HEAD:main)
+    if contains_cmd "git[[:space:]]+push[[:space:]]+[^[:space:]]+[[:space:]]+([^[:space:]]*:)?($BR_REGEX)(\$|[[:space:]])"; then
+      MATCHED_BRANCH=$(printf '%s' "$COMMAND" | grep -oE "($BR_REGEX)(\$|[[:space:]])" | head -1 | tr -d '[:space:]')
+      emit_deny "Blocked: push to protected branch '${MATCHED_BRANCH:-main}'. Use a feature branch and open a PR."
+    fi
+    if contains_cmd "git[[:space:]]+push.*:($BR_REGEX)(\$|[[:space:]])"; then
+      MATCHED_BRANCH=$(printf '%s' "$COMMAND" | grep -oE ":($BR_REGEX)(\$|[[:space:]])" | head -1 | tr -d ': [:space:]')
+      emit_deny "Blocked: push to protected branch '${MATCHED_BRANCH:-main}' via refspec. Use a feature branch and open a PR."
+    fi
+    # Bare `git push` while on protected branch
+    if contains_cmd 'git[[:space:]]+push[[:space:]]*($|[;&|])'; then
+      CURRENT=$(git branch --show-current 2>/dev/null || true)
+      if [ -n "$CURRENT" ] && printf '%s' ",$PROTECTED_BRANCHES," | grep -q ",$CURRENT,"; then
+        emit_deny "Blocked: you are on '$CURRENT' (a protected branch). Switch to a feature branch."
+      fi
+    fi
+  fi
+  # Force push (but allow --force-with-lease). Always enforced — Forge never force-pushes.
+  if contains_cmd 'git[[:space:]]+push([[:space:]]+[^[:space:]]+)*[[:space:]]+(-[a-zA-Z]*f[a-zA-Z]*|--force)([[:space:]=]|$)' \
+     && ! contains_cmd '\-\-force-with-lease'; then
+    emit_deny "Blocked: force push is not allowed. Use --force-with-lease if you must overwrite remote."
+  fi
+fi
+
+# ── Destructive filesystem operations ───────────────────────────────────
+# rm -rf targeting root, home, $HOME, $VAR (any unresolved expansion), or parent traversal.
+CMD_NOQUOTE=$(printf '%s' "$COMMAND" | tr -d "'\"")
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+(/([[:space:]]|\*|$)|~|\$HOME|\$[A-Za-z_][A-Za-z0-9_]*|\.\./\.\.)' ; then
+  emit_deny "Blocked: recursive force-delete on /, ~, \$HOME, an unresolved \$VAR, or .../.. path. Specify a concrete safe target."
+fi
+# rm -rf /usr, /etc, /var, /bin, etc.
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+/(usr|etc|var|bin|sbin|lib|opt|root|boot)([[:space:]/]|$)'; then
+  emit_deny "Blocked: recursive delete targeting a system directory."
+fi
+# rm -rf where the target is produced by $(...) or `...` command substitution.
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+[^;&|]*(\$\(|`)'; then
+  emit_deny "Blocked: recursive force-delete with a shell-substituted target (\$(...) or \`...\`). Pass a literal path."
+fi
+
+# ── Dangerous database operations ───────────────────────────────────────
+if contains_icmd 'DROP[[:space:]]+(TABLE|DATABASE|SCHEMA)[[:space:]]+'; then
+  emit_deny "Blocked: DROP TABLE/DATABASE/SCHEMA detected. Run manually if intended."
+fi
+# DELETE FROM without a WHERE on the SAME statement (split on ';').
+if printf '%s\n' "$COMMAND" | awk '
+  BEGIN { IGNORECASE=1; RS=";" }
+  /DELETE[[:space:]]+FROM[[:space:]]+[A-Za-z_][A-Za-z0-9_.]*/ {
+    if ($0 !~ /WHERE/) { print "BAD"; exit }
+  }
+' | grep -q BAD; then
+  emit_deny "Blocked: DELETE FROM without a WHERE clause. Add a WHERE or run manually."
+fi
+if contains_icmd 'TRUNCATE[[:space:]]+TABLE'; then
+  emit_deny "Blocked: TRUNCATE TABLE detected. Run manually if intended."
+fi
+
+# ── Framework-specific destructive migration commands ───────────────────
+# These drop data. Block — require manual invocation against a dev DB.
+if contains_icmd '(php[[:space:]]+artisan[[:space:]]+(migrate:fresh|migrate:reset|migrate:refresh|db:wipe)|(rails|rake)[[:space:]]+db:(drop|reset)|prisma[[:space:]]+migrate[[:space:]]+reset|sequelize[[:space:]]+db:drop)([[:space:]]|$)'; then
+  emit_deny "Blocked: destructive migration command detected (drops/recreates the database). Run manually, and only against a dev DB."
+fi
+
+# ── Dangerous system commands ───────────────────────────────────────────
+# chmod: any world-writable/universal mode (0?777 or a+rwx)
+if contains_cmd 'chmod([[:space:]]+-[a-zA-Z]+)*[[:space:]]+0?777([[:space:]]|$)' \
+  || contains_cmd 'chmod([[:space:]]+-[a-zA-Z]+)*[[:space:]]+a\+rwx([[:space:]]|$)'; then
+  emit_deny "Blocked: chmod 777 / a+rwx grants everyone full access. Use restrictive perms."
+fi
+
+# curl/wget piped to a shell
+if contains_cmd '(curl|wget)[[:space:]].*\|[[:space:]]*(sudo[[:space:]]+)?(bash|sh|zsh|ksh|fish|dash|csh)([[:space:]]|$)'; then
+  emit_deny "Blocked: piping downloaded content directly to a shell is dangerous."
+fi
+
+# Disk / partition. Only REDIRECTIONS to /dev/ are destructive — `2>/dev/null` is not.
+if printf '%s' "$COMMAND" | grep -qE '(^|[^0-9&])>[[:space:]]*/dev/[a-zA-Z][a-zA-Z0-9]*' \
+   && ! printf '%s' "$COMMAND" | grep -qE '>[[:space:]]*/dev/(null|stdout|stderr|tty|zero|random|urandom)([[:space:]]|$)' ; then
+  emit_deny "Blocked: redirection into a raw device file can destroy data."
+fi
+if contains_cmd '(^|[;&|[:space:]])(mkfs|mkfs\.[a-z0-9]+)([[:space:]]|$)' \
+  || contains_cmd '(^|[;&|[:space:]])dd[[:space:]]+[^|]*(if|of)=/dev/[a-zA-Z]' ; then
+  emit_deny "Blocked: mkfs/dd against a device node. Irreversible data loss."
+fi
+
+# ── Destructive git ─────────────────────────────────────────────────────
+if contains_cmd 'git[[:space:]]+reset[[:space:]]+--hard'; then
+  emit_deny "Blocked: git reset --hard discards uncommitted changes permanently. Use git stash or commit first."
+fi
+if contains_cmd 'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'; then
+  emit_deny "Blocked: git clean -f permanently deletes untracked files."
+fi
+
+# ── Accidental package publishing ───────────────────────────────────────
+# Allow --dry-run variants. Covers the common package managers.
+publish_patterns=(
+  '(npm|yarn|pnpm|bun)[[:space:]]+publish'
+  'cargo[[:space:]]+publish'
+  'gem[[:space:]]+push'
+  'twine[[:space:]]+upload'
+  'uv[[:space:]]+publish'
+  'poetry[[:space:]]+publish'
+  'composer[[:space:]]+publish'
+)
+for pat in "${publish_patterns[@]}"; do
+  if contains_cmd "$pat" && ! contains_cmd '(^|[[:space:]])(--dry-run|-n)([[:space:]=]|$)'; then
+    emit_deny "Blocked: publishing packages should run in CI or be done manually, not via the agent."
+  fi
+done
+
+exit 0

package/template/.claude/hooks/forge-active-skill-guard.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Forge PreToolUse(Write|Edit) workflow guard.
+#
+# Blocks code edits when no Forge skill is driving the session, nudging the
+# operator to invoke /forge or /quick-tasking first. A skill IS active when
+# EITHER signal holds:
+#
+#   (a) the ephemeral marker .forge/.active-skill exists — written by the
+#       PostToolUse(Skill) hook on every Skill invocation; reliable for short
+#       skills (quick-tasking) but cleared between turns / at session
+#       boundaries, so a long executing run loses it mid-flight; OR
+#   (b) a milestone is mid-execution (current.status: executing) — the durable
+#       signal that survives across turns because it lives in a committed state
+#       file, not an ephemeral marker.
+#
+# (b) is the fix for the failure mode where the marker was cleared 3+ times in
+# one executing session and legitimate edits got blocked (forge#12). When (b)
+# holds we also re-assert the marker so the rest of the turn is cheap.
+#
+# Contract: exit 0 = allow, exit 2 = block with guidance. Advisory workflow
+# gate — the documented bypass is `touch .forge/.active-skill`.
+
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -n "$ROOT" ] || ROOT="$PWD"
+FORGE="$ROOT/.forge"
+
+# (a) marker present → active.
+[ -f "$FORGE/.active-skill" ] && exit 0
+
+# (b) a milestone is executing → durable "skill active" signal that outlives the
+#     marker. Match the indented `current.status: executing` line; a milestone
+#     file is small, so the grep is cheap.
+if ls "$FORGE"/state/milestone-*.yml >/dev/null 2>&1; then
+  if grep -qE '^[[:space:]]+status:[[:space:]]*executing([[:space:]]|$)' "$FORGE"/state/milestone-*.yml 2>/dev/null; then
+    # Self-heal: re-assert the marker so later checks this turn short-circuit at (a).
+    printf 'executing\n' > "$FORGE/.active-skill" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+echo "[Forge] No active skill. Invoke /forge or /quick-tasking before editing code. To bypass: touch .forge/.active-skill" >&2
+exit 2

package/template/.claude/hooks/forge-reserve.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env sh
+# forge-reserve — allocate a collision-safe sequential id (ADR/DEF/FR/NFR).
+#
+# Implements ADR-021: the coordination point is a machine-local ledger in the
+# git COMMON dir (.git/forge/id-reservations), shared instantly across every
+# sibling worktree of the repo on this machine — the input ADR-016's
+# branch-tracked reservations.yml could not see. Same primitive as the
+# integration flag (.git/forge/integration-pending).
+#
+#   forge-reserve <kind> --milestone <id> [--summary <text>]
+#     kind ∈ {adr|def|fr|nfr}
+#
+# stdout: the allocated id and NOTHING else (e.g. ADR-022). All logs → stderr.
+# exit:   0 success; 2 bad/missing kind or args; 3 lock timeout. On non-zero
+#         exit nothing is written.
+#
+# Side effects (both UNcommitted — the caller commits reservations.yml with its
+# work): appends one TSV line to the common-dir ledger and one YAML block to the
+# worktree's .forge/reservations.yml, both under a portable mkdir lock.
+#
+# Pure POSIX sh — no bashisms, no flock (absent on macOS, ADR-021 point 3),
+# no node/python. Only git/mkdir/awk/grep/sed/date/stat.
+set -eu
+
+WAIT="${FORGE_RESERVE_WAIT:-5}"    # seconds: bounded lock-acquire budget
+STALE="${FORGE_RESERVE_STALE:-15}" # seconds: a lock older than this is broken
+SLEEP="0.1"                         # retry interval while the lock is held
+
+# --- 1. parse args ----------------------------------------------------------
+kind=""
+milestone=""
+summary=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --milestone) shift; milestone="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --milestone=*) milestone="${1#*=}"; shift ;;
+    --summary) shift; summary="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --summary=*) summary="${1#*=}"; shift ;;
+    -*) printf 'forge-reserve: unknown option: %s\n' "$1" >&2; exit 2 ;;
+    *)
+      if [ -z "$kind" ]; then kind="$1"; shift
+      else printf 'forge-reserve: unexpected argument: %s\n' "$1" >&2; exit 2; fi
+      ;;
+  esac
+done
+
+# Validate kind BEFORE touching git, the lock, or any file — a bad kind must
+# exit non-zero having written nothing (must_have truth #3).
+case "$kind" in
+  adr) prefix="ADR" ;;
+  def) prefix="DEF" ;;
+  fr)  prefix="FR" ;;
+  nfr) prefix="NFR" ;;
+  "") printf 'forge-reserve: missing kind (adr|def|fr|nfr)\n' >&2; exit 2 ;;
+  *) printf 'forge-reserve: unknown kind: %s (expected adr|def|fr|nfr)\n' "$kind" >&2; exit 2 ;;
+esac
+[ -n "$milestone" ] || { printf 'forge-reserve: --milestone <id> is required\n' >&2; exit 2; }
+
+# --- 2. resolve paths -------------------------------------------------------
+common="$(git rev-parse --git-common-dir)"
+top="$(git rev-parse --show-toplevel)"
+mkdir -p "$common/forge"
+ledger="$common/forge/id-reservations"
+lock="$common/forge/id-reservations.lock"
+reservations="$top/.forge/reservations.yml"
+
+# Portable mtime → epoch: BSD/macOS `stat -f %m`, GNU `stat -c %Y`. This is the
+# one place a platform branch is warranted (ADR-021 point 3: macOS is a
+# first-class platform and its stat flags differ from GNU's).
+get_mtime() {
+  stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || true
+}
+
+# --- 3. acquire lock (atomic mkdir, bounded retry, staleness-break) ----------
+# mkdir is POSIX-atomic: it succeeds for exactly one racer and fails if the dir
+# already exists — a lock without flock. A crashed helper's lock is broken after
+# STALE seconds so it can't wedge the namespace forever.
+max_iters="$(awk -v w="$WAIT" -v s="$SLEEP" 'BEGIN{print int(w/s)}')"
+iters=0
+while ! mkdir "$lock" 2>/dev/null; do
+  mt="$(get_mtime "$lock")"
+  now_epoch="$(date +%s)"
+  if [ -n "$mt" ] && [ "$((now_epoch - mt))" -ge "$STALE" ]; then
+    printf 'forge-reserve: breaking stale lock (age %ss): %s\n' "$((now_epoch - mt))" "$lock" >&2
+    rmdir "$lock" 2>/dev/null || true
+    continue
+  fi
+  iters="$((iters + 1))"
+  if [ "$iters" -ge "$max_iters" ]; then
+    printf 'forge-reserve: lock timeout after ~%ss: %s\n' "$WAIT" "$lock" >&2
+    exit 3
+  fi
+  sleep "$SLEEP"
+done
+# Only now that the lock is ours do we install the release trap.
+trap 'rmdir "$lock" 2>/dev/null || true' EXIT INT TERM
+
+# --- 4/5. three-way max(ledger ∪ in-tree ∪ main:reservations.yml) + 1 --------
+# Everything numeric goes through awk (n+0) so leading-zero ids like 021 are read
+# as decimal 21, never octal — no shell $(( )) octal trap.
+
+# (a) ledger — same-machine siblings, INCLUDING uncommitted (the ADR-016-blind input)
+ledger_max=0
+if [ -f "$ledger" ]; then
+  ledger_max="$(awk -F'\t' -v k="$kind" \
+    '$1==k { split($2,a,"-"); n=a[2]+0; if(n>m)m=n } END{print m+0}' "$ledger")"
+fi
+
+# (b) in-tree — landed ids in THIS worktree. Exact-prefix match in awk ($1==p) so
+# FR does not swallow NFR (FR is a substring of NFR).
+if [ "$kind" = "adr" ]; then
+  intree_max="$(ls "$top/docs/decisions" 2>/dev/null \
+    | awk -F- '/^ADR-[0-9]/ { n=$2+0; if(n>m)m=n } END{print m+0}')"
+else
+  intree_max="$(grep -rhoE '[A-Z]+-[0-9]+' "$top/.forge/requirements/" 2>/dev/null \
+    | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
+fi
+
+# (c) main:reservations.yml — cross-machine / cold-start floor (survives a
+# .git/forge wipe; carries another machine's MERGED reservations). Absent → 0.
+main_max="$(git show main:.forge/reservations.yml 2>/dev/null \
+  | grep -oE '[A-Z]+-[0-9]+' \
+  | awk -F- -v p="$prefix" '$1==p { n=$2+0; if(n>m)m=n } END{print m+0}')"
+[ -n "$main_max" ] || main_max=0
+
+next="$(awk -v a="$ledger_max" -v b="$intree_max" -v c="$main_max" \
+  'BEGIN{m=a; if(b>m)m=b; if(c>m)m=c; print m+1}')"
+id="$(printf '%s-%03d' "$prefix" "$next")"
+
+# --- 6. dual-write (still under the lock) -----------------------------------
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf '%s\t%s\t%s\t%s\n' "$kind" "$id" "$milestone" "$now" >> "$ledger"
+
+# reservations.yml missing → seed the 0.42.0 starter HEADER, but with a bare
+# `reservations:` key (not the guide's `reservations: []`) so the block items we
+# append below form a valid sequence — appending `- kind:` under a `[]` flow list
+# is malformed YAML. Existing repo files already use the bare-key block form.
+if [ ! -f "$reservations" ]; then
+  mkdir -p "$(dirname "$reservations")"
+  cat > "$reservations" <<'YML'
+# Forge ID Reservations — cross-worktree coordination for ADR / DEF / FR / NFR numbers
+# Written by .claude/hooks/forge-reserve.sh (ADR-021). The machine-local ledger
+# (.git/forge/id-reservations) is the same-machine coordination point; this file
+# is the durable committed audit trail + cross-machine floor. Append-only; never
+# edit prior entries. Next number for a kind = max(ledger, in-tree, main) + 1.
+# kind ∈ {adr,def,fr,nfr}. See FORGE.md → ID Reservation Protocol + ADR-021.
+reservations:
+YML
+fi
+
+# YAML double-quoted scalar: escape backslash then double-quote.
+esc_summary="$(printf '%s' "$summary" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+{
+  printf '  - kind: %s\n' "$kind"
+  printf '    id: %s\n' "$id"
+  printf '    milestone: %s\n' "$milestone"
+  printf '    reserved_at: "%s"\n' "$now"
+  printf '    summary: "%s"\n' "$esc_summary"
+} >> "$reservations"
+
+# --- 7. emit the id (stdout only); trap releases the lock on exit ------------
+printf '%s\n' "$id"

package/template/.claude/hooks/format-on-save.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Forge — runs the project's formatter after the agent edits a file.
+# PostToolUse hook for Edit|Write|MultiEdit. Always exits 0 — a formatting
+# failure must never block subsequent work.
+#
+# "Most specific project config wins". A formatter only runs when BOTH the tool
+# and the project's config for it are present, so this never fires against repos
+# that haven't opted in.
+
+set -uo pipefail
+
+# jq missing → silently skip. Never block work over formatting.
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+EXT="${FILE_PATH##*.}"
+EXT_LC=$(printf '%s' "$EXT" | tr '[:upper:]' '[:lower:]')
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+has_file() { [ -f "$REPO_ROOT/$1" ]; }
+has_any()  { for f in "$@"; do has_file "$f" && return 0; done; return 1; }
+pyproject_has() { has_file "pyproject.toml" && grep -q "^\[$1\]" "$REPO_ROOT/pyproject.toml" 2>/dev/null; }
+pkgjson_has_key() { has_file "package.json" && grep -q "\"$1\"" "$REPO_ROOT/package.json" 2>/dev/null; }
+
+run() {
+  printf 'format-on-save: %s\n' "$*" >&2
+  "$@" >/dev/null 2>&1 || true
+}
+
+case "$EXT_LC" in
+  # ── Python ────────────────────────────────────────────────────────────
+  py)
+    if command -v ruff >/dev/null 2>&1 \
+       && ( has_any "ruff.toml" ".ruff.toml" || pyproject_has "tool.ruff" ); then
+      run ruff format "$FILE_PATH"
+      run ruff check --fix "$FILE_PATH"
+    elif command -v black >/dev/null 2>&1 && pyproject_has "tool.black"; then
+      run black --quiet "$FILE_PATH"
+      command -v isort >/dev/null 2>&1 && run isort --quiet "$FILE_PATH"
+    fi
+    ;;
+  # ── PHP / Laravel ─────────────────────────────────────────────────────
+  php)
+    if [ -x "$REPO_ROOT/vendor/bin/pint" ]; then
+      run "$REPO_ROOT/vendor/bin/pint" "$FILE_PATH"
+    elif command -v php-cs-fixer >/dev/null 2>&1 && has_any ".php-cs-fixer.php" ".php-cs-fixer.dist.php"; then
+      run php-cs-fixer fix "$FILE_PATH"
+    fi
+    ;;
+  # ── JS / TS / Vue / CSS / HTML / JSON / MD / YAML ─────────────────────
+  js|jsx|ts|tsx|vue|mjs|cjs|css|scss|sass|less|html|json|jsonc|md|mdx|yml|yaml)
+    if has_any "biome.json" "biome.jsonc" && [ -x "$REPO_ROOT/node_modules/.bin/biome" ]; then
+      run "$REPO_ROOT/node_modules/.bin/biome" format --write "$FILE_PATH"
+      run "$REPO_ROOT/node_modules/.bin/biome" check --write "$FILE_PATH"
+    else
+      if [ -x "$REPO_ROOT/node_modules/.bin/prettier" ] \
+         && ( has_any ".prettierrc" ".prettierrc.json" ".prettierrc.js" ".prettierrc.cjs" ".prettierrc.mjs" ".prettierrc.yaml" ".prettierrc.yml" "prettier.config.js" "prettier.config.cjs" "prettier.config.mjs" \
+              || pkgjson_has_key "prettier" ); then
+        run "$REPO_ROOT/node_modules/.bin/prettier" --write --log-level=silent "$FILE_PATH"
+      fi
+      case "$EXT_LC" in
+        js|jsx|ts|tsx|vue|mjs|cjs)
+          if [ -x "$REPO_ROOT/node_modules/.bin/eslint" ] \
+             && ( has_any ".eslintrc" ".eslintrc.js" ".eslintrc.cjs" ".eslintrc.json" ".eslintrc.yml" ".eslintrc.yaml" "eslint.config.js" "eslint.config.mjs" "eslint.config.cjs" "eslint.config.ts" \
+                  || pkgjson_has_key "eslintConfig" ); then
+            run "$REPO_ROOT/node_modules/.bin/eslint" --fix "$FILE_PATH"
+          fi
+          ;;
+      esac
+    fi
+    ;;
+  # ── Rust ──────────────────────────────────────────────────────────────
+  rs)
+    command -v rustfmt >/dev/null 2>&1 && run rustfmt "$FILE_PATH"
+    ;;
+  # ── Go ────────────────────────────────────────────────────────────────
+  go)
+    if command -v goimports >/dev/null 2>&1; then
+      run goimports -w "$FILE_PATH"
+    elif command -v gofmt >/dev/null 2>&1; then
+      run gofmt -w "$FILE_PATH"
+    fi
+    ;;
+  # ── Shell ─────────────────────────────────────────────────────────────
+  sh|bash)
+    command -v shfmt >/dev/null 2>&1 && run shfmt -w "$FILE_PATH"
+    ;;
+esac
+
+exit 0

package/template/.claude/hooks/protect-files.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks edits to sensitive or generated files.
+# PreToolUse hook for Edit|Write. Exit 2 = block. Exit 0 = allow.
+
+set -uo pipefail
+
+emit() {
+  # $1 = decision (deny|ask) ; $2 = reason
+  local decision="$1"
+  local reason="${2//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s","permissionDecisionReason":"%s"}}\n' "$decision" "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit deny "jq is required for file protection hooks but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+
+BASENAME=$(basename -- "$FILE_PATH")
+BASENAME_LC=$(printf '%s' "$BASENAME" | tr '[:upper:]' '[:lower:]')
+PATH_LC=$(printf '%s' "$FILE_PATH" | tr '[:upper:]' '[:lower:]')
+
+# Allowlist: template/example env files are meant to be checked in and edited.
+case "$BASENAME_LC" in
+  .env.example|.env.sample|.env.dist|.env.template)
+    exit 0
+    ;;
+esac
+
+# Protected basename patterns (matched case-insensitively).
+PROTECTED_PATTERNS=(
+  ".env"
+  ".env.*"
+  "*.pem"
+  "*.key"
+  "*.crt"
+  "*.p12"
+  "*.pfx"
+  "id_rsa"
+  "id_ed25519"
+  "credentials.json"
+  ".npmrc"
+  ".pypirc"
+  ".composer-auth.json"
+  "auth.json"
+  # Lock files — update through the package manager, never by hand.
+  "package-lock.json"
+  "yarn.lock"
+  "pnpm-lock.yaml"
+  "composer.lock"
+  "uv.lock"
+  "poetry.lock"
+  "Gemfile.lock"
+  "Cargo.lock"
+  "go.sum"
+  # Generated / minified
+  "*.gen.ts"
+  "*.generated.*"
+  "*.min.js"
+  "*.min.css"
+)
+
+shopt -s nocasematch 2>/dev/null || true
+for pattern in "${PROTECTED_PATTERNS[@]}"; do
+  case "$BASENAME_LC" in
+    $pattern)
+      emit deny "Protected file: $BASENAME matches pattern '$pattern'. Edit via the package manager or the appropriate secret store."
+      ;;
+  esac
+done
+
+# Sensitive directories (lower-cased path for case-insensitive matches).
+case "$PATH_LC" in
+  .git/*|*/.git/*)
+    emit deny "Cannot edit files inside .git/" ;;
+  secrets/*|*/secrets/*)
+    emit deny "Cannot edit files inside secrets/" ;;
+  .secrets/*|*/.secrets/*)
+    emit deny "Cannot edit files inside .secrets/" ;;
+  .env|.env.*|*/.env|*/.env.*)
+    emit deny "Cannot edit .env files" ;;
+esac
+
+# Framework-authoring files. In a normal project these are re-synced via
+# /upgrading, never hand-edited — so we block hooks and prompt on settings.
+# FORGE_ALLOW_HOOK_EDITS=1 lifts both, set only in the Forge framework repo
+# itself (where authoring hooks and settings IS the work).
+if [ -z "${FORGE_ALLOW_HOOK_EDITS:-}" ]; then
+  case "$PATH_LC" in
+    .claude/hooks/*|*/.claude/hooks/*)
+      emit deny "Cannot edit hook scripts — these enforce safety boundaries. Update them in the framework repo and re-sync (/upgrading)." ;;
+    .claude/settings.json|*/.claude/settings.json|.claude/settings.local.json|*/.claude/settings.local.json)
+      emit ask "Editing settings.json — this controls permissions and hooks. Confirm this change." ;;
+  esac
+fi
+
+exit 0

package/template/.claude/hooks/scan-secrets.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — scans file content for accidental secrets before writing.
+# PreToolUse hook for Edit|Write. Exit 2 = block (decision "ask" so the user can
+# override for genuine test fixtures). Exit 0 = allow.
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "jq is required for secret scanning but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+if [ "$TOOL_NAME" = "Write" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+else
+  exit 0
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+MATCHES=""
+
+# AWS Access Key IDs
+if echo "$CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+  MATCHES="$MATCHES AWS access key (AKIA...);"
+fi
+# AWS Secret Access Keys (40 chars base64 after a key assignment)
+if echo "$CONTENT" | grep -qiE '(aws_secret_access_key|secret_key)[[:space:]]*[=:][[:space:]]*["\x27]?[A-Za-z0-9/+=]{40}'; then
+  MATCHES="$MATCHES AWS secret key;"
+fi
+# GitHub tokens (PAT, OAuth, App)
+if echo "$CONTENT" | grep -qE '(ghp_|gho_|ghs_|ghr_|github_pat_)[a-zA-Z0-9_]{20,}'; then
+  MATCHES="$MATCHES GitHub token;"
+fi
+# OpenAI / Anthropic / Stripe style keys (sk-...)
+if echo "$CONTENT" | grep -qE 'sk-[a-zA-Z0-9]{20,}'; then
+  MATCHES="$MATCHES API key (sk-...);"
+fi
+# Anthropic-specific keys
+if echo "$CONTENT" | grep -qE 'sk-ant-[a-zA-Z0-9_-]{20,}'; then
+  MATCHES="$MATCHES Anthropic API key;"
+fi
+# Slack tokens
+if echo "$CONTENT" | grep -qE 'xox[bpras]-[0-9a-zA-Z-]{10,}'; then
+  MATCHES="$MATCHES Slack token;"
+fi
+# Google API keys
+if echo "$CONTENT" | grep -qE 'AIza[0-9A-Za-z_-]{35}'; then
+  MATCHES="$MATCHES Google API key;"
+fi
+# Private key blocks
+if echo "$CONTENT" | grep -qE -- '-----BEGIN[[:space:]]+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----'; then
+  MATCHES="$MATCHES private key block;"
+fi
+# Connection strings with embedded credentials
+if echo "$CONTENT" | grep -qE '(mongodb|postgres|postgresql|mysql|redis|amqp|smtp|mssql)(\+[a-z]+)?://[^:[:space:]]+:[^@[:space:]]+@'; then
+  MATCHES="$MATCHES connection string with credentials;"
+fi
+# Laravel APP_KEY with a real base64 value (not a placeholder)
+if echo "$CONTENT" | grep -qE 'APP_KEY[[:space:]]*=[[:space:]]*base64:[A-Za-z0-9+/=]{40,}'; then
+  MATCHES="$MATCHES Laravel APP_KEY;"
+fi
+# Generic password/secret/token assignments with literal string values.
+# Excludes env var references (process.env, os.environ, getenv, ${...}, ENV[, env(, config()).
+if echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27][^"\x27]{8,}["\x27]' && \
+   ! echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27]?(process\.env|os\.environ|getenv|\$\{|ENV\[|env\(|config\()'; then
+  MATCHES="$MATCHES hardcoded credential;"
+fi
+
+if [ -n "$MATCHES" ]; then
+  # "ask" not "deny" — warn but let the user override (could be a fixture).
+  REASON="Possible secret detected in content:$MATCHES Review carefully before allowing."
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+exit 0