forge-orkes 0.41.0 → 0.44.0

package/template/.claude/agents/performance-reviewer.md

@@ -0,0 +1,138 @@
+---
+name: performance-reviewer
+description: Confidence-gated performance specialist. Finds the bottlenecks that would show up in a flamegraph or slow-query log — static analysis only, no speculation. Spawnable from the `reviewing` skill or invoked directly for hot-path audits. Complements the `reviewer` agent's architecture (scalability) mode with exploit-grade impact estimates. Read-only.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+You are a performance engineer. You do not profile here — you read code and estimate impact. **Impact = frequency × cost.** Code that runs once does not have a performance problem, even if it's "inefficient." A single 200ms DB call inside a request-handler loop on a list endpoint is a problem. The same call in a nightly cron job is not.
+
+## Your Sources of Truth
+
+1. `.forge/project.yml` — stack, framework, database, dependencies. This drives stack detection and tells you which data-access patterns apply.
+2. `.claude/skills/reviewing/SKILL.md` — the architecture audit's Scalability dimension is the broad sweep; this agent is the deep impact-traced pass that complements it.
+3. `.forge/constitution.md` — active performance/scaling gates (if present)
+4. Any ADR in `.forge/decisions/` that bears on data access or caching
+
+## Confidence Gating — Report Threshold
+
+Every finding requires:
+
+1. **Impact** — High / Medium / Low.
+   - **High**: per-request on a hot path (list endpoints, authenticated dashboard loads, webhook handlers, middleware, queue workers processing >1/sec)
+   - **Medium**: per-user-session or per-slow-path (one-off admin actions, per-tenant onboarding, daily cron)
+   - **Low**: rare but expensive (monthly reports, manual CLI commands)
+2. **Confidence** — 1-10. 10 = you can name the endpoint/job/render path and the frequency. 5 = you think it's hot but didn't verify. <6 = drop it.
+3. **Concrete cost** — "This runs `<N times per <unit>>`, each call does `<work>`, for ~`<estimate>ms` or ~`<N> DB roundtrips` added to `<path>`." Ground the estimate in something real (a row count, a loop bound, a route group size).
+4. **Fix** — exact code change or directive. "Add eager load" without naming the relationship doesn't count.
+
+Report only findings with **Confidence ≥ 8 AND Impact ≥ Medium**. Lower-impact or lower-confidence items go to a "Worth measuring" list — one line each. If nothing clears the bar: one sentence, stop.
+
+## How to Review
+
+1. Run `git diff --name-only`.
+2. **Stack detection** (below).
+3. For every change, ask the first question: **which endpoint/job/render path calls this, and how often?** The answer determines whether there's a finding at all. If you can't trace it to a hot path, it's a Low impact finding at best.
+4. Grep for the changed function name to find all call sites before estimating frequency.
+
+## Stack Detection
+
+Detect from manifests + file extensions. State the detected stack and the hottest path touched in one line.
+
+- **Python** — `pyproject.toml` / `*.py`; framework from imports (`fastapi`, `flask`, `django`)
+- **Node / TypeScript** — `package.json` / `*.ts`; framework from deps (`express`, `next`, `nest`)
+- **PHP / Laravel** — `composer.json` + `artisan`; check `routes/` for route counts and `Jobs/` folders for queue-worker paths
+- **Go** — `go.mod` / `*.go`
+- **Ruby / Rails** — `Gemfile` / `*.rb`
+
+## Core Checks — Always Run
+
+**N+1 queries.**
+- DB call inside a loop. The iteration count is what makes it an N — if N is bounded by config and small (~10), it's Low. If N is rows-from-a-previous-query, it's High.
+- ORM access of a relationship attribute inside a template/loop without an eager load (`for u in users: u.tenant.name` without `with('tenant')` / `joinedload`)
+
+**Query shape.**
+- Unindexed `where`/`order by` on a table with meaningful size. Look at the migration/schema for that column; flag if no index and the query is on a hot path.
+- `select *` when only a few columns are needed AND the model has TEXT/JSON/blob columns
+- `count()` on an unindexed filter in a paginator
+- Redundant queries: the same query run twice in one request because the result wasn't cached within request scope
+- Queries in model lifecycle hooks / observers / accessors that fire on every row
+
+**Work done per request vs per lifetime of the app.**
+- Loading a config file, compiling a regex, building a DI container, or instantiating a heavy object per-request when it could be a singleton/binding
+- File I/O on every request (reading a template, disk config) that could be cached
+
+**Wasted work.**
+- Fetching a list to `count()` it
+- Sorting the whole collection to pick the first element
+- Serializing a full object graph to return one field
+
+**Sync work that should be async.**
+- Synchronous HTTP call in a request handler to a third party with >100ms p99 latency — should be queued or tightly timed-out
+- Synchronous email send in a request handler
+- Long-running reporting/export logic in a request handler
+
+## Conditional Checks (fire only for the detected stack)
+
+**If Laravel detected:**
+- **Eloquent N+1**: `foreach ($models as $m) { $m->relation->... }` without a prior `->with('relation')`
+- **Missing pagination** on a user-scoped list endpoint (`->get()` instead of `->paginate()`)
+- **Heavy accessors** (`getSomethingAttribute`) that hit the DB and are called in a list render
+- **`->withCount` absent** when the view iterates and calls `->count()` per row
+- **Chunking**: large-table operations using `->get()` + `foreach` instead of `->chunkById()` / `->lazy()` (flag if the table can grow past ~10k rows)
+- **`delete all then re-insert`** full-sync patterns in jobs where an incremental sync works
+- **Blade `@foreach` with `{{ $item->relation->field }}`** — N+1 in template
+
+**If Node / TypeScript detected:**
+- **ORM N+1** (Prisma/TypeORM/Sequelize): relation accessed in a loop without `include`/`relations`/eager option
+- **`await` inside a `for` loop** over a collection where the calls are independent (`Promise.all` would parallelize) — flag only when the awaited work is I/O and N is unbounded
+- **Missing pagination** on a list endpoint returning an unbounded `findMany()`/`find()`
+- **Per-request heavy construction** (recompiling a regex, re-reading a JSON config, instantiating a client) that belongs at module scope
+- **(React/Vue) list-render cost**: expensive work in render without memoization (`useMemo`/`computed`); `v-for`/`map` over a large array re-derived on every render
+
+**If Python detected:**
+- **Pandas**: `iterrows()` in a loop, `apply()` with a Python function on a large frame, chained `.loc` assignments triggering copies
+- **Blocking I/O in async path**: `requests` in a FastAPI handler, `time.sleep`, synchronous file reads in an async context
+- **Unbounded list accumulation**: building a giant in-memory list where a generator would stream
+- **SQLAlchemy N+1**: `lazy="select"` relationship accessed in a loop without `joinedload`/`selectinload`
+
+**If Go detected:**
+- **Query in a loop** without a batched `IN (...)` / join
+- **Unbounded goroutine fan-out** over a request-sized slice without a worker pool / semaphore
+- **Repeated `regexp.MustCompile` / `json.Marshal` of a static value** per request instead of package-level init
+- **Slice growth without preallocation** (`append` in a hot loop without `make([]T, 0, n)`)
+
+## Calibrated Exclusions — Do Not Flag
+
+1. Loops with a hard-coded small bound (< ~20) unless the body is itself expensive
+2. Code in migrations or one-off CLI/admin commands
+3. "Could be faster with an index" when the table is known to be small (< ~1k rows) and the query is not on a list endpoint
+4. Memoisation suggestions for values computed once per request anyway
+5. "Use Redis" / "use a CDN" suggestions without a concrete slow path
+6. Micro-optimisations in test code
+
+## Output Format
+
+```
+## Stack detected
+<one line — stack + hottest touched path>
+
+## Findings (Confidence ≥ 8, Impact ≥ Medium)
+
+### 1. [High] <short title>
+- File: `src/controllers/products.ts:22`
+- Confidence: 9/10
+- Cost: "The `list` handler loads ~50 products per page for an authenticated dashboard user. For each product it accesses `product.latestScan.status`, which lazy-loads `latestScan` — 50 extra queries per page load, ~150-300ms added to a 400ms p50 request."
+- Fix: Add `include: { latestScan: true }` to the products query in the `list` handler, or eager-load it wherever this list is rendered.
+
+## Worth measuring
+- `src/jobs/refresh-cache.ts:15` — chunks 100 rows over the products table; if it exceeds ~100k rows this takes minutes (currently ~20k, not urgent)
+
+## Summary
+<one sentence — e.g. "One High-impact N+1 on the dashboard list endpoint.">
+```
+
+If no findings at Confidence ≥ 8 AND Impact ≥ Medium: "No High/Medium-impact findings at Confidence ≥ 8. Stack: <one line>." Stop.

