@hegemonart/get-design-done 1.59.7 → 1.59.9

package/scripts/lib/detect/cli.cjs

@@ -45,13 +45,23 @@ function isUrl(p) {
   return /^https?:\/\//i.test(String(p || ''));
 }
 
-/** Select the detection engine. Returns { mode, warning }. Regex-fast is the dep-free default. */
+/**
+ * Select the detection engine. Returns { mode, warning }.
+ *
+ * There is exactly one engine path: regex over file text (see engine.cjs#run, which takes no
+ * jsdom/DOM parameter and is byte-identical whether or not jsdom is installed). So the truthful
+ * mode is always 'regex-fast'. We still probe jsdom (unless --fast) to surface a one-line hint
+ * that a DOM-aware path is not wired in this build — but we no longer claim a 'dom-aware' mode the
+ * engine does not have.
+ */
 function selectEngine(opts, requireFn) {
   if (opts.fast) return { mode: 'regex-fast', warning: null };
   let hasJsdom = false;
   try { requireFn('jsdom'); hasJsdom = true; } catch { hasJsdom = false; }
-  if (hasJsdom) return { mode: 'dom-aware', warning: null };
-  return { mode: 'regex-fast', warning: 'jsdom not installed — using regex-fast (install jsdom for DOM-aware mode, or pass --fast to silence this).' };
+  // jsdom presence does not change the engine — only emit a hint when it's absent, and never
+  // promise a mode we can't deliver.
+  const warning = hasJsdom ? null : 'jsdom not installed — running regex-fast (the only wired mode; a DOM-aware path is not implemented). Pass --fast to silence this.';
+  return { mode: 'regex-fast', warning };
 }
 
 function renderHuman(result, mode) {

package/scripts/lib/install/converters/cursor.cjs

@@ -25,25 +25,17 @@
  * Pure / side-effect-free: no fs, no env, no path. `convert` is a
  * deterministic string → string transform.
  *
- * KNOWN LIMITATION — sibling .md files (audit batch H6, 2026-06-04):
- *   The Cursor install drops ONLY `skills/<name>/SKILL.md`. Sibling
- *   `.md` files living next to SKILL.md (e.g. `discover-procedure.md`,
- *   `explore-procedure.md`, `cache-policy.md`) are NOT enumerated by
- *   `runtime-artifact-layout.cjs#skillsKind` and therefore NOT installed.
- *   Source SKILL.md files reference siblings via relative paths
- *   (e.g. `./discover-procedure.md`); on Cursor those links resolve to
- *   nothing.
- *
- *   This is a systemic limitation of the current `multi-artifact`
- *   pipeline, not a Cursor-specific bug — it affects every runtime that
- *   uses `skillsKind` (claude global, cursor, codex, copilot, antigravity,
- *   windsurf, augment, trae, qwen, codebuddy). Fix requires extending the
- *   StagedArtifact contract to emit multiple files per skill (one
- *   SKILL.md + N siblings), updating `computeDestPath`, the foreign-file
- *   detection in `detectMultiArtifactInstalled`, and the uninstall
- *   enumeration in `uninstallMultiArtifact`. Tracked as a follow-up
- *   beyond batch H6 scope. See `connections/cursor.md` for user-facing
- *   guidance.
+ * SIBLING .md FILES — RESOLVED (audit AR6, Phase 59.8):
+ *   The install now carries co-located sibling `*.md` reference files
+ *   (e.g. `discover-procedure.md`, `cache-policy.md`) alongside SKILL.md
+ *   for EVERY skillsKind runtime, not just Cursor. The carry happens in
+ *   `installer.cjs#installMultiArtifact` (gated on `kind.kind === 'skills'`
+ *   plus `item.srcPath`), with symmetric removal in `uninstallMultiArtifact`.
+ *   Siblings are passthrough copies fingerprinted via `fingerprintSiblingRef`
+ *   so foreign-file protection + uninstall treat them as plugin-owned. Only
+ *   top-level `*.md` siblings are carried; nested subdirectories are out of
+ *   scope. Previously this was a Batch-H6 cursor-only patch (the audit AR6
+ *   finding); it is now generalized across all skillsKind runtimes.
  */
 
 const shared = require('./shared.cjs');

package/scripts/lib/install/installer.cjs

@@ -163,12 +163,17 @@ function installClaudeMarketplace(runtime, configDir, dryRun) {
       dryRun,
     };
   }
