@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/gap-checker.cjs

@@ -23,7 +23,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
-const { output, error } = io;
+const { output, error, formatDiagnosticToken } = io;
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -54,6 +54,17 @@ function parseRequirements(reqMd) {
     // The **ID** is extracted from the bullet text caller-side — the seam provides
     // the raw text; we parse the bold-ID prefix from it here.
     const boldIdRe = new RegExp(`^\\*\\*(${ID_PATTERN})\\*\\*\\s*(.*)$`);
+    // The shipped template (gsd-core/templates/requirements.md) writes
+    // `- [ ] **AUTH-01**: User can sign up` — a single separator delimiter
+    // between the bold ID and the description. Strip AT MOST ONE leading
+    // delimiter (plus its surrounding whitespace) before the final `.trim()`,
+    // mirroring roadmap-parser.cts's `stripLeadingDelimiter` delimiter set
+    // (em dash, en dash, colon, hyphen) — that helper is not exported, and its
+    // own `+`-quantified strip removes an entire delimiter RUN, which would
+    // also eat a second, meaningful marker (`**X-01**: -- weird` must keep the
+    // `--`), so the set is mirrored here with a single-occurrence match instead
+    // of reused verbatim.
+    const ONE_LEADING_DELIMITER_RE = /^\s*[—–:-]\s*/;
     for (const bullet of (0, markdown_sectionizer_cjs_1.iterateBullets)(reqMd)) {
         if (bullet.marker !== 'checkbox-unchecked' && bullet.marker !== 'checkbox-checked')
             continue;
@@ -65,7 +76,8 @@ function parseRequirements(reqMd) {
             continue;
         if (!seen.has(id)) {
             seen.add(id);
-            out.push({ id, text: (m[2] || '').trim() });
+            const rawText = m[2] || '';
+            out.push({ id, text: rawText.replace(ONE_LEADING_DELIMITER_RE, '').trim() });
         }
     }
     // Pipe-table-row path and separator-row skip stay caller-side
@@ -290,6 +302,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '',
             summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: null,
         };
     }
     const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
@@ -313,11 +326,18 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     // Read the phase directory once; reuse the listing for both context detection
     // and plan-file enumeration (avoids redundant readdirSync calls).
     let phaseDirFiles = [];
+    // #3885 (ADR-3473 §8.5): the existsSync guard above already means a catch
+    // here is NEVER "genuinely absent" (ENOENT) — this directory exists, so any
+    // failure to list it is a real read error (EACCES/EIO/...) and must be
+    // named, not folded into the same `[]` an absent directory produces.
+    let phaseDirReadError = null;
     try {
         if (node_fs_1.default.existsSync(absPhaseDir))
             phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
     }
