@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/scripts/compare.js

@@ -8,62 +8,70 @@
  *   sdlab compare iron_sword_base iron_sword_icon_mid a "Better silhouette" --project star-freight
  */
 
-import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
+import { writeFile, readdir, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName } from "../lib/args.js";
+import { parseArgs, getProjectName } from "../lib/args.js";
 import { REPO_ROOT } from "../lib/paths.js";
-
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { readJsonFile } from "../lib/config.js";
+import { inputError, handleCliError } from "../lib/errors.js";
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
-
-  // Strip --project/--game and their values from positional parsing
-  const args = argv.filter((a, i) => {
-    if (a === '--project' || a === '--game') return false;
-    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
-    return true;
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      scores: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
   });
 
-  const [assetAId, assetBId, winner, ...reasonParts] = args;
+  const projectName = flags.project || getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+
+  const [assetAId, assetBId, winner, ...reasonParts] = positionals;
 
   if (!assetAId || !assetBId || !winner) {
-    throw new Error("Usage: sdlab compare <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>");
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'Usage: sdlab compare <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>'
+    );
   }
 
   if (!["a", "b", "tie"].includes(winner)) {
-    throw new Error(`Invalid winner: ${winner}. Must be a, b, or tie.`);
+    throw inputError(
+      'INPUT_BAD_WINNER',
+      `Invalid winner: ${winner}. Must be a, b, or tie.`
+    );
   }
 
-  const reasoning = reasonParts.filter(r => !r.startsWith('--')).join(" ") || null;
+  const reasoning = reasonParts.join(" ") || null;
 
   // Load records to get paths
   const recordA = await loadRecord(GAME_ROOT, assetAId);
   const recordB = await loadRecord(GAME_ROOT, assetBId);
 
   if (!recordA || !recordB) {
-    throw new Error("Could not load one or both records.");
+    throw inputError('INPUT_UNKNOWN_RECORD', 'Could not load one or both records.');
   }
 
   // Parse optional scores
-  const scoresStr = getFlagValue(args, "scores");
+  const scoresStr = flags.scores;
   const criteria_scores = {};
   if (scoresStr) {
     for (const pair of scoresStr.split(",")) {
       const [k, v] = pair.split(":");
       // Format: "silhouette:0.9/0.6" → { silhouette: { a: 0.9, b: 0.6 } }
       if (k && v) {
-        const [aScore, bScore] = v.split("/");
-        criteria_scores[k.trim()] = { a: parseFloat(aScore), b: parseFloat(bScore) };
+        const [aStr, bStr] = v.split("/");
+        const aScore = parseFloat(aStr);
+        const bScore = parseFloat(bStr);
+        if (!Number.isFinite(aScore) || !Number.isFinite(bScore)) {
+          throw inputError(
+            'INPUT_BAD_SCORE',
+            `Score for "${k.trim()}" is not numeric: "${v}"`,
+            'Use the form --scores silhouette:0.9/0.6,palette:0.8/0.7'
+          );
+        }
+        criteria_scores[k.trim()] = { a: aScore, b: bScore };
       }
     }
   }
