@opengsd/gsd-core 1.19.0 → 1.20.1

package/gsd-core/bin/lib/capability-validator.cjs

@@ -1874,6 +1874,11 @@ const KNOWN_REVIEWER_FIELDS = new Set([
   // effort", which emits no effort argument at all.
   'effortConfigKey',
   'defaultEffort',
+  // `contextWindowTokens` / `contextWindowConfigKey` added by #4559, same optional/backward-compatible
+  // shape as `promptBudgetKey`: a manifest authored before they existed keeps validating, and an
+  // absent or non-positive window resolves to "no derived prompt cap" at the invocation boundary.
+  'contextWindowTokens',
+  'contextWindowConfigKey',
   'handler',
 ]);
 
@@ -2505,6 +2510,16 @@ function validateReviewerBodyFields(cap) {
     );
   }
 
+  // #4559: optional. Absent or null is "no declared window"; a present key must be a dotted
+  // config key string. The window's VALUE is narrowed (never rejected) by `resolveLaneCap`.
+  if (r.contextWindowConfigKey !== undefined && r.contextWindowConfigKey !== null
+      && (typeof r.contextWindowConfigKey !== 'string' || r.contextWindowConfigKey.length === 0)) {
+    errors.push(
+      ctx + ' reviewer.contextWindowConfigKey must be a dotted config key or null ' +
+      '(got: ' + describeValue(r.contextWindowConfigKey) + ')',
+    );
+  }
+
   // ── handler (D6) — closed first-party enum; null is the default ────────────
   if (r.handler !== null && !VALID_LANE_HANDLERS.has(r.handler)) {
     errors.push(

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
@@ -31,13 +32,13 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, extractOneLinerFromBody } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, } = phaseIdMod;
+const { customPhaseQuery, customDirectoryOwner, isCustomPhaseId, normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdDisplayMod = require("./phase-id-display.cjs");
 const { renderBracketMilestoneDisplay } = phaseIdDisplayMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { extractCurrentMilestone, stripShippedMilestones: _stripShippedMilestones, getMilestoneInfo, getRoadmapPhaseInternal } = roadmapParserMod;
@@ -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');
 }
 /**
@@ -1822,7 +1841,7 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify, filesRemoved) {
             // phase — the phase arm must never branch-mutate for it (isSentinelPhaseId
             // is the invariant's single owner, src/phase-id.cts).
             if (phaseNum && !isSentinelPhaseId(phaseNum)) {
-                const phaseInfo = findPhaseInternal(cwd, phaseNum);
+                const phaseInfo = findPhaseInternal(cwd, phaseNum, undefined, phaseDirectoryOptions(cwd, config));
                 if (phaseInfo) {
                     // #4126: shared with init.cts's cmdInitExecutePhase branch_name field
                     // via the one canonical renderer (src/phase-id.cts) so an undeliverable
@@ -3053,6 +3072,7 @@ function cmdProgressRender(cwd, format, raw) {
         ? renderBracketMilestoneDisplay(milestone?.version, loadConfig(cwd).project_code)
         : null;
     const milestoneVersion = milestoneDisplay ?? milestone?.version ?? null;
+    const directoryContext = phaseDirectoryOptions(cwd);
     const phases = [];
     let totalPlans = 0;
     let totalSummaries = 0;
@@ -3091,9 +3111,11 @@ function cmdProgressRender(cwd, format, raw) {
                 }
             }
             else {
+                const custom = customPhaseQuery(dir, directoryContext);
+                const owner = custom && customDirectoryOwner(dir, custom);
                 const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
-                phaseNum = dm ? dm[1] : dir;
-                phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+                phaseNum = owner ? owner.id : dm ? dm[1] : dir;
+                phaseName = owner ? owner.slug.replace(/-/g, ' ') : dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
             }
             // #3183/#5060: canonical plan/summary counts and lifecycle status
             // (root+nested, superseded-excluded, canonical pairing) from the
@@ -3212,7 +3234,7 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
         .map(w => w.replace(/[^a-z0-9]/g, ''))
         .filter(w => w.length > 2 && !stopWords.has(w)));
     // Find phase directory to get expected file paths
-    const phaseInfoDisk = findPhaseInternal(cwd, phase);
+    const phaseInfoDisk = findPhaseInternal(cwd, phase, undefined, phaseDirectoryOptions(cwd));
     const phasePlans = [];
     if (phaseInfoDisk && phaseInfoDisk['found']) {
         try {
@@ -3394,7 +3416,7 @@ function cmdScaffold(cwd, type, options, raw) {
     const padded = phase ? normalizePhaseName(phase) : '00';
     const today = clock_cjs_1.realClock.localToday();
     // Find phase directory
-    const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+    const phaseInfo = phase && type !== 'phase-dir' ? findPhaseInternal(cwd, phase, undefined, phaseDirectoryOptions(cwd)) : null;
     const phaseDir = phaseInfo ? node_path_1.default.join(cwd, phaseInfo['directory']) : null;
     if (phase && !phaseDir && type !== 'phase-dir') {
         error(`Phase ${phase} directory not found`);
@@ -3422,14 +3444,14 @@ function cmdScaffold(cwd, type, options, raw) {
             }
             const slug = generateSlugInternal(name);
             // #3287: apply project_code prefix to stay consistent with phase.add/phase.insert
-            const scaffoldConfig = loadConfig(cwd);
-            const scaffoldProjectCode = scaffoldConfig['project_code'] || '';
-            const scaffoldPrefix = scaffoldProjectCode ? `${scaffoldProjectCode}-` : '';
-            const dirName = `${scaffoldPrefix}${padded}-${slug}`;
-            const phasesParent = planningPaths(cwd).phases;
-            (0, shell_command_projection_cjs_1.platformEnsureDir)(phasesParent);
-            const dirPath = node_path_1.default.join(phasesParent, dirName);
-            (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
+            const scaffoldConfig = phaseDirectoryOptions(cwd, undefined, '');
+            const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+            const roadmap = scaffoldConfig.phaseNaming === 'custom' && node_fs_1.default.existsSync(roadmapPath)
+                ? node_fs_1.default.readFileSync(roadmapPath, 'utf8') : '';
+            const [{ dirPath }] = phaseLocatorMod.createPhaseDirectories(cwd, [{
+                    id: phase, slug: slug || '',
+                    directoryId: scaffoldConfig.phaseNaming === 'custom' && isCustomPhaseId(phase) ? phase : padded,
+                }], { ...scaffoldConfig, roadmap }, false);
             output({ created: true, directory: toPosixPath(node_path_1.default.relative(cwd, dirPath)), path: dirPath }, raw, dirPath);
             return;
         }
@@ -3728,12 +3750,19 @@ function cmdStats(cwd, format, raw) {
  */
 function cmdCheckCommit(cwd, raw) {
     const config = loadConfig(cwd);
-    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only', '-z'], { cwd });
+    // #5548: execGit scrubs the repo-location vars, but inside the pre-commit hook git sets them
+    // (GIT_DIR/GIT_WORK_TREE of an explicit --git-dir commit, GIT_INDEX_FILE of a `-a` / `<path>`
+    // commit) to name the repo being committed: hand them back or the guard finds no repo and allows.
+    const hookEnv = {};
+    for (const k of shell_command_projection_cjs_1.GIT_LOCATION_ENV_VARS)
+        if (process.env[k] !== undefined)
+            hookEnv[k] = process.env[k];
+    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only', '-z'], { cwd, env: hookEnv });
     if (stagedResult.exitCode === 0) {
         const files = stagedResult.stdout.split('\0').filter(Boolean);
         const planningFiles = files.filter(f => f.startsWith('.planning/'));
         if (planningFiles.length > 0) {
-            const policy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(planningFiles), () => isGitIgnored(cwd, '.planning'));
+            const policy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(planningFiles), () => isGitIgnored(cwd, '.planning', hookEnv));
             if (!policy.resolved) {
                 error(`commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
                     planningFiles.map(f => `  ${f}`).join('\n') +

package/gsd-core/bin/lib/config-loader.cjs

@@ -213,16 +213,16 @@ function _deepMergeConfig(base, overlay) {
 const _warnedUnknownConfigKeys = new Set();
 // ─── Git utilities ────────────────────────────────────────────────────────────
 const _gitIgnoredCache = new Map();
-function isGitIgnored(cwd, targetPath) {
+function isGitIgnored(cwd, targetPath, env) {
     // #2206: strip trailing slashes — `git check-ignore` has a quirk where a
     // CRLF .gitignore with blank lines falsely reports a trailing-slash path
     // (e.g. `.planning/`) as ignored. Normalizing here protects every call site.
     const normalized = targetPath.replace(/\/+$/, '');
-    const key = cwd + '::' + normalized;
+    const key = cwd + '::' + normalized + (env ? '::env:' + JSON.stringify(Object.entries(env).sort()) : '');
     if (_gitIgnoredCache.has(key))
         return _gitIgnoredCache.get(key);
     // --no-index checks .gitignore rules regardless of whether the file is tracked.
-    const result = (0, shell_command_projection_cjs_1.execGit)(['check-ignore', '-q', '--no-index', '--', normalized], { cwd });
+    const result = (0, shell_command_projection_cjs_1.execGit)(['check-ignore', '-q', '--no-index', '--', normalized], { cwd, env });
     const ignored = result.exitCode === 0;
     _gitIgnoredCache.set(key, ignored);
     return ignored;

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

@@ -42,6 +42,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // pattern.cjs is a leaf module (escapeRegex only), so this adds no cycle.
 const pattern_cjs_1 = require("./pattern.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -553,6 +554,15 @@ function planRowPattern(planId, opts = {}) {
     const lead = opts.anchored ? '^(\\s*-\\s*\\[)' : '(-\\s*\\[)';
     return new RegExp(`${lead}${box}(\\]\\s*(?:\\*\\*)?${(0, pattern_cjs_1.escapeRegex)(planId)}${PLAN_ID_ROW_BOUNDARY_SOURCE}(?:\\*\\*)?)`, 'i');
 }
+/**
+ * Tick the first line-anchored unchecked row for `planId` in `text` (the
+ * `phase complete` / `roadmap update-plan-progress` bullet flip): a bullet
+ * mutation through `updateBullet`, so never a fenced line or mid-line match.
+ */
+function tickAnchoredPlanRow(text, planId) {
+    const row = planRowPattern(planId, { anchored: true });
+    return (0, markdown_sectionizer_cjs_1.updateBullet)(text, (_bulletText, rawLine) => row.test(rawLine), (rawLine) => rawLine.replace(row, '$1x$2'));
+}
 module.exports = {
     toPosixPath,
     normalizeLineEndings,
@@ -570,4 +580,5 @@ module.exports = {
     findOrphanSummaries,
     summaryPairsWithAnyPlan,
     planRowPattern,
+    tickAnchoredPlanRow,
 };

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

@@ -851,6 +851,17 @@ function frontmatterListEntries(content, key) {
  * no closed, parseable frontmatter mapping or the key is not an own key of it.
  */
 function rawFrontmatterField(content, key) {
+    const mapping = rawFrontmatterMapping(content);
+    if (!mapping || !Object.prototype.hasOwnProperty.call(mapping, key))
+        return null;
+    return { value: mapping[key] };
+}
+/**
+ * The top-level frontmatter mapping VERBATIM, off `rawFrontmatterField`'s guarded parse path.
+ * Null when the document has no closed, parseable frontmatter mapping — so a caller can tell
+ * "parsed, without that key" (#4998 review) from "no usable frontmatter".
+ */
+function rawFrontmatterMapping(content) {
     const found = frontmatterRegion(content);
     if (!found || !found.terminated)
         return null;
@@ -867,9 +878,7 @@ function rawFrontmatterField(content, key) {
     }
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
-    if (!Object.prototype.hasOwnProperty.call(raw, key))
-        return null;
-    return { value: raw[key] };
+    return raw;
 }
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779). ADR-3473 §8.1
@@ -940,6 +949,14 @@ function scalarNeedsDoubleQuoting(s) {
     // round-trip.
     if (/[\uD800-\uDFFF]/.test(s))
         return true;
+    // #4998: U+2028/U+2029 are not YAML line breaks, so a bare one round-trips
+    // through js-yaml, but every line-anchored reader of a planning document
+    // (`^key:\s*(.+)` with the `m` flag) ends the line there and reads only the
+    // part before it. (A value holding `:` was already quoted by the callers, so
+    // no key could be forged this way.) The quoted path escapes them (`\L`,
+    // `\P`), which no such reader splits on.
+    if (/[\u2028\u2029]/.test(s))
+        return true;
     return false;
 }
 /**
@@ -1806,6 +1823,7 @@ module.exports = {
     // parse path — the decision-coverage gates read `must_haves`/`truths`/`objective` and the
     // SUMMARY `files_modified` list through it instead of a hand-rolled `^key:` scan / regex.
     rawFrontmatterField,
+    rawFrontmatterMapping,
     // #5139: one key's block as unparsed text, for a citation scan that must survive frontmatter
     // the YAML parser refuses.
     frontmatterKeyBlockText,

package/gsd-core/bin/lib/gate-api-coverage-verify-pre.cjs

@@ -39,7 +39,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const { phaseDirectoryOptions, findPhaseInternal } = phaseLocatorMod;
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
@@ -171,7 +171,7 @@ function evaluateApiCoverageVerifyPre(input) {
     let resolvedDir = null;
     let phaseNumber = '';
     if (token) {
-        const found = findPhaseInternal(projectDir, token);
+        const found = findPhaseInternal(projectDir, token, undefined, phaseDirectoryOptions(projectDir));
         if (found && found.directory) {
             // findPhaseInternal's `directory` is relative to the project root; anchor it to `projectDir`
             // (not the process cwd) so the gate reads the same files in-process as it does from the CLI.

package/gsd-core/bin/lib/gate-context-drift.cjs

@@ -85,7 +85,7 @@ function runContextDriftGate(cwd, phaseArg) {
     }
     // Same phase-directory resolution rule the schema-drift gate uses (#1571, #2528):
     // matchPhaseDirs, never a naive substring test.
-    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, phasesDir, phaseArg);
     if (!phaseDir) {
         return unresolvable();
     }

package/gsd-core/bin/lib/gate-phase-context.cjs

@@ -34,10 +34,7 @@ const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs } = phaseIdMod;
+const { phaseDirectoryOptions, findPhaseInternal, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapModule = require("./roadmap.cjs");
 const { getRoadmapPhaseWithFallback } = roadmapModule;
@@ -78,7 +75,7 @@ function unresolvableProbeVerdict(readError) {
 function resolvePhaseDir(projectDir, phase) {
     let result;
     try {
-        result = findPhaseInternal(projectDir, phase);
+        result = findPhaseInternal(projectDir, phase, undefined, phaseDirectoryOptions(projectDir));
     }
     catch (err) {
         return (0, gate_evidence_cjs_1.evidenceFromError)(err, `phase ${phase}`);
@@ -109,11 +106,13 @@ function resolvePhaseDir(projectDir, phase) {
  * `resolvePhaseDir` would widen what those gates inspect, so the two stay apart and each states its
  * scope. Throws when `phasesDir` cannot be listed; both callers sit inside their non-blocking catch.
  */
-function resolvePhaseDirByToken(phasesDir, phaseArg) {
-    const normalizedPhase = normalizePhaseName(phaseArg);
+function resolvePhaseDirByToken(cwd, phasesDir, phaseArg, directoryContext = phaseDirectoryOptions(cwd)) {
+    const lookup = resolvePhaseDirectoryLookup(cwd, phaseArg, undefined, directoryContext);
     const dirEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
     const dirNames = dirEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+    // #4304: both drift gates resolve a directory in the current checkout.
+    // Bracket is the only opt-in grammar; all other conventions remain legacy.
+    const matched = matchPhaseDirsForLookup(dirNames, lookup, undefined, directoryContext).matches[0];
     if (matched)
         return node_path_1.default.join(phasesDir, matched);
     const contained = (0, security_cjs_1.tryWithinRoot)(phaseArg, phasesDir);

package/gsd-core/bin/lib/gate-schema-drift.cjs

@@ -68,7 +68,7 @@ function runSchemaDriftGate(cwd, phaseArg, skipFlag) {
     // matching "11-expansion"), making the drift gate inspect the wrong phase.
     // This shares the one selection rule with find-phase / verify
     // phase-completeness rather than restating it. (#1571, #2528)
-    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(cwd, phasesDir, phaseArg);
     if (!phaseDir) {
         // An unresolvable phase is "could not look" (#5170): there is no phase directory to evaluate.
         return schemaDriftUnreadable(`Phase directory not found: ${phaseArg}`);

package/gsd-core/bin/lib/git-info-exclude.cjs

@@ -32,14 +32,9 @@ function excludeFromGit(dir, filename) {
         // gitignore cannot express a newline in a pattern, and git's line output could not be split.
         if (/[\r\n]/.test(dir))
             return;
-        // cwd must pick the repo: drop inherited repository-location variables (e.g. inside a git hook).
-        const env = { GIT_DIR: undefined, GIT_WORK_TREE: undefined, GIT_INDEX_FILE: undefined, GIT_COMMON_DIR: undefined };
         // The prefix goes last: stdout is trimmed, and a non-empty prefix ends in `/`, so only an
         // empty prefix (dir is the git root) loses its line; a leading space survives.
-        const revParse = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], {
-            cwd: dir,
-            env: env,
-        });
+        const revParse = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], { cwd: dir });
         const [excludeRel, prefix = ''] = (0, text_lines_cjs_1.splitLines)(String(revParse.stdout));
         if (revParse.exitCode !== 0 || !excludeRel)
             return;

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/health-diagnostic-rules/phase-structure.cjs

@@ -54,7 +54,7 @@ const validateMod = require("../validate.cjs");
 const { isPhaseDirName } = validateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { extractPhaseToken, normalizePhaseName, comparePhaseNum } = phaseIdMod;
+const { extractPhaseToken, normalizePhaseName, phaseKeyFromDir, comparePhaseNum } = phaseIdMod;
 // #5060: the Phase Status Module owns the status-label ladder.
 const phase_status_cjs_1 = require("../phase-status.cjs");
 // #5291: W030 asks whether a raw report status has a known repair. The lookup is
@@ -63,8 +63,11 @@ const verification_cjs_1 = require("../verification.cjs");
 // ─── W005 — phase directory doesn't follow NN-name format (verify.cts:1893-1902) ─
 function checkW005(snapshot) {
     const diagnostics = [];
+    const context = snapshot.directoryContext ?? phaseIdMod.phaseDirectoryContext(snapshot.config.value ?? {}, '', snapshot.roadmapDeclaredPhases.value.map(({ phaseId }) => phaseId));
     for (const name of snapshot.phaseDirs.value) {
-        if (!isPhaseDirName(name, snapshot.phaseIdConvention)) {
+        const custom = snapshot.phaseIdConvention === 'bracket' ? null : phaseIdMod.customPhaseQuery(name, context);
+        const owner = custom && phaseIdMod.customDirectoryOwner(name, custom);
+        if (!owner && !isPhaseDirName(name, snapshot.phaseIdConvention)) {
             diagnostics.push({
                 code: 'W005',
                 severity: SEVERITY.WARNING,
@@ -77,17 +80,18 @@ function checkW005(snapshot) {
 }
 // ─── W023 — phase directories collide on normalized key (verify.cts:1904-1950) ─
 //
-// Groups `snapshot.phaseDirs.value` by `normalizePhaseName(extractPhaseToken(name))`
-// — the exact same two owners (`phase-id.cjs`) the original `verify.cts:1917-1918`
-// call site uses, relocated verbatim rather than reimplemented. Sorted with
-// `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
+// Groups directories by the canonical identity owner, preserving recorded
+// custom IDs instead of collapsing their shared token prefixes. Sorted with
+// contextual `comparePhaseNum` + a `localeCompare` tiebreak, mirroring
 // `verify.cts:1930-1932`'s deterministic-output rationale. See the file-level
 // comment for the disclosed "described" fidelity reduction.
 function checkW023(snapshot) {
+    const context = snapshot.directoryContext;
     const groups = new Map();
     for (const name of snapshot.phaseDirs.value) {
-        const token = extractPhaseToken(name);
-        const key = normalizePhaseName(token);
+        const key = context?.phaseNaming === 'custom'
+            ? phaseKeyFromDir(name, undefined, context)
+            : normalizePhaseName(extractPhaseToken(name));
         const list = groups.get(key);
         if (list)
             list.push(name);
@@ -101,7 +105,7 @@ function checkW023(snapshot) {
             continue;
         const described = dirs
             .slice()
-            .sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
+            .sort((a, b) => comparePhaseNum(a, b, context) || String(a).localeCompare(String(b)))
             .map((d) => {
             const phase = phaseByDir.get(d);
             const plans = phase ? phase.planCount : 0;