@opengsd/gsd-core 1.17.0 → 1.19.0

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

@@ -1264,10 +1264,10 @@ function configuredEntrypointsForHook(configDir, hookName, opts) {
     const bash = resolveBashExecutable(opts);
     if (isShellHook) {
         // An unresolved bash must still surface as an interpreterCandidates entry
-        // (the literal token, same as the portableHooks runner below) so
+        // (the sentinel token, same as the portableHooks runner below) so
         // validateConfiguredEntrypoints reports 'unresolved-interpreter' instead
         // of silently skipping the check because the field is absent.
-        return [{ ...target, interpreterCandidates: [bash === null ? 'bash' : bash] }];
+        return [{ ...target, interpreterCandidates: [bash === null ? UNRESOLVED_BASH_SENTINEL : bash] }];
     }
     // #4249: check the SAME stable alias buildNodeRunnerChainToken bakes as its
     // first candidate (normalizeNodePath rewrites a version-manager shim like
@@ -1287,7 +1287,7 @@ function configuredEntrypointsForHook(configDir, hookName, opts) {
         runtime,
         configPath,
         scriptPath: node_path_1.default.join(configDir, 'hooks', NODE_RUNNER_RESOLVER_HOOK),
-        interpreterCandidates: bash === null ? ['bash'] : [bash],
+        interpreterCandidates: bash === null ? [UNRESOLVED_BASH_SENTINEL] : [bash],
         platform,
     };
     return [runner, { ...target, interpreterCandidates: nodeCandidates }];
@@ -1298,6 +1298,15 @@ function recordConfiguredHookCommand(command, configDir, hookName, opts) {
     }
     return command;
 }
