@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

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

@@ -157,10 +157,44 @@ function computeClosure(base, manifest) {
     }
     return closed;
 }
+/**
+ * Compute the capability skills to add for a given profile mode from the registry.
+ * Returns an array of skill stems contributed by capabilities whose profileMembership
+ * includes the given mode.  Guards against prototype pollution and malformed registry.
+ */
+function _capabilitySkillsForMode(mode, registry) {
+    const BANNED = ['__proto__', 'constructor', 'prototype'];
+    const clusters = registry.capabilityClusters;
+    const membership = registry.profileMembership;
+    if (!clusters || typeof clusters !== 'object' || !membership || typeof membership !== 'object') {
+        return [];
+    }
+    const result = [];
+    for (const capId of Object.keys(clusters)) {
+        if (BANNED.includes(capId))
+            continue;
+        const mem = membership[capId];
+        if (!mem || typeof mem !== 'object')
+            continue;
+        const profiles = mem.profiles;
+        if (!Array.isArray(profiles))
+            continue;
+        if (!profiles.includes(mode))
+            continue;
+        const skills = clusters[capId];
+        if (!Array.isArray(skills))
+            continue;
+        for (const s of skills) {
+            if (typeof s === 'string' && s.length > 0)
+                result.push(s);
+        }
+    }
+    return result;
+}
 /**
  * Resolve a profile (or composed profiles) to a typed result object.
  */
-function resolveProfile({ modes, manifest, _profilesOverride } = {}) {
+function resolveProfile({ modes, manifest, _profilesOverride, registry } = {}) {
     const profiles = _profilesOverride || PROFILES;
     const activeModes = (modes && modes.length > 0) ? modes : ['full'];
     const normalizedModes = activeModes
@@ -185,7 +219,11 @@ function resolveProfile({ modes, manifest, _profilesOverride } = {}) {
             // This profile is full — sentinel short-circuit
             return { name: 'full', skills: '*', agents: new Set() };
         }
-        const closure = computeClosure(base, man);
+        // ADR-857 phase 4c: union capability skills for this mode BEFORE closure so
+        // their requires: chains expand too.
+        const capSkills = registry ? _capabilitySkillsForMode(mode, registry) : [];
+        const baseWithCap = [...base, ...capSkills];
+        const closure = computeClosure(baseWithCap, man);
         for (const s of closure)
             unionSkills.add(s);
     }
@@ -318,9 +356,103 @@ function stageAgentsForProfile(srcAgentsDir, resolvedProfile) {
     ensureExitCleanup();
     return stageDir;
 }
-function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix) {
+/**
+ * Build the namespace router → concrete sub-skill mapping (#69). The
+ * authoritative source is each `ns-*.md` router file's `requires:` frontmatter
+ * list. A concrete skill may be routed by more than one router (e.g. spec-phase
+ * is shared by ns-workflow and ns-ideate); it is nested — and physically
+ * duplicated — under every owning router.
+ */
+function buildNamespaceBundleMap(srcCommandsDir) {
+    const routerStems = new Set();
+    const routerChildren = new Map();
+    const childToRouters = new Map();
+    if (!node_fs_1.default.existsSync(srcCommandsDir)) {
+        return { routerStems, routerChildren, childToRouters };
+    }
+    for (const entry of node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (!entry.name.startsWith('ns-'))
+            continue;
+        const stem = entry.name.slice(0, -3);
+        let children = [];
+        try {
+            children = parseRequires(node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8'));
+        }
+        catch {
+            children = [];
+        }
+        routerStems.add(stem);
+        routerChildren.set(stem, children);
+        for (const child of children) {
+            const owners = childToRouters.get(child) || [];
+            owners.push(stem);
+            childToRouters.set(child, owners);
+        }
+    }
+    return { routerStems, routerChildren, childToRouters };
+}
+/**
+ * Rewrite a converted namespace-router SKILL.md so its routing table points at
+ * nested sub-skill files instead of bare Skill-tool names (#69). Each table row
+ * whose final cell carries a `gsd-<stem>` token (optionally with `--flag`
+ * suffixes) is rewritten to `Read \`skills/<stem>/SKILL.md\`` (flags preserved
+ * as a note), the `Invoke` column header becomes `Read`, and the
+ * "Invoke … using the Skill tool" trailer becomes a file-read instruction.
+ * Only lines beginning with a table pipe are touched, so the `|` inside the
+ * `description:` frontmatter field is never matched.
+ */
+function transformRouterBodyToNested(converted) {
+    const lines = converted.split('\n');
+    const out = lines.map((line) => {
+        if (/Invoke the matched skill directly using the Skill tool\./.test(line)) {
+            return line.replace(/Invoke the matched skill directly using the Skill tool\./, "Read the matched sub-skill's SKILL.md and follow its instructions. The `skills/<name>/SKILL.md` paths in the right column are relative to this skill's own directory.");
+        }
+        if (!/^\s*\|/.test(line))
+            return line;
+        if (/^\s*\|[\s:|-]+\|\s*$/.test(line))
+            return line;
+        if (/\|\s*Invoke\s*\|/.test(line)) {
+            return line.replace(/\|\s*Invoke\s*\|/, '| Read |');
+        }
+        const cells = line.split('|');
+        const lastIdx = cells.length - 2;
+        if (lastIdx < 1)
+            return line;
+        const cell = cells[lastIdx];
+        const m = cell.match(/gsd-([a-z0-9-]+)((?:\s+--[a-z0-9-]+)*)/i);
+        if (!m)
+            return line;
+        const stem = m[1];
+        const flags = m[2].trim();
+        cells[lastIdx] = flags
+            ? ` Read \`skills/${stem}/SKILL.md\` (${flags}) `
+            : ` Read \`skills/${stem}/SKILL.md\` `;
+        return cells.join('|');
+    });
+    return out.join('\n');
+}
+function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix, nested = false) {
     if (!node_fs_1.default.existsSync(srcCommandsDir))
         return srcCommandsDir;
+    // Nesting applies to the `full` install AND to any surface whose skill set
+    // still contains every namespace router (a full/reset surface). It must NOT
+    // depend on the `'*'` sentinel alone: applySurface() materializes `full` into
+    // a concrete Set, so a sentinel-only gate would re-flatten the layout on every
+    // surface apply/reset (#69 adversarial-review finding). A partial surface that
+    // drops a whole router cluster falls back to flat automatically.
+    const bundles = nested ? buildNamespaceBundleMap(srcCommandsDir) : null;
+    let doNest = false;
+    if (nested && bundles && bundles.routerStems.size > 0) {
+        if (resolvedProfile.skills === '*') {
+            doNest = true;
+        }
+        else {
+            const present = resolvedProfile.skills;
+            doNest = [...bundles.routerStems].every((r) => present.has(r));
+        }
+    }
     const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-skills-'));
     try {
         const entries = node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true });
@@ -335,6 +467,27 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
             const skillName = `${prefix}${stem}`;
             const converted = converter(content, skillName);
+            if (doNest && bundles.routerStems.has(stem)) {
+                // Router skill: rewrite its routing table to the nested Read pattern and
+                // emit it as the single top-level bundle entry.
+                const destDir = node_path_1.default.join(stageDir, skillName);
+                node_fs_1.default.mkdirSync(destDir, { recursive: true });
+                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), transformRouterBodyToNested(converted));
+                continue;
+            }
+            if (doNest && bundles.childToRouters.has(stem)) {
+                // Concrete skill routed by one or more namespace routers: nest a copy
+                // under each owning router's skills/ subdir so it drops out of the
+                // top-level eager listing while staying readable by file path (#69).
+                for (const routerStem of bundles.childToRouters.get(stem)) {
+                    const destDir = node_path_1.default.join(stageDir, `${prefix}${routerStem}`, 'skills', stem);
+                    node_fs_1.default.mkdirSync(destDir, { recursive: true });
+                    node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
+                }
+                continue;
+            }
+            // Flat top-level skill (default behaviour; also the unrouted fallback when
+            // nesting is active).
             const destDir = node_path_1.default.join(stageDir, skillName);
             node_fs_1.default.mkdirSync(destDir, { recursive: true });
             node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
