@entelligentsia/forgecli 0.11.2 → 0.15.0

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

@@ -160,7 +160,18 @@ If `CONFIG_MODE == "fast"`: apply the single-file materialized check
 not materialized, emit the stub-or-missing message and exit 0. Otherwise
 proceed.
 
-Before writing, remove any existing manifest entry for this specific file (handles rename case):
+Before writing, check the file for manual modifications (mirrors the workflows
+and templates pre-write guard — FORGE-BUG-037 / forge#106):
+```sh
+node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/personas/<sub-target>.md
+```
+For exit 1 (modified): warn `△ .forge/personas/<sub-target>.md has been manually
+modified (likely by /forge:enhance). Overwriting will discard your changes.
+Proceed? (yes / no / show diff)`. Collect the answer before proceeding. On
+`no` or `show diff` rejecting overwrite, skip this file and exit cleanly.
+On exit 2 (untracked) or exit 3 (missing): proceed without prompting.
+
+Then remove any existing manifest entry for this specific file (handles rename case):
 ```sh
 node "$FORGE_ROOT/tools/generation-manifest.cjs" remove .forge/personas/<sub-target>.md 2>/dev/null || true
 ```
@@ -198,17 +209,46 @@ steps below apply to that single file.
    node "$FORGE_ROOT/tools/banners.cjs" --badge bloom
    ```
    Then emit: `Generating personas (<N> files in parallel)...` — use `N_materialized` in fast mode, `M_total` in full mode.
-4. **Full mode only**: clear stale entries (skip in fast mode — see step 2):
+4. Check each (enumerated, fast-mode-filtered) file for manual modifications
+   before any clearing or regeneration (mirrors the workflows + templates
+   pre-write guard — FORGE-BUG-037 / forge#106):
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/personas/<role>.md
+   ```
+   For any exit 1 (modified): warn `△ .forge/personas/<role>.md has been manually
+   modified (likely by /forge:enhance). Overwriting will discard your changes.
+   Proceed? (yes / no / show diff)`. Collect answers before proceeding. Files
+   the user declines are removed from the regeneration set for this run. Exit
+   2 (untracked) and exit 3 (missing) require no prompt.
+5. **Full mode only**: clear stale entries (skip in fast mode — see step 2):
    ```sh
    node "$FORGE_ROOT/tools/generation-manifest.cjs" clear-namespace .forge/personas/
    ```
-5. **Spawn the persona subagents in a SINGLE Agent tool message** using
+6. **Spawn the persona subagents in a SINGLE Agent tool message** using
    `$FORGE_ROOT/init/generation/generate-persona.md` as the per-subagent rulebook
    (same fan-out pattern as `/forge:init` Phase 4). Spawn one per filtered
    entry — every entry in fast mode, every meta source in full mode.
-6. Collect results. For each `done:` result → emit `  〇 <filename>.md`.
+7. Collect results. For each `done:` result → emit `  〇 <filename>.md`.
    Retry failures once. Any still failing: surface the id list.
-7. Emit `  〇 personas — <N> files written` (fast mode appends ` (M-N deferred)` when `N < M`).
+8. **Replay user enhancements** (forge#107 / Approach A — layer 3 of the composition
+   contract declared at `manage-versions.cjs:13`). After fresh base-pack content
+   is written, restore any user-enhanced files captured by `/forge:enhance` Phase 2
+   snapshots:
+   ```sh
+   node "$FORGE_ROOT/tools/manage-versions.cjs" replay --target personas
+   ```
+   The tool walks all snapshots in `.forge/structure-versions.json`, finds enhanced
+   elements whose normalized path starts with `personas/`, and copies them from
+   the archive back over the freshly-generated content. Later snapshots win on
+   file collision. Files not captured by any snapshot remain at the fresh
+   base-pack version.
+9. Re-record manifest hashes for the (now restored) files so subsequent
+   `generation-manifest check` calls reflect current on-disk content:
+   ```sh
+   for each <role> in the filtered set:
+     node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/personas/<role>.md
+   ```
+10. Emit `  〇 personas — <N> files written` (fast mode appends ` (M-N deferred)` when `N < M`).
 
 ---
 
@@ -226,7 +266,19 @@ If `CONFIG_MODE == "fast"`: apply the single-file materialized check
 If not materialized, emit the stub-or-missing message and exit 0. Otherwise
 proceed.
 
-Before writing, remove any existing manifest entry for this specific file:
+Before writing, check the file for manual modifications (mirrors the workflows
+and templates pre-write guard — FORGE-BUG-037 / forge#106):
+```sh
+node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/skills/<sub-target>-skills.md
+```
+For exit 1 (modified): warn `△ .forge/skills/<sub-target>-skills.md has been
+manually modified (likely by /forge:enhance). Overwriting will discard your
+changes. Proceed? (yes / no / show diff)`. Collect the answer before
+proceeding. On `no` or `show diff` rejecting overwrite, skip this file and
+exit cleanly. On exit 2 (untracked) or exit 3 (missing): proceed without
+prompting.
+
+Then remove any existing manifest entry for this specific file:
 ```sh
 node "$FORGE_ROOT/tools/generation-manifest.cjs" remove .forge/skills/<sub-target>-skills.md 2>/dev/null || true
 ```
@@ -251,15 +303,38 @@ apply to that single file.
    node "$FORGE_ROOT/tools/banners.cjs" --badge tide
    ```
    Then emit: `Generating skills (<N> files in parallel)...`
-4. **Full mode only**: clear stale entries (skip in fast mode):
+4. Check each (enumerated, fast-mode-filtered) file for manual modifications
+   before any clearing or regeneration (mirrors the workflows + templates
+   pre-write guard — FORGE-BUG-037 / forge#106):
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/skills/<role>-skills.md
+   ```
+   For any exit 1 (modified): warn `△ .forge/skills/<role>-skills.md has been
+   manually modified (likely by /forge:enhance). Overwriting will discard your
+   changes. Proceed? (yes / no / show diff)`. Collect answers before proceeding.
+   Files the user declines are removed from the regeneration set for this run.
+   Exit 2 (untracked) and exit 3 (missing) require no prompt.
+5. **Full mode only**: clear stale entries (skip in fast mode):
    ```sh
    node "$FORGE_ROOT/tools/generation-manifest.cjs" clear-namespace .forge/skills/
    ```
-5. **Spawn the skill subagents in a SINGLE Agent tool message** using
+6. **Spawn the skill subagents in a SINGLE Agent tool message** using
    `$FORGE_ROOT/init/generation/generate-skill.md` as the per-subagent rulebook.
-6. Collect results. Retry failures once. Any still failing: surface the id list.
-7. For each completed file, check manifest (warn on modified), emit `  〇 <filename>.md`.
-   Fast mode appends `〇 skills — <N> files written (M-N deferred)` when `N < M`.
+7. Collect results. Retry failures once. Any still failing: surface the id list.
+8. **Replay user enhancements** (forge#107 / Approach A):
+   ```sh
+   node "$FORGE_ROOT/tools/manage-versions.cjs" replay --target skills
+   ```
+   Walks snapshots; restores any enhanced `skills/<role>-skills.md` files from
+   the archive over the freshly-generated content. Later snapshots win on
+   collision.
+9. Re-record manifest hashes for the (now restored) files:
+   ```sh
+   for each <role> in the filtered set:
+     node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/skills/<role>-skills.md
+   ```
+10. For each completed file, check manifest (warn on modified), emit `  〇 <filename>.md`.
+    Fast mode appends `〇 skills — <N> files written (M-N deferred)` when `N < M`.
 
 ---
 
@@ -341,7 +416,7 @@ write, record hash.
    node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/workflows/{filename}.md
    ```
    For any exit 1 (modified): warn `△ .forge/workflows/{filename}.md has been manually
-   modified. Overwriting will discard your changes. Proceed? (yes / no / show diff)`
+   modified. Overwriting may discard manual edits not captured in any /forge:enhance snapshot. Edits captured by snapshots will be restored automatically via `manage-versions replay` after regeneration. Proceed? (yes / no / show diff)`
    Collect answers before proceeding.
 5. **Full mode only**: clear stale entries (skip in fast mode — clearing
    would drop manifest entries for stubs we are intentionally leaving alone):
@@ -367,8 +442,15 @@ write, record hash.
    Input: $FORGE_ROOT/meta/workflows/meta-orchestrate.md + .forge/workflows/
    Output: .forge/workflows/orchestrate_task.md and .forge/workflows/run_sprint.md
    ```
-9. For each written file: record hash `node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/workflows/{filename}.md`
-10. Emit `  〇 workflows — <N> files written` (full mode: 18; fast mode:
+9. **Replay user enhancements** (forge#107 / Approach A):
+   ```sh
+   node "$FORGE_ROOT/tools/manage-versions.cjs" replay --target workflows
+   ```
+   Walks snapshots; restores enhanced `workflows/<name>.md` files. Later
+   snapshots win on collision.
+10. For each written file: record hash `node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/workflows/{filename}.md`
+    (this runs AFTER replay so the recorded hash reflects the restored content).
+11. Emit `  〇 workflows — <N> files written` (full mode: 18; fast mode:
     `〇 workflows — N of M files regenerated (others remain as stubs)`).
 
 **Do NOT touch:** `.claude/commands/`, `.forge/config.json`, or any knowledge base file.
@@ -464,14 +546,21 @@ Generate the single file (no fan-out needed). Record hash after writing.
 6. **Spawn the template subagents in a SINGLE Agent tool message** using
    `$FORGE_ROOT/init/generation/generate-template.md` as the per-subagent rulebook.
 7. Collect results. Retry failures once. Any still failing: surface the id list.
-8. For each written file: record hash, emit `  〇 <filename>.md`.
-9. Re-record the one-shot init artifact not regenerated from a meta file:
+8. **Replay user enhancements** (forge#107 / Approach A):
    ```sh
-   if [ -f ".forge/templates/CUSTOM_COMMAND_TEMPLATE.md" ]; then
-     node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/templates/CUSTOM_COMMAND_TEMPLATE.md
-   fi
+   node "$FORGE_ROOT/tools/manage-versions.cjs" replay --target templates
    ```
-   Fast-mode footer: emit `〇 templates — <N> files written (M-N deferred)` when `N < M`.
+   Walks snapshots; restores enhanced `templates/<STEM>.md` files. Later
+   snapshots win on collision.
+9. For each written file: record hash, emit `  〇 <filename>.md` (hash reflects
+   post-replay content).
+10. Re-record the one-shot init artifact not regenerated from a meta file:
+    ```sh
+    if [ -f ".forge/templates/CUSTOM_COMMAND_TEMPLATE.md" ]; then
+      node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/templates/CUSTOM_COMMAND_TEMPLATE.md
+    fi
+    ```
+    Fast-mode footer: emit `〇 templates — <N> files written (M-N deferred)` when `N < M`.
 
 ---
 

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

@@ -0,0 +1,378 @@
+#!/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');
+
+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');
+
+// 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';
+}
+const currentDistribution = detectDistribution(pluginRoot);
+
+// --- Multi-plugin scanning ---
+// 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;
+}
+
+// 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
+  }
+}
+
+// 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;
+  }
+}
+
+function getUpdateUrl() {
+  try {
+    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; }
+}
+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: 5000 }, (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(''); });
+}
+
+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`);
+}
+
+// --- 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());
+  });
+}
+}
+
+// Export functions for testing
+module.exports = { scanPluginInstallations, isPluginEnabled, detectDistribution, validateUpdateUrl };