@@ -101,7 +109,7 @@ export async function run(argv = process.argv.slice(2)) {
 async function loadRecord(GAME_ROOT, id) {
   try {
     const path = join(GAME_ROOT, `records/${id}.json`);
-    return JSON.parse(await readFile(path, "utf-8"));
+    return await readJsonFile(path);
   } catch {
     console.error(`Record not found: records/${id}.json`);
     return null;
@@ -119,8 +127,5 @@ async function countComparisons(GAME_ROOT) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('compare.js') || process.argv[1].endsWith('compare'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/critique-show.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * critique-show.js — Display a saved critique report.
+ *
+ * Usage:
+ *   sdlab critique show --project star-freight --run run_2026-04-15_001
+ *   sdlab critique show --project star-freight --run run_2026-04-15_001 --json
+ *   sdlab critique show --project star-freight --run run_2026-04-15_001 --md
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { loadCritique } from '../lib/critique-engine.js';
+import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-render.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      run: { type: 'string' },
+      json: { type: 'boolean' },
+      md: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.run) {
+    console.log('Usage: sdlab critique show --run <id> [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --run <id>        Run ID (required)');
+    console.log('  --json            Output raw JSON');
+    console.log('  --md              Output full Markdown');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+
+  const report = loadCritique(projectRoot, flags.run);
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (flags.md) {
+    console.log(renderCritiqueMarkdown(report));
+  } else {
+    console.log(renderCritiqueText(report));
+  }
+}

package/scripts/critique.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/**
+ * critique.js — Generate a critique report for a completed run.
+ *
+ * Usage:
+ *   sdlab critique --project star-freight --run run_2026-04-15_001
+ *   sdlab critique --project star-freight --run run_2026-04-15_001 --json
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { critiqueRun, saveCritique } from '../lib/critique-engine.js';
+import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-render.js';
+import { info } from '../lib/log.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      run: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.run) {
+    console.log('Usage: sdlab critique --run <id> [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --run <id>        Run to critique (required)');
+    console.log('  --json            Output raw JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m critique`);
+  console.log(`  Project: ${projectName}`);
+  console.log(`  Run: ${flags.run}`);
+  console.log('');
+
+  // Generate critique
+  const report = await critiqueRun({
+    projectRoot,
+    projectId: projectName,
+    runId: flags.run,
+  });
+
+  // Save
+  const md = renderCritiqueMarkdown(report);
+  await saveCritique(projectRoot, flags.run, report, md);
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderCritiqueText(report));
+    const action = report.recommended_action;
+    console.log(`Critique saved to: runs/${flags.run}/critique.json`);
+
+    if (action.mode === 'refine_from_one' && action.preferred_candidate) {
+      console.log('');
+      info(`Next: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate}`);
+    } else if (action.mode === 'accept_one' && action.preferred_candidate) {
+      console.log('');
+      info(`Preferred candidate: ${action.preferred_candidate}`);
+    }
+  }
+}

package/scripts/curate.js

@@ -7,59 +7,73 @@
  *   node scripts/curate.js <asset_id> approved "Clean silhouette, correct palette" --scores silhouette:0.9,palette:0.8
  *   node scripts/curate.js <asset_id> rejected "3D render look, alpha halo" --failures alpha_halo,3d_render_look
  *   node scripts/curate.js --list  (show uncurated candidates)
- *   sdlab curate <asset_id> approved "explanation" --project star-freight
+ *   sdlab curate <asset_id> approved "explanation" --project star-freight [--dry-run]
  */
 
-import { readFile, writeFile, rename, readdir, mkdir } from "node:fs/promises";
+import { writeFile, rename, readdir, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName } from "../lib/args.js";
+import { parseArgs, getProjectName } from "../lib/args.js";
 import { REPO_ROOT } from "../lib/paths.js";
-
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { readJsonFile } from "../lib/config.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
+import { result } from "../lib/log.js";
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
-
-  // Strip --project/--game and their values from positional parsing
-  const args = argv.filter((a, i) => {
-    if (a === '--project' || a === '--game') return false;
-    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
-    return true;
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      scores: { type: 'string' },
+      failures: { type: 'string' },
+      notes: { type: 'string' },
+      list: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
   });
 
-  if (args.includes("--list")) {
+  const projectName = flags.project || getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+
+  if (flags.list) {
     return listUncurated(GAME_ROOT);
   }
 
-  const [assetId, status, explanation, ...rest] = args;
+  const [assetId, status, explanation] = positionals;
 
   if (!assetId || !status || !explanation) {
-    throw new Error("Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2] [--dry-run]'
+    );
   }
 
   if (!["approved", "rejected", "borderline"].includes(status)) {
-    throw new Error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
+    throw inputError(
+      'INPUT_BAD_STATUS',
+      `Invalid status: ${status}. Must be approved, rejected, or borderline.`
+    );
   }
 
-  // Parse optional flags
-  const scoresStr = getFlagValue(rest, "scores");
-  const failuresStr = getFlagValue(rest, "failures");
-  const notesStr = getFlagValue(rest, "notes");
+  const scoresStr = flags.scores;
+  const failuresStr = flags.failures;
+  const notesStr = flags.notes;
 
   const criteria_scores = {};
   if (scoresStr) {
     for (const pair of scoresStr.split(",")) {
       const [k, v] = pair.split(":");
-      if (k && v) criteria_scores[k.trim()] = parseFloat(v);
+      if (k && v) {
+        const score = parseFloat(v);
+        if (!Number.isFinite(score)) {
+          throw inputError(
+            'INPUT_BAD_SCORE',
+            `Score value for "${k.trim()}" is not a number: "${v}"`,
+            'Use the form --scores silhouette:0.9,palette:0.8'
+          );
+        }
+        criteria_scores[k.trim()] = score;
+      }
     }
   }
 
@@ -69,17 +83,44 @@ export async function run(argv = process.argv.slice(2)) {
   const recordPath = join(GAME_ROOT, `records/${assetId}.json`);
   let record;
   try {
-    record = JSON.parse(await readFile(recordPath, "utf-8"));
-  } catch {
-    throw new Error(`Record not found: ${recordPath}`);
+    record = await readJsonFile(recordPath);
+  } catch (err) {
+    if (err && err.code === 'INPUT_FILE_NOT_FOUND') {
+      throw inputError('INPUT_UNKNOWN_RECORD', `Record not found: ${recordPath}`);
+    }
+    throw err;
   }
 
-  // Update record first (write before move to avoid orphaned images)
-  const oldPath = join(GAME_ROOT, record.asset_path);
+  const originalAssetPath = record.asset_path;
+  const oldPath = join(GAME_ROOT, originalAssetPath);
   const newDir = `outputs/${status}`;
   const newPath = `${newDir}/${assetId}.png`;
+  const newFullPath = join(GAME_ROOT, newPath);
+
+  if (dryRun) {
+    console.log(`\x1b[33m(dry-run)\x1b[0m ${assetId}`);
+    console.log(`  status: ${status}`);
+    console.log(`  move:   ${originalAssetPath} -> ${newPath}`);
+    console.log(`  note:   ${explanation}`);
+    if (failure_modes.length) console.log(`  failures: ${failure_modes.join(", ")}`);
+    return;
+  }
+
   await mkdir(join(GAME_ROOT, newDir), { recursive: true });
 
+  // Move image FIRST — if the rename fails we still have a clean record.
+  try {
+    await rename(oldPath, newFullPath);
+  } catch (err) {
+    throw runtimeError(
+      'RUNTIME_MOVE_FAILED',
+      `Could not move ${oldPath} to ${newPath}: ${err.message}`,
+      'Check that the source image exists and the destination is writable.',
+      err
+    );
+  }
+
+  // Now safely update the record. If writing fails, try to restore the image.
   record.asset_path = newPath;
   record.judgment = {
     status,
@@ -92,16 +133,23 @@ export async function run(argv = process.argv.slice(2)) {
     confidence: 0.9,
   };
 
-  await writeFile(recordPath, JSON.stringify(record, null, 2));
-
-  // Move image file
   try {
-    await rename(oldPath, join(GAME_ROOT, newPath));
-  } catch {
-    throw new Error(`Could not move ${oldPath} to ${newPath}`);
+    await writeFile(recordPath, JSON.stringify(record, null, 2));
+  } catch (err) {
+    // Attempt rollback: put the image back.
+    try { await rename(newFullPath, oldPath); } catch {}
+    throw runtimeError(
+      'RUNTIME_WRITE_FAILED',
+      `Could not write record ${recordPath}: ${err.message}`,
+      null,
+      err
+    );
   }
 
-  console.log(`\x1b[32m✓\x1b[0m ${assetId} → ${status}`);
+  // Final artifact path — always shown, even under --quiet.
+  result('curate', `${assetId} → ${status}`);
+  result(`  image: ${newPath}`);
+  result(`  record: records/${assetId}.json`);
   console.log(`  ${explanation}`);
   if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
 }
@@ -135,8 +183,5 @@ async function listUncurated(GAME_ROOT) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('curate.js') || process.argv[1].endsWith('curate'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/doctor.js

@@ -15,6 +15,7 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { runtimeError, handleCliError } from '../lib/errors.js';
 
 const REQUIRED_CONFIG_FILES = [
   'project.json',
@@ -41,6 +42,13 @@ const REQUIRED_DIRS = [
   'training/packages',
   'training/eval-runs',
   'training/implementations',
+  'workflows/profiles',
+  'workflows/batch-modes',
+  'briefs',
+  'runs',
+  'batches',
+  'selections',
+  'inbox/generated',
 ];
 
 function pass(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }
@@ -284,7 +292,168 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  // ── 9. Records sanity check ──
+  // ── 9. Workflow profile validation ──
+  const workflowDir = join(projectDir, 'workflows', 'profiles');
+  if (existsSync(workflowDir)) {
+    console.log('');
+    const wfFiles = readdirSync(workflowDir).filter(f => f.endsWith('.json'));
+    if (wfFiles.length > 0) {
+      const VALID_SUBJECT_MODES = ['required', 'optional', 'forbidden'];
+      const VALID_OUTPUT_MODES = ['portrait_set', 'expression_sheet', 'variant_pack', 'moodboard', 'silhouette_sheet', 'turnaround'];
+      const laneIds = new Set((lanes?.lanes || []).map(l => l.id));
+
+      let wfErrors = 0;
+      for (const file of wfFiles) {
+        const { data, error } = tryParseJson(join(workflowDir, file));
+        if (error) { fail(`workflows/profiles/${file} — invalid JSON: ${error}`); wfErrors++; continue; }
+
+        const missing = ['workflow_id', 'label', 'lane_id', 'output_mode', 'output_count',
+          'prompt_strategy', 'negative_strategy', 'canon_focus', 'drift_guards', 'runtime_defaults']
+          .filter(f => data[f] === undefined || data[f] === null);
+        if (missing.length > 0) {
+          fail(`workflows/profiles/${file} — missing fields: ${missing.join(', ')}`);
+          wfErrors++;
+          continue;
+        }
+
+        if (data.lane_id && laneIds.size > 0 && !laneIds.has(data.lane_id)) {
+          fail(`workflows/profiles/${file} — lane_id "${data.lane_id}" not found in lanes.json`);
+          wfErrors++;
+        }
+
+        if (data.subject_mode && !VALID_SUBJECT_MODES.includes(data.subject_mode)) {
+          fail(`workflows/profiles/${file} — invalid subject_mode "${data.subject_mode}"`);
+          wfErrors++;
+        }
+
+        if (!VALID_OUTPUT_MODES.includes(data.output_mode)) {
+          fail(`workflows/profiles/${file} — invalid output_mode "${data.output_mode}"`);
+          wfErrors++;
+        }
+
+        const ps = data.prompt_strategy;
+        if (!ps || !Array.isArray(ps.style_prefix) || !ps.structure || !Array.isArray(ps.must_include)) {
+          fail(`workflows/profiles/${file} — prompt_strategy needs style_prefix[], structure, must_include[]`);
+          wfErrors++;
+        }
+
+        const ns = data.negative_strategy;
+        if (!ns || !Array.isArray(ns.must_avoid)) {
+          fail(`workflows/profiles/${file} — negative_strategy needs must_avoid[]`);
+          wfErrors++;
+        }
+
+        if (!data.runtime_defaults?.adapter_target) {
+          fail(`workflows/profiles/${file} — runtime_defaults needs adapter_target`);
+          wfErrors++;
+        }
+      }
+
+      if (wfErrors === 0) {
+        pass(`${wfFiles.length} workflow profiles — all valid`);
+        passes++;
+      } else {
+        failures += wfErrors;
+      }
+    } else {
+      pass('workflows/profiles/ — empty (no workflows yet)');
+      passes++;
+    }
+  }
+
+  // ── 10. Batch mode validation ──
+  const batchModesDir = join(projectDir, 'workflows', 'batch-modes');
+  if (existsSync(batchModesDir)) {
+    console.log('');
+    const bmFiles = readdirSync(batchModesDir).filter(f => f.endsWith('.json'));
+    if (bmFiles.length > 0) {
+      const VALID_BATCH_TYPES = ['expression_sheet', 'environment_board', 'silhouette_pack', 'continuity_variants'];
+      const VALID_SUBJECT_MODES_BM = ['required', 'optional', 'forbidden'];
+      const VALID_LAYOUTS = ['grid', 'moodboard', 'strip', 'freeform'];
+      const wfFiles = existsSync(join(projectDir, 'workflows', 'profiles'))
+        ? readdirSync(join(projectDir, 'workflows', 'profiles')).filter(f => f.endsWith('.json')).map(f => f.replace('.json', ''))
+        : [];
+
+      let bmErrors = 0;
+      for (const file of bmFiles) {
+        const { data, error } = tryParseJson(join(batchModesDir, file));
+        if (error) { fail(`workflows/batch-modes/${file} — invalid JSON: ${error}`); bmErrors++; continue; }
+
+        if (!data.mode_id) { fail(`workflows/batch-modes/${file} — missing mode_id`); bmErrors++; }
+        if (!data.batch_type || !VALID_BATCH_TYPES.includes(data.batch_type)) {
+          fail(`workflows/batch-modes/${file} — invalid batch_type "${data.batch_type}"`);
+          bmErrors++;
+        }
+        if (data.subject_mode && !VALID_SUBJECT_MODES_BM.includes(data.subject_mode)) {
+          fail(`workflows/batch-modes/${file} — invalid subject_mode "${data.subject_mode}"`);
+          bmErrors++;
+        }
+        if (data.base_workflow_id && wfFiles.length > 0 && !wfFiles.includes(data.base_workflow_id)) {
+          fail(`workflows/batch-modes/${file} — base_workflow_id "${data.base_workflow_id}" not found in profiles`);
+          bmErrors++;
+        }
+        if (!Array.isArray(data.variant_plan) || data.variant_plan.length === 0) {
+          fail(`workflows/batch-modes/${file} — variant_plan must be non-empty array`);
+          bmErrors++;
+        } else {
+          const slotIds = data.variant_plan.map(s => s.slot_id);
+          const dupes = slotIds.filter((id, i) => slotIds.indexOf(id) !== i);
+          if (dupes.length > 0) {
+            fail(`workflows/batch-modes/${file} — duplicate slot_ids: ${[...new Set(dupes)].join(', ')}`);
+            bmErrors++;
+          }
+        }
+        if (data.assembly?.layout && !VALID_LAYOUTS.includes(data.assembly.layout)) {
+          fail(`workflows/batch-modes/${file} — invalid assembly.layout "${data.assembly.layout}"`);
+          bmErrors++;
+        }
+      }
+
+      if (bmErrors === 0) {
+        pass(`${bmFiles.length} batch modes — all valid`);
+        passes++;
+      } else {
+        failures += bmErrors;
+      }
+    } else {
+      pass('workflows/batch-modes/ — empty (no batch modes yet)');
+      passes++;
+    }
+  }
+
+  // ── 11. Runtime templates check ──
+  {
+    console.log('');
+    const runtimeDir = join(REPO_ROOT, 'runtime', 'comfyui');
+    if (existsSync(runtimeDir)) {
+      const templateFiles = readdirSync(runtimeDir).filter(f => f.endsWith('.json'));
+      if (templateFiles.length > 0) {
+        let templateErrors = 0;
+        for (const file of templateFiles) {
+          const { data, error } = tryParseJson(join(runtimeDir, file));
+          if (error) { fail(`runtime/comfyui/${file}: invalid JSON — ${error}`); templateErrors++; continue; }
+          if (!data.template_id) { fail(`runtime/comfyui/${file}: missing template_id`); templateErrors++; }
+          if (!data.compatible_modes || !Array.isArray(data.compatible_modes)) {
+            fail(`runtime/comfyui/${file}: missing compatible_modes[]`); templateErrors++;
+          }
+        }
+        if (templateErrors === 0) {
+          pass(`${templateFiles.length} runtime templates — all valid`);
+          passes++;
+        } else {
+          failures += templateErrors;
+        }
+      } else {
+        warn('runtime/comfyui/ — no templates found');
+        warnings++;
+      }
+    } else {
+      warn('runtime/comfyui/ — directory not found');
+      warnings++;
+    }
+  }
+
+  // ── 12. Records sanity check ──
   const recordsDir = join(projectDir, 'records');
   if (existsSync(recordsDir)) {
     console.log('');
@@ -316,14 +485,11 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`═══ ${status} — ${passes} passed, ${failures} failed, ${warnings} warnings ═══`);
 
   if (failures > 0) {
-    throw new Error(`Project "${projectName}" has ${failures} issue(s).`);
+    throw runtimeError('PROJECT_UNHEALTHY', `Project "${projectName}" has ${failures} issue(s).`);
   }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('doctor.js') || process.argv[1].endsWith('doctor'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }