forgedock 1.1.6 → 1.1.8

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://avatars.githubusercontent.com/in/3731547?s=200&u=b38eba537e011502c010d4b682d641f802591845&v=4" alt="ForgeDock" width="80" />
+<img src="https://avatars.githubusercontent.com/in/4051319?s=200&v=4" alt="ForgeDock" width="80" />
 
 <h1>ForgeDock</h1>
 
@@ -227,6 +227,8 @@ npx forgedock --global # global install: installs into ~/.claude/commands/ — a
 
 **Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
 
+> **Want engine-mode dispatch?** `npx forgedock` is transient — the `forgedock` binary isn't persisted in PATH after install. `/orchestrate` and `/autopilot` use agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (`forgedock run-issue`) with its durable phase table and fail-closed review gate, run `npm install -g forgedock` instead.
+
 One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated `forge.yaml` to review — press Enter to accept. Run `npx forgedock init` any time afterward to re-generate the config only.
 
 Installing also registers a SessionStart hook, so every Claude Code session

package/bin/engine/invariants.mjs

@@ -0,0 +1,361 @@
+/**
+ * bin/engine/invariants.mjs — ForgeDock pipeline invariant evaluator.
+ *
+ * Evaluates three classes of invariants declared in forge-invariants.yaml:
+ *
+ *   pretooluse  — preconditions checked in pre-tool-use.mjs before tool
+ *                 execution (e.g. branch-must-exist-on-remote)
+ *   runlog      — temporal ordering rules over the append-only run-log
+ *                 (e.g. review-precedes-merge)
+ *   close       — terminal-state assertions checked before trajectory post
+ *                 (e.g. issue-closed-at-terminal)
+ *
+ * === Design constraints ===
+ *
+ * • No circular imports: only imports node:fs, node:child_process, node:path,
+ *   node:url. Does NOT import engine.mjs or phases.mjs.
+ * • Fail-open: every exported function returns a result object on error
+ *   rather than throwing. A missing forge-invariants.yaml or yq returns [].
+ * • Single-pass temporal evaluation: O(n) over the run-log event list.
+ *   No GitHub API calls.
+ * • Named violations: every failed result includes { ok: false, id, violated }
+ *   so callers can surface the proposition by name.
+ *
+ * === Usage ===
+ *
+ * // Load all declared invariants:
+ * const invariants = loadInvariants(forgeInvariantsYamlPath);
+ *
+ * // Evaluate temporal rules over a run-log event stream:
+ * const results = evaluateTemporalRules(invariants, events);
+ *
+ * // Check a hook precondition (branch must exist):
+ * const result = await checkPrecondition(invariants, "branch_must_exist_on_remote", { branch });
+ *
+ * // Assert close-time invariants before posting trajectory:
+ * const results = assertCloseInvariants(invariants, events);
+ */
+
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// YAML loader — uses yq (pipeline dependency) for proper array support.
+// forge-utils.mjs's minimal parser does not handle YAML sequences.
+// ---------------------------------------------------------------------------
+
+/**
+ * Load invariant declarations from forge-invariants.yaml.
+ *
+ * Returns an empty array if:
+ *   - forge-invariants.yaml is absent (fresh install before file ships)
+ *   - yq is not installed (graceful degradation)
+ *   - any parse error occurs
+ *
+ * @param {string} [yamlPath] Absolute path to forge-invariants.yaml.
+ *   Defaults to {repo root}/forge-invariants.yaml resolved relative to
+ *   this file's location.
+ * @returns {Invariant[]}
+ */
+export function loadInvariants(yamlPath) {
+  // Default: resolve relative to bin/engine/ → repo root / forge-invariants.yaml
+  const DEFAULT_PATH = resolve(
+    fileURLToPath(import.meta.url),
+    "..", "..", "..", "forge-invariants.yaml",
+  );
+  const target = yamlPath || DEFAULT_PATH;
+
+  if (!existsSync(target)) return []; // file absent — fail-open, not an error
+
+  try {
+    // Use yq to convert YAML → JSON (handles arrays; yq is a pipeline dep).
+    const json = execFileSync("yq", ["-o", "json", ".", target], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    const parsed = JSON.parse(json);
+    const items = parsed?.invariants;
+    if (!Array.isArray(items)) return [];
+    return items.filter(
+      (i) => i && typeof i.id === "string" && typeof i.scope === "string",
+    );
+  } catch {
+    // yq not installed, parse error, or any other failure — fail-open.
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Temporal rule evaluation (single-pass, O(n), no I/O)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate all runlog-scope invariants against an event list.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {object[]}    events      Event list from readLog() / deriveState().
+ * @returns {InvariantResult[]}
+ */
+export function evaluateTemporalRules(invariants, events) {
+  const rules = invariants.filter((i) => i.scope === "runlog");
+  if (!rules.length || !events.length) return rules.map((r) => ({ ok: true, id: r.id }));
+
+  // Single-pass: collect per-event-type positions.
+  const phaseCommits = {}; // phase id → first commit seq
+  let firstTerminal = null;
+  let terminalCount = 0;
+  let terminalReason = null;
+
+  for (const e of events) {
+    if (e.event === "PHASE_COMMIT" && e.phase) {
+      if (!(e.phase in phaseCommits)) phaseCommits[e.phase] = e.seq;
+    } else if (e.event === "RUN_TERMINAL") {
+      terminalCount++;
+      if (firstTerminal === null) { firstTerminal = e.seq; terminalReason = e.reason; }
+    }
+  }
+
+  return rules.map((r) => {
+    try {
+      return evaluateOneRule(r, { phaseCommits, firstTerminal, terminalCount, terminalReason });
+    } catch {
+      return { ok: true, id: r.id }; // evaluator error → fail-open
+    }
+  });
+}
+
+function evaluateOneRule(rule, { phaseCommits, firstTerminal, terminalCount, terminalReason }) {
+  switch (rule.id) {
+    case "review_precedes_merge": {
+      // Only check when the run ended with 'merged'.
+      if (terminalReason !== "merged") return { ok: true, id: rule.id };
+      const reviewSeq = phaseCommits["review"] ?? null;
+      if (reviewSeq === null || (firstTerminal !== null && reviewSeq > firstTerminal)) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `RUN_TERMINAL(merged) at seq ${firstTerminal} but no PHASE_COMMIT(review) precedes it`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    case "gate_event_precedes_review": {
+      const buildSeq = phaseCommits["build"] ?? null;
+      const reviewSeq = phaseCommits["review"] ?? null;
+      if (reviewSeq !== null && (buildSeq === null || buildSeq > reviewSeq)) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `PHASE_COMMIT(review) at seq ${reviewSeq} but PHASE_COMMIT(build) ${buildSeq === null ? "absent" : `at seq ${buildSeq} (after review)`}`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    case "terminal_state_once": {
+      if (terminalCount > 1) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `RUN_TERMINAL appears ${terminalCount} times in run-log (expected ≤1)`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    default:
+      // Unknown runlog invariant ID — fail-open (future invariants not yet in evaluator).
+      return { ok: true, id: rule.id };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook precondition checks (async — may shell out for git ls-remote)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a named pretooluse-scope precondition.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {string}      id         Invariant ID to evaluate.
+ * @param {object}      context    Evaluation context (e.g. { branch, repoPath }).
+ * @returns {Promise<InvariantResult>}
+ */
+export async function checkPrecondition(invariants, id, context) {
+  const inv = invariants.find((i) => i.scope === "pretooluse" && i.id === id);
+  if (!inv) return { ok: true, id }; // not declared — fail-open
+
+  try {
+    return await evaluateOnePrecondition(inv, context);
+  } catch {
+    return { ok: true, id }; // evaluator error → fail-open
+  }
+}
+
+/**
+ * Evaluate all pretooluse-scope preconditions matching a named context.
+ * Returns all results so the caller can surface the first failure.
+ *
+ * @param {Invariant[]} invariants
+ * @param {object}      context
+ * @returns {Promise<InvariantResult[]>}
+ */
+export async function checkAllPreconditions(invariants, context) {
+  const rules = invariants.filter((i) => i.scope === "pretooluse");
+  const results = [];
+  for (const r of rules) {
+    try {
+      results.push(await evaluateOnePrecondition(r, context));
+    } catch {
+      results.push({ ok: true, id: r.id }); // fail-open
+    }
+  }
+  return results;
+}
+
+async function evaluateOnePrecondition(inv, context) {
+  switch (inv.id) {
+    case "branch_must_exist_on_remote": {
+      const branch = context?.branch;
+      if (!branch) return { ok: true, id: inv.id }; // no branch in context — skip
+
+      // git ls-remote --exit-code: exits 0 if ref found, 2 if not found.
+      // Use a cached local-only check first (avoids network round-trip when
+      // the branch is already fetched).
+      try {
+        execFileSync("git", ["rev-parse", "--verify", `origin/${branch}`], {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 5000,
+        });
+        return { ok: true, id: inv.id }; // local origin ref exists
+      } catch {
+        // Not in local refs — fall through to remote check.
+      }
+
+      try {
+        const url = getRemoteUrl();
+        if (!url) return { ok: true, id: inv.id }; // no remote configured — fail-open
+
+        execFileSync("git", ["ls-remote", "--exit-code", "origin", branch], {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 10000,
+        });
+        return { ok: true, id: inv.id }; // remote ref found
+      } catch (e) {
+        const exitCode = e?.status ?? null;
+        if (exitCode === 2) {
+          // Exit code 2 from ls-remote means ref not found.
+          return {
+            ok: false, id: inv.id,
+            violated: inv.proposition,
+            detail: `Branch '${branch}' not found on origin — checkout would fail`,
+          };
+        }
+        // Other errors (network, auth, etc.) → fail-open.
+        return { ok: true, id: inv.id };
+      }
+    }
+
+    default:
+      return { ok: true, id: inv.id }; // unknown precondition — fail-open
+  }
+}
+
+function getRemoteUrl() {
+  try {
+    return execFileSync("git", ["remote", "get-url", "origin"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Close-time assertions (synchronous — run-log only, no I/O)
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert close-scope invariants before the trajectory annotation is posted.
+ * These run in the close phase after the PR is merged and issue is closed.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {object[]}    events      Event list from readLog().
+ * @returns {InvariantResult[]}
+ */
+export function assertCloseInvariants(invariants, events) {
+  const assertions = invariants.filter((i) => i.scope === "close");
+  if (!assertions.length) return [];
+
+  return assertions.map((a) => {
+    try {
+      return evaluateOneCloseAssertion(a, events);
+    } catch {
+      return { ok: true, id: a.id }; // evaluator error → fail-open
+    }
+  });
+}
+
+function evaluateOneCloseAssertion(assertion, events) {
+  switch (assertion.id) {
+    case "run_log_terminal_at_close": {
+      const hasTerminal = events.some((e) => e.event === "RUN_TERMINAL");
+      if (!hasTerminal) {
+        return {
+          ok: false, id: assertion.id,
+          violated: assertion.proposition,
+          detail: "RUN_TERMINAL event absent from run-log — pipeline may have exited abnormally",
+        };
+      }
+      return { ok: true, id: assertion.id };
+    }
+
+    case "issue_closed_at_terminal":
+      // This assertion is evaluated externally (requires a gh CLI call in the
+      // close phase). The evaluator returns ok=true here so callers that do
+      // not pass GitHub state still pass without error. The close.md phase
+      // block implements the actual gh issue view check.
+      return { ok: true, id: assertion.id };
+
+    default:
+      return { ok: true, id: assertion.id }; // unknown close assertion — fail-open
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: format a violation for human output
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a failed InvariantResult into a human-readable block.
+ * Safe to call on ok:true results (returns null).
+ *
+ * @param {InvariantResult} result
+ * @returns {string|null}
+ */
+export function formatViolation(result) {
+  if (result.ok) return null;
+  return [
+    `[ForgeDock] INVARIANT VIOLATION: ${result.id}`,
+    ``,
+    `Violated proposition: "${result.violated}"`,
+    result.detail ? `Detail: ${result.detail}` : "",
+  ].filter((l) => l !== undefined).join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// JSDoc types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ id: string, scope: string, proposition: string, enforcement: string, description?: string }} Invariant
+ * @typedef {{ ok: boolean, id: string, violated?: string, detail?: string }} InvariantResult
+ */

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