@@ -575,6 +728,7 @@ module.exports = {
     readActiveProfile,
     writeActiveProfile,
     // Shared internals
+    parseRequires,
     cleanupStagedSkills,
     // Back-compat / deprecated
     MINIMAL_SKILL_ALLOWLIST,

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

@@ -0,0 +1,116 @@
+'use strict';
+/**
+ * Intel command router — CLI subcommand dispatcher for `gsd-tools intel`.
+ *
+ * ADR-959 (phase 4d-impl-4): intel command family cutover — last first-party
+ * command cutover in the initial capability rollout.
+ * Extracted from the hardcoded `case 'intel':` arm in gsd-tools.cjs.
+ * Behaviour is preserved byte-for-behaviour from the prior inline case;
+ * the dispatch path now flows: default → dispatchCapabilityCommand →
+ * require(intel-command-router.cjs) → routeIntelCommand.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to the existing
+ * host routers. No new handler/arg convention; the capability registry
+ * discovers this router by name.
+ *
+ * Arg indexing (preserved exactly from the original case):
+ *   args[0] = 'intel'       (family — matched by dispatchCapabilityCommand)
+ *   args[1] = subcommand    (query | status | diff | snapshot | patch-meta |
+ *                            validate | extract-exports | update | api-surface)
+ *   args[2] = term (query) | filePath (patch-meta | extract-exports)
+ *
+ * Notable: the `status` subcommand applies a `timeAgo` transform on
+ * `status.files[*].updated_at` in non-raw mode — preserved exactly.
+ *
+ * Test seams: pass `_intel` to inject a mock intel module; pass `_core` to
+ * inject a mock core module (captures `output` calls and provides a
+ * deterministic `timeAgo` without writing to real stdout).  The `_`-prefix
+ * follows the repo's established seam convention (see audit-command-router.cts
+ * for the `_core` seam pattern).  Production callers omit both.
+ *
+ * Note on `error(); return` pairs: in production `error()` calls
+ * `process.exit(1)` so the `return` is an equivalent no-op halt. The pairs
+ * are kept for lint/control-flow clarity; they do NOT change behaviour.
+ *
+ * Lazy require: intel.cjs is required INSIDE the route function so it is
+ * only loaded when an intel command is actually dispatched (preserves
+ * equivalence with the old inline case arm which required it at the top of
+ * the case block).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+const { ERROR_REASON } = io;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeIntelCommand({ args, cwd, raw, error, _intel, _core }) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const intel = _intel ?? require('./intel.cjs');
+    const c = _core ?? core;
+    const subcommand = args[1];
+    if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) {
+            error('Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE);
+            return;
+        }
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelQuery(term, planningDir), raw);
+    }
+    else if (subcommand === 'status') {
+        const planningDir = path.join(cwd, '.planning');
+        const status = intel.intelStatus(planningDir);
+        if (!raw && status.files) {
+            for (const file of Object.values(status.files)) {
+                if (file.updated_at) {
+                    file.updated_at = c.timeAgo(new Date(file.updated_at));
+                }
+            }
+        }
+        c.output(status, raw);
+    }
+    else if (subcommand === 'diff') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelDiff(planningDir), raw);
+    }
+    else if (subcommand === 'snapshot') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelSnapshot(planningDir), raw);
+    }
+    else if (subcommand === 'patch-meta') {
+        const filePath = args[2];
+        if (!filePath) {
+            error('Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
+            return;
+        }
+        c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
+    }
+    else if (subcommand === 'validate') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelValidate(planningDir), raw);
+    }
+    else if (subcommand === 'extract-exports') {
+        const filePath = args[2];
+        if (!filePath) {
+            error('Usage: gsd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE);
+            return;
+        }
+        c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw);
+    }
+    else if (subcommand === 'update') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelUpdate(planningDir), raw);
+    }
+    else if (subcommand === 'api-surface') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelApiSurface(planningDir), raw);
+    }
+    else {
+        error('Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}
+module.exports = {
+    routeIntelCommand,
+};

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

@@ -149,7 +149,7 @@ function matchesInValue(value, lowerTerm) {
 }
 /**
  * Query intel files for a search term.
- * Searches across all JSON intel files (keys and values) and arch.md (text lines).
+ * Searches across all JSON intel files in INTEL_FILES (keys and values), including arch-decisions.json (parsed as JSON, not as text).
  */
 function intelQuery(term, planningDir) {
     if (!isIntelEnabled(planningDir))
@@ -328,7 +328,7 @@ function intelValidate(planningDir) {
         }
         // Validate entries are objects with expected fields
         if (data.entries && typeof data.entries === 'object') {
-            // files.json: check exports are actual symbol names (no spaces)
+            // file-roles.json (INTEL_FILES key 'files'): check exports are actual symbol names (no spaces)
             if (key === 'files') {
                 for (const [entryPath, entry] of Object.entries(data.entries)) {
                     const entryObj = entry;
@@ -348,7 +348,7 @@ function intelValidate(planningDir) {
                     }
                 }
             }
-            // deps.json: check entries have version, type, used_by
+            // dependency-graph.json (INTEL_FILES key 'deps'): check entries have version, type, used_by
             if (key === 'deps') {
                 for (const [depName, entry] of Object.entries(data.entries)) {
                     const entryObj = entry;

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

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * CLI I/O primitives — output(), error(), ERROR_REASON, JSON-error mode,
+ * and the temp-file helpers that output() depends on.
+ *
+ * Extracted from core.cts (ADR-857 rollout phase 1 / issue #859).
+ * The hand-written bodies are preserved byte-for-behaviour; only the module
+ * boundary moved. core.cts re-exports every symbol here under its own
+ * `export =` object so existing consumers are unaffected.
+ *
+ * New imports should pull I/O primitives from io.cjs directly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Temp-file helpers (needed by output()) ──────────────────────────────────
+/**
+ * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
+ * Created on first use. Keeps GSD temp files isolated from the system
+ * temp directory so reap scans only GSD files (#1975).
+ */
+const GSD_TEMP_DIR = node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd');
+function ensureGsdTempDir() {
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(GSD_TEMP_DIR);
+}
+/**
+ * Remove stale gsd-* temp files/dirs older than maxAgeMs (default: 5 minutes).
+ * Runs opportunistically before each new temp file write to prevent unbounded accumulation.
+ * @param prefix - filename prefix to match (e.g., 'gsd-')
+ * @param opts
+ * @param opts.maxAgeMs - max age in ms before removal (default: 5 min)
+ * @param opts.dirsOnly - if true, only remove directories (default: false)
+ */
+function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnly = false } = {}) {
+    try {
+        ensureGsdTempDir();
+        const now = Date.now();
+        const entries = node_fs_1.default.readdirSync(GSD_TEMP_DIR);
+        for (const entry of entries) {
+            if (!entry.startsWith(prefix))
+                continue;
+            const fullPath = node_path_1.default.join(GSD_TEMP_DIR, entry);
+            try {
+                const stat = node_fs_1.default.statSync(fullPath);
+                if (now - stat.mtimeMs > maxAgeMs) {
+                    if (stat.isDirectory()) {
+                        node_fs_1.default.rmSync(fullPath, { recursive: true, force: true });
+                    }
+                    else if (!dirsOnly) {
+                        node_fs_1.default.unlinkSync(fullPath);
+                    }
+                }
+            }
+            catch {
+                // File may have been removed between readdir and stat — ignore
+            }
+        }
+    }
+    catch {
+        // Non-critical — don't let cleanup failures break output
+    }
+}
+// ─── Output helpers ───────────────────────────────────────────────────────────
+/**
+ * Transient write errnos. When stdout/stderr is a NON-BLOCKING pipe — as it is
+ * under the parallel `node --test` runner on Linux CI — a full pipe buffer makes
+ * `fs.writeSync` throw EAGAIN, and a signal can interrupt it with EINTR. Both
+ * clear on retry once the reader drains. This is the same transient class the
+ * STATE.md lock path already retries (ACQUIRE_LOCK_RETRY_ERRNOS, #3776); #1008.
+ */
+const WRITE_RETRY_ERRNOS = new Set(['EAGAIN', 'EINTR']);
+// Bounded so a pathological never-draining fd cannot spin forever. Each retry
+// yields the thread for ~1ms via Atomics.wait (the project's sync-sleep idiom —
+// see clock.cts realClock.sleep), so the cap is ~1s of total back-pressure wait.
+const WRITE_MAX_RETRIES = 1000;
+const WRITE_RETRY_BACKOFF_MS = 1;
+// Sleep buffer is lazily allocated on the FIRST back-pressure retry (rare — only
+// when a non-blocking pipe is full) and then reused. Keeping it out of module
+// load costs nothing on the overwhelmingly common no-retry path and avoids
+// perturbing SharedArrayBuffer-allocation accounting in other modules (perf-316).
+let _writeSleepBuf = null;
+function backoffOnce() {
+    if (_writeSleepBuf === null)
+        _writeSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(_writeSleepBuf, 0, 0, WRITE_RETRY_BACKOFF_MS);
+}
+/**
+ * Write the entire payload to `fd`, tolerating non-blocking-pipe back-pressure.
+ *
+ * `fs.writeSync` does NOT block on a non-blocking pipe: a full buffer throws
+ * EAGAIN, and a partially-drained buffer returns a SHORT count (fewer bytes than
+ * requested). The previous bare `fs.writeSync(fd, string)` call assumed it always
+ * blocked until the kernel accepted every byte — false under load, which both
+ * threw spurious errors and risked silently truncating output (#1008).
+ *
+ * This loops on short counts (advancing the offset) and retries EAGAIN/EINTR with
+ * a brief Atomics.wait backoff that yields the thread so the reader can drain.
+ * Non-transient errors (e.g. EPIPE) propagate unchanged.
+ */
+function writeAllSync(fd, data) {
+    const buf = Buffer.from(data, 'utf8');
+    let offset = 0;
+    let retries = 0;
+    while (offset < buf.length) {
+        try {
+            offset += node_fs_1.default.writeSync(fd, buf, offset, buf.length - offset);
+        }
+        catch (err) {
+            const code = err.code ?? '';
+            if (WRITE_RETRY_ERRNOS.has(code) && retries < WRITE_MAX_RETRIES) {
+                retries += 1;
+                backoffOnce();
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+function output(result, raw, rawValue) {
+    let data;
+    if (raw && rawValue !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        data = String(rawValue);
+    }
+    else {
+        const json = JSON.stringify(result, null, 2);
+        // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
+        // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
+        if (json.length > 50000) {
+            reapStaleTempFiles();
+            ensureGsdTempDir();
+            const tmpPath = node_path_1.default.join(GSD_TEMP_DIR, `gsd-${Date.now()}.json`);
+            (0, shell_command_projection_cjs_1.platformWriteSync)(tmpPath, json);
+            data = '@file:' + tmpPath;
+        }
+        else {
+            data = json;
+        }
+    }
+    // process.stdout.write() is async when stdout is a pipe — process.exit()
+    // can tear down the process before the reader consumes the buffer. writeAllSync
+    // pushes every byte synchronously (looping short counts, retrying EAGAIN/EINTR),
+    // and skipping process.exit() lets the event loop drain naturally.
+    writeAllSync(1, data);
+}
+/**
+ * Frozen enum of typed reason codes used by error() for structured errors.
+ * Each subcommand contributes its own codes; the enum exists so tests can
+ * assert against typed values instead of grepping stderr (#2974).
+ *
+ * Adding a new code:
+ *   - Pick a snake_case lowercase value (the JSON wire form)
+ *   - Group by subsystem prefix (CONFIG_*, SDK_*, etc)
+ *   - Pass it to error(msg, ERROR_REASON.NEW_CODE) at the call site
+ */
+const ERROR_REASON = Object.freeze({
+    // config-get / config-set
+    CONFIG_KEY_NOT_FOUND: 'config_key_not_found',
+    CONFIG_NO_FILE: 'config_no_file',
+    CONFIG_PARSE_FAILED: 'config_parse_failed',
+    CONFIG_INVALID_KEY: 'config_invalid_key',
+    // SDK / gsd-tools dispatch
+    SDK_FAIL_FAST: 'sdk_fail_fast',
+    SDK_UNKNOWN_COMMAND: 'sdk_unknown_command',
+    SDK_MISSING_ARG: 'sdk_missing_arg',
+    // workflow / phase
+    PHASE_NOT_FOUND: 'phase_not_found',
+    SUMMARY_NO_PLANNING: 'summary_no_planning',
+    // graphify
+    GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
+    GRAPHIFY_INVALID_QUERY: 'graphify_invalid_query',
+    // hooks
+    HOOKS_OPT_OUT: 'hooks_opt_out',
+    // security-scan
+    SECURITY_SCAN_FAILED: 'security_scan_failed',
+    // generic
+    USAGE: 'usage',
+    UNKNOWN: 'unknown',
+});
+/**
+ * Process-level flag: when true, error() emits structured JSON to stderr
+ * instead of plain "Error: <message>" text. Set by gsd-tools.cjs when the
+ * CLI is invoked with `--json-errors`. Tests opt in to typed-IR error
+ * assertions by passing that flag and parsing the JSON.
+ *
+ * Default off so existing callers and human operators keep their plain-text
+ * diagnostics. The structured form is opt-in for tooling and tests (#2974).
+ */
+let _jsonErrorMode = false;
+function setJsonErrorMode(v) { _jsonErrorMode = !!v; }
+function getJsonErrorMode() { return _jsonErrorMode; }
+/**
+ * Emit an error and exit. When the second argument is provided it must be
+ * a value from ERROR_REASON; tests can assert on `result.reason`. When the
+ * process is in JSON-error mode, stderr receives `{ ok: false, reason,
+ * message }` so callers can parse it; otherwise stderr keeps the plain
+ * text form for human operators.
+ */
+function error(message, reason = ERROR_REASON.UNKNOWN) {
+    if (_jsonErrorMode) {
+        const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
+        writeAllSync(2, payload);
+    }
+    else {
+        writeAllSync(2, 'Error: ' + message + '\n');
+    }
+    process.exit(1);
+}
+module.exports = {
+    GSD_TEMP_DIR,
+    ensureGsdTempDir,
+    reapStaleTempFiles,
+    output,
+    ERROR_REASON,
+    setJsonErrorMode,
+    getJsonErrorMode,
+    error,
+};

package/gsd-core/bin/lib/loop-host-contract.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * loop-host-contract.cjs — generated by scripts/gen-loop-host-contract.cjs
+ * DO NOT EDIT BY HAND. Run: node scripts/gen-loop-host-contract.cjs --write
+ * ADR-894 §3 — Loop Host Contract, generated from workflow markers.
+ * 12 points: discuss:pre/post, plan:pre/post, execute:pre/wave:pre/wave:post/post,
+ * verify:pre/post, ship:pre/post. Per-step agentRoles and coreArtifacts.
+ */
+
+const LOOP_HOST_CONTRACT = [
+  {
+    "step": "discuss",
+    "points": [
+      "discuss:pre",
+      "discuss:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "CONTEXT.md"
+      ],
+      "consumes": []
+    }
+  },
+  {
+    "step": "plan",
+    "points": [
+      "plan:pre",
+      "plan:post"
+    ],
+    "agentRoles": [
+      "researcher",
+      "planner",
+      "checker"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "PLAN.md"
+      ],
+      "consumes": [
+        "CONTEXT.md"
+      ]
+    }
+  },
+  {
+    "step": "execute",
+    "points": [
+      "execute:pre",
+      "execute:wave:pre",
+      "execute:wave:post",
+      "execute:post"
+    ],
+    "agentRoles": [
+      "executor",
+      "verifier"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "SUMMARY.md"
+      ],
+      "consumes": [
+        "PLAN.md"
+      ]
+    }
+  },
+  {
+    "step": "verify",
+    "points": [
+      "verify:pre",
+      "verify:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "UAT.md"
+      ],
+      "consumes": [
+        "SUMMARY.md"
+      ]
+    }
+  },
+  {
+    "step": "ship",
+    "points": [
+      "ship:pre",
+      "ship:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [],
+      "consumes": [
+        "UAT.md"
+      ]
+    }
+  }
+];
+
+module.exports = { LOOP_HOST_CONTRACT };