@entelligentsia/forgecli 0.15.0 → 0.20.0

package/dist/forge-payload/.schemas/task.schema.json

@@ -30,29 +30,14 @@
       "type": "object",
       "description": "Terse structured summaries of phase artifacts. Optional; full artifacts on disk remain authoritative.",
       "properties": {
-        "plan":           { "$ref": "#/$defs/phaseSummary" },
-        "review_plan":    { "$ref": "#/$defs/phaseSummary" },
-        "implementation": { "$ref": "#/$defs/phaseSummary" },
-        "code_review":    { "$ref": "#/$defs/phaseSummary" },
-        "validation":     { "$ref": "#/$defs/phaseSummary" }
+        "plan":           { "$ref": "_defs/phaseSummary.schema.json" },
+        "review_plan":    { "$ref": "_defs/phaseSummary.schema.json" },
+        "implementation": { "$ref": "_defs/phaseSummary.schema.json" },
+        "code_review":    { "$ref": "_defs/phaseSummary.schema.json" },
+        "validation":     { "$ref": "_defs/phaseSummary.schema.json" }
       },
       "additionalProperties": false
     }
   },
-  "additionalProperties": false,
-  "$defs": {
-    "phaseSummary": {
-      "type": "object",
-      "required": ["objective", "written_at"],
-      "properties": {
-        "objective":   { "type": "string", "maxLength": 280 },
-        "key_changes": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 12 },
-        "findings":    { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 12 },
-        "verdict":     { "type": "string", "enum": ["approved", "revision", "n/a"] },
-        "written_at":  { "type": "string", "format": "date-time" },
-        "artifact_ref":{ "type": "string", "description": "Relative path to the full artifact" }
-      },
-      "additionalProperties": false
-    }
-  }
+  "additionalProperties": false
 }

package/dist/forge-payload/.schemas/transitions/bug.json

@@ -0,0 +1,31 @@
+[
+  {
+    "from": "reported",
+    "to": [
+      "triaged",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "triaged",
+    "to": [
+      "in-progress",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "in-progress",
+    "to": [
+      "fixed",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "fixed",
+    "to": []
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/.schemas/transitions/sprint.json

@@ -0,0 +1,46 @@
+[
+  {
+    "from": "planning",
+    "to": [
+      "active",
+      "blocked",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "active",
+    "to": [
+      "completed",
+      "partially-completed",
+      "blocked",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "completed",
+    "to": [
+      "retrospective-done"
+    ]
+  },
+  {
+    "from": "partially-completed",
+    "to": [
+      "retrospective-done"
+    ]
+  },
+  {
+    "from": "retrospective-done",
+    "to": []
+  },
+  {
+    "from": "blocked",
+    "to": [
+      "active",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/.schemas/transitions/task.json

@@ -0,0 +1,109 @@
+[
+  {
+    "from": "draft",
+    "to": [
+      "planned",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "planned",
+    "to": [
+      "plan-approved",
+      "plan-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "plan-approved",
+    "to": [
+      "implementing",
+      "plan-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "implementing",
+    "to": [
+      "implemented",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "implemented",
+    "to": [
+      "review-approved",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "review-approved",
+    "to": [
+      "approved",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "approved",
+    "to": [
+      "committed",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "plan-revision-required",
+    "to": [
+      "planned",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "code-revision-required",
+    "to": [
+      "implementing",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "committed",
+    "to": []
+  },
+  {
+    "from": "blocked",
+    "to": []
+  },
+  {
+    "from": "escalated",
+    "to": []
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/commands/health.md

@@ -54,10 +54,10 @@ cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/..."
 
 1. **Config-completeness check** — Read `$PROJECT_ROOT/.forge/config.json`.
    If it does not exist, stop and tell the user to run `/forge:init` in that directory first.
-   If it exists, validate it against `$FORGE_ROOT/sdlc-config.schema.json`:
+   If it exists, validate it against `$FORGE_ROOT/schemas/config.schema.json`:
    - Read the schema and extract all `required` fields at each level (top-level and nested objects).
-   - Required top-level fields: `version`, `project`, `stack`, `commands`, `paths`.
-   - Nested required fields: `project.prefix`, `project.name`, `commands.test`, `paths.engineering`, `paths.store`, `paths.workflows`, `paths.commands`, `paths.templates`.
+   - Required top-level fields per `config.schema.json`: `version`, `project`, `paths`.
+   - Nested required fields: `project.prefix`, `project.name`, `paths.engineering`, `paths.store`, `paths.forgeRoot`. Additionally enforce as completeness invariants (warn-if-missing, not schema-required): `commands.test`, `paths.workflows`, `paths.commands`, `paths.templates`.
    - For each required field, verify it exists in the config and has a non-empty value.
    - If all required fields are present and non-empty, emit:
      > 〇 Config complete — all required fields present.

package/dist/forge-payload/hooks/check-update.cjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// Forge session-start hook — runs on SessionStart
+// 1. Injects Forge-awareness context if this project has a .forge/ directory.
+// 2. Checks once per day whether a newer version is available.
+// 3. Detects distribution switches (forge@forge ↔ forge@skillforge) and
+//    refreshes paths.forgeRoot in .forge/config.json so subagents always
+//    reference the correct installed plugin path.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+// Works on Linux, macOS, and Windows wherever Claude Code runs.
+
+'use strict';
+
+// This hook must never exit non-zero — a hook failure surfaces as noise to the
+// user and blocks session start context. Any uncaught exception exits 0.
+process.on('uncaughtException', () => process.exit(0));
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+
+// Extracted lib modules (H-2a, H-2b, H-2c — FORGE-S25-T14)
+const { detectDistribution, scanPluginInstallations, isPluginEnabled } = require('./lib/plugin-detection.cjs');
+const { FALLBACK_UPDATE_URL, ALLOWED_DOMAINS, validateUpdateUrl, getUpdateUrl } = require('./lib/update-url.cjs');
+const { buildUpdateMsg, emit } = require('./lib/update-msg.cjs');
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '.';
+const dataDir = process.env.CLAUDE_PLUGIN_DATA || path.join(os.tmpdir(), 'forge-plugin-data');
+// Plugin-level cache: throttle only (lastCheck, remoteVersion) — shared across all projects.
+const pluginCacheFile = path.join(dataDir, 'update-check-cache.json');
+// Project-level cache: migration state (migratedFrom, localVersion, distribution, forgeRoot) — per project.
+const forgeDir = '.forge';
+const hasForge = fs.existsSync(forgeDir) && fs.existsSync(path.join(forgeDir, 'config.json'));
+const projectCacheFile = path.join(forgeDir, 'update-check-cache.json');
+
+const currentDistribution = detectDistribution(pluginRoot);
+
+const remoteUrl = getUpdateUrl();
+const checkInterval = 86400; // 24 hours in seconds
+
+fs.mkdirSync(dataDir, { recursive: true });
+
+// --- Forge-awareness context injection ---
+let forgeContext = '';
+if (fs.existsSync('.forge') && fs.existsSync(path.join('.forge', 'config.json'))) {
+  forgeContext =
+    'This project uses Forge AI-SDLC. Engineering knowledge base: engineering/. ' +
+    'Generated workflows: .forge/workflows/. Sprint and task store: .forge/store/. ' +
+    'Use the project slash commands (/plan, /implement, /sprint-plan) to drive development. ' +
+    'Run /forge:health to check knowledge base currency.';
+}
+
+// --- Update check helpers ---
+function localVersion() {
+  try {
+    const p = path.join(pluginRoot, '.claude-plugin', 'plugin.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function fetchRemoteVersion(cb) {
+  https.get(remoteUrl, { timeout: 2000 }, (res) => {
+    let body = '';
+    res.on('data', chunk => { body += chunk; });
+    res.on('end', () => {
+      try { cb(JSON.parse(body).version || ''); } catch { cb(''); }
+    });
+  }).on('error', () => cb(''))
+    .on('timeout', function() { this.destroy(); cb(''); });
+}
+
+// --- Main logic (only runs when executed as script, not when required as module) ---
+if (require.main === module) {
+  const local = localVersion();
+  const now = Math.floor(Date.now() / 1000);
+
+  // Scan for all plugin installations — builds inventory for multi-plugin awareness.
+  const allInstallations = scanPluginInstallations();
+
+// Plugin-level cache: throttle (lastCheck, remoteVersion) — shared, not migration state.
+let pluginCache = null;
+if (fs.existsSync(pluginCacheFile)) {
+  try { pluginCache = JSON.parse(fs.readFileSync(pluginCacheFile, 'utf8')); } catch { pluginCache = null; }
+}
+
+// Project-level cache: migration state — per project.
+let projectCache = null;
+if (hasForge && fs.existsSync(projectCacheFile)) {
+  try { projectCache = JSON.parse(fs.readFileSync(projectCacheFile, 'utf8')); } catch { projectCache = null; }
+}
+
+// FR-010: Backfill forgeRef from localVersion if missing in existing cache.
+if (projectCache && !projectCache.forgeRef && projectCache.localVersion) {
+  projectCache.forgeRef = projectCache.localVersion;
+}
+
+// --- Distribution + forgeRoot/forgeRef sync (always runs before update-check logic) ---
+// Refreshes paths.forgeRoot and paths.forgeRef in config.json and the distribution/
+// forgeRoot/forgeRef fields in the project cache. Handles distribution switches
+// transparently — the user gets a clear message and all path references are
+// corrected before any command runs.
+let distributionSwitchMsg = '';
+if (hasForge && pluginRoot !== '.') {
+  // Keep paths.forgeRoot and paths.forgeRef in .forge/config.json in sync.
+  // Generated workflows read forgeRoot to invoke tools without needing CLAUDE_PLUGIN_ROOT.
+  // forgeRef is the version-based portable field (FR-010).
+  try {
+    const configPath = path.join(forgeDir, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!cfg.paths) cfg.paths = {};
+    let configChanged = false;
+    if (cfg.paths.forgeRoot !== pluginRoot) {
+      cfg.paths.forgeRoot = pluginRoot;
+      configChanged = true;
+    }
+    // FR-010: Write forgeRef from the local plugin version.
+    if (!cfg.paths.forgeRef || cfg.paths.forgeRef !== local) {
+      cfg.paths.forgeRef = local;
+      configChanged = true;
+    }
+    if (configChanged) {
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+    }
+  } catch { /* non-fatal */ }
+
+  if (projectCache) {
+    const storedRoot = projectCache.forgeRoot;
+    const storedDist = projectCache.distribution;
+    const switched = storedRoot && storedRoot !== pluginRoot;
+
+    // Build distribution switch message when the active plugin path changed and
+    // the distribution name is different (e.g. forge@skillforge → forge@forge).
+    if (switched && storedDist && storedDist !== currentDistribution) {
+      const versionNote = projectCache.localVersion && projectCache.localVersion !== local
+        ? ` Version: ${projectCache.localVersion} → ${local}.`
+        : '';
+      distributionSwitchMsg =
+        `Plugin distribution switched from ${storedDist} to ${currentDistribution}.${versionNote}` +
+        ` paths.forgeRoot updated. Run /forge:update to verify migration state.`;
+    }
+
+    // Sync distribution + forgeRoot + forgeRef into the project cache whenever they drift.
+    // FR-002: Preserve updateStatus, pendingReason, pendingMigrations if present.
+    if (storedRoot !== pluginRoot || storedDist !== currentDistribution) {
+      try {
+        const updated = { ...projectCache, distribution: currentDistribution, forgeRoot: pluginRoot, forgeRef: local };
+        fs.writeFileSync(projectCacheFile, JSON.stringify(updated, null, 2) + '\n');
+        projectCache = updated; // keep in-memory copy consistent
+      } catch { /* non-fatal */ }
+    }
+  }
+}
+
+// FR-002: Surface pending-state message to the user if update is incomplete.
+let pendingStateMsg = '';
+if (hasForge && projectCache && projectCache.updateStatus === 'pending') {
+  const pendingMigrations = Array.isArray(projectCache.pendingMigrations)
+    ? projectCache.pendingMigrations.join(', ')
+    : '(unknown)';
+  pendingStateMsg =
+    `Forge update is incomplete — pending migration(s): ${pendingMigrations}.` +
+    ` Run /forge:update to continue or /forge:migrate to complete.`;
+}
+
+const elapsed = pluginCache ? now - (pluginCache.lastCheck || 0) : Infinity;
+
+// Build multi-plugin awareness message if multiple installations found.
+let multiPluginMsg = '';
+if (allInstallations.length >= 2) {
+  const activeInst = allInstallations.find(i => i.path === pluginRoot) || allInstallations[0];
+  const otherInsts = allInstallations.filter(i => i.path !== activeInst.path);
+  if (otherInsts.length > 0) {
+    const otherDesc = otherInsts.map(i => `${i.version} (${i.distribution}, ${i.scope})`).join(', ');
+    multiPluginMsg = `Also installed: ${otherDesc}. `;
+  }
+}
+
+if (elapsed < checkInterval) {
+  // Plugin cache still fresh — use stored remote version.
+  // Detect post-install: if the project's recorded localVersion differs from
+  // the running plugin version, the plugin was updated since last migration.
+  let postInstallMsg = '';
+  if (hasForge && projectCache && projectCache.localVersion && projectCache.localVersion !== local) {
+    // Record the pre-install version as baseline, update localVersion.
+    // FR-010: Include forgeRef. FR-002: updateStatus/pendingReason/pendingMigrations
+    // are preserved via spread.
+    const updated = {
+      ...projectCache,
+      migratedFrom: projectCache.localVersion,
+      localVersion: local,
+      distribution: currentDistribution,
+      forgeRoot: pluginRoot,
+      forgeRef: local,
+    };
+    try { fs.writeFileSync(projectCacheFile, JSON.stringify(updated, null, 2) + '\n'); } catch { /* non-fatal */ }
+    // Reset plugin cache lastCheck so we fetch a fresh remote version next session.
+    try { fs.writeFileSync(pluginCacheFile, JSON.stringify({ ...pluginCache, lastCheck: 0 }, null, 2) + '\n'); } catch { /* non-fatal */ }
+    // Suppress post-install message when a distribution switch message already covers the event.
+    if (!distributionSwitchMsg) {
+      postInstallMsg = `Forge was updated to ${local} (was ${projectCache.localVersion}). Run /forge:update to review changes and update.`;
+    }
+  }
+  const baseMsg = distributionSwitchMsg || postInstallMsg || buildUpdateMsg((pluginCache && pluginCache.remoteVersion) || '', local);
+  // FR-002: Append pending-state message if present.
+  const updateMsg = baseMsg ? multiPluginMsg + baseMsg : baseMsg;
+  const pendingMsg = pendingStateMsg ? ' ' + pendingStateMsg : '';
+  emit(forgeContext, (updateMsg + pendingMsg).trim());
+} else {
+  // Plugin cache expired or missing — fetch fresh remote version.
+  fetchRemoteVersion((remoteVersion) => {
+    if (remoteVersion) {
+      // Update plugin-level throttle cache.
+      try { fs.writeFileSync(pluginCacheFile, JSON.stringify({ lastCheck: now, remoteVersion }, null, 2) + '\n'); } catch { /* non-fatal */ }
+      // Seed project-level cache on first run if not yet present.
+      // FR-010: Include forgeRef alongside forgeRoot.
+      if (hasForge && !projectCache) {
+        try {
+          fs.writeFileSync(projectCacheFile, JSON.stringify({
+            migratedFrom: local, localVersion: local,
+            distribution: currentDistribution, forgeRoot: pluginRoot,
+            forgeRef: local,
+            updateStatus: 'complete', pendingReason: null, pendingMigrations: [],
+          }, null, 2) + '\n');
+        } catch { /* non-fatal */ }
+      } else if (hasForge && projectCache && !projectCache.localVersion) {
+        // Backfill localVersion (and distribution/forgeRoot/forgeRef) if missing.
+        // FR-002: Preserve updateStatus/pendingReason/pendingMigrations via spread.
+        try {
+          fs.writeFileSync(projectCacheFile, JSON.stringify({
+            ...projectCache, localVersion: local,
+            distribution: currentDistribution, forgeRoot: pluginRoot,
+            forgeRef: local,
+          }, null, 2) + '\n');
+        } catch { /* non-fatal */ }
+      }
+    }
+    const baseMsg = distributionSwitchMsg || buildUpdateMsg(remoteVersion, local);
+    // FR-002: Append pending-state message if present.
+    const updateMsg = baseMsg ? multiPluginMsg + baseMsg : baseMsg;
+    const pendingMsg = pendingStateMsg ? ' ' + pendingStateMsg : '';
+    emit(forgeContext, (updateMsg + pendingMsg).trim());
+  });
+}
+}
+
+// Re-export from lib modules for backward compatibility with existing tests
+// that import these functions from check-update directly.
+// Canonical sources: hooks/lib/plugin-detection.cjs and hooks/lib/update-url.cjs
+module.exports = {
+  ...require('./lib/plugin-detection.cjs'),  // detectDistribution, scanPluginInstallations, isPluginEnabled
+  ...require('./lib/update-url.cjs'),         // validateUpdateUrl, getUpdateUrl, FALLBACK_UPDATE_URL, ALLOWED_DOMAINS
+};

package/dist/forge-payload/hooks/forge-permissions.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Forge permission auto-approver — runs on PermissionRequest events.
+//
+// Purpose: eliminate the permission prompt storm (BUG-014) by auto-approving
+// known Forge tool patterns and persisting allow rules to localSettings.
+//
+// Protocol (Claude Code PermissionRequest hook):
+//   - stdin: JSON envelope { tool_name, tool_input, permission_suggestions }
+//   - stdout: { hookSpecificOutput: { hookEventName, decision: { behavior,
+//     updatedPermissions } } } to allow and persist rules
+//   - exit 0 with no output: let normal permission flow proceed
+//   - exit 2 with stderr: block the tool call
+//
+// Security model:
+//   - This hook can only ALLOW, never DENY
+//   - User deny rules always take precedence over hook allows
+//   - Rules persist to .claude/settings.local.json (gitignored, per-project)
+//   - Users can inspect/remove rules via /permissions
+
+'use strict';
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge-permissions: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+// ── Pattern registry ──────────────────────────────────────────────
+// Each entry: { pattern: RegExp, rule: string }
+// pattern matches against the tool input string (Bash command, file path, or URL)
+// rule is the allow rule content to persist via updatedPermissions
+//
+// Forge-command patterns within BASH_PATTERNS overlap with FORGE_COMMAND_PATTERNS.
+// Canonical source for forge command recognition: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS
+// (H-1d, FORGE-S25-T08). This file intentionally does NOT require hooks/lib/common.cjs
+// because build-payload.cjs bundles hooks/*.cjs but excludes hooks/lib/ (forge-cli bundle gap).
+// When adding a new forge command, update BOTH this list AND hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
+
+// H-5d: Interpolate CLAUDE_PLUGIN_ROOT into node-tool rule when the env var is set.
+// Falls back to the hardcoded glob when CLAUDE_PLUGIN_ROOT is not available.
+const _nodeToolRule = process.env.CLAUDE_PLUGIN_ROOT
+  ? `node ${process.env.CLAUDE_PLUGIN_ROOT}/tools/*`
+  : 'node ~/.claude/plugins/cache/forge/forge/*/tools/*';
+
+const BASH_PATTERNS = [
+  // Node tool invocations — covers $FORGE_ROOT/tools/*.cjs and $CLAUDE_PLUGIN_ROOT
+  // (H-5d: rule is dynamically built from CLAUDE_PLUGIN_ROOT when set)
+  { pattern: /^node\s+.*\/tools\/[\w-]+\.(cjs|js)\b/, rule: _nodeToolRule },
+  // NOTE: node -e and node -p removed — arbitrary code execution must not be auto-approved.
+  // Forge workflows use node .../tools/*.cjs for tool invocations; inline node -e/p requires
+  // explicit user approval each time.
+  // Shell commands used by Forge workflows
+  { pattern: /^mkdir\s+-p\s+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^mkdir\s+-p\s+\S+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^cp\s+/, rule: 'cp */schemas/*.schema.json .forge/schemas/' },
+  { pattern: /^ls\s+/, rule: 'ls *' },
+  { pattern: /^cat\s+/, rule: 'cat .forge/*' },
+  { pattern: /^date\s+-u\s+/, rule: 'date -u *' },
+  { pattern: /^date\s+/, rule: 'date -u *' },
+  { pattern: /^jq\s+/, rule: 'jq *' },
+  { pattern: /^touch\s+/, rule: 'touch .forge/*' },
+  { pattern: /^uname\s+/, rule: 'uname *' },
+  { pattern: /^rm\s+\.forge/, rule: 'rm .forge/*' },
+  { pattern: /^rm\s+-rf\s+\.forge/, rule: 'rm -rf .forge/*' },
+  { pattern: /^rmdir\s+/, rule: 'rmdir .forge/*' },
+  { pattern: /^gh\s+auth\s+/, rule: 'gh auth status *' },
+  { pattern: /^gh\s+issue\s+/, rule: 'gh issue create *' },
+  // git read-only commands (already auto-approved by Claude Code, but belt-and-suspenders)
+  { pattern: /^git\s+status\b/, rule: 'git status *' },
+  { pattern: /^git\s+log\b/, rule: 'git log *' },
+  { pattern: /^git\s+diff\b/, rule: 'git diff *' },
+  { pattern: /^git\s+add\s+/, rule: 'git add *' },
+  { pattern: /^git\s+commit\s+-m\s+/, rule: 'git commit -m *' },
+  { pattern: /^git\s+push\b/, rule: 'git push *' },
+  { pattern: /^git\s+checkout\s+/, rule: 'git checkout *' },
+  { pattern: /^git\s+branch\s+/, rule: 'git branch *' },
+  { pattern: /^git\s+stash\b/, rule: 'git stash *' },
+  { pattern: /^git\s+worktree\s+/, rule: 'git worktree *' },
+];
+
+const WRITE_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+  { pattern: /^\.gitignore$/, rule: '.gitignore' },
+];
+
+const EDIT_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+];
+
+const WEBFETCH_PATTERNS = [
+  { pattern: /^https:\/\/raw\.githubusercontent\.com\/Entelligentsia\/forge\//, rule: 'domain:raw.githubusercontent.com' },
+];
+
+const PATTERN_MAP = {
+  Bash: BASH_PATTERNS,
+  Write: WRITE_PATTERNS,
+  Edit: EDIT_PATTERNS,
+  MultiEdit: EDIT_PATTERNS,
+  WebFetch: WEBFETCH_PATTERNS,
+};
+
+// ── Core logic ─────────────────────────────────────────────────────
+
+function matchTool(toolName, toolInput) {
+  const patterns = PATTERN_MAP[toolName];
+  if (!patterns) return null;
+
+  const input = toolName === 'Bash' ? (toolInput.command || '')
+    : (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') ? (toolInput.file_path || '')
+    : toolName === 'WebFetch' ? (toolInput.url || '')
+    : '';
+
+  for (const { pattern, rule } of patterns) {
+    if (pattern.test(input)) return rule;
+  }
+  return null;
+}
+
+// ── Export for testing ─────────────────────────────────────────────
+module.exports = { matchTool, BASH_PATTERNS, WRITE_PATTERNS, EDIT_PATTERNS, WEBFETCH_PATTERNS };
+
+// ── Main (hook runner) ────────────────────────────────────────────
+if (require.main === module) {
+let input = '';
+process.stdin.on('data', (d) => { input += d; });
+process.stdin.on('end', () => {
+  let event;
+  try {
+    event = JSON.parse(input);
+  } catch (_) {
+    // Unparseable input — fail open, let normal permission flow handle it
+    process.exit(0);
+  }
+
+  const { tool_name, tool_input } = event;
+  if (!tool_name || !tool_input) {
+    process.exit(0);
+  }
+
+  const matchedRule = matchTool(tool_name, tool_input || {});
+  if (matchedRule) {
+    // Persist only the matched rule — never bulk-approve all rules at once.
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: {
+          behavior: 'allow',
+          updatedPermissions: [{
+            type: 'addRules',
+            rules: [{ toolName: tool_name, ruleContent: matchedRule }],
+            behavior: 'allow',
+            destination: 'localSettings',
+          }],
+        },
+      },
+    };
+    process.stdout.write(JSON.stringify(response));
+    process.exit(0);
+  }
+
+  // Not a Forge pattern — exit 0 with no output to let normal permission flow proceed
+  process.exit(0);
+});
+} // end require.main === module

package/dist/forge-payload/hooks/forge-permissions.js

@@ -28,6 +28,12 @@ process.on('uncaughtException', (err) => {
 // Each entry: { pattern: RegExp, rule: string }
 // pattern matches against the tool input string (Bash command, file path, or URL)
 // rule is the allow rule content to persist via updatedPermissions
+//
+// Forge-command patterns within BASH_PATTERNS overlap with FORGE_COMMAND_PATTERNS.
+// Canonical source for forge command recognition: hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS
+// (H-1d, FORGE-S25-T08). This file intentionally does NOT require hooks/lib/common.cjs
+// because build-payload.cjs bundles hooks/*.js but excludes hooks/lib/ (forge-cli bundle gap).
+// When adding a new forge command, update BOTH this list AND hooks/lib/common.cjs:FORGE_COMMAND_PATTERNS.
 
 const BASH_PATTERNS = [
   // Node tool invocations — covers $FORGE_ROOT/tools/*.cjs and $CLAUDE_PLUGIN_ROOT