@opengsd/gsd-core 1.15.0 → 1.16.0

package/scripts/command-contract-helpers.cjs

@@ -12,6 +12,11 @@
  * enforced by both consumers.
  */
 
+// The one frontmatter fence owner (src/frontmatter-fence.cts, built to bin/lib by
+// build:lib). Every consumer of this module runs after the build: lint:ci (CI builds
+// bin/lib first) and the test suite (pretest).
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
+
 const CANONICAL_TOOLS = new Set([
   'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
   'Task', 'Agent', 'Skill', 'SlashCommand',
@@ -22,16 +27,15 @@ const CANONICAL_TOOLS = new Set([
 ]);
 
 function parseFrontmatter(content) {
-  // CRLF-tolerant split: Windows checkouts (autocrlf=true) leave a trailing
-  // \r on every line, making lines.indexOf('---', 1) return -1 (the value
-  // would be '---\r', not '---') → returns {} → every field appears missing.
-  const lines = content.split(/\r?\n/);
-  if (lines[0].trim() !== '---') return {};
-  const end = lines.indexOf('---', 1);
-  if (end === -1) return {};
+  // The block is the one the one fence owner finds (found while implementing
+  // #5105) — BOM, CRLF (a Windows autocrlf checkout), an adjacent empty block
+  // and a `----` look-alike all read exactly as every runtime reader sees them.
+  // Its lines are split CRLF-tolerantly so a trailing \r never leaks into a value.
+  const fence = locateFrontmatterFence(content);
+  if (!fence || !fence.closed) return {};
   const fm = {};
   let key = null;
-  for (const line of lines.slice(1, end)) {
+  for (const line of content.slice(fence.openEnd, fence.bodyEnd).split(/\r?\n/)) {
     const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
     if (kv) { key = kv[1]; fm[key] = kv[2].trim(); }
     else if (key && line.match(/^\s+-\s+/)) {

package/scripts/docs-guard-registry.cjs

@@ -201,6 +201,9 @@ const DOCS_GUARD_TESTS = {
   'tests/compact-content-4139.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/config-field-docs.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/config.test.cjs': ['docs/CONFIGURATION.md'],
+  // #4974: doc/workflow content-parity checks read docs/CONFIGURATION.md's
+  // Gate Settings section directly (see tests/gates-confirmation-toggle-config.test.cjs).
+  'tests/gates-confirmation-toggle-config.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/context-index-sync.test.cjs': ['docs/CONTEXT-INDEX.json'],
   'tests/context-predicates-query.test.cjs': ['docs/contributor-standards.md'],
   // SCAN_DIRS includes 'docs' and recursively walks every .md file under it
@@ -418,6 +421,9 @@ const DOCS_GUARD_TESTS = {
   'tests/verifier-behavior-unverified.test.cjs': ['docs/reference/planning-artifacts.md'],
   'tests/verifier-coincidental-reliance.test.cjs': ['docs/AGENTS.md'],
   'tests/verify.test.cjs': ['docs/reference/plan-md.md'],
+  // #5118 V43: asserts the deleted execute-phase/steps/stale-reverification.md
+  // is absent from the generated inventory manifest.
+  'tests/verify-lifecycle-writes-e2e.test.cjs': ['docs/INVENTORY-MANIFEST.json'],
   'tests/workflow-fragments.test.cjs': ['docs/reference/workflow-fragments.md'],
 };
 

package/scripts/gen-features.cjs

@@ -66,6 +66,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+// The one frontmatter fence owner (src/frontmatter-fence.cts, built by build:lib).
+// Every entry point runs after the build: lint:generated-sync inside lint:ci (CI
+// builds bin/lib first), regen:derived (`npm run build` first), and the tests.
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const FEATURES_DIR = path.join(ROOT, 'docs', 'features');
@@ -255,13 +259,12 @@ function renderFrontmatter(data, body) {
  */
 function parseFrontmatter(text) {
   const normalized = String(text).replace(/\r\n/g, '\n');
-  if (!normalized.startsWith('---\n')) return { data: null, body: normalized };
-
-  const end = normalized.indexOf('\n---\n', 3);
-  if (end === -1) return { data: null, body: normalized };
+  // The block is the one the one fence owner finds (found while implementing #5105).
+  const fence = locateFrontmatterFence(normalized);
+  if (!fence || !fence.closed) return { data: null, body: normalized };
 
   const data = {};
-  for (const line of normalized.slice(4, end + 1).split('\n')) {
+  for (const line of normalized.slice(fence.openEnd, fence.bodyEnd).split('\n')) {
     if (line.trim() === '') continue;
     const sep = line.indexOf(':');
     if (sep === -1) continue;
@@ -270,9 +273,11 @@ function parseFrontmatter(text) {
     data[key] = parseScalar(line.slice(sep + 1).trim());
   }
 
-  // `+5` clears "\n---\n"; the blank line renderFrontmatter emits after the
-  // closing fence is consumed here so body text starts at its first real line.
-  let body = normalized.slice(end + 5);
+  // Past the closing fence line and its line ending; the blank line
+  // renderFrontmatter emits after the closing fence is consumed here so body
+  // text starts at its first real line.
+  let body = normalized.slice(fence.closingFenceEnd);
+  if (body.startsWith('\n')) body = body.slice(1);
   if (body.startsWith('\n')) body = body.slice(1);
   return { data, body };
 }

package/scripts/gen-hooks-cli-exit.cjs

@@ -18,6 +18,17 @@
  * target (`.js`, not `.cjs`, to match the hooks/lib/*.js convention) would
  * tangle a script that is otherwise simple and single-purpose.
  *
+ * compileToTemp() itself IS shared (required from ./gen-scripts-cli-exit.cjs)
+ * rather than duplicated: it compiles only src/cli-exit.cts (via a throwaway
+ * tsconfig that extends tsconfig.build.json with files/include scoped to
+ * that one module) rather than the whole project, since the emit this
+ * script needs depends only on cli-exit.cts's own import closure. A
+ * whole-project `-p tsconfig.build.json` type-check of every .cts file under
+ * a fixed COMPILE_TIMEOUT_MS ceiling can get killed by that timeout on a
+ * CPU-contended shared bench even though the one file this script needs
+ * compiles in a fraction of the time — and the compile strategy itself has
+ * nothing sibling-specific to fork.
+ *
  * Usage:
  *   node scripts/gen-hooks-cli-exit.cjs            # same as --write
  *   node scripts/gen-hooks-cli-exit.cjs --write     # write hooks/lib/cli-exit.js
@@ -35,14 +46,12 @@
 
 'use strict';
 
-const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { compileToTemp } = require('./gen-scripts-cli-exit.cjs');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 const OUTPUT_PATH = path.join(REPO_ROOT, 'hooks', 'lib', 'cli-exit.js');
-const COMPILE_TIMEOUT_MS = 60_000;
 
 /** Frozen reason codes so tests assert on structure, not prose. */
 const REASON = Object.freeze({
@@ -78,31 +87,6 @@ const BANNER = [
   '',
 ].join('\n');
 
-/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
-function compileToTemp() {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-hooks-cli-exit-'));
-  try {
-    execFileSync(
-      process.execPath,
-      [
-        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
-        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
-        '--outDir', tmp,
-        // A throwaway outDir must not reuse the in-tree incremental state, or
-        // tsc skips emit for files it believes are already current.
-        '--incremental', 'false',
-        '--tsBuildInfoFile', 'null',
-      ],
-      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe', timeout: COMPILE_TIMEOUT_MS },
-    );
-    return { ok: true, dir: tmp };
-  } catch (err) {
-    fs.rmSync(tmp, { recursive: true, force: true });
-    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
-    return { ok: false, detail };
-  }
-}
-
 /**
  * Compile src/cli-exit.cts to a throwaway outDir and return the expected
  * generated content (banner + compiled bytes, with the sibling registry

package/scripts/gen-loop-host-contract.cjs

@@ -37,7 +37,16 @@ const STEP_WORKFLOWS = [
       { file: 'quick.md', point: 'plan:pre', kinds: ['contribution'], into: 'planner' },
     ],
   },
-  { file: 'execute-phase.md', step: 'execute' },
+  {
+    file: 'execute-phase.md',
+    step: 'execute',
+    // #5118: execute:post's step AND gate dispatch (code_review_gate with
+    // its TDD escalation) lives in the ONE shared verification step that
+    // execute-phase includes (and verify-work includes too) — no per-caller copy.
+    auxiliaryHosts: [
+      { file: 'execute-phase/steps/verify-phase-goal.md', point: 'execute:post', kinds: ['step', 'gate'] },
+    ],
+  },
   { file: 'verify-work.md',   step: 'verify' },
   { file: 'ship.md',          step: 'ship' },
 ];

package/scripts/gen-platform-conformance-tier.cjs

@@ -97,6 +97,26 @@
  * point the CLI at a small temp fixture tree instead of this repo's real,
  * 900+-file tests/ tree. Production usage (package.json's lint:generated-sync
  * / regen:derived chains) passes no flags and gets the real repo paths.
+ *
+ * #5074 — the `.platform` sibling rule. A handful of the heaviest tier files
+ * carry their real Windows signal in only a few tests out of hundreds; the
+ * fix is to move those tests into a same-directory `X.platform.test.cjs`
+ * sibling of `X.test.cjs`, so only the sibling (not the whole base) needs
+ * real-OS coverage. That split is enforced here as a FAILING invariant
+ * (`findPlatformSplitViolations`, wired into `classifyTree`) rather than as a
+ * silent filename-based exclusion rule, for two reasons: epic #4589 Phase 2
+ * requires real-OS overrides to be centrally enumerated, not implied by a
+ * naming convention (a bare "base excluded whenever a sibling exists" rule
+ * would BE such a convention); and a platform-sensitive test later added
+ * back into a split base must not silently re-admit the whole base to
+ * Linux-only on the Windows tier — it must fail generation loudly instead, at
+ * the same `lint:generated-sync` gate this module already backs. This
+ * invariant is scoped to the Windows CATEGORIES and wired only into
+ * `classifyTree`; `classifyMacosTree` stays pure content selection by design,
+ * so a macOS-only signal (e.g. case-sensitivity wording) left in a split base
+ * re-admits that base to the macOS tier instead of failing — over-inclusion,
+ * the safe direction. See docs/how-to/split-platform-sensitive-tests.md for
+ * the authoring rules this invariant enforces.
  */
 
 const fs = require('node:fs');
@@ -316,6 +336,140 @@ function classifyMacosContent(content) {
   return { needsRealOs: signals.length > 0, signals };
 }
 
+/**
+ * The `.platform` sibling suffix (#5074). A sibling of `X.test.cjs` is a file
+ * whose basename ENDS with this suffix and has a non-empty stem before it —
+ * `foo.platform.test.cjs` is a sibling of `foo.test.cjs`, but a bare
+ * `platform.test.cjs` (empty stem) is not, and neither is a hyphenated name
+ * like `x-platform.test.cjs` or `platform-conformance-tier.test.cjs` (this
+ * module's own test file) — the rule keys on the literal dotted suffix, not
+ * on the substring "platform" appearing anywhere in the name.
+ */
+const PLATFORM_SIBLING_SUFFIX = '.platform.test.cjs';
+
+/**
+ * Parse `rel` (a POSIX `tests/...`-relative path) as a `.platform` sibling.
+ * Returns `{ dir, stem }` when it is one (dir is the POSIX dirname, stem is
+ * the basename with `PLATFORM_SIBLING_SUFFIX` stripped), or `null` when it is
+ * not — either because the basename does not end with the suffix, or because
+ * the stem would be empty (the `platform.test.cjs` negative-space case).
+ *
+ * @param {string} rel
+ * @returns {{ dir: string, stem: string } | null}
+ */
+function parsePlatformSibling(rel) {
+  const dir = path.posix.dirname(rel);
+  const base = path.posix.basename(rel);
+  if (!base.endsWith(PLATFORM_SIBLING_SUFFIX)) return null;
+  const stem = base.slice(0, -PLATFORM_SIBLING_SUFFIX.length);
+  if (stem.length === 0) return null;
+  return { dir, stem };
+}
+
+/** Resolve `X.test.cjs`'s rel path for a `.platform` sibling's `{ dir, stem }`. */
+function baseRelFor({ dir, stem }) {
+  return (dir === '.' ? '' : dir + '/') + stem + '.test.cjs';
+}
+
+/** Resolve `X.platform.test.cjs`'s rel path for a base rel path (inverse of baseRelFor). */
+function siblingRelForBase(baseRel) {
+  const dir = path.posix.dirname(baseRel);
+  const stem = path.posix.basename(baseRel).slice(0, -'.test.cjs'.length);
+  return (dir === '.' ? '' : dir + '/') + stem + PLATFORM_SIBLING_SUFFIX;
+}
+
+/**
+ * The `.platform` sibling invariant (#5074), pure over an explicit `entries`
+ * array so it can be driven directly against fixtures (and against the real
+ * `ALWAYS_REAL_OS` map, which no temp fixture tree can key into) without
+ * touching the filesystem. `entries` is the ELIGIBLE (unit-suite) test-file
+ * set — a suite-tagged base is never a member, which is what makes it
+ * "never eligible" per the design doc's negative space rather than something
+ * this function has to special-case.
+ *
+ * For every `.platform` sibling present in `entries` (see
+ * `parsePlatformSibling`), checks three independent things against its base
+ * (`X.test.cjs`, same directory):
+ *   - `base-has-signal`   — the base IS in `entries` and still carries a
+ *     genuine Windows signal (`classifyContent` on its own content) — the
+ *     split did not actually remove the signal from the base.
+ *   - `sibling-without-signal` — the sibling's OWN content carries no
+ *     Windows signal, regardless of whether its base exists — a `.platform`
+ *     file whose header claims a platform reason the classifier cannot see
+ *     in its own text.
+ *   - `base-always-real-os` — the base is a key of `alwaysRealOs`: the
+ *     escape hatch says the WHOLE base needs real-OS coverage, which
+ *     contradicts splitting only some of its tests into a sibling.
+ *
+ * A base that is absent from `entries` (suite-tagged, deleted, or renamed)
+ * never triggers `base-has-signal` — there is nothing to read.
+ *
+ * @param {{rel: string, content: string}[]} entries
+ * @param {Map<string, string>} [alwaysRealOs]
+ * @returns {{file: string, kind: 'base-has-signal'|'sibling-without-signal'|'base-always-real-os', signals: string[]}[]}
+ *   sorted by file, then kind.
+ */
+function findPlatformSplitViolations(entries, alwaysRealOs = ALWAYS_REAL_OS) {
+  const byRel = new Map(entries.map((entry) => [entry.rel, entry]));
+  const violations = [];
+
+  for (const entry of entries) {
+    const parsed = parsePlatformSibling(entry.rel);
+    if (!parsed) continue;
+    const baseRel = baseRelFor(parsed);
+
+    const base = byRel.get(baseRel);
+    if (base !== undefined) {
+      const { signals } = classifyContent(base.content);
+      if (signals.length > 0) {
+        violations.push({ file: baseRel, kind: 'base-has-signal', signals });
+      }
+    }
+
+    const { signals: siblingSignals } = classifyContent(entry.content);
+    if (siblingSignals.length === 0) {
+      violations.push({ file: entry.rel, kind: 'sibling-without-signal', signals: [] });
+    }
+
+    if (alwaysRealOs.has(baseRel)) {
+      violations.push({ file: baseRel, kind: 'base-always-real-os', signals: [] });
+    }
+  }
+
+  violations.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind < b.kind ? -1 : 1;
+    return 0;
+  });
+  return violations;
+}
+
+/**
+ * Render `findPlatformSplitViolations`' result as the Error message
+ * `classifyTree` throws: starts with the literal phrase callers/tests grep
+ * for, lists one line per violation (file, kind, residual signal names, and
+ * — for `base-has-signal` only — the sibling path those tests belong in),
+ * and points at the how-to doc for the authoring rules.
+ *
+ * @param {ReturnType<typeof findPlatformSplitViolations>} violations
+ * @returns {string}
+ */
+function formatPlatformSplitViolations(violations) {
+  const lines = violations.map((v) => {
+    let line = `  - ${v.file} [${v.kind}]`;
+    if (v.signals.length > 0) line += ` residual signal(s): ${v.signals.join(', ')}`;
+    if (v.kind === 'base-has-signal') {
+      line += ` — move these tests into ${siblingRelForBase(v.file)}`;
+    }
+    return line;
+  });
+  return (
+    `platform split invariant violated (#5074) — ${violations.length} file(s):\n` +
+    lines.join('\n') +
+    '\nSee docs/how-to/split-platform-sensitive-tests.md for the split-invariant rules.\n'
+  );
+}
+
 /**
  * Recursively collect every `*.test.cjs` file beneath `dir`.
  * @param {string} dir
@@ -355,10 +509,15 @@ function classifyTree(testsDir) {
   // tier — see the header doc-comment for why suite-tagged files are excluded
   // entirely rather than merely deprioritized.
   const unitFiles = absoluteFiles.filter((absPath) => suiteOf(absPath) === null);
+  const entries = [];
   const flagged = [];
   for (const absPath of unitFiles) {
     const rel = 'tests/' + path.relative(testsDir, absPath).replace(/\\/g, '/');
     const content = fs.readFileSync(absPath, 'utf8');
+    // Read once, reused below both for this file's own flagging AND (via
+    // `entries`) for the #5074 split-invariant check — a second read of the
+    // same file for that check would double the I/O for no reason.
+    entries.push({ rel, content });
     const { needsRealOs } = classifyContent(content);
     // The ALWAYS_REAL_OS escape hatch (Windows tier only — see its doc
     // comment) is unioned in HERE, keyed off a file that this walk actually
@@ -369,6 +528,19 @@ function classifyTree(testsDir) {
       flagged.push(rel);
     }
   }
+
+  // #5074: a `.platform` sibling pair that violates the split invariant
+  // (residual signal left in the base, a sibling with no signal of its own,
+  // or a base that ALWAYS_REAL_OS says needs the whole file on real OS) fails
+  // generation loudly rather than being silently included or excluded. This
+  // check is Windows-CATEGORIES-only and wired here, not into
+  // classifyMacosTree below — a macOS-only signal in a split base is handled
+  // there by ordinary content selection (over-inclusion), not this invariant.
+  const violations = findPlatformSplitViolations(entries, ALWAYS_REAL_OS);
+  if (violations.length > 0) {
+    throw new Error(formatPlatformSplitViolations(violations));
+  }
+
   const result = [...new Set(flagged)].sort();
   return { total: absoluteFiles.length, files: result };
 }
@@ -484,7 +656,19 @@ function main() {
   const isMacos = target === 'macos';
   const label = isMacos ? 'gen-platform-conformance-tier --target macos' : 'gen-platform-conformance-tier';
   const exportKey = isMacos ? 'MACOS_CONFORMANCE_TIER_FILES' : 'CONFORMANCE_TIER_FILES';
-  const { total, files } = isMacos ? classifyMacosTree(testsDir) : classifyTree(testsDir);
+  // classifyTree throws a plain Error on a #5074 split-invariant violation
+  // (it has no ExitError/exit-code opinion of its own — it is also called
+  // in-process by tests). runMain only special-cases ExitError (stderr gets
+  // err.message; anything else gets the full err.stack); wrapping it here
+  // keeps the CLI's stderr output to the clean, purpose-built violation
+  // report instead of a raw stack trace.
+  let total, files;
+  try {
+    ({ total, files } = isMacos ? classifyMacosTree(testsDir) : classifyTree(testsDir));
+  } catch (err) {
+    if (err instanceof ExitError) throw err;
+    throw new ExitError(1, err && err.message ? err.message : String(err));
+  }
 
   if (mode === 'write') {
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
@@ -554,4 +738,6 @@ module.exports = {
   MACOS_CATEGORIES,
   classifyMacosTree,
   renderMacosGeneratedFile,
+  PLATFORM_SIBLING_SUFFIX,
+  findPlatformSplitViolations,
 };

package/scripts/gen-plugin-skills.cjs

@@ -17,6 +17,21 @@
  * installer uses, producing a build-generated skills/ dir that ships in the
  * npm package and serves plugin-only installs.
  *
+ * #4995: commands/gsd/*.md still instruct bare command-position `gsd-tools
+ * <verb>` calls in 4 files (workstreams.md, quick.md, review-backlog.md,
+ * config.md), which fail with "command not found" on a shim-only install.
+ * That source can't be normalized to `gsd_run` directly the way #2751 did for
+ * agents/*.md and gsd-core/workflows/*.md: tests/gsd-tools-path-refs.test.cjs
+ * (#1766) pins commands/gsd/workstreams.md to the literal string
+ * `gsd-tools query workstream.list`, and bringing commands/ under the #2751
+ * guard was tried and reverted for unrelated load-bearing reasons (11ad7881ed
+ * / d286e54163). So this generator rewrites bare gsd-tools -> gsd_run in its
+ * OWN output — the same shape of fix #725 already established for the Codex
+ * conversion pipeline (rewrite the generated artifact, not the shared
+ * source) — reusing the exact `gsd_run` resolver preamble #2751 established
+ * (scripts/sync-runtime-launcher.cjs's transformFile) rather than inventing a
+ * new resolution mechanism.
+ *
  * Depends on: gsd-core/bin/lib/runtime-artifact-conversion.cjs (compiled from
  * src/runtime-artifact-conversion.cts by `npm run build:lib`). Must run AFTER
  * build:lib in the build chain.
@@ -25,6 +40,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { transformFile, loadPreamble } = require('./sync-runtime-launcher.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const COMMANDS_DIR = path.join(ROOT, 'commands', 'gsd');
@@ -33,6 +49,73 @@ const CONVERSION_MODULE = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'runtime-art
 const PREFIX = 'gsd-';
 const RUNTIME = 'claude';
 
+// #4995: the 4 commands/gsd/*.md stems (census taken by the issue) that carry
+// command-position bare `gsd-tools <verb>` calls. Deliberately an explicit
+// allowlist, NOT a blanket regex applied to every generated skill: several
+// other skills (e.g. gsd-graphify) merely NAME `gsd-tools`/`gsd_run`
+// descriptively (prose, "DO NOT use ..." warnings) in ways a command-position
+// regex cannot safely tell apart from a real instruction without per-site
+// human review -- exactly the ambiguity tests/no-bare-gsd-tools-command-
+// position.test.cjs's PROSE_ALLOWLIST exists to resolve by hand for #2751/
+// #3809. gsd-graphify also carries 5 deliberately-separate per-block
+// preambles (tests/graphify-visualization.test.cjs extracts and runs each
+// fenced Step-3 block standalone); running every skill through
+// transformFile's "collapse to one preamble per file" behavior would
+// reproduce the exact regression d286e54163 already found and reverted for
+// commands/gsd/graphify.md. Restricting the rewrite to the 4 files the
+// census in #4995 actually names avoids all of that.
+const BARE_GSD_TOOLS_STEMS = new Set(['workstreams', 'quick', 'review-backlog', 'config']);
+
+// #4995: command-position bare `gsd-tools` -> `gsd_run` token swap. Mirrors 3
+// of the 4 command-position shapes rewriteBareGsdToolsCommandsForCodex
+// (src/runtime-artifact-conversion.cts) already covers for the Codex
+// pipeline: start-of-line, inside `$( ... )`, and immediately after a
+// backtick (inline "Run: `gsd-tools verb args`" prose). Deliberately DROPS
+// that function's 4th shape -- a bare, unescaped `|` counted as a shell
+// pipe separator -- because a Markdown table row (`| col | gsd-tools verb
+// arg |`) also starts a cell with `| gsd-tools`, and none of the 11 sites in
+// #4995's census need it: config.md's own routing TABLE names `gsd-tools
+// query config-set-model-profile` descriptively in a `|`-delimited cell one
+// row above the real operative site, and rewriting that cell too would be a
+// change nobody asked for. (`&&`/`;` are kept: two-character or dedicated
+// separators, not also a Markdown table delimiter.) Only applied to
+// BARE_GSD_TOOLS_STEMS files (see above). Within those 4 files this narrower
+// pattern still matches one site beyond the issue's 11-site census --
+// gsd-quick/SKILL.md's <security_notes> line ("Status fields read via
+// `gsd-tools query frontmatter.get`") is a backtick-wrapped DESCRIPTIVE
+// mention, not a `Run:` instruction, but it has the identical command-
+// position shape and gets swapped too. That's harmless (the sentence reads
+// the same with `gsd_run` in it) and left as-is rather than special-cased,
+// but the true count this generator fixes is 12 operative-shaped sites, not
+// 11 -- the 12th just wasn't literal-command "operative" in the issue's own
+// sense.
+function rewriteBareGsdToolsCommandsToGsdRun(content) {
+  return content
+    .replace(/(^[ \t]*)gsd-tools(?=\s)/gm, '$1gsd_run')
+    .replace(/(\$\(\s*)gsd-tools(?=\s)/g, '$1gsd_run')
+    .replace(/(`\s*)gsd-tools(?=\s)/g, '$1gsd_run')
+    .replace(/((?:&&|;)\s*)gsd-tools(?=\s)/g, '$1gsd_run');
+}
+
+// #4995: after the token swap, any fenced bash/sh/shell block that now calls
+// `gsd_run` needs the resolver preamble that defines it -- reuse
+// sync-runtime-launcher.cjs's transformFile verbatim (the same mechanism
+// applied to agents/*.md and gsd-core/workflows/*.md) rather than
+// reimplementing preamble placement here. Inline (non-fenced) "Run: `gsd_run
+// verb args`" prose has no fenced block to anchor a preamble to; per the
+// precedent already set for this exact shape (commands/gsd/workstreams.md
+// and config.md in 11ad7881ed), it is left as a bare `gsd_run` token --
+// `gsd_run` is itself a shipped npm bin name, so it resolves identically to
+// how the pre-fix `gsd-tools` form resolved once PATH carries it (e.g. via
+// the CLAUDE_ENV_FILE export in an earlier-run preamble in the same
+// session), without regressing anything that worked before.
+function rewriteSkillContent(content) {
+  const swapped = rewriteBareGsdToolsCommandsToGsdRun(content);
+  const preamble = loadPreamble();
+  const withPreamble = transformFile(swapped, preamble);
+  return withPreamble === null ? swapped : withPreamble;
+}
+
 function generateSkills(conversion) {
   const cmdNames = conversion.readGsdCommandNames();
   const files = fs.readdirSync(COMMANDS_DIR).filter(f => f.endsWith('.md'));
@@ -41,7 +124,10 @@ function generateSkills(conversion) {
     const stem = file.slice(0, -3);
     const skillName = PREFIX + stem;
     const src = fs.readFileSync(path.join(COMMANDS_DIR, file), 'utf8');
-    const converted = conversion.convertClaudeCommandToClaudeSkill(src, skillName, RUNTIME, cmdNames, true);
+    let converted = conversion.convertClaudeCommandToClaudeSkill(src, skillName, RUNTIME, cmdNames, true);
+    if (BARE_GSD_TOOLS_STEMS.has(stem)) {
+      converted = rewriteSkillContent(converted);
+    }
     results.push({ skillName, content: converted });
   }
   return results;

package/scripts/gen-research-agents.cjs

@@ -25,6 +25,9 @@ const path = require('node:path');
 
 const { PROFILES } = require('./research-profiles.cjs');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+// The one frontmatter fence owner (src/frontmatter-fence.cts, built by build:lib).
+// This dev-time script runs after the build (manually, and from the tests).
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
 const AGENTS_DIR = path.join(ROOT, 'agents');
@@ -41,12 +44,13 @@ const AGENTS_DIR = path.join(ROOT, 'agents');
  * We read the CURRENT commented-hooks block from the agent file and preserve it
  * byte-for-byte; only name/description/tools/color are regenerated.
  */
-function buildFrontmatter(profile, existingFrontmatter) {
-  // Extract the commented hooks section from the existing frontmatter, if any.
-  // The hooks block starts at `# hooks:` and runs to (but not including) the
-  // closing `---`. In the committed files there is NO blank line between
-  // `color:` and `# hooks:`, so we append it directly after the color line's `\n`.
-  const hooksMatch = existingFrontmatter.match(/(# hooks:[\s\S]*?)(?=\n---)/);
+function buildFrontmatter(profile, existingRegion) {
+  // Extract the commented hooks section from the existing frontmatter region
+  // (the YAML text between the fences), if any. The hooks block starts at
+  // `# hooks:` and runs to the end of the region — the closing `---` follows it.
+  // In the committed files there is NO blank line between `color:` and
+  // `# hooks:`, so we append it directly after the color line's `\n`.
+  const hooksMatch = existingRegion.match(/(# hooks:[\s\S]*)$/);
   // hooksSuffix: if present, the block followed by a newline so `---` is on its own line;
   // if absent, empty string (the closing `---` follows directly after color's `\n`).
   const hooksSuffix = hooksMatch ? hooksMatch[1] + '\n' : '';
@@ -67,37 +71,26 @@ function buildFrontmatter(profile, existingFrontmatter) {
 /**
  * Parse a .md file and return { frontmatterRaw, body, frontmatterFields }.
  *
- * frontmatterRaw: the raw text between the first and second `---` delimiters (exclusive)
- * body: everything after the closing `---\n`
+ * frontmatterRaw: the YAML text between the opening and closing fences (exclusive)
+ * fullFrontmatter: the block from the opening fence through the closing fence line
+ * body: everything after the closing fence line's line ending
  * frontmatterFields: { name, description, color, tools }
+ *
+ * The block is the one the one fence owner finds (found while implementing #5105):
+ * it opens at byte 0 (after a BOM), exactly as the runtime that loads the agent reads it.
  */
 function parseAgentFile(filePath) {
   const raw = fs.readFileSync(filePath, 'utf8');
 
-  // The frontmatter is between the first `---` line and the next `---` line.
-  const lines = raw.split('\n');
-  let start = -1;
-  let end = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trim() === '---') {
-      if (start === -1) {
-        start = i;
-      } else {
-        end = i;
-        break;
-      }
-    }
-  }
-
-  if (start === -1 || end === -1) {
+  const fence = locateFrontmatterFence(raw);
+  if (!fence || !fence.closed) {
     throw new Error('No valid frontmatter delimiters found in ' + filePath);
   }
 
-  const frontmatterLines = lines.slice(start + 1, end);
-  const frontmatterRaw = frontmatterLines.join('\n');
-  // body includes the closing `---` line and everything after
-  const fullFrontmatter = lines.slice(start, end + 1).join('\n');
-  const body = lines.slice(end + 1).join('\n');
+  const frontmatterRaw = raw.slice(fence.openEnd, fence.bodyEnd);
+  const frontmatterLines = frontmatterRaw.split(/\r?\n/);
+  const fullFrontmatter = raw.slice(fence.bom.length, fence.closingFenceEnd);
+  const body = raw.slice(fence.closingFenceEnd).replace(/^\r?\n/, '');
 
   const fields = {};
   // Parse simple key: value pairs (not nested YAML, no multi-line values here)
@@ -214,9 +207,9 @@ function runCheck() {
  */
 function writeAgent(profile) {
   const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
-  const { fullFrontmatter, body } = parseAgentFile(agentPath);
+  const { frontmatterRaw, body } = parseAgentFile(agentPath);
 
-  const newFrontmatter = buildFrontmatter(profile, fullFrontmatter);
+  const newFrontmatter = buildFrontmatter(profile, frontmatterRaw);
   const newContent = newFrontmatter + '\n' + body;
 
   fs.writeFileSync(agentPath, newContent, 'utf8');