@imdeadpool/guardex 7.0.43 → 7.1.0

package/src/context.js

@@ -138,9 +138,6 @@ function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('github/')) {
     return `.${relativeTemplatePath}`;
   }
-  if (relativeTemplatePath.startsWith('vscode/')) {
-    return relativeTemplatePath;
-  }
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
@@ -153,7 +150,7 @@ function toDestinationPath(relativeTemplatePath) {
 //    replaced with a regular file. Edit only the templates/scripts/ copy;
 //    the symlink propagates.
 //
-// 2. SCAFFOLD-ONLY files (the 4 below + workflows + vscode extension):
+// 2. SCAFFOLD-ONLY files (the 3 below + workflows):
 //    tracked only under templates/; scaffolded into gitignored
 //    scripts/<file> (or .githooks/<file>, etc.) by `gx setup`. Consumer
 //    repos receive a regular file copy at the destination; gitguardex
@@ -165,7 +162,6 @@ function toDestinationPath(relativeTemplatePath) {
 // pattern (2), append the destination path to .gitignore's multiagent-
 // safety block (auto-managed by syncManagedGitignoreLines below).
 const TEMPLATE_FILES = [
-  'scripts/agent-session-state.js',
   'scripts/agent-preflight.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
@@ -176,9 +172,7 @@ const TEMPLATE_FILES = [
   'github/workflows/README.md',
 ];
 
-const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set([
-  'scripts/agent-session-state.js',
-]);
+const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set();
 
 const LEGACY_WORKFLOW_SHIM_SPECS = [
   { relativePath: 'scripts/agent-branch-start.sh', kind: 'shell', command: ['branch', 'start'] },
@@ -201,7 +195,6 @@ const MANAGED_TEMPLATE_SCRIPT_FILES = MANAGED_TEMPLATE_DESTINATIONS.filter((entr
 
 const LEGACY_MANAGED_REPO_FILES = [
   ...LEGACY_WORKFLOW_SHIMS,
-  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
@@ -251,7 +244,6 @@ const PACKAGE_SCRIPT_ASSETS = {
   branchMerge: path.join(TEMPLATE_ROOT, 'scripts', 'agent-branch-merge.sh'),
   codexAgent: path.join(TEMPLATE_ROOT, 'scripts', 'codex-agent.sh'),
   reviewBot: path.join(TEMPLATE_ROOT, 'scripts', 'review-bot-watch.sh'),
-  sessionState: path.join(TEMPLATE_ROOT, 'scripts', 'agent-session-state.js'),
   worktreePrune: path.join(TEMPLATE_ROOT, 'scripts', 'agent-worktree-prune.sh'),
   lockTool: path.join(TEMPLATE_ROOT, 'scripts', 'agent-file-locks.py'),
   planInit: path.join(TEMPLATE_ROOT, 'scripts', 'openspec', 'init-plan-workspace.sh'),
@@ -288,6 +280,8 @@ const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
 const AGENTS_BOTS_STATE_RELATIVE = '.omx/state/agents-bots.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
 const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
+const MONOREPO_MARKER_START = '<!-- monorepo-apps:START -->';
+const MONOREPO_MARKER_END = '<!-- monorepo-apps:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
 const GITIGNORE_MARKER_END = '# multiagent-safety:END';
 const CODEX_WORKTREE_RELATIVE_DIR = path.join('.omx', 'agent-worktrees');
@@ -315,7 +309,6 @@ const MANAGED_GITIGNORE_PATHS = [
   '!.vscode/',
   '.vscode/*',
   '!.vscode/settings.json',
-  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
   '.githooks',
@@ -389,6 +382,7 @@ const SUGGESTIBLE_COMMANDS = [
   'release',
   'budget',
   'ci-init',
+  'speckit',
 ];
 // CLI_COMMAND_GROUPS is the grouped source of truth the `gx --help` /
 // `gx` no-args renderer uses. Each group is ordered roughly by how often a
@@ -437,6 +431,7 @@ const CLI_COMMAND_GROUPS = [
       ['pr-review', 'Run local Codex/Claude PR review and post inline GitHub comments or write an artifact'],
       ['cockpit', 'Create or attach to a repo tmux cockpit session'],
       ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
+      ['speckit', 'Install Spec Kit (specify-cli) SDD slash skills (/speckit-specify, /speckit-plan, ...) into the current repo'],
       ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
       ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
       ['release', 'Create or update the current GitHub release with README-generated notes'],
@@ -700,11 +695,232 @@ const SCORECARD_RISK_BY_CHECK = {
   License: 'Low',
 };
 
+// ---------------------------------------------------------------------------
+// Process-scoped memoization for idempotent git/gh probes.
+//
+// Many gx commands (notably `gx doctor`, `gx status`, preflight checks) ask
+// git/gh the same read-only questions multiple times within a single Node
+// process (current branch, remote URL, worktree list, config values, PR
+// state). spawnSync is cheap individually but adds up across 20+ probes.
+//
+// Rules:
+//   * Cache only idempotent reads. Strict allowlist below.
+//   * Never cache writes, network mutations, or anything passing stdin.
+//   * Lifetime = this Node process only (no disk cache, no TTL beyond the
+//     process). A fresh `gx ...` invocation always starts cold.
+//   * Honors GUARDEX_PROBE_TRACE=1 to print `[probe]` / `[probe-hit]` lines
+//     on stderr so duplicate calls are observable.
+//   * Honors GUARDEX_PROBE_CACHE=0 to disable the cache entirely
+//     (escape hatch).
+// ---------------------------------------------------------------------------
+
+const PROBE_CACHE = new Map();
+const PROBE_TRACE_ENABLED = (() => {
+  const raw = String(process.env.GUARDEX_PROBE_TRACE || '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+})();
+const PROBE_CACHE_DISABLED = (() => {
+  const raw = String(process.env.GUARDEX_PROBE_CACHE || '').trim().toLowerCase();
+  return raw === '0' || raw === 'false' || raw === 'no' || raw === 'off';
+})();
+
+// Env vars that, if they differ between calls, must invalidate cache (because
+// they change git/gh's actual answer). Most env doesn't matter for read probes
+// so we deliberately key only on a small slice to keep cache hits high.
+const PROBE_CACHE_ENV_KEYS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GITHUB_TOKEN',
+  'GH_TOKEN',
+  'GH_HOST',
+];
+
+function envSubsetKey(envOverride) {
+  const env = envOverride || process.env;
+  const parts = [];
+  for (const key of PROBE_CACHE_ENV_KEYS) {
+    if (env[key] !== undefined) parts.push(`${key}=${env[key]}`);
+  }
+  return parts.join('');
+}
+
+// Strip a leading `-C <path>` (or `-c key=value`) pair from git args so we
+// look at the real verb after global options.
+function gitVerbAndRest(args) {
+  if (!Array.isArray(args) || args.length === 0) return { verb: '', rest: [] };
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '-C' && i + 1 < args.length) {
+      i += 2;
+      continue;
+    }
+    if (a === '-c' && i + 1 < args.length) {
+      i += 2;
+      continue;
+    }
+    if (typeof a === 'string' && a.startsWith('-c') && a !== '-c') {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  return { verb: args[i] || '', rest: args.slice(i + 1) };
+}
+
+// A git command is cacheable only if its answer is invariant for the lifetime
+// of the process under our own commands' behavior. Many git "reads"
+// (`status`, `diff`, `for-each-ref`, `rev-list`, `ls-files`, `worktree list`,
+// `branch --show-current`, `merge-base --is-ancestor`) can change mid-run
+// because gx itself writes (commits, branch ops, worktree add/remove, config
+// writes). Caching those would feed callers stale answers and break command
+// flows. The narrow allowlist below intentionally covers only:
+//   * filesystem geometry that git itself treats as fixed for a given repo
+//     checkout (`rev-parse --show-toplevel|--git-common-dir|--git-dir|
+//     --show-cdup|--show-superproject-working-tree|--is-inside-work-tree|
+//     --is-bare-repository`)
+//   * tool version banners (`--version`)
+// Everything else falls through to a real spawn each time.
+function gitIsCacheableRead(args) {
+  const { verb, rest } = gitVerbAndRest(args);
+  if (!verb) return false;
+
+  if (verb === '--version' || verb === 'version') return true;
+
+  if (verb === 'rev-parse') {
+    // Allow ONLY the geometry-probe forms whose answer never depends on the
+    // working-tree, ref state, or config. Concrete ref resolution
+    // (`rev-parse HEAD`, `rev-parse --verify <ref>`) is intentionally NOT
+    // cached because gx writes refs.
+    for (const a of rest) {
+      if (typeof a !== 'string') continue;
+      if (a.startsWith('-')) {
+        if (
+          a === '--show-toplevel' ||
+          a === '--git-common-dir' ||
+          a === '--git-dir' ||
+          a === '--show-cdup' ||
+          a === '--show-superproject-working-tree' ||
+          a === '--is-inside-work-tree' ||
+          a === '--is-inside-git-dir' ||
+          a === '--is-bare-repository' ||
+          a === '--show-prefix'
+        ) {
+          // continue scanning to make sure no ref-probe is also present
+          continue;
+        }
+        // Any other flag (--verify, --short, --abbrev-ref, etc.) means we're
+        // resolving a ref, which is mutable.
+        return false;
+      }
+      // Bare positional (e.g. a ref name) -> ref resolution, mutable.
+      return false;
+    }
+    return rest.length > 0;
+  }
+  return false;
+}
+
+// gh probes that ARE safe to cache within a single process: only the version
+// banner. Auth state can change (login/logout in another shell), PR state
+// can change (a merge can land mid-poll). The instruction's allowlist
+// included `gh auth status`, `gh api -X GET`, `gh pr view --json`, etc.;
+// those are read-only from gh's side but their underlying truth shifts under
+// gx's own writes (`gh pr create`, `gh pr merge`, `gh auth refresh`, server
+// state). Within a single doctor sweep we explicitly want to re-query auth
+// and PR state, so caching them would mask freshly-changed reality.
+function ghIsCacheableRead(args) {
+  if (!Array.isArray(args) || args.length === 0) return false;
+  const verb = args[0] || '';
+  if (verb === '--version' || verb === 'version') return true;
+  return false;
+}
+
+function isCacheableSpawn(cmd, args, options) {
+  if (PROBE_CACHE_DISABLED) return false;
+  if (!cmd || typeof cmd !== 'string') return false;
+  if (options && options.input !== undefined && options.input !== null) return false;
+  // Pass-through if stdio is anything other than fully pipe/ignore (callers
+  // that inherit stdio need the real child to print, not a cached payload).
+  if (options && options.stdio && options.stdio !== 'pipe' && options.stdio !== 'ignore') {
+    if (Array.isArray(options.stdio)) {
+      for (const leg of options.stdio) {
+        if (leg && leg !== 'pipe' && leg !== 'ignore' && leg !== null) return false;
+      }
+    } else {
+      return false;
+    }
+  }
+  const base = path.basename(cmd);
+  if (base === 'git') return gitIsCacheableRead(args || []);
+  if (base === 'gh' || base === 'ghx') return ghIsCacheableRead(args || []);
+  if (base === 'which' || base === 'command' || base === 'type') {
+    return Array.isArray(args) && args.length >= 1;
+  }
+  return false;
+}
+
+function probeTrace(prefix, cmd, args) {
+  if (!PROBE_TRACE_ENABLED) return;
+  try {
+    process.stderr.write(`[${prefix}] ${cmd} ${(args || []).join(' ')}\n`);
+  } catch {
+    // Tracing must never break the probe.
+  }
+}
+
+function cachedSpawn(cmd, args, options) {
+  const cacheable = isCacheableSpawn(cmd, args, options);
+  if (!cacheable) {
+    probeTrace('probe', cmd, args);
+    return cp.spawnSync(cmd, args, options);
+  }
+  const cwdKey = (options && options.cwd) || process.cwd();
+  const envKey = options && options.env
+    ? envSubsetKey({ ...process.env, ...options.env })
+    : envSubsetKey(process.env);
+  const key = `${cmd} ${JSON.stringify(args || [])} ${cwdKey} ${envKey}`;
+  const cached = PROBE_CACHE.get(key);
+  if (cached) {
+    probeTrace('probe-hit', cmd, args);
+    // Clone so callers that mutate the result don't poison the cache.
+    return {
+      pid: cached.pid,
+      status: cached.status,
+      signal: cached.signal,
+      stdout: cached.stdout,
+      stderr: cached.stderr,
+      output: cached.output ? cached.output.slice() : cached.output,
+      error: cached.error,
+    };
+  }
+  probeTrace('probe', cmd, args);
+  const result = cp.spawnSync(cmd, args, options);
+  // Don't cache spawn errors (ENOENT etc.) — they may resolve on retry with a
+  // different binary path.
+  if (result && result.error) {
+    return result;
+  }
+  PROBE_CACHE.set(key, {
+    pid: result && result.pid,
+    status: result && result.status,
+    signal: result && result.signal,
+    stdout: result && result.stdout,
+    stderr: result && result.stderr,
+    output: result && result.output,
+    error: result && result.error,
+  });
+  return result;
+}
+
 module.exports = {
   fs,
   os,
   path,
   cp,
+  cachedSpawn,
   PACKAGE_ROOT,
   CLI_ENTRY_PATH,
   packageJsonPath,
@@ -758,6 +974,8 @@ module.exports = {
   AGENTS_BOTS_STATE_RELATIVE,
   AGENTS_MARKER_START,
   AGENTS_MARKER_END,
+  MONOREPO_MARKER_START,
+  MONOREPO_MARKER_END,
   GITIGNORE_MARKER_START,
   GITIGNORE_MARKER_END,
   CODEX_WORKTREE_RELATIVE_DIR,

package/src/core/runtime.js

@@ -1,6 +1,7 @@
 const {
   fs,
   path,
+  cachedSpawn,
   CLI_ENTRY_PATH,
   PACKAGE_SCRIPT_ASSETS,
 } = require('../context');
@@ -13,8 +14,12 @@ function requireValue(rawArgs, index, flagName) {
   return value;
 }
 
+// Route reads through the process-scoped probe cache. cachedSpawn caches ONLY a
+// strict allowlist (git geometry probes, git/gh `--version`, `which`) and falls
+// through to a real spawn for everything else — writes, ref resolution, npm,
+// gh auth/pr — so observable behavior is unchanged, only redundant probes drop.
 function run(cmd, args, options = {}) {
-  return require('node:child_process').spawnSync(cmd, args, {
+  return cachedSpawn(cmd, args, {
     encoding: 'utf8',
     stdio: options.stdio || 'pipe',
     cwd: options.cwd,

package/src/doctor/index.js

@@ -1,6 +1,7 @@
 const {
   fs,
   path,
+  cachedSpawn,
   TOOL_NAME,
   SHORT_TOOL_NAME,
   GH_BIN,
@@ -11,7 +12,23 @@ const {
   AGENT_WORKTREE_RELATIVE_DIRS,
   defaultAgentWorktreeRelativeDir,
 } = require('../context');
-const { run, runPackageAsset } = require('../core/runtime');
+const { runPackageAsset } = require('../core/runtime');
+
+// Route doctor probe-running calls through the process-scoped probe cache.
+// cachedSpawn falls through to cp.spawnSync for any non-allowlisted call
+// (git commit/push/stash/checkout, gh auth login, etc.), so writes are never
+// cached. Doctor fires the same read questions many times within one run
+// (current branch, remote URL, worktree list, gh auth status) — caching
+// those is a pure perf win.
+function run(cmd, args, options = {}) {
+  return cachedSpawn(cmd, args, {
+    encoding: 'utf8',
+    stdio: options.stdio || 'pipe',
+    cwd: options.cwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    timeout: options.timeout,
+  });
+}
 const {
   currentBranchName,
   gitRefExists,
@@ -31,7 +48,7 @@ const {
   cleanupProtectedBaseSandbox,
 } = require('../sandbox');
 const { ensureOmxScaffold, configureHooks } = require('../scaffold');
-const { detectRecoverableAutoFinishConflict, printAutoFinishSummary } = require('../output');
+const { detectRecoverableAutoFinishConflict, printAutoFinishSummary, isTerseMode } = require('../output');
 const { autoCommitWorktreeForFinish } = require('../finish');
 
 /**
@@ -101,6 +118,7 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
+  if (options.contract) args.push('--contract');
   if (!options.dropStaleLocks) args.push('--keep-stale-locks');
   args.push(options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
   if (options.verboseAutoFinish) args.push('--verbose-auto-finish');
@@ -1152,6 +1170,7 @@ function emitDoctorSandboxJsonOutput(nestedResult, execution) {
 }
 
 function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult, nestedResult, execution) {
+  const terse = isTerseMode();
   console.log(
     `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
     `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
@@ -1164,6 +1183,10 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     return;
   }
 
+  // Terse mode: drop "[OK] X skipped because of Y" / "already in sync"
+  // confirmations. Keep committed/failed/pending/merged states verbose so
+  // operators still see action-required hints, PR URLs, branch names, and
+  // file paths.
   if (execution.autoCommit.status === 'committed') {
     console.log(
       `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
@@ -1172,22 +1195,24 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit failed; branch left for manual follow-up.`);
     if (execution.autoCommit.stdout) process.stdout.write(execution.autoCommit.stdout);
     if (execution.autoCommit.stderr) process.stderr.write(execution.autoCommit.stderr);
-  } else {
+  } else if (!terse) {
     console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${execution.autoCommit.note}.`);
   }
 
   if (execution.protectedBaseRepairSync.status === 'merged') {
     console.log(`[${TOOL_NAME}] Fast-forwarded tracked doctor repairs into the protected branch workspace.`);
-  } else if (execution.protectedBaseRepairSync.status === 'unchanged') {
-    console.log(`[${TOOL_NAME}] Protected branch workspace already had the tracked doctor repairs.`);
   } else if (execution.protectedBaseRepairSync.status === 'would-merge') {
     console.log(`[${TOOL_NAME}] Dry run: would fast-forward tracked doctor repairs into the protected branch workspace.`);
   } else if (execution.protectedBaseRepairSync.status === 'failed') {
     console.log(`[${TOOL_NAME}] Protected branch tracked repair merge failed: ${execution.protectedBaseRepairSync.note}.`);
     if (execution.protectedBaseRepairSync.stdout) process.stdout.write(execution.protectedBaseRepairSync.stdout);
     if (execution.protectedBaseRepairSync.stderr) process.stderr.write(execution.protectedBaseRepairSync.stderr);
-  } else {
-    console.log(`[${TOOL_NAME}] Protected branch tracked repair merge skipped: ${execution.protectedBaseRepairSync.note}.`);
+  } else if (!terse) {
+    if (execution.protectedBaseRepairSync.status === 'unchanged') {
+      console.log(`[${TOOL_NAME}] Protected branch workspace already had the tracked doctor repairs.`);
+    } else {
+      console.log(`[${TOOL_NAME}] Protected branch tracked repair merge skipped: ${execution.protectedBaseRepairSync.note}.`);
+    }
   }
 
   if (execution.lockSync.status === 'synced') {
@@ -1195,8 +1220,10 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
       `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
     );
   } else if (execution.lockSync.status === 'unchanged') {
+    // Kept verbose in terse mode too: downstream consumers (and tests) rely
+    // on seeing the lock-registry sync stage reach a terminal state line.
     console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
-  } else {
+  } else if (!terse) {
     console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${execution.lockSync.note}.`);
   }
 
@@ -1217,7 +1244,7 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
     if (execution.finish.stdout) process.stdout.write(execution.finish.stdout);
     if (execution.finish.stderr) process.stderr.write(execution.finish.stderr);
-  } else {
+  } else if (!terse) {
     console.log(`[${TOOL_NAME}] Auto-finish skipped: ${execution.finish.note}.`);
   }
 
@@ -1227,12 +1254,14 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
   });
   if (execution.omxScaffoldSync.status === 'synced') {
     console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
-  } else if (execution.omxScaffoldSync.status === 'unchanged') {
-    console.log(`[${TOOL_NAME}] .omx scaffold already aligned in protected branch workspace.`);
   } else if (execution.omxScaffoldSync.status === 'would-sync') {
     console.log(`[${TOOL_NAME}] Dry run: would sync .omx scaffold back to protected branch workspace.`);
-  } else {
-    console.log(`[${TOOL_NAME}] .omx scaffold sync skipped: ${execution.omxScaffoldSync.note}.`);
+  } else if (!terse) {
+    if (execution.omxScaffoldSync.status === 'unchanged') {
+      console.log(`[${TOOL_NAME}] .omx scaffold already aligned in protected branch workspace.`);
+    } else {
+      console.log(`[${TOOL_NAME}] .omx scaffold sync skipped: ${execution.omxScaffoldSync.note}.`);
+    }
   }
 }