@opengsd/gsd-core 1.20.0 → 1.20.1

package/gsd-core/bin/lib/commands.cjs

@@ -14,6 +14,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const text_lines_cjs_1 = require("./text-lines.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const install_manifest_record_cjs_1 = require("./install-manifest-record.cjs");
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -835,6 +836,7 @@ function cmdEffortSync(cwd, raw, opts) {
     // cmdEffortSyncCodex and cmdEffortSyncOpencode, so a fault mid-write can
     // never leave an agent file truncated or empty.
     let fileFailureCount = 0;
+    const rewrittenFiles = [];
     for (const file of files) {
         const agentName = file.replace(/\.md$/, '');
         const filePath = node_path_1.default.join(agentsDir, file);
@@ -852,6 +854,8 @@ function cmdEffortSync(cwd, raw, opts) {
             fileFailureCount++;
             continue;
         }
+        // #5683: hash BEFORE any rewrite — only a GSD-owned file gets re-recorded.
+        const preHash = (0, install_manifest_record_cjs_1.tryFileHash)(filePath);
         // Resolve using install-time logic: home defaults merged with project config.
         const universalEffort = resolveInstallTimeEffort(effortCfg, agentName);
         // #3533 (10d): 'inherit' means the key must NOT exist. An absent key is
@@ -915,6 +919,7 @@ function cmdEffortSync(cwd, raw, opts) {
                     }
                     catch { /* non-fatal: proceed with default tmp-file mode */ }
                     (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPathInherit, filePath);
+                    rewrittenFiles.push({ path: filePath, preHash });
                 }
                 catch {
                     try {
@@ -992,6 +997,7 @@ function cmdEffortSync(cwd, raw, opts) {
                 }
                 catch { /* non-fatal: proceed with default tmp-file mode */ }
                 (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPathSet, filePath);
+                rewrittenFiles.push({ path: filePath, preHash });
             }
             catch {
                 try {
@@ -1006,6 +1012,9 @@ function cmdEffortSync(cwd, raw, opts) {
         changes.push({ agent: agentName, from: currentEffort, to: newEffortValue });
         synced++;
     }
+    // #5683: keep the install manifest in step with the agents just rewritten.
+    if (!dryRun)
+        (0, install_manifest_record_cjs_1.recordManifestFileHashes)(node_path_1.default.dirname(agentsDir), rewrittenFiles);
     output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir }, raw, fileFailureCount > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
 }
 /**
@@ -1048,6 +1057,7 @@ function cmdEffortSyncCodex(raw, dryRun, configDir) {
     const refused = [];
     const writeFailures = [];
     const readFailures = [];
+    const rewrittenFiles = [];
     let synced = 0;
     let skipped = 0;
     for (const file of files) {
@@ -1066,6 +1076,7 @@ function cmdEffortSyncCodex(raw, dryRun, configDir) {
             readFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
             continue;
         }
+        const preHash = (0, install_manifest_record_cjs_1.tryFileHash)(filePath); // #5683
         const parsed = (0, codex_agent_toml_cjs_1.parseCodexAgentToml)(content);
         if (!parsed.ok) {
             // Never partially rewritten (40-design.md, ADR-2313 reader/writer
@@ -1134,6 +1145,7 @@ function cmdEffortSyncCodex(raw, dryRun, configDir) {
                 }
                 catch { /* non-fatal: proceed with default tmp-file mode */ }
                 (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, filePath);
+                rewrittenFiles.push({ path: filePath, preHash });
             }
             catch (err) {
                 // Reported, not thrown — the remaining agents still get processed.
@@ -1150,6 +1162,8 @@ function cmdEffortSyncCodex(raw, dryRun, configDir) {
         changes.push(...pendingChanges);
         synced++;
     }
+    if (!dryRun)
+        (0, install_manifest_record_cjs_1.recordManifestFileHashes)(node_path_1.default.dirname(agentsDir), rewrittenFiles);
     output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir, refused, write_failures: writeFailures, read_failures: readFailures }, raw, writeFailures.length > 0 || readFailures.length > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
 }
 /**
@@ -1198,6 +1212,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
     const changes = [];
     const writeFailures = [];
     const readFailures = [];
+    const rewrittenFiles = [];
     let synced = 0;
     let skipped = 0;
     for (const file of files) {
@@ -1216,6 +1231,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
             readFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
             continue;
         }
+        const preHash = (0, install_manifest_record_cjs_1.tryFileHash)(filePath); // #5683
         // `target === null` covers both "no effort configured" (inherit) and "a
         // level OpenCode does not accept" — both must produce NO `variant:` key,
         // exactly what install writes.
@@ -1312,6 +1328,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
                 }
                 catch { /* non-fatal: proceed with default tmp-file mode */ }
                 (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, filePath);
