@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -677,8 +677,25 @@ function stageValidated(opts) {
             throw new Error(`Hook fragment validation failed: ${fragErrs.join('; ')}`);
         }
         // Cross-capability validations (contract, consumes, cross-capability).
-        const capMap = new Map([[id, cap]]);
-        const centralKeys = new Set();
+        //
+        // #3929: seed the validation set the way the loader builds its accepted
+        // map — frozen first-party registry, then each committed overlay of the
+        // TARGET (global) install scope accepted incrementally (structural +
+        // engines + full-suite-clean), then the candidate LAST (mirroring
+        // `acceptedMap.set(id, cap)`). The singleton seed
+        // `new Map([[id, cap]])` this replaced made every non-empty `requires`
+        // unsatisfiable (membership is checked against the map) and left cycles,
+        // tier-monotone and central config-key exclusivity vacuous at install.
+        // The seed builder lives in capability-loader so the overlay semantics
+        // have one owner and are clean by construction — pre-existing junk in the
+        // install scope is skipped, never attributed to the candidate. No swallow:
+        // if the loader cannot build the seed the install fails loudly — silently
+        // degrading to the singleton map would re-hide #3929.
+        /* eslint-disable @typescript-eslint/no-require-imports */
+        const seedLoader = require('./capability-loader.cjs');
+        /* eslint-enable @typescript-eslint/no-require-imports */
+        const { capMap, centralKeys } = seedLoader.crossValidationSeed(process.cwd(), gsdHome, hostVersion, capValidator, semverMod);
+        capMap.set(id, cap);
         const crossErrs = [
             ...capValidator.validateAgainstContract(cap, id),
             ...capValidator.validateConsumesGlobal(capMap),

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

@@ -1956,6 +1956,11 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'sourceMarkerFile',
   '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',
 ]);
@@ -2796,7 +2801,7 @@ function materializeHookFragments(cap, capDir) {
 
       const abs = path.resolve(capDir, fragment.path);
       const capRoot = path.resolve(capDir);
-      if (abs !== capRoot && !abs.startsWith(capRoot + path.sep)) {
+      if (abs !== capRoot && !abs.startsWith(capRoot + path.sep)) { // allow-handrolled-containment: committed pre-build .cjs; compiled security.cjs is untracked build output
         errors.push(
           cap.id + '/' + groupName + '[' + i + '].fragment.path escapes capability directory: ' +
           fragment.path,
@@ -2948,6 +2953,14 @@ function validateStep(step, prefix, declaredSkills, declaredAgents) {
     errors.push(prefix + '.pointFrom must be a string if present');
   }
 
+  // #4209 DISP-02: strict optional boolean opt-in trait. Absent or false is
+  // inert; only a literal `true` reaches the projected active hook. Reject
+  // every other type (including truthy non-boolean values) so a typo can
+  // never silently opt a step into reviewer-lane dispatch.
+  if (step.supportsReviewerLanes !== undefined && typeof step.supportsReviewerLanes !== 'boolean') {
+    errors.push(prefix + '.supportsReviewerLanes must be a boolean if present');
+  }
+
   if (step.fragment !== undefined) {
     errors.push(...validateFragment(step.fragment, prefix + '.fragment'));
   }

package/gsd-core/bin/lib/check-command-router.cjs

@@ -14,7 +14,13 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
-const { output, error, ERROR_REASON } = io;
+const { output, ERROR_REASON } = io;
+// Explicitly annotated so TypeScript applies never-return control-flow narrowing.
+// A destructured `const { error } = io` is a const WITHOUT a type annotation, and TS
+// only narrows after a never-returning call when the callee is a function declaration
+// or an annotated const. Without the annotation every `error(...)` guard below would
+// need a dead `throw` after it to convince the checker that the value is non-null.
+const error = io.error;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
@@ -89,7 +95,12 @@ function readIfExists(filePath) {
     }
 }
 function resolvePath(inputPath, projectDir) {
-    return node_path_1.default.isAbsolute(inputPath) ? inputPath : node_path_1.default.join(projectDir, inputPath);
+    const candidate = node_path_1.default.isAbsolute(inputPath) ? inputPath : node_path_1.default.join(projectDir, inputPath);
+    const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+    if (contained === null) {
+        error(`path escapes its allowed directory: ${inputPath}`, ERROR_REASON.USAGE);
+    }
+    return contained;
 }
 function readWorkflowConfig(projectDir) {
     const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
@@ -272,9 +283,34 @@ function loadDecisionExtraction(contextPath) {
         outcome: extraction.outcome,
     };
 }
+/**
+ * `check decision-coverage-plan` — blocking plan-phase decision-coverage gate
+ * (#2492, #1365 fail-loud, #2770 empty-arg fail-closed).
+ *
+ * Invocation (the context path may be supplied EITHER way; #4130 follow-up):
+ *   gsd_run check decision-coverage-plan <phase-dir> <context-path>   (positional, the workflow caller's form)
+ *   gsd_run check decision-coverage-plan --context <path> [<phase-dir>]
+ *
+ * `--context <path>` follows the sibling flag convention (`check predicate`,
+ * #2008): `--flag value` pairs parsed by the shared partitionPredicateArgs
+ * pass, the flag WINNING over a same-purpose positional when both appear,
+ * and a valueless `--context` counting as no context at all (it falls
+ * through to the #2770 caller-error branch, not to the "CONTEXT.md missing"
+ * green skip). The positional form keeps working unchanged — no sibling
+ * check verb deprecates positionals and the plan-phase workflow passes them.
+ */
 function cmdDecisionCoveragePlan(projectDir, args, raw) {
-    const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
-    const contextArg = args[3];
+    // args[0]='check', args[1]=subcommand — partition the REST so flag tokens
+    // and their values never land in a positional slot.
+    const { flags, positionals } = partitionPredicateArgs(args.slice(2));
+    const phaseDir = positionals[0] ? resolvePath(positionals[0], projectDir) : '';
+    // A VALUELESS `--context` stays a bare token in the positionals (sibling
+    // parser semantics); it must not then be read as the context PATH — a
+    // `--`-prefixed "path" is a caller mistake, and #2770's law says a missing
+    // context argument fails CLOSED, never a silent "CONTEXT.md missing" green
+    // skip. So only a non-flag positional may serve as the context.
+    const positionalContext = positionals[1] && !positionals[1].startsWith('--') ? positionals[1] : '';
+    const contextArg = flags['context'] ?? positionalContext ?? '';
     const contextPath = contextArg ? resolvePath(contextArg, projectDir) : '';
     if (!gateEnabled(projectDir)) {
         output({ passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
@@ -309,12 +345,15 @@ function cmdDecisionCoveragePlan(projectDir, args, raw) {
             uncovered: [],
             message: partialParse
                 ? 'Decision coverage gate: decisions could not be fully parsed — one or more ' +
-                    '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator). ' +
-                    'Fix the bullet format so all D-NN decisions can be read before re-running the gate.'
+                    '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
+                    'prefix that is not a digit run, e.g. `D4x-01`). Fix the bullet format so all decisions ' +
+                    'can be read before re-running the gate.'
                 : 'Decision coverage gate: could not parse decisions — possible format mismatch. ' +
                     'The CONTEXT.md appears to be decision-shaped (has a <decisions> block, a decisions heading, ' +
-                    'or D- tokens) but no D-NN bullets could be extracted. Check the formatting of the decisions ' +
-                    'block and ensure bullets follow the `- **D-NN:** text` or `- **D-NN — title** body` form.',
+                    'or D- tokens) but no decision bullets could be extracted. Check the formatting of the decisions ' +
+                    'block and ensure bullets follow the `- **D-NN:** text`, `- **D4-NN:** text` (phase-prefixed), ' +
+                    'or `- **D-NN — title** body` form. An ID grammar the parser does not support (e.g. `DEC-01`) ' +
+                    'also lands here.',
         }, raw, undefined);
         return;
     }
@@ -354,11 +393,6 @@ function recentCommitMessages(projectDir) {
         return '';
     }
 }
-function isInsideRoot(candidatePath, rootDir) {
-    const root = node_path_1.default.resolve(rootDir);
-    const target = node_path_1.default.resolve(root, candidatePath);
-    return target === root || target.startsWith(`${root}${node_path_1.default.sep}`);
-}
 function readModifiedFilesContent(projectDir, summaries) {
     const out = [];
     let total = 0;
@@ -371,9 +405,17 @@ function readModifiedFilesContent(projectDir, summaries) {
             for (const file of files) {
                 if (total >= 50)
                     break;
-                if (!file || !isInsideRoot(file, projectDir))
+                if (!file)
+                    continue;
+                // Migrated off the hand-rolled prefix check (ADR-4650): resolve+contain in one
+                // step via the canonical realpath predicate — the eventual read below follows
+                // symlinks, so containment must be decided on the resolved target, not a lexical
+                // prefix. Read the value the predicate RETURNED; do not re-derive the path.
+                const candidate = node_path_1.default.isAbsolute(file) ? file : node_path_1.default.join(projectDir, file);
+                const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+                if (contained === null)
                     continue;
-                const raw = readIfExists(resolvePath(file, projectDir));
+                const raw = readIfExists(contained);
                 out.push(raw.length > 256 * 1024 ? raw.slice(0, 256 * 1024) : raw);
                 total++;
             }
@@ -411,9 +453,11 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
             not_honored: [],
             message: partialParse
                 ? 'Decision coverage verify (warning): decisions could not be fully parsed — one or more ' +
-                    '`- **D-NN ...**` bullets appear malformed. Fix the bullet format in the CONTEXT.md decisions block.'
+                    '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
+                    'prefix that is not a digit run). Fix the bullet format in the CONTEXT.md decisions block.'
                 : 'Decision coverage verify (warning): could not parse decisions — possible format mismatch. ' +
-                    'Check the formatting of the CONTEXT.md decisions block.',
+                    'Check the formatting of the CONTEXT.md decisions block (accepted forms: `- **D-NN:** text`, ' +
+                    '`- **D4-NN:** text` (phase-prefixed), `- **D-NN — title** body`).',
         }, raw, undefined);
         return;
     }
@@ -1019,8 +1063,9 @@ function cmdGapAnalysisPlanPost(projectDir, args, raw) {
         error('gap-analysis.plan-post requires a phase-dir argument: check gap-analysis.plan-post <phase-dir> [phase-req-ids]', ERROR_REASON.SDK_MISSING_ARG);
         return;
     }
+    const resolvedPhaseDir = resolvePath(phaseDir, projectDir);
     const phaseReqIds = args[3] ?? undefined;
-    const result = runGapAnalysis(projectDir, phaseDir, { phaseReqIds });
+    const result = runGapAnalysis(projectDir, resolvedPhaseDir, { phaseReqIds });
     // Uniform gate contract: block = false (gap-analysis is always advisory, never blocks).
     // `message` carries the human-readable gap analysis report so the dispatch's
     // advisory branch can surface it. --raw emits JSON (rawValue=undefined), not
@@ -1071,21 +1116,21 @@ function buildPredicateDeps() {
                 node_path_1.default.win32.basename(artifactSuffix) !== artifactSuffix) {
                 return null;
             }
-            const directPath = (0, security_cjs_1.validatePath)(artifactSuffix, phaseDir);
-            if (directPath.safe && node_fs_1.default.existsSync(directPath.resolved) && node_fs_1.default.statSync(directPath.resolved).isFile()) {
-                return directPath.resolved;
+            const directContained = (0, security_cjs_1.tryWithinRoot)(artifactSuffix, phaseDir);
+            if (directContained !== null && node_fs_1.default.existsSync(directContained) && node_fs_1.default.statSync(directContained).isFile()) {
+                return directContained;
             }
-            const planningPath = (0, security_cjs_1.validatePath)(node_path_1.default.join('.planning', artifactSuffix), phaseDir);
-            if (planningPath.safe && node_fs_1.default.existsSync(planningPath.resolved) && node_fs_1.default.statSync(planningPath.resolved).isFile()) {
-                return planningPath.resolved;
+            const planningContained = (0, security_cjs_1.tryWithinRoot)(node_path_1.default.join('.planning', artifactSuffix), phaseDir);
+            if (planningContained !== null && node_fs_1.default.existsSync(planningContained) && node_fs_1.default.statSync(planningContained).isFile()) {
+                return planningContained;
             }
             try {
                 const files = node_fs_1.default.readdirSync(phaseDir);
                 for (const f of files) {
                     if (f.endsWith('-' + artifactSuffix) || f === artifactSuffix) {
-                        const candidate = (0, security_cjs_1.validatePath)(f, phaseDir);
-                        if (candidate.safe && node_fs_1.default.statSync(candidate.resolved).isFile())
-                            return candidate.resolved;
+                        const candidateContained = (0, security_cjs_1.tryWithinRoot)(f, phaseDir);
+                        if (candidateContained !== null && node_fs_1.default.statSync(candidateContained).isFile())
+                            return candidateContained;
                     }
                 }
             }
@@ -1101,23 +1146,42 @@ function buildPredicateDeps() {
         }
     };
 }
-/** Parse `--flag value` pairs from an args array into a map (last write wins). */
-function parsePredicateFlags(args) {
-    const out = {};
+/**
+ * Split an args array into `--flag value` pairs and the leftover positional
+ * tokens, in ONE pass, with the semantics `check predicate` established
+ * (#2008): a `--flag` followed by a non-`--` token consumes it as the value
+ * (last write wins); a `--flag` with no value stays a bare token and moves to
+ * the positionals; everything else is positional. `parsePredicateFlags` is
+ * the flags half of this same pass — there is exactly one parser, so the
+ * flag-taking check verbs cannot drift apart (#4130 follow-up: `check
+ * decision-coverage-plan --context <path>` shares it).
+ */
+function partitionPredicateArgs(args) {
+    const flags = {};
+    const positionals = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (typeof a !== 'string')
             continue;
-        if (!a.startsWith('--'))
+        if (!a.startsWith('--')) {
+            positionals.push(a);
             continue;
+        }
         const key = a.slice(2);
         const next = args[i + 1];
         if (key.length > 0 && typeof next === 'string' && !next.startsWith('--')) {
-            out[key] = next;
+            flags[key] = next;
             i++;
         }
+        else {
+            positionals.push(a);
+        }
     }
-    return out;
+    return { flags, positionals };
+}
+/** Parse `--flag value` pairs from an args array into a map (last write wins). */
+function parsePredicateFlags(args) {
+    return partitionPredicateArgs(args).flags;
 }
 /**
  * `check predicate` — generic evaluator for capability gate `check.predicate`
@@ -1152,10 +1216,15 @@ function cmdCheckPredicate(projectDir, args, raw) {
         error('predicate --predicate value must be valid JSON', ERROR_REASON.USAGE);
         return;
     }
+    const rawPhaseDir = flags['phase-dir'];
+    let resolvedPhaseDir = rawPhaseDir;
+    if (typeof rawPhaseDir === 'string' && rawPhaseDir !== '') {
+        resolvedPhaseDir = resolvePath(rawPhaseDir, projectDir);
+    }
     const ctx = {
         cwd: projectDir,
         phaseNumber: flags['phase-number'],
-        phaseDir: flags['phase-dir'],
+        phaseDir: resolvedPhaseDir,
         phaseReqIds: flags['phase-req-ids'],
     };
     let result;
@@ -1249,7 +1318,12 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
     // Defense-in-depth: the resolved dir must be inside the phases root (or a
     // milestone archive under .planning/milestones).
     const milestonesRoot = node_path_1.default.join(pDir, 'milestones');
-    if (!isInsideRoot(resolvedDir, phasesRoot) && !isInsideRoot(resolvedDir, milestonesRoot)) {
+    // Lexical containment (ADR-4650): resolvedDir is a directory path, not read
+    // through here — mirrors the prior path.resolve(root, candidate)-based check
+    // without introducing a filesystem/realpath dependency this defense-in-depth
+    // recheck never had.
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedDir, phasesRoot) === null &&
+        (0, security_cjs_1.tryWithinRootLexical)(resolvedDir, milestonesRoot) === null) {
         output({
             block: true,
             passed: false,
@@ -1578,7 +1652,9 @@ function routeCheckCommand({ args, cwd, raw }) {
         // this for any gate whose `check` carries a `predicate` (instead of a `query`),
         // passing the predicate object as --predicate '<json>'. NOTE: unlike the
         // `check.query` subcommands above (which take positional phase args), this
-        // subcommand parses --flag value pairs.
+        // subcommand is flag-driven. `decision-coverage-plan` above now ALSO accepts
+        // `--context <path>` (its positionals still work) — both share
+        // partitionPredicateArgs, the one flag parser.
         cmdCheckPredicate(cwd, args, raw);
         return;
     }
@@ -1606,6 +1682,7 @@ module.exports = {
     cmdCheckPredicate,
     buildPredicateDeps,
     parsePredicateFlags,
+    partitionPredicateArgs,
     // Fail-closed phase-scope reader for the api-coverage gate — exported for
     // in-process failure-injection tests (#2365 review).
     readPhaseScope,

package/gsd-core/bin/lib/code-review-depth.cjs

@@ -61,7 +61,7 @@ function normalizeRelPath(p, repoRoot) {
     let relativized = false;
     if (typeof repoRoot === 'string' && repoRoot !== '') {
         const rootNormalized = repoRoot.trim().replace(/\\/g, '/').replace(/\/+$/, '');
-        if (rootNormalized !== '' && value.startsWith(`${rootNormalized}/`)) {
+        if (rootNormalized !== '' && value.startsWith(`${rootNormalized}/`)) { // allow-handrolled-containment: display-path normalization — strips a caller-declared repoRoot prefix so a path renders repo-relative, not a security root-confinement decision
             value = value.slice(rootNormalized.length + 1);
             relativized = true;
         }
@@ -86,7 +86,7 @@ function normalizeRelPath(p, repoRoot) {
  * with `rulePath + '/'`. Both arguments must already be normalized. Case-sensitive.
  */
 function ruleMatchesFile(rulePath, filePath) {
-    return filePath === rulePath || filePath.startsWith(`${rulePath}/`);
+    return filePath === rulePath || filePath.startsWith(`${rulePath}/`); // allow-handrolled-containment: rule-to-file segment match for selecting which review-depth rule applies — not a filesystem root-confinement gate
 }
 /**
  * Validate + normalize a single rule path (not yet matched against files).