@hegemonart/get-design-done 1.24.2 → 1.26.0

package/scripts/lib/install/installer.cjs

@@ -6,7 +6,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { getRuntime } = require('./runtimes.cjs');
+const { getRuntime, getRuntimeModels } = require('./runtimes.cjs');
 const { resolveConfigDir } = require('./config-dir.cjs');
 const {
   mergeClaudeSettings,
@@ -15,6 +15,15 @@ const {
   isPluginOwned,
 } = require('./merge.cjs');
 
+// Phase 26 D-06 — schema for the per-runtime models.json file emitted into
+// each runtime's config directory at install time. Forward-compatible: new
+// fields land additive; breaking changes bump `schema_version`.
+const MODELS_JSON_SCHEMA_VERSION = 1;
+const MODELS_JSON_FILE = 'models.json';
+const MODELS_JSON_SOURCE = 'reference/runtime-models.md';
+const MODELS_JSON_FINGERPRINT_KEY = 'generated_by';
+const MODELS_JSON_FINGERPRINT_VALUE = 'get-design-done';
+
 function loadJsonOr(empty, filePath) {
   if (!fs.existsSync(filePath)) return empty;
   const raw = fs.readFileSync(filePath, 'utf8');
@@ -48,13 +57,20 @@ function installRuntime(runtimeId, opts) {
   const dryRun = Boolean(opts && opts.dryRun);
   const configDir = resolveConfigDir(runtimeId, opts);
 
+  let result;
   if (runtime.kind === 'claude-marketplace') {
-    return installClaudeMarketplace(runtime, configDir, dryRun);
-  }
-  if (runtime.kind === 'agents-md') {
-    return installAgentsMd(runtime, configDir, dryRun);
+    result = installClaudeMarketplace(runtime, configDir, dryRun);
+  } else if (runtime.kind === 'agents-md') {
+    result = installAgentsMd(runtime, configDir, dryRun);
+  } else {
+    throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
   }
-  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+
+  // Phase 26 D-06 — emit per-runtime models.json into the same config-dir.
+  // Side-effect attached to the primary result so existing callers see the
+  // unchanged shape AND get visibility into the second file.
+  result.modelsJson = installModelsJson(runtime, configDir, dryRun, opts);
+  return result;
 }
 
 function uninstallRuntime(runtimeId, opts) {
@@ -62,13 +78,20 @@ function uninstallRuntime(runtimeId, opts) {
   const dryRun = Boolean(opts && opts.dryRun);
   const configDir = resolveConfigDir(runtimeId, opts);
 
+  let result;
   if (runtime.kind === 'claude-marketplace') {
-    return uninstallClaudeMarketplace(runtime, configDir, dryRun);
+    result = uninstallClaudeMarketplace(runtime, configDir, dryRun);
+  } else if (runtime.kind === 'agents-md') {
+    result = uninstallAgentsMd(runtime, configDir, dryRun);
+  } else {
+    throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
   }
-  if (runtime.kind === 'agents-md') {
-    return uninstallAgentsMd(runtime, configDir, dryRun);
-  }
-  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+
+  // Phase 26 D-06 — clean up the models.json we wrote on install.
+  // Idempotent: missing file → unchanged; foreign file (no fingerprint) is
+  // left alone, mirroring the AGENTS.md skipped-foreign discipline.
+  result.modelsJson = uninstallModelsJson(runtime, configDir, dryRun);
+  return result;
 }
 
 function installClaudeMarketplace(runtime, configDir, dryRun) {
@@ -203,6 +226,154 @@ function uninstallAgentsMd(runtime, configDir, dryRun) {
   };
 }
 
+// Phase 26 D-06 — `models.json` emission per runtime config-dir.
+//
+// Format (locked by CONTEXT D-06):
+//   {
+//     "tier_to_model": { "opus": "<model>", "sonnet": "<model>", "haiku": "<model>" },
+//     "reasoning_class_to_model": { "high": "<model>", "medium": "<model>", "low": "<model>" },
+//     "runtime": "<runtime-id>",
+//     "schema_version": 1,
+//     "generated_at": "<ISO-timestamp>",
+//     "source": "reference/runtime-models.md",
+//     "generated_by": "get-design-done"
+//   }
+//
+// `generated_by` is the fingerprint uninstall uses to decide whether the
+// file is plugin-owned (mirroring the AGENTS.md fingerprint discipline in
+// merge.cjs).
+
+function buildModelsJsonPayload(runtime, opts) {
+  const entry = getRuntimeModels(runtime.id, opts);
+  if (!entry) return null;
+  // Flatten { model: "..." } rows into bare strings per CONTEXT D-06's
+  // schema example. provider_model_id (if present in the source) is dropped
+  // here — runtime harnesses that need it can re-read runtime-models.md.
+  const flatten = (rowMap) => {
+    const out = {};
+    for (const k of Object.keys(rowMap)) {
+      out[k] = rowMap[k].model;
+    }
+    return out;
+  };
+  return {
+    tier_to_model: flatten(entry.tier_to_model),
+    reasoning_class_to_model: flatten(entry.reasoning_class_to_model),
+    runtime: runtime.id,
+    schema_version: MODELS_JSON_SCHEMA_VERSION,
+    generated_at: (opts && opts.now) || new Date().toISOString(),
+    source: MODELS_JSON_SOURCE,
+    [MODELS_JSON_FINGERPRINT_KEY]: MODELS_JSON_FINGERPRINT_VALUE,
+  };
+}
+
+function isModelsJsonPluginOwned(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
+  return parsed[MODELS_JSON_FINGERPRINT_KEY] === MODELS_JSON_FINGERPRINT_VALUE;
+}
+
+function installModelsJson(runtime, configDir, dryRun, opts) {
+  const target = path.join(configDir, MODELS_JSON_FILE);
+  const payload = buildModelsJsonPayload(runtime, opts);
+  if (!payload) {
+    // Runtime has no entry in runtime-models.md (e.g., research tail). Skip
+    // emission rather than writing an incomplete file. Surfaces as
+    // "skipped-no-data" in install summary so the operator can see why.
+    return {
+      path: target,
+      action: 'skipped-no-data',
+      dryRun,
+      reason: `No tier→model entry for runtime "${runtime.id}" in ${MODELS_JSON_SOURCE}`,
+    };
+  }
+  ensureDir(configDir, dryRun);
+
+  const desired = `${JSON.stringify(payload, null, 2)}\n`;
+
+  if (fs.existsSync(target)) {
+    let current;
+    try {
+      current = fs.readFileSync(target, 'utf8');
+    } catch (err) {
+      // Read failure is unusual but non-fatal — surface and continue.
+      return {
+        path: target,
+        action: 'skipped-foreign',
+        dryRun,
+        reason: `Could not read existing ${MODELS_JSON_FILE}: ${err.message}`,
+      };
+    }
+    let parsed = null;
+    try {
+      parsed = JSON.parse(current);
+    } catch {
+      // Corrupted/foreign JSON we did not write — leave it alone.
+      return {
+        path: target,
+        action: 'skipped-foreign',
+        dryRun,
+        reason: `Existing ${MODELS_JSON_FILE} is not valid JSON; refusing to overwrite.`,
+      };
+    }
+    if (!isModelsJsonPluginOwned(parsed)) {
+      return {
+        path: target,
+        action: 'skipped-foreign',
+        dryRun,
+        reason: `Existing ${MODELS_JSON_FILE} was not authored by this plugin; refusing to overwrite.`,
+      };
+    }
+    // Compare ignoring `generated_at` so re-runs aren't perpetually "updated"
+    // just because the timestamp moved.
+    if (modelsJsonContentEqual(parsed, payload)) {
+      return { path: target, action: 'unchanged', dryRun };
+    }
+    if (!dryRun) atomicWrite(target, desired);
+    return { path: target, action: 'updated', dryRun };
+  }
+  if (!dryRun) atomicWrite(target, desired);
+  return { path: target, action: 'created', dryRun };
+}
+
+function modelsJsonContentEqual(a, b) {
+  // Strip `generated_at` from both sides — every other field must match
+  // byte-for-byte for the install to be a true no-op.
+  const stripTs = (o) => {
+    const copy = { ...o };
+    delete copy.generated_at;
+    return copy;
+  };
+  return JSON.stringify(stripTs(a)) === JSON.stringify(stripTs(b));
+}
+
+function uninstallModelsJson(runtime, configDir, dryRun) {
+  const target = path.join(configDir, MODELS_JSON_FILE);
+  if (!fs.existsSync(target)) {
+    return { path: target, action: 'unchanged', dryRun };
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch {
+    return {
+      path: target,
+      action: 'skipped-foreign',
+      dryRun,
+      reason: `Existing ${MODELS_JSON_FILE} is not valid JSON; not removing.`,
+    };
+  }
+  if (!isModelsJsonPluginOwned(parsed)) {
+    return {
+      path: target,
+      action: 'skipped-foreign',
+      dryRun,
+      reason: `Existing ${MODELS_JSON_FILE} was not authored by this plugin; not removing.`,
+    };
+  }
+  if (!dryRun) fs.unlinkSync(target);
+  return { path: target, action: 'removed', dryRun };
+}
+
 function detectInstalled(opts) {
   const installed = [];
   const { listRuntimes } = require('./runtimes.cjs');
@@ -241,4 +412,10 @@ module.exports = {
   installRuntime,
   uninstallRuntime,
   detectInstalled,
+  // Phase 26 D-06 — exported for tests / external tooling that wants to
+  // preview the payload without performing a write.
+  buildModelsJsonPayload,
+  MODELS_JSON_FILE,
+  MODELS_JSON_SCHEMA_VERSION,
+  MODELS_JSON_SOURCE,
 };

package/scripts/lib/install/parse-runtime-models.cjs

@@ -0,0 +1,267 @@
+'use strict';
+/**
+ * parse-runtime-models.cjs — pure parser for reference/runtime-models.md.
+ *
+ * Reads the per-runtime tier→model adapter source-of-truth (Phase 26 D-01..D-03)
+ * and returns a structured object with one entry per runtime. Used by:
+ *
+ *   - scripts/lib/install/installer.cjs (26-03) at install time to emit
+ *     `models.json` per runtime config-dir.
+ *   - scripts/lib/tier-resolver.cjs (26-02) at runtime to resolve
+ *     (runtime, tier) → model.
+ *
+ * Pure-JS validation against the strict schema at
+ * `reference/schemas/runtime-models.schema.json`. No optional dependencies.
+ *
+ * Public API:
+ *   parseRuntimeModels({ cwd? }) → {
+ *     runtimes: [{ id, tier_to_model, reasoning_class_to_model, provenance, single_tier? }, ...],
+ *     schema_version: 1
+ *   }
+ *   parseRuntimeModelsFromString(markdown) → same shape
+ *
+ * Throws an Error with a specific message on the first validation failure
+ * (fail-fast: install-time validation catches typos before runtime).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const DEFAULT_PATH = path.join(REPO_ROOT, 'reference', 'runtime-models.md');
+
+// Mirrors scripts/lib/install/runtimes.cjs RUNTIMES list (Phase 24 D-02 lock).
+// Re-declared rather than imported to keep this parser dependency-free for
+// downstream consumers that may want to call it from outside the install/ tree.
+// Round-trip tested by tests/parse-runtime-models.test.cjs against the canonical
+// runtimes.cjs list.
+const KNOWN_RUNTIME_IDS = Object.freeze([
+  'claude',
+  'codex',
+  'gemini',
+  'qwen',
+  'kilo',
+  'copilot',
+  'cursor',
+  'windsurf',
+  'antigravity',
+  'augment',
+  'trae',
+  'codebuddy',
+  'cline',
+  'opencode',
+]);
+
+const TIER_KEYS = Object.freeze(['opus', 'sonnet', 'haiku']);
+const REASONING_CLASS_KEYS = Object.freeze(['high', 'medium', 'low']);
+
+/**
+ * Extract every ```json ... ``` fenced block from a markdown string.
+ * Returns an array of { raw, lineNumber } objects.
+ */
+function extractJsonBlocks(markdown) {
+  const blocks = [];
+  const re = /```json\s*\n([\s\S]*?)\n```/g;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    // Compute 1-indexed line number of the fence opening for error messages.
+    const lineNumber = markdown.slice(0, m.index).split('\n').length;
+    blocks.push({ raw: m[1], lineNumber });
+  }
+  return blocks;
+}
+
+function validateModelRow(row, where) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) {
+    throw new Error(`${where}: expected object, got ${typeof row}`);
+  }
+  if (typeof row.model !== 'string' || row.model.length === 0) {
+    throw new Error(`${where}: 'model' must be a non-empty string`);
+  }
+  const allowedKeys = new Set(['model', 'provider_model_id']);
+  for (const k of Object.keys(row)) {
+    if (!allowedKeys.has(k)) {
+      throw new Error(`${where}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+    }
+  }
+  if (row.provider_model_id !== undefined) {
+    if (typeof row.provider_model_id !== 'string' || row.provider_model_id.length === 0) {
+      throw new Error(`${where}: 'provider_model_id' must be a non-empty string when present`);
+    }
+  }
+}
+
+function validateProvenance(arr, where) {
+  if (!Array.isArray(arr) || arr.length < 1) {
+    throw new Error(`${where}: 'provenance' must be a non-empty array`);
+  }
+  arr.forEach((row, i) => {
+    const w = `${where}[${i}]`;
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+      throw new Error(`${w}: expected object`);
+    }
+    for (const required of ['source_url', 'retrieved_at', 'last_validated_cycle']) {
+      if (typeof row[required] !== 'string' || row[required].length === 0) {
+        throw new Error(`${w}: '${required}' must be a non-empty string`);
+      }
+    }
+    // ISO-8601 sanity check (Date.parse accepts the canonical form we emit).
+    if (Number.isNaN(Date.parse(row.retrieved_at))) {
+      throw new Error(`${w}: 'retrieved_at' must be a valid ISO 8601 timestamp (got ${JSON.stringify(row.retrieved_at)})`);
+    }
+    const allowedKeys = new Set(['source_url', 'retrieved_at', 'last_validated_cycle', 'note']);
+    for (const k of Object.keys(row)) {
+      if (!allowedKeys.has(k)) {
+        throw new Error(`${w}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+      }
+    }
+    if (row.note !== undefined && typeof row.note !== 'string') {
+      throw new Error(`${w}: 'note' must be a string when present`);
+    }
+  });
+}
+
+function validateRuntimeEntry(entry, where) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`${where}: expected object`);
+  }
+  // Required keys
+  for (const required of ['id', 'tier_to_model', 'reasoning_class_to_model', 'provenance']) {
+    if (!(required in entry)) {
+      throw new Error(`${where}: missing required key '${required}'`);
+    }
+  }
+  // id enum check
+  if (typeof entry.id !== 'string' || !KNOWN_RUNTIME_IDS.includes(entry.id)) {
+    throw new Error(
+      `${where}: 'id' must be one of ${KNOWN_RUNTIME_IDS.join('|')} (got ${JSON.stringify(entry.id)})`,
+    );
+  }
+  // No unknown top-level keys
+  const allowedKeys = new Set(['id', 'single_tier', 'tier_to_model', 'reasoning_class_to_model', 'provenance']);
+  for (const k of Object.keys(entry)) {
+    if (!allowedKeys.has(k)) {
+      throw new Error(`${where}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+    }
+  }
+  if (entry.single_tier !== undefined && typeof entry.single_tier !== 'boolean') {
+    throw new Error(`${where}: 'single_tier' must be a boolean when present`);
+  }
+
+  // tier_to_model: requires opus/sonnet/haiku
+  if (!entry.tier_to_model || typeof entry.tier_to_model !== 'object' || Array.isArray(entry.tier_to_model)) {
+    throw new Error(`${where}.tier_to_model: expected object`);
+  }
+  for (const tier of TIER_KEYS) {
+    if (!(tier in entry.tier_to_model)) {
+      throw new Error(`${where}.tier_to_model: missing required tier '${tier}'`);
+    }
+  }
+  for (const k of Object.keys(entry.tier_to_model)) {
+    if (!TIER_KEYS.includes(k)) {
+      throw new Error(`${where}.tier_to_model: unknown tier '${k}' (allowed: ${TIER_KEYS.join('|')})`);
+    }
+    validateModelRow(entry.tier_to_model[k], `${where}.tier_to_model.${k}`);
+  }
+
+  // reasoning_class_to_model: requires high/medium/low
+  if (!entry.reasoning_class_to_model || typeof entry.reasoning_class_to_model !== 'object' || Array.isArray(entry.reasoning_class_to_model)) {
+    throw new Error(`${where}.reasoning_class_to_model: expected object`);
+  }
+  for (const klass of REASONING_CLASS_KEYS) {
+    if (!(klass in entry.reasoning_class_to_model)) {
+      throw new Error(`${where}.reasoning_class_to_model: missing required class '${klass}'`);
+    }
+  }
+  for (const k of Object.keys(entry.reasoning_class_to_model)) {
+    if (!REASONING_CLASS_KEYS.includes(k)) {
+      throw new Error(`${where}.reasoning_class_to_model: unknown class '${k}' (allowed: ${REASONING_CLASS_KEYS.join('|')})`);
+    }
+    validateModelRow(entry.reasoning_class_to_model[k], `${where}.reasoning_class_to_model.${k}`);
+  }
+
+  validateProvenance(entry.provenance, `${where}.provenance`);
+}
+
+function parseRuntimeModelsFromString(markdown, sourceLabel) {
+  const label = sourceLabel || '<runtime-models markdown>';
+  if (typeof markdown !== 'string' || markdown.length === 0) {
+    throw new Error(`${label}: empty or non-string input`);
+  }
+
+  const blocks = extractJsonBlocks(markdown);
+  if (blocks.length < 2) {
+    // We expect at least the schema-version block + 1 runtime block.
+    throw new Error(`${label}: expected at least one schema-version block and one runtime block, found ${blocks.length} fenced json blocks`);
+  }
+
+  // First block MUST be the { "$schema_version": <int> } header.
+  let schemaVersion = null;
+  let firstParsed;
+  try {
+    firstParsed = JSON.parse(blocks[0].raw);
+  } catch (err) {
+    throw new Error(`${label}: first json block (line ${blocks[0].lineNumber}) failed to parse: ${err.message}`);
+  }
+  if (
+    !firstParsed ||
+    typeof firstParsed !== 'object' ||
+    Array.isArray(firstParsed) ||
+    !('$schema_version' in firstParsed) ||
+    Object.keys(firstParsed).length !== 1
+  ) {
+    throw new Error(`${label}: first json block (line ${blocks[0].lineNumber}) must be { "$schema_version": <int> } and nothing else`);
+  }
+  if (firstParsed.$schema_version !== 1) {
+    throw new Error(
+      `${label}: $schema_version must be 1 (got ${JSON.stringify(firstParsed.$schema_version)}). Bump the parser when the schema breaks forward.`,
+    );
+  }
+  schemaVersion = firstParsed.$schema_version;
+
+  // Remaining blocks are runtime entries.
+  const runtimes = [];
+  const seenIds = new Set();
+  for (let i = 1; i < blocks.length; i++) {
+    const block = blocks[i];
+    let parsed;
+    try {
+      parsed = JSON.parse(block.raw);
+    } catch (err) {
+      throw new Error(`${label}: json block at line ${block.lineNumber} failed to parse: ${err.message}`);
+    }
+    const where = `${label}#runtimes[${i - 1}] (line ${block.lineNumber})`;
+    validateRuntimeEntry(parsed, where);
+    if (seenIds.has(parsed.id)) {
+      throw new Error(`${where}: duplicate runtime id '${parsed.id}' (already seen earlier in the file)`);
+    }
+    seenIds.add(parsed.id);
+    runtimes.push(parsed);
+  }
+
+  return { schema_version: schemaVersion, runtimes };
+}
+
+function parseRuntimeModels({ cwd } = {}) {
+  const filePath = cwd ? path.join(cwd, 'reference', 'runtime-models.md') : DEFAULT_PATH;
+  let markdown;
+  try {
+    markdown = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    const wrapped = new Error(
+      `parse-runtime-models: cannot read ${filePath}\n  ${err.message}`,
+    );
+    wrapped.code = 'EPARSE_RUNTIME_MODELS_READ';
+    wrapped.path = filePath;
+    throw wrapped;
+  }
+  return parseRuntimeModelsFromString(markdown, filePath);
+}
+
+module.exports = {
+  parseRuntimeModels,
+  parseRuntimeModelsFromString,
+  KNOWN_RUNTIME_IDS,
+  TIER_KEYS,
+  REASONING_CLASS_KEYS,
+};

package/scripts/lib/install/runtimes.cjs

@@ -161,6 +161,47 @@ function listRuntimeIds() {
   return RUNTIMES.map((r) => r.id);
 }
 
+// Phase 26 D-06 — `tier_to_model` lookup helper.
+//
+// `getRuntimeModels(runtimeId, { cwd? })` resolves the per-runtime tier→model
+// adapter from `reference/runtime-models.md` via `parse-runtime-models.cjs`.
+// Returns `null` when the runtime has no entry in runtime-models.md (i.e.,
+// the data source ships rows for fewer than 14 runtimes during the rolling
+// research tail described in CONTEXT D-02). Caller is responsible for
+// degrading gracefully (e.g., installer skips models.json emission when null).
+//
+// The parsed payload is cached per `cwd` to avoid re-reading the markdown
+// on each runtime in a multi-runtime install loop.
+
+const _modelsCache = new Map();
+
+function getParsedRuntimeModels(opts) {
+  const cwd = (opts && opts.cwd) || null;
+  const cacheKey = cwd || '<default>';
+  if (_modelsCache.has(cacheKey)) return _modelsCache.get(cacheKey);
+  // Lazy require avoids a hard dep cycle if runtimes.cjs is imported in
+  // contexts that don't ship the reference/ tree (theoretical — not used today).
+  const { parseRuntimeModels } = require('./parse-runtime-models.cjs');
+  const parsed = parseRuntimeModels(cwd ? { cwd } : {});
+  _modelsCache.set(cacheKey, parsed);
+  return parsed;
+}
+
+function getRuntimeModels(runtimeId, opts) {
+  // Validate the runtime id up-front — this catches typos in the installer
+  // entry rather than silently returning null for "claud" vs "claude".
+  getRuntime(runtimeId);
+  const parsed = getParsedRuntimeModels(opts);
+  const entry = parsed.runtimes.find((r) => r.id === runtimeId);
+  return entry || null;
+}
+
+// Test-only hook: drop the cached parse result. Used by tests that mutate
+// the source markdown between assertions.
+function _resetRuntimeModelsCache() {
+  _modelsCache.clear();
+}
+
 module.exports = {
   RUNTIMES,
   REPO,
@@ -169,4 +210,6 @@ module.exports = {
   getRuntime,
   listRuntimes,
   listRuntimeIds,
+  getRuntimeModels,
+  _resetRuntimeModelsCache,
 };

package/scripts/lib/quality-gate-detect.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+// scripts/lib/quality-gate-detect.cjs — quality-gate detection chain.
+//
+// Phase 25 Plan 25-09: promotes the doc-only auto-detection logic from
+// skills/quality-gate/SKILL.md (Step 1, D-06) into a small testable
+// JS module. Pure function, no I/O, no clock.
+//
+// The 3-tier resolution order (D-06):
+//
+//   Tier 1 — Authoritative config:
+//     If the (already-loaded) `.design/config.json#quality_gate.commands`
+//     array is non-empty, return it verbatim. Skip all later tiers.
+//
+//   Tier 2 — Auto-detect from package.json#scripts:
+//     If the (already-loaded) package.json#scripts object exists and is
+//     non-empty, intersect its keys with the canonical allowlist and
+//     emit `npm run <script>` for each match. The allowlist (case-
+//     sensitive, exact match):
+//
+//       lint
+//       typecheck   (or `tsc` as a substitute when `typecheck` is absent)
+//       test
+//       chromatic
+//       test:visual
+//
+//     Hard exclusions (never included even if present):
+//
+//       test:e2e          (too slow for a Stage 4.5 gate)
+//       test:integration  (only excluded when a separate `test` exists)
+//
+//   Tier 3 — Skip with notice:
+//     Returns an empty array. Caller emits a `quality_gate_skipped`
+//     event and writes a `<run/>` with status="skipped".
+//
+// Mirrors the table in skills/quality-gate/SKILL.md verbatim. When the
+// SKILL.md prose changes, change this module in lockstep — the SKILL is
+// the design intent, this is the executable encoding consumers can test
+// against.
+
+/**
+ * Allowlisted script names (case-sensitive, exact match unless noted).
+ * Order matters: it determines the canonical command-list ordering, which
+ * in turn drives the deterministic `commands_run` field in events.jsonl
+ * and the STATE.md <run/> entry.
+ */
+const ALLOWLIST = Object.freeze([
+  'lint',
+  'typecheck',
+  'test',
+  'chromatic',
+  'test:visual',
+]);
+
+/**
+ * Hard exclusions. Even when present in package.json#scripts, these are
+ * never run by the quality gate — they are too slow / orthogonal to the
+ * gate's purpose. Excluding `test:integration` only matters when a
+ * separate `test` script exists; we encode that invariant in detect().
+ */
+const ALWAYS_EXCLUDED = Object.freeze(['test:e2e']);
+
+/**
+ * Detection chain.
+ *
+ * @param {object}  inputs
+ * @param {string[]|null|undefined} inputs.configCommands
+ *        Value of `.design/config.json#quality_gate.commands`. `null` or
+ *        empty array means "no config-side override; fall through to
+ *        auto-detect". The caller is responsible for reading the file.
+ * @param {Record<string, string>|null|undefined} inputs.scripts
+ *        Value of `package.json#scripts`. `null` means "no package.json".
+ * @returns {{commands: string[], tier: 1|2|3, reason?: string}}
+ *        Detection result. `tier` is the tier that produced the
+ *        commands (1 / 2 / 3 — see top of file). `reason` is populated
+ *        on tier 3 only ("no commands resolved").
+ */
+function detect(inputs) {
+  const configCommands = inputs && inputs.configCommands;
+  const scripts = inputs && inputs.scripts;
+
+  // --- Tier 1: authoritative config wins. ---
+  if (Array.isArray(configCommands) && configCommands.length > 0) {
+    return { commands: configCommands.slice(), tier: 1 };
+  }
+
+  // --- Tier 2: auto-detect from package.json#scripts. ---
+  if (scripts && typeof scripts === 'object') {
+    const detected = autoDetect(scripts);
+    if (detected.length > 0) {
+      return { commands: detected, tier: 2 };
+    }
+  }
+
+  // --- Tier 3: nothing resolved → skip with notice. ---
+  return { commands: [], tier: 3, reason: 'no commands resolved' };
+}
+
+/**
+ * Apply the allowlist to a `scripts` map. Pure.
+ */
+function autoDetect(scripts) {
+  const out = [];
+  for (const name of ALLOWLIST) {
+    if (name === 'typecheck') {
+      // `typecheck` preferred; fall through to `tsc` only if absent.
+      if (Object.prototype.hasOwnProperty.call(scripts, 'typecheck')) {
+        out.push('npm run typecheck');
+      } else if (Object.prototype.hasOwnProperty.call(scripts, 'tsc')) {
+        out.push('npm run tsc');
+      }
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(scripts, name) && !ALWAYS_EXCLUDED.includes(name)) {
+      out.push(`npm run ${name}`);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  ALLOWLIST,
+  ALWAYS_EXCLUDED,
+  detect,
+  autoDetect,
+};