forge-orkes 0.42.0 → 0.44.0

package/template/.claude/hooks/tests/cases/scan-secrets.cases.json

@@ -0,0 +1,218 @@
+[
+  {
+    "name": "flags AWS access key ID on Write",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "AWS_KEY = 'AKIAIOSFODNN7EXAMPLE'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "\"permissionDecision\":\"ask\""
+  },
+  {
+    "name": "flags AWS secret access key assignment",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "aws_secret_access_key = \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\""
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "AWS secret key"
+  },
+  {
+    "name": "flags GitHub personal access token",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "GH_TOKEN = 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "GitHub token"
+  },
+  {
+    "name": "flags Anthropic API key",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "ANTHROPIC_API_KEY = 'sk-ant-abcdefghijklmnopqrstuv'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Anthropic API key"
+  },
+  {
+    "name": "flags Slack bot token",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "SLACK_TOKEN = 'xoxb-1234567890-abcdefghijk'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Slack token"
+  },
+  {
+    "name": "flags a private key block",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "secrets/key.pem",
+        "content": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "private key block"
+  },
+  {
+    "name": "flags Postgres connection string with embedded credentials",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env.example",
+        "content": "DATABASE_URL=postgres://admin:s3cretP@ss@db.example.com:5432/app"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "connection string with credentials"
+  },
+  {
+    "name": "flags Laravel APP_KEY with real base64 value",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env",
+        "content": "APP_KEY=base64:IAm40CharsOfBase64EncodedAppKeyForLaravelApp="
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Laravel APP_KEY"
+  },
+  {
+    "name": "flags hardcoded password assignment with literal value",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "app/Services/MailService.php",
+        "content": "$password = \"realPassword123\";"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "hardcoded credential"
+  },
+  {
+    "name": "flags secret found inside an Edit new_string",
+    "input": {
+      "tool_name": "Edit",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "old_string": "TOKEN = ''",
+        "new_string": "TOKEN = 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "GitHub token"
+  },
+  {
+    "name": "allows password field that references process.env",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/db.js",
+        "content": "const password = process.env.DB_PASSWORD;"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows password field that uses Laravel env() helper",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "config/database.php",
+        "content": "'password' => env('DB_PASSWORD', ''),"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows password mentioned only in a comment",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "app/Services/MailService.php",
+        "content": "// Remember to set the MAIL_PASSWORD in .env\n$mailer = new Mailer();"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows empty content",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/empty.py",
+        "content": ""
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "ignores non-Write/Edit tools",
+    "input": {
+      "tool_name": "Bash",
+      "tool_input": {
+        "command": "echo ghp_abcdefghijklmnopqrstuvwxyz0123456789"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows an APP_KEY placeholder shorter than 40 chars",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env.example",
+        "content": "APP_KEY=base64:TODO_RUN_ARTISAN_KEY_GENERATE"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows a regular Python file with no secrets",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/utils.py",
+        "content": "def add(a: int, b: int) -> int:\n    return a + b\n"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "flags a Google API key",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "config.js",
+        "content": "const key = \"AIzaSyD-1234567890abcdefGHIJKLMNOPqrstuv\""
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Google API key"
+  }
+]

package/template/.claude/hooks/tests/cases/warn-large-files.cases.json

@@ -0,0 +1,146 @@
+[
+  {
+    "name": "denies writing into node_modules",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "node_modules/react/index.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "node_modules"
+  },
+  {
+    "name": "denies writing into nested node_modules",
+    "input": { "tool_name": "Edit", "tool_input": { "file_path": "apps/web/node_modules/foo/index.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "node_modules"
+  },
+  {
+    "name": "denies writing into dist",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "dist/bundle.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "build output"
+  },
+  {
+    "name": "denies writing into build",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "build/app.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "build output"
+  },
+  {
+    "name": "denies writing into vendor",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "vendor/laravel/framework/src/foo.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "vendor"
+  },
+  {
+    "name": "denies writing into storage/framework",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "storage/framework/views/cached.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "framework caches"
+  },
+  {
+    "name": "denies writing into bootstrap/cache",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "bootstrap/cache/config.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "framework caches"
+  },
+  {
+    "name": "denies writing into storage/logs",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "storage/logs/laravel.log" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "runtime logs"
+  },
+  {
+    "name": "denies writing into __pycache__",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/__pycache__/module.cpython-311.pyc" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "__pycache__"
+  },
+  {
+    "name": "denies writing into .venv",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".venv/lib/python3.11/site-packages/foo.py" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "virtual environment"
+  },
+  {
+    "name": "denies writing into .pytest_cache",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".pytest_cache/v/cache/lastfailed" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Python tool caches"
+  },
+  {
+    "name": "denies writing into coverage",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "coverage/lcov.info" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "coverage"
+  },
+  {
+    "name": "denies writing a .DS_Store",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".DS_Store" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": ".DS_Store"
+  },
+  {
+    "name": "denies writing a .so binary",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "lib/native.so" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "binary files"
+  },
+  {
+    "name": "denies writing a .exe",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "bin/tool.exe" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "binary files"
+  },
+  {
+    "name": "denies writing a .zip archive",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "release/bundle.zip" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "archive"
+  },
+  {
+    "name": "denies writing a .phar",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "tools/composer.phar" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "archive"
+  },
+  {
+    "name": "denies writing an mp4",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "assets/intro.mp4" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "media files"
+  },
+  {
+    "name": "denies writing a .pyc",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/module.pyc" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "bytecode"
+  },
+  {
+    "name": "allows writing a regular Python file",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/domains/service.py" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a regular PHP file",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/Cerebro/Domains/Services/DomainService.php" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a Vue file in resources",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "resources/js/pages/domains/Index.vue" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a .gitignore",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".gitignore" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "no-op when file_path is missing",
+    "input": { "tool_name": "Bash", "tool_input": { "command": "ls" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  }
+]

package/template/.claude/hooks/tests/run.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Runs all hook test cases and reports pass/fail.
+#
+# Usage:
+#   .claude/hooks/tests/run.sh              # run all hooks
+#   .claude/hooks/tests/run.sh protect-files  # run one hook
+#
+# Case files live in .claude/hooks/tests/cases/<hook>.cases.json.
+# Each case is an object with: name, input, expect_exit, expect_stdout_contains,
+# expect_stdout_not_contains. See README.md for the full schema.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOKS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+CASES_DIR="$SCRIPT_DIR/cases"
+
+# Hermetic run: cases assert default behavior, so neutralise the env knobs that
+# a maintainer's session may set (Forge's own dev repo exports both). Without
+# this, FORGE_ALLOW_HOOK_EDITS=1 lifts protect-files' hook/settings guards and an
+# empty CLAUDE_PROTECTED_BRANCHES disables the push checks — turning real cases red.
+unset FORGE_ALLOW_HOOK_EDITS
+unset CLAUDE_PROTECTED_BRANCHES
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'jq is required to run hook tests. Install with: brew install jq (macOS) or apt install jq (Linux).\n' >&2
+  exit 1
+fi
+
+# Optional single-hook filter.
+FILTER="${1:-}"
+
+PASSED=0
+FAILED=0
+SKIPPED=0
+FAILURES=()
+
+run_case() {
+  local hook_script="$1" case_json="$2"
+  local name input expect_exit expect_contains expect_not_contains
+  name=$(printf '%s' "$case_json" | jq -r '.name')
+  input=$(printf '%s' "$case_json" | jq -c '.input')
+  expect_exit=$(printf '%s' "$case_json" | jq -r '.expect_exit // 0')
+  expect_contains=$(printf '%s' "$case_json" | jq -r '.expect_stdout_contains // ""')
+  expect_not_contains=$(printf '%s' "$case_json" | jq -r '.expect_stdout_not_contains // ""')
+
+  local output rc
+  output=$(printf '%s' "$input" | "$hook_script" 2>&1)
+  rc=$?
+
+  local reasons=()
+  if [ "$rc" -ne "$expect_exit" ]; then
+    reasons+=("exit $rc, expected $expect_exit")
+  fi
+  if [ -n "$expect_contains" ] && ! printf '%s' "$output" | grep -qF -- "$expect_contains"; then
+    reasons+=("stdout missing: $expect_contains")
+  fi
+  if [ -n "$expect_not_contains" ] && printf '%s' "$output" | grep -qF -- "$expect_not_contains"; then
+    reasons+=("stdout should not contain: $expect_not_contains")
+  fi
+
+  if [ "${#reasons[@]}" -eq 0 ]; then
+    printf '  [PASS] %s\n' "$name"
+    PASSED=$((PASSED + 1))
+  else
+    printf '  [FAIL] %s\n' "$name"
+    for reason in "${reasons[@]}"; do
+      printf '         %s\n' "$reason"
+    done
+    if [ -n "$output" ]; then
+      printf '         output: %s\n' "$output" | head -3
+    fi
+    FAILED=$((FAILED + 1))
+    FAILURES+=("$name")
+  fi
+}
+
+for case_file in "$CASES_DIR"/*.cases.json; do
+  [ -f "$case_file" ] || continue
+
+  hook_name=$(basename "$case_file" .cases.json)
+
+  if [ -n "$FILTER" ] && [ "$hook_name" != "$FILTER" ]; then
+    continue
+  fi
+
+  hook_script="$HOOKS_DIR/$hook_name.sh"
+
+  if [ ! -f "$hook_script" ]; then
+    printf '[SKIP] %s — hook script not found at %s\n' "$hook_name" "$hook_script"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [ ! -x "$hook_script" ]; then
+    printf '[SKIP] %s — hook script not executable (run: chmod +x %s)\n' "$hook_name" "$hook_script"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  printf '\n%s\n' "$hook_name"
+
+  count=$(jq -r 'length' "$case_file")
+  for i in $(seq 0 $((count - 1))); do
+    case_json=$(jq -c ".[$i]" "$case_file")
+    run_case "$hook_script" "$case_json"
+  done
+done
+
+printf '\n---\n%d passed, %d failed, %d skipped\n' "$PASSED" "$FAILED" "$SKIPPED"
+
+if [ "$FAILED" -gt 0 ]; then
+  printf '\nFailed cases:\n'
+  for f in "${FAILURES[@]}"; do
+    printf '  - %s\n' "$f"
+  done
+  exit 1
+fi

package/template/.claude/hooks/warn-large-files.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks writes to build artifacts, binaries, and
+# dependency directories. PreToolUse hook for Edit|Write. Exit 2 = block.
+
+set -uo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"jq is required for file protection hooks but is not installed.\"}}"
+  exit 2
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Dependency, build, and cache directories across common stacks.
+REASON=""
+case "$FILE_PATH" in
+  # Node / JS / TS
+  node_modules/*|*/node_modules/*)
+    REASON="Cannot write into node_modules/ — install dependencies via the package manager instead." ;;
+  dist/*|*/dist/*|build/*|*/build/*|.next/*|*/.next/*|.nuxt/*|*/.nuxt/*|.output/*|*/.output/*)
+    REASON="Cannot write into build output directories — these are generated by the build process." ;;
+  # PHP / Laravel
+  vendor/*|*/vendor/*)
+    REASON="Cannot write into vendor/ — use composer instead." ;;
+  storage/framework/*|*/storage/framework/*|bootstrap/cache/*|*/bootstrap/cache/*)
+    REASON="Cannot write into Laravel framework caches — these are rebuilt by artisan." ;;
+  storage/logs/*|*/storage/logs/*)
+    REASON="Cannot write into storage/logs/ — these are runtime logs." ;;
+  # Python
+  __pycache__/*|*/__pycache__/*)
+    REASON="Cannot write into __pycache__/ — these are generated by Python." ;;
+  .venv/*|*/.venv/*|venv/*|*/venv/*)
+    REASON="Cannot write into virtual environment directories." ;;
+  .pytest_cache/*|*/.pytest_cache/*|.ruff_cache/*|*/.ruff_cache/*|.mypy_cache/*|*/.mypy_cache/*|.tox/*|*/.tox/*)
+    REASON="Cannot write into Python tool caches (pytest/ruff/mypy/tox) — these are regenerated automatically." ;;
+  # Go / Rust
+  target/debug/*|*/target/debug/*|target/release/*|*/target/release/*)
+    REASON="Cannot write into Rust target/ build output." ;;
+  # Generic
+  coverage/*|*/coverage/*|htmlcov/*|*/htmlcov/*|.nyc_output/*|*/.nyc_output/*)
+    REASON="Cannot write into coverage reports — these are regenerated by the test runner." ;;
+  .DS_Store|*/.DS_Store)
+    REASON="Cannot write .DS_Store — macOS metadata files should not be committed." ;;
+esac
+
+if [ -n "$REASON" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+# Block binary and archive file extensions.
+BASENAME=$(basename "$FILE_PATH")
+case "$BASENAME" in
+  *.wasm|*.so|*.dylib|*.dll|*.exe|*.o|*.a)
+    REASON="Cannot write binary files — these should be compiled, not hand-written." ;;
+  *.zip|*.tar|*.tar.gz|*.tar.bz2|*.tgz|*.rar|*.7z|*.phar)
+    REASON="Cannot write archive/bundle files." ;;
+  *.mp4|*.mov|*.avi|*.mkv|*.mp3|*.wav|*.flac)
+    REASON="Cannot write media files — add these manually outside the agent." ;;
+  *.pyc|*.pyo|*.class)
+    REASON="Cannot write compiled bytecode files." ;;
+esac
+
+if [ -n "$REASON" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+exit 0

package/template/.claude/rules/README.md

@@ -0,0 +1,63 @@
+# Rules
+
+Rules are short, ambient reminders that load passively based on which files are being edited. They are the lightweight counterpart to skills — cheap, file-path-triggered convention reminders that cost no context until you touch the relevant code. See [ADR-018](../../docs/decisions/ADR-018-lightweight-policy-layer.md).
+
+## The three weight tiers
+
+Forge governs agent behaviour at three different weights. Rules fill the gap between the always-loaded heavy constitution and the opt-in heavy skills.
+
+| Tier | Where | Weight | Loads when |
+|---|---|---|---|
+| **Constitution** | `.forge/constitution.md` | Heavy, project-wide hard rules | Always loaded — architectural **gates** that must pass |
+| **Rules** | `.claude/rules/` | Lightweight ambient guidance | Always-on (no frontmatter) **or** path-scoped (auto-attaches only when editing matching files) |
+| **Skills** | `.claude/skills/` | Heavy, full checklists/decision trees | Opt-in — loaded when a task description matches the skill |
+
+- **Constitution** = the non-negotiable architectural gates that gate shipping. Heavy, always paid, project-specific.
+- **Rules** = "don't add a phantom dependency", "re-read conventions on long sessions" — one-line bullets that fire ambiently. Path-scoped rules cost **zero context** until you touch a file matching their glob.
+- **Skills** = "how we run a security review" (50–200 lines, invoked deliberately by task description).
+
+The gap rules fill: the constitution is too heavy and too project-architectural for everyday convention reminders, and skills are opt-in so they miss ambient failure modes. Rules are the cheap, file-path-triggered middle layer.
+
+Think of it this way:
+
+- Constitution = "every API route enforces tenant isolation" (a gate, always checked)
+- Skill = "how we run a security review" (50–200 lines, invoked deliberately)
+- Rule = "don't call an API before grepping that it exists" (1-line bullet, fires ambiently)
+
+If a rule grows past 25 lines, it is a skill in disguise. Split it or promote it.
+
+## File format
+
+Every rule is a markdown file. Two modes:
+
+**Always-on:** no frontmatter. Claude Code loads rules without a `paths:` field unconditionally (same priority as `.claude/CLAUDE.md`). Use for universal discipline (agent behaviour).
+
+**Path-scoped:** YAML frontmatter with a `paths:` array of globs.
+```yaml
+---
+paths:
+  - "src/**/*.ts"
+  - "app/**/Http/**"
+---
+```
+Loaded only when Claude is reading or editing a file whose path matches any glob. Use for stack-specific or layer-specific guidance.
+
+Do not use `alwaysApply: true`. That is Cursor syntax; Claude Code ignores it. Absence of `paths:` is the always-on signal.
+
+## Stack-specific rules ship opt-in
+
+Forge core is **stack-agnostic**, so core ships only the always-on `agent-discipline.md`. Stack-specific path-scoped rules (Laravel, Vue, Python, etc.) live in the opt-in convention packs under `experimental/conventions/` — install them when your project's stack matches, and they auto-attach via their `paths:` globs. Keeping them out of core is what keeps core portable across any stack.
+
+## Current rules
+
+| File | Scope | Topic |
+|---|---|---|
+| `agent-discipline.md` | always | Scope creep, phantom deps, hallucinated APIs, silent assumptions |
+
+## Authoring rules
+
+- Keep each rule under ~20 lines of actual guidance.
+- Lead with the imperative ("Never use ...", "Always declare ..."), not justification.
+- No code blocks unless the exact syntax is the point.
+- One file per concern. Do not bundle unrelated rules into a single file just because they share a path.
+- If a rule needs a long explanation, it belongs in a skill. Rules state the rule; skills teach it. Past 25 lines, it's a skill in disguise.

package/template/.claude/rules/agent-discipline.md

@@ -0,0 +1,14 @@
+# Agent Discipline
+
+Always-on rule. These are the failure modes AI agents fall into most often. They apply to every session, regardless of stack. This restates the everyday floor; the executor's Deviation Rules (Rule 4 — STOP and ask before a new DB table, service layer, or library swap) in `.claude/agents/executor.md` are the hard stops.
+
+- **Scope creep.** Do not modify files outside the stated scope. If a change requires touching something adjacent, ask first.
+- **No phantom dependencies.** Do not add packages (`npm install`, `pip install`, `composer require`, `uv add`, etc.) without explicit approval. Name the package and version you need and wait. (A library swap is a Rule 4 stop.)
+- **No over-engineering.** No abstractions, patterns, factories, registries, or base classes unless the plan calls for them. One concrete implementation does not need an interface.
+- **No happy-path-only code.** Handle the unhappy paths the plan named. If the plan didn't name them, list what could go wrong before coding.
+- **No hallucinated APIs.** Before calling a function or method, verify it exists with grep or by reading the source. If unsure, say so.
+- **No silent assumptions.** Surface every non-obvious decision: "I assumed X because Y — confirm or redirect."
+- **No "while I was here" extras.** No added logging, metrics, renames, or cleanup unless the task requires them.
+- **Ask when unclear.** One good clarifying question beats an hour of wrong work.
+- **Re-read conventions when the session gets long.** Style drifts over multi-hour sessions. The constitution and the relevant skill are the source of truth.
+- **Test what you wrote.** Don't declare done without running the specific test or equivalent verification for the changed behaviour.