forgedock 1.2.0 → 1.3.0

package/bin/forgedock.mjs

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 import { fileURLToPath } from "url";
-import { dirname, join, relative, resolve } from "path";
+import { dirname, join, relative, resolve, sep } from "path";
 import { mkdir, lstat, readlink, readdir, unlink, readFile, writeFile } from "fs/promises";
 import {
   existsSync,
@@ -13,7 +13,7 @@ import {
   renameSync,
   unlinkSync,
 } from "fs";
-import { execSync, execFileSync } from "child_process";
+import { execSync, execFileSync, spawnSync } from "child_process";
 import { homedir } from "os";
 import https from "https";
 import {
@@ -1475,6 +1475,216 @@ async function printVersionAvailableChangelog(localVersion, latestVersion) {
   }
 }
 
+/**
+ * Detect whether FORGE_HOME resolves inside npm's global install tree, i.e.
+ * this process is running as a globally-installed `forgedock` package (not
+ * an ephemeral npx/dlx cache extraction). Used by update()'s npm-mode branch
+ * (forge#2133) to decide whether a newer published version can be installed
+ * in place with `npm install -g forgedock@latest`, versus the npx-cache case
+ * where there is nothing durable to reinstall over.
+ *
+ * Resolution: `npm root -g` reports the global node_modules directory; if
+ * FORGE_HOME sits under `{globalRoot}/forgedock`, this is a global install.
+ * Fails closed (returns false) on any error — the pre-existing advisory-only
+ * behavior is always a safe fallback when detection is inconclusive.
+ *
+ * @returns {boolean}
+ */
+function isGlobalNpmInstall() {
+  try {
+    const globalRoot = execSync("npm root -g", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+    if (!globalRoot) return false;
+    const globalPkgDir = resolve(join(globalRoot, "forgedock"));
+    const home = resolve(FORGE_HOME);
+    return home === globalPkgDir || home.startsWith(globalPkgDir + sep);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Maximum number of additional self-update re-exec attempts allowed after the
+ * first (i.e. up to MAX_SELF_UPDATE_ATTEMPTS + 1 total `npm install -g`
+ * attempts across the parent process and its re-exec'd children). Guards
+ * against unbounded recursion when `npm install -g` reports success but the
+ * resolved version never actually advances (stale registry mirror/proxy,
+ * cache issue, mismatched FORGE_HOME resolution) — see forge#2158.
+ */
+const MAX_SELF_UPDATE_ATTEMPTS = 1;
+
+/**
+ * Strict semver-shape check for a version string before it is interpolated
+ * into a shell-invoked command (see forge#2180). Intentionally narrow —
+ * digits-dot-digits-dot-digits with an optional `-prerelease`/`+build`
+ * suffix restricted to `[0-9A-Za-z.-]` — so it accepts every real value
+ * `fetchLatestVersion()` can return from the npm registry's `version` field,
+ * while rejecting anything containing shell metacharacters
+ * (`; | & $ \` ( ) < > " ' \n` etc.) that `shell: true` would otherwise
+ * hand straight to cmd.exe/`/bin/sh`.
+ *
+ * The regex above is fully anchored (`^...$`) but its quantifiers (`\d+`,
+ * `[0-9A-Za-z.-]+`) are unbounded, so shape validity alone does not bound
+ * string *length* — a pathologically long value could still match. This
+ * is defense-in-depth only (see forge#2195): the character-class
+ * restriction already rules out shell metacharacters at any length, and
+ * `fetchLatestVersion()`'s 65536-byte HTTP response cap already bounds
+ * `version` in practice. The explicit length cap below rejects oversized
+ * input before the regex ever runs, closing the gap outright rather than
+ * relying on an upstream cap this function has no visibility into.
+ *
+ * @param {string} version
+ * @returns {boolean}
+ */
+function isValidSemverShape(version) {
+  const MAX_VERSION_LENGTH = 100;
+  return (
+    typeof version === "string" &&
+    version.length <= MAX_VERSION_LENGTH &&
+    /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+  );
+}
+
+/**
+ * Install the newer published version globally via `npm install -g
+ * forgedock@{version}`, then re-exec this same file path (which npm has just
+ * overwritten with the new package's contents) so the rest of update()'s
+ * persist/relink phase runs against the *new* payload instead of the stale
+ * in-memory one (forge#2133 — previously the advisory-only branch would
+ * persist/relink from whatever was already resolved, silently downgrading
+ * a newer persisted ~/.forge/ or leaving the global install stuck on the
+ * old version indefinitely).
+ *
+ * Depth guard (forge#2158): the re-exec'd child process could, in principle,
+ * observe the same "newer version available" condition again (e.g. a stale
+ * registry mirror/proxy reports success without the resolved version ever
+ * advancing) and recurse indefinitely, each cycle blocking up to ~125s. The
+ * attempt count is propagated across the re-exec via the
+ * `FORGEDOCK_SELF_UPDATE_ATTEMPT` environment variable (parent process env is
+ * never mutated — the counter is only passed to the spawned child's own
+ * environment). Once `MAX_SELF_UPDATE_ATTEMPTS` is reached, this function
+ * fails loudly with an actionable message and returns `false` instead of
+ * attempting another install/re-exec cycle.
+ *
+ * Fail-open: any error during install or re-exec falls back to the
+ * pre-existing advisory message — the caller must treat a `false` return as
+ * "could not self-update, printed manual instructions instead."
+ *
+ * Windows note (forge#2180): `npm` is a `.cmd` batch launcher on Windows, and
+ * Node's `execFileSync`/`spawnSync` cannot invoke `.cmd`/`.bat` files without
+ * `shell: true` (nodejs/node#3675) — confirmed empirically on a real Windows
+ * 11 machine: `execFileSync("npm", [...])` ENOENTs, and even the exact
+ * `npm.cmd` filename EINVALs, without a shell. `shell: true` is required
+ * here so the install actually runs on Windows. Because that widens the
+ * command line to shell interpretation, `version` — sourced from an
+ * unauthenticated `https://registry.npmjs.org` response in
+ * `fetchLatestVersion()` — is validated against a strict semver shape
+ * (`isValidSemverShape`) before it is ever interpolated into the command,
+ * closing the injection surface `shell: true` would otherwise open (see the
+ * repo-wide execSync→execFileSync shell-injection hardening precedent in
+ * forge#1703/forge#413).
+ *
+ * @param {string} version - target version to install (e.g. "1.2.0")
+ * @returns {boolean} true if re-exec was launched (process will exit before
+ *   returning in the success path); false if self-update failed, was capped
+ *   by the depth guard, and the caller should fall back to advisory-only
+ *   behavior.
+ */
+function selfUpdateGlobalInstall(version) {
+  // Math.max(0, ...) clamps out negative values: `Number.parseInt(x, 10) || 0`
+  // only substitutes 0 for NaN/0/"" — a negative numeric string (e.g. a
+  // corrupted or manually-set FORGEDOCK_SELF_UPDATE_ATTEMPT="-1") is truthy
+  // and passes through unclamped, which would let a negative attempt count
+  // stay perpetually below MAX_SELF_UPDATE_ATTEMPTS. Defense-in-depth only —
+  // no known path sets this env var to a negative value today. (forge#2168)
+  const attempt = Math.max(
+    0,
+    Number.parseInt(process.env.FORGEDOCK_SELF_UPDATE_ATTEMPT, 10) || 0,
+  );
+
+  // `attempt` counts completed installs so far (0 = no installs yet). The
+  // guard must allow MAX_SELF_UPDATE_ATTEMPTS + 1 total installs (see the
+  // doc comment above this function) — i.e. it should only trip once
+  // `attempt` has already reached that total, not one call early. Using
+  // `>=` here tripped after only 1 install instead of the documented 2
+  // (forge#2203 — the retry this guard exists to allow never actually ran).
+  if (attempt > MAX_SELF_UPDATE_ATTEMPTS) {
+    console.log(
+      `  ${YELLOW}Self-update did not converge after ${attempt} attempt(s) — the installed version may not be advancing (stale registry mirror/cache?).${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  // Validate before this value ever reaches the shell-invoked install below
+  // (forge#2180) — fail open to the same advisory message a failed install
+  // would print, rather than throwing or passing an unvalidated string to
+  // `shell: true`.
+  if (!isValidSemverShape(version)) {
+    console.log(
+      `  ${YELLOW}Self-update aborted: received an unexpected version string ("${version}").${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  try {
+    console.log(`  Installing ${CYAN}forgedock@${version}${RESET} globally...`);
+    // shell: true is required to resolve npm.cmd on Windows (see the
+    // Windows note in this function's doc comment, forge#2180). `version`
+    // is validated as strict semver above before this point.
+    execFileSync("npm", ["install", "-g", `forgedock@${version}`], {
+      stdio: "inherit",
+      timeout: 120000,
+      shell: true,
+    });
+  } catch (err) {
+    console.log(
+      `  ${YELLOW}Global self-update failed: ${err && err.message ? err.message : String(err)}${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  console.log(
+    `  ${GREEN}Installed v${version}.${RESET} Re-running update to finish persist/relink...`,
+  );
+  try {
+    const result = spawnSync(process.execPath, [__filename, "update"], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        FORGEDOCK_SELF_UPDATE_ATTEMPT: String(attempt + 1),
+      },
+    });
+    // `result.signal` is set (non-null) when the re-exec'd child was
+    // terminated by a signal (e.g. SIGTERM/SIGKILL) rather than exiting
+    // cleanly — in that case `result.status` is `null`, and
+    // `result.status ?? 0` would silently collapse a killed child into a
+    // reported "success" (exit 0). Exit non-zero explicitly for the
+    // signal-killed case; the non-signaled path is unchanged. (forge#2159)
+    process.exit(result.signal ? 1 : (result.status ?? 0));
+    // Unreachable — process.exit() above terminates the process. Present
+    // only to satisfy linters expecting a return on every path.
+    return true;
+  } catch (err) {
+    console.log(
+      `  ${YELLOW}Could not re-run update after install: ${err && err.message ? err.message : String(err)}${RESET}`,
+    );
+    console.log(`  Run ${CYAN}npx forgedock update${RESET} again manually.`);
+    return false;
+  }
+}
+
 async function update() {
   console.log("");
   console.log(`${BOLD}ForgeDock${RESET} — Checking for updates`);
@@ -1569,8 +1779,25 @@ async function update() {
       console.log(
         `  ${GREEN}New version available: v${latestVersion}${RESET} (you have v${localVersion}).`,
       );
-      console.log(`  Run ${CYAN}npx forgedock@latest${RESET} to fetch it.`);
       await printVersionAvailableChangelog(localVersion, latestVersion);
+
+      // forge#2133 — a global npm install can actually be upgraded in place;
+      // do that instead of only printing an advisory (which previously left
+      // global installs stuck on whatever version was first installed,
+      // since every subsequent `npx forgedock update` re-resolves the same
+      // stale global binary). selfUpdateGlobalInstall() re-execs and exits
+      // the process on success, so anything after this block only runs when
+      // self-update wasn't attempted or failed.
+      if (isGlobalNpmInstall()) {
+        selfUpdateGlobalInstall(latestVersion);
+        // selfUpdateGlobalInstall() only returns (rather than exiting the
+        // process) when the install or re-exec failed — it already printed
+        // manual-recovery instructions, so fall through to the persist
+        // refresh below using the still-stale local payload (fail-open,
+        // matches pre-existing behavior for this failure case).
+      } else {
+        console.log(`  Run ${CYAN}npx forgedock@latest${RESET} to fetch it.`);
+      }
     } else {
       console.log(`  Already up to date (v${localVersion}).`);
     }
@@ -3238,7 +3465,11 @@ switch (command) {
   case "run-issue": {
     const { runFromCli } = await import("./engine-cli.mjs");
     try {
-      await runFromCli(restArgs);
+      const result = await runFromCli(restArgs);
+      // forge#2175: make a needs-human escalation distinguishable from a
+      // successful run by exit code, mirroring the resume-stalled case's
+      // existing convention below (result.failed.length > 0 -> exitCode 1).
+      if (result && result.terminalReason === "needs-human") exitCode = 1;
     } catch (err) {
       process.stderr.write(`${RED}${err.message}${RESET}\n`);
       exitCode = 1;

package/bin/hooks/pre-tool-use.mjs

@@ -180,13 +180,23 @@ const WORKFLOW_LABEL_PREFIX = "workflow:";
 // ---------------------------------------------------------------------------
 
 /**
- * Match a `find` search-root token that is exactly the filesystem root (`/`)
- * or a bare Git-Bash drive mount (`/c`, `/d`, `/C`, ... — a single letter,
- * case-insensitive, optionally followed by nothing else). Deliberately does
- * NOT match `/c/Users/...` or any other scoped absolute path — only the bare
- * root/drive-mount token itself.
+ * Match a `find` search-root token that reaches the exact same whole-drive,
+ * non-terminating scan on Git Bash as the bare filesystem root (`/`) or a
+ * bare drive mount (`/c`, `/d`, ...). This includes trailing-slash drive
+ * mounts (`/c/`) — a natural way to write the same root, since `/c` and
+ * `/c/` are the identical directory — and the dot/double-slash root
+ * variants `/.`, `/..`, `//`, which likewise resolve to (or immediately
+ * above, which Git Bash still normalizes to) the same whole-drive tree
+ * (issue #2113 — PR #2112 review finding SEC-1: `find /c/` was silently
+ * ALLOWED because the prior regex had no trailing-slash/dot alternative).
+ *
+ * Deliberately does NOT match `/c/Users/...`, `/./foo`, `/../foo`, or any
+ * other scoped absolute path — only the bare root/drive-mount token itself,
+ * optionally followed by exactly one trailing slash (drive-letter case) or
+ * standing alone (dot/double-slash case). Case-insensitive on the drive
+ * letter only (POSIX paths are otherwise case-sensitive).
  */
-const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z])?$/;
+const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z]\/?|\.{1,2}|\/)?$/;
 
 /**
  * Shell metacharacters that can glue a command name to an adjacent token
@@ -682,12 +692,16 @@ function extractLogicalTokens(command) {
 
 /**
  * Check whether a Bash command contains a `find` invocation whose search
- * root is the filesystem root (`/`) or a bare Git-Bash drive mount (`/c`,
- * `/d`, ...). On Windows Git Bash, `/` spans every mounted drive, so a
- * root-anchored `find` never terminates and accumulates as an orphaned,
- * CPU-exhausting process (issue #2034 — #1984 was a narrow precursor fix
- * that only patched a single call site + added a prose guardrail; this is
- * the systemic, deterministic follow-up).
+ * root is the filesystem root (`/`), a bare Git-Bash drive mount (`/c`,
+ * `/d`, ...), a trailing-slash drive mount (`/c/`), or a dot/double-slash
+ * root variant (`/.`, `/..`, `//`). On Windows Git Bash, `/` spans every
+ * mounted drive, so a root-anchored `find` never terminates and accumulates
+ * as an orphaned, CPU-exhausting process (issue #2034 — #1984 was a narrow
+ * precursor fix that only patched a single call site + added a prose
+ * guardrail; this is the systemic, deterministic follow-up. Issue #2113
+ * widened the root-token match to also cover the trailing-slash/dot
+ * variants, which reach the identical whole-drive scan but were not
+ * originally matched by `FIND_ROOT_TOKEN_RE`).
  *
  * Scans ALL logical tokens for a `find` occurrence (not just the first word
  * of the command), so it catches `find` appearing after `&&`, `;`, `|`, a

package/bin/journey.mjs

@@ -747,7 +747,8 @@ export async function preflight(ctx) {
 // Act II — Forging: command symlinks + SessionStart hook (Task 6)
 // ---------------------------------------------------------------------------
 
-import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink } from "fs/promises";
+import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink, rm } from "fs/promises";
+import { compareVersions } from "./registry.mjs";
 import { relative, dirname as pathDirname } from "path";
 import {
   installSessionStartHook,
@@ -1073,6 +1074,54 @@ async function copyDirIfChanged(srcDir, destDir) {
   return { copied, unchanged };
 }
 
+/**
+ * Recursively delete entries in `destDir` that no longer exist in `srcDir`.
+ * The mirror-image of copyDirIfChanged(): that function is additive-only (it
+ * copies new/changed files but never removes anything), so a file dropped or
+ * renamed upstream would otherwise linger in the persisted `~/.forge/` copy
+ * forever (forge#2133). A missing `srcDir` or `destDir` is treated as
+ * "nothing to reconcile" rather than an error — mirrors copyDirIfChanged()'s
+ * own ENOENT handling.
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @returns {Promise<{ removed: number }>}
+ */
+async function removeOrphans(srcDir, destDir) {
+  let destEntries;
+  try {
+    destEntries = await readdir(destDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return { removed: 0 };
+    throw err;
+  }
+
+  let srcNames = null;
+  try {
+    const srcEntries = await readdir(srcDir, { withFileTypes: true });
+    srcNames = new Set(srcEntries.map((e) => e.name));
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    // srcDir missing entirely — every dest entry is an orphan.
+    srcNames = new Set();
+  }
+
+  let removed = 0;
+  for (const entry of destEntries) {
+    const destPath = join(destDir, entry.name);
+    if (!srcNames.has(entry.name)) {
+      await rm(destPath, { recursive: true, force: true });
+      removed++;
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const sub = await removeOrphans(join(srcDir, entry.name), destPath);
+      removed += sub.removed;
+    }
+  }
+  return { removed };
+}
+
 /**
  * Copy ForgeDock's own installable payload (bin/, commands/, scripts/,
  * templates/) from wherever the package currently resolved — npm global
@@ -1115,6 +1164,7 @@ async function copyDirIfChanged(srcDir, destDir) {
  *   version: string,
  *   filesCopied?: number,
  *   filesUnchanged?: number,
+ *   filesRemoved?: number,
  * }>}
  */
 export async function persistHome(ctx) {
@@ -1142,15 +1192,55 @@ export async function persistHome(ctx) {
     // proceed with version === ""
   }
 
+  // Downgrade guard (forge#2133): if a newer version is already persisted at
+  // ~/.forge/version than the source package we're about to copy from, skip
+  // the copy entirely rather than silently overwriting newer files with
+  // older ones. This happens when a stale resolved package (e.g. a plain
+  // `npx forgedock update` that resolved an old global install) runs after
+  // ~/.forge/ was already refreshed to a newer version by some other path
+  // (e.g. `npx forgedock@latest`). Both `version` and the persisted value
+  // must be non-empty for the guard to apply — an unreadable/missing
+  // ~/.forge/version is treated as "no guard needed" so first-run persist
+  // is never blocked.
+  const persistedVersionPath = join(persistedHome, "version");
+  let existingPersistedVersion = "";
+  let persistedVersionFileExists = true;
+  try {
+    existingPersistedVersion = readFileSync(persistedVersionPath, "utf-8").trim();
+  } catch {
+    // missing/unreadable — proceed, nothing to guard against. Tracked
+    // separately from existingPersistedVersion's "" default so the
+    // versionChanged check below (a fresh persist with no prior version
+    // file) is still correctly treated as "changed" even when the source
+    // package's own version also resolves to "" (e.g. missing package.json).
+    persistedVersionFileExists = false;
+  }
+  if (
+    version &&
+    existingPersistedVersion &&
+    compareVersions(version, existingPersistedVersion) < 0
+  ) {
+    return {
+      forgeHome: persistedHome,
+      migrated: false,
+      skipped: true,
+      reason: `refusing to downgrade ~/.forge/ from v${existingPersistedVersion} to v${version} — source package is older than what's already persisted`,
+      version: existingPersistedVersion,
+    };
+  }
+
   try {
     await mkdir(persistedHome, { recursive: true });
 
     let filesCopied = 0;
     let filesUnchanged = 0;
+    let filesRemoved = 0;
     for (const name of PERSIST_HOME_DIRS) {
       const res = await copyDirIfChanged(join(source, name), join(persistedHome, name));
       filesCopied += res.copied;
       filesUnchanged += res.unchanged;
+      const pruned = await removeOrphans(join(source, name), join(persistedHome, name));
+      filesRemoved += pruned.removed;
     }
 
     // Also persist package.json itself (not just PERSIST_HOME_DIRS) — several
@@ -1181,18 +1271,19 @@ export async function persistHome(ctx) {
 
     // Write ~/.forge/version — content-compared like everything else here so
     // an unchanged version doesn't touch the file's mtime on every re-run.
-    const versionPath = join(persistedHome, "version");
-    let versionChanged = true;
-    try {
-      versionChanged = readFileSync(versionPath, "utf-8").trim() !== version;
-    } catch {
-      // missing/unreadable — treat as changed
-    }
+    // Reuses persistedVersionPath/existingPersistedVersion read above for the
+    // downgrade guard rather than re-reading the same file a second time. A
+    // version file that didn't exist yet (persistedVersionFileExists: false)
+    // always counts as "changed", regardless of whether the source's own
+    // version happens to also be "" (e.g. missing package.json) — otherwise
+    // "" !== "" would wrongly read as unchanged on a fresh, never-persisted
+    // ~/.forge/.
+    let versionChanged = !persistedVersionFileExists || existingPersistedVersion !== version;
     if (versionChanged) {
-      const tmpVersionPath = versionPath + ".tmp";
+      const tmpVersionPath = persistedVersionPath + ".tmp";
       try {
         writeFileSync(tmpVersionPath, version + "\n", "utf-8");
-        renameSync(tmpVersionPath, versionPath);
+        renameSync(tmpVersionPath, persistedVersionPath);
       } catch (err) {
         try { unlinkSync(tmpVersionPath); } catch { /* best-effort cleanup */ }
         throw err;
@@ -1201,11 +1292,12 @@ export async function persistHome(ctx) {
 
     return {
       forgeHome: persistedHome,
-      migrated: filesCopied > 0 || versionChanged,
+      migrated: filesCopied > 0 || filesRemoved > 0 || versionChanged,
       skipped: false,
       version,
       filesCopied,
       filesUnchanged,
+      filesRemoved,
     };
   } catch (err) {
     // Fail-open (forge#383): a permission error, disk-full, etc. must never

package/commands/forge-stats.md

@@ -34,8 +34,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 |------|-----------|-----------|
 | Orchestrator (work-on, orchestrate, review-pr) | 800 | Delegates to sub-agents; needs full pipeline logic |
 | Agent catalog (review-pr-agents, review-pr-staging) | 1000 | Reference file read on demand, not fed whole to one agent |
-| Specialist (milestone, analytics, validate, etc.) | 400 | Single-purpose; Sonnet attention degrades past this |
-| Utility (cleanup, sync-ecosystem, forge-stats) | 250 | Simple tasks; should stay lean |
+| Specialist (milestone, analytics, sync-ecosystem, validate, etc.) | 400 | Single-purpose or multi-subcommand; Sonnet attention degrades past this |
+| Utility (cleanup, forge-stats) | 250 | Simple tasks; should stay lean |
 | Sub-file (quality-gate, pipeline-health) | 350 | Invoked by parent; shares context budget |
 
 **Current overages (v1.1.0 baseline):**
@@ -46,7 +46,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 - `review-pr.md`: 796 lines (threshold 800) — OK
 - `validate.md`: 97 lines (threshold 400) — OK (compressed from 679)
 - `orchestrate.md`: 654 lines (threshold 800) — OK
-- `analytics.md`: 590 lines (threshold 400) — **48% over**
+- `analytics.md`: 856 lines (threshold 400) — **114% over**
+- `sync-ecosystem.md`: 799 lines (threshold 400) — **99% over**
 
 ---
 
@@ -75,7 +76,7 @@ for cmd in commands/*.md; do
     case "$name" in
         work-on.md|orchestrate.md|review-pr.md) threshold=800 ;;
         review-pr-agents.md|review-pr-staging.md) threshold=1000 ;;
-        cleanup.md|sync-ecosystem.md|forge-stats.md) threshold=250 ;;
+        cleanup.md|forge-stats.md) threshold=250 ;;
         quality-gate.md|pipeline-health.md) threshold=350 ;;
         *) threshold=400 ;;
     esac

package/commands/issue.md

@@ -13,7 +13,7 @@ You create GitHub issues with the exact structure the `/work-on` pipeline expect
 
 `/issue` is the structured create-hook for issue creation across the pipeline — it enforces the canonical template, reads code before drafting, runs dedup, and validates mandatory sections. Because those checks are deterministic, `/issue` **creates the issue by default once they pass** — it does not wait for a human to approve the draft. Pass `--dry-run` to review the draft without creating anything (see Argument Parsing below).
 
-`/issue` also accepts a **programmatic invocation form** for callers that have already composed a title, body, labels, and (optionally) a milestone — e.g. `Skill(skill="issue", args="--title \"fix: ...\" --body-file /tmp/body.md --label bug --label P2")`. This form skips the free-text parsing (Phase 1) and LLM drafting (Phase 3) entirely, but still runs the same dedup and body-validation correctness gates as the interactive path. See **Programmatic Invocation Contract** below.
+`/issue` also accepts a **programmatic invocation form** for callers that have already composed a title, body, labels, and (optionally) a milestone — e.g. `Skill(skill="issue", args="--title \"fix: ...\" --body-file \"$(mktemp)\" --label bug --label P2")` (the caller writes the body to that path before invoking). This form skips the free-text parsing (Phase 1) and LLM drafting (Phase 3) entirely, but still runs the same dedup and body-validation correctness gates as the interactive path. See **Programmatic Invocation Contract** below — in particular, `--body-file` callers MUST use a `mktemp`-created path, never a fixed literal like `/tmp/body.md`; concurrent orchestrated agents share this host's `/tmp`, and a fixed path can be clobbered mid-flight by another agent (forge#2198).
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
@@ -181,6 +181,10 @@ For callers that have already composed a title, body, labels, and (optionally) a
 
 If `--title` is present but neither `--body` nor `--body-file` is supplied, or both are supplied, this is a usage error: print `ERROR: programmatic mode requires exactly one of --body or --body-file` and STOP — do not fall through to Phase 2D or Phase 4B.
 
+**`--body-file` path requirement (MANDATORY for the caller)**: The path passed to `--body-file` MUST come from `mktemp` (e.g. `BODY_FILE="$(mktemp)"`), never a fixed literal such as `/tmp/body.md` or `/tmp/issue.json`. Concurrent orchestrated agents (`/orchestrate` dispatches up to `orchestration.max_concurrent` agents, default 12) share this host's `/tmp` — a fixed filename collides across agents, and a second agent's write to the same path can silently corrupt the first agent's staged content before it is read. `mktemp` gives every caller a collision-free path at effectively zero cost. This applies to every `--body-file` caller across the pipeline (`commands/work-on.md`, `commands/work-on/decompose.md`, `commands/review-pr*.md`, `commands/orchestrate/phase-1-resolve.md`, and all others) — all current callers already comply; this is the stated contract that keeps it that way (forge#2198).
+
+**Fail-loud read ordering (the defensive mechanism against a clobbered body-file)**: `/issue` reads `$PROGRAMMATIC_BODY_FILE` exactly once, into memory, immediately below — it never re-reads the file later in the pipeline. This is deliberate: combined with a `mktemp`-unique path, it minimizes the window in which another process could overwrite the file between the caller's write and this read to effectively nil (no other agent has any reason to target a `mktemp`-generated path). If the file is missing or unreadable at read time, the check below fails loudly (`exit 1`) rather than silently proceeding with an empty or partial body — a clobbered/missing body-file is surfaced as an error, not pushed to GitHub.
+
 ```bash
 if [ "$PROGRAMMATIC_MODE" = "true" ]; then
   if [ -n "$PROGRAMMATIC_BODY" ] && [ -n "$PROGRAMMATIC_BODY_FILE" ]; then

package/commands/orchestrate/phase-4-execution.md

@@ -425,6 +425,8 @@ Agent(
   - For satellite repo issues: `Skill(skill='work-on', args='{SATELLITE_PREFIX}:{NUMBER} --under-orchestration')` (prefix from forge.yaml → repos.satellites)
   - The `--under-orchestration` flag tells `/work-on` to post its phase-entry `FORGE:HEARTBEAT` comments (Phases 0/1/3/5) — this orchestrator's Step 4B.5 stall detector depends on those timestamps. A solo `/work-on` run omits the flag and skips those writes entirely (see `commands/work-on.md` → Orchestration Flag).
 - NEVER bypass /work-on with manual git/gh commands — the label updates and structured comments are critical for tracking
+- **Temp files — ALWAYS use `mktemp`, NEVER a fixed path**: You are one of several agents running concurrently on this host and you share its `/tmp` with all of them. Any time you stage content in a temp file before passing it to `gh` (e.g. `--body-file`), create that path with `mktemp` (e.g. `BODY_FILE="$(mktemp)"`) — never a fixed literal like `/tmp/body.md` or `/tmp/issue.json`. A fixed path collides with another concurrently-running agent and can silently overwrite the content you staged (or you can silently overwrite theirs) before either of you reads it back — this has caused real cross-agent GitHub issue-body corruption. `mktemp` costs nothing and eliminates the collision. (forge#2198)
+- **`docker cp` — NEVER write into a bind-mounted shared container**: If the project you're working on runs its dev/test containers with a bind mount to the main (non-worktree) checkout, `docker cp` into that container writes through the mount into the main checkout — not your isolated per-issue worktree. Before running `docker cp` into any container, confirm its mount source is your own worktree, not a shared/main one; if you can't confirm that, don't assume an in-container test run reflects your feature branch. (forge#2198)
 - NEVER target `main` for PRs targeting the default repo. Use `{STAGING_BRANCH}` for fast-lane issues, or `milestone/{slug}` for milestone issues.
 - Satellite repos (MCP, n8n) have no staging branch — fast-lane PRs go to `main` for those.
 - If the issue is INVALID after investigation, close it with a comment explaining why

package/commands/qa-sweep.md

@@ -36,6 +36,23 @@ See README.md Requirements section for full setup instructions.
 
 ---
 
+## Playwright MCP Prerequisite (MANDATORY — check before proceeding)
+
+Playwright MCP is a **guaranteed ForgeDock dependency** for all browser automation commands. Before running any qa-sweep phase, verify it is available:
+
+**Check**: Confirm `mcp__playwright__*` tools are available in your tool context (e.g., `mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`).
+
+**If Playwright MCP tools are NOT available**: STOP immediately. Do not attempt to run qa-sweep — all browser automation steps will fail silently.
+
+**Fix**:
+1. Register Playwright MCP: `claude mcp add playwright npx @playwright/mcp@latest`
+2. Restart Claude Code to reload MCP servers
+3. Verify with: `npx forgedock doctor` (Check 9 confirms registration)
+
+See README.md Requirements section for full setup instructions.
+
+---
+
 ## Browser Tool Reference
 
 All browser automation uses Playwright MCP tools (`mcp__playwright__*`). Playwright MCP is a guaranteed ForgeDock dependency — see the Playwright MCP Prerequisite section above.

package/commands/replay.md

@@ -95,7 +95,7 @@ fi
 
 ```bash
 # Filter to comments that contain a FORGE pipeline annotation
-FORGE_COMMENTS=$(echo "$ALL_COMMENTS" | jq -c '[.[] | select(.body | test("<!-- FORGE:(INVESTIGATOR|CONTRACT|CONTEXT|ARCHITECT|BUILDER|DECOMPOSED|TRAJECTORY)"))]')
+FORGE_COMMENTS=$(echo "$ALL_COMMENTS" | jq -c '[.[] | select(.body | test("<!-- FORGE:(INVESTIGATOR|CONTRACT|CONTEXT|ARCHITECT|BUILDER|DECOMPOSED|SUMMARY|TRAJECTORY)"))]')
 FORGE_COUNT=$(echo "$FORGE_COMMENTS" | jq 'length')
 
 if [ "$FORGE_COUNT" -eq 0 ]; then
@@ -115,7 +115,7 @@ echo ""
 
 ## Step 5: Display Each Annotation
 
-Phase mapping (inline): `INVESTIGATOR`→Phase 1, `CONTRACT`→Phase 3C, `CONTEXT`→Phase 3C.5, `ARCHITECT`→Phase 3C.6, `BUILDER`→Phase 3M, `DECOMPOSED`→Phase 2, `TRAJECTORY`→Phase 7.
+Phase mapping (inline): `INVESTIGATOR`→Phase 1, `CONTRACT`→Phase 3C, `CONTEXT`→Phase 3C.5, `ARCHITECT`→Phase 3C.6, `BUILDER`→Phase 3M, `DECOMPOSED`→Phase 2, `SUMMARY`→Phase C4.5, `TRAJECTORY`→Phase 7.
 
 For each FORGE comment in chronological order, print a formatted block. Use Python for robust multiline extraction from the comment body.
 
@@ -136,6 +136,7 @@ echo "$FORGE_COMMENTS" | jq -c '.[]' | while IFS= read -r COMMENT; do
     "FORGE:ARCHITECT")    PHASE_LABEL="Phase 3C.6 — Architecture Plan" ;;
     "FORGE:BUILDER")      PHASE_LABEL="Phase 3M — Implementation" ;;
     "FORGE:DECOMPOSED")   PHASE_LABEL="Phase 2 — Decomposition" ;;
+    "FORGE:SUMMARY")      PHASE_LABEL="Phase C4.5 — Shareable Summary" ;;
     "FORGE:TRAJECTORY")   PHASE_LABEL="Phase 7 — Pipeline Trajectory" ;;
     *)                    PHASE_LABEL="$ANNOTATION" ;;
   esac
@@ -216,6 +217,19 @@ elif annotation == "FORGE:DECOMPOSED":
     for s in subs[:5]:
         print(f"│    {s}")
 
+elif annotation == "FORGE:SUMMARY":
+    lane       = extract(r'\*\*Lane\*\*\s*\|\s*([^\|]+)')
+    verdict    = extract(r'\*\*Investigation verdict\*\*\s*\|\s*([^\|]+)')
+    task_type  = extract(r'\*\*Task type\*\*\s*\|\s*([^\|]+)')
+    review     = extract(r'\*\*Review verdict\*\*\s*\|\s*([^\|]+)')
+    files      = extract(r'\*\*Files changed\*\*\s*\|\s*([^\|]+)')
+    pr_link    = extract(r'\[View PR #(\d+)\]')
+    print(f"│  Lane       : {lane.strip()[:60]}")
+    print(f"│  Verdict    : {verdict.strip()[:60]}")
+    print(f"│  Task type  : {task_type.strip()[:60]}")
+    print(f"│  Review     : {review.strip()[:60]}")
+    print(f"│  Files      : {files.strip()[:30]}  |  PR: #{pr_link}")
+
 elif annotation == "FORGE:TRAJECTORY":
     # Print the phase table lines verbatim (they're already formatted)
     in_table = False