@hegemonart/get-design-done 1.24.2 → 1.26.0

package/scripts/lib/runtime-detect.cjs

@@ -0,0 +1,96 @@
+// scripts/lib/runtime-detect.cjs
+//
+// Plan 26-02 — runtime detection from env-vars.
+//
+// Identifies which AI-coding-CLI host process the current Node script is
+// running inside, by reading the same `*_CONFIG_DIR` / `*_HOME` env-vars
+// the Phase 24 installer uses to decide where to drop runtime files.
+//
+// The env-var → runtime-ID mapping is owned by Phase 24's
+// `scripts/lib/install/runtimes.cjs`. This module imports `RUNTIMES` from
+// there and derives the lookup table — DO NOT duplicate the mapping
+// (D-05). Adding a new runtime to runtimes.cjs automatically extends
+// detection here.
+//
+// Lookup order is the runtimes.cjs declaration order. When a host
+// happens to set multiple env-vars (e.g. a parent CLI spawns a child CLI
+// and inherits env), the first-declared runtime wins. Phase 24's order
+// puts Claude Code first, then OpenCode, Gemini, Kilo, Codex, …; that's
+// also the order this module returns for ambiguous hosts.
+//
+// Pure module — no top-level side effects. Reads `process.env` only when
+// `detect()` is called. Returns null when no recognized env-var is set
+// (e.g. running tests in CI matrix, or a bare Node script invoked outside
+// any of the 14 runtime hosts).
+//
+// `.cjs` extension matches existing Phase 22 primitives and lets both
+// `.cjs` callers and `.ts` callers (under --experimental-strip-types)
+// require it without ESM-interop friction.
+
+'use strict';
+
+const { RUNTIMES } = require('./install/runtimes.cjs');
+
+/**
+ * Build the env-var → runtime-ID lookup map at module load. Frozen so
+ * accidental mutation by callers can't drift the map away from the
+ * Phase 24 source of truth.
+ *
+ * Shape: `[{ env: 'CLAUDE_CONFIG_DIR', id: 'claude' }, …]` — array of
+ * pairs to preserve declaration order from RUNTIMES (Map / Object key
+ * order is guaranteed by spec but the array form documents intent).
+ */
+const ENV_TO_RUNTIME = Object.freeze(
+  RUNTIMES.map((r) => Object.freeze({ env: r.configDirEnv, id: r.id })),
+);
+
+/**
+ * Detect which runtime host the current process is running inside, by
+ * scanning `process.env` for the runtime-ID env-vars in declaration
+ * order and returning the first match.
+ *
+ * The env-var must be a non-empty string to count as set — runtime
+ * harnesses that export an empty value (`CLAUDE_CONFIG_DIR=`) are
+ * treated as unset, since the empty string is not a usable config-dir
+ * path and likely indicates "exported but not assigned".
+ *
+ * @returns {string | null} runtime-ID (e.g. 'claude', 'codex') or null
+ *   when no recognized env-var is set in the current environment.
+ *
+ * @example
+ *   process.env.CLAUDE_CONFIG_DIR = '/Users/me/.claude';
+ *   detect(); // → 'claude'
+ *
+ * @example
+ *   // No runtime env-var set:
+ *   detect(); // → null
+ */
+function detect() {
+  const env = process.env;
+  for (const { env: name, id } of ENV_TO_RUNTIME) {
+    const v = env[name];
+    if (typeof v === 'string' && v.length > 0) {
+      return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Return the env-var → runtime-ID map as a plain array of pairs. Useful
+ * for diagnostic logging and tests that want to verify the mapping
+ * matches Phase 24 without depending on `runtimes.cjs` internals.
+ *
+ * The returned array is a fresh copy; mutating it has no effect on
+ * future `detect()` calls.
+ *
+ * @returns {Array<{env: string, id: string}>}
+ */
+function envVarMap() {
+  return ENV_TO_RUNTIME.map((p) => ({ env: p.env, id: p.id }));
+}
+
+module.exports = {
+  detect,
+  envVarMap,
+};

package/scripts/lib/tier-resolver.cjs

@@ -0,0 +1,311 @@
+// scripts/lib/tier-resolver.cjs
+//
+// Plan 26-02 — tier→model resolver with fallback chain.
+//
+// `resolve(runtime, tier, opts?) → model-string | null`
+//
+// Translates the tier vocabulary frontmatter speaks (`opus`, `sonnet`,
+// `haiku`) into the concrete model name a specific runtime understands
+// (e.g. `gpt-5`, `gemini-2.5-pro`, `qwen3-max`). Source-of-truth for the
+// mapping is `reference/runtime-models.md` (plan 26-01); this module
+// reads the parsed form via 26-01's parser helper at
+// `scripts/lib/install/parse-runtime-models.cjs`.
+//
+// Parsed-models shape (from 26-01):
+//   {
+//     schema_version: 1,
+//     runtimes: [
+//       { id: 'claude',
+//         tier_to_model: { opus: { model: 'claude-opus-4-7' }, … },
+//         reasoning_class_to_model: { high: { model: '…' }, … },
+//         provenance: [...]
+//       },
+//       …
+//     ]
+//   }
+//
+// Fallback chain (D-04):
+//   1. runtime-specific entry has the tier → use directly (no event).
+//   2. runtime row missing OR tier missing on the row → fall back to the
+//      `claude` row (Anthropic-default convention 26-01 baked into every
+//      placeholder runtime), emit `tier_resolution_fallback`.
+//   3. neither available (e.g. a parsed map with no claude row, or a
+//      claude row missing the requested tier) → return null, emit
+//      `tier_resolution_failed`.
+//
+// Never throws. null is a valid output the caller (router, budget-
+// enforcer) must handle gracefully. Garbage input (undefined runtime,
+// bogus tier, malformed models) returns null + failure event.
+//
+// `.cjs` to match Phase 22 primitives and let .ts hooks require it
+// under --experimental-strip-types without ESM-interop friction.
+//
+// Pure module — no top-level side effects beyond reading the parsed
+// runtime-models document on first call. The parsed form is cached per-
+// process; callers that need a fresh read between cycles call `reset()`.
+//
+// Test-injection contract: callers may pass `opts.models` to bypass the
+// on-disk lookup entirely. Used by `tests/tier-resolver.test.cjs` to
+// exercise the fallback branches deterministically.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VALID_TIERS = Object.freeze(['opus', 'sonnet', 'haiku']);
+
+/**
+ * Runtime-id whose row supplies the fallback for missing entries.
+ * 26-01's runtime-models.md uses Anthropic models as the closest-
+ * published-equivalent placeholder for every runtime that lacks a
+ * confirmed tier-map; that convention makes `claude` the natural
+ * D-04-branch-2 default. If 26-01 ever changes that convention,
+ * update this constant in lockstep.
+ */
+const DEFAULT_RUNTIME_ID = 'claude';
+
+const DEFAULT_EVENTS_PATH = path.join('.design', 'telemetry', 'events.jsonl');
+
+/**
+ * Cached parsed-models data. `null` until first lazy load (or after
+ * `reset()`).
+ */
+let _cachedModels = null;
+
+/**
+ * Lazy soft-import of the 26-01 parser. Returns null if the parser
+ * file is unreachable — the resolver then degrades to "always emit
+ * failed" for on-disk callers, while test callers using `opts.models`
+ * are unaffected.
+ */
+function loadParser() {
+  try {
+    const modPath = path.join(__dirname, 'install', 'parse-runtime-models.cjs');
+    if (!fs.existsSync(modPath)) return null;
+    return require(modPath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lazy load + cache the parsed runtime-models map. Returns null when
+ * the parser is unavailable or throws on the source markdown.
+ */
+function loadModels() {
+  if (_cachedModels !== null) return _cachedModels;
+  const parser = loadParser();
+  if (parser === null) return null;
+  try {
+    const fn = typeof parser.parseRuntimeModels === 'function'
+      ? parser.parseRuntimeModels
+      : (typeof parser === 'function' ? parser : null);
+    if (fn === null) return null;
+    const out = fn();
+    if (out && typeof out === 'object') {
+      _cachedModels = out;
+      return out;
+    }
+    return null;
+  } catch {
+    // Parser throws on schema validation failure — treat as
+    // "no usable models" so the resolver fails open with events
+    // rather than crashing the consumer.
+    return null;
+  }
+}
+
+/**
+ * Reset the parsed-models cache. Tests use this after writing fixture
+ * runtime-models.md to a temp cwd; production callers rarely need it.
+ */
+function reset() {
+  _cachedModels = null;
+}
+
+/**
+ * Append a single event line to the on-disk events.jsonl. Honors
+ * `GDD_EVENTS_PATH` for test isolation (matches the TS EventWriter's
+ * env-var contract). Never throws — diagnostic on stderr only.
+ *
+ * We don't `require` the .ts EventWriter from .cjs (would force every
+ * consumer to run under --experimental-strip-types); instead we write
+ * the same JSONL line shape directly. The envelope matches BaseEvent
+ * so downstream consumers don't care which producer wrote the line.
+ */
+function emitEvent(type, payload) {
+  const line = JSON.stringify({
+    type,
+    timestamp: new Date().toISOString(),
+    sessionId: process.env.GDD_SESSION_ID || 'tier-resolver',
+    payload,
+    _meta: {
+      pid: process.pid,
+      host: 'tier-resolver',
+      source: 'tier-resolver',
+    },
+  });
+  const envPath = process.env.GDD_EVENTS_PATH;
+  const target = envPath && envPath.length > 0
+    ? envPath
+    : path.join(process.cwd(), DEFAULT_EVENTS_PATH);
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, line + '\n', { encoding: 'utf8' });
+  } catch (err) {
+    // Don't let event-emission failure cascade into resolver failure;
+    // the resolver's job is to return a model (or null), not to
+    // guarantee telemetry. The event-stream has its own resilience
+    // story (Phase 20-14 / Phase 22).
+    try {
+      process.stderr.write(
+        `[tier-resolver] event emit failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Find a runtime row by id. Accepts both the 26-01 array shape
+ * (`runtimes: [{id, …}, …]`) and a plain-object map shape
+ * (`runtimes: {id: {…}}`) used by some test fixtures. Returns the row
+ * or null when not found / malformed.
+ */
+function findRuntimeRow(models, id) {
+  if (!models || typeof models !== 'object') return null;
+  const r = models.runtimes;
+  if (Array.isArray(r)) {
+    for (const row of r) {
+      if (row && typeof row === 'object' && row.id === id) return row;
+    }
+    return null;
+  }
+  if (r && typeof r === 'object') {
+    const row = r[id];
+    return row && typeof row === 'object' ? row : null;
+  }
+  return null;
+}
+
+/**
+ * Read the model string for `tier` from a runtime row. The 26-01
+ * shape nests one level: `tier_to_model.opus = { model: '…' }`. A
+ * flat shape (`tier_to_model.opus = '…'`) is also accepted to keep
+ * test fixtures terse. Returns the model string or null when absent
+ * or malformed.
+ */
+function lookupTier(row, tier) {
+  if (!row || typeof row !== 'object') return null;
+  const map = row.tier_to_model;
+  if (!map || typeof map !== 'object') return null;
+  const v = map[tier];
+  if (typeof v === 'string' && v.length > 0) return v;
+  if (v && typeof v === 'object' && typeof v.model === 'string' && v.model.length > 0) {
+    return v.model;
+  }
+  return null;
+}
+
+/**
+ * Resolve a `(runtime, tier)` pair to a concrete model string. Returns
+ * null when neither the runtime-specific entry nor the runtime-default
+ * fallback supplies a value for the tier; emits a structured event in
+ * both the fallback and failure branches.
+ *
+ * @param {string | null | undefined} runtime
+ *   Runtime ID (e.g. 'claude', 'codex'). Garbage input returns null +
+ *   failure event.
+ * @param {string | null | undefined} tier
+ *   Tier name. Must be one of `opus`/`sonnet`/`haiku`. Anything else
+ *   returns null + failure event.
+ * @param {object} [opts]
+ * @param {object} [opts.models]
+ *   Pre-parsed models map. When supplied, bypasses the on-disk lookup
+ *   entirely (tests use this).
+ * @param {boolean} [opts.silent]
+ *   When true, suppresses event emission on the fallback / failure
+ *   paths. Used by callers that batch-resolve and prefer to roll up
+ *   their own diagnostics. Default false.
+ * @returns {string | null}
+ */
+function resolve(runtime, tier, opts) {
+  const models = (opts && opts.models) || loadModels();
+  const silent = !!(opts && opts.silent);
+
+  // Validate inputs FIRST so the failure event payload carries the
+  // garbage values verbatim — useful for telemetry diagnosis.
+  const runtimeOk = typeof runtime === 'string' && runtime.length > 0;
+  const tierOk = typeof tier === 'string' && VALID_TIERS.indexOf(tier) >= 0;
+
+  if (!runtimeOk || !tierOk || !models || typeof models !== 'object') {
+    if (!silent) {
+      emitEvent('tier_resolution_failed', {
+        runtime: runtimeOk ? runtime : (runtime === undefined ? null : runtime),
+        tier: tierOk ? tier : (tier === undefined ? null : tier),
+        reason: !runtimeOk
+          ? 'invalid_runtime'
+          : !tierOk
+            ? 'invalid_tier'
+            : 'models_unavailable',
+      });
+    }
+    return null;
+  }
+
+  const row = findRuntimeRow(models, runtime);
+
+  // Branch 1: runtime-specific hit.
+  const direct = lookupTier(row, tier);
+  if (direct !== null) return direct;
+
+  // Branch 2: fall back to the default-runtime row. 26-01 inlines
+  // Anthropic-default models on every placeholder runtime, so this
+  // branch primarily catches "runtime id not in the 14-runtime map"
+  // and "claude row itself missing the tier" — the latter being
+  // structurally near-impossible if 26-01's schema validation is on,
+  // but we still handle it.
+  const defaultRow = findRuntimeRow(models, DEFAULT_RUNTIME_ID);
+  // Don't double-fall-back if the runtime IS the default and we
+  // already missed the tier — that's a true failure.
+  const fallbackModel = runtime === DEFAULT_RUNTIME_ID
+    ? null
+    : lookupTier(defaultRow, tier);
+  if (fallbackModel !== null) {
+    if (!silent) {
+      emitEvent('tier_resolution_fallback', {
+        runtime,
+        tier,
+        model: fallbackModel,
+        reason: row === null ? 'runtime_not_in_map' : 'tier_missing_for_runtime',
+        fallback_runtime: DEFAULT_RUNTIME_ID,
+      });
+    }
+    return fallbackModel;
+  }
+
+  // Branch 3: nothing usable.
+  if (!silent) {
+    emitEvent('tier_resolution_failed', {
+      runtime,
+      tier,
+      reason: row === null
+        ? 'runtime_not_in_map'
+        : (runtime === DEFAULT_RUNTIME_ID
+          ? 'tier_missing_on_default_runtime'
+          : 'tier_missing_no_default'),
+    });
+  }
+  return null;
+}
+
+module.exports = {
+  resolve,
+  reset,
+  VALID_TIERS,
+  DEFAULT_RUNTIME_ID,
+  // internals surfaced for tests only — stable API = `resolve` + `reset`.
+  _internal: { lookupTier, findRuntimeRow, emitEvent, loadParser, loadModels },
+};

package/scripts/validate-frontmatter.ts

@@ -40,6 +40,7 @@ export interface AgentFrontmatter {
   'reads-only': boolean | string;
   writes: string | string[];
   'default-tier'?: 'haiku' | 'sonnet' | 'opus';
+  'reasoning-class'?: 'high' | 'medium' | 'low';
   'size_budget'?: 'S' | 'M' | 'L' | 'XL';
 }
 
@@ -54,6 +55,120 @@ const REQUIRED_FIELDS: readonly (keyof AgentFrontmatter)[] = [
   'writes',
 ];
 
+/**
+ * Phase 26 (Plan 26-08) — runtime-neutral `reasoning-class` alias for
+ * `default-tier`. Equivalence table is locked in CONTEXT D-10 / D-11:
+ *
+ *   high   <-> opus
+ *   medium <-> sonnet
+ *   low    <-> haiku
+ *
+ * The alias is OPTIONAL (no per-agent retrofit lands in v1.26 — see
+ * agents/README.md "Runtime-neutral reasoning class"). When both fields
+ * appear together they MUST satisfy the equivalence; mismatched dual
+ * annotations are a validation error.
+ */
+export type DefaultTier = 'haiku' | 'sonnet' | 'opus';
+export type ReasoningClass = 'high' | 'medium' | 'low';
+
+export const REASONING_CLASS_VALUES: readonly ReasoningClass[] = [
+  'high',
+  'medium',
+  'low',
+];
+
+export const DEFAULT_TIER_VALUES: readonly DefaultTier[] = [
+  'opus',
+  'sonnet',
+  'haiku',
+];
+
+/** Equivalence map: reasoning-class -> default-tier. */
+export const CLASS_TO_TIER: Readonly<Record<ReasoningClass, DefaultTier>> = {
+  high: 'opus',
+  medium: 'sonnet',
+  low: 'haiku',
+};
+
+/** Equivalence map: default-tier -> reasoning-class. */
+export const TIER_TO_CLASS: Readonly<Record<DefaultTier, ReasoningClass>> = {
+  opus: 'high',
+  sonnet: 'medium',
+  haiku: 'low',
+};
+
+/** Type guard for a valid `reasoning-class` value. */
+export function isReasoningClass(v: unknown): v is ReasoningClass {
+  return typeof v === 'string' && REASONING_CLASS_VALUES.includes(v as ReasoningClass);
+}
+
+/** Type guard for a valid `default-tier` value. */
+export function isDefaultTier(v: unknown): v is DefaultTier {
+  return typeof v === 'string' && DEFAULT_TIER_VALUES.includes(v as DefaultTier);
+}
+
+/**
+ * Validate the optional `reasoning-class` field and its equivalence with
+ * `default-tier` when both are present. Returns an array of violation
+ * messages; an empty array means the agent passes the Plan 26-08 rules.
+ *
+ * Rules (Plan 26-08, CONTEXT D-11):
+ *   1. `reasoning-class` is OPTIONAL. Absence is fine.
+ *   2. If present, it MUST be one of `high|medium|low`.
+ *   3. If both `default-tier` and `reasoning-class` are present, the values
+ *      MUST satisfy the equivalence table (high+opus, medium+sonnet,
+ *      low+haiku). Mismatch is a validation error.
+ *
+ * Existing agents that carry only `default-tier` (the v1.26 baseline state
+ * for all 26 shipped agents) are unaffected — this helper returns an empty
+ * array for them.
+ *
+ * The `agentName` argument is used in error messages to surface which agent
+ * is misconfigured when the validator runs against the full roster.
+ */
+export function validateReasoningClass(
+  fm: Record<string, unknown>,
+  agentName: string,
+): string[] {
+  const violations: string[] = [];
+  const hasClass = 'reasoning-class' in fm && !isMissing(fm['reasoning-class']);
+  const hasTier = 'default-tier' in fm && !isMissing(fm['default-tier']);
+
+  if (!hasClass) {
+    // Field absent — allowed. `default-tier` is the v1.26 source of truth and
+    // is enforced by separate Phase 10.1 contracts (not this validator).
+    return violations;
+  }
+
+  const rawClass = fm['reasoning-class'];
+  if (!isReasoningClass(rawClass)) {
+    violations.push(
+      `reasoning-class: invalid value "${String(rawClass)}" for agent "${agentName}" — must be one of ${REASONING_CLASS_VALUES.join('|')}`,
+    );
+    return violations;
+  }
+
+  if (hasTier) {
+    const rawTier = fm['default-tier'];
+    if (!isDefaultTier(rawTier)) {
+      // default-tier shape is enforced elsewhere; we still surface a clear
+      // message so co-validation is debuggable in one pass.
+      violations.push(
+        `default-tier: invalid value "${String(rawTier)}" for agent "${agentName}" — must be one of ${DEFAULT_TIER_VALUES.join('|')}`,
+      );
+      return violations;
+    }
+    const expectedTier = CLASS_TO_TIER[rawClass];
+    if (rawTier !== expectedTier) {
+      violations.push(
+        `reasoning-class/default-tier: mismatch for agent "${agentName}" — reasoning-class="${rawClass}" expects default-tier="${expectedTier}", but got default-tier="${rawTier}". Equivalence table: high<->opus, medium<->sonnet, low<->haiku.`,
+      );
+    }
+  }
+
+  return violations;
+}
+
 function walkMd(dir: string): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -105,10 +220,32 @@ function main(): void {
         violations++;
       }
     }
+
+    // Plan 26-08 — runtime-neutral reasoning-class alias validation.
+    const agentName: string =
+      typeof fm.name === 'string' && fm.name.length > 0
+        ? fm.name
+        : basename(f).replace(/\.md$/, '');
+    const classViolations = validateReasoningClass(
+      fm as Record<string, unknown>,
+      agentName,
+    );
+    for (const msg of classViolations) {
+      console.log(`${f}:${msg}`);
+      violations++;
+    }
   }
 
   console.log(`summary: ${files.length} file(s) checked, ${violations} violation(s)`);
   process.exit(violations === 0 ? 0 : 1);
 }
 
-main();
+// Only run as a CLI when invoked directly (Plan 26-08: tests import the
+// helpers above without triggering process.exit). Node's strip-types ESM
+// loader sets `process.argv[1]` to the resolved entry path; a substring
+// match against this filename catches both direct execution and the
+// `node --experimental-strip-types` wrapper used by `npm run validate:frontmatter`.
+const entry: string = process.argv[1] ?? '';
+if (entry.endsWith('validate-frontmatter.ts') || entry.endsWith('validate-frontmatter.js')) {
+  main();
+}