@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/markdown-table.cjs

@@ -657,6 +657,54 @@ function escapeCell(value) {
  * Raw Text Matching").
  */
 exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
+/**
+ * #3860: heading predicate for STATE.md's Quick Tasks Completed section(s).
+ * The heading is a section LABEL, not data — milestone-scoped files
+ * legitimately carry suffixed headings (`### Quick Tasks Completed (v1.1+)`
+ * beside an archived `(v1.0)`), so the match is prefix-anchored with a word
+ * boundary, never exact: `Quick Tasks Completedness` must NOT match. Hoisted
+ * beside QUICK_TASKS_SECTION_ABSENT so `appendQuickTaskRow` and
+ * `resetQuickTaskRows` cannot drift apart again.
+ */
+const isQuickTasksHeading = (h) => /^quick tasks completed\b/i.test(h.text.trim());
+/**
+ * #3860: among ALL heading-matching sections, pick the first whose body is a
+ * table with a recognized Quick Tasks schema — a legacy/unparseable table
+ * first in document order no longer shadows a usable one further down. When
+ * NO section is usable, return the FIRST match so the caller's downstream
+ * error describes the real problem (unparseable/legacy table) instead of a
+ * false QUICK_TASKS_SECTION_ABSENT.
+ *
+ * Bounding: `collectSections` ends a candidate's body only at the NEXT
+ * matching heading — far too wide for splicing (it would swallow an
+ * intervening `## Deferred Items` table into the Quick Tasks body, and
+ * `appendQuickTaskRow`'s last-table-line scan would then splice the new row
+ * into that WRONG table). Each candidate is therefore re-collected through
+ * `collectSection` with an offset-precise predicate, whose default
+ * level-bounded stop (next heading of the same or higher level) is exactly
+ * the semantics the pre-#3860 single-section lookup had.
+ *
+ * Convention: "first" is document order — the newest-on-top layout the issue
+ * itself demonstrates (`(v1.1+)` above an archived `(v1.0)`). When several
+ * suffixed sections all carry recognized schemas, this layer has no signal
+ * for which milestone is active, so document order is the pinned tie-break.
+ */
+function selectQuickTasksSection(stateContent) {
+    const candidates = (0, markdown_sectionizer_cjs_1.collectSections)(stateContent, isQuickTasksHeading);
+    if (candidates.length === 0)
+        return null;
+    const boundedOf = (cand) => (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => h.offset === cand.heading.offset);
+    const firstBounded = boundedOf(candidates[0]);
+    for (const cand of candidates) {
+        const bounded = boundedOf(cand);
+        if (!bounded)
+            continue;
+        const parsed = parseMarkdownTable(bounded.body);
+        if (parsed.ok && matchTableSchema(parsed.value.columns)?.id === 'QuickTasks')
+            return bounded;
+    }
+    return firstBounded;
+}
 /**
  * Append one row to STATE.md's "Quick Tasks Completed" table.
  *
@@ -677,7 +725,7 @@ exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
  * rows), preserving any surrounding blank lines/trailing content in the section.
  */
 function appendQuickTaskRow(stateContent, fields) {
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    const section = selectQuickTasksSection(stateContent);
     if (!section) {
         return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }
@@ -697,7 +745,7 @@ function appendQuickTaskRow(stateContent, fields) {
     const rowNumber = parsed.value.rows.length + 1;
     const cellFor = (col) => {
         switch (col) {
-            case '#': return escapeCell(String(rowNumber));
+            case '#': return escapeCell(fields.quickId ?? String(rowNumber));
             case 'Description': return escapeCell(fields.description);
             case 'Date': return escapeCell(fields.date);
             case 'Commit': return escapeCell(fields.commit);
@@ -736,7 +784,7 @@ function appendQuickTaskRow(stateContent, fields) {
  * directories out from under the table (see `src/milestone.cts`'s
  * `archiveQuickTaskDirectories` / `cmdMilestoneComplete` wiring).
  *
- * Mirrors `appendQuickTaskRow`'s exact contract (same `collectSection` ->
+ * Mirrors `appendQuickTaskRow`'s exact contract (same `selectQuickTasksSection` ->
  * `parseMarkdownTable` -> `matchTableSchema` pipeline, same fail-loud posture,
  * same EOL-detect-before-split handling) rather than inventing a second one:
  *   - no "Quick Tasks Completed" heading -> `{ok:false, reason:
@@ -758,7 +806,7 @@ function resetQuickTaskRows(stateContent) {
     if (typeof stateContent !== 'string' || stateContent.trim() === '') {
         return { ok: false, reason: 'empty or non-string input' };
     }
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    const section = selectQuickTasksSection(stateContent);
     if (!section) {
         return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }

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

@@ -31,8 +31,14 @@ const { resolveQuickTaskSummaryFile } = auditMod;
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitMod = require("./cli-exit.cjs");
+const { ExitError } = cliExitMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateContract = require("./state-contract.cjs");
+const { publishStateContract } = stateContract;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
+const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
@@ -477,7 +483,7 @@ function applyQuickTasksReset(content) {
 }
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
-        error('version required for milestone complete (e.g., v1.0)');
+        error('version required for milestone complete (e.g., v1.0) — and --confirm to mutate');
     }
     // #2288 security: `version` is a CLI positional that is interpolated into
     // multiple filesystem sinks below — `path.join(archiveDir, `${version}-ROADMAP.md`)`,
@@ -488,6 +494,23 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!ARCHIVE_VERSION_LABEL_RE.test(version)) {
         error(`milestone complete: version "${version}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
     }
+    // #3726: confirmation gate — refuse before ANY read of the tree beyond the
+    // arg checks above, so an unconfirmed invocation is a guaranteed no-op on
+    // disk. The threat model is the NEVER_VALID_FLAGS one (gsd-tools.cjs): a
+    // caller supplies a token it believes is inert and a destructive operation
+    // proceeds unchecked — here the caller-side belief was that the `query`
+    // meta-prefix implies a read, and `query milestone.complete <v>` archived
+    // the milestone with no confirmation. The prefix is an intentional
+    // invocation-compatibility mechanism, not a permission boundary, so the
+    // gate lives on the destructive command itself and covers every invocation
+    // path. --dry-run needs no confirmation (it mutates nothing and is the
+    // recommended first step); --force does NOT imply it (see
+    // MilestoneCompleteOptions.confirm).
+    if (!options.dryRun && !options.confirm) {
+        error(`milestone complete is irreversible: it archives ROADMAP.md and REQUIREMENTS.md, MOVES every phase ` +
+            `directory for ${version} into .planning/milestones/, and rewrites STATE.md. ` +
+            `Nothing has been changed. Re-run with --confirm to proceed, or --dry-run to preview exactly what would move.`);
+    }
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
@@ -660,6 +683,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             }
         }
         catch (e) {
+            // ADR-3889: error() now throws ExitError (carries no message) instead
+            // of calling process.exit() directly, so it can no longer be detected
+            // by sniffing e.message — an ExitError from our own guard above must be
+            // re-thrown UNCONDITIONALLY, before any message inspection, or the
+            // guard silently stops blocking milestone completion.
+            if (e instanceof ExitError)
+                throw e;
             // If the error came from our guard, re-throw it; otherwise skip silently.
             const message = e instanceof Error ? e.message : String(e);
             if (message && message.startsWith('Cannot mark milestone complete:'))
@@ -838,6 +868,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // Create/append MILESTONES.md entry
     const accomplishmentsList = accomplishments.map((a) => `- ${a}`).join('\n');
     const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+    // #3685: mirror requirementsUpdated's diff-tracking contract — the result
+    // below used to report `milestones_updated: true` hardcoded, never
+    // consulting whether the MILESTONES.md write actually changed anything.
+    // Captured before the write branches below so the after-comparison reports
+    // a real content diff instead of an assumed one.
+    const milestonesBefore = node_fs_1.default.existsSync(milestonesPath) ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8') : null;
     if (node_fs_1.default.existsSync(milestonesPath)) {
         const existing = node_fs_1.default.readFileSync(milestonesPath, 'utf-8');
         if (!existing.trim()) {
@@ -867,6 +903,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     else {
         (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
     }
+    // #3685: real content diff, not the hardcoded `true` this used to report —
+    // see the `milestonesBefore` capture above.
+    const milestonesAfter = node_fs_1.default.existsSync(milestonesPath) ? node_fs_1.default.readFileSync(milestonesPath, 'utf-8') : null;
+    const milestonesUpdated = milestonesAfter !== milestonesBefore;
     // #2142 BLOCKER 2 (review): opt-in quick-task archival. This call MUST sit
     // immediately adjacent to the STATE.md write block directly below it, with
     // NO unguarded IO in between (unlike the ROADMAP/REQUIREMENTS/audit/
@@ -906,6 +946,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     // taken). `resync: true` mirrors `cmdPhaseComplete`'s posture (progress
     // recomputed from disk; only the preserve-when-unchanged deltas apply) —
     // milestone completion is the same kind of lifecycle transition.
+    // #3685: mirror requirementsUpdated's diff-tracking contract — this used to
+    // report `state_updated: fs.existsSync(statePath)`, true even on a no-op
+    // transaction. Declared here beside `stateUpdated`'s sibling flags and
+    // defaulted to `false` so the "STATE.md absent" case keeps today's answer
+    // (existsSync also returns false there) reached via a real content
+    // comparison instead.
+    let stateUpdated = false;
     if (node_fs_1.default.existsSync(statePath)) {
         withStateLock(statePath, () => {
             const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
@@ -976,6 +1023,24 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                 divergedFields,
             });
             (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, finalContent);
+            // #3685 / #3691: compare NORMALIZED bytes, not the pre-normalize
+            // `finalContent` string, against the pre-normalize `originalStateContent`
+            // read above. `platformWriteSync` runs Markdown normalization (blank-line
+            // insertion around headings/fences/lists) before persisting — the
+            // transition core (`transitionCore`'s `## Current Position` section
+            // reset) regenerates that section fresh on every call, including on a
+            // genuine no-op re-run, and its raw un-normalized output differs from
+            // the already-normalized on-disk original even though the write
+            // converges to byte-identical content. Comparing pre-normalize strings
+            // (mirroring cmdPhaseComplete's shape verbatim) was verified live to
+            // report `true` on three consecutive byte-identical writes.
+            // `contentChangedAfterNormalize` runs BOTH sides through the exact same
+            // normalizer `platformWriteSync` used to persist (no extra disk I/O,
+            // and immune by construction to this ordering artifact) — this used to
+            // re-read the file to get the same answer; #3691 hoisted that seam so
+            // this site, `updateRoadmapAfterPhaseRemoval`, and `cmdPhaseComplete`'s
+            // roadmap/state/requirements flags all agree by construction.
+            stateUpdated = (0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(statePath, originalStateContent, finalContent);
             for (const field of divergedFields) {
                 preservationWarnings.push({ field, reason: 'preserved-over-disagreeing-derived' });
             }
@@ -1053,11 +1118,27 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             phases_archive_skip_reason: phasesArchiveSkipReason,
             quick: !!quickArchiveResult && quickArchiveResult.archived > 0,
         },
-        milestones_updated: true,
-        state_updated: node_fs_1.default.existsSync(statePath),
+        // #3685: mirror requirementsUpdated's diff-tracking contract — both flags
+        // now report a real before/after content diff instead of the previous
+        // hardcoded `true` (milestones_updated) / bare fs.existsSync (state_updated).
+        milestones_updated: milestonesUpdated,
+        state_updated: stateUpdated,
         preservation_warnings: preservationWarnings,
     };
     output(result, raw);
+    // #3227 (design doc §40 row 26 / "Not-corruption" rule): a refreshed
+    // state.json `updated_at` must always mean something on disk actually
+    // moved. This site is unconditional because every reachable path either
+    // exits via `error()` (process.exit — refusals like a truncated milestone
+    // window, an unstarted phase, or an invalid version never reach here) or
+    // returns early on `--dry-run` (before any mutation, see the `dry_run:
+    // true` branch above) — the only way execution reaches this line is after
+    // the unconditional MILESTONES.md `platformWriteSync` a few lines above,
+    // which always runs (new file, empty file, or append) once the run is
+    // committed to mutating. Best-effort — cannot throw, cannot change this
+    // command's exit code or output. publishStateContract resolves the
+    // workstream planning root itself via planningPaths.
+    publishStateContract(cwd);
 }
 function cmdPhasesClear(cwd, raw, args) {
     const phasesDir = planningPaths(cwd).phases;
@@ -1100,7 +1181,11 @@ function cmdPhasesClear(cwd, raw, args) {
         // divergence meant a `0-*` directory `roadmap analyze` preserves as a
         // sentinel was DELETED here. Routed through the canonical predicate so
         // every reader of "is this a sentinel phase" agrees by construction.
-        const dirs = entries.filter((e) => e.isDirectory() && !isSentinelPhaseId(e.name));
+        // #3639: the DIR-AWARE recognizer — the convention-less id predicate
+        // never saw bracket sentinel dirs (GSD.999-07-icebox), so they were
+        // counted for deletion here while the disk guards (post-#3639) preserve
+        // them; the destructive path must not be the one blind reader left.
+        const dirs = entries.filter((e) => e.isDirectory() && !isSentinelPhaseDir(e.name));
         if (dirs.length > 0 && !confirm) {
             error(`phases clear would delete ${dirs.length} phase director${dirs.length === 1 ? 'y' : 'ies'}. ` +
                 `Pass --confirm to proceed.`);

package/gsd-core/bin/lib/model-catalog.cjs

@@ -10,11 +10,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_ARGV = exports.EFFORT_RENDERING = exports.CLAUDE_AGENT_ALIASES = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
+exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_ARGV = exports.EFFORT_RENDERING = exports.CLAUDE_AGENT_ALIASES = exports.KNOWN_PROVIDERS = exports.CODEX_MODEL_EFFORT = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
 exports.isAnthropicFlavoredModel = isAnthropicFlavoredModel;
 exports.nextTier = nextTier;
 exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
 exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
+exports.clampEffortForHost = clampEffortForHost;
 exports.renderEffortArgv = renderEffortArgv;
 exports.renderEffortForRuntime = renderEffortForRuntime;
 exports.mergeEffortTierDefaults = mergeEffortTierDefaults;
@@ -99,6 +100,38 @@ exports.RUNTIMES_WITH_REASONING_EFFORT = new Set(Object.entries(_catalog.runtime
     .filter(([, tiers]) => Object.values(tiers).some((entry) => entry && entry.reasoning_effort))
     .map(([runtime]) => runtime));
 exports.PROVIDER_PRESETS = _catalog.providerPresets ?? {};
+// ─── #3007 — Codex per-model effort capability ───────────────────────────────
+//
+// Codex's own `models.json` publishes `supported_reasoning_levels` per model and
+// rejects an unsupported level at request time, so GSD must be conservative
+// about what it sends: read the ceiling as DATA from the catalog (never
+// branch on model id in code) and fall back to the family baseline for any
+// model the catalog doesn't know about.
+// (b) A malformed catalog entry (e.g. a non-array value like `"gpt-x": 5`) must
+// degrade to "ignore that entry", never throw — model-catalog.cjs is required
+// across the whole CLI, so one bad JSON value must not kill every command.
+// `new Set(5)` would throw at module load; filter to array values first.
+exports.CODEX_MODEL_EFFORT = Object.fromEntries(Object.entries(_catalog.codexModelEffort ?? {})
+    .filter(([, levels]) => Array.isArray(levels))
+    .map(([model, levels]) => [model, new Set(levels)]));
+// (a) `??` only catches null/undefined. A malformed `"_baseline": null` still
+// produces `new Set(null)` above — an empty Set, which is truthy — so a bare
+// `??` fallback would never fire and every level would silently lose its
+// advertised set (every effort would render as `value: null`). Guard on
+// `.size > 0` so an empty/missing/malformed baseline always falls back to the
+// hardcoded floor instead of failing open.
+const CODEX_EFFORT_BASELINE = exports.CODEX_MODEL_EFFORT['_baseline'] && exports.CODEX_MODEL_EFFORT['_baseline'].size > 0
+    ? exports.CODEX_MODEL_EFFORT['_baseline']
+    : new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+function advertisedCodexEffort(model) {
+    if (typeof model !== 'string' || model.length === 0)
+        return CODEX_EFFORT_BASELINE;
+    return Object.prototype.hasOwnProperty.call(exports.CODEX_MODEL_EFFORT, model) ? exports.CODEX_MODEL_EFFORT[model] : CODEX_EFFORT_BASELINE;
+}
+// The full universal effort ladder, low-to-high. Used only to find "the
+// nearest advertised level below" when a requested level isn't supported —
+// never to invent behaviour for a level that isn't on it at all.
+const EFFORT_LADDER = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
 // KNOWN_PROVIDERS excludes 'generic' — it is a sentinel (all null entries) that
 // forces users to supply model IDs via model_profile_overrides. It is not a
 // real catalog-backed provider (#49).
@@ -124,7 +157,10 @@ exports.KNOWN_PROVIDERS = new Set(Object.entries(exports.PROVIDER_PRESETS)
 // rejects all of these.
 exports.CLAUDE_AGENT_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
 function isAnthropicFlavoredModel(model) {
-    return typeof model === 'string' && (exports.CLAUDE_AGENT_ALIASES.has(model) || model.toLowerCase().includes('claude'));
+    if (typeof model !== 'string')
+        return false;
+    const lower = model.toLowerCase();
+    return exports.CLAUDE_AGENT_ALIASES.has(lower) || lower.includes('claude');
 }
 function nextTier(currentTier) {
     const order = ['light', 'standard', 'heavy'];
@@ -165,12 +201,21 @@ exports.EFFORT_RENDERING = {
         },
     },
     codex: {
+        // #3007: 'max' and 'minimal' are stale here — Codex's per-model table
+        // (CODEX_MODEL_EFFORT above) is now the source of truth for what a given
+        // model actually advertises, and every model in the family baseline DOES
+        // advertise 'max' (no model advertises 'minimal'). This runtime-level
+        // spec is kept in sync with the family baseline so the two tables can
+        // never disagree; renderEffortForRuntime layers the per-model ceiling
+        // (and the 'ultra' policy rejection) on top of it.
+        // KEEP IN SYNC with EFFORT_ARGV.codex below — same family baseline, two
+        // channels (install-time vs invocation-time); they must never diverge.
         param: 'model_reasoning_effort',
         channel: 'api',
-        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
+        supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
         clamp(level) {
-            if (level === 'max')
-                return 'xhigh';
+            if (level === 'minimal')
+                return 'low';
             return level;
         },
     },
@@ -191,12 +236,45 @@ exports.EFFORT_ARGV = {
     },
     // First-party Codex docs: `model_reasoning_effort` is a config-only key with no
     // dedicated flag, so the generic `-c key=value` override is the only argv route.
+    // #3007: KEEP IN SYNC with EFFORT_RENDERING.codex above — this table must match
+    // the family baseline exactly (no 'minimal', 'max' passes through unclamped),
+    // otherwise the argv channel and the install-time channel disagree about the
+    // same runtime's capability.
     codex: {
         render: (level) => ['-c', `model_reasoning_effort=${level}`],
-        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
-        clamp: (level) => (level === 'max' ? 'xhigh' : level),
+        supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
+        clamp: (level) => (level === 'minimal' ? 'low' : level),
     },
 };
+/**
+ * Clamp a universal effort level to what a host actually accepts, or null.
+ *
+ * #3706 — extracted from `renderEffortArgv` so the two effort CHANNELS can share
+ * one capability table without one pretending to be the other. `EFFORT_ARGV[host]`
+ * describes what levels the host understands (`supported` + `clamp`); whether that
+ * reaches the host as a CLI flag or as a baked frontmatter key is the caller's
+ * business. The install-time OpenCode `variant:` writer needs the former without
+ * the latter, and hardcoding `'argv'` at that call site to borrow this logic read
+ * as if the frontmatter key were gated on the invocation-time axis. It is not —
+ * claude declares `effortSurface: "argv"` and independently bakes an `effort:` key.
+ *
+ * Returns null for a level the host does not accept, which every caller treats as
+ * "emit nothing". `inherit` lands here too: per #3533 (10d) it is not a wire level
+ * on any runtime, so it is in no `supported` set and must never be written out.
+ */
+function clampEffortForHost(host, universalEffort) {
+    // Own-property lookup only: a plain `EFFORT_ARGV[host]` resolves `__proto__`
+    // and friends to inherited members that carry no clamp/render.
+    if (typeof host !== 'string' || !Object.prototype.hasOwnProperty.call(exports.EFFORT_ARGV, host))
+        return null;
+    const spec = exports.EFFORT_ARGV[host];
+    if (!spec || typeof spec.clamp !== 'function')
+        return null;
+    if (typeof universalEffort !== 'string' || universalEffort.length === 0)
+        return null;
+    const clamped = spec.clamp(universalEffort);
+    return spec.supported.has(clamped) ? clamped : null;
+}
 /**
  * Render the invocation-time effort argument for a host.
  *
@@ -212,37 +290,117 @@ function renderEffortArgv(host, universalEffort, effortSurface) {
     // (and `constructor`/`toString`) to inherited members, which are truthy but
     // carry no `clamp`/`render` — a hostile host id would throw instead of
     // degrading. The host id reaches here from a descriptor, i.e. untrusted JSON.
-    if (typeof host !== 'string' || !Object.prototype.hasOwnProperty.call(exports.EFFORT_ARGV, host))
+    // #3706: the clamp/supported half lives in clampEffortForHost so the
+    // install-time channel can reuse it; this function keeps the axis gate and
+    // the argv rendering. One table, one clamp, two channels.
+    const clamped = clampEffortForHost(host, universalEffort);
+    if (clamped === null)
         return empty;
     const spec = exports.EFFORT_ARGV[host];
-    if (!spec || typeof spec.clamp !== 'function' || typeof spec.render !== 'function')
-        return empty;
-    if (typeof universalEffort !== 'string' || universalEffort.length === 0)
-        return empty;
-    const clamped = spec.clamp(universalEffort);
-    if (!spec.supported.has(clamped))
+    if (typeof spec.render !== 'function')
         return empty;
     return { argv: spec.render(clamped), value: clamped, host };
 }
 /**
  * Render a universal effort string for a specific runtime.
+ *
+ * `model` (#3007) is consulted ONLY for codex: Codex's per-model
+ * `supported_reasoning_levels` means the same universal level can be a clean
+ * pass-through on one model and a clamp (or, for 'ultra', an outright
+ * rejection) on another. Every other runtime ignores the third argument
+ * entirely — passing a model id to claude changes nothing.
  */
-function renderEffortForRuntime(runtime, universalEffort) {
+function renderEffortForRuntime(runtime, universalEffort, model) {
     // #3533 (10d): 'inherit' is not a wire level on ANY runtime — it means
     // "omit the key / pass no argument and follow the session/host default".
     // Renderers must never emit it as a literal; null param/channel tells
-    // resolve-execution consumers there is no propagation.
+    // resolve-execution consumers there is no propagation. Never measured
+    // against any supported set.
     if (universalEffort === 'inherit') {
-        return { value: 'inherit', param: null, channel: null };
+        return { value: 'inherit', param: null, channel: null, requested: 'inherit', clamped: false, reason: null };
     }
     const spec = exports.EFFORT_RENDERING[runtime];
     if (!spec) {
-        return { value: universalEffort, param: null, channel: null };
+        return { value: universalEffort, param: null, channel: null, requested: universalEffort, clamped: false, reason: null };
+    }
+    if (runtime === 'codex') {
+        // #2167 — 'ultra' turns on Codex's automatic task delegation, which would
+        // let Codex spawn agents underneath GSD's own orchestration. GSD rejects
+        // it unconditionally as a POLICY call, never as a capability clamp — this
+        // holds even for a model (e.g. gpt-5.6-sol) that DOES advertise 'ultra',
+        // so it is never softened down to 'max'.
+        if (universalEffort === 'ultra') {
+            return {
+                value: null,
+                param: null,
+                channel: null,
+                requested: 'ultra',
+                clamped: false,
+                reason: "'ultra' turns on Codex's automatic task delegation, which would let Codex spawn agents underneath GSD's own orchestration (#2167); GSD rejects it regardless of what the model advertises.",
+            };
+        }
+        const allowed = advertisedCodexEffort(model);
+        if (allowed.has(universalEffort)) {
+            return { value: universalEffort, param: spec.param, channel: spec.channel, requested: universalEffort, clamped: false, reason: null };
+        }
+        const idx = EFFORT_LADDER.indexOf(universalEffort);
+        if (idx === -1) {
+            // Not on the ladder at all (e.g. 'MAX') — preserve prior behaviour:
+            // fall through to the runtime-level clamp rather than inventing new
+            // handling for input the ladder doesn't recognize.
+            return { value: spec.clamp(universalEffort), param: spec.param, channel: spec.channel, requested: universalEffort, clamped: false, reason: null };
+        }
+        // Every model's advertised set is a contiguous run up to 'max' (or 'ultra'
+        // for sol, already handled above), so the only unsupported level in
+        // practice is 'minimal' — below every model's floor. Walk UP the ladder
+        // to the nearest level the model actually advertises (its floor): there
+        // is nothing below 'minimal' to fall back to.
+        // Walking UP is safe today only because every advertised set floors at
+        // 'low' — a future model whose floor is, say, 'high' would silently turn
+        // a requested 'low' into 'high': MORE reasoning and MORE cost than asked
+        // for, with no error. `clamped`/`reason` below is what makes that
+        // escalation visible to a caller instead of a silent cost surprise, which
+        // is why those fields are not optional decoration.
+        for (let i = idx + 1; i < EFFORT_LADDER.length; i++) {
+            const candidate = EFFORT_LADDER[i];
+            // 'ultra' is never a valid clamp target: it would re-enter, by the back
+            // door, the delegation mode the #2167 rejection above exists to keep
+            // out. A clamp may never produce a value that a direct request for
+            // that same value would have refused.
+            if (candidate === 'ultra') {
+                continue;
+            }
+            if (allowed.has(candidate)) {
+                return {
+                    value: candidate,
+                    param: spec.param,
+                    channel: spec.channel,
+                    requested: universalEffort,
+                    clamped: true,
+                    reason: `requested '${universalEffort}' is not in ${model ? `${model}'s` : "the codex family baseline's"} advertised reasoning levels; clamped up to its floor, '${candidate}'.`,
+                };
+            }
+        }
+        // No advertised level at or above the request either (shouldn't happen
+        // given today's catalog data, but never throw): reject rather than emit
+        // an unsupported level.
+        return {
+            value: null,
+            param: null,
+            channel: null,
+            requested: universalEffort,
+            clamped: false,
+            reason: `requested '${universalEffort}' is not in ${model ? `${model}'s` : "the codex family baseline's"} advertised reasoning levels, and no advertised level is available either.`,
+        };
     }
+    const value = spec.clamp(universalEffort);
     return {
-        value: spec.clamp(universalEffort),
+        value,
         param: spec.param,
         channel: spec.channel,
+        requested: universalEffort,
+        clamped: value !== universalEffort,
+        reason: value !== universalEffort ? `requested '${universalEffort}' clamped to '${value}' for ${runtime}.` : null,
     };
 }
 /**

package/gsd-core/bin/lib/model-resolver.cjs

@@ -35,6 +35,7 @@ const model_catalog_cjs_1 = require("./model-catalog.cjs");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspaceMod;
@@ -58,38 +59,19 @@ const { planningDir } = planningWorkspaceMod;
 // registry-parity test guards this set so a future alias-capable runtime fails
 // loudly here instead of silently omitting.
 const RUNTIMES_WITH_NATIVE_ALIASES = new Set(['claude']);
-let _installMarkerCache;
-function readInstallRuntimeMarker() {
-    if (_installMarkerCache !== undefined)
-        return _installMarkerCache;
-    try {
-        const markerPath = node_path_1.default.join(__dirname, '..', '..', '.gsd-runtime');
-        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
-        _installMarkerCache = raw || null;
-    }
-    catch {
-        // No marker: dev/source tree, or an install predating #2297. Fall through to
-        // the 'claude' default (keeps tier aliases — never worse than the bug).
-        _installMarkerCache = null;
-    }
-    return _installMarkerCache;
-}
-// Test seams for the install-marker rung (the dev/source tree has no marker, so
-// the file read always bottoms out at 'claude' — these let tests exercise the
-// third precedence rung and reset the module-level cache between cases).
-function _setInstallRuntimeMarkerForTests(value) {
-    _installMarkerCache = value;
-}
-function _resetInstallRuntimeMarkerCacheForTests() {
-    _installMarkerCache = undefined;
-}
+// #3897 rung 2: the marker reader + its cache and test seams were promoted to
+// the canonical owner, `runtime-slash.cts` (imported above) — this module now
+// consumes that single implementation instead of holding its own copy. N5:
+// behaviour and the seam contract are unchanged by the move; the re-exports
+// below (`export =` at the bottom of this file) preserve every existing
+// caller's `require('./model-resolver.cjs')` surface byte-for-behaviour.
 // The runtime whose install is actually resolving, canonicalized so an alias or
 // case variant (e.g. "claude-code"/"Claude") cannot defeat the native-alias
 // check below (#2297 review). Precedence mirrors resolveRuntime()
 // (runtime-slash.cts): GSD_RUNTIME env → project config.runtime → per-install
 // .gsd-runtime marker → 'claude'.
 function resolveActiveRuntime(config) {
-    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], readInstallRuntimeMarker()) || 'claude';
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], (0, runtime_slash_cjs_1.readInstallRuntimeMarker)()) || 'claude';
 }
 // Did the PROJECT's own config (root `.planning/config.json` or the active
 // workstream/project override) explicitly set resolve_model_ids to "omit"?
@@ -841,8 +823,8 @@ module.exports = {
     resolveTierFromConfig,
     _resetModelPolicyWarningCacheForTests,
     _resetModelOverrideWarningCacheForTests,
-    _setInstallRuntimeMarkerForTests,
-    _resetInstallRuntimeMarkerCacheForTests,
+    _setInstallRuntimeMarkerForTests: runtime_slash_cjs_1._setInstallRuntimeMarkerForTests,
+    _resetInstallRuntimeMarkerCacheForTests: runtime_slash_cjs_1._resetInstallRuntimeMarkerCacheForTests,
     VALID_GRANULARITIES,
     resolveGranularityInternal,
     assertValidGranularityOverride,

package/gsd-core/bin/lib/onboard-projection.cjs

@@ -117,7 +117,11 @@ function listPlanningDocCandidates(cwd) {
     return [...candidates].sort();
 }
 function listCodebaseMapFiles(cwd) {
-    const codebaseDir = node_path_1.default.join(planningRoot(cwd), 'codebase');
+    // #3964: project-scoped, agreeing with init's map-codebase surface and
+    // verify.cts's codebase drift check — a flat-root read made
+    // has_codebase_map/needs_codebase_map answer for the wrong project under
+    // GSD_PROJECT.
+    const codebaseDir = node_path_1.default.join(planningDir(cwd), 'codebase');
     if (!node_fs_1.default.existsSync(codebaseDir))
         return [];
     return REQUIRED_CODEBASE_MAP_FILES.filter((file) => node_fs_1.default.existsSync(node_path_1.default.join(codebaseDir, file)));

package/gsd-core/bin/lib/phase-estimation.cjs

@@ -218,14 +218,23 @@ function applyCalibration(rawTokens, factor) {
  * Extract a two-space-indented scalar block (`estimate:` / `actuals:`) out of a
  * document's leading YAML frontmatter.
  *
- * Hand-rolled because gsd-core ships no external dependencies (CONTRIBUTING.md
- * "No external dependencies in core") — js-yaml is a devDependency and is not
- * available at runtime. Scope is deliberately narrow: the leading `---` block
- * only, so a `estimate:` line inside a fenced code block in the body cannot be
- * mistaken for frontmatter (the DEFECT.FRONTMATTER-SCALAR-BROAD-GREP class).
- *
- * Numeric-looking values are returned as numbers so parseEstimate/parseActuals
- * see the types they validate; everything else stays a string.
+ * Hand-rolled for its TYPE CONTRACT, not for dependency availability — js-yaml
+ * is vendored and available at runtime as of ADR-3473 §8.1 (#3881), which
+ * migrated `src/frontmatter.cts`'s `extractFrontmatter` onto it. That parser
+ * runs under js-yaml's FAILSAFE_SCHEMA, which resolves every scalar as a
+ * string, whereas this function deliberately returns numbers for
+ * numeric-looking values (`out[m[1]] = asNumber : rawValue`) so
+ * `parseEstimate`/`parseActuals` see the types they validate. A naive swap
+ * onto `extractFrontmatter` would turn `tokens: 5000` into `"5000"` and make
+ * `isPositiveInt` reject every estimate. Scope is deliberately narrow: the
+ * leading `---` block only, so an `estimate:` line inside a fenced code
+ * block in the body cannot be mistaken for frontmatter (the
+ * DEFECT.FRONTMATTER-SCALAR-BROAD-GREP class). Migrating this function onto
+ * the shared parser (with a typed coercion layer over its string-only
+ * output) is tracked as follow-on work under ADR-3473 §8.1, not done here —
+ * this module is calibration-critical and has a history of subtle numeric
+ * defects shipping past a large green suite (#2631 factor², #2632
+ * self-defeating loop).
  */
 function extractFrontmatterBlock(text, key) {
     if (typeof text !== 'string')