+// #5100: the two null-runner branches of buildHookCommand share this. No
+// command was ever built, so track() (which needs one) cannot record the
+// hook — push the entry directly instead, so the gate sees it rather than
+// the hook going silently unregistered.
+function recordUnresolvedBashEntrypoint(configDir, hookName, opts) {
+    if (opts.configuredEntrypoints) {
+        opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
+    }
+}
 function buildHookCommand(configDir, hookName, opts) {
     if (!opts)
         opts = {};
@@ -1323,15 +1332,9 @@ function buildHookCommand(configDir, hookName, opts) {
         const runner = resolveBashRunner(opts);
         if (runner === null) {
             // #4249 (antigravity review): this early return skips `track()` below,
-            // so an unresolved bash on win32 (no Git Bash found) previously left
-            // this hook silently unregistered with nothing for
-            // validateConfiguredEntrypoints to reject — configuredEntrypointsForHook's
-            // own 'unresolved bash must still surface' comment describes intent this
-            // return never reached. Push the entry directly (no `command`, since
-            // none was ever built) so the gate actually sees it.
-            if (opts.configuredEntrypoints) {
-                opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
-            }
+            // which needs a command that was never built — record the entry
+            // directly so the gate can reject it.
+            recordUnresolvedBashEntrypoint(configDir, hookName, opts);
             return null;
         }
         if (opts.portableHooks) {
@@ -1374,9 +1377,13 @@ function buildHookCommand(configDir, hookName, opts) {
             configDir,
             homeDir: node_os_1.default.homedir(),
         });
-        // Absolute Git-Bash discovery on win32 when available (#580); `bash` on
-        // PATH otherwise — the same assumption .sh hooks already make.
-        const resolverRunner = resolveBashRunner(opts) || 'bash';
+        // #5100: same contract as the .sh early return. A bare `bash` is how
+        // win32 reaches WSL's System32 launcher, and the gate used to accept it.
+        const resolverRunner = resolveBashRunner(opts);
+        if (resolverRunner === null) {
+            recordUnresolvedBashEntrypoint(configDir, hookName, opts);
+            return null;
+        }
         return track(shellCmdProjection.projectShellCommandText({
             runnerToken: resolverRunner,
             argTokens: [
@@ -2158,6 +2165,9 @@ const SETTINGS_JSON_HOOK_ROWS = deepFreeze([
     // Guard: only register if the hook file was actually installed (#1754, #1817).
     { file: 'gsd-check-update.js', event: 'SessionStart', command: { opts: 'updateCheckCommand' },
         configuredMessage: 'Configured update check hook', skipLabel: 'update check hook' },
+    // #5465: persists the gsd-core bin directory on PATH through $CLAUDE_ENV_FILE (SessionStart-only).
+    { file: 'gsd-path-export.js', event: 'SessionStart', timeout: 5, command: { build: 'js' },
+        configuredMessage: 'Configured PATH persistence hook', skipLabel: 'PATH persistence hook' },
     { file: 'gsd-context-monitor.js', event: 'post', matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task', timeout: 10,
         command: { opts: 'contextMonitorCommand' },
         configuredMessage: 'Configured context window monitor hook', skipLabel: 'context monitor hook',
@@ -2710,6 +2720,30 @@ function referencesHook(h, hookName) {
         (Array.isArray(args) && args.some(a => typeof a === 'string' && a.includes(hookName))) ||
         (typeof url === 'string' && url.includes(hookName));
 }
+// #5100: the writer emits the bare `bash` token when the Git Bash policy
+// finds nothing, and the gate resolves that token through the same policy —
+// never a PATH scan. One shared definition so the two sides cannot drift.
+const UNRESOLVED_BASH_SENTINEL = 'bash';
+const WIN32_BARE_BASH_TOKENS = [UNRESOLVED_BASH_SENTINEL, 'bash.exe'];
+function isWin32BareBashToken(candidate, platform) {
+    if ((platform || process.platform) !== 'win32')
+        return false;
+    // Equality already rejects any path: a string holding a separator can never
+    // equal a bare token, so no explicit separator guard is needed here.
+    return WIN32_BARE_BASH_TOKENS.includes(candidate.trim().toLowerCase());
+}
+// #5100: the literal `bash` sentinel means "Git Bash policy found nothing"
+// (#4249). Resolve that token through resolveBashExecutable, never a PATH
+// scan — WSL's System32\bash.exe is on PATH and cannot see Windows paths.
+function win32BareBashResolves(candidate, platform, deps) {
+    if (!isWin32BareBashToken(candidate, platform))
+        return null;
+    return resolveBashExecutable({
+        platform: 'win32',
+        env: deps.env,
+        existsSync: deps.existsSync,
+    }) !== null;
+}
 function validateConfiguredEntrypoints(entries, deps = {}) {
     const statSync = deps.statSync ?? node_fs_1.default.statSync;
     const accessSync = deps.accessSync ?? node_fs_1.default.accessSync;
@@ -2766,7 +2800,12 @@ function validateConfiguredEntrypoints(entries, deps = {}) {
                 invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'not-executable' });
             }
         }
-        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null)) {
+        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => {
+            const bareBash = win32BareBashResolves(candidate, entry.platform, deps);
+            if (bareBash !== null)
+                return bareBash;
+            return resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null;
+        })) {
             invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'interpreter', path: entry.interpreterCandidates.join(' | '), reason: 'unresolved-interpreter' });
         }
     }
@@ -2856,6 +2895,11 @@ module.exports = {
     resolveBashExecutable,
     resolveBashRunner,
     NODE_RUNNER_RESOLVER_HOOK,
+    // #5100: the literal the writer records for an unresolved Git Bash and the
+    // gate resolves through the Git Bash policy. Exported so a consumer that
+    // needs to recognise that entry imports it rather than respelling it;
+    // bin/install.js keys on the entry having no command instead.
+    UNRESOLVED_BASH_SENTINEL,
     // Atomic write seam (shared with bin/install.js so all writes participate
     // in install.js's _cleanTmpFiles() scoped temp-cleanup).
     atomicWriteFileSync,

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

@@ -65,7 +65,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 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 markdown_line_diff_cjs_1 = require("./markdown-line-diff.cjs");
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -249,6 +251,8 @@ const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
         'gsd-worktree-path-guard.js',
         // #4221: secret-file read guard (Read|Grep|Bash).
         'gsd-secret-read-guard.js',
+        // #5465: SessionStart PATH persistence through $CLAUDE_ENV_FILE.
+        'gsd-path-export.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -279,6 +283,8 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-worktree-path-guard.js',
         // #4221: secret-file read guard (Read|Grep|Bash).
         'gsd-secret-read-guard.js',
+        // #5465: SessionStart PATH persistence through $CLAUDE_ENV_FILE.
+        'gsd-path-export.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -613,8 +619,20 @@ function execGit(args, opts = {}) {
     // Non-interactive defaults: a hung credential prompt or terminal-input
     // probe must surface as a timeout, not block the tool forever. Callers
     // can override via opts.env.
+    //
+    // #5048: readOnlyGitEnv() as well. execGit is the shared seam behind every
+    // git call the tool makes, including the read-only ones (`status`,
+    // `diff --cached`, `rev-parse`, `log`, …). By default git refreshes the index
+    // and takes an *optional* `.git/index.lock` to write the refreshed copy back,
+    // so a read can lose a race against a real `git add` / `git commit` and fail
+    // it with `Unable to create '.git/index.lock': File exists`. The owner is
+    // src/read-only-git-env.cts, shared with every other read-only seam, so this
+    // call site cannot drift from them. The variable disables only those optional
+    // index operations; a caller that genuinely needs one (a writing command, or a
+    // status whose freshness it wants persisted) can still set it back through
+    // opts.env, which is spread last on purpose.
     const env = {
-        ...process.env,
+        ...(0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
         GIT_TERMINAL_PROMPT: '0',
         GCM_INTERACTIVE: 'never',
         ...(opts.env || {}),
@@ -1053,16 +1071,40 @@ function leadingFrontmatterLineCount(text) {
     // The lines before the closing fence, plus the closing fence line itself.
     return text.slice(0, fence.closingStart).split('\n').length;
 }
-function _normalizeMd(content) {
+/** A leading BOM is not part of the first line's content when aligning two documents. */
+function withoutBom(line) {
+    return line !== undefined && line.charCodeAt(0) === 0xFEFF ? line.slice(1) : (line ?? '');
+}
+function _normalizeMd(content, prior) {
     if (!content || typeof content !== 'string')
         return content;
     let text = content.replace(/\r\n/g, '\n');
     const lines = text.split('\n');
+    // #5165: when the document being replaced is known, only the junctions the
+    // write touched are normalized; every other region stays byte-identical.
+    let scope = null;
+    let priorLines = [];
+    if (typeof prior === 'string' && prior !== '') {
+        priorLines = prior.replace(/\r\n/g, '\n').split('\n');
+        // A BOM on either first line must not make an unchanged line look rewritten.
+        const alignPrior = [withoutBom(priorLines[0]), ...priorLines.slice(1)];
+        const alignNext = [withoutBom(lines[0]), ...lines.slice(1)];
+        const match = (0, markdown_line_diff_cjs_1.matchLines)(alignPrior, alignNext);
+        if (match)
+            scope = (0, markdown_line_diff_cjs_1.writeScope)(match, priorLines.length);
+    }
     // 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 = [];
+    // A separating blank the rules add. In scoped mode (#5165) two rules that fire on
+    // the same junction add ONE blank: the whole-document pass collapses them in its
+    // final blank-run regex, which scoped mode must not apply to runs the write kept.
+    const blank = () => {
+        if (scope === null || result[result.length - 1] !== '')
+            result.push('');
+    };
     const fenceRegex = /^```/;
     const insideFence = new Array(lines.length);
     let fenceOpen = false;
@@ -1095,11 +1137,23 @@ function _normalizeMd(content) {
         const prevTrimmed = prev.trimEnd();
         const trimmed = line.trimEnd();
         const isFenceLine = fenceRegex.test(trimmed);
-        if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---')
-            result.push('');
-        if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine)) {
+        // A heading or fence line the write authored brings its own separation, even
+        // where it replaced a prose line in place (#5165). One that replaced a heading
+        // or fence (a rename, a renumber) inherits the spacing around it instead.
+        const isStructural = (text) => /^#{1,6}\s/.test(text.trimEnd()) || fenceRegex.test(text.trimEnd());
+        const replacedPrior = scope !== null ? scope.replacedPriorIndex(i) : -1;
+        const authoredStructure = scope !== null && scope.lineWritten(i) && isStructural(line)
+            && !(replacedPrior >= 0 && isStructural(priorLines[replacedPrior] ?? ''));
+        const keptBefore = scope !== null && !authoredStructure && i > 0 && scope.junctionKept(i - 1);
+        const keptAfter = scope !== null && !authoredStructure && i < lines.length - 1 && scope.junctionKept(i);
+        // A blank-line run is collapsed only where the write made it (#5165).
+        if (scope !== null && line === '' && result.length > 0 && result[result.length - 1] === '' && !keptBefore)
+            continue;
+        if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---' && !keptBefore)
+            blank();
+        if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine) && !keptBefore) {
             if (i === 0 || !insideFence[i - 1])
-                result.push('');
+                blank();
         }
         // No "separate a list from a preceding paragraph" rule (#3854, #4725).
         // This pass re-normalizes the ENTIRE document on every .md write, so an
@@ -1111,30 +1165,32 @@ function _normalizeMd(content) {
         // 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('');
-        if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
-            result.push('');
-        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1) {
+        if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '' && !keptAfter)
+            blank();
+        if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '' && !keptAfter)
+            blank();
+        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1 && !keptAfter) {
             const next = lines[i + 1];
             if (next !== undefined && next.trimEnd() !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(next) && !/^\s/.test(next))
-                result.push('');
+                blank();
         }
     }
     // 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 = head + text.slice(head.length).replace(/\n{3,}/g, '\n\n');
+    text = scope === null ? head + text.slice(head.length).replace(/\n{3,}/g, '\n\n') : text;
     text = text.replace(/\n*$/, '\n');
     return text;
 }
 function normalizeContent(filePath, content, opts = {}) {
     const encoding = opts.encoding ?? 'utf-8';
+    if (opts.verbatim === true)
+        return { content: content ?? '', encoding };
     const isMd = node_path_1.default.extname(filePath).toLowerCase() === '.md';
     let normalized;
     if (isMd) {
-        normalized = _normalizeMd(content);
+        normalized = _normalizeMd(content, opts.prior);
     }
     else {
         normalized = (content ?? '').replace(/\r\n/g, '\n').replace(/\n*$/, '\n');
@@ -1156,7 +1212,7 @@ function normalizeContent(filePath, content, opts = {}) {
  * do not simplify this back to a direct string comparison.
  */
 function contentChangedAfterNormalize(filePath, before, after) {
-    return normalizeContent(filePath, after).content !== normalizeContent(filePath, before).content;
+    return normalizeContent(filePath, after, { prior: before }).content !== normalizeContent(filePath, before, { prior: before }).content;
 }
 // Rename errnos that are transient on Windows: a concurrent reader (or an AV
 // scanner / indexer) holding the target open makes renameSync fail briefly.
@@ -1208,8 +1264,59 @@ function retryRenameSync(fromPath, toPath) {
     if (err !== null)
         throw err;
 }
+/**
+ * Largest on-disk Markdown document read back as the `prior` of a scoped write.
+ * A larger file is normalized whole (the pre-#5165 behavior) rather than read and
+ * diffed on every write.
+ */
+const MAX_PRIOR_BYTES = 2 * 1024 * 1024;
+/**
+ * The Markdown document a write replaces, or undefined when there is none worth
+ * diffing against: no file, not a regular file (a FIFO or device reports size 0
+ * and would block or never end), unreadable, or larger than MAX_PRIOR_BYTES. The
+ * bound is enforced on the bytes actually read from one open descriptor, so a
+ * file that grows after the check cannot exceed it.
+ */
+function readPriorMarkdown(filePath, encoding) {
+    let fd;
+    try {
+        // O_NONBLOCK keeps opening a FIFO from waiting for a writer; it is absent on Windows.
+        fd = node_fs_1.default.openSync(filePath, node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NONBLOCK ?? 0));
+        const stat = node_fs_1.default.fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_PRIOR_BYTES)
+            return undefined;
+        // One byte of headroom: reading it means the file grew past what was measured.
+        const buffer = Buffer.alloc(stat.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = node_fs_1.default.readSync(fd, buffer, length, buffer.length - length, null);
+            if (read === 0)
+                break;
+            length += read;
+        }
+        if (length > stat.size)
+            return undefined;
+        return buffer.toString(encoding, 0, length);
+    }
+    catch {
+        return undefined; // no prior document (new file or unreadable): normalize it whole
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                node_fs_1.default.closeSync(fd);
+            }
+            catch { /* already closed */ }
+        }
+    }
+}
 function platformWriteSync(filePath, content, opts = {}) {
-    const { content: normalized, encoding } = normalizeContent(filePath, content, opts);
+    // #5165: a Markdown write is scoped to what it changed relative to the file it replaces.
+    let prior = opts.prior;
+    if (prior === undefined && opts.verbatim !== true && node_path_1.default.extname(filePath).toLowerCase() === '.md') {
+        prior = readPriorMarkdown(filePath, opts.encoding ?? 'utf-8');
+    }
+    const { content: normalized, encoding } = normalizeContent(filePath, content, { ...opts, prior });
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
     const tmpPath = filePath + '.tmp.' + process.pid;
     // Step 1: write the sibling tmp file. If THIS fails, nothing was published, so a

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

@@ -43,6 +43,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // #3696: the calendar-validity predicate moved to the STATE.md document module
 // so `state validate` can assert the same `last_activity` invariant this reader
@@ -222,6 +223,18 @@ function readGitSignals(cwd) {
                 windowsHide: true,
                 stdio: ['pipe', 'pipe', 'pipe'],
                 timeout: 10_000,
+                // #5048: readGitSignals runs `git status`, which by default refreshes
+                // the index and takes an *optional* `.git/index.lock` to write the
+                // refreshed copy back. That lock is the one a real `git add` / `git
+                // commit` needs, so a routine "which phase am I in" probe can fail
+                // someone else's commit with `Unable to create '.git/index.lock': File
+                // exists`. GIT_OPTIONAL_LOCKS=0 turns off exactly that optional write.
+                // The `rev-parse` / `log` calls sharing this helper never open the
+                // index, so the variable is inert for them. The block itself is owned by
+                // src/read-only-git-env.cts and shared with every other read-only seam;
+                // parity across every read-only surface is asserted in
+                // tests/git-optional-locks-parity.test.cjs.
+                env: (0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
             });
         }
         catch {
@@ -675,6 +688,28 @@ function actionsFor(situation, s, runtime = 'claude') {
     }
 }
 // ─── Summary line ─────────────────────────────────────────────────────────────
+function phaseSummary(s) {
+    const phase = s.current_phase;
+    // Preserve the milestone ordinal introduced by #5228 when it is known.
+    const at = phase === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, phase) === 0);
+    if (at >= 0)
+        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
+    const total = s.total_phases;
+    const legacy = `Phase ${phase ?? '?'} of ${total ?? '?'}`;
+    const roadmapTotal = s.roadmap_total_phases;
+    // Keep the recorded pair when roadmap counts are unavailable, or when the
+    // pair can describe a single milestone without changing its existing text.
+    if (phase === null || total === null || roadmapTotal === null || roadmapTotal <= 0
+        || (total === roadmapTotal && comparePhaseNum(phase, total) <= 0)) {
+        return legacy;
+    }
+    // When the recorded pair cannot safely describe this roadmap, label its
+    // counts separately rather than printing a mixed-scope ratio.
+    const roadmapDone = s.roadmap_completed_phases;
+    return roadmapDone === null
+        ? `Phase ${phase} (${roadmapTotal} roadmap phases)`
+        : `Phase ${phase} (${roadmapDone} of ${roadmapTotal} roadmap phases complete)`;
+}
 function buildSummary(situation, s) {
     switch (situation) {
         case 'no-project':
@@ -688,7 +723,7 @@ function buildSummary(situation, s) {
         case 'needs-first-phase':
             return 'Project initialized — plan your first phase';
         case 'planning':
-            return `${phasePosition(s)} — needs a plan`;
+            return `${phaseSummary(s)} — needs a plan`;
         case 'executing':
             return progressLine('executing', s);
         case 'verify-pending':
@@ -702,24 +737,10 @@ function buildSummary(situation, s) {
             return 'Unsure of state — showing progress';
     }
 }
-/**
- * "Phase N of M" for the current phase. N is the phase's 1-based position in
- * the current milestone's ordered phase list (#5228), so a milestone that
- * continues the numbering of an earlier one (phases 9-17) reads "Phase 1 of 9",
- * not "Phase 9 of 9". When the phase is not in that list (or the roadmap lists
- * none) the STATE.md figures are printed as recorded.
- */
-function phasePosition(s) {
-    const current = s.current_phase;
-    const at = current === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, current) === 0);
-    if (at >= 0)
-        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
-    return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'}`;
-}
 function progressLine(tail, s) {
     const parts = [];
     if (s.current_phase !== null && s.total_phases !== null) {
-        parts.push(phasePosition(s));
+        parts.push(phaseSummary(s));
     }
     else if (s.current_phase !== null) {
         parts.push(`Phase ${s.current_phase}`);

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

@@ -129,6 +129,7 @@ function owners() {
         locateProgressTable: phaseLifecycleMod.locateProgressTable,
         isSentinelPhaseId: phaseIdMod.isSentinelPhaseId,
         parsePhaseFromProse: phaseIdMod.parsePhaseFromProse,
+        resolvePhaseIdConvention: planningWorkspaceMod.resolvePhaseIdConvention,
         getMilestoneInfo: roadmapParserMod.getMilestoneInfo,
         collectSection: markdownSectionizerMod.collectSection,
         stateFieldValue: stateDocumentMod.stateFieldValue,
@@ -154,16 +155,31 @@ function buildMilestone(cwd) {
 }
 // ─── phases: Progress-table (primary) enumerator ───────────────────────────
 const PHASE_CELL_RE = /^(\d+(?:\.\d+)*)\s*[.:)–—-]?\s*(.*)$/;
-function phasesFromProgressTable(table) {
+// #5626: under `milestone-prefixed` the phase id is the whole `M-NN` (`3-01`), so the number capture takes
+// one optional `-NN` segment. Chosen by the convention value alone: every other convention keeps the
+// dotted-only capture above, and the `\d+-\d+` shape stays an ordinary leading integer there.
+const MILESTONE_PREFIXED = 'milestone-prefixed';
+const PHASE_CELL_MILESTONE_RE = /^(\d+(?:-\d+)?(?:\.\d+)*)\s*[.:)–—-]?\s*(.*)$/;
+/** The project's `phase_id_convention` (null when unset or unreadable), through its one owner. */
+function phaseIdConventionOf(cwd) {
+    try {
+        return owners().resolvePhaseIdConvention(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function phasesFromProgressTable(table, convention) {
     const { isSentinelPhaseId } = owners();
     const phases = [];
+    const cellRe = convention === MILESTONE_PREFIXED ? PHASE_CELL_MILESTONE_RE : PHASE_CELL_RE;
     for (const row of table.rows) {
         const cell = (row['Phase'] ?? '').trim();
         if (!/^\d/.test(cell))
             continue; // stray note row, no leading digit
         if (isSentinelPhaseId(cell))
             continue; // phase 0 / 999.x sentinels
-        const m = PHASE_CELL_RE.exec(cell);
+        const m = cellRe.exec(cell);
         const number = m ? m[1] : cell;
         const name = m && m[2].trim().length > 0 ? m[2].trim() : null;
         phases.push({ number, name, status: (0, phase_status_cjs_1.parseRoadmapStatusCell)(row['Status']) });
@@ -173,6 +189,8 @@ function phasesFromProgressTable(table) {
 // ─── phases: `## Phases` checkbox fallback ─────────────────────────────────
 // `- [x] **Phase 1: Foundation**` / `- [ ] **Phase 2.1: Hardening**`.
 const PHASE_BULLET_RE = /^[ \t]*[-*][ \t]+\[([ xX])\][ \t]+\*\*Phase[ \t]+(\d+(?:\.\d+)*)[ \t]*:?[ \t]*([^*\n]*)\*\*/gm;
+// #5626: the same bullet under `milestone-prefixed`: the number capture takes one optional `-NN` segment.
+const PHASE_BULLET_MILESTONE_RE = /^[ \t]*[-*][ \t]+\[([ xX])\][ \t]+\*\*Phase[ \t]+(\d+(?:-\d+)?(?:\.\d+)*)[ \t]*:?[ \t]*([^*\n]*)\*\*/gm;
 /**
  * STATE.md's current phase, via the same frontmatter-then-body chain
  * `cmdStateCompletePhase` uses (`stateFieldValue` owns the #1760 fallback
@@ -180,7 +198,7 @@ const PHASE_BULLET_RE = /^[ \t]*[-*][ \t]+\[([ xX])\][ \t]+\*\*Phase[ \t]+(\d+(?
  * phase as unknown so every unchecked bullet is PENDING rather than
  * IN_PROGRESS by a guess.
  */
-function currentPhaseFromState(statePath) {
+function currentPhaseFromState(statePath, convention) {
     const { platformReadSync, extractFrontmatter, stripFrontmatter, stateFieldValue, parsePhaseFromProse } = owners();
     try {
         const raw = platformReadSync(statePath);
@@ -191,7 +209,7 @@ function currentPhaseFromState(statePath) {
         const { value } = stateFieldValue(fm, body, 'current_phase', 'Current Phase');
         if (!value)
             return null;
-        return parsePhaseFromProse(value).phase;
+        return parsePhaseFromProse(value, convention).phase;
     }
     catch {
         return null;
@@ -207,15 +225,16 @@ function currentPhaseFromState(statePath) {
  * `**Phase N` anchor inside `PHASE_BULLET_RE` is the second layer of that
  * defence — a plan bullet's text never starts with `**Phase`.
  */
-function phasesFromChecklist(roadmapContent, cwd, statePath) {
+function phasesFromChecklist(roadmapContent, cwd, statePath, convention) {
     const { collectSection, isSentinelPhaseId } = owners();
     const section = collectSection(roadmapContent, (h) => /^phases$/i.test(h.text.trim()));
     if (!section)
         return [];
-    const currentPhase = currentPhaseFromState(statePath);
+    const currentPhase = currentPhaseFromState(statePath, convention);
     const phases = [];
     let match;
-    const pattern = new RegExp(PHASE_BULLET_RE.source, PHASE_BULLET_RE.flags);
+    const bulletRe = convention === MILESTONE_PREFIXED ? PHASE_BULLET_MILESTONE_RE : PHASE_BULLET_RE;
+    const pattern = new RegExp(bulletRe.source, bulletRe.flags);
     while ((match = pattern.exec(section.body)) !== null) {
         const checked = match[1] === 'x' || match[1] === 'X';
         const number = match[2];
@@ -237,10 +256,11 @@ function buildPhases(cwd, paths) {
             return [];
         if (content.charCodeAt(0) === 0xfeff)
             content = content.slice(1); // strip leading BOM
+        const convention = phaseIdConventionOf(cwd);
         const table = locateProgressTable(content);
         if (table)
-            return phasesFromProgressTable(table);
-        return phasesFromChecklist(content, cwd, paths.state);
+            return phasesFromProgressTable(table, convention);
+        return phasesFromChecklist(content, cwd, paths.state, convention);
     }
     catch {
         return [];

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

@@ -14,6 +14,7 @@ exports.isUnfilledFieldValue = isUnfilledFieldValue;
 exports.leadingCalendarDate = leadingCalendarDate;
 exports.isRealCalendarDate = isRealCalendarDate;
 exports.stateFieldContinuation = stateFieldContinuation;
+exports.fieldContinuationEnd = fieldContinuationEnd;
 exports.stateExtractField = stateExtractField;
 exports.stateFieldValue = stateFieldValue;
 exports.stateCurrentPositionSlice = stateCurrentPositionSlice;
@@ -359,6 +360,8 @@ const STATE_SIBLING_FIELD_LINE_RE = /^\*{0,2}[A-Za-z][A-Za-z0-9 _-]*\*{0,2}:{1,2
  * cannot wrap), or is followed by end-of-file, a blank line, Markdown
  * structure, or a sibling field.
  */
+/** The line terminators the STATE.md readers (JS `m`-flag `^`/`$`) treat as a line boundary. */
+const LINE_SEPARATOR_RE = /[\n\u2028\u2029]/;
 function stateFieldContinuation(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Same two single-line grammars stateExtractField uses, in the same order, so
@@ -375,10 +378,21 @@ function stateFieldContinuation(content, fieldName) {
     // before testing for the newline.
     const afterValue = match.index + match[0].length;
     const rest = content.slice(afterValue).replace(/^\r/, '');
-    if (!rest.startsWith('\n'))
+    // #5460: U+2028 / U+2029 are line starts to the `m`-flag readers (and stop `(.+)`), so they end
+    // the value's line exactly as `\n` does.
+    if (!/^[\n\u2028\u2029]/.test(rest))
         return null; // end of file: nothing follows
-    const lines = rest.slice(1).split('\n').map((line) => line.replace(/\r$/, ''));
-    const continuation = [];
+    const lines = rest.slice(1).split(LINE_SEPARATOR_RE).map((line) => line.replace(/\r$/, ''));
+    const continuation = lines.slice(0, continuationLineCount(lines)).map((line) => line.trim());
+    return continuation.length ? continuation.join(' ') : null;
+}
+/**
+ * How many of the lines directly below a single-line field belong to its value: the scan
+ * `stateFieldContinuation` reports on, shared so a writer that replaces the value removes exactly
+ * the lines a validator would call its continuation (#4945). `lines` are CR-free.
+ */
+function continuationLineCount(lines) {
+    let count = 0;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (!line.trim())
@@ -391,9 +405,37 @@ function stateFieldContinuation(content, fieldName) {
         // title, so stop before consuming it rather than after.
         if (i + 1 < lines.length && SETEXT_UNDERLINE_RE.test(lines[i + 1]))
             break;
-        continuation.push(line.trim());
+        count++;
     }
-    return continuation.length ? continuation.join(' ') : null;
+    return count;
+}
+/**
+ * The index just past a single-line field's value AND the continuation lines that wrap it
+ * (#4945). `valueEnd` is where the field's own line ends (before its line terminator). Replacing
+ * `content.slice(valueEnd, result)` with nothing removes every continuation line and the
+ * terminator in front of each, so the terminator after the last one stays. Returns `valueEnd`
+ * when nothing continues the value.
+ */
+function fieldContinuationEnd(content, valueEnd) {
+    const tail = content.slice(valueEnd);
+    // #5460: the readers' `m`-flag `^` also starts a line after U+2028 / U+2029, so a continuation
+    // scan that split on `\n` alone swallowed `...tail<U+2028>Stopped at: x` as ONE continuation line
+    // and deleted the sibling field with it. Each separator is one UTF-16 unit, like `\n`, so the
+    // removal arithmetic below is unchanged.
+    const first = /^(?:\r?\n|[\u2028\u2029])/.exec(tail);
+    if (!first)
+        return valueEnd;
+    const rawLines = tail.slice(first[0].length).split(LINE_SEPARATOR_RE);
+    const count = continuationLineCount(rawLines.map((line) => line.replace(/\r$/, '')));
+    if (count === 0)
+        return valueEnd;
+    let removed = first[0].length + (count - 1);
+    for (let i = 0; i < count; i++)
+        removed += rawLines[i].length;
+    // The terminator after the last continuation line stays; on a CRLF document that includes its CR.
+    if (rawLines[count - 1].endsWith('\r'))
+        removed -= 1;
+    return valueEnd + removed;
 }
 function stateExtractField(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);