@mcptoolshop/style-dataset-lab 3.0.0 → 3.0.1

package/lib/training-manifests.js

@@ -12,8 +12,9 @@ import { existsSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadExport } from './export.js';
 import { loadTrainingProfile } from './training-profiles.js';
-import { computeConfigFingerprint } from './snapshot.js';
+import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
 import { listEvalPacks } from './eval-pack.js';
+import { inputError } from './errors.js';
 
 /**
  * Generate a training manifest ID: tm-YYYYMMDD-HHMMSS-XXXX
@@ -64,6 +65,8 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
 
   const manifestId = generateManifestId();
   const manifest = {
+    // DB-001 / DB-006: stamp manifest schema version
+    schema_version: SCHEMA_VERSION,
     training_manifest_id: manifestId,
     created_at: new Date().toISOString(),
     created_by: 'sdlab-training-manifest-v1',
@@ -89,7 +92,16 @@ export async function createTrainingManifest(projectRoot, exportId, profileId, o
   // Write manifest
   const dir = join(projectRoot, 'training', 'manifests');
   await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, `${manifestId}.json`), JSON.stringify(manifest, null, 2) + '\n');
+  const manifestPath = join(dir, `${manifestId}.json`);
+  // D-005: refuse to silently overwrite on ID collision.
+  if (existsSync(manifestPath)) {
+    throw inputError(
+      'TRAINING_MANIFEST_ID_COLLISION',
+      `Training manifest file already exists: ${manifestPath}`,
+      'Retry to generate a fresh manifest ID.',
+    );
+  }
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
 
   return { manifestId, exportId, profileId };
 }
@@ -139,7 +151,9 @@ export async function loadTrainingManifest(projectRoot, manifestId) {
   if (!existsSync(path)) {
     throw new Error(`Training manifest "${manifestId}" not found at ${path}`);
   }
-  return JSON.parse(await readFile(path, 'utf-8'));
+  const manifest = JSON.parse(await readFile(path, 'utf-8'));
+  checkManifestVersion(manifest, 'training-manifest');
+  return manifest;
 }
 
 /**

package/lib/training-packages.js

@@ -15,6 +15,8 @@ import { loadTrainingProfile } from './training-profiles.js';
 import { loadSplitPartition } from './split.js';
 import { loadRecord } from './records.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
+import { inputError } from './errors.js';
+import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
 
 /**
  * Generate a training package ID: tp-YYYYMMDD-HHMMSS-XXXX
@@ -63,6 +65,14 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   const recordsDir = join(projectRoot, 'records');
   const packageId = generatePackageId();
   const packageDir = join(projectRoot, 'training', 'packages', packageId);
+  // D-005: refuse to silently overwrite on ID collision.
+  if (existsSync(packageDir)) {
+    throw inputError(
+      'TRAINING_PACKAGE_ID_COLLISION',
+      `Training package directory already exists: ${packageDir}`,
+      'Retry to generate a fresh package ID.',
+    );
+  }
 
   // Load split partitions
   const partitions = {};
@@ -105,19 +115,10 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
 
   totalImages = adapterResult.imageCount || 0;
 
-  // Generate checksums for all files in the package
-  const checksumEntries = [];
-  const allFiles = await collectFiles(packageDir);
-  for (const filePath of allFiles.sort()) {
-    const relPath = relative(packageDir, filePath);
-    if (relPath === 'checksums.txt') continue;
-    const hash = await sha256File(filePath);
-    checksumEntries.push(`SHA256 (${relPath}) = ${hash}`);
-  }
-  await writeFile(join(packageDir, 'checksums.txt'), checksumEntries.join('\n') + '\n');
-
-  // Write package manifest (last — references everything)
+  // D-015: Write manifest + README FIRST so they are covered by checksums.
   const packageManifest = {
+    // DB-001 / DB-006: stamp manifest schema version
+    schema_version: SCHEMA_VERSION,
     training_package_id: packageId,
     created_at: new Date().toISOString(),
     created_by: 'sdlab-training-package-v1',
@@ -134,7 +135,7 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
       val: partitions.val.length,
       test: partitions.test.length,
       images: totalImages,
-      checksums: checksumEntries.length,
+      checksums: 0, // updated after checksum pass below
     },
   };
   await writeFile(join(packageDir, 'manifest.json'), JSON.stringify(packageManifest, null, 2) + '\n');
@@ -143,6 +144,17 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
   const readme = generatePackageReadme(packageManifest, profile, manifest, adapterTarget);
   await writeFile(join(packageDir, 'README.md'), readme);
 
+  // Generate checksums AFTER manifest+README are on disk so they are included.
+  const checksumEntries = [];
+  const allFiles = await collectFiles(packageDir);
+  for (const filePath of allFiles.sort()) {
+    const relPath = relative(packageDir, filePath);
+    if (relPath === 'checksums.txt') continue;
+    const hash = await sha256File(filePath);
+    checksumEntries.push(`SHA256 (${relPath}) = ${hash}`);
+  }
+  await writeFile(join(packageDir, 'checksums.txt'), checksumEntries.join('\n') + '\n');
+
   return { packageId, records: totalRecords, images: totalImages };
 }
 
@@ -237,5 +249,7 @@ export async function loadTrainingPackage(projectRoot, packageId) {
   if (!existsSync(path)) {
     throw new Error(`Training package "${packageId}" not found at ${path}`);
   }
-  return JSON.parse(await readFile(path, 'utf-8'));
+  const manifest = JSON.parse(await readFile(path, 'utf-8'));
+  checkManifestVersion(manifest, 'training-package');
+  return manifest;
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Canon-aligned dataset production and generation workbench — define visual rules, build versioned training data, compile production briefs, run local workflows, batch-produce, select winners, and re-ingest into your corpus",
   "type": "module",
   "bin": {
     "sdlab": "./bin/sdlab.js"
   },
   "scripts": {
+    "test": "node --test tests/**/*.test.js",
     "verify": "node bin/sdlab.js --help && node bin/sdlab.js project doctor --project star-freight",
     "generate": "node scripts/generate.js",
     "curate": "node scripts/curate.js",
@@ -19,11 +20,16 @@
     "bin/",
     "lib/",
     "scripts/",
+    "!scripts/bulk-curate-*.js",
+    "!scripts/curate-wave*.js",
+    "!scripts/migrate-records.js",
     "templates/",
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
   ],
   "keywords": [
     "dataset",

package/scripts/batch-generate.js

@@ -9,7 +9,7 @@
  *   sdlab batch generate --mode silhouette-pack --project star-freight --dry-run
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot, getRunsDir } from '../lib/paths.js';
 import { compileBatch } from '../lib/batch-compiler.js';
 import { getBatchMode } from '../lib/batch-modes.js';
@@ -19,14 +19,14 @@ import {
   saveBatchManifest,
 } from '../lib/batch-runs.js';
 import { renderSheetHTML, saveSheet } from '../lib/batch-sheet-render.js';
-import { info } from '../lib/log.js';
+import { info, result } from '../lib/log.js';
 import { join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       mode: { type: 'string' },
       subject: { type: 'string' },
       theme: { type: 'string' },
@@ -50,7 +50,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const dryRun = flags['dry-run'] || false;
 
@@ -79,9 +79,10 @@ export async function run(argv = process.argv.slice(2)) {
 
   // 2. Create batch directory
   const { batchId, batchDir } = await createBatchDir(projectRoot);
-  info(`Batch: ${batchId}`);
+  info('batch-generate', `Batch: ${batchId}`);
 
   // 3. Execute runs
+  const batchStartMs = Date.now();
   const results = await executeBatchRuns({
     projectRoot,
     projectName,
@@ -90,6 +91,12 @@ export async function run(argv = process.argv.slice(2)) {
     slotBriefs,
     dryRun,
   });
+  const batchElapsedMs = Date.now() - batchStartMs;
+  if (!dryRun && results.length > 0) {
+    const avgSec = Math.round(batchElapsedMs / results.length / 1000);
+    const totalSec = Math.round(batchElapsedMs / 1000);
+    info('batch-generate', `Completed ${results.length} slot(s) in ${totalSec}s (avg ${avgSec}s/slot)`);
+  }
 
   // 4. Build manifest
   const manifest = {
@@ -161,7 +168,9 @@ export async function run(argv = process.argv.slice(2)) {
       console.log(`  ${status} ${r.label.padEnd(24)} → ${r.run_id}  ${r.selected_output || '(dry run)'}`);
     }
     console.log('');
-    info(`Sheet: batches/${batchId}/sheets/primary-sheet.html`);
-    info(`Manifest: batches/${batchId}/manifest.json`);
+    // Primary artifact paths — always print (survives --quiet) so pipelines
+    // can parse the output location.
+    result(`Sheet: batches/${batchId}/sheets/primary-sheet.html`);
+    result(`Manifest: batches/${batchId}/manifest.json`);
   }
 }

package/scripts/batch-sheet.js

@@ -7,7 +7,7 @@
  *   sdlab batch sheet batch_2025-06-30_001 --project star-freight
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadBatchManifest } from '../lib/batch-runs.js';
 import { getBatchMode } from '../lib/batch-modes.js';
@@ -20,13 +20,13 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       batch: { type: 'string' },
     },
     deprecated: { game: 'project' },
   });
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const batchId = positionals[0] || flags.batch;
 

package/scripts/batch-show.js

@@ -9,21 +9,21 @@
  *   sdlab batch show batch_2025-06-30_001 --json     # as JSON
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { listBatches, loadBatchManifest } from '../lib/batch-runs.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       batch: { type: 'string' },
       json: { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const batchId = positionals[0] || flags.batch;
 

package/scripts/brief-compile.js

@@ -10,7 +10,7 @@
  *   sdlab brief compile --project star-freight --workflow character-portrait-set --subject kael_maren --output-count 8 --json
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { compileBrief, saveCompiledBrief } from '../lib/brief-compiler.js';
 import { info } from '../lib/log.js';
@@ -18,7 +18,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       workflow: { type: 'string' },
       subject: { type: 'string' },
       asset: { type: 'string' },
@@ -58,7 +58,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   // Parse reference IDs
@@ -68,11 +68,11 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Parse overrides
   const overrides = {};
-  if (flags['output-count']) overrides.output_count = parseInt(flags['output-count'], 10);
-  if (flags.width) overrides.width = parseInt(flags.width, 10);
-  if (flags.height) overrides.height = parseInt(flags.height, 10);
-  if (flags.steps) overrides.steps = parseInt(flags.steps, 10);
-  if (flags.cfg) overrides.cfg = parseFloat(flags.cfg);
+  if (flags['output-count']) overrides.output_count = parseNumberFlag('output-count', flags['output-count'], { int: true, min: 1 });
+  if (flags.width) overrides.width = parseNumberFlag('width', flags.width, { int: true, min: 1 });
+  if (flags.height) overrides.height = parseNumberFlag('height', flags.height, { int: true, min: 1 });
+  if (flags.steps) overrides.steps = parseNumberFlag('steps', flags.steps, { int: true, min: 1 });
+  if (flags.cfg) overrides.cfg = parseNumberFlag('cfg', flags.cfg, { min: 0 });
   if (flags.sampler) overrides.sampler = flags.sampler;
   if (flags['seed-mode']) overrides.seed_mode = flags['seed-mode'];
 

package/scripts/brief-show.js

@@ -9,7 +9,7 @@
  *   sdlab brief show brief_2026-04-15_001 --md
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadCompiledBrief } from '../lib/brief-compiler.js';
 import { renderBriefText, renderBriefMarkdown } from '../lib/brief-render.js';
@@ -17,7 +17,7 @@ import { renderBriefText, renderBriefMarkdown } from '../lib/brief-render.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       json: { type: 'boolean' },
       md: { type: 'boolean' },
     },
@@ -31,7 +31,8 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectRoot = getProjectRoot(flags.project);
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
   const brief = await loadCompiledBrief(projectRoot, briefId);
 
   if (flags.json) {

package/scripts/canon-bind.js

@@ -21,6 +21,7 @@ import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
 import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 
 /**
  * Build rationale string from rule's template, interpolating variables.
@@ -162,10 +163,10 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Load project config — fail loudly if missing
   if (!existsSync(join(PROJECT_ROOT, 'constitution.json'))) {
-    throw new Error(
-      `No constitution.json found in ${PROJECT_ROOT}.\n` +
-      `Canon binding requires per-project config files.\n` +
-      `Run: sdlab init ${projectName} --domain <domain>`
+    throw inputError(
+      'INPUT_MISSING_CONFIG',
+      `No constitution.json found in ${PROJECT_ROOT}.`,
+      `Canon binding requires per-project config files. Run: sdlab init ${projectName} --domain <domain>`
     );
   }
 
@@ -175,7 +176,7 @@ export async function run(argv = process.argv.slice(2)) {
   const termConfig = loadTerminology(PROJECT_ROOT);
 
   if (!constitutionConfig.rules || constitutionConfig.rules.length === 0) {
-    throw new Error(`constitution.json has no rules — cannot bind.`);
+    throw inputError('INPUT_EMPTY_CONFIG', `constitution.json has no rules — cannot bind.`);
   }
 
   const constitutionRules = constitutionConfig.rules;
@@ -280,8 +281,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('canon-bind.js') || process.argv[1].endsWith('canon-bind'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/card.js

@@ -4,43 +4,44 @@
  * card.js — Generate dataset cards.
  *
  * Usage:
- *   sdlab card generate --snapshot <id> --split <id> [--project <name>]
+ *   sdlab card generate [--snapshot <id>] [--split <id>] [--project <name>]
  */
 
 import { join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { listSnapshots } from '../lib/snapshot.js';
 import { listSplits } from '../lib/split.js';
 import { generateCard } from '../lib/card.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      snapshot: { type: 'string' },
+      split: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'generate';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'generate';
 
   if (subcommand === 'generate') {
-    // Find snapshot
-    let snapshotId;
-    const snapIdx = args.indexOf('--snapshot');
-    if (snapIdx >= 0) {
-      snapshotId = args[snapIdx + 1];
-    } else {
+    let snapshotId = flags.snapshot;
+    if (!snapshotId) {
       const snapshots = await listSnapshots(projectRoot);
-      if (snapshots.length === 0) throw new Error('No snapshots found. Run: sdlab snapshot create');
+      if (snapshots.length === 0) throw inputError('INPUT_NO_SNAPSHOT', 'No snapshots found. Run: sdlab snapshot create');
       snapshotId = snapshots[snapshots.length - 1].id;
     }
 
-    // Find split
-    let splitId;
-    const splitIdx = args.indexOf('--split');
-    if (splitIdx >= 0) {
-      splitId = args[splitIdx + 1];
-    } else {
+    let splitId = flags.split;
+    if (!splitId) {
       const splits = await listSplits(projectRoot);
-      if (splits.length === 0) throw new Error('No splits found. Run: sdlab split build');
+      if (splits.length === 0) throw inputError('INPUT_NO_SPLIT', 'No splits found. Run: sdlab split build');
       splitId = splits[splits.length - 1].id;
     }
 
@@ -51,7 +52,6 @@ export async function run(argv = process.argv.slice(2)) {
 
     const { markdown, json } = await generateCard(projectRoot, snapshotId, splitId);
 
-    // Write to project root
     const mdPath = join(projectRoot, 'dataset-card.md');
     const jsonPath = join(projectRoot, 'dataset-card.json');
     await writeFile(mdPath, markdown);
@@ -61,13 +61,10 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  \x1b[32m✓\x1b[0m dataset-card.json`);
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: generate`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: generate`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('card.js') || process.argv[1].endsWith('card'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

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

@@ -9,7 +9,7 @@
  *   sdlab critique show --project star-freight --run run_2026-04-15_001 --md
  */
 
-import { parseArgs } from '../lib/args.js';
+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';
@@ -17,7 +17,7 @@ import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-rend
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       json: { type: 'boolean' },
       md: { type: 'boolean' },
@@ -35,7 +35,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   const report = loadCritique(projectRoot, flags.run);

package/scripts/critique.js

@@ -8,7 +8,7 @@
  *   sdlab critique --project star-freight --run run_2026-04-15_001 --json
  */
 
-import { parseArgs } from '../lib/args.js';
+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';
@@ -17,7 +17,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       json: { type: 'boolean' },
     },
@@ -33,7 +33,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   console.log(`\x1b[1mstyle-dataset-lab\x1b[0m critique`);