-    catch { /* unreadable */ }
+    catch (err) {
+        phaseDirReadError = `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
+    }
     // #3511-class: scope the raw listing to this phase dir before the
     // phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
     // it is also reused below only as a `.length > 0` guard ahead of
@@ -384,6 +404,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 table: formatGapTable(rows) + '\n' + coverageSummary + '\n\n' + mismatchMsg,
                 summary: coverageSummary + '; extracted 0 of N — possible format mismatch',
                 counts: { total: rows.length, covered, uncovered },
+                phase_dir_read_error: phaseDirReadError,
             };
         }
         return {
@@ -392,6 +413,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: mismatchMsg,
             summary: 'extracted 0 of N — possible format mismatch',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: phaseDirReadError,
         };
     }
     // #1365: if no items at all, surface a clean no-check message.
@@ -408,6 +430,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
             summary: 'no requirements or decisions to check',
             counts: { total: 0, covered: 0, uncovered: 0 },
+            phase_dir_read_error: phaseDirReadError,
         };
     }
     const rows = sortRows([
@@ -425,6 +448,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         table: formatGapTable(rows) + '\n' + summary + '\n',
         summary,
         counts: { total: rows.length, covered, uncovered },
+        phase_dir_read_error: phaseDirReadError,
     };
 }
 function cmdGapAnalysis(cwd, args, raw) {

package/gsd-core/bin/lib/git-base-branch.cjs

@@ -34,57 +34,134 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readConfigBaseBranch = readConfigBaseBranch;
+exports._readGitNested = _readGitNested;
+exports._readGitKey = _readGitKey;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 exports.tryLocalBranch = tryLocalBranch;
 exports.resolveBaseBranchDiagnostics = resolveBaseBranchDiagnostics;
 exports.resolveBaseBranch = resolveBaseBranch;
+exports.resolveProtectedBranchStatus = resolveProtectedBranchStatus;
 exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
 exports.phaseStartCommit = phaseStartCommit;
 exports.changedFilesSince = changedFilesSince;
 exports.cmdGitBaseBranch = cmdGitBaseBranch;
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const configuration_cjs_1 = require("./configuration.cjs");
+const security_cjs_1 = require("./security.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-// ─── Helpers ──────────────────────────────────────────────────────────────────
+const { error, ERROR_REASON } = io;
+const { loadConfig: loadConfigSeam } = configLoader;
+/** Render a rejected config value for a diagnostic without throwing on exotic input. */
+function renderRejected(value) {
+    try {
+        return (0, security_cjs_1.sanitizeLabel)(JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        return (0, security_cjs_1.sanitizeLabel)(String(value));
+    }
+}
+/** Nested-only read of `git.<field>`, mirroring `loadConfigResolved`'s `getNested`. */
+function _readGitNested(config, field) {
+    const git = config['git'];
+    if (git !== null && typeof git === 'object' && !Array.isArray(git)) {
+        return git[field];
+    }
+    return undefined;
+}
+/**
+ * Flat-then-nested read, mirroring `loadConfigResolved`'s own `get()`.
+ *
+ * Used for `base_branch` ONLY, and only because it HAS a legacy flat spelling:
+ * `normalizeLegacyKeys` normally hoists it away, so a flat key that SURVIVED
+ * normalization is one the migration refused (a non-object `git` section,
+ * #3760) and is the user's last remaining expression of intent.
+ *
+ * `protected_branches` deliberately does NOT use this. It is new in #3552 with
+ * no legacy form, so honouring a top-level spelling would invent an
+ * undocumented alias that silently outranks the canonical nested key
+ * (round-4 external review).
+ */
+function _readGitKey(config, field) {
+    if (config[field] !== undefined)
+        return config[field];
+    return _readGitNested(config, field);
+}
 /**
- * Safely look up `git.base_branch` from the project's config.json.
- * Returns the configured value (a non-empty, non-null string) or null.
+ * Read the effective root/workstream configuration once for branch policy.
+ *
+ * Production takes the `loadConfig` branch, with `persist: false` — this is a
+ * PREDICATE, invoked on every `execute-phase` and every `ship` run, and a
+ * question must not rewrite the file it is asking about. Without it, any project
+ * carrying a legacy flat key (`base_branch`, `branching_strategy`, `depth`, …)
+ * has `.planning/config.json` silently normalized and rewritten by a call whose
+ * entire contract is to answer a boolean (#3648 review Blocker 1).
+ *
+ * The `readFile` branch is a unit-test seam, NOT a second production path, and
+ * it is deliberately narrower than `loadConfig`. It covers exactly two of
+ * production's steps — `normalizeLegacyKeys`, then the flat-then-nested lookup
+ * — over a single `<cwd>/.planning/config.json`. It does NOT apply
+ * root/workstream `_deepMergeConfig`, builtin or `~/.gsd/defaults.json`
+ * defaults, or `mergeFederatedConfig`. Tests that assert on any of those must
+ * drive `loadConfig` instead; the seam's own tests are scoped to normalization
+ * and shape validation, which is all it reproduces (#3648 review Major 3).
  */
-function readConfigBaseBranch(planningDir, deps) {
-    const readFile = deps?.readFile ??
-        ((p) => { try {
-            return node_fs_1.default.readFileSync(p, 'utf8');
+function readEffectiveGitConfig(cwd, deps) {
+    let config = {};
+    if (deps?.readFile && !deps.loadConfig) {
+        const raw = deps.readFile(node_path_1.default.join(cwd, '.planning', 'config.json'));
+        if (raw) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    const { parsed: normalized } = (0, configuration_cjs_1.normalizeLegacyKeys)(parsed);
+                    config = {
+                        base_branch: _readGitKey(normalized, 'base_branch'),
+                        protected_branches: _readGitNested(normalized, 'protected_branches'),
+                    };
+                }
+            }
+            catch { /* malformed direct edit contributes no policy values */ }
         }
-        catch {
-            return null;
-        } });
-    const configPath = node_path_1.default.join(planningDir, 'config.json');
-    const raw = readFile(configPath);
-    if (!raw)
-        return null;
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
     }
-    catch {
-        return null;
+    else {
+        try {
+            config = (deps?.loadConfig ?? loadConfigSeam)(cwd, { persist: false });
+        }
+        catch { /* configuration loading is fail-soft for branch resolution */ }
     }
-    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
-        return null;
-    const top = cfg;
-    // Support both "git.base_branch" (nested) and "base_branch" (flat legacy)
-    const gitSection = top.git;
-    if (gitSection && typeof gitSection === 'object' && !Array.isArray(gitSection)) {
-        const nested = gitSection.base_branch;
-        if (typeof nested === 'string' && nested.trim())
-            return nested.trim();
+    const rawBaseBranch = config.base_branch;
+    const baseBranch = typeof rawBaseBranch === 'string' && rawBaseBranch.trim()
+        ? rawBaseBranch.trim()
+        : null;
+    // A protection predicate must not fail OPEN. `config-set` validation is
+    // bypassable by a direct edit of .planning/config.json, so one bad element
+    // discarding the whole list would silently answer "not protected" for names
+    // the user believes are protected — the exact failure #3552 exists to close,
+    // reintroduced through a different door (#3648 review Blocker 3). Drop only
+    // the bad elements, and report every rejection so it cannot pass unnoticed.
+    const rawProtectedBranches = config.protected_branches;
+    const protectedBranches = [];
+    const rejectedProtectedBranches = [];
+    if (Array.isArray(rawProtectedBranches)) {
+        for (const branch of rawProtectedBranches) {
+            if (typeof branch === 'string' && branch.trim() !== '') {
+                protectedBranches.push(branch.trim());
+            }
+            else {
+                rejectedProtectedBranches.push(renderRejected(branch));
+            }
+        }
+    }
+    else if (rawProtectedBranches !== undefined && rawProtectedBranches !== null) {
+        // Not a list at all — contributes no names, but is still a misconfiguration.
+        rejectedProtectedBranches.push(renderRejected(rawProtectedBranches));
     }
-    const flat = top.base_branch;
-    if (typeof flat === 'string' && flat.trim())
-        return flat.trim();
-    return null;
+    return { baseBranch, protectedBranches, rejectedProtectedBranches };
 }
 /**
  * Try `git symbolic-ref --short refs/remotes/origin/HEAD` (no network).
@@ -170,7 +247,7 @@ function tryLocalBranch(cwd, execGit) {
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  */
-function resolveBaseBranchDiagnostics(cwd, deps) {
+function resolveBaseBranchDiagnosticsWithConfig(cwd, configured, deps) {
     const rawExecGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     // A genuine execGit failure (timeout, or the call could not even spawn —
     // e.g. git missing, surfaced as exitCode 127 with `error` set) is distinct
@@ -186,10 +263,7 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
             anyGitFailure = true;
         return r;
     };
-    // Derive .planning dir relative to cwd (mirrors planningDir() in planning-workspace.cjs)
-    const planningDir = node_path_1.default.join(cwd, '.planning');
     // 1. Config override
-    const configured = readConfigBaseBranch(planningDir, deps);
     if (configured)
         return { branch: configured, verified: true };
     // 2. symbolic-ref (fast, no network)
@@ -210,6 +284,10 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
     // not answer (#3057 B4).
     return { branch: 'main', verified: !anyGitFailure };
 }
+function resolveBaseBranchDiagnostics(cwd, deps) {
+    const { baseBranch } = readEffectiveGitConfig(cwd, deps);
+    return resolveBaseBranchDiagnosticsWithConfig(cwd, baseBranch, deps);
+}
 /**
  * Resolve the default/base branch for the repository at `cwd`.
  *
@@ -220,6 +298,19 @@ function resolveBaseBranchDiagnostics(cwd, deps) {
 function resolveBaseBranch(cwd, deps) {
     return resolveBaseBranchDiagnostics(cwd, deps).branch;
 }
+/** Resolve the base branch plus configured protected-branch extensions. */
+function resolveProtectedBranchStatus(cwd, currentBranch, deps) {
+    const effectiveConfig = readEffectiveGitConfig(cwd, deps);
+    const { branch: baseBranch, verified } = resolveBaseBranchDiagnosticsWithConfig(cwd, effectiveConfig.baseBranch, deps);
+    const protectedBranches = [...new Set([baseBranch, ...effectiveConfig.protectedBranches])];
+    return {
+        baseBranch,
+        protectedBranches,
+        rejectedProtectedBranches: effectiveConfig.rejectedProtectedBranches,
+        isProtected: protectedBranches.includes(currentBranch),
+        verified,
+    };
+}
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the
  * absolute path of the worktree root.
@@ -352,7 +443,51 @@ function changedFilesSince(cwd, sinceRef, execGit) {
  * Resolves the default branch and writes it to stdout (raw string, newline-terminated).
  * Called by workflows via `gsd_run query git.base-branch`.
  */
-function cmdGitBaseBranch(cwd, _args, deps) {
+function cmdGitBaseBranch(cwd, args, deps) {
+    if (args[0] === '--is-protected') {
+        if (args.length > 2) {
+            error('Usage: git base-branch --is-protected [<branch>]', ERROR_REASON.USAGE);
+        }
+        const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));
+        // `git branch --show-current` prints nothing on a detached HEAD, so the
+        // call sites legitimately pass an explicit empty string: no protected
+        // branch is named '', the answer is false, and that is not a fault worth
+        // reporting. The flag with NO argument is a different thing — a caller bug
+        // that `args[1] ?? ''` used to collapse into the detached-HEAD case. Same
+        // handling, but said out loud so the two can be told apart.
+        //
+        // This diagnostic deliberately does NOT state the answer. The empty branch
+        // matches no protected name, but the fail-closed guard below still renders
+        // `true` when the base branch could not be verified — so promising "false"
+        // here would contradict what this same call prints on stdout (#3648 review).
+        if (args.length < 2) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected was called without a branch argument; ` +
+                `treating it as an empty branch name. Pass the branch to test, ` +
+                `e.g. --is-protected "$CURRENT_BRANCH".\n`);
+        }
+        const status = resolveProtectedBranchStatus(cwd, args[1] ?? '', deps);
+        if (status.rejectedProtectedBranches.length > 0) {
+            writeDiagnostic(`⚠ git-base-branch: ignoring ${status.rejectedProtectedBranches.length} unusable ` +
+                `git.protected_branches entr${status.rejectedProtectedBranches.length === 1 ? 'y' : 'ies'} ` +
+                `(${status.rejectedProtectedBranches.join(', ')}) — each must be a non-empty branch name. ` +
+                `The remaining names are still enforced. See #3552.\n`);
+        }
+        // A protection guard must fail closed: if the base branch could not be
+        // verified against this repository (a git query timed out or failed to
+        // run — #3057 B4), report "protected" rather than silently trusting an
+        // unverified guess that might happen to not match the current branch.
+        const rendered = String(status.verified ? status.isProtected : true);
+        if (!status.verified) {
+            writeDiagnostic(`⚠ git-base-branch: --is-protected could not verify repository branch metadata; ` +
+                `defaulting to protected (fail-closed). See #3057.\n`);
+        }
+        const write = deps?.write ?? ((s) => process.stdout.write(s));
+        write(rendered + '\n');
+        return rendered;
+    }
+    if (args.length > 0) {
+        error(`Unknown flag for git.base-branch: ${args[0]}`, ERROR_REASON.USAGE);
+    }
     const { branch, verified } = resolveBaseBranchDiagnostics(cwd, deps);
     if (!verified) {
         const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));