+                rewrittenFiles.push({ path: filePath, preHash });
             }
             catch (err) {
                 try {
@@ -1340,6 +1357,8 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
     // Making the exit code reflect failure would be a CLI-contract change
     // affecting all three cmdEffortSync* branches (claude, codex, opencode) and
     // is out of scope for this fix.
+    if (!dryRun)
+        (0, install_manifest_record_cjs_1.recordManifestFileHashes)(node_path_1.default.dirname(agentsDir), rewrittenFiles);
     output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir, write_failures: writeFailures, read_failures: readFailures }, raw, writeFailures.length > 0 || readFailures.length > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
 }
 /**

package/gsd-core/bin/lib/gsd-tool-dir.cjs

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Tool-owned `.gsd/` directory owner (#5757).
+ *
+ * gsd-core keeps small tool state under `<project>/.gsd/` (the dispatch
+ * isolation sentinel, the harness fork-probe cache). A user project does not
+ * inherit gsd-core's own root `.gitignore`, and the project may contain a
+ * `.gsd` symlink, so every writer needs the same two guarantees before it
+ * writes anything there:
+ *
+ *   1. the directory is a real directory that resolves inside the project
+ *      (never write through a project-supplied symlink or ancestor redirect);
+ *   2. the directory is ignored by git (`.gsd/.gitignore`), without clobbering
+ *      rules a user already put there.
+ *
+ * This module is the single owner of both. Callers pass their own ignore-file
+ * `marker` comment and the `rules` they need; the owner appends only the rules
+ * that are missing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GSD_IGNORE_SYMLINK = exports.GSD_DIR_UNSAFE = void 0;
+exports.ignoreAdditions = ignoreAdditions;
+exports.ensureToolOwnedGsdDir = ensureToolOwnedGsdDir;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const SYMLINK_IGNORE_MESSAGE = '.gsd/.gitignore is a symlink';
+/** Stable `code` values on the refusal errors; callers translate by code, never by message. */
+exports.GSD_DIR_UNSAFE = 'GSD_DIR_UNSAFE';
+exports.GSD_IGNORE_SYMLINK = 'GSD_IGNORE_SYMLINK';
+function codedError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function hasLine(text, line) {
+    return text.split('\n').some((l) => l.replace(/\r$/, '') === line);
+}
+/**
+ * Pure merge: the text to append to an existing ignore file so that `marker`
+ * and every rule are present, or '' when nothing is missing. A file that
+ * already ignores everything (`*` line) needs nothing.
+ */
+function ignoreAdditions(current, { marker, rules }) {
+    if (hasLine(current, '*'))
+        return '';
+    const missing = rules.filter((rule) => !hasLine(current, rule));
+    if (missing.length === 0)
+        return '';
+    const lead = current === '' || current.endsWith('\n') ? '' : '\n';
+    const markerLine = current.includes(marker) ? '' : `${marker}\n`;
+    return `${lead}${markerLine}${missing.join('\n')}\n`;
+}
+function isLinkError(err) {
+    const e = err;
+    return !!e && (e.code === 'ELOOP' || e.message === SYMLINK_IGNORE_MESSAGE);
+}
+function mergeExistingIgnore(ignorePath, options) {
+    let fd;
+    let tmpPath = null;
+    try {
+        if (node_fs_1.default.lstatSync(ignorePath).isSymbolicLink())
+            throw new Error(SYMLINK_IGNORE_MESSAGE);
+        // Read through an fd opened without following links where supported
+        // (O_NOFOLLOW is absent on Windows, hence `|| 0`), then replace by rename
+        // rather than append through the path, so a link swapped in after the
+        // check cannot redirect a write elsewhere.
+        fd = node_fs_1.default.openSync(ignorePath, node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NOFOLLOW || 0));
+        if (!node_fs_1.default.fstatSync(fd).isFile())
+            throw new Error('.gsd/.gitignore is not a regular file');
+        const current = node_fs_1.default.readFileSync(fd, 'utf8');
+        node_fs_1.default.closeSync(fd);
+        fd = undefined;
+        const additions = ignoreAdditions(current, options);
+        if (additions === '')
+            return;
+        // `tmpPath` is assigned only once the exclusive create succeeded, so an
+        // EEXIST never unlinks an entry this process did not create.
+        const candidateTmp = `${ignorePath}.tmp-${process.pid}-${node_crypto_1.default.randomBytes(6).toString('hex')}`;
+        const tmpFd = node_fs_1.default.openSync(candidateTmp, 'wx');
+        tmpPath = candidateTmp;
+        try {
+            node_fs_1.default.writeFileSync(tmpFd, current + additions);
+        }
+        finally {
+            node_fs_1.default.closeSync(tmpFd);
+        }
+        if (node_fs_1.default.lstatSync(ignorePath).isSymbolicLink())
+            throw new Error(SYMLINK_IGNORE_MESSAGE);
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, ignorePath);
+        tmpPath = null;
+    }
+    catch (err) {
+        if (isLinkError(err))
+            throw codedError(SYMLINK_IGNORE_MESSAGE, exports.GSD_IGNORE_SYMLINK);
+        // Ignore seeding is best-effort; the caller's state is still useful if
+        // this path cannot be read or updated.
+    }
+    finally {
+        if (fd !== undefined)
+            node_fs_1.default.closeSync(fd);
+        if (tmpPath) {
+            try {
+                node_fs_1.default.unlinkSync(tmpPath);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}
+/**
+ * Ensure `<cwd>/.gsd` exists as a real, project-contained, git-ignored
+ * directory and return its path. Throws when `.gsd` is a symlink, resolves
+ * outside the project, or `.gsd/.gitignore` is a symlink.
+ */
+function ensureToolOwnedGsdDir(cwd, options) {
+    const dir = node_path_1.default.join(cwd, '.gsd');
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    if (node_fs_1.default.lstatSync(dir).isSymbolicLink() ||
+        node_path_1.default.relative(node_fs_1.default.realpathSync(cwd), node_fs_1.default.realpathSync(dir)) !== '.gsd') {
+        throw codedError('.gsd directory is a symlink or resolves outside the project', exports.GSD_DIR_UNSAFE);
+    }
+    const ignorePath = node_path_1.default.join(dir, '.gitignore');
+    try {
+        node_fs_1.default.writeFileSync(ignorePath, '*\n', { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            mergeExistingIgnore(ignorePath, options);
+        // Any other ignore-file IO failure must not prevent the caller's write.
+    }
+    return dir;
+}

package/gsd-core/bin/lib/init.cjs

@@ -99,7 +99,7 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { phaseDirectoryOptions, findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs, } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { comparePhaseNum, phaseDirectoryName, customPhaseQuery, customDirectoryOwner, phaseScanTokenSource, phaseKeyFromToken, phaseDirectoryContext, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, extractPhaseDependencyTokens, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, bracketQualifiedKey, phaseHeadingPrefixSrcFor, parsePhaseChecklistLine, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
+const { comparePhaseNum, phaseDirectoryName, customPhaseQuery, customDirectoryOwner, phaseScanTokenSource, phaseNumberTokenSource, phaseKeyFromToken, phaseDirectoryContext, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, extractPhaseDependencyTokens, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, bracketQualifiedKey, phaseHeadingPrefixSrcFor, parsePhaseChecklistLine, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
 const { phaseToken } = phaseIdDisplayMod;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, todosDir, listAvailableWorkstreams, peekActiveWorkstream, resolveEnvWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, findContextMdIn, findPhaseSpecIn, resolvePhaseIdConvention, worktreesOptedOut, } = planningWorkspace;
@@ -2626,7 +2626,7 @@ function cmdInitManager(cwd, raw) {
         }
     }
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${phaseScanTokenSource(directoryContext)})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${phaseScanTokenSource(directoryContext, phaseIdConvention)})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
     const phases = [];
     const bracketIdsByPhaseNumber = new Map();
     let match;
@@ -2650,7 +2650,7 @@ function cmdInitManager(cwd, raw) {
         }
         const sectionStart = match.index;
         const restOfContent = content.slice(sectionStart);
-        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}${phaseScanTokenSource(directoryContext)}`, 'i'));
+        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}${phaseScanTokenSource(directoryContext, phaseIdConvention)}`, 'i'));
         const sectionEnd = nextHeader
             ? sectionStart + nextHeader.index
             : content.length;
