@therocketcode/gsd-core 1.4.0

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

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Check subcommand router — auto-mode, decision-coverage-plan, decision-coverage-verify.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/check-command-router.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict 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"));
+const node_child_process_1 = require("node:child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output, error, ERROR_REASON } = core;
+const decisions_cjs_1 = require("./decisions.cjs");
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function normalizePhrase(text) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    return String(text || '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const SOFT_PHRASE_MIN_WORDS = 6;
+function softPhrase(text) {
+    const words = normalizePhrase(text).split(' ').filter(Boolean);
+    if (words.length < SOFT_PHRASE_MIN_WORDS)
+        return '';
+    return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
+}
+function decisionMentioned(haystack, decision) {
+    if (!haystack)
+        return false;
+    if (new RegExp(`\\b${decision.id}\\b`).test(haystack))
+        return true;
+    const phrase = softPhrase(decision.text);
+    return phrase ? normalizePhrase(haystack).includes(phrase) : false;
+}
+function readIfExists(filePath) {
+    try {
+        return node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+function resolvePath(inputPath, projectDir) {
+    return node_path_1.default.isAbsolute(inputPath) ? inputPath : node_path_1.default.join(projectDir, inputPath);
+}
+function readWorkflowConfig(projectDir) {
+    const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        const wf = parsed['workflow'] || {};
+        return {
+            ...wf,
+            auto_advance: (wf['auto_advance'] ?? parsed['auto_advance']),
+            _auto_chain_active: (wf['_auto_chain_active'] ?? parsed['_auto_chain_active']),
+            context_coverage_gate: (wf['context_coverage_gate'] ?? parsed['context_coverage_gate']),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function cmdAutoMode(projectDir, raw) {
+    const workflow = readWorkflowConfig(projectDir);
+    const autoAdvance = Boolean(workflow.auto_advance ?? false);
+    const autoChainActive = Boolean(workflow._auto_chain_active ?? false);
+    let source = 'none';
+    if (autoChainActive && autoAdvance)
+        source = 'both';
+    else if (autoChainActive)
+        source = 'auto_chain';
+    else if (autoAdvance)
+        source = 'auto_advance';
+    output({
+        active: autoChainActive || autoAdvance,
+        source,
+        auto_chain_active: autoChainActive,
+        auto_advance: autoAdvance,
+    }, raw, undefined);
+}
+function gateEnabled(projectDir) {
+    const value = readWorkflowConfig(projectDir).context_coverage_gate;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const lower = value.toLowerCase();
+        if (lower === 'false' || lower === 'true')
+            return lower !== 'false';
+    }
+    return true;
+}
+function loadPlanContents(phaseDir) {
+    if (!node_fs_1.default.existsSync(phaseDir))
+        return [];
+    try {
+        return node_fs_1.default.readdirSync(phaseDir)
+            .filter((entry) => /-PLAN\.md$/.test(entry))
+            .map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)));
+    }
+    catch {
+        return [];
+    }
+}
+const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
+const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]*)?>([\s\S]*?)<\/(?:objective|tasks?|action)>/gi;
+function stripCommentsAndFences(text) {
+    return text
+        .replace(/<!--[\s\S]*?-->/g, ' ')
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/~~~[\s\S]*?~~~/g, ' ');
+}
+function extractYamlBlock(frontmatter, key) {
+    const match = frontmatter.match(new RegExp(`^${key}\\s*:(.*)$`, 'm'));
+    if (!match)
+        return '';
+    const startIdx = (match.index || 0) + match[0].length;
+    const rest = frontmatter.slice(startIdx + 1).split(/\r?\n/);
+    const block = [match[1] || ''];
+    for (const line of rest) {
+        if (line === '' || /^\s/.test(line))
+            block.push(line);
+        else
+            break;
+    }
+    return block.join('\n');
+}
+function extractXmlTagBodies(text) {
+    const parts = [];
+    for (const match of text.matchAll(XML_DECISION_TAGS_RE)) {
+        if (match[1])
+            parts.push(match[1]);
+    }
+    return parts.join('\n');
+}
+function extractPlanDesignatedSections(planContent) {
+    if (!planContent)
+        return '';
+    const cleaned = stripCommentsAndFences(planContent);
+    const fmMatch = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    const frontmatter = fmMatch ? fmMatch[1] : '';
+    const body = fmMatch ? fmMatch[2] : cleaned;
+    const parts = [];
+    for (const key of ['must_haves', 'truths', 'objective']) {
+        const block = extractYamlBlock(frontmatter, key);
+        if (block)
+            parts.push(block);
+    }
+    const bodyParts = [];
+    let inDesignated = false;
+    for (const line of body.split(/\r?\n/)) {
+        const heading = /^#{1,6}\s+/.test(line);
+        if (heading) {
+            inDesignated = DESIGNATED_HEADINGS_RE.test(line);
+            if (inDesignated)
+                bodyParts.push(line);
+            continue;
+        }
+        if (inDesignated)
+            bodyParts.push(line);
+    }
+    parts.push(bodyParts.join('\n'));
+    parts.push(extractXmlTagBodies(cleaned));
+    return parts.join('\n\n');
+}
+function buildPlanMessage(uncovered) {
+    if (uncovered.length === 0)
+        return 'All trackable CONTEXT.md decisions are covered by plans.';
+    return [
+        '## Decision Coverage Gap',
+        '',
+        `${uncovered.length} CONTEXT.md decision(s) are not covered by any plan:`,
+        '',
+        ...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+        '',
+        'Resolve by citing `D-NN:` in a relevant plan\'s `must_haves`/`truths` (or body),',
+        'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
+    ].join('\n');
+}
+function buildVerifyMessage(notHonored) {
+    if (notHonored.length === 0)
+        return 'All trackable CONTEXT.md decisions are honored by shipped artifacts.';
+    return [
+        '### Decision Coverage (warning)',
+        '',
+        `${notHonored.length} decision(s) not found in shipped artifacts:`,
+        '',
+        ...notHonored.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+        '',
+        'This is a soft warning - verification status is unchanged.',
+    ].join('\n');
+}
+function loadTrackableDecisions(contextPath) {
+    return (0, decisions_cjs_1.parseDecisions)(readIfExists(contextPath)).filter((decision) => decision.trackable);
+}
+function cmdDecisionCoveragePlan(projectDir, args, raw) {
+    const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
+    const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
+    if (!gateEnabled(projectDir)) {
+        output({ passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
+        return;
+    }
+    if (!contextPath || !node_fs_1.default.existsSync(contextPath)) {
+        output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
+        return;
+    }
+    const decisions = loadTrackableDecisions(contextPath);
+    if (decisions.length === 0) {
+        output({ passed: true, skipped: true, reason: 'no trackable decisions', total: 0, covered: 0, uncovered: [], message: 'No trackable decisions in CONTEXT.md.' }, raw, undefined);
+        return;
+    }
+    const sections = loadPlanContents(phaseDir).map(extractPlanDesignatedSections);
+    const uncovered = [];
+    let covered = 0;
+    for (const decision of decisions) {
+        if (sections.some((section) => decisionMentioned(section, decision)))
+            covered++;
+        else
+            uncovered.push({ id: decision.id, text: decision.text, category: decision.category });
+    }
+    output({
+        passed: uncovered.length === 0,
+        skipped: false,
+        total: decisions.length,
+        covered,
+        uncovered,
+        message: buildPlanMessage(uncovered),
+    }, raw, undefined);
+}
+function recentCommitMessages(projectDir) {
+    try {
+        return (0, node_child_process_1.execFileSync)('git', ['log', '-n', '200', '--pretty=%s%n%b'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            maxBuffer: 4 * 1024 * 1024,
+            windowsHide: true,
+        });
+    }
+    catch {
+        return '';
+    }
+}
+function isInsideRoot(candidatePath, rootDir) {
+    const root = node_path_1.default.resolve(rootDir);
+    const target = node_path_1.default.resolve(root, candidatePath);
+    return target === root || target.startsWith(`${root}${node_path_1.default.sep}`);
+}
+function readModifiedFilesContent(projectDir, summaries) {
+    const out = [];
+    let total = 0;
+    for (const summary of summaries) {
+        if (!summary)
+            continue;
+        for (const blockMatch of summary.matchAll(/files_modified:\s*\n((?:[ \t]*-\s+.+\n?)+)/g)) {
+            const files = [...(blockMatch[1] || '').matchAll(/-\s+(.+)/g)]
+                .map((match) => match[1].trim().replace(/^["']|["']$/g, ''));
+            for (const file of files) {
+                if (total >= 50)
+                    break;
+                if (!file || !isInsideRoot(file, projectDir))
+                    continue;
+                const raw = readIfExists(resolvePath(file, projectDir));
+                out.push(raw.length > 256 * 1024 ? raw.slice(0, 256 * 1024) : raw);
+                total++;
+            }
+            if (total >= 50)
+                break;
+        }
+        if (total >= 50)
+            break;
+    }
+    return out.join('\n\n');
+}
+function cmdDecisionCoverageVerify(projectDir, args, raw) {
+    const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
+    const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
+    if (!gateEnabled(projectDir)) {
+        output({ skipped: true, blocking: false, reason: 'workflow.context_coverage_gate is false', total: 0, honored: 0, not_honored: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
+        return;
+    }
+    if (!contextPath || !node_fs_1.default.existsSync(contextPath)) {
+        output({ skipped: true, blocking: false, reason: 'CONTEXT.md missing', total: 0, honored: 0, not_honored: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
+        return;
+    }
+    const decisions = loadTrackableDecisions(contextPath);
+    if (decisions.length === 0) {
+        output({ skipped: true, blocking: false, reason: 'no trackable decisions', total: 0, honored: 0, not_honored: [], message: 'No trackable decisions in CONTEXT.md.' }, raw, undefined);
+        return;
+    }
+    const planContents = loadPlanContents(phaseDir);
+    const summaryParts = node_fs_1.default.existsSync(phaseDir)
+        ? node_fs_1.default.readdirSync(phaseDir).filter((entry) => /-SUMMARY\.md$/.test(entry)).map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)))
+        : [];
+    const haystack = [
+        planContents.join('\n\n'),
+        summaryParts.join('\n\n'),
+        readModifiedFilesContent(projectDir, summaryParts),
+        recentCommitMessages(projectDir),
+    ].join('\n\n');
+    const notHonored = [];
+    let honored = 0;
+    for (const decision of decisions) {
+        if (decisionMentioned(haystack, decision))
+            honored++;
+        else
+            notHonored.push({ id: decision.id, text: decision.text, category: decision.category });
+    }
+    output({
+        skipped: false,
+        blocking: false,
+        total: decisions.length,
+        honored,
+        not_honored: notHonored,
+        message: buildVerifyMessage(notHonored),
+    }, raw, undefined);
+}
+function routeCheckCommand({ args, cwd, raw }) {
+    const subcommand = args[1];
+    if (subcommand === 'auto-mode') {
+        cmdAutoMode(cwd, raw);
+        return;
+    }
+    if (subcommand === 'decision-coverage-plan') {
+        cmdDecisionCoveragePlan(cwd, args, raw);
+        return;
+    }
+    if (subcommand === 'decision-coverage-verify') {
+        cmdDecisionCoverageVerify(cwd, args, raw);
+        return;
+    }
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+}
+module.exports = {
+    routeCheckCommand,
+    decisionMentioned,
+    extractPlanDesignatedSections,
+};

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

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * CJS Command Router Adapter Module
+ *
+ * Compatibility routing for gsd-tools.cjs command families. Uses generated
+ * command metadata for availability and small family-local argument shapers for
+ * CJS handler calls.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/cjs-command-router-adapter.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+const { createHub, ERROR_KINDS } = commandRoutingHub;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeCjsCommandFamily({ args, subcommands, handlers, defaultSubcommand, unsupported = {}, unknownMessage, error, cwd, raw, }) {
+    routeHubCommandFamily({
+        family: '__legacy_cjs_family__',
+        args,
+        subcommands,
+        handlers,
+        defaultSubcommand,
+        unsupported,
+        unknownMessage,
+        error,
+        cwd,
+        raw,
+    });
+}
+/**
+ * Hub-backed family router adapter.
+ *
+ * Deepens the command-topology seam by routing family handlers through
+ * CommandRoutingHub's typed Result contract instead of ad-hoc per-router
+ * lookup + error handling branches.
+ */
+function routeHubCommandFamily({ family, args, subcommands, handlers, defaultSubcommand, unsupported = {}, unknownMessage, error, cwd, raw, }) {
+    const subcommand = args[1] || defaultSubcommand;
+    if (subcommand && unsupported[subcommand]) {
+        error(unsupported[subcommand]);
+        return;
+    }
+    const available = subcommands.filter((s) => !unsupported[s]);
+    const registryHandlers = Object.fromEntries(Object.entries(handlers).map(([name, handler]) => [
+        name,
+        () => {
+            const result = handler();
+            if (result && typeof result === 'object' && Object.prototype.hasOwnProperty.call(result, 'ok')) {
+                return result;
+            }
+            return { ok: true, data: null };
+        },
+    ]));
+    const hub = createHub({
+        cjsRegistry: { [family]: registryHandlers },
+        manifest: { [family]: available },
+    });
+    const result = hub.dispatch({
+        family,
+        subcommand,
+        args: args.slice(2),
+        cwd,
+        raw,
+    });
+    if (result.ok)
+        return;
+    if (result.kind === ERROR_KINDS.UnknownCommand) {
+        error(unknownMessage(subcommand ?? '', available));
+        return;
+    }
+    if (result.kind === ERROR_KINDS.InvalidArgs || result.kind === ERROR_KINDS.HandlerRefusal) {
+        error(result.reason);
+        return;
+    }
+    error(result.message);
+}
+module.exports = {
+    routeCjsCommandFamily,
+    routeHubCommandFamily,
+};

package/gsd-core/bin/lib/cli-exit.cjs

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Error carrying a process exit code. CLI logic throws this instead of calling
+ * process.exit() (banned by n/no-process-exit); runMain() translates it into
+ * process.exitCode at the entrypoint.
+ */
+class ExitError extends Error {
+    code;
+    hasUserMessage;
+    constructor(code = 1, message) {
+        super(message === undefined ? `process exit ${code}` : message);
+        this.name = 'ExitError';
+        this.code = code;
+        this.hasUserMessage = message !== undefined;
+    }
+}
+/**
+ * Run a CLI main and translate its outcome into process.exitCode (never
+ * process.exit, so n/no-process-exit stays satisfied; output flushes and
+ * process.on('exit') cleanup still fires). main may be sync or async:
+ *   number return -> process.exitCode = it
+ *   thrown ExitError -> process.exitCode = err.code (+ stderr err.message if hasUserMessage && code!=0)
+ *   other throw -> stderr stack + process.exitCode = 1
+ */
+function runMain(main) {
+    Promise.resolve()
+        .then(() => main())
+        .then((code) => { if (typeof code === 'number')
+        process.exitCode = code; })
+        .catch((err) => {
+        if (err instanceof ExitError) {
+            if (err.hasUserMessage && err.code !== 0)
+                process.stderr.write(`${err.message}\n`);
+            process.exitCode = err.code;
+            return;
+        }
+        const e = err;
+        process.stderr.write(`${e && e.stack ? e.stack : String(err)}\n`);
+        process.exitCode = 1;
+    });
+}
+module.exports = { ExitError, runMain };

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

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Deterministic clock seam for lock modules (ADR-457 build-at-publish: the
+ * hand-written bin/lib/clock.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * Production code uses `realClock` (the default). Test code passes in a
+ * `makeFakeClock()` instance to drive lock timing without real wall-clock
+ * waits or Atomics.wait calls.
+ *
+ * Both methods in realClock use exactly the same system primitives that
+ * acquireStateLock and withPlanningLock used inline before the seam was
+ * introduced:
+ *   - now()   → Date.now()
+ *   - sleep() → Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realClock = void 0;
+// Module-level Atomics.wait buffer reused across every realClock.sleep() call.
+// The buffer value is always 0 (never written), so reuse is semantically
+// identical to allocating a fresh buffer each time.
+const _realSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Parse GSD_NOW_MS to a valid pinned epoch millisecond value, or return null.
+ *
+ * Accepts ONLY strict decimal integer strings within JS Date bounds
+ * (abs(ms) <= 8.64e15).  Rejects empty strings, whitespace-only, floats
+ * ('12.5'), scientific notation ('1e30'), and out-of-range values.
+ *
+ * Returns null (fall back to Date.now()) for any invalid or absent input.
+ * Returns null when GSD_TEST_MODE is not set.
+ */
+function _pinnedNowMs() {
+    if (!process.env.GSD_TEST_MODE)
+        return null;
+    const raw = process.env.GSD_NOW_MS;
+    if (typeof raw !== 'string')
+        return null;
+    const t = raw.trim();
+    if (!/^-?\d+$/.test(t))
+        return null; // reject '', 'abc', '1e30', '12.5'
+    const ms = Number(t);
+    if (!Number.isFinite(ms) || Math.abs(ms) > 8.64e15)
+        return null; // Date-valid bounds
+    return ms;
+}
+exports.realClock = {
+    /**
+     * Return current epoch milliseconds.
+     *
+     * When both GSD_TEST_MODE and GSD_NOW_MS are set (subprocess time-pin adapter,
+     * issue #474), returns the pinned millisecond value so all date-stamping in the
+     * subprocess SUT is deterministic.  In production, falls back to Date.now().
+     *
+     * Only strict decimal integer strings within JS Date bounds are accepted as pins.
+     * Any other value (empty string, float, scientific notation, out-of-range) falls
+     * back to Date.now() to prevent RangeError from new Date(ms).toISOString().
+     */
+    now() {
+        const pinned = _pinnedNowMs();
+        if (pinned !== null)
+            return pinned;
+        return Date.now();
+    },
+    /**
+     * Return the current instant as an ISO 8601 string (UTC).
+     * Uses this.now() so the subprocess time-pin adapter is honoured.
+     *
+     * @returns e.g. "2020-06-15T12:00:00.000Z"
+     */
+    nowIso() {
+        return new Date(this.now()).toISOString();
+    },
+    /**
+     * Return today's date as a YYYY-MM-DD string (UTC calendar day).
+     * Uses this.now() so the subprocess time-pin adapter is honoured.
+     *
+     * @returns e.g. "2020-06-15"
+     */
+    today() {
+        return this.nowIso().split('T')[0];
+    },
+    /**
+     * Synchronous sleep via Atomics.wait.
+     * This is the identical primitive acquireStateLock and withPlanningLock used
+     * inline before the seam.  Atomics.wait on a shared buffer that is never
+     * notified times out after exactly `ms` milliseconds without spinning the CPU.
+     *
+     * @param ms - milliseconds to sleep
+     */
+    sleep(ms) {
+        Atomics.wait(_realSleepBuf, 0, 0, ms);
+    },
+};

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

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Skill cluster definitions for the runtime surface module (ADR-457
+ * build-at-publish: the hand-written bin/lib/clusters.cjs collapsed to a
+ * TypeScript source of truth). Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ *
+ * Each cluster is a named group of skill stems. Clusters are used by /gsd:surface
+ * to enable/disable a cohesive group of skills without reinstall.
+ *
+ * Cluster membership may overlap (a skill can live in two clusters). The union
+ * of all clusters should cover every installed skill stem; uncategorized stems
+ * are flagged by surface-clusters.test.cjs.
+ *
+ * Source: docs/research/2026-05-12-skill-surface-budget.md §3.2 (verified
+ * against commands/gsd/ listing in surface-clusters.test.cjs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTERS = void 0;
+exports.allClusteredSkills = allClusteredSkills;
+exports.CLUSTERS = Object.freeze({
+    core_loop: Object.freeze([
+        'new-project',
+        'discuss-phase',
+        'plan-phase',
+        'execute-phase',
+        'help',
+        'update',
+    ]),
+    audit_review: Object.freeze([
+        'code-review',
+        'review',
+        'audit-fix',
+        'audit-milestone',
+        'audit-uat',
+        'verify-work',
+        'validate-phase',
+        'plan-review-convergence',
+        'eval-review',
+        'add-tests',
+        'secure-phase',
+    ]),
+    milestone: Object.freeze([
+        'new-milestone',
+        'complete-milestone',
+        'milestone-summary',
+        'health',
+    ]),
+    research_ideate: Object.freeze([
+        'sketch',
+        'spike',
+        'forensics',
+        'explore',
+        'graphify',
+        'ns-ideate',
+    ]),
+    workspace_state: Object.freeze([
+        'pause-work',
+        'resume-work',
+        'workspace',
+        'workstreams',
+        'thread',
+        'capture',
+        'inbox',
+    ]),
+    docs: Object.freeze([
+        'docs-update',
+        'ingest-docs',
+    ]),
+    ui: Object.freeze([
+        'ui-phase',
+        'ui-review',
+    ]),
+    ai_eval: Object.freeze([
+        'ai-integration-phase',
+        'eval-review',
+    ]),
+    ns_meta: Object.freeze([
+        'ns-context',
+        'ns-ideate',
+        'ns-manage',
+        'ns-project',
+        'ns-review',
+        'ns-workflow',
+    ]),
+    utility: Object.freeze([
+        'health',
+        'stats',
+        'settings',
+        'cleanup',
+        'pr-branch',
+        'ship',
+        'undo',
+        'fast',
+        'quick',
+        'autonomous',
+        'config',
+        'progress',
+        'phase',
+        'review',
+        'update',
+        'help',
+        'code-review',
+        'import',
+        'manager',
+        'map-codebase',
+        'profile-user',
+        'spec-phase',
+        'model-domain',
+        'recommend-architecture',
+        'discover-product',
+        'testing-strategy',
+        'ultraplan-phase',
+        'mvp-phase',
+        'execute-phase',
+        'review-backlog',
+        'debug',
+        'extract-learnings',
+        'surface',
+    ]),
+});
+/**
+ * Build a Set of all skill stems covered by at least one cluster.
+ */
+function allClusteredSkills() {
+    const result = new Set();
+    for (const skills of Object.values(exports.CLUSTERS)) {
+        for (const s of skills)
+            result.add(s);
+    }
+    return result;
+}