package/gsd-core/bin/lib/health-diagnostic-rules/consistency.cjs

@@ -35,7 +35,7 @@ const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
 const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { isSentinelPhaseId } = phaseIdMod;
+const { isSentinelPhaseDir } = phaseIdMod;
 // ─── C001 — gap in disk phase numbering (integer sequence) ────────────────
 // (verify.cts:1504-1519)
 function checkC001(snapshot) {
@@ -47,8 +47,12 @@ function checkC001(snapshot) {
         return [];
     const integerPhases = snapshot.allPhaseDirNames.value
         // #3225: exclude sentinel phase ids (999.x/0.x) — never part of the
-        // sequential numbering, mirrors verify.cts:1510 verbatim.
-        .filter((p) => !p.includes('.') && !isSentinelPhaseId(p))
+        // sequential numbering, mirrors verify.cts:1510 verbatim. The dot filter
+        // already drops every code-prefixed (bracket) name before the sentinel
+        // test, so the dir-aware recognizer below is defense-in-depth for the
+        // dotless legacy forms — kept so this guard cannot regress if the dot
+        // filter is ever loosened (#3639).
+        .filter((p) => !p.includes('.') && !isSentinelPhaseDir(p))
         .map((p) => parseInt(p, 10))
         .filter((n) => !Number.isNaN(n))
         .sort((a, b) => a - b);

package/gsd-core/bin/lib/health-diagnostic-rules/roadmap-disk-consistency.cjs

@@ -104,7 +104,7 @@ const planningScopeMod = require("../planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("../phase-id.cjs");
-const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId } = phaseIdMod;
+const { matchPhaseDirs, normalizePhaseName, extractPhaseToken, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const validateMod = require("../validate.cjs");
 const { phaseVariants } = validateMod;
@@ -231,8 +231,11 @@ function checkW007(snapshot) {
         // `verify.cts:1373-1397`) — same token, relocated read, not reinvented.
         const token = extractPhaseToken(dirName);
         // #3225: a sentinel dir on disk (999-interim, 0-drafts) is defined as
-        // never-on-roadmap; it must not trigger W007.
-        if (isSentinelPhaseId(token))
+        // never-on-roadmap; it must not trigger W007. #3639: judged on the DIR
+        // NAME via the dir-aware recognizer — the extracted token is
+        // milestone-stripped, so a bracket sentinel (GSD.999-07-icebox) was
+        // invisible to the id predicate and false-fired as an orphan.
+        if (isSentinelPhaseDir(dirName))
             continue;
         if (claimedDirs.has(dirName))
             continue;

package/gsd-core/bin/lib/health-diagnostic-rules/worktree-health.cjs

@@ -35,10 +35,8 @@
  * src/health-diagnostic-rules/worktree-health.cts, compiled to
  * gsd-core/bin/lib/health-diagnostic-rules/worktree-health.cjs (gitignored).
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const shellCmdProjection = require("../shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const healthDiagnosticMod = require("../health-diagnostic-types.cjs");
 const { SEVERITY, adviseRemedy } = healthDiagnosticMod;
@@ -121,15 +119,31 @@ function checkW017(snapshot) {
 // against `process.cwd()`. Per this batch's brief: the interpolated command
 // (with the real path) lives in `message`; `remedy.args.command` stays a
 // static `<path>` template, mirroring the split the brief specifies.
+// ─── #3663 — path-comparison provenance helper ─────────────────────────────
+//
+// snapshot.cwd is raw process-cwd-derived — path.resolve() normalizes
+// separators and relative segments but NOT casing, and a process launched via
+// a differently-cased path echoes that spelling back. finding.path is
+// `git worktree list`-derived, which self-normalizes to the canonical
+// on-disk casing (forward slashes). Comparing those two spellings strictly
+// misclassifies the ACTIVE worktree as stale on win32 — so the comparison
+// folds case ONLY on win32 (case-insensitive filesystem, via the Shell
+// Command Projection seam's toComparablePathKey — the platform-conditional
+// fold policy lives there, not per call site) and stays case-sensitive on
+// POSIX, where differently-cased paths are genuinely different directories.
+// No realpath resolution — that would change symlink matching behavior.
+function isActiveWorktreePath(activeCwd, worktreePath, platform = process.platform) {
+    const active = shellCmdProjection.toComparablePathKey(activeCwd, platform);
+    const worktree = shellCmdProjection.toComparablePathKey(worktreePath, platform);
+    return active === worktree || active.startsWith(worktree + '/');
+}
 function checkW027(snapshot) {
     const diagnostics = [];
     const activeCwd = snapshot.cwd;
     for (const finding of snapshot.worktreeHealth.value) {
         if (finding.kind !== 'stale')
             continue;
-        const normalizedWorktree = node_path_1.default.resolve(finding.path);
-        const isActiveWorktree = activeCwd === normalizedWorktree || activeCwd.startsWith(normalizedWorktree + node_path_1.default.sep);
-        if (isActiveWorktree)
+        if (isActiveWorktreePath(activeCwd, finding.path))
             continue;
         diagnostics.push({
             code: 'W027',
@@ -170,4 +184,4 @@ const RULES = [
         check: checkW027,
     },
 ];
-module.exports = { RULES };
+module.exports = { RULES, isActiveWorktreePath };

package/gsd-core/bin/lib/health-diagnostic.cjs

@@ -103,7 +103,7 @@ const CONSISTENCY_RULES = [
 // (`verify.cts:2405-2553`) — ported verbatim, not reinvented.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
-const { planningRoot, planningDir } = planningWorkspaceMod;
+const { planningDir } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderMod = require("./config-loader.cjs");
 const { CONFIG_DEFAULTS } = configLoaderMod;
@@ -113,6 +113,12 @@ const { getMilestoneInfo } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateMod = require("./state.cjs");
 const { writeStateMd } = stateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateTransitionMod = require("./state-transition.cjs");
+const { rebuildStateTransaction } = stateTransitionMod;
 const clock_cjs_1 = require("./clock.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
@@ -160,7 +166,13 @@ function evaluateConsistencyRules(snapshot) {
  * document for the read side.
  */
 function repairPaths(cwd) {
-    const rootBase = planningRoot(cwd);
+    // #3749: the project root is PROJECT-aware but deliberately NOT workstream-
+    // scoped — under GSD_PROJECT, config.json/MILESTONES.md/milestones belong to
+    // `.planning/<project>/` (the same base init.new-project's config_path
+    // names); under GSD_WORKSTREAM they stay at the workstream PARENT, keeping
+    // the documented root-vs-workstream split. planningDir(cwd, null) is exactly
+    // that base: project env honored, ws env suppressed.
+    const rootBase = planningDir(cwd, null);
     const wsBase = planningDir(cwd);
     return {
         rootBase,
@@ -268,7 +280,15 @@ function runRepairAction(cwd, action, paths) {
             stateContent += `**Status:** Resuming\n\n`;
             stateContent += `## Session Log\n\n`;
             stateContent += `- ${clock_cjs_1.realClock.localToday()}: STATE.md regenerated by ${slash('health')} --repair\n`;
-            writeStateMd(statePath, stateContent, cwd);
+            // ADR-3473 §8.6: `/gsd-health --repair` is a factory reset, so
+            // preservation must not run; the snapshot of the file being replaced is
+            // still captured, and `{}` is the correct, legal snapshot of a
+            // STATE.md that had no parseable frontmatter — which is the usual
+            // reason this repair fires.
+            const priorState = node_fs_1.default.existsSync(statePath) ? ((0, shell_command_projection_cjs_1.platformReadSync)(statePath) ?? '') : '';
+            writeStateMd(statePath, stateContent, rebuildStateTransaction({
+                snapshot: extractFrontmatter(priorState, statePath),
+            }), cwd);
             return { success: true, path: 'STATE.md', extraDetails };
         }
         case REMEDY_ACTION.ADD_NYQUIST_KEY:

package/gsd-core/bin/lib/host-integration.cjs

@@ -653,10 +653,25 @@ function extensionEventSurfaceFor(extensionEvents) {
  * per-host branch ADR-1239 exists to remove. Omit `prompt` entirely and the
  * resolution is byte-identical to Phase 2's (the unconsumed-resolver shape).
  *
- * Argv order is base args → cwd flag → prompt, so the prompt stays the final
- * positional token for the hosts that read it that way.
+ * Argv order is base args → model flag → cwd flag → prompt, so the prompt
+ * stays the final positional token for the hosts that read it that way. The
+ * model flag is placed BEFORE the cwd flag (not after, and not appended at
+ * the very end) purely to keep it clear of that trailing positional — the
+ * model value itself is never the prompt-adjacent token a host might scan
+ * for last.
+ *
+ * `model` (Phase 4, #3714) is optional, descriptor-gated exactly like prompt:
+ * a `modelFlag` string on the descriptor names the flag that pins the
+ * spawned executor's model (codex: `--model`); `null`/absent means the host
+ * exposes no such override on this exec path, and `[modelFlag, model]` is
+ * appended ONLY when both the descriptor's `modelFlag` and the caller's
+ * `model` are non-empty strings. Omitting `model` entirely (or passing it to
+ * a host with no `modelFlag`) is byte-identical to the resolver's behavior
+ * before this parameter existed. This function decides no policy about WHICH
+ * model to pass or what 'inherit' means — that is entirely the caller's job;
+ * this seam only shapes descriptor + values into argv.
  */
-function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
+function resolveOrchestratorExec(orchestratorExec, cwd, prompt, model) {
     if (!orchestratorExec || typeof orchestratorExec !== 'object' || Array.isArray(orchestratorExec)) {
         return { ok: false, reason: 'missing_command' };
     }
@@ -676,11 +691,22 @@ function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
     if (oe.promptFlag !== undefined && oe.promptFlag !== null && typeof oe.promptFlag !== 'string') {
         return { ok: false, reason: 'invalid_prompt_flag' };
     }
+    if (oe.modelFlag !== undefined && oe.modelFlag !== null && typeof oe.modelFlag !== 'string') {
+        return { ok: false, reason: 'invalid_model_flag' };
+    }
     // An executor spawned with no instruction is a hang, not a degraded run —
     // fail closed rather than launching a prompt-less process.
     if (prompt !== undefined && (typeof prompt !== 'string' || prompt.length === 0)) {
         return { ok: false, reason: 'invalid_prompt' };
     }
+    // Unlike `prompt` — where empty is a hang, not a degraded run, hence the
+    // fail-closed check above — an absent/null/empty model is simply "use the
+    // host default", the same benign degradation `cwdFlag: null` already
+    // expresses. Only a present-but-non-string value (number/bool/array/object)
+    // is a caller error; null/undefined/'' fall through to "omit the flag".
+    if (model !== undefined && model !== null && typeof model !== 'string') {
+        return { ok: false, reason: 'invalid_model' };
+    }
     // Leading-dash guard, mirroring worktree-safety.cts's `unsafe_leading_dash`
     // check on git arguments. A positional prompt (or a cwd) beginning with '-'
     // is parsed by the spawned CLI as a FLAG, not a value — the same failure the
@@ -695,10 +721,17 @@ function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
     if (cwd.startsWith('-')) {
         return { ok: false, reason: 'unsafe_leading_dash_cwd' };
     }
+    if (typeof model === 'string' && model.startsWith('-')) {
+        return { ok: false, reason: 'unsafe_leading_dash_model' };
+    }
     const baseArgs = Array.isArray(oe.args) ? [...oe.args] : [];
-    const args = typeof oe.cwdFlag === 'string' && oe.cwdFlag.length > 0
-        ? [...baseArgs, oe.cwdFlag, cwd]
-        : baseArgs;
+    let args = baseArgs;
+    if (typeof oe.modelFlag === 'string' && oe.modelFlag.length > 0 && typeof model === 'string' && model.length > 0) {
+        args = [...args, oe.modelFlag, model];
+    }
+    args = typeof oe.cwdFlag === 'string' && oe.cwdFlag.length > 0
+        ? [...args, oe.cwdFlag, cwd]
+        : args;
     if (typeof prompt === 'string') {
         if (typeof oe.promptFlag === 'string' && oe.promptFlag.length > 0) {
             args.push(oe.promptFlag, prompt);