@opengsd/gsd-core 1.13.0 → 1.15.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

@@ -1947,7 +1947,6 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'skillPriorityFrontmatter',
   'skillsGlobalOnboarding',
   'skillsManifestPrefix',
-  'skipCodexSkillsManifest',
   'skipHomePrefixSubstitution',
   'skipSettingsUi',
   'skipSharedHooksInstall',
@@ -1956,6 +1955,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 +2800,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 +2952,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');
@@ -270,11 +281,37 @@ function loadDecisionExtraction(contextPath) {
     return {
         trackable: extraction.decisions.filter((d) => d.trackable),
         outcome: extraction.outcome,
+        unreadableIds: extraction.unreadableIds ?? [],
     };
 }
+/**
+ * `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);
@@ -293,28 +330,59 @@ function cmdDecisionCoveragePlan(projectDir, args, raw) {
         output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
         return;
     }
-    const { trackable: decisions, outcome } = loadDecisionExtraction(contextPath);
+    // #4794: a NON-FILE path (a directory — the adjacent same-looking positional
+    // swapped, the issue's repro 2) is a caller error like #2770's empty argument:
+    // fs.existsSync is true, the read yields nothing, and the gate used to
+    // certify passed:true on a phase full of decisions. Fail closed, naming it.
+    // The stat is wrapped: a path that vanishes between existsSync and statSync
+    // (or any stat failure) must answer the SAME fail-closed JSON, never a throw.
+    let contextIsFile = false;
+    let contextKind = 'non-file entry';
+    try {
+        const st = node_fs_1.default.statSync(contextPath);
+        contextIsFile = st.isFile();
+        if (st.isDirectory())
+            contextKind = 'directory';
+    }
+    catch {
+        contextIsFile = false;
+        contextKind = 'unreadable path';
+    }
+    if (!contextIsFile) {
+        output({ passed: false, skipped: false, reason: 'context path is not a file', total: null, covered: null, message: `Decision coverage gate: the context path "${contextArg}" is not a readable file (${contextKind}). Swap the adjacent positionals or pass --context <path-to-CONTEXT.md>.` }, raw, undefined);
+        return;
+    }
+    const { trackable: decisions, outcome, unreadableIds } = loadDecisionExtraction(contextPath);
     // #1365 fail-loud gate: any could-not-parse outcome must NOT silently pass —
     // even when some decisions were extracted (e.g. D-01 valid but D-02 malformed).
     // A parse-miss on ANY bullet means the gate cannot certify full coverage.
     // Fire independent of decisions.length so a partial-parse still blocks.
     if (outcome === 'could-not-parse') {
+        // #4794: nothing was measured — the answer must not carry the fields of a
+        // gate that did. total/covered are null (a type change is the point:
+        // 0 reads as data, null does not), `uncovered` is OMITTED (the list was
+        // never built), and the ids that failed to parse are carried so a caller
+        // capturing stdout knows which decision to fix.
         const partialParse = decisions.length > 0;
         output({
             passed: false,
             skipped: false,
             reason: 'could-not-parse',
-            total: decisions.length,
-            covered: 0,
-            uncovered: [],
-            message: partialParse
+            total: null,
+            covered: null,
+            unreadable: unreadableIds,
+            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.')
+                + (unreadableIds.length > 0 ? ' Unreadable ids: ' + unreadableIds.join(', ') + '.' : ''),
         }, raw, undefined);
         return;
     }
@@ -354,11 +422,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 +434,17 @@ function readModifiedFilesContent(projectDir, summaries) {
             for (const file of files) {
                 if (total >= 50)
                     break;
-                if (!file || !isInsideRoot(file, projectDir))
+                if (!file)
                     continue;
-                const raw = readIfExists(resolvePath(file, projectDir));
+                // 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(contained);
                 out.push(raw.length > 256 * 1024 ? raw.slice(0, 256 * 1024) : raw);
                 total++;
             }
@@ -411,9 +482,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;
     }
@@ -502,8 +575,10 @@ function findUiSpecInDir(phaseDir) {
  * matches the token `dashboard` exactly like the real compound `micro-frontend`
  * (the boundary rule of #3718 is intentional and untouched). The gate therefore
  * blocks only when the token match is corroborated by static frontend evidence
- * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep or
- * a component-framework file). This mirrors the sibling post-wave gate
+ * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep, a
+ * component-framework file, or native UI evidence — a `.xaml` file or a
+ * `.swift`/`.kt`/`.dart` file carrying its ecosystem's UI import marker,
+ * #4658). This mirrors the sibling post-wave gate
  * computeUiSafetyGate, which requires `hasUiFiles` (git diff) before blocking.
  * matchedToken/matchedLine surface what tripped the sniffer so an operator can
  * judge the flag in one second instead of reaching for --skip-ui.
@@ -925,8 +1000,22 @@ function resolvePhaseDirOrEmpty(projectDir, phase) {
  * phase's `-PLAN.md` files against the filesystem WITHOUT executing anything —
  * see verify-command-grounding.cjs for the recognizer contract.
  *
- * Args: check verify-command-paths <phase>
+ * Args: check verify-command-paths <phase> | check verify-command-paths --dir <plan-dir>
  * Invocable as: gsd_run check verify-command-paths <phase>
+ *               gsd_run check verify-command-paths --dir <plan-dir>
+ *
+ * `--dir` (#4767) names a directory holding `-PLAN.md` files directly, for
+ * plans that live outside `.planning/phases/` — quick mode's
+ * `.planning/quick/<id>/` is the motivating caller, which until #4767 never ran
+ * this probe at all. The directory is resolved against the project root AND
+ * CONTAINED WITHIN IT — an absolute or climbing `--dir` that lands outside the
+ * root is `unresolvable`, never read — then probed exactly as a phase directory
+ * is; `projectRoot` stays the project root in both forms. `--dir <value>` is the
+ * only accepted spelling: `--dir=<value>` yields no `dir` flag and falls through to
+ * the no-argument arm, as does an empty value. Both are `partitionPredicateArgs`
+ * behaviour, inherited and unchanged. (How that parser resolves a REPEATED `--dir`
+ * is deliberately not characterised here — a malformed later occurrence does not
+ * displace an earlier valid one, so the obvious "last one wins" gloss is wrong.)
  *
  * When the phase cannot be resolved to a directory, this emits a non-throwing
  * degraded JSON payload (status/commands/counts all zeroed, `readError`
@@ -935,18 +1024,60 @@ function resolvePhaseDirOrEmpty(projectDir, phase) {
  * look", which a non-zero exit / thrown error would collapse.
  */
 function cmdVerifyCommandPaths(projectDir, args, raw) {
-    // args[0] = 'check', args[1] = 'verify-command-paths', args[2] = phase
-    const phase = args[2] || '';
-    if (!phase) {
+    // args[0] = 'check', args[1] = 'verify-command-paths', then either a phase
+    // positional or `--dir <plan-dir>` (#4767).
+    const { flags, positionals } = partitionPredicateArgs(args.slice(2));
+    const dirFlag = typeof flags['dir'] === 'string' ? flags['dir'] : '';
+    // First non-flag positional: `--raw` (valueless) lands in positionals too, and its position
+    // relative to the phase argument is the caller's choice.
+    const phase = positionals.find(p => !p.startsWith('--')) ?? '';
+    if (!phase && !dirFlag) {
         output({
             status: 'unresolvable',
             commands: [],
             counts: { blocker: 0, warning: 0, total: 0 },
-            readError: 'verify-command-paths requires a phase argument: check verify-command-paths <phase>',
+            readError: 'verify-command-paths requires a phase argument or --dir: check verify-command-paths <phase> | --dir <plan-dir>',
         }, raw, undefined);
         return;
     }
-    const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    // `--dir` is CALLER-SUPPLIED, so it is contained before it reaches the
+    // `readdirSync`/`readFileSync` calls in probePhaseVerifyCommands (#4785 review).
+    // Same predicate and policy as `resolvePath` above, and for the reason ADR-4650
+    // gives at the other read site: the reads below FOLLOW SYMLINKS, so containment
+    // must be decided on the resolved target, not a lexical prefix — a link inside
+    // the root pointing outside it passes `tryWithinRootLexical` and is then read.
+    // Read the value the predicate RETURNED; never re-derive the path. An escape
+    // degrades to the same non-throwing payload the unresolvable-phase arm emits,
+    // because a consumer must be able to tell "could not look" from "nothing to
+    // report" (and `error()` would collapse them).
+    //
+    // RESIDUAL, stated rather than left to be rediscovered: this is check-then-use, so
+    // a symlink planted at the resolved path BETWEEN this call and the reads inside
+    // probePhaseVerifyCommands would be followed. A link already in place when the
+    // command runs IS refused — the predicate resolves it and returns null (driven) —
+    // so the window is the in-process gap, not the ordinary case. It is a property of
+    // every `tryWithinRoot` call site in this repo, including `resolvePath` above and
+    // the artifact scan below, not of this arm; closing it needs O_NOFOLLOW/dirfd
+    // semantics inside the ADR-4650 predicate, which is a wider change than the bug
+    // this fixes.
+    let phaseDir;
+    if (dirFlag) {
+        const candidate = node_path_1.default.isAbsolute(dirFlag) ? dirFlag : node_path_1.default.join(projectDir, dirFlag);
+        const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+        if (contained === null) {
+            output({
+                status: 'unresolvable',
+                commands: [],
+                counts: { blocker: 0, warning: 0, total: 0 },
+                readError: `--dir resolves outside the project root: ${dirFlag}`,
+            }, raw, undefined);
+            return;
+        }
+        phaseDir = contained;
+    }
+    else {
+        phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    }
     if (!phaseDir) {
         output({
             status: 'unresolvable',
@@ -1019,8 +1150,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 +1203,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 +1233,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 +1303,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 +1405,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 +1739,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 +1769,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).

package/gsd-core/bin/lib/codex-agent-toml.cjs

@@ -382,9 +382,9 @@ function stripReasoningEffort(doc) {
 /**
  * The 17 roles measured as widening under derivation (declare Write/Edit,
  * never in the pre-#3897 `CODEX_AGENT_SANDBOX` map, so the old
- * `|| 'read-only'` fallback silently under-granted them). Pinned to
- * `read-only` pending the open question of whether Codex enforces
- * `sandbox_mode` or treats it as advisory (HALT.md). This list is CLOSED and
+ * `|| 'read-only'` fallback silently under-granted them) — pinned to
+ * `read-only` from 2026-09-08 (HALT.md) until #4770 lifted the hold on
+ * 2026-09-21. This list is CLOSED and
  * SHRINK-ONLY: a new writing role never lands here (S6, T26); it is validated
  * against the live tool contract every time it is consulted
  * ({@link _deriveCodexSandboxModeFromTools}) and against the real
@@ -401,29 +401,25 @@ function stripReasoningEffort(doc) {
  * parses the list correctly, so this role genuinely derives
  * `workspace-write` from its tool contract — HALT.md's original 16-role
  * count measured against the pre-fix (single-line) readers and undercounted
- * this role. It is held here for the same reason as the other 16: pending
- * Codex's `sandbox_mode` enforcement decision, not because the derivation is
- * wrong.
+ * this role.
+ *
+ * **LIFTED 2026-09-21 (#4770, maintainer decision: documented enforcement
+ * suffices).** The map is empty: the rung-3 hold's recorded reopen condition
+ * — official OpenAI documentation establishing Codex `sandbox_mode` as an
+ * enforced technical boundary that custom subagent TOML files honor — is
+ * satisfied, so every role now derives `sandbox_mode` purely from its own
+ * `tools:` frontmatter (`workspace-write` iff Write/Edit is declared). The
+ * shrink-to-zero invariant (ADR-3473 §8.3) is satisfied by reaching zero;
+ * the map is kept as an empty frozen structure so a future re-hold has a
+ * shape to land in, and {@link validateCodexSandboxHolds} keeps failing if
+ * the list ever grows a role that no longer exists in `agents/`. The
+ * #3897 security-review F1/F3 fail-closed pins are unchanged and
+ * map-independent: `suspicious` identities (non-ASCII after
+ * normalization) still pin `read-only`, and post-lift the sandbox derives
+ * from an artifact's own CONTENT, so the F1 identity-confusion attack no
+ * longer has a hold to ride.
  */
-exports.CODEX_SANDBOX_HOLDS = Object.freeze({
-    'gsd-ai-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-code-fixer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-code-reviewer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-debug-session-manager': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-classifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-synthesizer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-verifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-writer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-dom-verifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-domain-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-eval-auditor': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-eval-planner': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-intel-updater': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-pattern-mapper': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-ui-auditor': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-ui-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-nyquist-auditor': 'declares Write/Edit (YAML list-form tools:, surfaced by the list-form parse fix); pending Codex sandbox_mode enforcement decision',
-});
+exports.CODEX_SANDBOX_HOLDS = Object.freeze({});
 // True iff a `tools:` frontmatter value declares Write or Edit as a whole
 // token (never a substring match, so a hypothetical "Edith"-named tool could
 // never collide). Single predicate owner for both the emitter