@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -1311,6 +1311,128 @@ function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
     }
     return { changed: changed, wrote: shouldWrite, path: hooksJsonPath };
 }
+/**
+ * Stage the `hooks/lib/` helpers a set of staged hook scripts require, walking
+ * the require graph TRANSITIVELY to a fixed point.
+ *
+ * Extracted from writeCursorHooksJson (#3911 review, commit 704859e9c) so the
+ * reduced Codex hook bundle can share one implementation instead of growing a
+ * second, divergent copy (#4087 / #4098). Both reduced bundles hand-pick which
+ * hook SCRIPTS they ship, and neither can hand-pick their helpers correctly for
+ * long: `hooks/lib/hook-exit.js` requires `./cli-exit.js`, which requires
+ * `./exit-code-registry.js` — with NO `./lib/` prefix, because from inside
+ * `lib/` the sibling is already local. A single-pass scan for the `./lib/…`
+ * spelling used FROM a hook script stages hook-exit.js and stops, and the
+ * installed hook then dies on MODULE_NOT_FOUND at load, before its own
+ * try/catch, on every event it is registered for.
+ *
+ * Scans CONTENT rather than paths so a caller can seed from whatever it staged,
+ * transformed or not, without this helper knowing the caller's layout.
+ *
+ * @returns the lib filenames actually staged, in staging order.
+ */
+function stageTransitiveHookLibs(opts) {
+    const { seedSources, srcLibDir, destLibDir, runtimeLabel, transform } = opts;
+    const requiredLibFiles = new Set();
+    const scannedLibFiles = new Set();
+    const staged = [];
+    // `./X` means DIFFERENT things depending on where the scanned file lives, and
+    // conflating them stages the wrong file. From a hook SCRIPT in hooks/, a bare
+    // `./X` is a sibling hook-level artifact — Codex's gsd-check-update-worker.js
+    // requires `./managed-hooks-registry.cjs`, which lives in hooks/, not
+    // hooks/lib/ — so only the explicit `./lib/X` spelling is a lib requirement.
+    // From inside a LIB file, the sibling is already local, so `./X` IS a lib
+    // requirement (hook-exit.js -> ./cli-exit.js -> ./exit-code-registry.js); that
+    // is the case 704859e9c added and it must keep working. Cursor never exposed
+    // the difference because none of its staged scripts has a bare sibling
+    // require; Codex's does, and the fail-loud guard below caught it immediately
+    // by demanding managed-hooks-registry.cjs out of hooks/dist/lib.
+    // Fresh per call: a module-level /g regex carries lastIndex across calls and
+    // would silently skip matches on the second install in one process.
+    const seedRequireRe = /require\(\s*['"]\.\/lib\/([A-Za-z0-9._-]+)['"]\s*\)/g;
+    const libRequireRe = /require\(\s*['"]\.\/(?:lib\/)?([A-Za-z0-9._-]+)['"]\s*\)/g;
+    // A NESTED helper path is outside the flat layout hooks/lib/ has and the
+    // build emits, and the character classes above cannot express it — so it
+    // would be a SILENT miss, staging nothing and shipping a hook that dies at
+    // load. Detected separately and refused loudly instead: a silent miss is the
+    // failure mode this whole function exists to remove (review of #4087).
+    const nestedRequireRe = /require\(\s*['"]\.\/lib\/[A-Za-z0-9._-]+\/[^'"]*['"]\s*\)/;
+    const scanForLibRequires = (source, fromLib) => {
+        if (nestedRequireRe.test(source)) {
+            throw new Error(`A staged ${runtimeLabel} hook requires a NESTED hooks/lib path. hooks/lib/ is flat and `
+                + 'this stager only resolves flat helper names, so the nested helper would never be '
+                + 'staged and the hook would throw MODULE_NOT_FOUND at load. Flatten the helper or '
+                + 'extend this stager deliberately.');
+        }
+        const re = fromLib ? libRequireRe : seedRequireRe;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const candidate = m[1];
+            // A capture with no alphanumeric character is not a module name — it is
+            // prose. This scan reads whole file text, comments included, and
+            // hooks/lib/injection-patterns.js's own header documents this mechanism
+            // with the literal string `require('./lib/...')`, which captures `...`
+            // and would send the resolver hunting for `hooks/lib/...` and fail the
+            // install (measured; that helper is not staged for either reduced bundle
+            // today, so it is latent rather than live).
+            //
+            // KNOWN LIMIT, disclosed rather than papered over: this does NOT make the
+            // scan comment-aware. A comment naming a REAL helper — `require(
+            // './lib/git-cmd.js')` in prose — still registers it and would over-stage
+            // that helper. Closing that needs a comment-stripping pass; the
+            // line-based stripper in scripts/lint-hooks-runtime-build-seam.cjs is the
+            // precedent (its header explains why the naive two-regex strip corrupts
+            // these very files), but promoting a lint-script helper into installer
+            // runtime code is a larger change than this fix.
+            if (!/[A-Za-z0-9]/.test(candidate))
+                continue;
+            requiredLibFiles.add(candidate);
+        }
+    };
+    for (const source of seedSources)
+        scanForLibRequires(source, false);
+    if (requiredLibFiles.size === 0)
+        return staged;
+    node_fs_1.default.mkdirSync(destLibDir, { recursive: true });
+    // Iterate to a fixed point: staging a lib file can add MORE required lib
+    // files (its own requires), which must themselves be staged and scanned.
+    let libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
+    while (libFile !== undefined) {
+        scannedLibFiles.add(libFile);
+        // Node's own extension resolution: `require('./lib/x')` is a valid, working
+        // CommonJS spelling today, and matching only the extension-bearing form
+        // resolved `x` literally, found nothing, and failed the install on a
+        // legitimate require (review of #4087). Try the bare name first so an
+        // extension-bearing capture still wins, then .js/.cjs.
+        let resolvedName;
+        for (const candidate of [libFile, `${libFile}.js`, `${libFile}.cjs`]) {
+            if (node_fs_1.default.existsSync(node_path_1.default.join(srcLibDir, candidate))) {
+                resolvedName = candidate;
+                break;
+            }
+        }
+        const libSrc = node_path_1.default.join(srcLibDir, resolvedName ?? libFile);
+        if (resolvedName === undefined) {
+            // FAIL LOUD. Skipping here would ship hook scripts whose top-level
+            // require() throws before their own try/catch, wedging every session —
+            // and the install would still exit 0, so nobody would know until a user
+            // hit it. A missing helper source is a packaging bug; surface it.
+            throw new Error(`hooks/lib/${libFile} is required by a staged ${runtimeLabel} hook but is missing from ${srcLibDir}. `
+                + 'Installing would ship a hook that throws MODULE_NOT_FOUND at load.');
+        }
+        let libContent = node_fs_1.default.readFileSync(libSrc, 'utf8');
+        if (transform)
+            libContent = transform(libContent);
+        // Written under its RESOLVED name so an extensionless require still lands a
+        // file Node can resolve at the destination.
+        node_fs_1.default.writeFileSync(node_path_1.default.join(destLibDir, resolvedName), libContent);
+        staged.push(resolvedName);
+        scanForLibRequires(libContent, true);
+        libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
+    }
+    return staged;
+}
 function writeCursorHooksJson(targetDir, src, opts) {
     opts = opts || {};
     const hooksDir = node_path_1.default.join(targetDir, 'hooks');
@@ -1348,43 +1470,13 @@ function writeCursorHooksJson(targetDir, src, opts) {
     // "./lib/X" requires, and every lib file staged is itself scanned for further
     // "./lib/X" OR bare "./X" (sibling-within-lib) requires, so the requirement
     // graph is derived to a fixed point instead of one hand-tuned level deep.
-    const requiredLibFiles = new Set();
-    const scannedLibFiles = new Set();
-    const libRequireRe = /require\(\s*['"]\.\/(?:lib\/)?([A-Za-z0-9._-]+)['"]\s*\)/g;
-    function scanForLibRequires(source) {
-        libRequireRe.lastIndex = 0;
-        let m;
-        while ((m = libRequireRe.exec(source)) !== null)
-            requiredLibFiles.add(m[1]);
-    }
-    for (const script of installedScripts) {
-        scanForLibRequires(node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8'));
-    }
-    if (requiredLibFiles.size > 0) {
-        const srcLibDir = node_path_1.default.join(srcHooksDir, 'lib');
-        const destLibDir = node_path_1.default.join(hooksDir, 'lib');
-        node_fs_1.default.mkdirSync(destLibDir, { recursive: true });
-        // Iterate to a fixed point: staging a lib file can add MORE required lib
-        // files (its own requires), which must themselves be staged and scanned.
-        let libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
-        while (libFile !== undefined) {
-            scannedLibFiles.add(libFile);
-            const libSrc = node_path_1.default.join(srcLibDir, libFile);
-            if (!node_fs_1.default.existsSync(libSrc)) {
-                // FAIL LOUD. Skipping here would ship hook scripts whose top-level
-                // require() throws before their own try/catch, wedging every session —
-                // and the install would still exit 0, so nobody would know until a user
-                // hit it. A missing helper source is a packaging bug; surface it.
-                throw new Error(`hooks/lib/${libFile} is required by a staged Cursor hook but is missing from ${srcLibDir}. `
-                    + 'Installing would ship a hook that throws MODULE_NOT_FOUND at load.');
-            }
-            let libContent = node_fs_1.default.readFileSync(libSrc, 'utf8');
-            libContent = libContent.replace(/gsd:/gi, 'gsd-');
-            node_fs_1.default.writeFileSync(node_path_1.default.join(destLibDir, libFile), libContent);
-            scanForLibRequires(libContent);
-            libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
-        }
-    }
+    stageTransitiveHookLibs({
+        seedSources: [...installedScripts].map((script) => node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8')),
+        srcLibDir: node_path_1.default.join(srcHooksDir, 'lib'),
+        destLibDir: node_path_1.default.join(hooksDir, 'lib'),
+        runtimeLabel: 'Cursor',
+        transform: (content) => content.replace(/gsd:/gi, 'gsd-'),
+    });
     // #2717: write the CommonJS marker into hooks/ alongside the staged .js
     // scripts. Cursor sets skipSharedHooksInstall, so it never reaches
     // installSharedHooksBundle (the only other writer of this marker); without
@@ -1587,6 +1679,26 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
             installedScripts.add(script);
         }
     }
+    // Stage the hooks/lib/ helpers these scripts require (#4087 review). Windsurf
+    // sets hostBehaviors.skipSharedHooksInstall, so like Cursor it never reaches
+    // installSharedHooksBundle — the only other stager of hooks/lib — and it was
+    // staging neither. Both Cascade guards require helpers at module load:
+    // gsd-windsurf-pre-write.js requires ./lib/hook-exit.js and ./lib/git-probe.js,
+    // gsd-windsurf-pre-command.js requires ./lib/hook-exit.js. Measured against a
+    // real `--windsurf --global` install before this call existed: the installer
+    // exited 0, hooks/ held only the two scripts, and running either one exited 1
+    // with "Cannot find module './lib/hook-exit.js'" — the same failure #4087
+    // reports for Codex, on every pre_write_code / pre_run_command event.
+    //
+    // The transform matches the one applied to the scripts above: a helper must be
+    // rewritten the same way as its caller or the two disagree on the spelling.
+    stageTransitiveHookLibs({
+        seedSources: [...installedScripts].map((script) => node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8')),
+        srcLibDir: node_path_1.default.join(srcHooksDir, 'lib'),
+        destLibDir: node_path_1.default.join(hooksDir, 'lib'),
+        runtimeLabel: 'Windsurf',
+        transform: (content) => content.replace(/gsd:/gi, 'gsd-'),
+    });
     // #2717: write the CommonJS marker into hooks/ alongside the staged .js
     // scripts. Windsurf sets skipSharedHooksInstall, so it never reaches
     // installSharedHooksBundle (the only other writer of this marker); without
@@ -1737,6 +1849,37 @@ function applySettingsJsonHooks(settings, opts) {
         if (!settings.hooks.SessionStart) {
             settings.hooks.SessionStart = [];
         }
+        // #3981: Claude Code treats a timed-out hook as NON-blocking — the tool
+        // call continues through the normal permission flow. The blocking
+        // PreToolUse guards therefore need a budget a host stall cannot exceed,
+        // not one sized to the hook's own ~0.1 s runtime. Observed stalls reached
+        // 84.3 s; 120 s is the top of the issue's prescribed 60–120 range and
+        // returns every observed verdict. Registration below uses this constant,
+        // and the migration pass right here raises existing managed entries.
+        const BLOCKING_GUARD_TIMEOUT_S = 120;
+        const blockingGuardNames = [
+            'gsd-prompt-guard',
+            'gsd-workflow-guard',
+            'gsd-worktree-path-guard',
+            'gsd-agent-isolation-guard',
+            'gsd-write-guard',
+            'gsd-secret-read-guard',
+            'gsd-validate-commit',
+        ];
+        for (const entries of Object.values(settings.hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                if (!entry || !Array.isArray(entry.hooks))
+                    continue;
+                for (const h of entry.hooks) {
+                    if (blockingGuardNames.some((name) => referencesHook(h, name)) &&
+                        h.timeout === 5) {
+                        h.timeout = BLOCKING_GUARD_TIMEOUT_S;
+                    }
+                }
+            }
+        }
         const hasGsdUpdateHook = settings.hooks.SessionStart.some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-check-update')));
         // Guard: only register if the hook file was actually installed (#1754).
         // When hooks/dist/ is missing from the npm package (as in v1.32.0), the
@@ -1817,7 +1960,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: promptGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1894,7 +2037,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: workflowGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1919,7 +2062,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: worktreePathGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1949,7 +2092,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: agentIsolationGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1976,7 +2119,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: writeGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1985,6 +2128,33 @@ function applySettingsJsonHooks(settings, opts) {
         else if (!hasWriteGuardHook && !node_fs_1.default.existsSync(writeGuardFile)) {
             console.warn(`  ${yellow}⚠${reset}  Skipped write guard hook — gsd-write-guard.js not found at target`);
         }
+        // Configure PreToolUse hook for secret-file read protection (#4221).
+        // Hard-blocks Read/Grep/Bash reads of .env, .env.<suffix> and .secrets.
+        // Replaces the Read(.env*) permission deny rules the installer used to
+        // write (#768): on Claude Code >= 2.1.259 ANY Read() deny rule makes every
+        // `cd DIR && grep …` compound prompt for approval, even in auto mode; a
+        // hook denial is not a permission rule and never arms that check.
+        const secretReadGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-secret-read-guard.js', hookOpts)
+            : localCmd('gsd-secret-read-guard.js');
+        const hasSecretReadGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-secret-read-guard')));
+        const secretReadGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-secret-read-guard.js');
+        if (!hasSecretReadGuardHook && node_fs_1.default.existsSync(secretReadGuardFile) && secretReadGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                matcher: 'Read|Grep|Bash',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: secretReadGuardCommand,
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured secret read guard hook (.env / .secrets read protection)`);
+        }
+        else if (!hasSecretReadGuardHook && !node_fs_1.default.existsSync(secretReadGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped secret read guard hook — gsd-secret-read-guard.js not found at target`);
+        }
         // Configure commit validation hook (Conventional Commits enforcement, opt-in)
         const validateCommitCommand = isGlobal
             ? buildHookCommand(targetDir, 'gsd-validate-commit.sh', hookOpts)
@@ -2001,7 +2171,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: validateCommitCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -2330,6 +2500,7 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'PreToolUse', command: cmd('gsd-read-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-worktree-path-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-write-guard.js'), matcher: 'WriteFile', timeout: 5 },
+        { event: 'PreToolUse', command: cmd('gsd-secret-read-guard.js'), matcher: 'ReadFile|Grep|Shell', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: 5 },
         // PostToolUse
@@ -2532,6 +2703,7 @@ module.exports = {
     KIMI_HOOKS_TOML_MARKER_BEGIN,
     KIMI_HOOKS_TOML_MARKER_END,
     // Shared
+    stageTransitiveHookLibs,
     buildHookCommand,
     applySettingsJsonHooks,
     referencesHook,

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

@@ -242,6 +242,8 @@ const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
         'gsd-write-guard.js',
         'gsd-agent-isolation-guard.js',
         'gsd-worktree-path-guard.js',
+        // #4221: secret-file read guard (Read|Grep|Bash).
+        'gsd-secret-read-guard.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -269,6 +271,8 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-write-guard.js',
         'gsd-agent-isolation-guard.js',
         'gsd-worktree-path-guard.js',
+        // #4221: secret-file read guard (Read|Grep|Bash).
+        'gsd-secret-read-guard.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',

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

@@ -64,7 +64,7 @@ const stateDocument = require("./state-document.cjs");
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseId = require("./phase-id.cjs");
-const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, stripProjectCodePrefix } = phaseId;
+const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, parsePhaseFromProse, stripProjectCodePrefix } = phaseId;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateMod = require("./state.cjs");
 const { readStateHeadFreshness } = stateMod;
@@ -233,10 +233,7 @@ function readGitSignals(cwd) {
 }
 /** Leading numeric phase token from a STATE.md scalar or body `Phase:` value. */
 function phaseTokenFromState(raw) {
-    if (!raw?.trim())
-        return null;
-    const match = raw.trim().match(/^(\d+(?:[A-Z])?(?:\.\d+)*)/i);
-    return match ? match[1] : null;
+    return parsePhaseFromProse(raw).phase;
 }
 /**
  * Detect whether the current phase's verify report indicates failure. The
@@ -429,7 +426,7 @@ function detectSignals(cwd, now = Date.now) {
     const stateHeadRaw = stateFieldValue(fm, body, 'state_head', 'State Head').value;
     const freshness = readStateHeadFreshness(cwd, stateHeadRaw);
     return {
-        current_phase: parseIntOrNull(currentPhaseRaw),
+        current_phase: phaseTokenFromState(currentPhaseRaw),
         total_phases: parseIntOrNull(totalPhasesRaw),
         status: (statusRaw || '').toLowerCase(),
         progress: parseIntOrNull(progressRaw),
@@ -472,11 +469,12 @@ function isComplete(s) {
             return false;
     }
     else {
-        // Legacy path: STATE.md comparison. Still subject to the two-scale bug,
-        // but only fires when ROADMAP.md is absent or has no Progress table.
+        // Legacy path: STATE.md comparison. It only fires when ROADMAP.md is
+        // absent or has no Progress table, and uses canonical phase-id ordering
+        // so dotted phase ids are never coerced to JavaScript numbers.
         if (s.total_phases === null || s.current_phase === null)
             return false;
-        if (s.current_phase < s.total_phases)
+        if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
             return false;
     }
     // Status regex: require milestone-level completion language. The pre-fix

package/gsd-core/bin/lib/state-document.cjs

@@ -512,17 +512,42 @@ function stateCurrentPositionSlice(body) {
     const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, isCurrentPosition, { levelBounded: true });
     return section ? section.body : null;
 }
+/**
+ * Join a matched `**Field:**`/`Field:` label prefix to its new value, inserting a
+ * single space when the prefix does not already end in same-line whitespace.
+ *
+ * On an empty field the same-line `[ \t]*` gap (below) captures nothing, so the
+ * bare `prefix + value` would glue the value to the label (`**Status:**value`);
+ * this inserts the missing separator. A non-empty field whose label-to-value
+ * separator is ordinary space/tab keeps that separator in the prefix, so `[ \t]$`
+ * is true and the output stays byte-identical to prior behaviour. The one
+ * exception is a non-empty field written with NO separator at all (a hand-edited
+ * `**Status:**value`): the narrowed gap captures nothing, `[ \t]$` is false, and a
+ * single space is inserted — an intentional normalization, not byte-identical, and
+ * with no GSD-template trigger. An empty new value inserts no separator, avoiding a
+ * dangling trailing space. See #4010.
+ */
+function joinFieldReplacement(prefix, newValue) {
+    const value = `${newValue}`;
+    const needsSeparator = value.length > 0 && !/[ \t]$/.test(prefix);
+    return `${prefix}${needsSeparator ? ' ' : ''}${value}`;
+}
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
-    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+    // The label-to-value gap is same-line whitespace only (`[ \t]*`, mirroring the
+    // read side at stateExtractField). `\s*` here matched `\n`, so on an empty field
+    // `(.*)` captured the following line and the rebuild discarded it — the #4010
+    // data-loss. ADR-3180 §7.7 makes stateExtractField the same-line-confined owner;
+    // this aligns the writer to it.
+    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*[ \\t]*)(.*)`, 'i');
     if (boldPattern.test(content)) {
-        return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+        return content.replace(boldPattern, (_match, prefix) => joinFieldReplacement(prefix, newValue));
     }
-    // Plain line-start format: FieldName: value
-    const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+    // Plain line-start format: FieldName: value (same same-line confinement as above)
+    const plainPattern = new RegExp(`(^${escaped}:[ \\t]*)(.*)`, 'im');
     if (plainPattern.test(content)) {
-        return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+        return content.replace(plainPattern, (_match, prefix) => joinFieldReplacement(prefix, newValue));
     }
     // Pipe-table format: | FieldName | value |
     // Preserve the surrounding pipe/whitespace structure; only swap the value cell.

package/gsd-core/bin/lib/state-md-schema.cjs

@@ -128,19 +128,29 @@ exports.STATE_FIELD_SCHEMA = Object.freeze(Object.assign(Object.create(null), {
         // (verified: it calls `stateExtractField(bodyContent, 'Current Plan')`
         // only), so that shape is out of scope for this row regardless.
         //
-        // #3784 is the open issue for teaching `Current Plan` to read the
-        // hybrid shape; **PR #3791** ("fix(#3784): read the hybrid
-        // `Current Plan: N of M` shape, keep zero-padding, and name the
-        // accepted shapes on failure") is the in-flight fix. Do NOT widen
-        // this row speculatively — that would assert a shape the shipped
-        // parser does not accept, which is the exact defect class §8.8
-        // exists to make impossible. When #3791 merges, `acceptedShapes`
-        // MUST widen to `['N', 'N of M']` — until then, the row 23/24/25
-        // parser-shape tests (`tests/state-transition.test.cjs`) will go RED
-        // the moment the parser changes underneath it. That failure is the
-        // forcing function working as designed, not a broken test: it is
-        // what stops the schema and the parser from drifting apart silently.
-        acceptedShapes: Object.freeze(['N']),
+        // #3784/#3791 WIDENED THIS ROW. The paragraph above describes the
+        // pre-#3791 parser and is kept as the record of what the shape was
+        // before, because row 25 exists to stop exactly that reading from
+        // being re-asserted by accident.
+        //
+        // `advancePlanCore` now accepts the hybrid shape, so the declared set
+        // is `['N', 'N of M']`. Two properties of the widening matter to a
+        // future reader:
+        //
+        //   - It is ANCHORED. The parser matches `/^(\d+)\s+of\s+(\d+)\s*$/`
+        //     against the whole value, so `4 — blocked on review of 2 PRs`
+        //     is REJECTED rather than yielding a total of 2 out of prose.
+        //     Declaring `'N of M'` is a claim about that grammar, not about
+        //     "contains the word of".
+        //   - `'N/M'` stays UNDECLARED and must keep failing. Row 23 probes
+        //     the undeclared remainder of `SHAPE_EXAMPLES`, so it needs at
+        //     least one member outside the declared set to stay non-vacuous.
+        //
+        // Widening this row without widening the parser (or the reverse) goes
+        // RED on rows 23/24/25. That coupling is the forcing function, and it
+        // is the reason this row is data rather than a predicate: §8.8's
+        // "parsers are checked, not generated".
+        acceptedShapes: Object.freeze(['N', 'N of M']),
         emitted: 'when-present',
     },
     // Status / lifecycle (body-derived; #1230 delta heuristic applies)