@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -30,7 +30,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLANNING_ARTIFACTS = void 0;
+exports.PLANNING_ARTIFACTS = exports.FIELD_LINE_BREAK_RE = void 0;
 exports.parsePlanningDoc = parsePlanningDoc;
 exports.findField = findField;
 exports.readNode = readNode;
@@ -48,6 +48,15 @@ const artifacts_cjs_1 = require("./artifacts.cjs");
 // is imported as a default import (esModuleInterop), not a named import.
 const frontmatter_cjs_1 = __importDefault(require("./frontmatter.cjs"));
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+/**
+ * #4998: every character that ends a line for the planning-document readers.
+ * Their `^`/`$` run with the `m` flag, and a JavaScript multiline anchor
+ * matches at U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR as well as
+ * at CR and LF — so a single-line value carrying either one forges a sibling
+ * line just as `\n` does. Every single-line writer, here (`setFieldValue`,
+ * `replaceProse`) and in `state-document.cts`, refuses a value matching this.
+ */
+exports.FIELD_LINE_BREAK_RE = /[\r\n\u2028\u2029]/;
 const { extractFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatter_cjs_1.default;
 /**
  * Canonical `.planning/` root artifact basenames this seam recognises,
@@ -562,13 +571,25 @@ function setFieldValue(doc, id, value) {
         return { ok: false, reason: `node kind '${node.kind}' is not writable this phase` };
     }
     // #4917 / ADR-4910 Decision 2 & 4: a boldField's token boundary is a LINE
-    // boundary, not just an offset range — a value containing \n or \r escapes
+    // boundary, not just an offset range — a value containing any
+    // FIELD_LINE_BREAK_RE character (#4998: U+2028/U+2029 too) escapes
     // the field's own span and reparses as sibling structure (a forged field)
     // once spliced back into the source. Decision 4 licenses refusal for any
     // value the grammar cannot represent; Phase 3 may widen this to escaping,
     // but Phase 1 refuses outright. Do not remove this as an over-restriction.
-    if (/[\r\n]/.test(value)) {
-        return { ok: false, reason: 'field value must not contain a line break (\\r or \\n)' };
+    // One carve-out (#4998, Codex review): a U+2028/U+2029 the field ALREADY
+    // carries may stay when everything from it on is byte-identical — a rewrite
+    // of the text before it (phase renumbering a `Depends on`) adds no line, and
+    // refusing it left the field silently unrenumbered.
+    const breakAt = value.search(exports.FIELD_LINE_BREAK_RE);
+    if (breakAt !== -1) {
+        const current = doc.source.slice(node.valueSpan.start, node.valueSpan.end);
+        const currentBreak = current.search(exports.FIELD_LINE_BREAK_RE);
+        const keepsExistingTail = !/[\r\n]/.test(value) && currentBreak !== -1
+            && value.slice(breakAt) === current.slice(currentBreak);
+        if (!keepsExistingTail) {
+            return { ok: false, reason: 'field value must not contain a line break (\\r, \\n, U+2028 or U+2029)' };
+        }
     }
     // #4917 / ADR-4910 Decision 4: "a value that cannot be represented in the
     // grammar is refused by the writer, with a report." This is a GENERAL
@@ -664,7 +685,7 @@ function replaceProse(doc, from, to) {
     if (typeof from !== 'string' || from.length === 0) {
         return { ok: false, reason: 'replaceProse: `from` must be a non-empty string' };
     }
-    if (typeof to !== 'string' || /[\r\n]/.test(from) || /[\r\n]/.test(to)) {
+    if (typeof to !== 'string' || exports.FIELD_LINE_BREAK_RE.test(from) || exports.FIELD_LINE_BREAK_RE.test(to)) {
         return { ok: false, reason: 'replaceProse: `from` and `to` must be single-line strings' };
     }
     if (doc.staged.size > 0) {

package/gsd-core/bin/lib/planning-inspect.cjs

@@ -51,7 +51,7 @@ const planningSnapshotMod = require("./planning-snapshot.cjs");
 const { buildPlanningSnapshot, worstScope } = planningSnapshotMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
-const { planningPaths } = planningWorkspaceMod;
+const { planningPaths, resolvePhaseIdConvention } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planScan = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -74,7 +74,7 @@ const verificationMod = require("./verification.cjs");
 const { readVerificationStatus, VerificationStatusError, failOnVerificationStatusError } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { phaseKeyFromDir, phaseKeyFromToken, phaseMarkdownRegexSource } = phaseIdMod;
+const { phaseKeyFromDir, phaseKeyFromToken, phaseMarkdownRegexSource, extractPhaseDependencyTokens } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { extractCurrentMilestone } = roadmapParserMod;
@@ -407,7 +407,7 @@ function findDuplicateIds(reqMd) {
     }
     return dupes;
 }
-function buildRequirements(requirementsPath, knownPhaseKeys, diagnostics, planningRoot) {
+function buildRequirements(requirementsPath, knownPhaseKeys, diagnostics, planningRoot, directoryContext) {
     const doc = readDocument(requirementsPath, planningRoot);
     if (!doc.exists) {
         diagnostics.push({
@@ -464,7 +464,7 @@ function buildRequirements(requirementsPath, knownPhaseKeys, diagnostics, planni
             // here too — it is a FILE-MEMBERSHIP predicate (#3511) for aggregate
             // `*-UAT.md` / `*-VERIFICATION.md` scans, not a phase-identity equality
             // test, and is unreliable for decimal phases.
-            if (!knownPhaseKeys.has(phaseKeyFromToken(token))) {
+            if (!knownPhaseKeys.has(phaseKeyFromToken(token, directoryContext))) {
                 diagnostics.push({
                     code: INSPECT_DIAGNOSTIC.REQUIREMENT_PHASE_UNKNOWN,
                     subject: `${item.id}->${token}`,
@@ -915,28 +915,16 @@ function extractGoalProse(sectionBody) {
  * token scan above), never a document-wide scan. `[]` when the line is
  * absent.
  */
-function extractDependencyTokens(sectionBody) {
+function extractDependencyTokens(sectionBody, phaseIdConvention) {
     const m = DEPENDS_ON_LINE_RE.exec(sectionBody);
     if (!m)
         return [];
-    // #4764: phase REFERENCES, not digit runs — the same prose-anchored grammar
-    // init.manager's dep_phases extraction uses (owner: phase-id.cts's
-    // PHASE_DEP_REF_SOURCE). The whole-field token scrape this replaces pulled
-    // calendar dates, git shas and ledger ids in as dependencies. The grammar's
-    // capture group 1 already excludes the "Phase(s)" anchor word, so no
-    // prefix-strip literal is needed here. Self-exclusion (init.manager drops
-    // the row's own number) is deliberately NOT applied: this reader has no row
-    // context at the extraction site and reports informationally, it does not
-    // gate.
-    const refRe = new RegExp(phaseIdMod.PHASE_DEP_REF_SOURCE, 'gi');
-    const tokenRe = new RegExp(phaseIdMod.PHASE_NUMBER_TOKEN_SOURCE, 'g');
-    const tokens = [];
-    let refMatch;
-    while ((refMatch = refRe.exec(m[1])) !== null) {
-        for (const t of refMatch[1].matchAll(tokenRe))
-            tokens.push(t[0]);
-    }
-    return sortedUnique(tokens);
+    // #4764/#4304: phase REFERENCES, not digit runs. Both this informational
+    // reader and init.manager consume phase-id.cts's convention-aware owner, so
+    // bracket milestone digits never surface as dependencies. Self-exclusion is
+    // deliberately NOT applied here: this site has no row context and does not
+    // gate readiness.
+    return sortedUnique(extractPhaseDependencyTokens(m[1], phaseIdConvention));
 }
 /**
  * This phase's own ROADMAP.md section body — milestone-scoped via the SAME
@@ -949,9 +937,9 @@ function extractDependencyTokens(sectionBody) {
  * sibling phase whose TITLE merely mentions this phase's number is never
  * hijacked.
  */
-function findPhaseRoadmapSection(cwd, roadmapText, phaseId) {
+function findPhaseRoadmapSection(cwd, roadmapText, phaseId, directoryContext) {
     const scoped = extractCurrentMilestone(roadmapText, cwd);
-    const headingRe = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${phaseMarkdownRegexSource(phaseId)}(?=[\\s:(]|$)`, 'i');
+    const headingRe = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${phaseMarkdownRegexSource(phaseId, directoryContext)}(?=[\\s:(]|$)`, 'i');
     const section = collectSection(scoped, (h) => headingRe.test(h.text));
     return section ? section.body : null;
 }
@@ -976,7 +964,7 @@ function findPhaseRoadmapSection(cwd, roadmapText, phaseId) {
  * `readDocument(paths.roadmap)` read, keeps both the read path and the
  * "found vs missing vs unreadable" distinction singular.
  */
-function buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phaseDirLabel, diagnostics) {
+function buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phaseDirLabel, phaseIdConvention, diagnostics, directoryContext) {
     if (!roadmapDoc.readable || roadmapDoc.text === null) {
         diagnostics.push({
             code: INSPECT_DIAGNOSTIC.ROADMAP_UNSCOPED,
@@ -999,7 +987,7 @@ function buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phaseDirLabel,
             dependencies: { value: [], scope: SCOPE.UNSCOPED },
         };
     }
-    const sectionBody = findPhaseRoadmapSection(cwd, roadmapDoc.text, phaseId);
+    const sectionBody = findPhaseRoadmapSection(cwd, roadmapDoc.text, phaseId, directoryContext);
     if (sectionBody === null) {
         diagnostics.push({
             code: INSPECT_DIAGNOSTIC.ROADMAP_UNSCOPED,
@@ -1013,7 +1001,7 @@ function buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phaseDirLabel,
     }
     return {
         goal: { value: extractGoalProse(sectionBody), scope: SCOPE.COMPLETE },
-        dependencies: { value: extractDependencyTokens(sectionBody), scope: SCOPE.COMPLETE },
+        dependencies: { value: extractDependencyTokens(sectionBody, phaseIdConvention), scope: SCOPE.COMPLETE },
     };
 }
 // ─── Entry points ─────────────────────────────────────────────────────────────
@@ -1031,6 +1019,7 @@ function buildPlanningInspectResult(cwd) {
     let statusError = null;
     const diagnostics = [];
     const paths = planningPaths(cwd);
+    const phaseIdConvention = resolvePhaseIdConvention(cwd);
     const planningExists = node_fs_1.default.existsSync(paths.planning);
     if (!planningExists) {
         diagnostics.push({
@@ -1040,6 +1029,7 @@ function buildPlanningInspectResult(cwd) {
         });
     }
     const snapshot = buildPlanningSnapshot(cwd);
+    const directoryContext = snapshot.directoryContext;
     if (snapshot.milestone.scope !== SCOPE.COMPLETE) {
         diagnostics.push({
             code: INSPECT_DIAGNOSTIC.ROADMAP_UNSCOPED,
@@ -1072,14 +1062,14 @@ function buildPlanningInspectResult(cwd) {
     // one phase.
     const checkboxByPhaseKey = new Map();
     for (const [token, ticked] of Object.entries(checkboxes)) {
-        checkboxByPhaseKey.set(phaseKeyFromToken(token), ticked);
+        checkboxByPhaseKey.set(phaseKeyFromToken(token, directoryContext), ticked);
     }
     const phaseSnapshots = snapshot.phases.value;
     // Canonical per-directory identity keys (`phase-id.cts`'s
     // `phaseKeyFromDir`), not a raw regex scrape — this is the set
     // `buildRequirements` below matches Traceability tokens against via
     // `phaseKeyFromToken`.
-    const knownPhaseKeys = new Set(windowed.map((dir) => phaseKeyFromDir(dir)));
+    const knownPhaseKeys = new Set(windowed.map((dir) => phaseKeyFromDir(dir, undefined, directoryContext)));
     // Read once, shared across every phase row's goal/dependencies lookup —
     // the same `readDocument` seam every other document read in this module
     // uses, never a second file-reading path.
@@ -1124,8 +1114,10 @@ function buildPlanningInspectResult(cwd) {
             verification = { status: null, next_action: err.message, route: '' };
         }
         const token = /^(\d+(?:\.\d+)*)/.exec(phase.dir);
-        const phaseId = token ? token[1] : null;
-        const { goal, dependencies } = buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phase.dir, diagnostics);
+        const custom = phaseIdMod.customPhaseQuery(phase.dir, directoryContext);
+        const owner = custom && phaseIdMod.customPhaseDirectoryParts(phase.dir, custom);
+        const phaseId = owner ? owner.id : token ? token[1] : null;
+        const { goal, dependencies } = buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phase.dir, phaseIdConvention, diagnostics, directoryContext);
         // `uat.foldScope`, NOT `uat.scope` (#3078 round-8). The two currently
         // agree at every call site — see `buildUatRows` for why the field is
         // still kept separate — so folding either one here produces the same
@@ -1159,8 +1151,8 @@ function buildPlanningInspectResult(cwd) {
                 route: verification.route,
             },
             roadmap_acceptance: {
-                checkbox: checkboxByPhaseKey.has(phaseKeyFromDir(phase.dir))
-                    ? checkboxByPhaseKey.get(phaseKeyFromDir(phase.dir))
+                checkbox: checkboxByPhaseKey.has(phaseKeyFromDir(phase.dir, undefined, directoryContext))
+                    ? checkboxByPhaseKey.get(phaseKeyFromDir(phase.dir, undefined, directoryContext))
                     : null,
                 // ADR-3180 §7.4: a ticked checkbox is a human annotation with no
                 // machine authority. Stated in the payload so a consumer cannot
@@ -1174,7 +1166,7 @@ function buildPlanningInspectResult(cwd) {
             scope: folded,
         };
     });
-    const requirements = buildRequirements(paths.requirements, knownPhaseKeys, diagnostics, paths.planning);
+    const requirements = buildRequirements(paths.requirements, knownPhaseKeys, diagnostics, paths.planning, directoryContext);
     const phaseScope = worstScope(snapshot.phaseDirs.scope, snapshot.phases.scope, ...phaseRows.map((p) => p.scope));
     const acceptedPhases = makeFraction(phaseRows.filter((p) => p.complete).length, phaseRows.length, phaseScope, 'progress.accepted_phases', diagnostics);
     const completedPlans = makeFraction(phaseRows.reduce((sum, p) => sum + p.summary_count, 0), phaseRows.reduce((sum, p) => sum + p.plan_count, 0), phaseScope, 'progress.completed_plans', diagnostics);

package/gsd-core/bin/lib/planning-snapshot.cjs

@@ -29,7 +29,7 @@ const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestoneInfo, extractCurrentMilestone } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
@@ -51,6 +51,7 @@ const { planningPaths, planningRoot, resolvePhaseIdConvention, resolveEnvWorkstr
 // PROSE, not quoted literals.
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const phase_entry_grammar_cjs_1 = require("./phase-entry-grammar.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterMod = require("./frontmatter.cjs");
 const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
@@ -129,7 +130,9 @@ function buildPhaseSnapshot(phasesDir, dir, convention) {
         dir,
         complete: completionResult.value.complete,
         verificationStatus: completionResult.value.verification.status,
-        verificationStatusError: statusError ? { file: statusError.file, message: statusError.message } : null,
+        verificationStatusError: statusError
+            ? { file: statusError.file, message: statusError.message, rawStatus: statusError.rawStatus }
+            : null,
         planCount: scanResult.planCount,
         summaryCount: scanResult.summaryCount,
         scope: worstScope(completionResult.scope, scanResult.scope),
@@ -584,7 +587,7 @@ function buildRoadmapDeclaredPhasesField(roadmapPath, convention) {
  * diagnostic (W011) whose entire purpose is flagging when the two DISAGREE —
  * reading the data is not re-litigating who is authoritative.
  */
-function buildRoadmapPhaseCheckboxesField(roadmapPath, convention) {
+function buildRoadmapPhaseCheckboxesField(roadmapPath, convention, directoryContext) {
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         return { value: {}, scope: SCOPE.UNREADABLE };
     }
@@ -603,7 +606,9 @@ function buildRoadmapPhaseCheckboxesField(roadmapPath, convention) {
     // vanish from the exclusion set and every unstarted bracket phase gains a
     // W006. NON-capturing (`capturing` defaults false), so the phase token stays
     // group 2 and the legacy repo compiles a byte-identical source.
-    const checkboxRe = new RegExp(`-\\s*\\[([xX ])\\].*?${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}0*(${PHASE_NUMBER_TOKEN_SOURCE})${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi');
+    // The entry prefix (marker, box, bold token) is the phase-entry grammar's (#5764),
+    // the same one `buildNotStartedPhaseVariants` composes; group 1 is the box.
+    const checkboxRe = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}0*(${convention === 'bracket' ? PHASE_NUMBER_TOKEN_SOURCE : phaseIdMod.phaseScanTokenSource(directoryContext)})${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi', { state: 'captured' });
     const value = {};
     let m;
     while ((m = checkboxRe.exec(content)) !== null) {
@@ -862,7 +867,7 @@ function buildArchivedPhaseTokensField(planBase, convention) {
  * ROADMAP.md degrades to an empty list, mirroring every other
  * ROADMAP-sourced field's absent-file handling.
  */
-function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath, convention) {
+function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath, convention, directoryContext) {
     if (!node_fs_1.default.existsSync(roadmapPath))
         return { value: [], scope: SCOPE.UNREADABLE };
     let content;
@@ -900,7 +905,7 @@ function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath, convention)
     // pinned to this site by name) would catch that narrowing, since the census
     // only pins `phaseHeadingPrefixSrcFor`'s own output, not this regex's tail.
     // Kept as its own composition to preserve this exact byte-for-behavior.
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, Boolean(bracketGroup))}(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, Boolean(bracketGroup))}(${convention !== 'bracket' ? phaseIdMod.phaseScanTokenSource(directoryContext) : PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
     const value = [];
     for (const m of scoped.matchAll(phasePattern)) {
         const bracketId = bracketGroup ? m[1] : undefined;
@@ -1019,6 +1024,7 @@ function buildPlanningSnapshot(cwd) {
     // See the `phaseIdConvention` field's comment for why one resolution point is
     // load-bearing rather than a micro-optimisation.
     const phaseIdConvention = resolvePhaseIdConvention(cwd) ?? null;
+    const directoryContext = phaseDirectoryOptions(cwd);
     // #4257: the workstream `planningPaths(cwd)` just scoped every read to
     // (its `planningDir` call applies this exact discriminator when handed no
     // `ws`), resolved through the same owner so W002's scope clause names the
@@ -1066,17 +1072,18 @@ function buildPlanningSnapshot(cwd) {
         statePhaseTokens: stateFields.statePhaseTokens,
         stateStatus: stateFields.stateStatus,
         roadmapDeclaredPhases: roadmapDeclared.declared,
-        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap, phaseIdConvention),
+        roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap, phaseIdConvention, directoryContext),
         researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope, phaseIdConvention),
         milestoneArchiveStatus: buildMilestoneArchiveStatusField(cwd),
         planningRootFiles: buildPlanningRootFilesField(cwd),
         allPhaseDirNames,
         archivedPhaseTokens: buildArchivedPhaseTokensField(paths.planning, phaseIdConvention),
-        currentMilestoneRoadmapPhaseIds: buildCurrentMilestoneRoadmapPhaseIdsField(cwd, paths.roadmap, phaseIdConvention),
+        currentMilestoneRoadmapPhaseIds: buildCurrentMilestoneRoadmapPhaseIdsField(cwd, paths.roadmap, phaseIdConvention, directoryContext),
         perPhasePlanNumbering: perPhasePlanScanFields.perPhasePlanNumbering,
         perPhaseOrphanSummaries: perPhasePlanScanFields.perPhaseOrphanSummaries,
         perPhaseWaveMissingPlans: perPhasePlanScanFields.perPhaseWaveMissingPlans,
         phaseIdConvention,
+        directoryContext,
         roadmapSentinelPhaseTokens: roadmapDeclared.sentinelTokens,
         roadmapBracketIncoherences: buildRoadmapBracketIncoherencesField(paths.roadmap, phaseIdConvention),
         workstream,

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -186,12 +186,12 @@ function ownConfigValue(configPath, keyPath) {
  * GSD_PROJECT/GSD_WORKSTREAM value containing path separators or `..`, and
  * that shape resolves to "not present".
  */
-function readScopedConfigValue(cwd, keyPath) {
+function readScopedConfigValue(cwd, keyPath, workstream) {
     try {
-        const scoped = ownConfigValue(node_path_1.default.join(planningDir(cwd), 'config.json'), keyPath);
+        const scoped = ownConfigValue(node_path_1.default.join(planningDir(cwd, workstream), 'config.json'), keyPath);
         if (scoped.present)
             return scoped;
-        if (resolveEnvWorkstream() !== null) {
+        if ((workstream === undefined ? resolveEnvWorkstream() : workstream) !== null) {
             return ownConfigValue(node_path_1.default.join(planningRoot(cwd), 'config.json'), keyPath);
         }
     }
@@ -630,6 +630,22 @@ function findContextMdIn(absDirOrFiles) {
         return { file: null, files: [], scope: SCOPE.UNREADABLE };
     }
 }
+/**
+ * Is `name` the phase's requirements SPEC (#5629)? A plain `NN-SPEC.md`: the `-AI-SPEC.md` (AI design
+ * contract) and `-UI-SPEC.md` (UI design contract) variants have other purposes and never lock requirements.
+ * The one definition behind the init payloads' `has_spec` / `spec_path`, the discuss and plan-phase workflows
+ * (which read those fields) and the context-drift gate, so they cannot disagree about which file is "the SPEC".
+ */
+function isPhaseSpecFile(name) {
+    return name.endsWith('-SPEC.md') && !name.endsWith('-AI-SPEC.md') && !name.endsWith('-UI-SPEC.md');
+}
+/**
+ * The phase SPEC in an already-read directory listing, or `null`. The lexically first match, so the answer
+ * does not depend on the filesystem's readdir order. The caller's array is not reordered.
+ */
+function findPhaseSpecIn(files) {
+    return files.filter(isPhaseSpecFile).sort()[0] ?? null;
+}
 module.exports = {
     worktreesOptedOut,
     readScopedConfigValue,
@@ -655,6 +671,8 @@ module.exports = {
     diagnoseUnresolvedActiveWorkstream,
     describeUnresolvedWorkstreamReason,
     findContextMdIn,
+    isPhaseSpecFile,
+    findPhaseSpecIn,
     // Test seam (audit M1): inject a deterministic isPidAlive so the liveness-gated
     // steal decision is exercised without real pids. Mirrors capability-lock.cts.
     _setLockProbes(probes) {

package/gsd-core/bin/lib/pristine-baseline.cjs

@@ -34,6 +34,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 /**
  * SHA-256 hex digest of a file's raw bytes. Byte-for-byte the same digest
  * install.js fileHash() records into manifests and backup-meta.json.
@@ -144,13 +145,20 @@ function isCleanRelativePosixPath(relPath) {
 }
 function gitExec(gitDir, args) {
     return (0, node_child_process_1.execFileSync)('git', args, {
+        // windowsHide (#685): a console-window flash per git call would spam the
+        // user on Windows for what is a background, read-only history walk. Kept
+        // high in the options so the completeness guard's 400-char scan finds it.
+        windowsHide: true,
         cwd: gitDir,
         encoding: 'utf8',
+        // #5048: every call here is a history/objects walk that never opens the
+        // index, so the variable is inert today — set anyway so a future `status` /
+        // `diff` caller inherits it. The block is owned by
+        // src/read-only-git-env.cts and shared with every other read-only seam.
+        // Parity: tests/git-optional-locks-parity.test.cjs.
+        env: (0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
         timeout: GIT_SUBPROCESS_TIMEOUT_MS,
         maxBuffer: GIT_MAX_BUFFER_BYTES,
-        // windowsHide (#685): a console-window flash per git call would spam the
-        // user on Windows for what is a background, read-only history walk.
-        windowsHide: true,
         // stderr is discarded: "file absent in commit" is an expected walk outcome,
         // not operator-visible diagnostics.
         stdio: ['ignore', 'pipe', 'ignore'],

package/gsd-core/bin/lib/read-only-git-env.cjs

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * read-only-git-env.cts — the single owner of the read-only git env block
+ * (#5048). CONTEXT.md / OS Shell Projection seam.
+ *
+ * By default `git status` refreshes the index and takes an *optional*
+ * `.git/index.lock` to write the refreshed copy back. That is a write the caller
+ * never asked for, and it turns a pure read into a contender for the lock a
+ * real `git add` / `git commit` needs — so a read-only statusline render can
+ * make a concurrent commit fail with
+ * `Unable to create '.git/index.lock': File exists`. `GIT_OPTIONAL_LOCKS=0`
+ * tells git to skip only those *optional* index operations. Nothing a read
+ * needs is lost: `git status` reads the index, it just doesn't need to rewrite
+ * it.
+ *
+ * ## Why this module exists
+ *
+ * The block used to be hand-written at every seam that spawns git for a read.
+ * Six copies of `{ ...process.env, GIT_OPTIONAL_LOCKS: '0' }` is six places to
+ * forget when a seam is added, and a probe that checks each seam for the literal
+ * value passes even when a seam stopped consulting the owner. One owner makes
+ * the drift structural instead: the parity test patches THIS function to a
+ * sentinel and asserts every seam's spawn carries the sentinel, so a seam that
+ * hand-writes the variable again fails red rather than passing quietly.
+ * (tests/git-optional-locks-parity.test.cjs, "#5048 every seam reads the shared
+ * owner".)
+ *
+ * ## Why the hook scripts require the built artifact
+ *
+ * `hooks/*.js` are staged as standalone files at install time, so they reach
+ * compiled `src/` modules through `../gsd-core/bin/lib/*.cjs` rather than a
+ * sibling hooks/-tree file — the same rule hooks/lib/git-cmd.js follows for
+ * token-scanner. They call `readOnlyGitEnv()` per spawn rather than snapshotting
+ * the result at module load, so a later `process.env` mutation is visible and the
+ * two behave identically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GIT_LOCATION_ENV_VARS = void 0;
+exports.scrubGitLocationEnv = scrubGitLocationEnv;
+exports.readOnlyGitEnv = readOnlyGitEnv;
+/**
+ * #5548: env vars that make git act on a repository other than the one `cwd`
+ * names (git sets them inside hooks; wrappers export them). This is
+ * `git rev-parse --local-env-vars` minus GIT_CONFIG, GIT_CONFIG_PARAMETERS and
+ * GIT_CONFIG_COUNT, which inject config (e.g. CI `safe.directory`) rather than
+ * select a repository. (They are not repository-neutral: `GIT_CONFIG_COUNT` with a
+ * `core.worktree` pair can still redirect git, but a caller who controls the
+ * environment can already inject `core.sshCommand` or `core.fsmonitor`.)
+ * hooks/lib/git-probe.js carries a parity-tested copy.
+ */
+exports.GIT_LOCATION_ENV_VARS = [
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+    'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS',
+    'GIT_REPLACE_REF_BASE', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+];
+/** Copy of `env` without the repo-location vars; case-insensitive (Windows keeps `Git_Dir` casing). */
+function scrubGitLocationEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter(([k]) => !exports.GIT_LOCATION_ENV_VARS.includes(k.toUpperCase())));
+}
+/**
+ * Build the env for a read-only git spawn.
+ *
+ * @param base Environment to spread, `process.env` minus the repo-location vars by default (#5548). Callers that
+ *   layer extra git variables on top (GIT_TERMINAL_PROMPT, a caller's own
+ *   overrides) pass them in `base`; callers that must let a caller-supplied
+ *   override win spread the result and apply their own keys afterwards.
+ * @returns A fresh object each call — never the cached `process.env`.
+ */
+function readOnlyGitEnv(base = scrubGitLocationEnv(process.env)) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        // process.env carries undefined-valued keys on some platforms; spawn()
+        // rejects a non-string value rather than ignoring it.
+        if (value !== undefined)
+            env[key] = value;
+    }
+    env.GIT_OPTIONAL_LOCKS = '0';
+    return env;
+}

package/gsd-core/bin/lib/refactor-trigger-command-router.cjs

@@ -58,7 +58,7 @@ const { routeHubCommandFamily } = cjsCommandRouterAdapter;
 const { isCapabilityActive } = capabilityStateMod;
 const { resolveConfigKey } = capabilityActivationMod;
 const { loadConfig } = configLoaderMod;
-const { findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
 const { planningDir } = planningWorkspaceMod;
 const CAPABILITY_ID = 'refactor-trigger';
 // Default CoreModule implementation. `_core` seam overrides this entirely
@@ -148,7 +148,7 @@ function requirePhaseArg(args, complexity, usage) {
  * REFACTOR_GIT_UNAVAILABLE, for this case.
  */
 function resolvePhaseDirForArg(cwd, phaseArg) {
-    const search = findPhaseInternal(cwd, phaseArg);
+    const search = findPhaseInternal(cwd, phaseArg, undefined, phaseDirectoryOptions(cwd));
     if (!search || search.found !== true)
         return null;
     return { phaseDir: search.directory, padded: search.phase_number };