@@ -2849,7 +2849,7 @@ function cmdInitManager(cwd, raw) {
     }
     else {
         // Preserve the historical greedy non-bracket fallback byte-for-byte.
-        const _allCompletedPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`.*${phaseHeadingPrefixNoCapture}(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
+        const _allCompletedPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`.*${phaseHeadingPrefixNoCapture}(${phaseNumberTokenSource(phaseIdConvention)})[:\\s]`, 'gi');
         let _allMatch;
         while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
             if (!(0, phase_entry_grammar_cjs_1.isPhaseEntryChecked)(_allMatch[0]))
@@ -3433,9 +3433,9 @@ function cmdInitProgress(cwd, raw, options = {}) {
     const roadmapPhaseNums = new Set();
     const roadmapPhaseNames = new Map();
     const roadmapCheckboxStates = new Map();
+    const progressConvention = resolvePhaseIdConvention(cwd);
     try {
         const roadmapContent = extractCurrentMilestone(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd);
-        const progressConvention = resolvePhaseIdConvention(cwd);
         // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag, owned by
         // buildPhaseHeadingScanRegex (phase-id.cts) so this scan also recognizes
         // bracket-convention headings instead of hand-rolling a literal `Phase\s+`.
@@ -3472,7 +3472,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // matched (by absorbing the bracket text). This does NOT migrate the site
         // onto phaseHeadingPrefixSrcFor / the bracket convention — that stays
         // out of scope per the comment above (#4984 revert, pinned census).
-        const cbPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${phaseScanTokenSource(directoryContext)})[:\\s]`, 'gim', { state: 'captured' });
+        const cbPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${phaseScanTokenSource(directoryContext, progressConvention)})[:\\s]`, 'gim', { state: 'captured' });
         let cbm;
         while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
             const cbKey = cbm[2];
@@ -3494,7 +3494,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // behavior-preserving).
         const dirs = listMilestonePhaseDirs(phasesDir, { cwd }).value;
         for (const dir of dirs) {
-            const dirMatch = dir.match(new RegExp(`^(${phaseScanTokenSource(directoryContext)})-?(.*)`, 'i'));
+            const dirMatch = dir.match(new RegExp(`^(${phaseScanTokenSource(directoryContext, progressConvention)})-?(.*)`, 'i'));
             const query = customPhaseQuery(dir, directoryContext);
             const owner = query && customDirectoryOwner(dir, query);
             const phaseNumber = owner ? owner.id : dirMatch ? dirMatch[1] : dir;

package/gsd-core/bin/lib/install-engine.cjs

@@ -229,11 +229,8 @@ const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
  * with the computed pathPrefix for the install.
  */
 function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
-    content = content.replace(/~\/\.claude\//g, pathPrefix);
-    content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-    content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
-    content = content.replace(/~\/\.opencode\//g, pathPrefix);
-    content = content.replace(/~\/\.kilo\//g, pathPrefix);
+    // #5715: one pass with literal replacement (see rewriteOpencodeFamilyConfigDirForms).
+    content = runtimeArtifactConversion._rewriteOpencodeFamilyConfigDirForms(content, pathPrefix, getDirName(runtime));
     // #5637: the typed-text capture heredoc ends at a terminator the typed text cannot know.
     return (0, args_terminator_cjs_1.stampInstalledContent)(content);
 }
@@ -1653,7 +1650,8 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
         let content = installFs().readFileSync(node_path_1.default.join(rawDir, entry.name), 'utf8');
         content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
         content = processAttribution(content, resolveAttribution(runtime));
-        content = converter(content, skillName);
+        // #5715: the converter runs after the prefix pass; shield the emitted prefix from it.
+        content = runtimeArtifactConversion._shieldEmittedPrefix(content, pathPrefix, (c) => converter(c, skillName));
         const skillDir = node_path_1.default.join(dest, skillName);
         installFs().mkdirSync(skillDir, { recursive: true });
         installFs().writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
@@ -1881,9 +1879,11 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
             // already satisfies the fold-to-descriptor requirement. Only the SKILLS
             // converter site above (installOpencodeFamilySkills) has a real
             // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
-            content = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
-                ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
-                : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
+            // #5715: the converter runs after the prefix pass; shield the emitted prefix from it.
+            const frontmatterConverter = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
+                ? (c) => runtimeArtifactConversion.convertClaudeToKiloFrontmatter(c)
+                : (c) => runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(c);
+            content = runtimeArtifactConversion._shieldEmittedPrefix(content, pathPrefix, frontmatterConverter);
             installFs().writeFileSync(node_path_1.default.join(destDir, destName), content);
         }
     }

package/gsd-core/bin/lib/install-manifest-record.cjs

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Install manifest per-file hash ownership (#5683).
+ *
+ * `gsd-file-manifest.json` records `sha256(file bytes)` per installed file,
+ * keyed by path relative to the runtime config dir. `effort sync --apply`
+ * rewrites installed agents, so it re-records exactly those files here.
+ * `bin/install.js` fileHash delegates to this module: one hash function.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileHash = fileHash;
+exports.tryFileHash = tryFileHash;
+exports.recordManifestFileHashes = recordManifestFileHashes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const MANIFEST_NAME = 'gsd-file-manifest.json';
+/** SHA256 (lowercase hex) of a file's bytes — the manifest's per-file hash. */
+function fileHash(filePath) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(filePath)).digest('hex');
+}
+/** fileHash that returns null instead of throwing — for capturing a pre-rewrite hash. */
+function tryFileHash(filePath) {
+    try {
+        return fileHash(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Update ONLY the manifest entries for `rewritten` files (under `configDir`),
+ * and only those that were GSD-owned before the rewrite: `preHash` equal to the
+ * recorded manifest entry. A file the user had already edited keeps its stale
+ * entry so the next install still detects it and backs it up.
+ * Skips silently (returns false) when the manifest is absent, unparseable or
+ * not the documented shape; publishes via tmp + rename.
+ */
+function recordManifestFileHashes(configDir, rewritten) {
+    if (rewritten.length === 0)
+        return false;
+    const manifestPath = (0, node_path_1.join)(configDir, MANIFEST_NAME);
+    let manifest;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        manifest = parsed;
+    }
+    catch {
+        return false;
+    }
+    const files = manifest['files'];
+    if (!files || typeof files !== 'object' || Array.isArray(files))
+        return false;
+    const entries = files;
+    let changed = false;
+    for (const { path: absPath, preHash } of rewritten) {
+        const rel = (0, node_path_1.relative)(configDir, absPath).replace(/\\/g, '/');
+        if (rel === '' || rel.startsWith('..') || (0, node_path_1.isAbsolute)(rel))
+            continue;
+        if (preHash === null || entries[rel] !== preHash)
+            continue;
+        try {
+            entries[rel] = fileHash(absPath);
+            changed = true;
+        }
+        catch { /* unreadable file: leave its entry as recorded */ }
+    }
+    if (!changed)
+        return false;
+    const tmpPath = `${manifestPath}.tmp.${process.pid}`;
+    try {
+        (0, node_fs_1.writeFileSync)(tmpPath, JSON.stringify(manifest, null, 2));
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, manifestPath);
+        return true;
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(tmpPath);
+        }
+        catch { /* already gone or never created */ }
+        return false;
+    }
+}

package/gsd-core/bin/lib/install-profiles.cjs

@@ -35,7 +35,7 @@ const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs
 const capabilityLedger = require("./capability-ledger.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
-const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, } = conversionModule;
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, appendAgentTools: _appendAgentTools, _shieldAgentConverterPrefix, } = conversionModule;
 // #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
 // stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
 // `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
@@ -1011,7 +1011,9 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                 // Step 3: validated canonical grants, before host conversion.
                 content = _appendAgentTools(content, grants);
                 // Step 4: converter (runtime-specific frontmatter/body transform)
-                content = converter(content, isGlobal, { agentName });
+                // #5715: the converter runs after the prefix pass above; shield the emitted prefix
+                // from it, except where the runtime declares no path rewrite (nothing was emitted).
+                content = _shieldAgentConverterPrefix(content, agentCtx.runtime, agentCtx.pathPrefix, (shielded) => converter(shielded, isGlobal, { agentName, pathPrefix: agentCtx.pathPrefix }));
                 // Step 5: frontmatter extensions (effort/disallowedTools; no-op unless
                 // the runtime declares hostBehaviors.agentFrontmatterExtensions)
                 content = _applyAgentFrontmatterExtensions(content, { runtime: agentCtx.runtime, agentName, targetDir: agentCtx.targetDir });

package/gsd-core/bin/lib/phase-id.cjs

@@ -71,6 +71,8 @@ const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]{0,200}\\))?';
 // (scripts/lint-phase-id-drift.cjs) fails CI if a literal re-derivation is
 // introduced outside this module without a `// phase-id-owner:` justification.
 const PHASE_NUMBER_TOKEN_SOURCE = '\\d+[A-Z]?(?:\\.\\d+)*';
+// #5676: milestone-prefixed M-NN token grammar (one optional -NN segment, the #5626 grammar).
+const PHASE_NUMBER_TOKEN_SOURCE_MILESTONE_PREFIXED = '\\d+(?:-\\d+)?[A-Z]?(?:\\.\\d+)*';
 // #4764: a legacy phase REFERENCE in depends-on PROSE — the token in context, directly
 // following "Phase"/"Phases", with bare-token list continuation ("Phases 1 and 2",
 // "Phase 1, 2, and 3", "Phase 1-3"). Built HERE, beside the token grammar it is
@@ -381,7 +383,7 @@ function phaseHeadingPrefixSrcFor(baseline, convention, capturing = false) {
 function parsePhaseChecklistLine(line, convention, context) {
     const capturesBracketId = convention === 'bracket';
     const intro = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, capturesBracketId);
-    const pattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`${intro}(${context ? phaseScanTokenSource(context) : PHASE_NUMBER_TOKEN_SOURCE})`
+    const pattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`${intro}(${context ? phaseScanTokenSource(context, convention) : phaseNumberTokenSource(convention)})`
         + `${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])`, 'i', { state: 'captured' });
     const match = pattern.exec(line);
     if (!match)
@@ -413,7 +415,7 @@ function buildPhaseHeadingScanRegex(baseline, convention, context) {
     const bracketGroup = convention === 'bracket' ? 1 : null;
     const phaseNumGroup = bracketGroup ? 2 : 1;
     const phaseNameGroup = phaseNumGroup + 1;
-    const regex = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(baseline, convention, true)}(${context && convention !== 'bracket' ? phaseScanTokenSource(context) : PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^\\n]+)`, 'gim');
+    const regex = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(baseline, convention, true)}(${context && convention !== 'bracket' ? phaseScanTokenSource(context, convention) : phaseNumberTokenSource(convention)})${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^\\n]+)`, 'gim');
     return { regex, bracketGroup, phaseNumGroup, phaseNameGroup };
 }
 /**
@@ -435,7 +437,7 @@ function buildPhaseDeclarationScans(convention, withBullets = true) {
     // Under bracket a numbered-list item (`1. [ ] **[GSD.02] 05: n**`) is a checklist row too.
     const bullet = bracket ? '^[ \\t]*(?:-|\\d+[.)])[ \\t]*' : '^[ \\t]*-[ \\t]*';
     // Bracket ids may carry a letter suffix (`12A`), as the heading scan's phase token does.
-    const tail = bracket ? '(\\d+)(?=[A-Za-z]?(?:[:.\\s*]|$))' : '(\\d+)(?=[:.\\s*]|$)';
+    const tail = bracket ? '(\\d+)(?=[A-Za-z]?(?:[:.\\s*]|$))' : convention === 'milestone-prefixed' ? `(${phaseNumberTokenSource(convention)})(?=[:.\\s*]|$)` : '(\\d+)(?=[:.\\s*]|$)';
     const checkbox = `\\[${bracket ? `(?!${BRACKET_ID_SRC}\\])` : ''}[^\\]]{0,200}\\][ \\t]*`;
     if (!bracket) {
         if (withBullets)
@@ -1582,9 +1584,17 @@ const CUSTOM_PHASE_ID_FILE = '.phase-id';
 function phaseDirectoryContext(config, roadmap = '', knownIds = []) {
     return { phaseNaming: typeof config.phase_naming === 'string' ? config.phase_naming.toLowerCase() : config.phase_naming, projectCode: config.project_code ?? null, roadmap, knownIds };
 }
-/** Custom scans reuse the numeric source verbatim outside configured custom projects. */
-function phaseScanTokenSource(context) {
-    return context?.phaseNaming === 'custom' ? '[^ \t:\n]+' : PHASE_NUMBER_TOKEN_SOURCE;
+/** #5676: the single owner of the numeric phase-token source per convention. */
+function phaseNumberTokenSource(convention) {
+    return convention === 'milestone-prefixed' ? PHASE_NUMBER_TOKEN_SOURCE_MILESTONE_PREFIXED : PHASE_NUMBER_TOKEN_SOURCE;
+}
+/**
+ * Custom scans reuse the numeric source verbatim outside configured custom projects.
+ * #5676: under `milestone-prefixed` the numeric source admits the `M-NN` token
+ * (`3-02`), so a `03-02-beta` directory is read as phase `3-02`, not phase `3`.
+ */
+function phaseScanTokenSource(context, convention) {
+    return context?.phaseNaming === 'custom' ? '[^ \t:\n]+' : phaseNumberTokenSource(convention);
 }
 const customIdentityIndexes = new WeakMap();
 function customIdentityIndex(options) {
@@ -1986,12 +1996,17 @@ function phaseKeyFromDir(dirName, convention, context) {
  * `Phase:` value. Markdown emphasis is stripped first so a bolded cell is not
  * mistaken for a non-phase. Returns null when the value does not BEGIN with a
  * phase token (`parsePhaseFromProse` anchoring, #2111).
+ *
+ * #5675: `convention` is the project's `phase_id_convention`. Under `milestone-prefixed` the id is
+ * the whole `M-NN` (`3-01`), so the key equals `phaseKeyFromDir` for the same phase; every other
+ * convention (and an absent one) keeps the leading-integer read. It is the trailing parameter so the
+ * existing `(value, context)` callers stay byte-identical.
  */
-function phaseKeyFromProse(value, context) {
+function phaseKeyFromProse(value, context, convention) {
     if (value == null)
         return null;
     const clean = String(value).replace(/[*_`~]/g, '');
-    const { phase } = parsePhaseFromProse(clean, undefined, context);
+    const { phase } = parsePhaseFromProse(clean, convention, context);
     return phase === null ? null : phaseKeyFromToken(phase, context);
 }
 /**
@@ -2031,7 +2046,7 @@ function isPlannedPhaseStatusPhrase(value) {
 // (`3-01`), so the number capture takes one optional `-NN` segment; every other convention (and an absent
 // one) keeps the dotted-only capture, where `3-01` reads as phase `3` exactly as before.
 const PHASE_PROSE_RE = /^\s*(?:Phase\s+)?(?:[A-Z][A-Z0-9_]*-)?(\d+[A-Z]?(?:\.\d+)*)\b/i;
-const PHASE_PROSE_MILESTONE_PREFIXED_RE = /^\s*(?:Phase\s+)?(?:[A-Z][A-Z0-9_]*-)?(\d+(?:-\d+)?[A-Z]?(?:\.\d+)*)\b/i;
+const PHASE_PROSE_MILESTONE_PREFIXED_RE = new RegExp(`^\\s*(?:Phase\\s+)?(?:[A-Z][A-Z0-9_]*-)?(${PHASE_NUMBER_TOKEN_SOURCE_MILESTONE_PREFIXED})\\b`, 'i');
 function parsePhaseFromProse(value, convention, context) {
     if (!value)
         return { phase: null, name: null };
@@ -2206,6 +2221,8 @@ const phaseIdExports = {
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
     OPTIONAL_PHASE_TAG_SOURCE,
     PHASE_NUMBER_TOKEN_SOURCE,
+    PHASE_NUMBER_TOKEN_SOURCE_MILESTONE_PREFIXED,
+    phaseNumberTokenSource,
     PHASE_DEP_REF_SOURCE,
     tokenizePhaseDependencyReferences,
     extractPhaseDependencyTokens,