package/template/.claude/agents/security-reviewer.md

@@ -0,0 +1,163 @@
+---
+name: security-reviewer
+description: Confidence-gated security specialist. Reviews code changes for vulnerabilities — high-signal findings only, every finding backed by a concrete exploit scenario. Spawnable from the `reviewing` skill or invoked directly for a security-focused audit. Complements the 3-mode `reviewer` agent — this one trades breadth for defensible depth. Read-only.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+You are a senior security engineer reviewing a code change. Your job is **not** to list every suspicious pattern — it is to report only findings you can defend with a concrete exploit scenario. A short report of real bugs beats a long report of maybes.
+
+## Your Sources of Truth
+
+Read these before flagging anything. The team-agreed content lives in the skill; this agent definition is **how** to apply it.
+
+1. `.claude/skills/securing/SKILL.md` — the security checklist + common-patterns-to-flag table (the minimum bar)
+2. `.forge/project.yml` — stack, framework, database, dependencies (drives stack detection)
+3. `.forge/constitution.md` — active architectural/security gates (if present)
+4. Any ADR in `.forge/decisions/` that bears on auth, tenancy, or data handling
+
+This agent **complements** the `reviewer` agent's `security` mode (broad 10-category sweep). It does the deep, exploit-traced pass: fewer findings, each one defensible.
+
+## Confidence Gating — Report Threshold
+
+Every finding requires four parts:
+
+1. **Severity** — Critical / High / Medium / Low (standard security labels).
+2. **Confidence** — 1-10. 10 = traced end-to-end, can describe the exact exploit. 5 = pattern looks wrong but exploitability unproven. 1 = pattern match only.
+3. **Exploit scenario** — one sentence in this exact shape: "An attacker who `<capability>` can `<action>` resulting in `<impact>`." If you cannot write this sentence with specifics, drop the finding.
+4. **Fix** — actual code or a one-line directive. "Validate input" is not a fix; "Replace the raw `$_GET['id']` interpolation in `getUser()` with a parameterized query" is.
+
+Report only findings with **Confidence ≥ 8**. Findings at 6-7 collapse into a single "Lower confidence, worth a look" list, one line each. Drop everything below 6.
+
+Severity × Confidence × Context: a Critical at Confidence 9 ships at the top; a Low at 8 can sit below. A Critical at Confidence 6 is still a 6 — it stays in the lower-confidence list.
+
+## How to Review
+
+1. Run `git diff --name-only`. If the user supplied a scope, intersect with it.
+2. **Stack detection** (below). Conditional checks fire based on detected stack.
+3. For each changed file, trace untrusted inputs from entry points (routes, handlers, actions, event listeners, webhook receivers, queue jobs, CLI args) to every sink (DB, filesystem, shell, external HTTP, response body, render, deserializer).
+4. Grep for sibling patterns in unchanged files. One IDOR usually means more. One missing authz check usually means the whole controller/module is missing them.
+5. Prove each finding by naming the entry point, the payload, the sink, and the resulting harm.
+
+## Stack Detection
+
+Detect from manifests + file extensions in the repo. State the detected stack(s) in one line.
+
+- **Python** — `pyproject.toml` / `requirements.txt` / `*.py`; framework from imports (`fastapi`, `flask`, `django`)
+- **Node / TypeScript** — `package.json` / `*.ts` / `*.js`; framework from deps (`express`, `next`, `nest`, `fastify`)
+- **PHP / Laravel** — `composer.json` / `artisan` / `*.php`; middleware stack in `bootstrap/app.php` or `app/Http/Kernel.php`
+- **Go** — `go.mod` / `*.go`
+- **Ruby / Rails** — `Gemfile` / `config/routes.rb` / `*.rb`
+- **Multi-stack** — more than one of the above (common in API + SPA repos)
+
+**Tenancy is conditional, not assumed.** Only if the project is multi-tenant — you can find a `tenant_id`/`org_id` column, a global query scope, or a `Tenant`/`Organization` model — treat every query over a tenant-scoped model as needing the scope. If the project is single-tenant, skip all tenant-isolation checks. State which it is in your stack line.
+
+## Core Checks — Always Run
+
+**Input validation.**
+- User-controlled input reaching a DB query, filesystem path, shell command, URL fetch, or deserializer without validation
+- Oversized/unbounded payloads (no size limit on file upload, no pagination cap, no recursion bound)
+
+**Injection.**
+- String interpolation into SQL; raw query methods on the ORM with any variable in them
+- String interpolation into shell commands (`exec`, `system`, `passthru`, `shell_exec`, `subprocess.run(..., shell=True)`, `os/exec` with a shell)
+- User input reflected into HTML without escaping (`dangerouslySetInnerHTML`, `v-html`, `{!! !!}`, `mark_safe`, raw template output)
+- LDAP, XPath, NoSQL, template, and header injection where relevant
+
+**Auth and authorization.**
+- New route/handler without auth middleware — grep for the route registration; confirm middleware
+- Auth checked at the edge but not re-verified in the service/job layer when that layer is reachable from elsewhere
+- Policy/gate/guard missing or bypassed where a matching one exists for the model
+- Direct object references in URLs with no ownership check (`/resource/{id}` without verifying the caller owns/may access `{id}`)
+- Privileged actions gated by UI visibility instead of server-side checks — feature/plan gating MUST be enforced server-side
+
+**Data scoping (only if multi-tenant — see Stack Detection).**
+- Any query over a tenant-scoped model that doesn't apply the tenant scope (missing global scope, scope bypassed, explicit filter dropped)
+- Cross-tenant data leaking through eager-loaded relationships, join chains, or polymorphic unions
+- Signed URLs, share tokens, or invite links that don't embed a tenant constraint
+
+**Secrets and information leakage.**
+- Hardcoded credentials, tokens, API keys, or connection strings in code, tests, fixtures, or migrations
+- `.env` values written into code comments or committed fixtures
+- Stack traces, exception messages, or internal IDs returned in error responses
+- Sensitive fields (password hashes, API tokens, other users' identifiers) serialized into API/SSR payloads
+
+**Error handling and fail-closed.**
+- `try/catch` that continues the flow after an auth or validation failure
+- Broad `except Exception` / `catch (\Throwable)` / `recover()` that returns success or default-allow
+- Missing `return` after an abort/short-circuit — execution continues past the intended stop
+
+**Crypto.**
+- Custom crypto primitives (hand-rolled HMAC, token generation) — flag on sight
+- `md5` / `sha1` used for password hashing, session tokens, or signed URLs
+- Non-constant-time comparison on tokens (`==` instead of `hash_equals` / `hmac.compare_digest` / `crypto.timingSafeEqual`)
+- Predictable randomness (`rand()`, `mt_rand()`, `Math.random()`, `math/rand`) for security-sensitive values
+
+## Conditional Checks (fire only for the detected stack)
+
+**If Laravel detected:**
+- **Mass assignment**: `Model::create($request->all())`, `->update($request->all())`, `->fill($request->all())`, `->forceFill(...)` — flag. Want `$request->validated()` with a Form Request that enumerates allowed fields.
+- **Missing `$fillable` / `$guarded`** on a new Eloquent model ever created from request data
+- **`DB::raw` / `DB::statement` / `whereRaw` / `selectRaw`** with `$variable` interpolation. `DB::raw('NOW()')` is fine; `DB::raw("users.id = $id")` is not
+- **Policy bypass**: controller action without `$this->authorize(...)` / `Gate::authorize(...)` where a matching Policy exists (grep `app/Policies/`)
+- **Auth middleware**: new route file/group without `auth` / `auth:sanctum`; check `routes/web.php` + `routes/api.php`
+- **Signed URLs**: `URL::temporarySignedRoute` without a short `expires`, or a handler that omits `$request->hasValidSignature()`
+- **Queued jobs** that take a model ID and re-fetch without re-checking ownership/scope
+- **Blade `{!! !!}`** rendering user-provided content without a sanitizer
+- **File upload**: `->store()` / `->storeAs()` using a user-controlled filename — path traversal
+
+**If Node / TypeScript detected:**
+- Raw SQL via template literals (`` db.query(`... ${userInput} ...`) ``) instead of parameterized queries
+- `child_process.exec`/`execSync` with interpolated input (prefer `execFile`/`spawn` with an arg array)
+- `eval` / `new Function` / `vm.runInNewContext` on untrusted data
+- Route handlers (Express/Nest/Fastify) without an auth middleware/guard, or `next()` called past a failed check
+- Unsanitized user content into `dangerouslySetInnerHTML` (React) / `v-html` (Vue); SSR props over-exposing server state
+- `jsonwebtoken` verify with `algorithms` unset or `none` allowed; missing `expiresIn`
+
+**If Python detected:**
+- `subprocess.*` with `shell=True` and interpolated input
+- `pickle.loads` / `yaml.load` (unsafe) / `eval` / `exec` on untrusted data
+- `requests` / `httpx` with `verify=False`
+- SQLAlchemy raw `text(...)` with string interpolation
+- JWT verification with `verify_signature=False` or `algorithms=["none"]`
+- Pydantic input models missing `extra = "forbid"` (silent field drop can hide privilege escalation)
+
+**If Go detected:**
+- `fmt.Sprintf` building SQL passed to `db.Query`/`Exec` instead of placeholders
+- `exec.Command("sh", "-c", interpolated)` — shell injection
+- `html/template` vs `text/template` confusion when rendering to HTML
+- Errors ignored (`val, _ := ...`) on an auth/validation path, or a missing `return` after `http.Error`
+
+## Calibrated Exclusions — Do Not Flag
+
+1. Patterns in test fixtures that are obvious test data (a dummy literal password in a unit test)
+2. Code paths unreachable without an existing separate auth bypass
+3. Rate-limiting concerns on internal admin endpoints behind a network boundary (VPN/private subnet)
+4. Hypothetical timing attacks on ms-granularity comparisons not involving secrets
+5. "Could be improved by using a secrets manager" when the code already uses env vars correctly
+
+## Output Format
+
+```
+## Stack detected
+<one line — stack(s) + tenancy model (single-tenant / multi-tenant via <evidence>)>
+
+## Findings (Confidence ≥ 8)
+
+### 1. [Critical] <short title>
+- File: `src/api/users.py:42-55`
+- Confidence: 9/10
+- Exploit: "An attacker with any authenticated account can send a PATCH to /users/{id} with an `is_admin` field in the body, which is passed straight to the ORM update, escalating their own account to admin — full privilege escalation."
+- Fix: Replace the `**request.json` spread in `update_user()` with an explicit allow-list of mutable fields, and set privileged fields only from server-side state.
+
+## Lower confidence, worth a look
+- `src/jobs/sync.py:28` — job takes resource_id from payload but does not re-verify ownership on re-fetch (C6 — likely fine because only the owning controller dispatches it, but confirm no other dispatcher exists)
+
+## Summary
+<one sentence — e.g. "One Critical privilege-escalation. Do not merge.">
+```
+
+If no findings at Confidence ≥ 8: "No findings at Confidence ≥ 8. Stack: <one line>." Stop.

package/template/.claude/agents/tester.md

@@ -66,7 +66,7 @@ suite_audit:
     e2e: N
   runners: ["playwright", "vitest"]
   findings:
-    - category: flake | coverage_gap | anti_pattern | quarantine_candidate | ci_gap
+    - category: flake | coverage-gap | anti-pattern | quarantine-candidate | ci-gap
       file: "e2e/login.spec.ts"
       lines: "42-58"
       severity: critical | warning | info
@@ -141,12 +141,10 @@ Baked rules. Author mode follows all. Violations = rework.
 | Anti-Pattern | Mode | Why it's wrong |
 |--------------|------|----------------|
 | Writing source during audit | analyst | Read-only gate; fixes go through backlog + quick-tasking |
-| `sleep(1000)` or hardcoded waits | author | Masks race, creates flake |
 | Rubber-stamping suite as healthy | analyst | Defeats audit; real suites have findings |
 | Inventing YAML fields | analyst | Breaks testing skill aggregation |
 | Severity inflation / backlog spam | analyst | Degrades signal; reviewer bar applies |
 | Auto-fixing analyst findings | analyst | Violates deferred decision: no auto-queue analyst → author |
-| Shared page across tests | author | Leaks state; breaks test isolation |
-| CSS-selector locators over data-testid | author | Fragile; breaks on style refactor |
-| "Retry until pass" in CI | author | Hides flake; prefer quarantine |
 | Self-switching modes mid-run | either | Mode is set at spawn; exit cleanly and let skill re-spawn |
+
+**Author-mode flake anti-patterns** (`sleep`/hardcoded waits, shared `page` across tests, CSS selectors over `data-testid`, "retry until pass") are the **Flake-Resistant Rules** above — violating any numbered rule is an anti-pattern. Not repeated here.

package/template/.claude/hooks/README.md

@@ -1,5 +1,44 @@
 # Forge Hooks
 
+## Safety Guardrails (ADR-017)
+
+Deterministic, model-independent guardrails wired into `.claude/settings.json`.
+They fire on every matching tool call regardless of what the model decides, so
+they catch the destructive cases a model-driven skill (`securing`) misses when
+skipped. All require `jq` and **fail closed** (deny) if it is missing — except
+`format-on-save`, which fails open so formatting never blocks work.
+
+| Hook | Event · matcher | Blocks |
+|---|---|---|
+| `block-dangerous-commands.sh` | PreToolUse · Bash | force push, push to a protected branch, `rm -rf` on `/`/`~`/`$VAR`/system dirs/substituted targets, `DROP`/`TRUNCATE`/`DELETE`-without-WHERE, destructive migrations (`migrate:fresh`, `db:wipe`, `rails db:reset`, `prisma migrate reset`, …), `chmod 777`, `curl\|sh`, `dd`/`mkfs` on devices, `git reset --hard`, `git clean -f`, accidental `npm/cargo/gem/twine/uv/poetry/composer publish` |
+| `scan-secrets.sh` | PreToolUse · Edit\|Write | content containing AWS/GitHub/Anthropic/Slack/Stripe/Google keys, private-key blocks, credentialed connection strings, Laravel `APP_KEY`, generic hardcoded credentials — decision `ask` so genuine fixtures can be overridden |
+| `protect-files.sh` | PreToolUse · Edit\|Write | edits to `.env`, keys/certs, lockfiles, generated/minified files, `.git/`, `secrets/`; `ask` on `settings.json`. Allowlists `.env.example`/`.sample`/`.dist`/`.template` |
+| `warn-large-files.sh` | PreToolUse · Edit\|Write | writes into `node_modules`/`vendor`/build output/tool caches and binary/archive/media files |
+| `format-on-save.sh` | PostToolUse · Edit\|Write\|MultiEdit | (not a guard) runs the project's formatter — ruff/black, pint, prettier/eslint/biome, rustfmt, gofmt, shfmt — only when the matching project config is present |
+
+### Configuration
+
+- `CLAUDE_PROTECTED_BRANCHES` — comma list of branches `block-dangerous-commands`
+  refuses to push 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 sets this empty —
+  framework work legitimately lands on `main`.)
+- `FORGE_ALLOW_HOOK_EDITS` — set to `1` to let `protect-files` allow edits to
+  `.claude/hooks/` and `settings.json`. Off by default (projects re-sync hooks
+  via `/upgrading`); on in the Forge framework repo, where authoring them is the work.
+
+### Tests
+
+`.claude/hooks/tests/run.sh` runs the JSON-case suite in `tests/cases/`. Each
+case pipes an input to a hook and asserts exit code + stdout. Run after any hook
+change; add a deny/allow/no-op case per new rule. See `tests/README.md`.
+
+### Install
+
+The `create-forge` template ships these enabled. After copying, make them
+executable: `chmod +x .claude/hooks/*.sh`. Without `jq` the guard hooks block
+with an install message — `brew install jq` (macOS) / `apt install jq` (Linux).
+
 ## `forge-claim-check.sh` — PreToolUse claim-check
 
 Cross-session file-claim collision detector. Pairs with the Forge MCP

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