@opengsd/gsd-core 1.13.0 → 1.15.0

package/scripts/release-tarball-smoke.cjs

@@ -37,6 +37,12 @@
  *     colon-namespace leaks (WORKFLOW_BODY_COLON_LEAK).
  *   This check populates result.details with counters but does NOT return a
  *   failure code by default; it is informational until enforcement is enabled.
+ *
+ * Configured-entrypoint checks (Cycle 4 — #4154):
+ *   For each runtime in entrypointRuntimes, runs the tarball-installed
+ *   installer into a throwaway HOME, then re-reads that runtime's own written
+ *   config files and asserts every GSD-managed script path they name resolves
+ *   to a file (ENTRYPOINT_UNRESOLVED). Requires fixtureDir.
  */
 
 'use strict';
@@ -47,6 +53,8 @@ const os = require('os');
 const path = require('path');
 const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const shellCmdProjection = require('../gsd-core/bin/lib/shell-command-projection.cjs');
+const { escapeRegex } = require('../gsd-core/bin/lib/pattern.cjs');
 // 120 s proved too tight for cold-cache `npm install -g` of a 1499-file tarball:
 // spawnSync fires SIGTERM at the deadline and returns { status: null, stdout: '',
 // stderr: '' } (Node docs: status is null when a subprocess is terminated by a
@@ -86,6 +94,8 @@ const SMOKE = Object.freeze({
   INIT_FAILED: 'init_failed',
   // Cycle 3 code
   WORKFLOW_BODY_COLON_LEAK: 'workflow_body_colon_leak',
+  // Cycle 4 code (#4154)
+  ENTRYPOINT_UNRESOLVED: 'entrypoint_unresolved',
 });
 
 // ---------------------------------------------------------------------------
@@ -274,6 +284,106 @@ function scanWorkflowColonLeak(filePath, cmdNames) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Cycle 4 helpers: configured-entrypoint resolution (#4154)
+// ---------------------------------------------------------------------------
+
+/**
+ * Top-level config files this scan reads. These are the surfaces that carry
+ * every GSD-managed launch path for the runtimes Cycle 4 actually installs
+ * (`entrypointRuntimes`, default claude + codex): claude registers into
+ * settings.json, codex into hooks.json and config.toml.
+ *
+ * This is NOT an exhaustive map of where GSD writes launch paths across all
+ * runtimes, and the scan is top-level only by design. Two known surfaces sit
+ * outside it: Cline registers its hook at `.clinerules/hooks/PreToolUse` (a
+ * subdirectory, and not one of these names — see writeClineArtifacts in
+ * src/runtime-hooks-surface.cts), and Kimi's native `[[hooks]]` config.toml
+ * lives under `resolveKimiHooksTomlDir()` (`~/.kimi`), a directory separate
+ * from Kimi's own GSD configDir. Adding either runtime to entrypointRuntimes
+ * requires teaching scanConfiguredEntrypoints about its surface first,
+ * otherwise the scan reports zero entrypoints and silently proves nothing.
+ */
+const RUNTIME_CONFIG_FILES = Object.freeze(['settings.json', 'hooks.json', 'config.toml']);
+
+/**
+ * Extract every script path `text` names underneath `configDir`.
+ *
+ * #4249 (antigravity review): anchored on the literal, already-known
+ * `configDir` prefix instead of a generic "any absolute path" character
+ * class. The prior version excluded whitespace from the match to avoid
+ * swallowing a shell command's trailing args, which also truncated any
+ * legitimate path containing a space (e.g. `/Users/John Doe/.claude`) —
+ * `scanConfiguredEntrypoints` would then silently report zero checked
+ * paths. Anchoring on `configDir` removes the ambiguity outright: a match
+ * can only start where the known prefix literally occurs in the text, so
+ * an interpreter path concatenated ahead of it (`"/usr/bin/node
+ * /configDir/hooks/foo.js"`) is never swallowed either, and interior
+ * whitespace inside `configDir` or the script's own path segments is safe
+ * to allow. This still scans raw, unparsed config text on purpose (see
+ * scanConfiguredEntrypoints's doc comment) — it catches a writer that
+ * embeds a launch path without registering it, which a structured
+ * JSON.parse of the expected schema would miss entirely.
+ *
+ * Windows configs store paths with backslashes, which JSON/TOML doubles on
+ * write; collapsing `\\` to `\` first makes the raw text scan work on both
+ * platforms without parsing each config format separately (POSIX text has no
+ * backslashes, so the collapse is a no-op there).
+ *
+ * Every writer bakes `configDir` through the same posixNormalize seam
+ * (src/runtime-hooks-surface.cts) before writing it into config text, on
+ * every platform — so the anchor must match that projection, not the
+ * OS-native `configDir` string this function receives.
+ */
+function configuredEntrypointsIn(text, configDir) {
+  const normalizedPrefix = shellCmdProjection.posixNormalize(configDir).replace(/\/+$/, '') + '/';
+  const scriptPathRe = new RegExp(`${escapeRegex(normalizedPrefix)}[^"']{0,400}?\\.(?:js|cjs|mjs|sh|cmd|ps1)`, 'g');
+  const found = new Set();
+  for (const match of text.replace(/\\\\/g, '\\').matchAll(scriptPathRe)) {
+    found.add(path.resolve(match[0]));
+  }
+  return [...found];
+}
+
+/**
+ * Throwaway HOME the Cycle 4 install for `runtime` runs against. Exported so a
+ * test can seed that runtime's config before the install rather than
+ * hard-coding the layout runSmoke picks.
+ */
+function entrypointFixtureHome(fixtureDir, runtime) {
+  return path.join(fixtureDir, `entrypoints-${runtime}`);
+}
+
+/**
+ * Re-derive the configured entrypoints a completed install wrote into a
+ * runtime's own config files and report the ones that do not resolve to a
+ * file. Internal to Cycle 4; the smoke's verdict is the exported contract.
+ *
+ * This deliberately does NOT consult the installer's own entrypoint list (the
+ * assertConfiguredEntrypoints gate in bin/install.js). That gate can only
+ * validate paths a config writer remembered to register; reading the written
+ * config back is what catches a writer that emits a launch path without
+ * registering it, and a stale registration an install left behind.
+ *
+ * @param {string} configDir - Absolute path to the runtime config dir.
+ * @returns {{ checked: string[], unresolved: { configPath: string, scriptPath: string }[] }}
+ */
+function scanConfiguredEntrypoints(configDir) {
+  const checked = [];
+  const unresolved = [];
+  for (const name of RUNTIME_CONFIG_FILES) {
+    const configPath = path.join(configDir, name);
+    if (!fs.existsSync(configPath) || !fs.statSync(configPath).isFile()) continue;
+    const text = fs.readFileSync(configPath, 'utf-8');
+    for (const scriptPath of configuredEntrypointsIn(text, configDir)) {
+      checked.push(scriptPath);
+      if (fs.existsSync(scriptPath) && fs.statSync(scriptPath).isFile()) continue;
+      unresolved.push({ configPath, scriptPath });
+    }
+  }
+  return { checked, unresolved };
+}
+
 // ---------------------------------------------------------------------------
 // Pure function: runSmoke
 // ---------------------------------------------------------------------------
@@ -285,6 +395,8 @@ function scanWorkflowColonLeak(filePath, cmdNames) {
  * @param {string}   opts.expectedVersion    - semver string to assert (e.g. "1.50.0")
  * @param {string}   [opts.fixtureDir]       - Temp dir to run `init` into (must NOT be HOME)
  * @param {string[]} [opts.lifecycleCommands] - Commands to file-check (default: see below)
+ * @param {string[]} [opts.entrypointRuntimes] - Runtime profiles whose configured entrypoints are
+ *   re-checked after a real install (default: see below). Requires fixtureDir; pass [] to skip.
  * @param {boolean}  [opts.dryRun=false]     - If true, skip actual npm install; validate input only
  * @param {object}   [opts.npmEnv]           - Optional env dict for the internal npm install
  *   spawnSync call. Pass an isolated HOME env (e.g. from isolatedNpmEnv() in tests/helpers.cjs)
@@ -298,6 +410,11 @@ function runSmoke({
   expectedVersion,
   fixtureDir,
   lifecycleCommands = ['init', 'discuss-phase', 'plan-phase', 'execute-phase'],
+  // claude and codex cover the two top-level config surfaces this scan knows
+  // how to read (settings.json, and hooks.json + config.toml). Most other
+  // runtimes reuse one of those two shapes; Cline and Kimi do not (see
+  // RUNTIME_CONFIG_FILES), so they are out of scope here rather than covered.
+  entrypointRuntimes = ['claude', 'codex'],
   dryRun = false,
   npmEnv = undefined,
 }) {
@@ -551,6 +668,75 @@ function runSmoke({
   // NOTE: colonLeakCount is informational here. Once the backlog is fixed,
   // a future enforcement mode can fail on non-zero counts.
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Cycle 4: configured-entrypoint resolution (#4154)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  // The installer's own gate (assertConfiguredEntrypoints) runs in-process and
+  // only sees the paths a config writer registered with it. Installing the
+  // packed tarball for real and reading each runtime's written config back is
+  // what proves the launch paths a user's runtime will actually invoke exist
+  // in the shipped layout.
+  const entrypointProfiles = [];
+  if (fixtureDir && entrypointRuntimes.length > 0) {
+    for (const runtime of entrypointRuntimes) {
+      // Own HOME per runtime so a --global install cannot reach the real one.
+      const runtimeHome = entrypointFixtureHome(fixtureDir, runtime);
+      const configDir = path.join(runtimeHome, `.${runtime}`);
+      fs.mkdirSync(runtimeHome, { recursive: true });
+
+      const installResult = spawnSync(
+        process.execPath,
+        [path.join(pkg, 'bin', 'install.js'), `--${runtime}`, '--global', '--config-dir', configDir],
+        {
+          encoding: 'utf-8',
+          cwd: runtimeHome,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: {
+            ...effectiveNpmEnv,
+            HOME: runtimeHome,
+            USERPROFILE: runtimeHome,
+            // Same reason as the init check above: install.js skips its main()
+            // block when GSD_TEST_MODE is set and would exit 0 writing nothing.
+            GSD_TEST_MODE: '',
+            NO_UPDATE_NOTIFIER: '1',
+          },
+          timeout: CHILD_TIMEOUT_MS,
+        },
+      );
+
+      if (installResult.status !== 0) {
+        // #4249 (antigravity review): this is the Cycle 4 per-runtime install,
+        // not Cycle 1's `gsd init` — SMOKE.INSTALL_FAILED is the code Cycle 2's
+        // identical spawnSync-failure check already uses for the same failure
+        // class; reusing SMOKE.INIT_FAILED here conflated the two lifecycle
+        // stages in the reported code.
+        return {
+          code: SMOKE.INSTALL_FAILED,
+          details: {
+            ...details,
+            runtime,
+            configDir,
+            stderr: installResult.stderr,
+            stdout: installResult.stdout,
+          },
+        };
+      }
+
+      const scan = scanConfiguredEntrypoints(configDir);
+      if (scan.unresolved.length > 0) {
+        return {
+          code: SMOKE.ENTRYPOINT_UNRESOLVED,
+          details: { ...details, runtime, configDir, unresolved: scan.unresolved },
+        };
+      }
+
+      entrypointProfiles.push({ runtime, configDir, entrypointsChecked: scan.checked.length });
+    }
+  }
+
+  details.entrypointProfiles = entrypointProfiles;
+
   return { code: SMOKE.OK, details };
 }
 
@@ -635,7 +821,14 @@ function cleanup(...dirs) {
 // Exports
 // ---------------------------------------------------------------------------
 
-module.exports = { SMOKE, runSmoke, binInvocation, CHILD_TIMEOUT_MS };
+module.exports = {
+  SMOKE,
+  runSmoke,
+  binInvocation,
+  entrypointFixtureHome,
+  CHILD_TIMEOUT_MS,
+  configuredEntrypointsIn,
+};
 
 if (require.main === module) {
   runMain(cliMain);

package/scripts/workflow-size.cjs

@@ -89,10 +89,149 @@ function measureWorkflows(dir = WORKFLOWS_DIR) {
   return measureMdFiles(dir);
 }
 
+/**
+ * #4261: the reserved margin, as a fraction of a tier's hard cap.
+ *
+ * The hard caps are red lines and stay exactly where they are. This is the
+ * second, softer level the caps never had: `execute-phase.md` already carries
+ * a hand-rolled version of this shape (a hard `< 93600` plus a `<= 93400`
+ * margin whose own message says it exists "so minor future edits don't
+ * re-trip the gate"), and it is the only capped file that does. Everywhere
+ * else a file is either fine or already over, with nothing in between — so
+ * the first signal a contributor gets is a failure, and by then the cheap
+ * moment to extract has passed.
+ *
+ * 95% is deliberately not derived from anything. It is the round number the
+ * issue proposed, and the census below is what makes it reviewable: if it
+ * turns out to name too many or too few files, that is visible in one table
+ * rather than argued from first principles.
+ */
+const MARGIN_RATIO = 0.95;
+
+/**
+ * The reserved-margin threshold for a hard cap, in bytes.
+ *
+ * Floor, not round: the margin must never land ON or above the cap it is
+ * meant to sit under, however small the cap.
+ *
+ * @param {number} cap - Tier hard cap in bytes.
+ * @returns {number} Margin threshold in bytes.
+ */
+function marginFor(cap) {
+  return Math.floor(cap * MARGIN_RATIO);
+}
+
+/**
+ * Build the headroom census for a set of measured files.
+ *
+ * Sorted by pressure (least headroom first) because that is the reading
+ * order that matters: the top row is the file that will break next.
+ *
+ * @param {Object<string, number>} sizes - Map of filename -> LF byte size.
+ * @param {function(string): {tier: string, cap: number}} capFor - Tier lookup, keyed by stem.
+ * @returns {Array<{name: string, tier: string, bytes: number, cap: number, margin: number, headroom: number, usedPct: number, overMargin: boolean}>}
+ */
+function buildHeadroomRows(sizes, capFor) {
+  return Object.entries(sizes)
+    .map(([file, bytes]) => {
+      const name = file.replace(/\.md$/, '');
+      const { tier, cap } = capFor(name);
+      const margin = marginFor(cap);
+      return {
+        name,
+        tier,
+        bytes,
+        cap,
+        margin,
+        headroom: cap - bytes,
+        usedPct: (bytes / cap) * 100,
+        overMargin: bytes > margin,
+      };
+    })
+    .sort((a, b) => a.headroom - b.headroom || a.name.localeCompare(b.name));
+}
+
+/**
+ * Render the census as a fixed-width text table for the test diagnostics.
+ *
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @param {{limit?: number}} [opts] - How many rows to render (default: all).
+ * @returns {string[]} Lines, ready to hand to `t.diagnostic` one at a time.
+ */
+function formatHeadroomTable(rows, { limit = Infinity } = {}) {
+  const shown = rows.slice(0, limit);
+  const width = Math.max(4, ...shown.map((r) => r.name.length));
+  const head = `${'file'.padEnd(width)}  ${'tier'.padEnd(7)}  ${'bytes'.padStart(7)}  ${'cap'.padStart(7)}  ${'margin'.padStart(7)}  ${'headroom'.padStart(8)}  ${'used'.padStart(6)}`;
+  const body = shown.map(
+    (r) =>
+      `${r.name.padEnd(width)}  ${r.tier.padEnd(7)}  ${String(r.bytes).padStart(7)}  ${String(r.cap).padStart(7)}  ${String(r.margin).padStart(7)}  ${String(r.headroom).padStart(8)}  ${r.usedPct.toFixed(1).padStart(5)}%`,
+  );
+  return [head, ...body];
+}
+
+/**
+ * Render the census as a GitHub job-summary markdown table.
+ *
+ * Only the rows over the reserved margin: a job summary that lists all 124
+ * capped files is a log dump nobody reads, and every row below the margin is
+ * by definition not the problem. The count of the rest is still reported so
+ * an empty table cannot be mistaken for an unmeasured one.
+ *
+ * @param {string} title - Section heading (e.g. `'Agent size headroom'`).
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @returns {string} Markdown block.
+ */
+function buildHeadroomSummaryMarkdown(title, rows) {
+  const pressured = rows.filter((r) => r.overMargin);
+  const lines = [`### ${title}`, ''];
+  if (pressured.length === 0) {
+    lines.push(`All ${rows.length} files are under the ${Math.round(MARGIN_RATIO * 100)}% reserved margin.`);
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push(
+    `**${pressured.length} of ${rows.length}** files are over the ${Math.round(MARGIN_RATIO * 100)}% reserved margin.`,
+    '',
+    '| file | tier | bytes | cap | headroom | used |',
+    '| --- | --- | ---: | ---: | ---: | ---: |',
+  );
+  for (const r of pressured) {
+    lines.push(`| \`${r.name}\` | ${r.tier} | ${r.bytes} | ${r.cap} | ${r.headroom} | ${r.usedPct.toFixed(1)}% |`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Append a census block to `$GITHUB_STEP_SUMMARY` when running in CI.
+ *
+ * No-op off CI, and never throws: this is reporting, and a test suite must
+ * not go red because a summary file was not writable.
+ *
+ * @param {string} title - Section heading.
+ * @param {ReturnType<typeof buildHeadroomRows>} rows
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean} Whether anything was written.
+ */
+function appendHeadroomStepSummary(title, rows, env = process.env) {
+  if (!env.GITHUB_STEP_SUMMARY) return false;
+  try {
+    fs.appendFileSync(env.GITHUB_STEP_SUMMARY, `${buildHeadroomSummaryMarkdown(title, rows)}\n`);
+    return true;
+  } catch (err) {
+    process.stderr.write(`workflow-size: could not write GITHUB_STEP_SUMMARY: ${err.message}\n`);
+    return false;
+  }
+}
+
 module.exports = {
   WORKFLOWS_DIR,
+  MARGIN_RATIO,
   lfByteCount,
   listWorkflowStems,
   measureMdFiles,
   measureWorkflows,
+  marginFor,
+  buildHeadroomRows,
+  formatHeadroomTable,
+  buildHeadroomSummaryMarkdown,
+  appendHeadroomStepSummary,
 };

package/skills/gsd-autonomous/SKILL.md

@@ -36,10 +36,10 @@ Optional flags:
 - `--to N` — stop after phase N completes (halt instead of advancing to next phase).
 - `--only N` — execute only phase N (single-phase mode).
 - `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
-- `--converge` — run each phase's planning step through `gsd-plan-review-convergence` instead of plain `gsd-plan-phase`. Requires `workflow.plan_review_convergence=true`.
+- `--converge` — run each phase's planning step through `gsd-plan-review-convergence` instead of plain `gsd-plan-phase`. Works even when `workflow.plan_review_convergence` is `false` — the explicit flag overrides the gate; the gate (`workflow.plan_review_convergence=true` enables it) governs the standalone `gsd-plan-review-convergence` command. Without the flag, planning runs `gsd-plan-phase`.
 - `--cross-ai` — compatibility alias for `--converge`.
 
-When `--converge` or `--cross-ai` is set, reviewer selector flags supported by `gsd-plan-review-convergence` may be passed through: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.
+When `--converge` or `--cross-ai` is set, reviewer selector flags supported by `gsd-plan-review-convergence` may be passed through: `--codex`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.
 
 Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools query init.milestone-op`, `gsd-tools query roadmap.analyze`). No upfront context loading needed.
 </context>

package/skills/gsd-capture/SKILL.md

@@ -32,7 +32,7 @@ Mode routing:
 | (none) | Structured todo in .planning/todos/ | add-todo |
 | --note | Timestamped note file, list, or promote | note |
 | --backlog | ROADMAP.md backlog section (999.x) | add-backlog |
-| --seed | .planning/seeds/SEED-NNN-slug.md | plant-seed |
+| --seed | .planning/seeds/SEED-YYMMDD-xxx-slug.md | plant-seed |
 | --list | Interactive todo browser + action router | check-todos |
 | --list-seeds | Read-only seed list/audit (optional status filter) | list-seeds |
 

package/skills/gsd-cleanup/SKILL.md

@@ -5,6 +5,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - AskUserQuestion
 ---
 

package/skills/gsd-code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-code-review
 description: "Review source files changed during a phase for bugs, security issues, and code quality problems"
-argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]"
+argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]] [reviewer-lane flags]"
 allowed-tools:
   - Read
   - Bash
@@ -26,6 +26,7 @@ Arguments:
 - `--fix` (optional) — after review completes (or if REVIEW.md already exists), auto-apply fixes found. Spawns gsd-code-fixer agent. Accepts sub-flags:
   - `--all` — include Info findings in fix scope (default: Critical + Warning only)
   - `--auto` — enable fix + re-review iteration loop, capped at 3 iterations
+- Optional reviewer-lane flags (#4209) — any flag returned by `gsd_run review-lane flags` (the canonical reviewer-lane roster; e.g. `--codex`, `--agy`) requests that lane independently review the same already-resolved scope alongside the internal `gsd-code-reviewer` agent. Its findings are corroborating evidence only — `gsd-code-reviewer` alone verifies each claim against the actual source and writes REVIEW.md; there is exactly one REVIEW.md schema. No reviewer-lane flag (the default) reviews with only the internal agent, byte-for-byte unchanged from before #4209.
 
 Output: {padded_phase}-REVIEW.md in phase directory + inline summary of findings
 </objective>

package/skills/gsd-complete-milestone/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
 ---
 
 

package/skills/gsd-config/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - AskUserQuestion
 ---
 

package/skills/gsd-debug/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - Agent
   - AskUserQuestion
 ---

package/skills/gsd-graphify/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[build|query <term>|status|diff]"
 allowed-tools:
   - Read
   - Bash
+  - Grep
 ---
 
 

package/skills/gsd-health/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[--repair] [--context]"
 allowed-tools:
   - Read
   - Bash
+  - Grep
   - Write
   - AskUserQuestion
 ---

package/skills/gsd-mempalace-capture/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[CONTEXT.md|PLAN.md|SUMMARY.md]"
 allowed-tools:
   - Read
   - Bash
+  - Grep
 ---
 
 
@@ -83,15 +84,19 @@ On any error or timeout, stop and let the phase continue -- capture is best-effo
    ROOM_DIR="$STAGE/<room>/<phase-id>"
    mkdir -p "$ROOM_DIR"
    cp "<artifact-path>" "$ROOM_DIR/<basename>"
-   # Mine with --wing only — no --room flag; detect_room() assigns from the folder path
-   mempalace mine "$STAGE" --wing <wing>
+   # Mine with --wing only — no --room flag; detect_room() assigns from the folder path.
+   # --daemon --background (#4700): MemPalace wraps every mine in a per-palace
+   # lock; a concurrent writer would make a foreground mine exit 1
+   # (MineAlreadyRunning) and this onError: skip step would silently drop the
+   # capture. The background queue defers the job until the lock frees.
+   mempalace mine "$STAGE" --wing <wing> --daemon --background
    ```
 3. **Mirror KG facts** unless `config.mempalace.mirror_kg === false` (registry default is true — an absent key means enabled): extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
 4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
 
 ## Step 4 -- Report
 
-Print a one-line summary: `Filed <artifact> → <wing>/<room> (<n> KG facts)` or `MemPalace unavailable — capture skipped`.
+Print a one-line summary: `Filed <artifact> → <wing>/<room> (<n> KG facts)`, `Capture queued — palace busy; MemPalace will file it when the lock frees` (the background mine was deferred behind another writer), or `MemPalace capture skipped — <reason>` (#4700: a skipped capture is never silent).
 
 ## Anti-Patterns
 

package/skills/gsd-mempalace-recall/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
 ---
 
 

package/skills/gsd-new-milestone/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
   - Agent
   - AskUserQuestion
 ---

package/skills/gsd-new-project/SKILL.md

@@ -5,6 +5,7 @@ argument-hint: "[--auto]"
 allowed-tools:
   - Read
   - Bash
+  - Grep
   - Write
   - Agent
   - AskUserQuestion

package/skills/gsd-next/SKILL.md

@@ -5,6 +5,7 @@ allowed-tools:
   - Read
   - Bash
   - Glob
+  - Grep
   - SlashCommand
   - AskUserQuestion
 ---

package/skills/gsd-pause-work/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - Grep
 ---
 
 

package/skills/gsd-phase/SKILL.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Write
   - Bash
   - Glob
+  - Grep
 ---
 
 

package/skills/gsd-plan-review-convergence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-plan-review-convergence
 description: "Cross-AI plan convergence - replan until review concerns are resolved."
-argument-hint: "<phase> [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--antigravity] [--agy] [--ollama] [--lm-studio] [--llama-cpp] [--kimi-code] [--text] [--ws <name>] [--all] [--max-cycles N]"
+argument-hint: "<phase> [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--antigravity] [--agy] [--ollama] [--lm-studio] [--llama-cpp] [--kimi-code] [--text] [--ws <name>] [--all] [--max-cycles N]"
 allowed-tools:
   - Read
   - Write
@@ -20,7 +20,7 @@ Repeatedly: review plans with external AI CLIs → if HIGH or actionable non-HIG
 
 **Flow:** Skill("gsd-plan-phase") → Agent→Skill("gsd-review") → check unresolved HIGH + actionable non-HIGH → Skill("gsd-plan-phase --reviews") → Agent→Skill("gsd-review") → ... → Converge or escalate
 
-Replaces gsd-plan-phase's internal gsd-plan-checker with external AI reviewers (codex, gemini, etc.). Plan-phase runs **inline** (bare Skill at depth 0) so it can spawn gsd-planner/gsd-plan-checker at depth 1. Review runs inside an isolated Agent (gsd-review is a Bash leaf — no sub-agents needed). Orchestrator only does loop control.
+Replaces gsd-plan-phase's internal gsd-plan-checker with external AI reviewers (codex, claude, etc.). Plan-phase runs **inline** (bare Skill at depth 0) so it can spawn gsd-planner/gsd-plan-checker at depth 1. Review runs inside an isolated Agent (gsd-review is a Bash leaf — no sub-agents needed). Orchestrator only does loop control.
 
 **Orchestrator role:** Parse arguments, validate phase, run plan-phase inline (Skill at depth 0), spawn an Agent for gsd-review, check unresolved HIGH and actionable non-HIGH counts, stall detection, escalation gate.
 </objective>
@@ -41,8 +41,7 @@ Phase number: extracted from $ARGUMENTS (required)
 
 **Flags:**
 - `--codex` — Use Codex CLI as reviewer (default if no reviewer flag given AND `review.default_reviewers` is unset; otherwise `review.default_reviewers` wins per ADR-0011 — #2315)
-- `--gemini` — Use Gemini CLI as reviewer
-- `--agy` / `--antigravity` — Use Antigravity CLI as reviewer (successor to the discontinued Gemini CLI)
+- `--agy` / `--antigravity` — Use Antigravity CLI as reviewer
 - `--claude` — Use Claude CLI as reviewer (separate session)
 - `--coderabbit` — Use CodeRabbit as reviewer (reviews the working-tree diff, not the source tree)
 - `--opencode` — Use OpenCode as reviewer
@@ -56,7 +55,8 @@ Phase number: extracted from $ARGUMENTS (required)
 - `--max-cycles N` — Maximum replan→review cycles (default: 3)
 
 **Feature gate:** This command requires `workflow.plan_review_convergence=true`. Enable with:
-`gsd config-set workflow.plan_review_convergence true`
+`gsd config-set workflow.plan_review_convergence true`. A dispatch carrying `--override-gate` —
+how `/gsd-autonomous --converge` invokes this workflow (#4600) — bypasses the gate for that run.
 </context>
 
 <process>

package/skills/gsd-pr-branch/SKILL.md

@@ -4,6 +4,7 @@ description: "Create a clean PR branch by filtering out .planning/ commits — r
 argument-hint: "[target branch, default: main]"
 allowed-tools:
   - Bash
+  - Grep
   - Read
   - AskUserQuestion
 ---

package/skills/gsd-progress/SKILL.md

@@ -24,7 +24,7 @@ Three modes:
 <flags>
 - **--next**: Detect current project state and automatically invoke the next logical GSD workflow step. Scans all prior phases for incomplete work before routing. `--next --force` bypasses safety gates.
 - **--next --auto**: Like `--next`, but after the determined step completes, automatically re-invokes `/gsd-progress --next --auto` to continue chaining steps until completion or a blocking decision. Enables hands-free plan→execute→verify→complete progression.
-- **--next --converge**: When the next action is planning (Route 3), route it through the plan-review **convergence** loop instead of the standard planner. Requires `workflow.plan_review_convergence=true` (enable with `gsd config-set workflow.plan_review_convergence true`). `--cross-ai` is an alias. Reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`) and `--max-cycles N` are forwarded to the convergence loop.
+- **--next --converge**: When the next action is planning (Route 3), route it through the plan-review **convergence** loop instead of the standard planner. Requires `workflow.plan_review_convergence=true` (enable with `gsd config-set workflow.plan_review_convergence true`). `--cross-ai` is an alias. Reviewer flags (`--codex`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`) and `--max-cycles N` are forwarded to the convergence loop.
 - **--do "..."**: Smart dispatcher — match freeform intent to the best GSD command using routing rules, confirm the match, then hand off.
 - **--forensic**: Run 6-check integrity audit after the standard progress report.
 - **(no flag)**: Standard progress check + intelligent routing (Routes A through F).

package/skills/gsd-quick-batch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsd-quick-batch
-description: "Batch several /gsd:quick-shaped tasks together — planned, dispatched, and merged as one run"
+description: "Batch several `/gsd-quick`-shaped tasks together — planned, dispatched, and merged as one run"
 argument-hint: "[--file <path>] [--jobs auto|N] [--validate] [--research] [--resume <batch-id>] [task list]"
 allowed-tools:
   - Read

package/skills/gsd-resume-work/SKILL.md

@@ -4,6 +4,7 @@ description: "Resume work from previous session with full context restoration"
 allowed-tools:
   - Read
   - Bash
+  - Grep
   - Write
   - AskUserQuestion
   - SlashCommand