@opengsd/gsd-core 1.7.0 → 1.9.0

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

@@ -12,6 +12,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripFencedCode = stripFencedCode;
+exports.stripInlineCode = stripInlineCode;
+exports.scanInlineCodeSpans = scanInlineCodeSpans;
 exports.extractFencedBlock = extractFencedBlock;
 exports.tokenizeHeadings = tokenizeHeadings;
 exports.collectSections = collectSections;
@@ -84,6 +86,111 @@ function stripFencedCode(content) {
     }
     return { text: kept.join('\n'), unterminatedFence: openFence !== null };
 }
+// ─── stripInlineCode ──────────────────────────────────────────────────────────
+/**
+ * Remove CommonMark inline code spans (§6.1) from prose, line by line.
+ *
+ * A span opens with a run of N backticks and closes at the next run of EXACTLY
+ * N backticks on the same line (a longer or shorter run is span content, per
+ * CommonMark). The whole span — delimiters and content — is replaced by a
+ * single space so the surrounding words do not join. A run with no matching
+ * closer is literal text and is kept. Spans never cross line boundaries here:
+ * multi-line code in planning prose is fenced-block territory
+ * (`stripFencedCode`).
+ *
+ * Companion to `stripFencedCode` for term-matching callers (#2365): strip
+ * fenced blocks first, then inline spans, so a trigger term inside backticks
+ * is code, not prose evidence.
+ */
+function stripInlineCode(content) {
+    if (typeof content !== 'string' || content.length === 0)
+        return '';
+    return content.split('\n').map(stripInlineCodeLine).join('\n');
+}
+/**
+ * Locate every inline code span in `content`, per line (offsets are into the
+ * full string; spans never cross a `\n`). Callers that need the span CONTENT
+ * (e.g. api-coverage's dependency-evidence scan, #2365) use this; callers that
+ * just want spans gone use `stripInlineCode`.
+ */
+function scanInlineCodeSpans(content) {
+    if (typeof content !== 'string' || content.length === 0)
+        return [];
+    const out = [];
+    let lineStart = 0;
+    for (const line of content.split('\n')) {
+        for (const s of scanSpansInLine(line)) {
+            out.push({ start: lineStart + s.start, end: lineStart + s.end, content: s.content });
+        }
+        lineStart += line.length + 1;
+    }
+    return out;
+}
+function scanSpansInLine(line) {
+    const spans = [];
+    if (line.indexOf('`') === -1)
+        return spans;
+    // Collect the maximal backtick RUNS once, then match openers to closers using
+    // a per-length forward cursor. A naive "search the rest of the line for the
+    // closer" loop is O(n²) on a line of many unmatched increasing-length runs
+    // (#2365 review 9); precomputing runs makes the whole scan linear while
+    // preserving CommonMark semantics (closer = next run of EXACTLY the same len).
+    const runs = [];
+    for (let i = 0; i < line.length;) {
+        if (line[i] === '`') {
+            let n = 1;
+            while (i + n < line.length && line[i + n] === '`')
+                n++;
+            runs.push([i, n]);
+            i += n;
+        }
+        else {
+            i++;
+        }
+    }
+    const runsByLen = new Map();
+    for (let k = 0; k < runs.length; k++) {
+        const len = runs[k][1];
+        const arr = runsByLen.get(len);
+        if (arr)
+            arr.push(k);
+        else
+            runsByLen.set(len, [k]);
+    }
+    const cursorByLen = new Map();
+    let k = 0;
+    while (k < runs.length) {
+        const [openPos, n] = runs[k];
+        const candidates = runsByLen.get(n); // n came from this map, always present
+        let ci = cursorByLen.get(n) ?? 0;
+        while (ci < candidates.length && candidates[ci] <= k)
+            ci++;
+        if (ci < candidates.length) {
+            const closeK = candidates[ci];
+            const closePos = runs[closeK][0];
+            spans.push({ start: openPos, end: closePos + n, content: line.slice(openPos + n, closePos) });
+            cursorByLen.set(n, ci + 1);
+            k = closeK + 1; // resume after the closer — runs inside the span are code
+        }
+        else {
+            cursorByLen.set(n, ci);
+            k++; // unmatched run → literal text, next run is a fresh opener
+        }
+    }
+    return spans;
+}
+function stripInlineCodeLine(line) {
+    const spans = scanSpansInLine(line);
+    if (spans.length === 0)
+        return line;
+    let out = '';
+    let prev = 0;
+    for (const s of spans) {
+        out += line.slice(prev, s.start) + ' ';
+        prev = s.end;
+    }
+    return out + line.slice(prev);
+}
 /**
  * Shared low-level fence-scanning engine. Walks `lines` and returns every
  * fenced block found, applying the EXACT SAME CommonMark delimiter rules as

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

@@ -38,6 +38,14 @@ const { extractOneLinerFromBody } = coreUtilsMod;
 const { planningPaths } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { writeStateMd } = stateMod;
+// #2288 security: a milestone version label becomes a filesystem directory
+// component (`milestones/<label>-phases/`) into which phase directories are
+// MOVED. Any label used as a path segment must be a safe version token —
+// letters/digits/'.'/'-'/'_', leading alphanumeric, no path separators and no
+// `..` (the leading-alphanumeric anchor rejects a bare `..`). This gates both
+// the caller-supplied `--archive-version` override and the STATE.md-derived
+// live-read value, so a crafted value cannot escape `.planning/milestones/`.
+const ARCHIVE_VERSION_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 /**
  * Scope an `updateTableCell` call to the `## Traceability` (or
  * `## Traceability Status`) heading's own section — up to the next H1/H2
@@ -229,10 +237,179 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
         write_set_complete: (0, write_set_cjs_1.writeSetComplete)(writeSet),
     }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
 }
+/**
+ * #2388: a requirement ID shared by more than one plan in a phase must not be
+ * handed to `cmdRequirementsMarkComplete` until every plan declaring it has
+ * finished (i.e. has a `*-SUMMARY.md`) — otherwise the ID reads `Complete` in
+ * REQUIREMENTS.md ~20 minutes before its sibling plans even run, and long
+ * before `verify_phase_goal` has a chance to catch a gap.
+ *
+ * Pure read-only gate: scans sibling `*-PLAN.md` files in the SAME phase
+ * directory as `planPath` (excluding `planPath` itself) and, for each
+ * candidate ID, blocks it only when a sibling plan ALSO declares that ID in
+ * its own `requirements:` frontmatter AND that sibling has no matching
+ * `*-SUMMARY.md` yet. An ID no sibling declares is never blocked — a
+ * single-plan (non-shared) ID is always `ready`, preserving immediate
+ * marking with no added latency (acceptance criterion 4). Does not read or
+ * write REQUIREMENTS.md itself; callers pass the `ready` subset on to
+ * `cmdRequirementsMarkComplete` (whose own flip semantics are untouched).
+ */
+function cmdRequirementsReadyIds(cwd, args, raw) {
+    const planPathArg = args[0];
+    if (!planPathArg) {
+        error('plan path required. Usage: requirements ready-ids <plan-path> REQ-01,REQ-02');
+    }
+    const reqIds = args
+        .slice(1)
+        .join(' ')
+        .replace(/[\[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (reqIds.length === 0) {
+        output({ ready: [], blocked: [], total: 0 }, raw, 'no requirement IDs provided');
+        return;
+    }
+    const planAbsPath = node_path_1.default.resolve(cwd, planPathArg);
+    const phaseDir = node_path_1.default.dirname(planAbsPath);
+    const currentBasename = node_path_1.default.basename(planAbsPath);
+    let siblingPlanFiles = [];
+    try {
+        siblingPlanFiles = node_fs_1.default
+            .readdirSync(phaseDir)
+            .filter((f) => f.endsWith('-PLAN.md') && f !== currentBasename);
+    }
+    catch {
+        siblingPlanFiles = [];
+    }
+    const parseFrontmatterReqIds = (content, sourcePath) => {
+        const fm = extractFrontmatter(content, sourcePath);
+        const fmReq = fm.requirements;
+        if (Array.isArray(fmReq))
+            return fmReq.map((r) => String(r).trim()).filter(Boolean);
+        if (typeof fmReq === 'string') {
+            return fmReq
+                .replace(/[\[\]]/g, '')
+                .split(/[,\s]+/)
+                .map((r) => r.trim())
+                .filter(Boolean);
+        }
+        return [];
+    };
+    const ready = [];
+    const blocked = [];
+    for (const reqId of reqIds) {
+        let blockedBySibling = false;
+        for (const siblingFile of siblingPlanFiles) {
+            const siblingPath = node_path_1.default.join(phaseDir, siblingFile);
+            let siblingContent;
+            try {
+                siblingContent = node_fs_1.default.readFileSync(siblingPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const siblingReqIds = parseFrontmatterReqIds(siblingContent, siblingPath);
+            const siblingDeclaresId = siblingReqIds.some((id) => id.toLowerCase() === reqId.toLowerCase());
+            if (!siblingDeclaresId)
+                continue;
+            // Sibling declares the SAME ID — it must have finished (produced a
+            // SUMMARY) before this ID is ready to mark Complete.
+            const siblingSummaryPath = siblingPath.replace(/-PLAN\.md$/, '-SUMMARY.md');
+            if (!node_fs_1.default.existsSync(siblingSummaryPath)) {
+                blockedBySibling = true;
+                break;
+            }
+        }
+        if (blockedBySibling)
+            blocked.push(reqId);
+        else
+            ready.push(reqId);
+    }
+    output({ ready, blocked, total: reqIds.length }, raw, `${ready.length}/${reqIds.length} requirement(s) ready to mark complete`);
+}
+/**
+ * #2388: revert this phase's own requirement IDs out of `Complete` when
+ * `verify_phase_goal` returns `gaps_found` — a gap verdict must not leave a
+ * premature `Complete` (from a shared ID's first-declaring plan, or from any
+ * other early write) sitting in REQUIREMENTS.md indefinitely.
+ *
+ * Mirrors `cmdRequirementsMarkComplete`'s two write surfaces in reverse:
+ * checkbox `[x]` -> `[ ]`, and traceability Status `Complete` -> `Gaps
+ * Found`. Phase-scoping is the CALLER's responsibility — this function only
+ * ever touches the exact IDs it is given, so a caller passing just this
+ * phase's own `phase_req_ids` never touches another phase's `Complete` row.
+ * Never call this on the pass path; it is `gaps_found`-only.
+ */
+function cmdRequirementsRevertPhase(cwd, reqIdsRaw, raw) {
+    const reqIds = (reqIdsRaw || [])
+        .join(' ')
+        .replace(/[\[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (reqIds.length === 0) {
+        output({ reverted: [], unchanged: [], total: 0 }, raw, 'no requirement IDs provided');
+        return;
+    }
+    const reqPath = planningPaths(cwd).requirements;
+    if (!node_fs_1.default.existsSync(reqPath)) {
+        output({ reverted: [], unchanged: reqIds, total: reqIds.length, reason: 'REQUIREMENTS.md not found' }, raw, 'no requirements file');
+        return;
+    }
+    let reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
+    const reverted = [];
+    const unchanged = [];
+    for (const reqId of reqIds) {
+        const reqEscaped = escapeRegex(reqId);
+        let idReverted = false;
+        // Surface 1 — checkbox: - [x] **REQ-ID** -> - [ ] **REQ-ID**
+        const checkboxPattern = new RegExp(`(-\\s*\\[)x(\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+        const afterCheckbox = reqContent.replace(checkboxPattern, '$1 $2');
+        if (afterCheckbox !== reqContent) {
+            reqContent = afterCheckbox;
+            idReverted = true;
+        }
+        // Surface 2 — traceability row: Status Complete -> Gaps Found. Only
+        // flips a row currently reading Complete (mirrors mark-complete's own
+        // "only flip Pending -> Complete" gate, in reverse).
+        const rowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
+        let tableHit = false;
+        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            if (/^complete$/i.test(current.trim())) {
+                tableHit = true;
+                return ' Gaps Found ';
+            }
+            return current;
+        });
+        if (tableUpdate.ok) {
+            reqContent = tableUpdate.value;
+            if (tableHit)
+                idReverted = true;
+        }
+        if (idReverted)
+            reverted.push(reqId);
+        else
+            unchanged.push(reqId);
+    }
+    if (reverted.length > 0) {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(reqPath, reqContent);
+    }
+    output({ reverted, unchanged, total: reqIds.length }, raw, `${reverted.length}/${reqIds.length} requirement(s) reverted from Complete`);
+}
 function cmdMilestoneComplete(cwd, version, options, raw) {
     if (!version) {
         error('version required for milestone complete (e.g., v1.0)');
     }
+    // #2288 security: `version` is a CLI positional that is interpolated into
+    // multiple filesystem sinks below — `path.join(archiveDir, `${version}-ROADMAP.md`)`,
+    // `${version}-REQUIREMENTS.md`, `${version}-MILESTONE-AUDIT.md`, and the
+    // `${version}-phases` archive directory that phase dirs are MOVED into. Reject
+    // path separators / `..` here (same guard as `--archive-version`) so a crafted
+    // version cannot write or relocate content outside `.planning/milestones/`.
+    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 "..".`);
+    }
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
@@ -354,7 +531,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             for (const s of summaries) {
                 try {
                     const content = node_fs_1.default.readFileSync(node_path_1.default.join(phasesDir, dir, s), 'utf-8');
-                    const fm = extractFrontmatter(content);
+                    const fm = extractFrontmatter(content, node_path_1.default.join(phasesDir, dir, s));
                     const rawOneLiner = fm['one-liner'];
                     const oneLiner = (typeof rawOneLiner === 'string' ? rawOneLiner : '') || extractOneLinerFromBody(content);
                     if (oneLiner) {
@@ -491,7 +668,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             kind: 'milestoneComplete',
             version,
             nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        }, { clock: clock_cjs_1.realClock, progressProvider: () => null });
+        }, { clock: clock_cjs_1.realClock, progressProvider: () => null, sourcePath: statePath });
         writeStateMd(statePath, result.content, cwd);
     }
     // Archive phase directories if requested
@@ -552,6 +729,32 @@ function cmdPhasesClear(cwd, raw, args) {
     // --force bypasses the uncommitted-changes guard. Only use when the caller
     // has already archived or explicitly accepts loss of uncommitted work. (#1447)
     const force = Array.isArray(args) && args.includes('--force');
+    // #2288: explicit outgoing-version override for the archive destination.
+    // new-milestone.md runs `state.milestone-switch` BEFORE `phases.clear --confirm`,
+    // so a live read of STATE.md would already report the NEW milestone version by
+    // the time we get here. Callers that know the outgoing version pass it explicitly;
+    // absent an override, archivePhaseDirectories falls back to the live read.
+    const avIndex = Array.isArray(args) ? args.indexOf('--archive-version') : -1;
+    let archiveVersionOverride = null;
+    if (avIndex !== -1) {
+        const rawArchiveVersion = args[avIndex + 1];
+        // Missing / flag-shaped value: fail loud instead of silently dropping the
+        // override. A truncated invocation (e.g. a broken template substitution
+        // leaving `--archive-version` with no value) must NOT fall through to the
+        // live read — that silently re-files the archive under the new milestone,
+        // the exact #2288 bug this flag exists to prevent.
+        if (typeof rawArchiveVersion !== 'string' || rawArchiveVersion.startsWith('--') || rawArchiveVersion.trim() === '') {
+            error('--archive-version requires a value (a milestone version token, e.g. v1.0)');
+        }
+        const trimmed = rawArchiveVersion.trim();
+        // #2288 security: reject path separators / `..` so a crafted value cannot
+        // relocate phase history outside `.planning/milestones/` (phase dirs are
+        // MOVED into the archive dir — a traversal is data loss, not just an odd name).
+        if (!ARCHIVE_VERSION_LABEL_RE.test(trimmed)) {
+            error(`--archive-version "${trimmed}" is invalid — a milestone version label may contain only letters, digits, '.', '-' and '_', and must not contain path separators or "..".`);
+        }
+        archiveVersionOverride = trimmed;
+    }
     let cleared = 0;
     if (node_fs_1.default.existsSync(phasesDir)) {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
@@ -598,7 +801,8 @@ function cmdPhasesClear(cwd, raw, args) {
         }
         try {
             // #1871: archive phase directories instead of destroying them (shared helper).
-            cleared = archivePhaseDirectories(cwd, phasesDir, dirs).archived;
+            // #2288: thread the explicit --archive-version override (if any) through.
+            cleared = archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride).archived;
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -609,18 +813,46 @@ function cmdPhasesClear(cwd, raw, args) {
 }
 /**
  * #1871: move each non-999 phase directory under `phasesDir` into
- * `milestones/<version>-phases/` (collision-safe; version from getMilestoneInfo,
- * timestamp fallback). Shared by `phases clear` (archive-then-remove) and the
- * internal milestone.complete phase archival so phase history survives a
- * milestone switch instead of being hard-deleted.
+ * `milestones/<version>-phases/` (collision-safe). Shared by `phases clear`
+ * (archive-then-remove) and the internal milestone.complete phase archival so
+ * phase history survives a milestone switch instead of being hard-deleted.
+ *
+ * Archive-version precedence (#2288): an explicit `archiveVersionOverride` wins
+ * first, then a live `getMilestoneInfo(cwd)` read (which itself defaults to a
+ * version like `v1.0` when ROADMAP/STATE is absent), and only a dated fallback
+ * label if no safe version label is resolvable at all. The override is validated
+ * by the caller (`cmdPhasesClear`); the live-read value is re-validated here
+ * (defense in depth) because `getMilestoneInfo` derives it from STATE.md's
+ * unvalidated `milestone:` field. The override exists because `new-milestone.md`
+ * runs `state.milestone-switch` BEFORE `phases.clear --confirm` — by the time
+ * this runs, a live read of STATE.md would already report the NEW milestone
+ * version, so phase history from the OLD milestone would be misfiled under the
+ * new version's archive directory. Callers that know the outgoing version must
+ * pass it explicitly.
  */
-function archivePhaseDirectories(cwd, phasesDir, dirs) {
-    let archiveVersion = null;
-    try {
-        archiveVersion = getMilestoneInfo(cwd).version ?? null;
-    }
-    catch {
-        /* ROADMAP/STATE unreadable — fall back to a dated label */
+function archivePhaseDirectories(cwd, phasesDir, dirs, archiveVersionOverride = null) {
+    // Self-protecting (#2288 security defense in depth): the sole current caller
+    // (`cmdPhasesClear`) already validates the override, but re-test it here so a
+    // future caller cannot reopen the path-traversal sink at line ~742. An override
+    // that fails the safe-label check is discarded (falls through to the live read
+    // / dated label) rather than reaching `path.join` unvalidated.
+    const safeOverride = archiveVersionOverride && ARCHIVE_VERSION_LABEL_RE.test(archiveVersionOverride.trim())
+        ? archiveVersionOverride.trim()
+        : null;
+    let archiveVersion = safeOverride;
+    if (!archiveVersion) {
+        try {
+            const liveVersion = getMilestoneInfo(cwd).version ?? null;
+            // Defense in depth (#2288 security): getMilestoneInfo reads STATE.md's
+            // `milestone:` field, which is unvalidated file content. Only accept it
+            // as a path component if it is a safe version label; a crafted value
+            // (path separators / `..`) falls through to the dated label below rather
+            // than escaping `.planning/milestones/`.
+            archiveVersion = liveVersion && ARCHIVE_VERSION_LABEL_RE.test(liveVersion) ? liveVersion : null;
+        }
+        catch {
+            /* ROADMAP/STATE unreadable — fall back to a dated label */
+        }
     }
     if (!archiveVersion) {
         archiveVersion = `archived-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 8)}`;
@@ -643,6 +875,8 @@ function archivePhaseDirectories(cwd, phasesDir, dirs) {
 }
 module.exports = {
     cmdRequirementsMarkComplete,
+    cmdRequirementsReadyIds,
+    cmdRequirementsRevertPhase,
     cmdMilestoneComplete,
     cmdPhasesClear,
 };

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

@@ -10,10 +10,11 @@ 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_RENDERING = 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.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.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.nextTier = nextTier;
 exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
 exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
+exports.renderEffortArgv = renderEffortArgv;
 exports.renderEffortForRuntime = renderEffortForRuntime;
 const node_path_1 = __importDefault(require("node:path"));
 // In .cts (CommonJS output) files, `require` is available as a global;
@@ -23,11 +24,19 @@ const _require = require;
 // works in every layout:
 //
 //   1. Co-located install path — gsd-core/bin/shared/model-catalog.json
-//   2. Source-repo dev path — sdk/shared/model-catalog.json
-//   3. GSD_MODEL_CATALOG env override
+//   2. GSD_MODEL_CATALOG env override
+//
+// A third candidate — `sdk/shared/model-catalog.json`, three levels up — used to
+// sit between them. It was the legacy source-repo path kept as a fallback by the
+// #3288 fix, whose contract was "check the co-located path FIRST, before the
+// legacy source-repo path". ADR-0174 then retired the `@opengsd/gsd-sdk` package
+// boundary and deleted the `sdk/` tree outright, so that candidate can no longer
+// resolve in any layout: in a source repo there is no `sdk/`, and in an install
+// layout it points at `~/.claude/sdk/shared/`, which the installer never writes
+// (the original #3288 bug). It is removed rather than left as dead weight that
+// implies a package boundary this repo no longer has.
 const _catalogCandidates = [
     node_path_1.default.resolve(__dirname, '..', 'shared', 'model-catalog.json'),
-    node_path_1.default.resolve(__dirname, '..', '..', '..', 'sdk', 'shared', 'model-catalog.json'),
     ...(process.env['GSD_MODEL_CATALOG'] ? [node_path_1.default.resolve(process.env['GSD_MODEL_CATALOG'])] : []),
 ];
 let catalog = null;
@@ -54,6 +63,13 @@ exports.catalog = _catalog;
 exports.VALID_PROFILES = [..._catalog.profiles];
 exports.VALID_PHASE_TYPES = new Set(_catalog.phaseTypes);
 exports.VALID_AGENT_TIERS = new Set(Object.keys(_catalog.adaptiveTierMap));
+// Catalog-derived so this can never drift from the resolver's tier gate:
+// Object.values(adaptiveTierMap) === ['opus', 'sonnet', 'haiku'] today, plus 'inherit'.
+exports.VALID_TIERS = new Set([...Object.values(_catalog.adaptiveTierMap), 'inherit']);
+// Same catalog-derived tier values as VALID_TIERS but WITHOUT 'inherit' — used
+// by config-loader's runtime-override validation (model_profile_overrides /
+// model_policy.runtime_tiers), which does not accept 'inherit' as a tier.
+exports.ADAPTIVE_TIER_VALUES = new Set(Object.values(_catalog.adaptiveTierMap));
 exports.MODEL_PROFILES = Object.fromEntries(Object.entries(_catalog.agents).map(([agent, meta]) => [agent, {
         quality: meta.golden,
         balanced: meta.balanced,
@@ -136,6 +152,55 @@ exports.EFFORT_RENDERING = {
         },
     },
 };
+exports.EFFORT_ARGV = {
+    // Verified against `claude --help`: `--effort <level>`.
+    claude: {
+        render: (level) => ['--effort', level],
+        supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
+        clamp: (level) => (level === 'minimal' ? 'low' : level),
+    },
+    // Verified against `opencode run --help`: `--variant` — "model variant
+    // (provider-specific reasoning effort, e.g., high, max, minimal)".
+    opencode: {
+        render: (level) => ['--variant', level],
+        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
+        clamp: (level) => level,
+    },
+    // 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.
+    codex: {
+        render: (level) => ['-c', `model_reasoning_effort=${level}`],
+        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
+        clamp: (level) => (level === 'max' ? 'xhigh' : level),
+    },
+};
+/**
+ * Render the invocation-time effort argument for a host.
+ *
+ * `effortSurface` is the host's negotiated axis value. Only `argv` produces an
+ * argument; `none`, `undocumented`, and anything unrecognised produce nothing.
+ * Never throws.
+ */
+function renderEffortArgv(host, universalEffort, effortSurface) {
+    const empty = { argv: [], value: null, host };
+    if (effortSurface !== 'argv')
+        return empty;
+    // Own-property lookup only. A plain `EFFORT_ARGV[host]` resolves `__proto__`
+    // (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))
+        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))
+        return empty;
+    return { argv: spec.render(clamped), value: clamped, host };
+}
 /**
  * Render a universal effort string for a specific runtime.
  */