@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -15,7 +15,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_LOCAL_CONFIG_DIR_SENTINEL = void 0;
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.FALLBACK_HOST_BEHAVIORS = exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = exports.RetiredRuntimeError = exports.UnknownRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
+exports.isRetiredRuntimeId = isRetiredRuntimeId;
+exports.assertNotRetiredRuntime = assertNotRetiredRuntime;
+exports.isKnownRuntimeId = isKnownRuntimeId;
+exports.assertKnownRuntime = assertKnownRuntime;
+exports.hostBehaviorsFor = hostBehaviorsFor;
 exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
@@ -23,9 +28,237 @@ exports.getDirName = getDirName;
 exports.getRuntimeLabel = getRuntimeLabel;
 exports.getGlobalConfigHomeFragment = getGlobalConfigHomeFragment;
 exports.runtimeFlags = runtimeFlags;
-exports.getRuntimeNewProjectCommand = getRuntimeNewProjectCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Runtime ids that GSD deliberately RETIRED, as opposed to ids it has simply
+ * never heard of. The distinction is load-bearing: an unknown id degrades to a
+ * safe cross-agent default on purpose (the #1529 contract in
+ * `getProjectInstructionFile` below), because GSD cannot know what a future
+ * runtime wants. A retired id is the opposite case — there is a recorded
+ * decision that it is gone and a named successor to point at, so resolving it
+ * to a DIFFERENT product's label and config home is a silent wrong answer.
+ *
+ * Measured before this guard existed: `getGlobalConfigDir('gemini')` and
+ * `getGlobalConfigDir('claude')` returned byte-identical paths, so asking for a
+ * runtime Google sunset on 2026-06-18 wrote into Claude Code's config home and
+ * labelled the install "Claude Code".
+ *
+ * Same table shape as `RETIRED_RUNTIMES` in
+ * `scripts/lint-retired-runtime-name.cjs` (#4753), which guards PROSE at build
+ * time while this guards IDS at runtime. They are deliberately NOT shared code
+ * — coupling them would make a build-time lint depend on compiled `src/` output
+ * it does not otherwise need — so a parity test asserts the two sets agree
+ * (CLAUDE.md, Generative Fix Divergence).
+ */
+const RETIRED_RUNTIME_DETAILS = new Map([
+    ['gem' + 'ini', { successor: 'Antigravity', retiredBy: '#1928', sunset: '2026-06-18' }],
+]);
+/**
+ * Normalise a candidate id for retirement matching: NFKC-fold, lowercase, and
+ * drop every non-alphanumeric character.
+ *
+ * Folding the separators is what makes `gemini-cli`, `gemini_cli`,
+ * `gemini.cli` and `geminicli` one key instead of four near-misses a reviewer
+ * has to find one at a time — and NFKC folds the full-width `ｇｅｍｉｎｉ` a CJK
+ * keyboard produces. It stays MEMBERSHIP matching, not a prefix or substring
+ * test: `gemini-2.5-pro` folds to `gemini25pro` and `gemini-3.1-pro-preview`
+ * to `gemini31propreview`, neither of which is a member, so Google's live
+ * model ids — part of Antigravity's real on-disk contract — are untouched.
+ *
+ * Homoglyph folding is deliberately NOT attempted. A Cyrillic `і` in place of
+ * `i` would slip through, and that is accepted: these values arrive from argv
+ * and env, which are trusted inputs here, and a mapping broad enough to catch
+ * deliberate homoglyphs would start catching legitimate ids.
+ */
+function normalizeForRetirementMatch(value) {
+    return value.normalize('NFKC').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Every spelling that names a retired runtime, mapped to its canonical id.
+ * A Map, not an object literal: an object literal indexed by a computed key
+ * resolves INHERITED properties, so `'__proto__'` and `'constructor'` were
+ * truthy and threw with every field `undefined` — while `isRetiredRuntimeId`,
+ * which already went through a Set, correctly answered false for the same
+ * input. Two guards disagreeing about one id is worse than either answer.
+ * A Map has no prototype keys, so the hazard is structural, not patched.
+ */
+const RETIRED_RUNTIME_SPELLINGS = new Map(Array.from(RETIRED_RUNTIME_DETAILS.keys()).flatMap((id) => [
+    [normalizeForRetirementMatch(id), id],
+    [normalizeForRetirementMatch(`${id}-cli`), id],
+]));
+/**
+ * The canonical retired runtime ids, lowercase. Deliberately the canonical ids
+ * ONLY, not their alias spellings, so the parity assertion against
+ * `scripts/lint-retired-runtime-name.cjs`'s `RETIRED_RUNTIMES` compares like
+ * with like.
+ */
+exports.RETIRED_RUNTIME_IDS = new Set(RETIRED_RUNTIME_DETAILS.keys());
+/**
+ * Error thrown when a non-empty runtime id that is neither registered nor a
+ * known non-registry host reaches a descriptor accessor (ADR-5057 §5, #5169).
+ * Before this, such an id silently resolved to Claude Code's values.
+ */
+class UnknownRuntimeError extends Error {
+    code = 'GSD_UNKNOWN_RUNTIME';
+    runtimeId;
+    constructor(runtimeId) {
+        super(`Runtime "${runtimeId}" is not registered in the capability registry. `
+            + 'Refusing to resolve it, because the previous behaviour silently returned Claude Code\'s values.');
+        this.name = 'UnknownRuntimeError';
+        this.runtimeId = runtimeId;
+    }
+}
+exports.UnknownRuntimeError = UnknownRuntimeError;
+/** Error thrown when a retired runtime id reaches a resolution accessor. */
+class RetiredRuntimeError extends Error {
+    code = 'GSD_RETIRED_RUNTIME';
+    runtimeId;
+    constructor(runtimeId, detail) {
+        super(`Runtime "${runtimeId}" was retired by ${detail.retiredBy} (sunset ${detail.sunset}); `
+            + `use "${detail.successor}" instead. Refusing to resolve it, because the previous `
+            + `behaviour silently returned Claude Code's values.`);
+        this.name = 'RetiredRuntimeError';
+        this.runtimeId = runtimeId;
+    }
+}
+exports.RetiredRuntimeError = RetiredRuntimeError;
+/**
+ * Is `runtime` a deliberately retired runtime, under any of its spellings?
+ * Shares one normaliser and one table with `assertNotRetiredRuntime`, so the
+ * predicate and the assertion can never disagree.
+ */
+function isRetiredRuntimeId(runtime) {
+    if (typeof runtime !== 'string')
+        return false;
+    return RETIRED_RUNTIME_SPELLINGS.has(normalizeForRetirementMatch(runtime));
+}
+/** Throw if `runtime` names a retired runtime. No-op otherwise. */
+function assertNotRetiredRuntime(runtime) {
+    if (typeof runtime !== 'string')
+        return;
+    const id = RETIRED_RUNTIME_SPELLINGS.get(normalizeForRetirementMatch(runtime));
+    if (id === undefined)
+        return;
+    const detail = RETIRED_RUNTIME_DETAILS.get(id);
+    if (detail === undefined)
+        return;
+    throw new RetiredRuntimeError(id, detail);
+}
+/**
+ * Legacy runtime ids that have a genuine, dedicated resolution branch in
+ * `runtime-homes.cts` but no capability-registry descriptor (#3024). They are
+ * KNOWN ids: every accessor resolves them rather than refusing. Enumerated by
+ * hand and MUST stay in lockstep with `getGlobalConfigDir`'s hardcoded
+ * branches — add an id only after confirming it has a real dedicated branch.
+ */
+exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = Object.freeze({
+    // Grok's agents home: `GROK_AGENTS_HOME`, else `~/.agents` (dir = path segments under $HOME).
+    grok: Object.freeze({ env: 'GROK_AGENTS_HOME', dir: Object.freeze(['.agents']) }),
+});
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = new Set(Object.keys(exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES));
+/** The capability registry's `runtimes` map, or `null` when it fails to load. */
+function loadRegistryRuntimes() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const reg = require('./capability-registry.cjs');
+        return (reg && reg.runtimes) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `runtime` is a registered runtime id (own property of the registry
+ * `runtimes` map — never an inherited key such as `__proto__`/`constructor`)
+ * or one of {@link LEGACY_NON_REGISTRY_RUNTIME_IDS}. Raw-id match: no trimming,
+ * no case folding, no alias expansion.
+ */
+function isKnownRuntimeId(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return false;
+    const runtimes = loadRegistryRuntimes();
+    if (runtimes && Object.prototype.hasOwnProperty.call(runtimes, runtime))
+        return true;
+    return exports.LEGACY_NON_REGISTRY_RUNTIME_IDS.has(runtime);
+}
+/**
+ * The ONE refusal every descriptor accessor shares (ADR-5057 §5, #5169).
+ * No-op for an absent id (`''`, non-string): that is the documented
+ * "no runtime selected" generic path. A retired id throws
+ * {@link RetiredRuntimeError}; any other non-empty id that is not known throws
+ * {@link UnknownRuntimeError} instead of silently resolving to Claude Code's
+ * values. When the registry itself failed to load, unknown-ness cannot be
+ * proven, so the check degrades to a no-op (the #338 floor in
+ * {@link hostBehaviorsFor} still protects the reference host).
+ */
+function assertKnownRuntime(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return;
+    assertNotRetiredRuntime(runtime);
+    if (loadRegistryRuntimes() === null)
+        return;
+    if (!isKnownRuntimeId(runtime))
+        throw new UnknownRuntimeError(runtime);
+}
+/**
+ * The #338-privacy fail-safe floor: host behaviors for the two hosts whose
+ * generic fallthrough would be WRONG if the registry failed to load. Moved
+ * here from `bin/install.js` so the registry-load-failure degrade lives in the
+ * single host-behaviors accessor instead of one of three copies (#5169).
+ */
+exports.FALLBACK_HOST_BEHAVIORS = Object.freeze({
+    claude: Object.freeze({
+        settingsFileByScope: Object.freeze({ local: 'settings.local.json', global: 'settings.json' }),
+        permissionsSchema: 'claude',
+        sourceMarkerFile: '.gsd-source',
+        hyphenNameAgentBody: true,
+        legacyCommandsGsdInstallMigration: true,
+        legacyCommandsGsdUninstall: 'global',
+    }),
+    // antigravity's global config dir is resolved dynamically (env-overridable,
+    // multi-segment); this floor keeps that routing intact if the registry fails
+    // to load instead of falling through to the wrong '.claude' fragment (#2096).
+    antigravity: Object.freeze({ globalDirResolver: 'antigravity' }),
+});
+/**
+ * The single accessor for a runtime's host behaviors
+ * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors). Replaces
+ * the three private `_hostBehaviors` copies in `bin/install.js`,
+ * `install-engine.cts` and `runtime-artifact-conversion.cts`.
+ *
+ * - absent id (`''`, non-string) → `{}` (generic path).
+ * - registered id → the descriptor's `hostBehaviors` (or `{}` when it declares
+ *   none).
+ * - known non-registry id (`grok`) → `{}`.
+ * - registry failed to load → the #338 floor for the ids it covers, else `{}`.
+ * - any other id (unregistered, retired, a prototype key) → `{}`: no declared
+ *   behaviors, which is the GENERIC path — never Claude Code's behaviors.
+ *
+ * Unlike the path/label accessors (`getDirName`, `getGlobalConfigDir`, …), whose
+ * fallthrough answer is Claude Code's value and therefore a silent wrong answer
+ * (#4632), an absent behavior is the correct answer for a label GSD does not
+ * know — and this accessor is read by guard and hook code on user-supplied
+ * runtime labels (stale config, a retired id), where a throw would crash the
+ * session rather than skip a behavior. ADR-5057 §5 Phase 10 amendment.
+ *
+ * `registry` is injectable so the load-failure branch is unit-testable.
+ */
+function hostBehaviorsFor(runtime, registry) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return {};
+    const floor = () => Object.prototype.hasOwnProperty.call(exports.FALLBACK_HOST_BEHAVIORS, runtime)
+        ? exports.FALLBACK_HOST_BEHAVIORS[runtime]
+        : {};
+    const runtimes = registry === undefined ? loadRegistryRuntimes() : (registry && registry.runtimes) || null;
+    if (runtimes === null)
+        return floor();
+    if (Object.prototype.hasOwnProperty.call(runtimes, runtime)) {
+        const declared = runtimes[runtime]?.runtime?.hostBehaviors;
+        return declared ? declared : floor();
+    }
+    return {};
+}
 const FALLBACK_ALIASES = {
     claude: ['claude', 'claude-code', 'claude-cli'],
     opencode: ['opencode', 'open-code', 'opencode-cli'],
@@ -145,6 +378,7 @@ function resolveRuntimeNameFromCandidates(...candidates) {
  * avoid a circular dependency at module load.
  */
 function getProjectInstructionFile(runtime) {
+    assertNotRetiredRuntime(runtime);
     const canonical = canonicalizeRuntimeName(runtime);
     if (canonical === 'claude')
         return '.claude/CLAUDE.md';
@@ -198,6 +432,9 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
  * compatibility spine had no production consumer at all.
  */
 function getDirName(runtime) {
+    // Same silent-wrong-answer class as the four accessors AC#1 names: this
+    // returned '.claude' for a retired id, and it feeds runtimeConfigDir.
+    assertKnownRuntime(runtime);
     if (!runtime)
         return '.claude';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -268,6 +505,7 @@ const RUNTIME_LABELS = {
  * 'Claude Code'. Sibling to `getDirName`; pure (no I/O).
  */
 function getRuntimeLabel(runtime) {
+    assertKnownRuntime(runtime);
     if (!runtime)
         return 'Claude Code';
     const label = RUNTIME_LABELS[runtime];
@@ -323,6 +561,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
  * dynamically). Pure: no I/O. Sibling to `getDirName` / `getRuntimeLabel`.
  */
 function getGlobalConfigHomeFragment(runtime) {
+    assertKnownRuntime(runtime);
     if (!runtime)
         return DEFAULT_CONFIG_HOME_FRAGMENT;
     const frag = GLOBAL_CONFIG_HOME_FRAGMENTS[runtime];
@@ -368,22 +607,8 @@ function runtimeFlags(runtime) {
     }
     return Object.freeze(flags);
 }
-/**
- * The `/gsd-new-project` invocation syntax per runtime — the post-install
- * "next step" command string. Most runtimes use the default `/gsd-new-project`;
- * a few hosts need a different surface syntax. Collapses the 14-line
- * `if (runtime === 'x') command = ...` chain in bin/install.js's next-step
- * message (ADR-1239 Phase B / #1679 AC2). Pure: no I/O.
- */
-const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
-const RUNTIME_NEW_PROJECT_COMMANDS = {
-    codex: '$gsd-new-project',
-    cursor: 'gsd-new-project (mention the skill name)',
-    kimi: '/skill:gsd-new-project',
-};
-function getRuntimeNewProjectCommand(runtime) {
-    if (!runtime)
-        return DEFAULT_NEW_PROJECT_COMMAND;
-    const c = RUNTIME_NEW_PROJECT_COMMANDS[runtime];
-    return typeof c === 'string' && c.length > 0 ? c : DEFAULT_NEW_PROJECT_COMMAND;
-}
+// The `/gsd-new-project` next-step command is no longer a per-runtime table
+// here: it is generated from the runtime's registered trigger surface by
+// `resolveAdvertisedNewProject` (runtime-artifact-layout.cts, #5215, ADR-5057
+// §5 Phase 12), so what the installer advertises cannot differ from what a
+// runtime registered.

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -34,6 +34,7 @@ exports._setInstallRuntimeMarkerForTests = _setInstallRuntimeMarkerForTests;
 exports._resetInstallRuntimeMarkerCacheForTests = _resetInstallRuntimeMarkerCacheForTests;
 exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
+exports.resolveActiveRuntime = resolveActiveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -148,31 +149,36 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
     const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME']);
     if (envRuntime)
         return envRuntime;
-    if (projectDir) {
-        try {
-            // Read config.json directly (not via loadConfig). loadConfig has a side
-            // effect of normalizing and re-writing legacy keys back to disk, which
-            // would mutate the project file just to read the runtime name. We only
-            // need the literal `runtime:` value, so a plain JSON read is sufficient
-            // and side-effect-free.
-            const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
-            if (node_fs_1.default.existsSync(configPath)) {
-                const raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
-                const parsed = JSON.parse(raw);
-                if (parsed && typeof parsed === 'object' && 'runtime' in parsed) {
-                    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(parsed['runtime']);
-                    if (configRuntime)
-                        return configRuntime;
-                }
-            }
-        }
-        catch {
-            // Fall through to default — a missing/broken config must not crash
-            // runtime output formatting.
-        }
-    }
+    const config = readProjectConfig(projectDir);
+    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(config ? config['runtime'] : undefined);
+    if (configRuntime)
+        return configRuntime;
     return null;
 }
+/**
+ * Read `<projectDir>/.planning/config.json` as a plain object, or `null` when
+ * there is no project, no file, or it is unreadable or not an object.
+ *
+ * Read directly (not via loadConfig). loadConfig has a side effect of
+ * normalizing and re-writing legacy keys back to disk, which would mutate the
+ * project file just to read the runtime name. A plain JSON read is sufficient
+ * and side-effect-free. A missing or broken config must not crash runtime
+ * output formatting, so every failure degrades to `null`.
+ */
+function readProjectConfig(projectDir) {
+    if (!projectDir)
+        return null;
+    try {
+        const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+        if (!node_fs_1.default.existsSync(configPath))
+            return null;
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the effective runtime for a project directory.
  *
@@ -195,13 +201,24 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
  * @returns the resolved runtime name
  */
 function resolveRuntime(projectDir) {
-    const explicit = resolveExplicitRuntime(projectDir);
-    if (explicit)
-        return explicit;
-    const markerRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(readInstallRuntimeMarker());
-    if (markerRuntime)
-        return markerRuntime;
-    return 'claude';
+    // The same chain `resolveActiveRuntime` owns, fed by a project directory:
+    // one implementation, so the two entry points cannot drift (#5169).
+    return resolveActiveRuntime(readProjectConfig(projectDir));
+}
+/**
+ * Resolve the effective runtime from an ALREADY-LOADED config object — the one
+ * chain every consumer of "which runtime is this install" shares (#5169,
+ * ADR-5057 §5, #4690):
+ *
+ *   env.GSD_RUNTIME  >  config.runtime  >  install marker  >  'claude'
+ *
+ * Canonicalized, so an alias or case variant (`claude-code`, `Claude`) cannot
+ * defeat a downstream comparison. `resolveRuntime` above is the same chain for
+ * callers that hold a project directory rather than a parsed config; the marker
+ * is read through `readInstallRuntimeMarker` in both.
+ */
+function resolveActiveRuntime(config, env = process.env) {
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME'], config ? config['runtime'] : undefined, readInstallRuntimeMarker()) || 'claude';
 }
 /**
  * Convenience: format using the runtime resolved from a project directory.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -64,6 +64,8 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
 const pattern_cjs_1 = require("./pattern.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -146,7 +148,10 @@ function formatHookCommandForRuntime(command, opts = {}) {
 // path missed this guard and reintroduced the #166/#377 failure (#580).
 function shellHookOmitsBashRunner({ platform, runtime = 'generic', isShellHook = false } = {}) {
     const p = platform ?? process.platform;
-    return p === 'win32' && runtime === 'claude' && isShellHook;
+    // #5169: descriptor-declared (`hostBehaviors.omitBashRunnerOnWindows`). The
+    // `'generic'` default and any other non-registered label declares nothing, so
+    // it never omits the runner, exactly as before.
+    return p === 'win32' && isShellHook && (0, runtime_name_policy_cjs_1.hostBehaviorsFor)(runtime).omitBashRunnerOnWindows === true;
 }
 // Builds the command string for a local-install managed `.sh` hook. Mirrors the
 // global buildHookCommand path but uses the $CLAUDE_PROJECT_DIR-anchored prefix
@@ -263,6 +268,7 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-session-state.sh',
         'gsd-validate-commit.sh',
         'gsd-phase-boundary.sh',
+        'gsd-graphify-update.sh',
         // #3662: same three guards as MANAGED_HOOK_BASENAMES_BY_SURFACE above —
         // their absence here meant isManagedHookCommand never recognized them, so
         // the settings.json→settings.local.json migration filter (and uninstall
@@ -1032,16 +1038,39 @@ function probeTty(opts = {}) {
     }
 }
 // ─── Platform file I/O ────────────────────────────────────────────────────────
+/**
+ * How many leading lines of LF-only `text` are its closed YAML frontmatter block (opening
+ * fence through closing fence), or 0 when there is none (an unterminated block is not
+ * frontmatter). The fence is `locateFrontmatterFence`'s — the one owner the frontmatter reader
+ * and writer (`frontmatter.cts`) also read — so the normalizer skips exactly the block every
+ * reader sees (found while implementing #5105: this was a private mirror of the reader's
+ * fence rule, because `frontmatter.cts` imports this module, and the two drifted).
+ */
+function leadingFrontmatterLineCount(text) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(text);
+    if (!fence || !fence.closed)
+        return 0;
+    // The lines before the closing fence, plus the closing fence line itself.
+    return text.slice(0, fence.closingStart).split('\n').length;
+}
 function _normalizeMd(content) {
     if (!content || typeof content !== 'string')
         return content;
     let text = content.replace(/\r\n/g, '\n');
     const lines = text.split('\n');
+    // The frontmatter block is YAML, not markdown: its lines are published exactly as written.
+    // A `# comment` is not a heading, and a blank line inserted into a multi-line quoted scalar
+    // or removed from a block scalar changes the value (found while implementing #5105).
+    const frontmatterLines = leadingFrontmatterLineCount(text);
     const result = [];
     const fenceRegex = /^```/;
     const insideFence = new Array(lines.length);
     let fenceOpen = false;
     for (let i = 0; i < lines.length; i++) {
+        if (i < frontmatterLines) {
+            insideFence[i] = false;
+            continue;
+        }
         if (fenceRegex.test(lines[i].trimEnd())) {
             if (fenceOpen) {
                 insideFence[i] = false;
@@ -1058,6 +1087,10 @@ function _normalizeMd(content) {
     }
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (i < frontmatterLines) {
+            result.push(line);
+            continue;
+        }
         const prev = i > 0 ? lines[i - 1] : '';
         const prevTrimmed = prev.trimEnd();
         const trimmed = line.trimEnd();
@@ -1068,12 +1101,15 @@ function _normalizeMd(content) {
             if (i === 0 || !insideFence[i - 1])
                 result.push('');
         }
-        // #3854: the `!/^\s/.test(prev)` guard mirrors the after-a-bullet rule below —
-        // an indented non-bullet line is a CONTINUATION of the previous list item, not a
-        // preceding paragraph, so no separating blank may be injected before this bullet
-        // (that injection converted every tight multi-line list to a loose one on write).
-        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && !/^\s/.test(prev) && prevTrimmed !== '---')
-            result.push('');
+        // No "separate a list from a preceding paragraph" rule (#3854, #4725).
+        // This pass re-normalizes the ENTIRE document on every .md write, so an
+        // inserted blank before a bullet whose previous line is ordinary prose
+        // reflowed text the command never touched (converting tight lists to
+        // loose ones); #3854 first guarded the indented-continuation predecessor,
+        // #4725 removed the rule outright. A paragraph→list transition stays
+        // exactly as the author wrote it; a heading→list separation still comes
+        // from the after-heading rule below. The after-a-bullet rule at the end
+        // of this loop is a different transition (list→prose) and is unaffected.
         result.push(line);
         if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
             result.push('');
@@ -1085,8 +1121,11 @@ function _normalizeMd(content) {
                 result.push('');
         }
     }
+    // The frontmatter lines are `result`'s first entries, unchanged; the blank-run collapse
+    // applies from the line ending that closes the block onward.
+    const head = result.slice(0, frontmatterLines).join('\n');
     text = result.join('\n');
-    text = text.replace(/\n{3,}/g, '\n\n');
+    text = head + text.slice(head.length).replace(/\n{3,}/g, '\n\n');
     text = text.replace(/\n*$/, '\n');
     return text;
 }

package/gsd-core/bin/lib/smart-entry.cjs

@@ -55,7 +55,7 @@ const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
-const { extractFrontmatter } = frontmatter;
+const { extractFrontmatter, frontmatterBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
 const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
@@ -71,6 +71,10 @@ const { readStateHeadFreshness } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInput = require("./unusable-input.cjs");
 const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
+// #5118: the verification-status owner's frontmatter-only report check.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
+const { findVerificationStatusError } = verificationMod;
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * Staleness threshold for idle-stranded detection. A clean tree whose last
@@ -285,11 +289,20 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     catch {
         return false;
     }
+    // #5118: this phase's VERIFICATION report `status` is judged by its owner
+    // (src/verification.cts, the same frontmatter-only, containment-checked
+    // locator every reader shares) — an out-of-set value is the owner's hard
+    // error here as at every other reader, never a silent "not failed". The
+    // body `STATUS:` marker scan below is this probe's own signal.
+    const statusError = findVerificationStatusError([latestDir]);
+    if (statusError)
+        throw statusError;
     const candidates = files.filter((f) => /summary|verif(?:y|ication)|uat/i.test(f));
     for (const name of candidates) {
         let content = '';
+        const filePath = node_path_1.default.join(latestDir, name);
         try {
-            content = node_fs_1.default.readFileSync(node_path_1.default.join(latestDir, name), 'utf-8');
+            content = node_fs_1.default.readFileSync(filePath, 'utf-8');
         }
         catch {
             continue;
@@ -311,7 +324,10 @@ function readStateFile(statePath) {
         return null;
     }
     const fm = extractFrontmatter(content, statePath);
-    const body = content.replace(/^---[\s\S]*?---\s*/, '');
+    // The body starts after the block `extractFrontmatter` just read (the one fence owner), so a
+    // `---` inside a value, a BOM, or an adjacent empty block cannot cut it somewhere else.
+    const block = frontmatterBlock(content);
+    const body = block ? block.rest.replace(/^\s+/, '') : content;
     return { fm, body };
 }
 /** Collect the full signal set from disk for `cwd`. Exported for unit tests. */