@entelligentsia/forgecli 1.0.25 → 1.0.36

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

@@ -13,7 +13,7 @@ AI software development lifecycle for the codebase in the current working direct
 Set `$FORGE_ROOT` to the plugin root provided by Claude Code:
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 `$FORGE_ROOT` is the directory containing `meta/`, `init/`, `hooks/`, and `commands/`.
@@ -136,13 +136,68 @@ Any other input (including 0, 5+, or non-numeric text) re-prompts with the same
 If a `$ARGUMENTS` phase number is provided (e.g. `3`), skip the pre-flight
 table and go straight to the specified phase.
 
-Read `$FORGE_ROOT/init/sdlc-init.md` — that document is your complete orchestration.
-Follow it exactly. It defines 4 phases:
+Before dispatching, gather the following values interactively:
 
-1. **Collect** — 5 parallel discovery prompts, KB folder prompt, `config.json`
-2. **Discover** — KB doc fan-out + inline `project-context.json` construction
-3. **Materialize** — `substitute-placeholders.cjs` + `build-overlay.cjs` smoke test
-4. **Register** — tools, versioning, manifest, cache, store seed, Tomoshibi, `.gitignore` update (unconditional), CLAUDE.md KB-link offer
+**KB Folder Prompt:**
+
+```
+What should your engineering knowledge base folder be named?
+  Default: engineering
+
+KB folder name [engineering]: ___
+```
+
+If the user provides a custom name, write it:
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" set paths.engineering "{name}"
+```
+Set `kbFolder` to the chosen name (default: `"engineering"`).
+
+**CLAUDE.md Offer:**
+
+```sh
+ls CLAUDE.md AGENTS.md CLAUDE.local.md .cursorrules 2>/dev/null
+```
+
+If NONE of those files exist, ask:
+```
+No CLAUDE.md / AGENTS.md found. Create a minimal CLAUDE.md with Forge KB links? [Y/n]: ___
+```
+Set `createClaudeMd = true` (default Y) or `false`.
+If any file exists, set `createClaudeMd = false` (skip silently).
+
+**Timestamp:** `isoTimestamp = new Date().toISOString()`
+
+Execute the workflow:
+
+```
+workflow('wfl:init', {
+  forgeRoot: FORGE_ROOT,
+  kbFolder,
+  startPhase,
+  createClaudeMd,
+  isoTimestamp,
+  rawArguments: $ARGUMENTS
+})
+```
+
+If the Workflow tool is unavailable, halt immediately with the following message:
+
+> The Workflow tool is required to run `/forge:init`. This Claude Code build does not
+> support the Workflow tool. Upgrade Claude Code and try again.
+>
+> (Alternatively, run `4ge init claude .` again to re-scaffold, then upgrade Claude Code.)
+
+Do NOT fall back to reading `sdlc-init.md` or any other document — Iron Law 5.
+
+**Post-workflow:** on `result.ok === true`, render closing banners (use `banners.cjs forge`
+and `--subtitle "灯 SDLC ready…"`), emit the welcome block, present the marketplace-skills
+offer from `result.skillMatches` (install accepted skills via `manage-config.cjs set
+installedSkills.{id} true`), invoke `forge:refresh-kb-links` via the Skill tool, and
+print the final report (KB doc count, workflow count, command count, accepted/skipped skills).
+
+On `result.ok === false`: surface `result.failure` as formatted JSON and offer
+`/forge:report-bug`.
 
 The current working directory is the target project. All generated artifacts go into
 `.forge/`, the configured KB folder (default: `engineering/`), and `.claude/commands/`

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

@@ -10,7 +10,7 @@ Re-run generation phases using the current state of the project. Use `--enrich`
 ## Locate the Forge plugin
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Read `.forge/config.json`. If it does not exist, stop and tell the user to run
@@ -18,7 +18,7 @@ Read `.forge/config.json`. If it does not exist, stop and tell the user to run
 
 Resolve tools from the plugin:
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 All tool invocations in this command use `node "$FORGE_ROOT/tools/<tool>.cjs"`.
@@ -709,7 +709,7 @@ When `$ARGUMENTS` contains `--enrich`, run the enhancement workflow instead of r
 This is the v1.0 replacement for the removed `/forge:enhance` command.
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 1. Check that `$FORGE_ROOT/meta/workflows/meta-enhance.md` exists. If absent:

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

@@ -21,7 +21,7 @@ nothing is deleted until you confirm explicitly.
 Read the configured KB path and project prefix from config:
 
 ```sh
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 KB_PATH: !`node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}"`
 PREFIX: !`node -e "try{console.log(require('./.forge/config.json').project.prefix.toLowerCase())}catch{console.log('')}"`
 ```

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

@@ -19,7 +19,7 @@ $ARGUMENTS
 
 1. Resolve the plugin root:
    ```
-   FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+   FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
    ```
 
 2. Run the four-phase repair workflow below. If `--dry-run` is in `$ARGUMENTS`,

package/dist/forge-payload/commands/report-bug.md

@@ -30,7 +30,7 @@ gh is not installed or not authenticated.
 Collect the following in parallel:
 
 ```
-forge_version:  !`cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/'`
+forge_version:  !`cat "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/'`
 node_version:   !`node --version 2>/dev/null || echo "N/A"`
 os_info:        !`uname -srm 2>/dev/null || echo "N/A"`
 forge_config:   !`cat ".forge/config.json" 2>/dev/null | head -30 || echo "No .forge/config.json found"`

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

@@ -12,7 +12,7 @@ Quick overview of the current sprint and task state.
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 ## Locate project config

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/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