@therocketcode/gsd-core 1.4.0

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

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Milestone — Milestone and requirements lifecycle operations.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/milestone.cjs collapsed to
+ * a TypeScript source of truth, compiled by tsc to a gitignored .cjs at the same
+ * require() path. Behaviour preserved byte-for-behaviour; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- core.cjs is an export= CommonJS module
+const core = require("./core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- state.cjs is an export= CommonJS module
+const stateMod = require("./state.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, normalizePhaseName, phaseTokenMatches, output, error, } = core;
+const { planningPaths } = planningWorkspace;
+const { extractFrontmatter } = frontmatterMod;
+const { writeStateMd, stateReplaceFieldWithFallback } = stateMod;
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+    if (!reqIdsRaw || reqIdsRaw.length === 0) {
+        error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+    }
+    // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+    const reqIds = reqIdsRaw
+        .join(' ')
+        .replace(/[\[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (reqIds.length === 0) {
+        error('no valid requirement IDs found');
+    }
+    const reqPath = planningPaths(cwd).requirements;
+    if (!node_fs_1.default.existsSync(reqPath)) {
+        output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+        return;
+    }
+    let reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
+    const updated = [];
+    const alreadyComplete = [];
+    const notFound = [];
+    for (const reqId of reqIds) {
+        let found = false;
+        const reqEscaped = escapeRegex(reqId);
+        // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+        // Use replace() directly and compare — avoids test()+replace() global regex
+        // lastIndex bug where test() advances state and replace() misses matches.
+        const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+        const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
+        if (afterCheckbox !== reqContent) {
+            reqContent = afterCheckbox;
+            found = true;
+        }
+        // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+        const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+        const afterTable = reqContent.replace(tablePattern, '$1 Complete $2');
+        if (afterTable !== reqContent) {
+            reqContent = afterTable;
+            found = true;
+        }
+        if (found) {
+            updated.push(reqId);
+        }
+        else {
+            // Check if already complete before declaring not_found.
+            // Non-global flag is fine here — we only need to know if a match exists.
+            const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i');
+            const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'i');
+            if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
+                alreadyComplete.push(reqId);
+            }
+            else {
+                notFound.push(reqId);
+            }
+        }
+    }
+    if (updated.length > 0) {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(reqPath, reqContent);
+    }
+    output({
+        updated: updated.length > 0,
+        marked_complete: updated,
+        already_complete: alreadyComplete,
+        not_found: notFound,
+        total: reqIds.length,
+    }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+function cmdMilestoneComplete(cwd, version, options, raw) {
+    if (!version) {
+        error('version required for milestone complete (e.g., v1.0)');
+    }
+    const roadmapPath = planningPaths(cwd).roadmap;
+    const reqPath = planningPaths(cwd).requirements;
+    const statePath = planningPaths(cwd).state;
+    const milestonesPath = node_path_1.default.join(cwd, '.planning', 'MILESTONES.md');
+    const archiveDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    const phasesDir = planningPaths(cwd).phases;
+    const today = new Date().toISOString().split('T')[0];
+    const milestoneName = options.name || version;
+    // Ensure archive directory exists
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    // Scope stats and accomplishments to only the phases belonging to the
+    // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+    // (same logic used by cmdPhasesList and other callers).
+    const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+    if (isDirInMilestone.missingExplicitVersion) {
+        error(`no phases found for milestone ${version} in ROADMAP.md`);
+    }
+    // Guard: prevent marking complete when ROADMAP still lists phases that have
+    // no directory on disk (disk_status: no_directory). This catches the case
+    // where the active milestone was erroneously marked complete before phases
+    // were even started. Only fires when STATE.md confirms the current milestone
+    // version matches what is being completed — no false positives on fresh
+    // projects where phases haven't been scaffolded yet.
+    // Pass --force to override this guard.
+    if (!options.force) {
+        try {
+            // Only guard when STATE.md's milestone field matches the version being completed.
+            let stateVersion = null;
+            try {
+                const stateRaw = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
+                if (stateRaw) {
+                    const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
+                    if (milestoneMatch)
+                        stateVersion = milestoneMatch[1].trim();
+                }
+            }
+            catch {
+                /* skip */
+            }
+            if (stateVersion && stateVersion === version) {
+                const { extractCurrentMilestone } = core;
+                const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+                const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
+                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+                const noDirectoryPhases = [];
+                let pm;
+                const phaseDirEntries = (() => {
+                    try {
+                        return node_fs_1.default
+                            .readdirSync(phasesDir, { withFileTypes: true })
+                            .filter((e) => e.isDirectory())
+                            .map((e) => e.name);
+                    }
+                    catch {
+                        return [];
+                    }
+                })();
+                while ((pm = phasePattern.exec(scopedContent)) !== null) {
+                    const phaseNum = pm[1];
+                    const normalized = normalizePhaseName(phaseNum);
+                    // A phase has disk_status: 'no_directory' when no phase directory
+                    // with a matching token exists on disk. Use the same phaseTokenMatches
+                    // helper that roadmap.analyze uses to avoid false positives on decimal
+                    // (2.1) and letter-suffix (12A) phase IDs.
+                    const hasDirectory = phaseDirEntries.some((d) => phaseTokenMatches(d, normalized));
+                    if (!hasDirectory) {
+                        noDirectoryPhases.push(phaseNum);
+                    }
+                }
+                if (noDirectoryPhases.length > 0) {
+                    error(`Cannot mark milestone complete: ROADMAP lists ${noDirectoryPhases.length} unstarted phase(s) ` +
+                        `(e.g. Phase ${noDirectoryPhases[0]}). Re-run with --force to override.`);
+                }
+            }
+        }
+        catch (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:'))
+                throw e;
+            // Phase scan failed or STATE version mismatch — allow completion to proceed.
+        }
+    }
+    // Gather stats from phases (scoped to current milestone only)
+    let phaseCount = 0;
+    let totalPlans = 0;
+    let totalTasks = 0;
+    const accomplishments = [];
+    try {
+        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+        const dirs = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+        for (const dir of dirs) {
+            if (!isDirInMilestone(dir))
+                continue;
+            phaseCount++;
+            const phaseFiles = node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, dir));
+            const plans = phaseFiles.filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+            const summaries = phaseFiles.filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+            totalPlans += plans.length;
+            // Extract one-liners from summaries
+            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 rawOneLiner = fm['one-liner'];
+                    const oneLiner = (typeof rawOneLiner === 'string' ? rawOneLiner : '') || extractOneLinerFromBody(content);
+                    if (oneLiner) {
+                        accomplishments.push(oneLiner);
+                    }
+                    // Count tasks: prefer **Tasks:** N from Performance section,
+                    // then <task XML tags, then ## Task N markdown headers
+                    const tasksFieldMatch = content.match(/\*\*Tasks:\*\*\s*(\d+)/);
+                    if (tasksFieldMatch) {
+                        totalTasks += parseInt(tasksFieldMatch[1], 10);
+                    }
+                    else {
+                        const xmlTaskMatches = content.match(/<task[\s>]/gi) || [];
+                        const mdTaskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+                        totalTasks += xmlTaskMatches.length || mdTaskMatches.length;
+                    }
+                }
+                catch {
+                    /* intentionally empty */
+                }
+            }
+        }
+    }
+    catch {
+        /* intentionally empty */
+    }
+    // Archive ROADMAP.md
+    if (node_fs_1.default.existsSync(roadmapPath)) {
+        const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent);
+    }
+    // Archive REQUIREMENTS.md
+    if (node_fs_1.default.existsSync(reqPath)) {
+        const reqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
+        const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+        (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
+    }
+    // Archive audit file if exists
+    const auditFile = node_path_1.default.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+    if (node_fs_1.default.existsSync(auditFile)) {
+        node_fs_1.default.renameSync(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+    }
+    // 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`;
+    if (node_fs_1.default.existsSync(milestonesPath)) {
+        const existing = node_fs_1.default.readFileSync(milestonesPath, 'utf-8');
+        if (!existing.trim()) {
+            // Empty file — treat like new
+            (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+        }
+        else {
+            // Insert after the header line(s) for reverse chronological order (newest first)
+            const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+            if (headerMatch) {
+                const header = headerMatch[1];
+                const rest = existing.slice(header.length);
+                (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, header + milestoneEntry + rest);
+            }
+            else {
+                // No recognizable header — prepend the entry
+                (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, milestoneEntry + existing);
+            }
+        }
+    }
+    else {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+    }
+    // Update STATE.md — keep frontmatter/body semantically aligned after closure
+    if (node_fs_1.default.existsSync(statePath)) {
+        let stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
+        stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
+        stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
+        stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null, `${version} milestone completed and archived`);
+        // Reset Current Position narrative so resume/progress flows do not keep
+        // pointing at closed-phase execution instructions.
+        const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+        const closedPositionBody = `\nPhase: Milestone ${version} complete\n` +
+            `Plan: —\n` +
+            `Status: Awaiting next milestone\n` +
+            `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
+        if (positionPattern.test(stateContent)) {
+            stateContent = stateContent.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+        }
+        else {
+            stateContent = `${stateContent.trimEnd()}\n\n## Current Position\n${closedPositionBody}`;
+        }
+        // Normalize operator-next-step tails that can become stale after close.
+        const operatorPattern = /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i;
+        if (operatorPattern.test(stateContent)) {
+            stateContent = stateContent.replace(operatorPattern, `$1\n- Start the next milestone with ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))}\n\n`);
+        }
+        else {
+            stateContent = `${stateContent.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))}\n`;
+        }
+        writeStateMd(statePath, stateContent, cwd);
+    }
+    // Archive phase directories if requested
+    let phasesArchived = false;
+    if (options.archivePhases) {
+        try {
+            const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
+            (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
+            const phaseEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+            const phaseDirNames = phaseEntries.filter((e) => e.isDirectory()).map((e) => e.name);
+            let archivedCount = 0;
+            for (const dir of phaseDirNames) {
+                if (!isDirInMilestone(dir))
+                    continue;
+                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
+                archivedCount++;
+            }
+            phasesArchived = archivedCount > 0;
+        }
+        catch {
+            /* intentionally empty */
+        }
+    }
+    const result = {
+        version,
+        name: milestoneName,
+        date: today,
+        phases: phaseCount,
+        plans: totalPlans,
+        tasks: totalTasks,
+        accomplishments,
+        archived: {
+            roadmap: node_fs_1.default.existsSync(node_path_1.default.join(archiveDir, `${version}-ROADMAP.md`)),
+            requirements: node_fs_1.default.existsSync(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+            audit: node_fs_1.default.existsSync(node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+            phases: phasesArchived,
+        },
+        milestones_updated: true,
+        state_updated: node_fs_1.default.existsSync(statePath),
+    };
+    output(result, raw);
+}
+function cmdPhasesClear(cwd, raw, args) {
+    const phasesDir = planningPaths(cwd).phases;
+    const confirm = Array.isArray(args) && args.includes('--confirm');
+    let cleared = 0;
+    if (node_fs_1.default.existsSync(phasesDir)) {
+        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory() && !/^999(?:\.|$)/.test(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.`);
+        }
+        try {
+            for (const entry of dirs) {
+                node_fs_1.default.rmSync(node_path_1.default.join(phasesDir, entry.name), { recursive: true, force: true });
+                cleared++;
+            }
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            error('Failed to clear phases directory: ' + message);
+        }
+    }
+    output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+module.exports = {
+    cmdRequirementsMarkComplete,
+    cmdMilestoneComplete,
+    cmdPhasesClear,
+};

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

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Model catalog — typed access to model-catalog.json.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/model-catalog.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ */
+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.nextTier = nextTier;
+exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
+exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
+exports.renderEffortForRuntime = renderEffortForRuntime;
+const node_path_1 = __importDefault(require("node:path"));
+// In .cts (CommonJS output) files, `require` is available as a global;
+// we use it directly to load JSON candidates.
+const _require = require;
+// Resolve model-catalog.json via a prioritised candidate list so the module
+// 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
+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;
+let _catalogLastErr = null;
+for (const _p of _catalogCandidates) {
+    try {
+        catalog = _require(_p);
+        break;
+    }
+    catch (e) {
+        const isMissingCandidate = (e && e.code === 'MODULE_NOT_FOUND' && String(e.message || '').includes(_p)) ||
+            (e && e.code === 'ENOENT');
+        if (!isMissingCandidate)
+            throw e;
+        _catalogLastErr = e;
+    }
+}
+if (!catalog) {
+    throw new Error(`model-catalog.json not found. Tried:\n${_catalogCandidates.map((p) => `  ${p}`).join('\n')}\nLast error: ${_catalogLastErr?.message}`);
+}
+// After the throw guard above, catalog is guaranteed non-null.
+const _catalog = catalog;
+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));
+exports.MODEL_PROFILES = Object.fromEntries(Object.entries(_catalog.agents).map(([agent, meta]) => [agent, {
+        quality: meta.golden,
+        balanced: meta.balanced,
+        budget: meta.budget,
+        adaptive: _catalog.adaptiveTierMap[meta.routingTier],
+    }]));
+exports.AGENT_TO_PHASE_TYPE = Object.fromEntries(Object.entries(_catalog.agents).map(([agent, meta]) => [agent, meta.phaseType]));
+exports.AGENT_DEFAULT_TIERS = Object.fromEntries(Object.entries(_catalog.agents).map(([agent, meta]) => [agent, meta.routingTier]));
+exports.MODEL_ALIAS_MAP = Object.fromEntries(Object.entries(_catalog.runtimeTierDefaults['claude'] ?? {}).map(([tier, entry]) => [tier, entry?.model]));
+exports.RUNTIME_PROFILE_MAP = (() => {
+    const result = {};
+    for (const [runtime, tiers] of Object.entries(_catalog.runtimeTierDefaults)) {
+        const filtered = {};
+        for (const [tier, entry] of Object.entries(tiers)) {
+            if (entry)
+                filtered[tier] = entry;
+        }
+        if (Object.keys(filtered).length > 0)
+            result[runtime] = filtered;
+    }
+    return result;
+})();
+exports.KNOWN_RUNTIMES = new Set(Object.keys(_catalog.runtimeTierDefaults));
+exports.RUNTIMES_WITH_REASONING_EFFORT = new Set(Object.entries(_catalog.runtimeTierDefaults)
+    .filter(([, tiers]) => Object.values(tiers).some((entry) => entry && entry.reasoning_effort))
+    .map(([runtime]) => runtime));
+exports.PROVIDER_PRESETS = _catalog.providerPresets ?? {};
+// 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).
+exports.KNOWN_PROVIDERS = new Set(Object.entries(exports.PROVIDER_PRESETS)
+    .filter(([, tiers]) => Object.values(tiers).some((budgets) => budgets && Object.values(budgets).some((entry) => entry && entry.model)))
+    .map(([name]) => name));
+function nextTier(currentTier) {
+    const order = ['light', 'standard', 'heavy'];
+    const idx = order.indexOf(String(currentTier));
+    if (idx === -1)
+        return null;
+    return order[Math.min(idx + 1, order.length - 1)];
+}
+function formatAgentToModelMapAsTable(agentToModelMap) {
+    const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
+    const modelWidth = Math.max('Model'.length, ...Object.values(agentToModelMap).map((m) => m.length));
+    const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
+    const header = ` ${'Agent'.padEnd(agentWidth)} │ ${'Model'.padEnd(modelWidth)}`;
+    let out = `${header}\n${sep}\n`;
+    for (const [agent, model] of Object.entries(agentToModelMap)) {
+        out += ` ${agent.padEnd(agentWidth)} │ ${model.padEnd(modelWidth)}\n`;
+    }
+    return out;
+}
+function getAgentToModelMapForProfile(normalizedProfile) {
+    const profile = exports.VALID_PROFILES.includes(normalizedProfile) ? normalizedProfile : 'balanced';
+    const out = {};
+    for (const [agent, profiles] of Object.entries(exports.MODEL_PROFILES)) {
+        const profilesRec = profiles;
+        out[agent] = profile === 'inherit' ? 'inherit' : (profilesRec[profile] ?? profiles.balanced);
+    }
+    return out;
+}
+exports.EFFORT_RENDERING = {
+    claude: {
+        param: 'output_config.effort',
+        channel: 'frontmatter',
+        supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
+        clamp(level) {
+            if (level === 'minimal')
+                return 'low';
+            return level;
+        },
+    },
+    codex: {
+        param: 'model_reasoning_effort',
+        channel: 'api',
+        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
+        clamp(level) {
+            if (level === 'max')
+                return 'xhigh';
+            return level;
+        },
+    },
+};
+/**
+ * Render a universal effort string for a specific runtime.
+ */
+function renderEffortForRuntime(runtime, universalEffort) {
+    const spec = exports.EFFORT_RENDERING[runtime];
+    if (!spec) {
+        return { value: universalEffort, param: null, channel: null };
+    }
+    return {
+        value: spec.clamp(universalEffort),
+        param: spec.param,
+        channel: spec.channel,
+    };
+}
+// ─── Fast mode propagation ───────────────────────────────────────────────────
+exports.RUNTIMES_WITH_FAST_MODE = new Set(['api']);

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

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * model-profiles — re-exports model catalog symbols consumed by callers that
+ * historically required bin/lib/model-profiles.cjs.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/model-profiles.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+const model_catalog_cjs_1 = require("./model-catalog.cjs");
+module.exports = {
+    MODEL_PROFILES: model_catalog_cjs_1.MODEL_PROFILES,
+    VALID_PROFILES: model_catalog_cjs_1.VALID_PROFILES,
+    AGENT_TO_PHASE_TYPE: model_catalog_cjs_1.AGENT_TO_PHASE_TYPE,
+    VALID_PHASE_TYPES: model_catalog_cjs_1.VALID_PHASE_TYPES,
+    AGENT_DEFAULT_TIERS: model_catalog_cjs_1.AGENT_DEFAULT_TIERS,
+    VALID_AGENT_TIERS: model_catalog_cjs_1.VALID_AGENT_TIERS,
+    nextTier: model_catalog_cjs_1.nextTier,
+    formatAgentToModelMapAsTable: model_catalog_cjs_1.formatAgentToModelMapAsTable,
+    getAgentToModelMapForProfile: model_catalog_cjs_1.getAgentToModelMapForProfile,
+    EFFORT_RENDERING: model_catalog_cjs_1.EFFORT_RENDERING,
+    renderEffortForRuntime: model_catalog_cjs_1.renderEffortForRuntime,
+    RUNTIMES_WITH_FAST_MODE: model_catalog_cjs_1.RUNTIMES_WITH_FAST_MODE,
+};

package/gsd-core/bin/lib/observability/event.cjs

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * DispatchEvent shape factory — issue #177 (ADR-0174 P1.3), extended in #178 (P1.4).
+ *
+ * Creates a structured event record for every Hub dispatch, used by
+ * DispatchLogger to emit stderr errors and opt-in file audit trails.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/observability/event.cjs collapsed to a TypeScript source of truth.
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * Shape:
+ *   traceId:       string           — UUID v4, generated per dispatch
+ *   parentTraceId: string|undefined — propagated from the caller when it is a canonical UUID v4
+ *                                     (RFC 4122); invalid values are silently coerced to undefined.
+ *   command:       string  — the dispatched verb
+ *   args?:         unknown — only present when includeArgs === true
+ *   result:        { kind: 'ok' | 'UnknownCommand' | 'InvalidArgs' | 'HandlerRefusal' | 'HandlerFailure', ...payload }
+ *   timestamp:     string  — ISO 8601
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeDispatchEvent = makeDispatchEvent;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Canonical UUID v4 regex (RFC 4122).
+ */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Returns true only when value is a canonical UUID v4 string.
+ */
+function isValidParentTraceId(value) {
+    return typeof value === 'string' && UUID_V4_REGEX.test(value);
+}
+/**
+ * Create a DispatchEvent.
+ */
+function makeDispatchEvent({ command, args, result, includeArgs = false, parentTraceId, }) {
+    const resolvedParentTraceId = isValidParentTraceId(parentTraceId) ? parentTraceId : undefined;
+    const event = {
+        traceId: (0, node_crypto_1.randomUUID)(),
+        parentTraceId: resolvedParentTraceId,
+        command: String(command),
+        result,
+        timestamp: new Date().toISOString(),
+    };
+    if (includeArgs && args !== undefined) {
+        event.args = args;
+    }
+    return Object.freeze(event);
+}