@entelligentsia/forgecli 1.0.25 → 1.0.40

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

@@ -12,7 +12,7 @@ project's generated artifacts.
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Detect install mode:
@@ -442,7 +442,7 @@ install changes the cache path (e.g. `…/cache/forge/forge/0.9.6/` →
 this command is stale.
 
 ```sh
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 If the re-derived `FORGE_ROOT` differs from the original value, print:
@@ -916,7 +916,7 @@ consolidated prompt. **Nothing is written without the user saying yes.**
 ### 5a — Locate tools
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 All tools are invoked directly from the plugin:

package/dist/forge-payload/{.base-pack/commands → commands}/validate.md

@@ -3,14 +3,14 @@ name: validate
 description: Validate that a task implementation satisfies acceptance criteria
 ---
 
-# /{{PREFIX}}:validate
+# /forge:validate
 
 Read the validate workflow and follow it.
 
 ## Locate the Forge plugin
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 ## Execute

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

@@ -41,19 +41,38 @@ const _nodeToolRule = process.env.CLAUDE_PLUGIN_ROOT
   ? `node ${process.env.CLAUDE_PLUGIN_ROOT}/tools/*`
   : 'node ~/.claude/plugins/cache/forge/forge/*/tools/*';
 
+// SECURITY (issue #43 / forge-engineering #42): these patterns auto-approve a
+// Bash command with NO prompt. A non-match falls through to Claude Code's normal
+// permission flow (the human is asked) — it does NOT block. So the rule is:
+// auto-allow ONLY shapes that are unambiguously in-tree Forge workflow steps,
+// and let anything that could read a secret, exfiltrate, or execute foreign code
+// fall through to a prompt. Patterns are anchored to their argument shape, not a
+// bare command prefix, precisely so `cat ~/.ssh/id_rsa`, `cp <secret> /tmp/x`,
+// `gh issue create -R attacker/repo`, `git push https://attacker/…`, and
+// `node /tmp/evil/tools/x.cjs` are NOT auto-approved.
 const BASH_PATTERNS = [
-  // Node tool invocations — covers $FORGE_ROOT/tools/*.cjs and $CLAUDE_PLUGIN_ROOT
+  // Node tool invocations — only when the directory before /tools/ is a trusted
+  // Forge root: $FORGE_ROOT / $CLAUDE_PLUGIN_ROOT, the plugin cache, or a path
+  // ending in /.forge. `node /tmp/evil/tools/x.cjs` does NOT match.
   // (H-5d: rule is dynamically built from CLAUDE_PLUGIN_ROOT when set)
-  { pattern: /^node\s+.*\/tools\/[\w-]+\.(cjs|js)\b/, rule: _nodeToolRule },
+  {
+    pattern:
+      /^node\s+(?:"?\$(?:CLAUDE_PLUGIN_ROOT|FORGE_ROOT)"?|\S*\/\.claude\/plugins\/cache\/forge\/\S*|\S*\/\.forge)\/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/' },
+  // cp only when the destination (last arg) is under .forge/ — copying a secret
+  // out to an arbitrary location is not auto-approved.
+  { pattern: /^cp\s+\S.*\s\.?\/?\.forge\/\S*\s*$/, rule: 'cp */schemas/*.schema.json .forge/schemas/' },
   { pattern: /^ls\s+/, rule: 'ls *' },
-  { pattern: /^cat\s+/, rule: 'cat .forge/*' },
+  // cat only within .forge/ or engineering/ — reading arbitrary files (e.g.
+  // ~/.ssh/id_rsa, /etc/passwd) falls through to a prompt.
+  { pattern: /^cat\s+(?:-\S+\s+)*\.?\/?(?:\.forge|engineering)\//, rule: 'cat .forge/*' },
   { pattern: /^date\s+-u\s+/, rule: 'date -u *' },
   { pattern: /^date\s+/, rule: 'date -u *' },
   { pattern: /^jq\s+/, rule: 'jq *' },
@@ -63,14 +82,18 @@ const BASH_PATTERNS = [
   { 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 *' },
+  // gh issue only against the current repo — a -R/--repo pointing at a foreign
+  // repo (cross-repo exfiltration) is not auto-approved.
+  { pattern: /^gh\s+issue\s+(?!.*(?:\s-R\b|\s--repo\b))/, 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 *' },
+  // git push only to a named remote — pushing to an explicit attacker URL
+  // (http(s)/ssh/git/file) is not auto-approved.
+  { pattern: /^git\s+push\b(?!.*(?:https?:\/\/|git@|ssh:\/\/|file:\/\/))/, 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 *' },

package/dist/forge-payload/hooks/lib/common.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * hooks/lib/common.cjs — Shared primitives for Forge hooks
+ *
+ * Provides four canonical exports used across hook files:
+ *   - resolveForgePaths()       (H-1a) — read .forge/config.json and derive key paths
+ *   - readStdinJson(cb, stdin)  (H-1b) — async stdin → JSON parsing (callback pattern)
+ *   - formatHookOutput(name, p) (H-1c) — build hookSpecificOutput JSON envelope
+ *   - FORGE_COMMAND_PATTERNS    (H-1d) — canonical forge-command RegExp array
+ *
+ * IMPORTANT: This file is intentionally excluded from the forge-cli payload
+ * (build-payload.cjs copies only hooks/*.js, not hooks/lib/). Therefore:
+ *   - Only .cjs hooks (post-init.cjs, post-sprint.cjs) may require this file.
+ *   - .js hooks (triage-error.js, forge-permissions.js) retain inline copies
+ *     of the patterns they need. Those inline copies carry comments pointing
+ *     here as the canonical source. Keep both in sync when patterns change.
+ *
+ * Closes findings: H-1a, H-1b, H-1c, H-1d (FORGE-S25-T08)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// H-1a: resolveForgePaths
+// ---------------------------------------------------------------------------
+
+/**
+ * Read .forge/config.json from the current working directory and derive the
+ * key filesystem paths used by hooks.
+ *
+ * Merged from the two identical implementations in post-init.cjs and
+ * post-sprint.cjs. The post-init version included structureVersionsPath;
+ * this function always returns all fields — callers that don't need a field
+ * simply ignore it.
+ *
+ * @returns {{ forgeDir: string, eventsRoot: string, cacheDir: string,
+ *             forgeRoot: string|null, structureVersionsPath: string } | null}
+ *   Returns null if .forge/config.json is missing or unparseable.
+ */
+function resolveForgePaths() {
+  const cfgPath = path.join(process.cwd(), '.forge', 'config.json');
+  if (!fs.existsSync(cfgPath)) return null;
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch (_) { return null; }
+  const forgeDir = path.dirname(cfgPath);
+  return {
+    forgeDir,
+    eventsRoot: path.join(forgeDir, 'store', 'events'),
+    structureVersionsPath: path.join(forgeDir, 'structure-versions.json'),
+    cacheDir: path.join(forgeDir, 'cache'),
+    forgeRoot: (cfg.paths && cfg.paths.forgeRoot) || null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// H-1b: readStdinJson
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all data from a readable stream (defaulting to process.stdin), parse
+ * as JSON, and invoke the callback with the result.
+ *
+ * Merges the async stdin reading pattern used by triage-error.js and
+ * forge-permissions.js. Note: .js hooks retain inline copies of this
+ * pattern to avoid a module-scope require on hooks/lib/ (forge-cli bundle
+ * gap — see file header). This function is provided for .cjs hook consumers
+ * and for future use when the .js extension is migrated in T14.
+ *
+ * @param {function(object|null): void} callback
+ *   Called with the parsed object, or null if input is empty or malformed.
+ * @param {NodeJS.ReadableStream} [stdin]
+ *   Readable stream to consume. Defaults to process.stdin.
+ */
+function readStdinJson(callback, stdin) {
+  const stream = stdin || process.stdin;
+  if (stream.setEncoding) stream.setEncoding('utf8');
+  let raw = '';
+  stream.on('data', chunk => { raw += chunk; });
+  stream.on('end', () => {
+    if (!raw) { callback(null); return; }
+    try {
+      callback(JSON.parse(raw));
+    } catch (_) {
+      callback(null);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// H-1c: formatHookOutput
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Claude Code hook stdout envelope as a JSON string.
+ *
+ * Claude Code hook protocol: hooks write a JSON object to stdout where the
+ * top-level key is `hookSpecificOutput` containing `hookEventName` plus any
+ * additional fields from payload.
+ *
+ * @param {string} hookEventName - e.g. 'PostToolUse', 'SessionStart'
+ * @param {object} payload - additional fields to include in hookSpecificOutput
+ * @returns {string} JSON string ready for process.stdout.write
+ */
+function formatHookOutput(hookEventName, payload) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName,
+      ...payload,
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// H-1d: FORGE_COMMAND_PATTERNS
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical array of RegExp patterns that identify forge-related commands.
+ *
+ * @catalogSync forge/schemas/enum-catalog.json#commandNames (FORGE-S25-T26)
+ *
+ * Build-time drift detection: forge/tools/__tests__/build-enum-catalog.test.cjs
+ * verifies that every `forge:*` entry in enum-catalog.json commandNames has at
+ * least one matching regex here. Run `node --test forge/tools/__tests__/*.test.cjs`
+ * to check. Drift will cause the drift-detection test to fail.
+ *
+ * Runtime: this array is the single source of truth for forge command recognition.
+ * hooks/triage-error.cjs and hooks/forge-permissions.cjs maintain inline copies
+ * of subsets; those files cannot require() this module due to the forge-cli bundle
+ * gap (build-payload.cjs bundles hooks/*.cjs but excludes hooks/lib/).
+ *
+ * When adding a new forge command: update this array, the inline copies in
+ * triage-error.cjs and forge-permissions.cjs, AND build-enum-catalog.cjs COMMAND_NAMES.
+ */
+const FORGE_COMMAND_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:rebuild/,
+  /forge:update/,
+  /forge:add-pipeline/,
+  /forge:add-task/,
+  /forge:plan/,
+  /forge:implement/,
+  /forge:approve/,
+  /forge:commit/,
+  /forge:review/,
+  /forge:new-sprint/,
+  /forge:plan-sprint/,
+  /forge:run-task/,
+  /forge:run-sprint/,
+  /forge:fix-bug/,
+  /forge:retro/,
+  /forge:check-agent/,
+  /forge:report-bug/,
+  // forge:enhance removed in v1.0 (T03) — absorbed into forge:rebuild --enrich
+  // forge:collate removed from user-facing surface in v1.0 (T03) — internal tool only
+  /forge:validate/,
+  // forge:calibrate removed in v1.0 (T03) — absorbed into forge:health --fix (T04)
+  // forge:materialize removed in v1.0 (T03) — fast-mode eliminated in T01
+  /forge:remove/,
+  /forge:search/,
+  /forge:repair/,
+  /forge:store-custodian/,
+  /forge:config/,
+  /forge:ask/,
+  /forge:refresh-kb-links/,
+  /store-cli\.cjs/,
+  /validate-store\.cjs/,
+];
+
+// ---------------------------------------------------------------------------
+// H-5b: logSwallowedError
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a diagnostic line to the swallowed-error log at
+ * `$dataDir/logs/forge-hooks.log`. If `dataDir` is falsy, falls back to
+ * `os.tmpdir()/forge-plugin-data/logs/forge-hooks.log`.
+ *
+ * Format per line:
+ *   <ISO-timestamp> [<tag>] <err.message>
+ *
+ * Invariants:
+ *   - Append-only. No log rotation. Users can `truncate -s 0` or `rm` the
+ *     file; it will be recreated on the next swallowed error.
+ *   - Hook code NEVER reads this log.
+ *   - Fully fail-open: if the log write itself fails, we exit silently.
+ *
+ * Closes finding: H-5b (FORGE-S25-T15)
+ *
+ * @param {string} tag - Short hook identifier (e.g. 'post-init', 'post-sprint').
+ * @param {Error|*} err - The caught error. Uses err.message if available.
+ * @param {string|null|undefined} dataDir - CLAUDE_PLUGIN_DATA directory.
+ */
+function logSwallowedError(tag, err, dataDir) {
+  try {
+    const baseDir = dataDir || path.join(os.tmpdir(), 'forge-plugin-data');
+    const logsDir = path.join(baseDir, 'logs');
+    fs.mkdirSync(logsDir, { recursive: true });
+    const logPath = path.join(logsDir, 'forge-hooks.log');
+    const msg = (err && err.message) ? err.message : String(err);
+    const line = `${new Date().toISOString()} [${tag}] ${msg}\n`;
+    fs.appendFileSync(logPath, line, 'utf8');
+  } catch (_) {
+    // Fully fail-open — never re-throw
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  resolveForgePaths,
+  readStdinJson,
+  formatHookOutput,
+  FORGE_COMMAND_PATTERNS,
+  logSwallowedError,
+};

package/dist/forge-payload/hooks/lib/plugin-detection.cjs

@@ -0,0 +1,106 @@
+'use strict';
+// hooks/lib/plugin-detection.cjs — extracted from check-update.js (H-2a, FORGE-S25-T14)
+//
+// Provides Forge plugin distribution detection and installation scanning.
+// Extracted to improve testability — each function can be imported and
+// tested independently without requiring the full check-update module.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Distribution detection — derived from plugin path at runtime.
+// The cache path encodes the marketplace name, making this more reliable than
+// reading fields from plugin.json (which may be stale after a switch).
+function detectDistribution(root) {
+  return root.includes('/cache/skillforge/forge/') || root.includes('/marketplaces/skillforge/forge/')
+    ? 'forge@skillforge' : 'forge@forge';
+}
+
+// Check if forge plugin is enabled in settings files.
+// Returns true if no explicit disable found, false if disabled.
+function isPluginEnabled(pluginPath, scope, homeDir, cwd) {
+  try {
+    // Check user settings: ~/.claude/settings.json
+    const userSettingsPath = path.join(homeDir, '.claude', 'settings.json');
+    if (fs.existsSync(userSettingsPath)) {
+      const userSettings = JSON.parse(fs.readFileSync(userSettingsPath, 'utf8'));
+      if (userSettings.disablePlugin === true) return false;
+      // Check for per-plugin disable (if supported in future)
+      if (userSettings.plugins && userSettings.plugins.forge === false) return false;
+    }
+
+    // Check project settings: ./.claude/settings.local.json
+    const projectSettingsPath = path.join(cwd, '.claude', 'settings.local.json');
+    if (fs.existsSync(projectSettingsPath)) {
+      const projectSettings = JSON.parse(fs.readFileSync(projectSettingsPath, 'utf8'));
+      if (projectSettings.disablePlugin === true) return false;
+      if (projectSettings.plugins && projectSettings.plugins.forge === false) return false;
+    }
+
+    return true; // Default: enabled
+  } catch (e) {
+    return true; // Non-fatal — assume enabled if cannot read settings
+  }
+}
+
+// Scans all known plugin locations to detect multiple Forge installations.
+// Returns array of installation records with version, distribution, scope, enabled status.
+// Optional parameters for dependency injection (testing).
+function scanPluginInstallations(options) {
+  const installations = [];
+  const homeDir = (options && options.homeDir) || os.homedir();
+  const cwd = (options && options.cwd) || process.cwd();
+
+  // Candidate paths — user scope (global) and project scope (local)
+  // Also scan skillforge subdirectory variant (skillforge/forge/forge)
+  const basePaths = [
+    path.join(homeDir, '.claude', 'plugins'),
+    path.join(cwd, '.claude', 'plugins'),
+  ];
+  const variants = ['cache', 'marketplaces'];
+  const pluginNames = ['forge/forge', 'skillforge/forge/forge'];
+
+  const candidates = [];
+  for (const basePath of basePaths) {
+    for (const variant of variants) {
+      for (const pluginName of pluginNames) {
+        candidates.push(path.join(basePath, variant, pluginName));
+      }
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const pluginJsonPath = path.join(candidate, '.claude-plugin', 'plugin.json');
+      if (!fs.existsSync(pluginJsonPath)) continue;
+
+      const manifest = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+      // Determine scope: user-scope paths start with homeDir/.claude, project-scope start with cwd/.claude
+      // Use cwd-relative check first to avoid false positives when cwd is subdir of homeDir
+      const isProjectScope = candidate.startsWith(path.join(cwd, '.claude'));
+      const isUserScope = candidate.startsWith(path.join(homeDir, '.claude'));
+      const scope = isProjectScope ? 'project' : (isUserScope ? 'user' : 'unknown');
+      const enabled = isPluginEnabled(candidate, scope, homeDir, cwd);
+
+      // Avoid duplicates — skip if same path already recorded
+      if (installations.some(i => i.path === candidate)) continue;
+
+      installations.push({
+        path: candidate,
+        version: manifest.version || 'unknown',
+        distribution: detectDistribution(candidate),
+        scope: scope,
+        enabled: enabled,
+      });
+    } catch (e) {
+      // Non-fatal — skip broken installations silently
+    }
+  }
+
+  return installations;
+}
+
+module.exports = { detectDistribution, isPluginEnabled, scanPluginInstallations };

package/dist/forge-payload/hooks/lib/update-msg.cjs

@@ -0,0 +1,23 @@
+'use strict';
+// hooks/lib/update-msg.cjs — extracted from check-update.js (H-2c, FORGE-S25-T14)
+//
+// Provides update message construction and emission.
+// Extracted to improve testability — buildUpdateMsg and emit can be tested
+// without executing the full check-update session logic.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+function buildUpdateMsg(remoteVersion, local) {
+  return remoteVersion && remoteVersion !== local
+    ? `Forge ${remoteVersion} available (you have ${local}). Run /forge:update to review changes and update.`
+    : '';
+}
+
+function emit(forgeCtx, updateMsg) {
+  if (!forgeCtx && !updateMsg) return;
+  const combined = [forgeCtx, updateMsg].filter(Boolean).join(' ');
+  const escaped = combined.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
+  process.stdout.write(`{"additionalContext":"${escaped}"}\n`);
+}
+
+module.exports = { buildUpdateMsg, emit };

package/dist/forge-payload/hooks/lib/update-url.cjs

@@ -0,0 +1,46 @@
+'use strict';
+// hooks/lib/update-url.cjs — extracted from check-update.js (H-2b, FORGE-S25-T14)
+//
+// Provides update-check URL resolution and validation.
+// Reads process.env.CLAUDE_PLUGIN_ROOT directly (option b from plan) so
+// the module is self-contained — no pluginRoot argument needed at call sites.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+const fs = require('fs');
+const path = require('path');
+
+// Determine the correct update-check URL for this distribution.
+// Each distribution's plugin.json carries its own updateUrl pointing at the
+// branch it was installed from (main for forge@forge, release for forge@skillforge),
+// so we read it directly — no hardcoded per-distribution URLs needed.
+const FALLBACK_UPDATE_URL = 'https://raw.githubusercontent.com/Entelligentsia/forge/main/forge/.claude-plugin/plugin.json';
+
+const ALLOWED_DOMAINS = ['raw.githubusercontent.com'];
+
+function validateUpdateUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname.toLowerCase();
+    if (!ALLOWED_DOMAINS.some(d => hostname === d || hostname.endsWith('.' + d))) {
+      process.stderr.write(`forge-update: rejected update URL with disallowed domain '${hostname}', falling back\n`);
+      return FALLBACK_UPDATE_URL;
+    }
+    return url;
+  } catch {
+    return FALLBACK_UPDATE_URL;
+  }
+}
+
+// Reads updateUrl from the installed plugin.json.
+// Uses process.env.CLAUDE_PLUGIN_ROOT (option b) with a fallback of '' so
+// the function is self-contained. Falls back to FALLBACK_UPDATE_URL on any error.
+function getUpdateUrl() {
+  try {
+    const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '';
+    const manifest = JSON.parse(fs.readFileSync(path.join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+    return validateUpdateUrl(manifest.updateUrl || FALLBACK_UPDATE_URL);
+  } catch { return FALLBACK_UPDATE_URL; }
+}
+
+module.exports = { FALLBACK_UPDATE_URL, ALLOWED_DOMAINS, validateUpdateUrl, getUpdateUrl };

package/dist/forge-payload/hooks/lib/write-registry.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Write-boundary registry: maps Forge-owned filesystem path patterns to the
+// schema (and kind) that the write-boundary hook enforces on Write/Edit/
+// MultiEdit. FIRST match wins, so order matters — place more specific
+// patterns before their generalizations (sidecar before event).
+//
+// Patterns are anchored to absolute-path suffixes so they match whether the
+// tool invocation used an absolute or project-relative path. Every pattern
+// assumes the Forge store lives at `.forge/store/` (the installed default).
+//
+// If NO pattern matches a write, the hook is a no-op: Forge does not validate
+// non-Forge-owned files. The registry is an allowlist of paths we claim, not
+// a denylist of paths we reject.
+
+const REGISTRY = [
+  // Core store entities — flat files under .forge/store/{kind}s/<id>.json
+  { pattern: /(?:^|\/)\.forge\/store\/features\/[^/]+\.json$/,             schema: 'feature.schema.json',         kind: 'feature' },
+  { pattern: /(?:^|\/)\.forge\/store\/sprints\/[^/]+\.json$/,              schema: 'sprint.schema.json',          kind: 'sprint' },
+  { pattern: /(?:^|\/)\.forge\/store\/tasks\/[^/]+\.json$/,                schema: 'task.schema.json',            kind: 'task' },
+  { pattern: /(?:^|\/)\.forge\/store\/bugs\/[^/]+\.json$/,                 schema: 'bug.schema.json',             kind: 'bug' },
+
+  // Event sidecars — prefixed with `_` and suffixed with `_usage.json`.
+  // Must come BEFORE the general event pattern so the leading `_` file is
+  // classified as a sidecar, not an event with a malformed id.
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/_[^/]+_usage\.json$/, schema: 'event-sidecar.schema.json',   kind: 'event-sidecar' },
+
+  // Canonical events — any other .json under events/<bucket>/ that does NOT
+  // start with an underscore. (Ghost events are not written through Write/Edit
+  // tools, so we don't special-case them here.)
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/[^_/][^/]*\.json$/,   schema: 'event.schema.json',           kind: 'event' },
+
+  // Collation watermark
+  { pattern: /(?:^|\/)\.forge\/store\/COLLATION_STATE\.json$/,             schema: 'collation-state.schema.json', kind: 'collation-state' },
+
+  // Progress log — line-oriented, not JSON. The hook's parser splits newly
+  // appended lines and validates each as a pipe-delimited progress entry.
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/progress\.log$/,      schema: 'progress-entry.schema.json',  kind: 'progress-line', format: 'line-pipe-delimited' },
+];
+
+function matchRegistry(absPath) {
+  if (!absPath || typeof absPath !== 'string') return null;
+  for (const entry of REGISTRY) {
+    if (entry.pattern.test(absPath)) return entry;
+  }
+  return null;
+}
+
+// REGISTRY is intentionally not exported — it is a private implementation detail
+// of this module. Callers use matchRegistry() for lookups. Exporting REGISTRY
+// would expose internal pattern structures to external consumers and create
+// coupling that makes future pattern changes harder. (H-3, FORGE-S25-T14)
+module.exports = { matchRegistry };

package/dist/forge-payload/init/discovery/discover-database.md

@@ -0,0 +1,32 @@
+# Discovery: Database
+
+## Purpose
+
+Detect the project's data model: entities, relationships, field types,
+and migration patterns.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| Django: `models.py` files | ORM models, fields, relationships |
+| Rails: `app/models/*.rb` | ActiveRecord models |
+| Prisma: `schema.prisma` | Prisma schema |
+| TypeORM: `*.entity.ts` | TypeORM entities |
+| Sequelize: `models/*.js` | Sequelize models |
+| Go: `*_model.go` | Go struct definitions |
+| SQL: `migrations/` / `schema.sql` | Raw schema |
+| MongoDB: Mongoose schemas | Document models |
+
+## Tools
+
+Use Grep to find model/entity definitions, Read to parse them.
+
+## Output
+
+Structured report:
+- Entity inventory (name, field count, key relationships)
+- Database type (PostgreSQL, MySQL, MongoDB, SQLite, etc.)
+- ORM/query layer in use
+- Migration framework and directory
+- Seed data presence

package/dist/forge-payload/init/discovery/discover-processes.md

@@ -0,0 +1,31 @@
+# Discovery: Processes
+
+## Purpose
+
+Detect the project's service topology, build tools, and deployment configuration.
+
+## Scan Targets
+
+| File | What It Reveals |
+|------|----------------|
+| `docker-compose.yml` | Service topology, dependencies, ports |
+| `Procfile` | Process types (web, worker, etc.) |
+| `ecosystem.config.js` | PM2 process management |
+| `systemd/*.service` | System service definitions |
+| `.github/workflows/*.yml` | CI/CD pipeline |
+| `.gitlab-ci.yml` | CI/CD pipeline |
+| `Jenkinsfile` | CI/CD pipeline |
+| `vercel.json` / `netlify.toml` | Deployment platform |
+
+## Tools
+
+Use Glob to find these files, Read to parse them.
+
+## Output
+
+Structured report:
+- Services and their roles (web, worker, database, cache, etc.)
+- Build command(s)
+- Deploy command(s) or platform
+- CI/CD pipeline structure
+- Environment variables referenced (names only, not values)

package/dist/forge-payload/init/discovery/discover-routing.md

@@ -0,0 +1,31 @@
+# Discovery: Routing
+
+## Purpose
+
+Detect the project's API surface, authentication strategy, and middleware.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| Django: `urls.py`, `views.py` | URL patterns, view functions/classes |
+| Express: `router.get/post/...` | Route definitions |
+| Rails: `routes.rb` | Route definitions |
+| FastAPI: `@app.get/post` | Endpoint decorators |
+| Go: `http.HandleFunc` / mux | Route handlers |
+| Auth decorators/middleware | `@login_required`, `authenticate`, `IsAuthenticated` |
+| API docs: `openapi.yaml` / `swagger.json` | API specification |
+
+## Tools
+
+Use Grep to find route definitions and auth patterns, Read to parse them.
+
+## Output
+
+Structured report:
+- Route count (approximate)
+- Auth strategy (decorator-based, middleware, JWT, session, etc.)
+- Public vs protected route ratio
+- URL namespace structure
+- API versioning (if any)
+- Middleware chain