@opengsd/gsd-core 1.16.0 → 1.18.0

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

@@ -32,6 +32,8 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_https_1 = __importDefault(require("node:https"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const { resolveGsdHome } = require('./runtime-homes.cjs');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellSeam = require('./shell-command-projection.cjs');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capValidator = require('./capability-validator.cjs');
@@ -984,7 +986,7 @@ async function resolveTarball(parsed, opts, gsdHome, hostVersion) {
 async function resolveCapabilitySource(spec, opts = {}) {
     const parsed = parseSpec(spec);
     const hostVersion = opts.hostVersion ?? readHostVersion();
-    const gsdHome = opts.gsdHome ?? process.env['GSD_HOME'] ?? node_os_1.default.homedir();
+    const gsdHome = opts.gsdHome || resolveGsdHome();
     switch (parsed.kind) {
         case 'local':
             return resolveLocal(parsed, opts, gsdHome, hostVersion);

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

@@ -47,6 +47,8 @@ const { loadConfig } = configLoaderMod;
 const installProfilesMod = require("./install-profiles.cjs");
 const { readActiveProfile, loadSkillsManifest, resolveProfile, parseRequires, parseCallsAgents, workflowAgentRefs } = installProfilesMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const ledgerMod = require("./capability-ledger.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const surfaceMod = require("./surface.cjs");
 const { resolveSurface } = surfaceMod;
 // ─── Prototype-pollution guard (inline literal, CodeQL barrier) ───────────────
@@ -265,16 +267,17 @@ function _loadInstalledSkillsManifest(configDir) {
         // SKILL.md must NOT register the stem — otherwise the capability would be
         // wrongly reported surfaced/enabled and a verify:post hook would render
         // for a skill that cannot run.
-        if (!node_fs_1.default.existsSync(skillMdPath))
-            continue;
+        // #5121: bounded read — a missing, non-regular (FIFO/device) or oversized SKILL.md registers no stem.
         let content = '';
         try {
-            content = node_fs_1.default.readFileSync(skillMdPath, 'utf8');
+            content = ledgerMod.readSkillFile(skillMdPath);
         }
         catch {
             // SKILL.md present but unreadable — register with no deps (parity with
             // loadSkillsManifest's readFileSync catch branch).
         }
+        if (content === null)
+            continue;
         // Parse requires: via the SAME shared parser loadSkillsManifest uses, so
         // installed-runtime dependency resolution can never silently diverge from
         // the source-tree path (single source of truth — no duplicated regex).

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

@@ -1899,6 +1899,10 @@ const REVIEWER_EFFORT_LEVELS = new Set(['minimal', 'low', 'medium', 'high', 'xhi
  * silently rot away from reality (DEFECT.GENERATIVE-FIX).
  */
 const KNOWN_HOST_BEHAVIORS = new Set([
+  // #2586: declares runtime-level feature axes GSD does not/cannot support on
+  // omitting the key on every other runtime carries no inverted meaning.
+  // this host (e.g. Codex's `["context-warnings","phase-lifecycle-display"]`)
+  // — present-and-populated / absent-is-unsupported-empty convention, so
   'agentFileExtension',
   'agentFrontmatterExtensions',
   'agentManifestStyle',
@@ -1916,6 +1920,7 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'combinedFamilyInstall',
   'commandBodyConverter',
   'contentRewriteProfile',
+  'defaultHomeIncludeRoot',
   'doneBannerStyle',
   'flatCommandDir',
   'frontmatterDialect',
@@ -1936,6 +1941,7 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'managedHookEvents',
   'mcpCompanion',
   'namedSubagentsSupported',
+  'nativeCliPlugin',
   'nativeModelAliases',
   'nativePlugin',
   'noPathRewrite',
@@ -1952,6 +1958,7 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'requiresSubagentPair',
   'restoreAtRefTildeInAgents',
   'restoreAtRefTildeInSpecTree',
+  'retargetsGsdCoreProsePath',
   'retiredArtifacts',
   'rewriteClaudeAtIncludes',
   'settingsFileByScope',
@@ -1971,10 +1978,6 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'specRootSkillPass',
   'tomlConfigInstall',
   'trackCategoryDescription',
-  // #2586: declares runtime-level feature axes GSD does not/cannot support on
-  // this host (e.g. Codex's `["context-warnings","phase-lifecycle-display"]`)
-  // — present-and-populated / absent-is-unsupported-empty convention, so
-  // omitting the key on every other runtime carries no inverted meaning.
   'unsupportedFeatures',
   'verificationStyle',
   'writeCategoryDescription',
@@ -2572,7 +2575,7 @@ function validateLaneProbe(ctx, probe) {
     if (!isPositiveIntegerMs(probe.timeoutMs)) {
       errors.push(
         ctx + ' reviewer.probe.timeoutMs must be a positive integer of milliseconds for kind "' +
-        probe.kind + '" — an unbounded probe hangs every /gsd:review invocation ' +
+        probe.kind + '" — an unbounded probe hangs every /gsd-review invocation ' +
         '(got: ' + describeValue(probe.timeoutMs) + ')',
       );
     }

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

@@ -50,6 +50,7 @@ const { planningDir } = planningWorkspaceMod;
 const nodefs = require("fs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const nodepath = require("path");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // ─── Implementation ───────────────────────────────────────────────────────────
 /**
  * Write-side capability state mutator.
@@ -305,7 +306,7 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
         if (entry.enabled === true) {
             const afterCap = after.capabilities.find((c) => c.id === entry.id);
             if (afterCap && afterCap.enabled !== true) {
-                errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use /gsd:surface enable)`);
+                errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'surface enable')})`);
             }
         }
         // Fix B: desired enabled=false — assert it is actually disabled after write.

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

@@ -1233,6 +1233,24 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // null — it would leave an unresolvable `variant: null` key on disk
         // forever. Test presence with its own regex, and only compare values
         // once presence is known.
+        // Native OpenCode 2.x form (ADR-5331 D5): the effort rides on the model reference as
+        // `provider/model#variant`, with no separate `variant:` key. When the agent's `model:` carries a
+        // `#` suffix that suffix IS the effort, so the sync edits the model instead of adding a second,
+        // conflicting `variant:` line.
+        const modelLineMatch = /^model:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
+        const modelValue = modelLineMatch ? modelLineMatch[1].replace(/\r$/, '').replace(/^(["'])(.*)\1$/, '$2') : null;
+        const hashAt = modelValue === null ? -1 : modelValue.lastIndexOf('#');
+        let modelFormContent = null;
+        let modelFormFrom = null;
+        if (modelValue !== null && hashAt > 0) {
+            const base = modelValue.slice(0, hashAt);
+            modelFormFrom = modelValue.slice(hashAt + 1);
+            if (target !== null && modelFormFrom === target) {
+                skipped++;
+                continue;
+            }
+            modelFormContent = setFrontmatterKeyLine(content, 'model', target === null ? base : `${base}#${target}`);
+        }
         const variantPresent = /^variant:/m.test(fmMatch.body);
         const variantMatch = /^variant:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
         // `null` (key absent) and `''` (key present, value empty) are distinct
@@ -1241,17 +1259,19 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // "empty key" indistinguishable in the sync output, even though only one
         // of them actually has a `variant:` line to remove.
         const currentVariant = variantPresent ? (variantMatch ? variantMatch[1] : '') : null;
-        if (target === null) {
-            if (!variantPresent) {
+        if (modelFormContent === null) {
+            if (target === null) {
+                if (!variantPresent) {
+                    skipped++;
+                    continue;
+                }
+            }
+            else if (variantPresent && currentVariant === target) {
                 skipped++;
                 continue;
             }
         }
-        else if (variantPresent && currentVariant === target) {
-            skipped++;
-            continue;
-        }
-        changes.push({ agent: agentName, from: currentVariant, to: target });
+        changes.push({ agent: agentName, from: modelFormContent === null ? currentVariant : modelFormFrom, to: target });
         synced++;
         if (!dryRun) {
             // Atomic publish AND mode preservation, same discipline as
@@ -1279,7 +1299,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
             }
             catch { /* non-fatal: fall back to writing without an explicit mode */ }
             try {
-                node_fs_1.default.writeFileSync(tmpPath, target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target), originalMode !== undefined ? { mode: originalMode } : undefined);
+                node_fs_1.default.writeFileSync(tmpPath, modelFormContent ?? (target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target)), originalMode !== undefined ? { mode: originalMode } : undefined);
                 // Not redundant with the `mode` option above: `mode` only applies
                 // when the file is actually created (O_CREAT). A leftover tmp file
                 // from an earlier crashed run would be reused (truncated) at its OLD
@@ -2966,6 +2986,8 @@ async function cmdWebsearch(query, options, raw) {
                         'Accept': 'application/json',
                         'X-Subscription-Token': apiKey
                     },
+                    // never follow redirects: X-Subscription-Token must not leave api.search.brave.com (#5409)
+                    redirect: 'manual',
                     signal: ac.signal
                 });
             }
@@ -2991,7 +3013,9 @@ async function cmdWebsearch(query, options, raw) {
             const status = response.status;
             const isRetryable = status === 429 || status >= 500;
             if (!isRetryable) {
-                // Non-retryable 4xx — fail immediately, no attempts field
+                // Non-retryable 4xx and every 3xx (redirect: 'manual' hands them back as-is, #5409) —
+                // fail immediately, no attempts field. Keep 3xx out of isRetryable.
+                response.body?.cancel().catch(() => { });
                 output({ available: false, error: `API error: ${status}` }, raw, '');
                 return;
             }

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

@@ -25,11 +25,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // #4717: runtime-identity fill — env rung + per-install marker rung.
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -935,7 +935,7 @@ function loadConfigResolvedInternal(cwd, options = {}) {
         // untouched. Faults in the global file stay silent in this branch (the
         // project config governs; the nearer file is the actionable one).
         try {
-            const shadowHome = process.env['GSD_HOME'] || node_os_1.default.homedir();
+            const shadowHome = (0, runtime_homes_cjs_1.resolveGsdHome)();
             const shadowPath = node_path_1.default.join(shadowHome, '.gsd', 'defaults.json');
             const shadowRead = _readConfigFile(shadowPath);
             if (shadowRead.kind === 'ok') {
@@ -997,7 +997,7 @@ function loadConfigResolvedInternal(cwd, options = {}) {
         }
         // Branch D or E: no .planning/
         try {
-            const home = process.env['GSD_HOME'] || node_os_1.default.homedir();
+            const home = (0, runtime_homes_cjs_1.resolveGsdHome)();
             const globalDefaultsPath = node_path_1.default.join(home, '.gsd', 'defaults.json');
             const globalRead = _readConfigFile(globalDefaultsPath);
             if (globalRead.kind === 'fault') {

package/gsd-core/bin/lib/decision-coverage-support.cjs

@@ -21,6 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decisionMentioned = decisionMentioned;
+exports.phaseDirProblem = phaseDirProblem;
 exports.loadPlanContents = loadPlanContents;
 exports.loadSummaryContents = loadSummaryContents;
 exports.loadDecisionExtraction = loadDecisionExtraction;
@@ -70,6 +71,24 @@ function decisionMentioned(haystack, decision) {
     return phrase ? normalizePhrase(haystack).includes(phrase) : false;
 }
 // ─── File reading ─────────────────────────────────────────────────────────────
+// #4939: loadPlanContents answers no files for a path that is not there, and that reads
+// as "no plan cites anything" — so a phase-dir argument that names no directory
+// (the phase NUMBER in the phase-dir slot) must be told apart BEFORE the scan.
+// Answers null for a directory, else what is wrong with the path and what to do
+// about it. Like the plan gate's contextKind (#4794), the message names the real
+// stat outcome: a permission or I/O failure (EACCES, ELOOP, EIO) is reported as
+// unreadable, not as a missing directory. Only ENOENT/ENOTDIR mean the path is not there.
+function phaseDirProblem(dirPath) {
+    const passDirectory = 'Pass the phase DIRECTORY (e.g. .planning/phases/01-slug), not the phase number.';
+    const st = (0, gate_evidence_cjs_1.statEvidence)(dirPath);
+    if (st.kind === 'none')
+        return { reason: 'phase directory not found', what: 'does not exist', hint: passDirectory, unreadable: false };
+    if (st.kind === 'unreadable')
+        return { reason: 'phase directory unreadable', what: `could not be read (${st.reason})`, hint: 'Check that the directory is readable.', unreadable: true };
+    if (st.value.isDirectory())
+        return null;
+    return { reason: 'phase path is not a directory', what: st.value.isFile() ? 'is a file, not a directory' : 'is not a directory', hint: passDirectory, unreadable: false };
+}
 /**
  * The contents of the phase files `pick` selects (#5170, ADR-5057 §4). An ABSENT phase directory
  * is "no files" (`found []`); a directory or file that exists but cannot be read is `unreadable` —

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

@@ -28,6 +28,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 const gate_config_cjs_1 = require("./gate-config.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -45,13 +46,13 @@ const { defaultPhaseCleanCommitTimesMs } = verificationMod;
 function computeContextDrift(contextEffectiveMs, entries) {
     return entries.filter((e) => e.effectiveMs < contextEffectiveMs).map((e) => e.file);
 }
-function buildContextDriftMessage(staleArtifacts, phaseArg) {
+function buildContextDriftMessage(staleArtifacts, phaseArg, projectDir) {
     const parts = [`CONTEXT.md decisions are newer than: ${staleArtifacts.join(', ')}.`];
     if (staleArtifacts.some((f) => f.endsWith('-RESEARCH.md'))) {
-        parts.push(`Regenerate research: /gsd:plan-phase ${phaseArg} --research.`);
+        parts.push(`Regenerate research: ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, `plan-phase ${phaseArg} --research`)}.`);
     }
     if (staleArtifacts.some((f) => f.endsWith('-PATTERNS.md'))) {
-        parts.push('Regenerate patterns: delete the PATTERNS.md file, then re-run /gsd:plan-phase.');
+        parts.push(`Regenerate patterns: delete the PATTERNS.md file, then re-run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, 'plan-phase')}.`);
     }
     if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || (f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md')))) {
         parts.push('Regenerate or manually reconcile VALIDATION.md / SPEC.md against the current decisions.');
@@ -114,7 +115,7 @@ function runContextDriftGate(cwd, phaseArg) {
     // missing or malformed config is "key absent", nothing is printed).
     const action = (0, gate_config_cjs_1.readWorkflowConfigValue)(cwd, 'workflow.context_drift_action').value === 'block' ? 'block' : 'warn';
     const block = staleArtifacts.length > 0 && action === 'block';
-    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg) : '';
+    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg, cwd) : '';
     return (0, gate_verdict_cjs_1.gateVerdict)(block ? 'block' : (staleArtifacts.length > 0 ? 'advisory' : 'pass'), block, {
         block,
         skipped: false,

package/gsd-core/bin/lib/gate-decision-coverage-plan.cjs

@@ -145,9 +145,24 @@ function evaluateDecisionCoveragePlan(input) {
     if (decisions.length === 0) {
         return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { passed: true, skipped: true, reason: 'no trackable decisions', total: 0, covered: 0, uncovered: [], message: 'No trackable decisions in CONTEXT.md.' });
     }
+    // #4939: a phase-dir argument that was GIVEN but is not a directory is a caller
+    // error like #2770's empty context argument and #4794's non-file context path:
+    // no plan was scanned, so nothing was measured. Fail closed with total/covered
+    // null and `uncovered` omitted. An OMITTED phase dir is left to the scan below —
+    // the #4130 `--context <path>` alone tests pin that as a coverage gap.
+    const phaseDirIssue = phaseDir ? (0, decision_coverage_support_cjs_1.phaseDirProblem)(phaseDir) : null;
+    if (phaseDirIssue) {
+        const phaseDirResult = { passed: false, skipped: false, reason: phaseDirIssue.reason, total: null, covered: null, message: `Decision coverage gate: the phase directory "${positionals[0]}" ${phaseDirIssue.what}, so no plans were scanned. ${phaseDirIssue.hint}` };
+        return phaseDirIssue.unreadable ? (0, gate_verdict_cjs_1.gateUnreadable)(true, phaseDirResult) : (0, gate_verdict_cjs_1.gateVerdict)('block', true, phaseDirResult);
+    }
     const planContents = (0, decision_coverage_support_cjs_1.loadPlanContents)(phaseDir);
     if (planContents.kind === 'unreadable')
         return unreadableDecisionGate(`${planContents.span ?? phaseDir}: ${planContents.reason}`);
+    // #4939: a phase directory that holds no PLAN file is the same caller error: zero plans
+    // loaded is not zero coverage.
+    if (phaseDir && planContents.value.length === 0) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, { passed: false, skipped: false, reason: 'phase directory holds no plans', total: null, covered: null, message: `Decision coverage gate: the phase directory "${positionals[0]}" holds no PLAN files, so no plans were scanned. Pass the phase DIRECTORY that holds the plans (e.g. .planning/phases/01-slug), not the phase number.` });
+    }
     const sections = planContents.value.map(decision_coverage_support_cjs_1.extractPlanDesignatedSections);
     const uncovered = [];
     let covered = 0;

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

@@ -90,6 +90,14 @@ function evaluateDecisionCoverageVerify(input) {
     if (decisions.length === 0) {
         return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { skipped: true, blocking: false, reason: 'no trackable decisions', total: 0, honored: 0, not_honored: [], message: 'No trackable decisions in CONTEXT.md.' });
     }
+    // #4939: mirror the plan gate. A phase-dir argument that names no directory
+    // means no plan or summary was scanned, so no decision can be reported
+    // not-honored. Warn (verify stays non-blocking) rather than list every decision.
+    const phaseDirIssue = phaseDir ? (0, decision_coverage_support_cjs_1.phaseDirProblem)(phaseDir) : null;
+    if (phaseDirIssue) {
+        const phaseDirResult = { skipped: false, blocking: false, reason: phaseDirIssue.reason, total: null, honored: null, not_honored: [], message: `Decision coverage verify (warning): the phase directory "${args[0]}" ${phaseDirIssue.what}, so no plans or summaries were scanned. ${phaseDirIssue.hint}` };
+        return phaseDirIssue.unreadable ? (0, gate_verdict_cjs_1.gateUnreadable)(false, phaseDirResult) : (0, gate_verdict_cjs_1.gateVerdict)('advisory', false, phaseDirResult);
+    }
     // Every file the haystack is built from is typed evidence (#5170): one that exists but cannot be
     // read is `unreadable`, never an empty slice of the haystack that makes a decision look unhonored.
     const planContents = (0, decision_coverage_support_cjs_1.loadPlanContents)(phaseDir);
@@ -98,6 +106,11 @@ function evaluateDecisionCoverageVerify(input) {
     const summaryParts = (0, decision_coverage_support_cjs_1.loadSummaryContents)(phaseDir);
     if (summaryParts.kind === 'unreadable')
         return unreadableVerify(`${summaryParts.span ?? phaseDir}: ${summaryParts.reason}`);
+    // #4939: mirror the plan gate. A phase directory with no PLAN and no SUMMARY file gave the
+    // verifier nothing to read, which is a caller error, not a phase whose decisions were all missed.
+    if (phaseDir && planContents.value.length === 0 && summaryParts.value.length === 0) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('advisory', false, { skipped: false, blocking: false, reason: 'phase directory holds no plans', total: null, honored: null, not_honored: [], message: `Decision coverage verify (warning): the phase directory "${args[0]}" holds no PLAN or SUMMARY files, so nothing was scanned. Pass the phase DIRECTORY that holds the plans (e.g. .planning/phases/01-slug), not the phase number.` });
+    }
     const modifiedFiles = (0, decision_coverage_support_cjs_1.readModifiedFilesContent)(projectDir, summaryParts.value);
     if (modifiedFiles.kind === 'unreadable')
         return unreadableVerify(`${modifiedFiles.span ?? 'files_modified'}: ${modifiedFiles.reason}`);

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -26,6 +26,10 @@
  * This is a leaf pure module: no fs, no child_process, no config — the subprocess
  * seam is injected so the evaluator is trivially testable without spawning.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
 // ─── Public constants ─────────────────────────────────────────────────────────
 /** Default command timeout for `command-exit-zero` (30s). Matches execTool default. */
 const COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS = 30_000;
@@ -116,15 +120,31 @@ function evaluateArtifactFrontmatterEquals(predicate, ctx, deps) {
         throw new Error('artifact-frontmatter-equals predicate requires an "equals" key');
     }
     const targetDir = isNonEmptyString(ctx.phaseDir) ? ctx.phaseDir : ctx.cwd;
-    const filePath = deps.findPhaseArtifact(targetDir, artifactSuffix);
-    if (!filePath) {
+    // Plain `.sort()` (no locale) so the outcome never depends on directory listing order (#5313).
+    // Set: finders return realpaths, so a symlink to the same file is one artifact, not two.
+    const found = deps.findPhaseArtifact(targetDir, artifactSuffix);
+    // A pre-#5313 dep returned `string | null`; a silent null -> "not found" block or per-character spread would mislead.
+    if (!Array.isArray(found)) {
+        throw new Error('predicate deps "findPhaseArtifact" must return an array of paths');
+    }
+    const candidates = [...new Set(found)].sort();
+    if (candidates.length === 0) {
         return {
             block: true,
             message: `Artifact matching ${artifactSuffix} not found in ${targetDir}`,
             details: { kind: 'artifact-frontmatter-equals', artifactNotFound: true },
         };
     }
-    const fm = deps.readFrontmatter(filePath);
+    // #5313: never pick one of several matches (listing order is OS-dependent); a throw would fail open via onError.
+    if (candidates.length > 1) {
+        const names = candidates.map((c) => node_path_1.default.relative(targetDir, c).split(node_path_1.default.sep).join('/')).join(', ');
+        return {
+            block: true,
+            message: `Multiple artifacts match ${artifactSuffix} in ${targetDir}: ${names}; remove or rename all but one`,
+            details: { kind: 'artifact-frontmatter-equals', ambiguous: true, candidates },
+        };
+    }
+    const fm = deps.readFrontmatter(candidates[0]);
     const actualValue = fm[field];
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     const expectedStr = typeof expectedValue === 'object' ? JSON.stringify(expectedValue) : String(expectedValue);

package/gsd-core/bin/lib/gate-predicate.cjs

@@ -80,31 +80,27 @@ function buildPredicateDeps() {
             if (phaseDirStat.kind === 'unreadable')
                 return unreadable(phaseDir, phaseDirStat.reason);
             if (phaseDirStat.kind === 'none')
-                return null;
+                return [];
             if (artifactSuffix === '.' ||
                 artifactSuffix === '..' ||
                 artifactSuffix.includes('\0') ||
                 node_path_1.default.basename(artifactSuffix) !== artifactSuffix ||
                 node_path_1.default.win32.basename(artifactSuffix) !== artifactSuffix) {
-                return null;
-            }
-            const directContained = (0, security_cjs_1.tryWithinRoot)(artifactSuffix, phaseDir);
-            if (directContained !== null) {
-                const direct = regularFileOrNull(directContained);
-                if (direct !== null)
-                    return direct;
+                return [];
             }
+            // #5313: collect EVERY distinct match; the evaluator fails closed on >1 instead of trusting listing order.
+            const found = [];
             const planningContained = (0, security_cjs_1.tryWithinRoot)(node_path_1.default.join('.planning', artifactSuffix), phaseDir);
             if (planningContained !== null) {
                 const planning = regularFileOrNull(planningContained);
                 if (planning !== null)
-                    return planning;
+                    found.push(planning);
             }
             const listing = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
             if (listing.kind === 'unreadable')
                 return unreadable(phaseDir, listing.reason);
             if (listing.kind === 'none')
-                return null;
+                return [];
             for (const f of listing.value) {
                 if (f.endsWith('-' + artifactSuffix) || f === artifactSuffix) {
                     const candidateContained = (0, security_cjs_1.tryWithinRoot)(f, phaseDir);
@@ -112,10 +108,10 @@ function buildPredicateDeps() {
                         continue;
                     const candidate = regularFileOrNull(candidateContained);
                     if (candidate !== null)
-                        return candidate;
+                        found.push(candidate);
                 }
             }
-            return null;
+            return found;
         },
         readFrontmatter(filePath) {
             const content = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);

package/gsd-core/bin/lib/gate-tdd-review-checkpoint.cjs

@@ -17,6 +17,12 @@
  * tolerant. A plan id that is not `<phase>-<plan>` (a plan named `.*-PLAN.md`) matches nothing,
  * and a git failure is "no commits" exactly as before.
  *
+ * Cross-plan GREEN (#4867): a gap closure is planned as a RED-only probe plan plus the plan that
+ * `depends_on` it and carries the fix. A `type: tdd` plan with its own RED but no GREEN is credited
+ * with a `feat(...)` commit under any plan that lists it in `depends_on`, directly or through a
+ * chain; the row carries `greenFrom` and the report names the supplier. Its own RED is still
+ * required, and a plan nothing depends on is scored on its own commits alone.
+ *
  * Argv after the verb: `<phase>` (a number; an unresolvable phase reports zero plans).
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -31,7 +37,7 @@ const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterMod = require("./frontmatter.cjs");
-const { frontmatterKeyHasValue } = frontmatterMod;
+const { frontmatterKeyHasValue, extractFrontmatter } = frontmatterMod;
 /**
  * True when the plan's frontmatter declares `type: tdd` (CRLF included, #2449). The block is the
  * one fence owner's, read as RAW text — not through the YAML parser — so a block the parser refuses
@@ -42,6 +48,35 @@ const { frontmatterKeyHasValue } = frontmatterMod;
 function isTddPlan(content) {
     return frontmatterKeyHasValue(content, 'type', 'tdd');
 }
+/** A `depends_on` token as a plan id: `01.1-20`, `01.1-20-PLAN` and `01.1-20-PLAN.md` all name plan `01.1-20`. */
+function toPlanId(token) {
+    return token.trim().replace(/-PLAN(?:\.md)?$/i, '');
+}
+/**
+ * The plan ids a plan lists in `depends_on` (#4867). A plan whose frontmatter does not parse, or has
+ * no `depends_on`, depends on nothing: the pairing below only ever ADDS credit, so an unreadable
+ * link can never turn a failing plan into a passing one.
+ */
+function dependsOnOf(content) {
+    // `extractFrontmatter` does not throw: an unparseable block is an empty result, so `depends_on` is absent.
+    const value = extractFrontmatter(content)['depends_on'];
+    const tokens = Array.isArray(value) ? value.map(String) : typeof value === 'string' ? value.split(',') : [];
+    return tokens.map(toPlanId).filter((id) => id !== '');
+}
+/** Every plan that depends on `planId`, directly or through a chain (#4867); a cycle is walked once. */
+function transitiveDependents(planId, dependents) {
+    const seen = new Set();
+    const queue = [planId];
+    while (queue.length > 0) {
+        for (const next of dependents.get(queue.shift()) ?? []) {
+            if (next !== planId && !seen.has(next)) {
+                seen.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return [...seen].sort();
+}
 /**
  * The commit types (`test`, `feat`, `refactor`, …) among the plan's own commits — those that
  * touched at least one path (`pathspecs: ['.']`, as the old `git log -- .` lookup did). An
@@ -91,6 +126,9 @@ function evaluateTddReviewCheckpoint(input) {
     const phaseDir = located.kind === 'found' ? located.value : '';
     // Find all PLAN.md files with type: tdd in frontmatter
     const tddPlanFiles = [];
+    // #4867: plan id -> the plans that list it in `depends_on`, over EVERY plan of the phase (a
+    // dependent GREEN plan is usually `type: execute`, not `tdd`).
+    const dependents = new Map();
     const unreadable = [];
     if (phaseDir) {
         const entries = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
@@ -110,8 +148,13 @@ function evaluateTddReviewCheckpoint(input) {
                     const plan = (0, gate_evidence_cjs_1.readTextEvidence)(planPath);
                     if (plan.kind === 'unreadable')
                         unreadable.push({ source: planPath, reason: plan.reason });
-                    else if (plan.kind === 'found' && isTddPlan(plan.value))
-                        tddPlanFiles.push(planPath);
+                    else if (plan.kind === 'found') {
+                        if (isTddPlan(plan.value))
+                            tddPlanFiles.push(planPath);
+                        const planId = node_path_1.default.basename(planPath, '-PLAN.md');
+                        for (const dep of dependsOnOf(plan.value))
+                            dependents.set(dep, [...(dependents.get(dep) ?? []), planId]);
+                    }
                 }
             }
         }
@@ -136,15 +179,24 @@ function evaluateTddReviewCheckpoint(input) {
         const planId = node_path_1.default.basename(planPath, '-PLAN.md');
         const kinds = planCommitKinds(projectDir, planId);
         const red = kinds.has('test');
-        const green = kinds.has('feat');
         const refactor = kinds.has('refactor');
+        // #4867: a RED-only probe plan is satisfied by the GREEN of a plan that (transitively) declares
+        // `depends_on` it. Only a real `feat(...)` commit under such a plan counts; the plan's own RED is
+        // still required, and a plan nothing depends on is scored on its own commits alone.
+        const ownGreen = kinds.has('feat');
+        const greenFrom = ownGreen
+            ? []
+            : transitiveDependents(planId, dependents).filter((dependentId) => planCommitKinds(projectDir, dependentId).has('feat'));
+        const green = ownGreen || greenFrom.length > 0;
         const missing = [];
         if (!red)
             missing.push('RED');
         if (!green)
             missing.push('GREEN');
         const status = missing.length === 0 ? 'Pass' : 'FAIL';
-        rows.push({ planId, red, green, refactor, status, missing });
+        rows.push(greenFrom.length > 0
+            ? { planId, red, green, refactor, status, missing, greenFrom }
+            : { planId, red, green, refactor, status, missing });
     }
     const violations = rows.filter(r => r.status === 'FAIL').length;
     // Build review table
@@ -160,6 +212,9 @@ function evaluateTddReviewCheckpoint(input) {
         tableDivider,
         ...tableRows,
     ].join('\n');
+    for (const r of rows.filter(row => row.greenFrom)) {
+        table += `\n\nPlan ${r.planId} GREEN is supplied by dependent plan ${(r.greenFrom ?? []).join(', ')}.`;
+    }
     if (violations > 0) {
         table += '\n\n⚠ Gate violations are advisory — review before advancing.';
         for (const r of rows.filter(row => row.status === 'FAIL')) {

package/gsd-core/bin/lib/gate-ui-safety.cjs

@@ -19,6 +19,7 @@ exports.evaluateUiSafetyGate = evaluateUiSafetyGate;
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
 const UI_FILE_EXTENSIONS_RE = /\.(tsx|jsx|css|scss|sass|less|vue|svelte|html)$/i;
 const UI_PATH_PATTERNS_RE = /\/(components|pages|views|screens|layouts|ui|frontend)\//i;
@@ -52,7 +53,7 @@ function computeUiSafetyGate(projectDir, phase) {
     const result = { frontend, hasUiFiles, hasUiSpec, block };
     if (block) {
         result.message = `UI files changed in this wave but no UI-SPEC.md exists for Phase ${phase}. ` +
-            `Run /gsd:ui-phase ${phase} to generate the design contract before continuing.`;
+            `Run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, `ui-phase ${phase}`)} to generate the design contract before continuing.`;
     }
     if (phaseLookupFailed)
         result.phaseLookupFailed = true;

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

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 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 runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
@@ -408,7 +409,7 @@ function graphifyQuery(cwd, term, options = {}) {
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
         return { error: configured
-                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'graphify build')}.`
                 : 'No graph built yet. Run graphify build first.' };
     }
     const graph = safeReadJson(graphPath);
@@ -446,7 +447,7 @@ function graphifyStatus(cwd) {
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
         return { exists: false, graph_path: graphPath, message: configured
-                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'graphify build')}.`
                 : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);