forgedock 1.1.7 → 1.1.9

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

@@ -8,6 +8,41 @@ const _require = createRequire(import.meta.url);
 /** Absolute path to the ForgeDock installation root (parent of bin/). */
 const FORGE_HOME = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
+// Lazy-loaded invariants module and YAML declarations (loaded once on first use).
+// Using a lazy import avoids top-level await and keeps the module synchronous
+// for the simple path — invariant loading only happens when a branch checkout
+// command is detected.
+// Sentinel states for _invariants:
+//   null   — import not yet attempted
+//   false  — a prior import attempt failed (do NOT retry; stay fail-open)
+//   object — successfully loaded module namespace (cached)
+let _invariants = null;
+let _invariantDecls = null;
+
+async function getInvariants() {
+  // A prior import attempt already failed — stay fail-open, do not retry.
+  if (_invariants === false) return { module: null, decls: [] };
+  // Successful load cached from a previous call.
+  if (_invariants !== null) return { module: _invariants, decls: _invariantDecls };
+  // Not yet attempted — try importing now.
+  try {
+    _invariants = await import(
+      pathToFileURL(join(FORGE_HOME, "bin", "engine", "invariants.mjs")).href
+    );
+    _invariantDecls = _invariants.loadInvariants(
+      join(FORGE_HOME, "forge-invariants.yaml")
+    );
+  } catch {
+    // invariants.mjs unavailable (fresh install, partial update) — fail-open.
+    // Mark the failure with a distinct sentinel so we don't re-attempt the
+    // import on every subsequent call.
+    _invariants = false;
+    _invariantDecls = [];
+    return { module: null, decls: [] };
+  }
+  return { module: _invariants, decls: _invariantDecls };
+}
+
 /**
  * bin/hooks/pre-tool-use.mjs — ForgeDock PreToolUse hook.
  *
@@ -40,6 +75,23 @@ const FORGE_HOME = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", ".
  *    against the workflow label state machine.
  *    Blocks invalid transitions (e.g. jumping from investigating to merged).
  *
+ * 3. Declared precondition checks (from forge-invariants.yaml)
+ *    Intercepts git checkout / git worktree add / git switch commands and
+ *    evaluates pretooluse-scope invariants declared in forge-invariants.yaml.
+ *    Currently: branch_must_exist_on_remote — blocks checkouts of branches
+ *    that don't exist on origin (catches hallucinated branch names before
+ *    they cause a mid-build git failure).
+ *
+ * 4. Gist visibility guard (issue #1729)
+ *    Intercepts `gh gist create --public` and hard-blocks it.
+ *    Memory-bearing pipeline gists (FORGE:KNOWLEDGE_GIST, FORGE:MILESTONE_INDEX,
+ *    FORGE:PRIOR_GIST, FORGE:MEMORY_INDEX) MUST be secret — publishing them to
+ *    a world-readable Gist exposes root causes, file paths, and security findings.
+ *    Override: set FORGE_ALLOW_PUBLIC_GIST=1 in the shell environment before
+ *    starting Claude Code (operator-set only — agents cannot bypass this by
+ *    setting env vars via Bash tool calls, as this hook reads process.env which
+ *    is set at process start, not at tool-call time).
+ *
  * Both rules only apply inside a ForgeDock-managed directory (a directory
  * with a `forge.yaml` or `.forgedock` marker) — see `isForgeDockManagedCwd()`
  * (issue #1591). The hook installs into the user's global
@@ -139,9 +191,87 @@ async function main() {
     return;
   }
 
+  // --- Rule 3: Declared precondition checks (forge-invariants.yaml) ---
+  const preconditionViolation = await checkDeclaredPreconditions(command);
+  if (preconditionViolation) {
+    process.stderr.write(preconditionViolation);
+    process.exit(2);
+    return;
+  }
+
+  // --- Rule 4: Gist visibility guard ---
+  const gistViolation = checkGistVisibility(command);
+  if (gistViolation) {
+    process.stderr.write(gistViolation);
+    process.exit(2);
+    return;
+  }
+
   process.exit(0);
 }
 
+// ---------------------------------------------------------------------------
+// Rule 3: Declared precondition checks (forge-invariants.yaml)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check declared pretooluse-scope invariants from forge-invariants.yaml.
+ *
+ * Currently evaluates the branch_must_exist_on_remote precondition for:
+ *   - git checkout <branch>
+ *   - git worktree add <path> [-b <branch>] <base>
+ *   - git switch <branch>
+ *
+ * Wrapped in a try/catch in the caller (main()) — fail-open on any error.
+ *
+ * @param {string} command
+ * @returns {Promise<string|null>} Error message or null if allowed.
+ */
+async function checkDeclaredPreconditions(command) {
+  // Only intercept git commands that reference a branch.
+  const isCheckout = /git\s+(?:checkout|switch)/.test(command) &&
+    !/git\s+checkout\s+-[bf]/.test(command); // -b creates new branch (no check needed)
+  const isWorktreeAdd = /git\s+worktree\s+add/.test(command);
+
+  if (!isCheckout && !isWorktreeAdd) return null;
+
+  // Extract branch name from command.
+  let branch = null;
+  if (isCheckout) {
+    // git checkout <branch> or git switch <branch>
+    // Avoid matching flags: skip tokens starting with -
+    const m = command.match(/git\s+(?:checkout|switch)\s+(?:--\s+)?([^\s-][^\s]*)/);
+    if (m) branch = m[1];
+  } else if (isWorktreeAdd) {
+    // git worktree add <path> <base> — base is typically origin/<branch> or just <branch>
+    // Also handle: git worktree add <path> -b <new-branch> <base>
+    const tokens = tokenizeCommand(command).map((t) => t.value);
+    // Find -b flag if present (new branch — no remote check needed)
+    const bIdx = tokens.indexOf("-b");
+    if (bIdx !== -1) return null; // creating new branch — no remote existence check
+    // Otherwise the last non-option argument after 'add' and path is the base
+    const addIdx = tokens.findIndex((t) => t === "add");
+    if (addIdx !== -1 && addIdx + 2 < tokens.length) {
+      const base = tokens[addIdx + 2];
+      // base may be 'origin/<branch>' — strip the remote prefix
+      branch = base.replace(/^origin\//, "");
+    }
+  }
+
+  if (!branch || branch.startsWith("-") || branch === "HEAD") return null;
+
+  // Load invariants (cached after first load).
+  const { module, decls } = await getInvariants();
+  if (!module || !decls?.length) return null;
+
+  // Evaluate the branch_must_exist precondition.
+  const result = await module.checkPrecondition(decls, "branch_must_exist_on_remote", { branch });
+  if (!result.ok) {
+    return module.formatViolation(result) + "\n";
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Project-scope guard (issue #1591)
 // ---------------------------------------------------------------------------
@@ -326,6 +456,58 @@ function checkLabelTransition(command) {
   return null; // valid transition — allow
 }
 
+// ---------------------------------------------------------------------------
+// Rule 4: Gist visibility guard (issue #1729)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a gh gist create command uses the --public flag.
+ *
+ * Pipeline gists (FORGE:KNOWLEDGE_GIST, FORGE:MILESTONE_INDEX, FORGE:PRIOR_GIST,
+ * FORGE:MEMORY_INDEX) MUST be secret. Passing --public to gh gist create publishes
+ * investigation findings — root causes, file paths, security details — to a
+ * world-readable URL. gh gist create is secret by default; this rule blocks any
+ * explicit --public override so a future spec edit cannot reintroduce a public gist.
+ *
+ * Override: FORGE_ALLOW_PUBLIC_GIST=1 in the operator's shell environment.
+ * This env var must be set BEFORE starting Claude Code — it is read from process.env
+ * at hook startup, not from the tool payload, so agents cannot bypass it by setting
+ * the variable via a Bash tool call in the same session.
+ *
+ * @param {string} command
+ * @returns {string|null} Error message to show, or null if allowed.
+ */
+function checkGistVisibility(command) {
+  // Only check gh gist create commands.
+  if (!/gh\s+gist\s+create/.test(command)) return null;
+
+  // Allow operator override via env var.
+  if (process.env.FORGE_ALLOW_PUBLIC_GIST === "1") return null;
+
+  // Check for --public flag (space form, equals form, and standalone --public).
+  // extractFlag handles --public=value; for the bare boolean flag --public we
+  // additionally check whether "--public" appears as a standalone token.
+  const tokens = tokenizeCommand(command);
+  const hasPublicFlag = tokens.some(({ value }) => value === "--public") ||
+    extractFlag(command, "--public") !== null;
+
+  if (hasPublicFlag) {
+    return [
+      `[ForgeDock] BLOCKED: gh gist create --public is a pipeline violation.`,
+      ``,
+      `Pipeline gists (FORGE:KNOWLEDGE_GIST, FORGE:MILESTONE_INDEX, FORGE:PRIOR_GIST,`,
+      `FORGE:MEMORY_INDEX) MUST be created secret. Passing --public publishes`,
+      `investigation findings — root causes, file paths, security details — to a`,
+      `world-readable URL. Remove the --public flag (gh gist create is secret by default).`,
+      ``,
+      `Exception: set FORGE_ALLOW_PUBLIC_GIST=1 in your shell environment BEFORE`,
+      `starting Claude Code if you intentionally need a public gist.`,
+    ].join("\n");
+  }
+
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Git helpers
 // ---------------------------------------------------------------------------

package/bin/hooks/session-start.mjs

@@ -63,6 +63,16 @@ let markNudgeSeen;
 let parseForgeYaml;
 let sanitizeContextValue;
 
+// ---------------------------------------------------------------------------
+// init-detect helpers — populated inside the try block to honour fail-open
+// ---------------------------------------------------------------------------
+
+// Declared at module scope so it is accessible from handler functions
+// (handleUnmanaged) called from within the try block. Assigned inside the
+// try/catch so that any import failure (missing file, permissions error,
+// syntax error) is caught and the hook still exits 0. <!-- fix: forge#1927 -->
+let resolveGitRoot;
+
 // ---------------------------------------------------------------------------
 // Main — wrapped in try/catch to guarantee fail-open
 // ---------------------------------------------------------------------------
@@ -98,6 +108,21 @@ try {
     )
   );
 
+  // Import the git-root resolver from the same installation.
+  // Placed inside try/catch to honour the fail-open contract: if init-detect.mjs
+  // cannot be loaded (broken install, missing file, permissions error) the
+  // catch block below ensures we still exit 0 without blocking Claude Code.
+  //
+  // Use pathToFileURL() to convert the OS-native path to a file:// URL before
+  // passing it to dynamic import(). On Windows, join() produces backslash paths
+  // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
+  /** @type {import('../init-detect.mjs')} */
+  (
+    { resolveGitRoot } = await import(
+      pathToFileURL(join(FORGE_HOME, "bin", "init-detect.mjs")).href
+    )
+  );
+
   const cwd = process.cwd();
   const state = resolveState(cwd);
 
@@ -165,19 +190,32 @@ async function handleManagedActive(dir) {
  * Uses the registry to ensure the nudge fires at most once per directory.
  * After showing, records the directory so subsequent sessions are silent.
  *
+ * The nudge-tracking key is the *resolved git root*, not the raw `dir` — a
+ * user who launches Claude Code from a parent directory that merely contains
+ * the real git repo as its single subdirectory (e.g. `Projects/` containing
+ * `Projects/my-app/.git`) would otherwise have every sibling project under
+ * that same parent share one nudge-seen entry: the first project to trigger
+ * the nudge silently suppresses it for all the others. `resolveGitRoot`
+ * degrades gracefully (falls back to the unresolved `dir`) when the case
+ * doesn't apply, so this is safe to call unconditionally. <!-- fix: forge#1927 -->
+ *
  * @param {string} dir - Absolute path to the project directory.
  */
 async function handleUnmanaged(dir) {
-  if (nudgeSeen(dir)) {
+  const trackingKey = resolveGitRoot(dir).root;
+
+  if (nudgeSeen(trackingKey)) {
     // Nudge already shown — stay silent
     return;
   }
 
-  // Show the nudge, then record it so it won't show again
+  // Show the nudge, then record it so it won't show again. The displayed
+  // message still shows the raw `dir` the user is actually in — only the
+  // tracking key changes.
   console.log(buildNudgeContext(dir));
 
   // Best-effort — if this fails the nudge may show once more next session
-  await markNudgeSeen(dir).catch(() => {});
+  await markNudgeSeen(trackingKey).catch(() => {});
 }
 
 // ---------------------------------------------------------------------------
@@ -223,12 +261,39 @@ function buildActiveContext(dir, forgeYaml) {
     200,
   );
 
+  // Default agent model — resolved from forge.yaml's optional
+  // `agents.default_model` field, falling back to "sonnet" (the hardcoded
+  // default every command spec's "Agent model policy" line already uses).
+  // Rendered unconditionally, like stagingBranch/featurePattern above, so
+  // command specs always have a concrete value to reference — not a
+  // conditional *Note line like milestoneNote, which is omitted when unset.
+  const defaultModel = sanitizeContextValue(
+    forgeYaml.agents?.default_model ?? "sonnet",
+    100,
+  ) ?? "sonnet";
+
+  // Sub-agent model — resolved from forge.yaml's optional
+  // `agents.subagent_model` field. Governs child agents that a top-level
+  // command spawns internally (e.g. /orchestrate's per-issue /work-on
+  // agents, /review-pr's domain persona reviewers), which is a distinct
+  // hardcoded call-site from the top-level "Agent model policy" banner that
+  // `defaultModel` above already covers. Falls back to `defaultModel` (not
+  // directly to "sonnet") so a project that only sets `default_model` gets
+  // consistent behavior across both the main agent and its children.
+  // Rendered unconditionally, same as defaultModel above. <!-- issue #1852 -->
+  const subagentModel = sanitizeContextValue(
+    forgeYaml.agents?.subagent_model ?? defaultModel,
+    100,
+  ) ?? defaultModel;
+
   return `\
 <!-- ForgeDock: managed-active -->
 **ForgeDock** is active in this directory (${safeDir}).
 ${nameNote}${repoNote}${descNote}${milestoneNote}
 - **Staging branch**: \`${stagingBranch}\`
 - **Feature branch pattern**: \`${featurePattern}\`
+- **Default agent model**: \`${defaultModel}\`
+- **Sub-agent model**: \`${subagentModel}\`
 
 ### Available pipeline commands
 

package/bin/init-detect.mjs

@@ -2,7 +2,11 @@
 /**
  * init-detect.mjs — Pure deterministic config detection for ForgeDock.
  *
- * Exports a single function: detectConfig(cwd)
+ * Exports:
+ *   detectConfig(cwd)   → Promise<ConfigDraft>  (main deterministic detector)
+ *   resolveGitRoot(cwd) → { root, resolved, why }  (git-root resolution,
+ *                          reused outside this module by session-start.mjs's
+ *                          nudge-tracking path — see forge#1927)
  *
  * Returns a ConfigDraft: a structured object mirroring forge.yaml's required
  * sections (project, paths, branches) where every leaf is:
@@ -21,7 +25,8 @@
  */
 
 import { execFileSync } from "child_process";
-import { join } from "path";
+import { join, resolve } from "path";
+import { readdirSync, existsSync } from "fs";
 
 // ---------------------------------------------------------------------------
 // Field factory helpers
@@ -228,13 +233,88 @@ function detectStagingBranch(cwd, defaultBranch) {
     // git not available or no remotes
   }
 
-  return medium(
+  // No 'origin/staging' found. Deriving a merge target from a failed lookup
+  // is not a "likely correct" inference — it's a guess, and `staging` is the
+  // single most destructive field to get wrong (it's the fast-lane PR merge
+  // target). Flag it "low" so it gets a # TODO comment and the [low] badge
+  // instead of silently blending in as if it were verified. <!-- Added: forge#1850 -->
+  return low(
     defaultBranch,
-    "derived from default branch",
-    `No 'origin/staging' remote branch found; staging defaults to the default branch '${defaultBranch}'`,
+    "default placeholder",
+    `No 'origin/staging' remote branch found; guessed the default branch '${defaultBranch}' — verify this is actually your staging branch`,
   );
 }
 
+/**
+ * Resolve the effective git repository root for detection purposes.
+ *
+ * `execFileSync("git", ...)` already searches UPWARD through parent
+ * directories to find a repo root, so a `cwd` nested inside a repo is
+ * already handled correctly with no extra code here. The gap this closes is
+ * the other direction: `cwd` is a *parent* of the actual repo (a common
+ * monorepo-adjacent layout, e.g. `ScraperAPI/` containing the real repo at
+ * `ScraperAPI/alterlab/`) — git has no way to discover a repo by looking
+ * downward, so every detector below would otherwise degrade straight to
+ * placeholders.
+ *
+ * Never throws; falls back to the original `cwd` unchanged when neither
+ * case applies (no repo found at all, or the subdirectory scan is
+ * ambiguous — zero or multiple candidates).
+ *
+ * Exported for reuse outside `detectConfig()` — `bin/hooks/session-start.mjs`
+ * uses it to resolve the nudge-tracking key so that a directory which is a
+ * parent of the real git repo doesn't collide with sibling projects sharing
+ * the same parent. <!-- Added: forge#1927 -->
+ *
+ * @param {string} cwd
+ * @returns {{ root: string, resolved: boolean, why: string }}
+ */
+export function resolveGitRoot(cwd) {
+  // cwd is already inside a repo (possibly nested) — `--show-toplevel` finds
+  // the true root regardless of depth. Compare with path.resolve() so a pure
+  // separator-style difference (git always emits forward slashes, even on
+  // Windows) doesn't get mistaken for an actual resolution.
+  try {
+    const toplevel = execFileSync(
+      "git",
+      ["rev-parse", "--show-toplevel"],
+      { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 },
+    ).trim();
+    if (toplevel) {
+      const resolved = resolve(toplevel) !== resolve(cwd);
+      return {
+        root: resolved ? toplevel : cwd,
+        resolved,
+        why: `'${cwd}' is nested inside a git repository rooted at '${toplevel}'`,
+      };
+    }
+  } catch {
+    // Not inside any git repository — try the subdirectory scan below.
+  }
+
+  // cwd itself isn't a repo — check whether it holds exactly one immediate
+  // subdirectory that is. Ambiguous (0 or 2+) candidates fall through
+  // unchanged, preserving the existing placeholder behavior.
+  try {
+    const entries = readdirSync(cwd, { withFileTypes: true });
+    const gitDirs = entries.filter(
+      (e) => e.isDirectory() && existsSync(join(cwd, e.name, ".git")),
+    );
+    if (gitDirs.length === 1) {
+      const sub = join(cwd, gitDirs[0].name);
+      return {
+        root: sub,
+        resolved: true,
+        why: `'${cwd}' is not a git repository, but its only subdirectory '${gitDirs[0].name}' is — resolved detection to that subdirectory`,
+      };
+    }
+  } catch {
+    // cwd unreadable — fall through to the unresolved case.
+  }
+
+  return { root: cwd, resolved: false, why: "" };
+}
+
 /**
  * Derive a human-readable project name from the repository slug.
  *
@@ -295,23 +375,32 @@ function deriveProjectName(repoSlug) {
  * @returns {Promise<ConfigDraft>}
  */
 export async function detectConfig(cwd = process.cwd()) {
+  // Resolve the effective repo root FIRST — every detector below runs
+  // against this, not the raw cwd argument. See resolveGitRoot() docblock.
+  const { root: gitRoot, resolved: rootResolved, why: rootWhy } = resolveGitRoot(cwd);
+
   // Project identity
-  const { owner, repo, remoteDetected } = detectRemote(cwd);
+  const { owner, repo, remoteDetected } = detectRemote(gitRoot);
 
   // Project name derived from the repo slug
   const name = deriveProjectName(repo.value);
 
-  // Paths — always high confidence (derived from the cwd argument)
-  const root = high(cwd, "process.cwd()", "Absolute path passed to detectConfig — the project root");
+  // Paths — high confidence in the common case (root === cwd, nothing to
+  // resolve). When detection had to redirect to a git subdirectory or a
+  // parent toplevel, flag it medium confidence with an explanatory `why` so
+  // the review screen surfaces the redirection instead of silently adopting it.
+  const root = rootResolved
+    ? medium(gitRoot, "resolved git repository root", rootWhy)
+    : high(cwd, "process.cwd()", "Absolute path passed to detectConfig — the project root");
   const worktreeBase = high(
-    join(cwd, ".claude", "worktrees"),
+    join(gitRoot, ".claude", "worktrees"),
     "derived from root",
-    `Convention: {root}/.claude/worktrees (root = ${cwd})`,
+    `Convention: {root}/.claude/worktrees (root = ${gitRoot})`,
   );
 
   // Branch detection
-  const defaultBranchField = detectDefaultBranch(cwd);
-  const stagingBranchField = detectStagingBranch(cwd, defaultBranchField.value);
+  const defaultBranchField = detectDefaultBranch(gitRoot);
+  const stagingBranchField = detectStagingBranch(gitRoot, defaultBranchField.value);
 
   return {
     project: { owner, repo, name },