+  // B1 fix (Phase 59.8): decide created-vs-updated BEFORE the write. The
+  // settings.json file is written by atomicWrite below, so testing
+  // `existsSync(settingsPath)` afterwards always returned 'updated' (the file
+  // we just wrote exists). Capture the pre-write existence instead.
+  const existedBefore = fs.existsSync(settingsPath);
   const formatted = `${JSON.stringify(next, null, 2)}\n`;
   if (!dryRun) atomicWrite(settingsPath, formatted);
   return {
     runtime: runtime.id,
     path: settingsPath,
-    action: fs.existsSync(settingsPath) ? 'updated' : 'created',
+    action: existedBefore ? 'updated' : 'created',
     dryRun,
   };
 }
@@ -439,6 +444,20 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
       continue;
     }
     for (const item of staged) {
+      // AR7 fix (Phase 59.8): never write a 0-byte / empty artifact. The old
+      // agents path staged `content: ''` for every skill name that had no
+      // matching agent file, producing empty `gdd-<name>.md` placeholders.
+      // Even with the layout-side enumeration fix, guard defensively here so
+      // no converter/kind can ever emit an empty file to disk.
+      if (!item.content || !String(item.content).trim()) {
+        perFile.push({
+          kind: kind.kind,
+          path: computeDestPath(configDir, kind, item.name),
+          action: 'skipped-empty',
+          reason: `Refusing to write empty artifact ${item.name}`,
+        });
+        continue;
+      }
       const destPath = computeDestPath(configDir, kind, item.name);
       const writeResult = writeFingerprinted(destPath, item.content, dryRun);
       perFile.push({
@@ -448,15 +467,16 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
         ...(writeResult.reason ? { reason: writeResult.reason } : {}),
       });
 
-      // Batch H6: carry co-located sibling `*.md` reference files alongside
-      // SKILL.md. The skills layout only stages SKILL.md per skill, so
-      // reference siblings (e.g. `<name>-procedure.md`) are otherwise lost.
-      // Scoped to cursor (the audited flat-layout runtime); other runtimes
-      // keep their prior single-SKILL.md behavior. Siblings are passthrough
-      // copies fingerprinted so foreign-file protection + uninstall treat
-      // them as plugin-owned. Broader skillsKind-runtime carry is deferred
-      // (see converters/cursor.cjs KNOWN LIMITATION).
-      if (kind.kind === 'skills' && runtime.id === 'cursor' && item.srcPath) {
+      // AR6 fix (Phase 59.8): carry co-located sibling `*.md` reference files
+      // alongside SKILL.md for EVERY skillsKind runtime (cursor, codex,
+      // copilot, antigravity, windsurf, augment, trae, qwen, codebuddy, and
+      // claude global). The skills layout only stages SKILL.md per skill, so
+      // reference siblings (e.g. `<name>-procedure.md`) were otherwise lost on
+      // every runtime except cursor — shipping dead relative links. Siblings
+      // are passthrough copies fingerprinted so foreign-file protection +
+      // uninstall treat them as plugin-owned. Was previously scoped to cursor
+      // only (Batch H6); see converters/cursor.cjs former KNOWN LIMITATION.
+      if (kind.kind === 'skills' && item.srcPath) {
         const skillSrcDir = path.dirname(item.srcPath);
         const skillDestDir = path.dirname(destPath);
         for (const sibling of listSiblingRefFiles(skillSrcDir)) {
@@ -550,8 +570,27 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
   const skillDirsToTrim = [];
 
   for (const kind of layout.kinds) {
-    for (const bareName of skillNames) {
-      const itemName = (kind.prefix || '') + bareName;
+    // AR7 fix (Phase 59.8): derive the artifact names from the SAME staging
+    // pass install uses, so uninstall stays symmetric. The `agents` kind
+    // enumerates `agents/*.md` (real agent role names), NOT skill names — the
+    // old `gdd-<skillName>.md` derivation never matched any installed agent
+    // file and left every real agent on disk after `--uninstall`.
+    let stagedNames;
+    try {
+      const staged = kind.stage({
+        skillsRoot,
+        skillNames,
+        scope,
+        runtime: runtime.id,
+        configDir,
+      });
+      stagedNames = staged.map((item) => item.name);
+    } catch {
+      // Fall back to the prior skill-name derivation if staging fails (e.g.
+      // a converter throws); skills/commands kinds match this shape exactly.
+      stagedNames = skillNames.map((n) => (kind.prefix || '') + n);
+    }
+    for (const itemName of stagedNames) {
       const destPath = computeDestPath(configDir, kind, itemName);
       if (!fs.existsSync(destPath)) {
         perFile.push({ kind: kind.kind, path: destPath, action: 'unchanged' });
@@ -586,11 +625,12 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
         const skillDestDir = path.dirname(destPath);
         skillDirsToTrim.push(skillDestDir);
 
-        // Batch H6: symmetric cleanup for the sibling reference files the
-        // cursor install carries alongside SKILL.md. Remove only the
-        // plugin-owned siblings so a now-empty dir can be trimmed below;
-        // user-authored siblings are left in place (foreign-file discipline).
-        if (runtime.id === 'cursor') {
+        // AR6 fix (Phase 59.8): symmetric cleanup for the sibling reference
+        // files every skillsKind install carries alongside SKILL.md. Remove
+        // only the plugin-owned siblings so a now-empty dir can be trimmed
+        // below; user-authored siblings are left in place (foreign-file
+        // discipline). Was previously scoped to cursor only (Batch H6).
+        if (kind.kind === 'skills') {
           for (const sibling of listSiblingRefFiles(skillDestDir)) {
             const siblingPath = path.join(skillDestDir, sibling);
             let siblingContent;
@@ -682,11 +722,22 @@ function installCline(runtime, configDir, skillsRoot, skillNames, dryRun) {
   const cline = require('./converters/cline.cjs');
   ensureDir(configDir, dryRun);
 
-  const blocks = skillNames.map((name) => {
+  // B2 fix (Phase 59.8): wrap the per-skill read in try/catch. Previously a
+  // single unreadable SKILL.md threw out of `installCline`, aborting the
+  // entire cline install (and, when cline is one runtime in a multi-runtime
+  // batch, every runtime queued after it). Skip the unreadable skill and keep
+  // going, mirroring the best-effort sibling reads elsewhere in this file.
+  const blocks = [];
+  for (const name of skillNames) {
     const srcPath = path.join(skillsRoot, name, 'SKILL.md');
-    const raw = fs.readFileSync(srcPath, 'utf8');
-    return { name, block: cline.convert(raw, name, { runtime: 'cline' }) };
-  });
+    let raw;
+    try {
+      raw = fs.readFileSync(srcPath, 'utf8');
+    } catch {
+      continue; // unreadable skill — skip, don't abort the whole install
+    }
+    blocks.push({ name, block: cline.convert(raw, name, { runtime: 'cline' }) });
+  }
 
   const desired = cline.buildClinerulesFile(blocks);
   const target = path.join(configDir, '.clinerules');

package/scripts/lib/install/merge.cjs

@@ -111,11 +111,39 @@ function buildAgentsFileContent(runtime, payloadHeader) {
 const GDD_ADAPTER_FINGERPRINT = 'gdd: auto-generated from Claude SKILL.md';
 const CLINERULES_HEADER_FINGERPRINT = '# get-design-done rules';
 
+// B5/S4 fix (Phase 59.8): ownership detection is WHOLE-LINE anchored, not a
+// loose `String.includes` substring scan. The old substring match treated any
+// user-authored file that merely *mentioned* a marker string (e.g. a doc that
+// quotes "get-design-done plugin instructions", or a code fence containing
+// "gdd: auto-generated from Claude SKILL.md") as plugin-owned — so install
+// would overwrite it and uninstall would delete it. We now require the marker
+// to appear on a recognized GENERATED line:
+//
+//   - `<!-- ... <fingerprint> ... -->`  HTML-comment marker line. Both the
+//     Phase-24 plugin fingerprint and the per-runtime/sibling adapter header
+//     are emitted as a standalone HTML comment line; we accept the marker only
+//     when it sits inside an HTML comment that occupies the whole (trimmed)
+//     line. A bare prose mention of the same words no longer qualifies.
+//   - `# get-design-done rules`  cline rules header — must be the exact, whole
+//     trimmed line (a Markdown H1), matching converters/cline.cjs.
+//
+// Scanning line-by-line keeps detection of genuinely plugin-owned files intact
+// (the generated marker line is always present near the top) while refusing to
+// claim ownership of user files that merely contain the words somewhere.
+function isHtmlCommentMarkerLine(line, fingerprint) {
+  const t = line.trim();
+  if (!t.startsWith('<!--') || !t.endsWith('-->')) return false;
+  return t.includes(fingerprint);
+}
+
 function isPluginOwned(content) {
   if (!content || typeof content !== 'string') return false;
-  if (content.includes(PLUGIN_FINGERPRINT)) return true;
-  if (content.includes(GDD_ADAPTER_FINGERPRINT)) return true;
-  if (content.includes(CLINERULES_HEADER_FINGERPRINT)) return true;
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    if (isHtmlCommentMarkerLine(line, PLUGIN_FINGERPRINT)) return true;
+    if (isHtmlCommentMarkerLine(line, GDD_ADAPTER_FINGERPRINT)) return true;
+    if (line.trim() === CLINERULES_HEADER_FINGERPRINT) return true;
+  }
   return false;
 }
 

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

@@ -78,7 +78,7 @@ function validateModelRow(row, where) {
   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']);
+  const allowedKeys = new Set(['model', 'provider_model_id', 'context_window']);
   for (const k of Object.keys(row)) {
     if (!allowedKeys.has(k)) {
       throw new Error(`${where}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
@@ -89,6 +89,14 @@ function validateModelRow(row, where) {
       throw new Error(`${where}: 'provider_model_id' must be a non-empty string when present`);
     }
   }
+  // Optional context-window size — mirror the schema (integer >= 1). Recorded as
+  // machine-readable metadata (the 1M-context [1m] opus variant); not yet a
+  // budgeting driver (deferred — no consumer wired this cycle).
+  if (row.context_window !== undefined) {
+    if (typeof row.context_window !== 'number' || !Number.isInteger(row.context_window) || row.context_window < 1) {
+      throw new Error(`${where}: 'context_window' must be a positive integer when present`);
+    }
+  }
 }
 
 function validateProvenance(arr, where) {

package/scripts/lib/install/runtime-artifact-layout.cjs

@@ -226,9 +226,21 @@ function commandsKind(destSubpath, prefix, converterPath, runtime) {
 /**
  * Build an `agents` artifact-kind descriptor.
  *
- * claude local only — passthrough copy from `<repo>/agents/*` into
+ * claude local only — passthrough copy from `<repo>/agents/*.md` into
  * `<configDir>/agents/`. No converter.
  *
+ * AR7 fix (Phase 59.8): the agent set is ENUMERATED from the `agents/`
+ * directory on disk — NOT derived from `ctx.skillNames`. Real agent files
+ * are named after agent roles (`design-planner.md`, `a11y-mapper.md`, …),
+ * which never coincide with skill directory names. The old skill-name-derived
+ * path read `agents/<skillName>.md`, found nothing for any skill, and staged
+ * ~96 empty `gdd-<skillName>.md` artifacts while installing ZERO real agents.
+ *
+ * Enumeration rules:
+ *   - top-level `*.md` files in `agents/` only (no nested dirs),
+ *   - `README.md` is excluded (it is documentation, not an agent),
+ *   - empty / unreadable files are skipped (best-effort; never throws).
+ *
  * @param {string} destSubpath
  * @param {string} prefix
  * @returns {ArtifactKind}
@@ -243,13 +255,35 @@ function agentsKind(destSubpath, prefix) {
         path.dirname(ctx.skillsRoot),
         'agents'
       );
-      return ctx.skillNames.map((name) => {
-        const srcPath = path.join(agentsRoot, name + '.md');
-        const raw = fs.existsSync(srcPath)
-          ? fs.readFileSync(srcPath, 'utf8')
-          : '';
-        return { srcPath, content: raw, name: prefix + name };
-      });
+      let entries;
+      try {
+        entries = fs.readdirSync(agentsRoot, { withFileTypes: true });
+      } catch {
+        // No agents/ dir on disk — stage nothing (never throw).
+        return [];
+      }
+      const staged = [];
+      for (const ent of entries) {
+        if (!ent.isFile()) continue;
+        if (!ent.name.toLowerCase().endsWith('.md')) continue;
+        if (ent.name.toLowerCase() === 'readme.md') continue;
+        // Strip any pre-existing gdd-/gsd- prefix on the agent filename before
+        // re-applying `prefix`, so an agent already named `gdd-foo.md` does not
+        // become `gdd-gdd-foo.md`. Real agents ship un-prefixed
+        // (`a11y-mapper.md`); this guard keeps both shapes correct.
+        const fileBase = ent.name.slice(0, -'.md'.length);
+        const bareName = fileBase.replace(/^(gdd-|gsd-)/i, '');
+        const srcPath = path.join(agentsRoot, ent.name);
+        let raw = '';
+        try {
+          raw = fs.readFileSync(srcPath, 'utf8');
+        } catch {
+          continue;
+        }
+        if (!raw.trim()) continue; // skip empty agent files
+        staged.push({ srcPath, content: raw, name: prefix + bareName });
+      }
+      return staged;
     },
   };
 }

package/scripts/lib/manifest/harnesses.json

@@ -20,11 +20,13 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": true,
         "placeholder_substitution": true,
+        "agents_support": true,
+        "hooks_support": true,
         "install_path": "dist/claude-code/.claude/skills/",
         "status": "tested"
       },
       "last_verified": "2026-06-02",
-      "capability_notes": "Host runtime. Marketplace-registered, end-to-end documented, Phase 42 golden baseline.",
+      "capability_notes": "Host runtime. Marketplace-registered, end-to-end documented, Phase 42 golden baseline. Sole runtime that receives the 64 sub-agents (claude --local installs agents/) and the hook layer (SessionStart / PostToolUse / statusLine).",
       "fragment_links": [
         "reference/runtime-models.md#claude---claude-code"
       ]
@@ -44,6 +46,8 @@
         "command_syntax": "/gdd-<skill>",
         "mcp_support": true,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/codex/.codex/skills/",
         "status": "experimental"
       },
@@ -71,6 +75,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": true,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/gemini/.gemini/skills/",
         "status": "experimental"
       },
@@ -98,6 +104,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/qwen/.qwen/skills/",
         "status": "experimental"
       },
@@ -124,6 +132,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/kilo/.kilo/skills/",
         "status": "untested"
       },
@@ -148,6 +158,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/copilot/.copilot/skills/",
         "status": "experimental"
       },
@@ -174,6 +186,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/cursor/.cursor/skills/",
         "status": "experimental"
       },
@@ -200,6 +214,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/windsurf/.windsurf/skills/",
         "status": "untested"
       },
@@ -224,6 +240,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/antigravity/.antigravity/skills/",
         "status": "untested"
       },
@@ -248,6 +266,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/augment/.augment/skills/",
         "status": "untested"
       },
@@ -272,6 +292,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/trae/.trae/skills/",
         "status": "untested"
       },
@@ -296,6 +318,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/codebuddy/.codebuddy/skills/",
         "status": "untested"
       },
@@ -320,6 +344,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/cline/.cline/skills/",
         "status": "untested"
       },
@@ -344,6 +370,8 @@
         "command_syntax": "/gdd:<skill>",
         "mcp_support": false,
         "placeholder_substitution": true,
+        "agents_support": false,
+        "hooks_support": false,
         "install_path": "dist/opencode/.opencode/skills/",
         "status": "untested"
       },

package/scripts/lib/manifest/skills.json

@@ -541,7 +541,7 @@
     },
     {
       "name": "router",
-      "description": "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic - no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.ts.",
+      "description": "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. A SKILL.md prompt the model executes to emit a routing-decision JSON from rule tables (no separate agent spawn). Optional/advisory - invoked only by the skills that opt into routing; the budget-enforcer hook tolerates its absence. Read by hooks/budget-enforcer.ts.",
       "argument_hint": "<intent-string> [<target-artifacts-csv>]",
       "tools": "Read, Bash, Grep"
     },

package/scripts/lib/model-id.cjs

@@ -0,0 +1,141 @@
+'use strict';
+/*
+ * scripts/lib/model-id.cjs — model-id normalization + tiering (pure, dependency-free).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Two unrelated callers need to reason about model ids in identical ways:
+ *   - scripts/lib/session-runner/index.ts (routing: which tier am I running?)
+ *   - scripts/lib/budget-enforcer.cjs       (pricing: what does this model cost?)
+ * Each previously carried its own ad-hoc parsing, which drifted. This module is
+ * the single source of truth so a new model family is a DATA edit here (or in the
+ * price tables), never a logic change scattered across callers.
+ *
+ * DESIGN PRINCIPLES
+ * -----------------
+ * 1. TIER IS FOR ROUTING. `tierForModelId` answers "opus | sonnet | haiku" so the
+ *    router can pick an agent class. It is NOT a pricing key on its own — pricing
+ *    also depends on the exact id and (later) the context-window variant.
+ *
+ * 2. NULL MEANS UNKNOWN — PRICE CONSERVATIVELY + LOUDLY. We deliberately return
+ *    `null` for ids we cannot confidently classify rather than guessing a tier.
+ *    A wrong tier guess silently mis-routes or mis-prices. Callers MUST treat
+ *    null as "unknown model — assume the most expensive plausible price AND warn",
+ *    never as a tier and never as free. Do NOT add heuristic fallbacks that
+ *    invent a tier for arbitrary strings.
+ *
+ * 3. VARIANT SUFFIX IS FOR CONTEXT-WINDOW-AWARE PRICING (LATER). Ids may carry a
+ *    bracketed variant such as `claude-opus-4-8[1m]` or `...[200k]`. The variant
+ *    encodes a context-window SKU that can have different per-token pricing. We
+ *    split it off cleanly (`{ base, variant }`) so tiering operates on `base`
+ *    while a future price table can key on `(base, variant)`. Date stamps in the
+ *    base (e.g. `claude-opus-4-8-20260101`) are NOT variants and are left intact.
+ *
+ * 4. NEW FAMILIES ARE A DATA EDIT, NOT A CODE CHANGE. To onboard a new model:
+ *      - if its id contains the tier word (opus/sonnet/haiku), the family-pattern
+ *        rule already handles it — optionally pin it in KNOWN_TIER_BY_ID;
+ *      - if its id does NOT contain the tier word (e.g. a hypothetical
+ *        `claude-fable-5`), add one line to ALIAS_MAP (see comment there);
+ *      - pricing specifics go in the caller's price table keyed on the exact id.
+ */
+
+/**
+ * KNOWN_TIER_BY_ID — explicit, exact-id → tier pins.
+ * Seeded with the currently-shipping ids. Exact matches win over pattern rules,
+ * so this is also the place to OVERRIDE a family-pattern result if a specific
+ * sku is mis-classified by the generic regex. Keys are the normalized `base`
+ * (no bracket variant).
+ */
+const KNOWN_TIER_BY_ID = Object.freeze({
+  'claude-opus-4-8': 'opus',
+  'claude-opus-4-7': 'opus',
+  'claude-sonnet-4-7': 'sonnet',
+  'claude-sonnet-4-6': 'sonnet',
+  'claude-sonnet-4-5': 'sonnet',
+  'claude-haiku-4-5': 'haiku',
+});
+
+/**
+ * ALIAS_MAP — extension point for families whose id does NOT contain the tier word.
+ *
+ * Currently EMPTY by design. The family-pattern rule (step c in tierForModelId)
+ * already covers any id literally containing `opus`/`sonnet`/`haiku`. Use this map
+ * ONLY for a future lineup whose product name omits the tier word.
+ *
+ * Example — when Anthropic publishes the `claude-fable-5` sku lineup and we learn
+ * it maps to opus-class routing, add (keyed on normalized base):
+ *
+ *     'claude-fable-5': 'opus',
+ *
+ * Until the lineup is public we leave it empty rather than guess — an unknown
+ * `claude-fable-5` correctly resolves to null (conservative pricing + warning).
+ */
+const ALIAS_MAP = Object.freeze({
+  // 'claude-fable-5': 'opus',  // <- add when the fable-5 sku lineup is public
+});
+
+const VARIANT_RE = /\[([^\]]*)\]\s*$/; // trailing bracketed suffix, e.g. [1m] / [200k]
+const FAMILY_RE = /(?:^|-)(opus|sonnet|haiku)(?:-|$)/;
+
+/**
+ * normalizeModelId(id) → { base, variant }
+ *
+ * Splits off a single trailing bracketed variant suffix (e.g. `[1m]`, `[200k]`),
+ * returning it lowercased with brackets removed as `variant`, and the remaining
+ * trimmed id as `base`. Date stamps in the base are preserved. Null/empty/
+ * undefined input yields `{ base: '', variant: null }`.
+ *
+ * @param {string|null|undefined} id
+ * @returns {{ base: string, variant: string|null }}
+ */
+function normalizeModelId(id) {
+  if (id == null) return { base: '', variant: null };
+  const s = String(id).trim();
+  if (s === '') return { base: '', variant: null };
+
+  const m = s.match(VARIANT_RE);
+  if (m) {
+    const variant = m[1].trim().toLowerCase();
+    const base = s.slice(0, m.index).trim();
+    return { base, variant: variant === '' ? null : variant };
+  }
+  return { base: s, variant: null };
+}
+
+/**
+ * tierForModelId(id) → 'opus' | 'sonnet' | 'haiku' | null
+ *
+ * Resolution order:
+ *   (a) normalize → work on `base`;
+ *   (b) exact match in KNOWN_TIER_BY_ID;
+ *   (c) family-pattern: base contains the tier word as a token;
+ *   (d) ALIAS_MAP (families whose id omits the tier word);
+ *   (e) otherwise null — UNKNOWN. Callers must price conservatively + loudly,
+ *       NOT treat null as a tier.
+ *
+ * @param {string|null|undefined} id
+ * @returns {'opus'|'sonnet'|'haiku'|null}
+ */
+function tierForModelId(id) {
+  const { base } = normalizeModelId(id);
+  if (base === '') return null;
+
+  // (b) exact known-id pin
+  if (Object.prototype.hasOwnProperty.call(KNOWN_TIER_BY_ID, base)) {
+    return KNOWN_TIER_BY_ID[base];
+  }
+
+  // (c) family-pattern (tier word appears as a token in the id)
+  const fam = base.match(FAMILY_RE);
+  if (fam) return fam[1];
+
+  // (d) alias for families whose id omits the tier word
+  if (Object.prototype.hasOwnProperty.call(ALIAS_MAP, base)) {
+    return ALIAS_MAP[base];
+  }
+
+  // (e) unknown → null (conservative pricing + loud warning is the caller's job)
+  return null;
+}
+
+module.exports = { normalizeModelId, tierForModelId, KNOWN_TIER_BY_ID, ALIAS_MAP };