@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/scripts/colab/remote_runner.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Remote kernel runner executed via `colab exec -s <session> -f remote_runner.py`.
+
+Runs the uploaded remote shell script (`SDLAB_REMOTE_SCRIPT`, e.g.
+`/content/remote_lane1_stub.sh` or `/content/remote_lane3_stub.sh`) via
+`subprocess.Popen`, streaming each stdout/stderr line to the IPython kernel's
+stdout as it arrives so the rig's vitals and DEAD HARNESS watcher read it in
+real time, and finishes by printing a `SDLAB_REMOTE_RC=<rc>` marker line.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+
+
+def _resolve_bash(env: dict[str, str]) -> str:
+    git_bash = "C:/Program Files/Git/bin/bash.exe"
+    if os.name == "nt" and os.path.exists(git_bash):
+        return git_bash
+    found = shutil.which("bash", path=env.get("PATH"))
+    return found or "bash"
+
+
+def run_remote_script(
+    script_path: str | None = None,
+    *,
+    env: dict[str, str] | None = None,
+) -> int:
+    effective_env = dict(os.environ if env is None else env)
+    target_script = script_path or effective_env.get("SDLAB_REMOTE_SCRIPT", "").strip()
+    if not target_script:
+        print("REFUSED: SDLAB_REMOTE_SCRIPT is required", file=sys.stderr, flush=True)
+        print("SDLAB_REMOTE_RC=2", flush=True)
+        return 2
+
+    cmd = [_resolve_bash(effective_env), target_script]
+    proc = subprocess.Popen(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+        env=effective_env,
+    )
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+    rc = int(proc.wait())
+    print(f"SDLAB_REMOTE_RC={rc}", flush=True)
+    return rc
+
+
+if __name__ == "__main__":
+    run_remote_script()

package/scripts/compare.js

@@ -11,7 +11,7 @@
 import { writeFile, readdir, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parseArgs, getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectRoot } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, handleCliError } from "../lib/errors.js";
 
@@ -25,7 +25,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
 
   const [assetAId, assetBId, winner, ...reasonParts] = positionals;
 

package/scripts/critique.js

@@ -84,9 +84,24 @@ export async function run(argv = process.argv.slice(2)) {
     const action = report.recommended_action;
     console.log(`Critique saved to: runs/${flags.run}/critique.json`);
 
+    // H2: `refine_from_one` fires today purely from every candidate sitting
+    // at the unreviewed default overall_fit "usable" (nothing in the
+    // codebase currently sets it to anything else) — action.reviewed
+    // (lib/critique-engine.js recommendAction) distinguishes that from an
+    // actually-assessed run. Printing "Next: ..." with the same confidence
+    // either way presented brief-keyword drift tiebreaking as a considered
+    // recommendation. Qualify instead of suppressing outright — the pick is
+    // still a reasonable place to look first, it's just not a judgment.
     if (action.mode === 'refine_from_one' && action.preferred_candidate) {
       console.log('');
-      info(`Next: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate}`);
+      if (action.reviewed) {
+        info(`Next: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate}`);
+      } else {
+        info(`No candidate has been reviewed yet — every image is at the rule-based pass's default "usable" ` +
+          `until a human or LLM judge assesses fit.`);
+        info(`If you want to proceed anyway: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate} ` +
+          `(picked by fewest rule-based drift issues, not by looking at the image).`);
+      }
     } else if (action.mode === 'accept_one' && action.preferred_candidate) {
       console.log('');
       info(`Preferred candidate: ${action.preferred_candidate}`);

package/scripts/curate.js

@@ -13,7 +13,7 @@
 import { writeFile, rename, readdir, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parseArgs, getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectRoot } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { result } from "../lib/log.js";
@@ -35,7 +35,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const dryRun = flags['dry-run'] || flags.dryRun;
 
   if (flags.list) {

package/scripts/doctor.js

@@ -14,7 +14,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 { REPO_ROOT, getProjectRoot, getRuntimeDir } from '../lib/paths.js';
 import { runtimeError, handleCliError } from '../lib/errors.js';
 
 const REQUIRED_CONFIG_FILES = [
@@ -52,7 +52,16 @@ const REQUIRED_DIRS = [
 ];
 
 function pass(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }
-function fail(msg) { console.log(`  \x1b[31m✗\x1b[0m ${msg}`); }
+// M1: fail() carried no hint — every OTHER command in this CLI prints a
+// "Hint:" line (lib/errors.js handleCliError) when one is available, but
+// doctor's ~40 failure sites just dropped it on the floor. Doctor is the
+// tool people run when confused; its output IS the error-recovery story.
+// hint is optional so existing terse call sites (a handful of genuinely
+// self-explanatory failures) keep working unchanged.
+function fail(msg, hint) {
+  console.log(`  \x1b[31m✗\x1b[0m ${msg}`);
+  if (hint) console.log(`    \x1b[33mHint:\x1b[0m ${hint}`);
+}
 function warn(msg) { console.log(`  \x1b[33m⚠\x1b[0m ${msg}`); }
 
 function tryParseJson(filePath) {
@@ -65,7 +74,23 @@ function tryParseJson(filePath) {
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const projectDir = join(REPO_ROOT, 'projects', projectName);
+  // SDL-C3-completion: resolve through the hardened getProjectRoot() instead of
+  // a raw join(REPO_ROOT, 'projects', projectName) — the raw join let a
+  // --project value like "../../ai-eyes-mcp" escape the projects/ directory
+  // entirely (path traversal). getProjectRoot() rejects any name containing
+  // "/", "\" or ".." (INPUT_UNSAFE_PROJECT_NAME) and re-verifies containment,
+  // and throws INPUT_UNKNOWN_PROJECT (with the same "run sdlab init" hint this
+  // function used to print by hand) when the project does not exist.
+  //
+  // That second throw is also the SDL-C4 fix: this function used to check
+  // existence itself with `if (!existsSync(projectDir)) { fail(...); return; }`
+  // — a bare `return` that resolved the run() promise successfully, so
+  // handleCliError's process.exit() never ran and `sdlab project doctor
+  // --project <missing>` exited 0. getProjectRoot() throws instead of
+  // returning, so a missing project now rejects run() and reaches the CLI's
+  // normal nonzero-exit error path — the ANDON gate this command IS (it's
+  // exactly what `npm run verify` and the CI smoke-test step call).
+  const projectDir = getProjectRoot(projectName);
 
   console.log(`\x1b[1msdlab project doctor\x1b[0m — ${projectName}`);
   console.log(`  Path: ${projectDir}\n`);
@@ -75,11 +100,8 @@ export async function run(argv = process.argv.slice(2)) {
   let warnings = 0;
 
   // ── 1. Project directory exists ──
-  if (!existsSync(projectDir)) {
-    fail(`Project directory not found: ${projectDir}`);
-    console.log(`\n  Run: sdlab init ${projectName} --domain <domain>`);
-    return;
-  }
+  // Guaranteed true here — getProjectRoot() above already throws otherwise.
+  // Recorded as a pass so the check numbering below stays stable.
   pass('Project directory exists');
   passes++;
 
@@ -89,13 +111,17 @@ export async function run(argv = process.argv.slice(2)) {
   for (const file of REQUIRED_CONFIG_FILES) {
     const filePath = join(projectDir, file);
     if (!existsSync(filePath)) {
-      fail(`Missing: ${file}`);
+      fail(
+        `Missing: ${file}`,
+        `Run "sdlab init <name> --domain <domain>" to scaffold it, or hand-author ${file} — see ` +
+        `templates/domains/*/${file} for the expected shape.`
+      );
       failures++;
       continue;
     }
     const { data, error } = tryParseJson(filePath);
     if (error) {
-      fail(`${file} — invalid JSON: ${error}`);
+      fail(`${file} — invalid JSON: ${error}`, `Open ${filePath} and fix the syntax error above.`);
       failures++;
       continue;
     }
@@ -121,10 +147,11 @@ export async function run(argv = process.argv.slice(2)) {
   if (meta) {
     console.log('');
     if (meta.name) { pass(`project.json: name = "${meta.name}"`); passes++; }
-    else { fail('project.json: missing "name"'); failures++; }
+    else { fail('project.json: missing "name"', 'Add a top-level "name" field matching the project directory name.'); failures++; }
 
     if (meta.domain) { pass(`project.json: domain = "${meta.domain}"`); passes++; }
     else { warn('project.json: no "domain" set'); warnings++; }
+    if (meta.display_name === 'TEMPLATE') { fail('project.json: display_name is still "TEMPLATE"', 'Set a real display_name in project.json instead of the unedited template placeholder.'); failures++; }
   }
 
   // ── 5. Constitution validation ──
@@ -133,21 +160,42 @@ export async function run(argv = process.argv.slice(2)) {
     console.log('');
     const rules = constitution.rules || (Array.isArray(constitution) ? constitution : []);
     if (rules.length === 0) {
-      fail('constitution.json: no rules defined');
+      fail(
+        'constitution.json: no rules defined',
+        'Add at least one rule object to the "rules" array — see templates/domains/*/constitution.json for the shape.'
+      );
       failures++;
     } else {
       pass(`constitution.json: ${rules.length} rules`);
       passes++;
 
       // Check required rule fields
-      const ruleIds = new Set();
+      // M1: localize WHICH index is missing an id, and WHICH TWO indices
+      // collide on a duplicate — a rule id is not the record's only
+      // identity, and "duplicate rule ID X" without saying where left the
+      // operator grepping the file by hand.
+      const ruleIdFirstIndex = new Map(); // id -> first index that defined it
       let ruleErrors = 0;
-      for (const rule of rules) {
-        if (!rule.id) { fail(`constitution.json: rule missing "id"`); ruleErrors++; continue; }
-        if (ruleIds.has(rule.id)) { fail(`constitution.json: duplicate rule ID "${rule.id}"`); ruleErrors++; }
-        ruleIds.add(rule.id);
+      for (const [i, rule] of rules.entries()) {
+        if (!rule.id) {
+          fail(`constitution.json: rule missing "id"`, `Add an "id" field to rules[${i}] (e.g. "STY-002").`);
+          ruleErrors++;
+          continue;
+        }
+        if (ruleIdFirstIndex.has(rule.id)) {
+          fail(
+            `constitution.json: duplicate rule ID "${rule.id}"`,
+            `rules[${ruleIdFirstIndex.get(rule.id)}] and rules[${i}] both use id "${rule.id}" — give one of them a unique id.`
+          );
+          ruleErrors++;
+        } else {
+          ruleIdFirstIndex.set(rule.id, i);
+        }
         if (!rule.dims || rule.dims.length === 0) {
-          fail(`constitution.json: rule ${rule.id} has no "dims" (scoring dimensions)`);
+          fail(
+            `constitution.json: rule ${rule.id} has no "dims" (scoring dimensions)`,
+            `Add a non-empty "dims" array to rules[${i}] (e.g. ["style_consistency"]) — see rubric.json's "dimensions" for valid values.`
+          );
           ruleErrors++;
         }
       }
@@ -168,18 +216,35 @@ export async function run(argv = process.argv.slice(2)) {
       pass(`lanes.json: ${laneList.length} lanes`);
       passes++;
 
-      // Check lane IDs unique
-      const laneIds = new Set();
+      // Check lane IDs unique — same index-localization as constitution rules above.
+      const laneIdFirstIndex = new Map();
       let laneErrors = 0;
-      for (const lane of laneList) {
-        if (!lane.id) { fail('lanes.json: lane missing "id"'); laneErrors++; continue; }
-        if (laneIds.has(lane.id)) { fail(`lanes.json: duplicate lane ID "${lane.id}"`); laneErrors++; }
-        laneIds.add(lane.id);
+      for (const [i, lane] of laneList.entries()) {
+        if (!lane.id) {
+          fail('lanes.json: lane missing "id"', `Add an "id" field to lanes[${i}].`);
+          laneErrors++;
+          continue;
+        }
+        if (laneIdFirstIndex.has(lane.id)) {
+          fail(
+            `lanes.json: duplicate lane ID "${lane.id}"`,
+            `lanes[${laneIdFirstIndex.get(lane.id)}] and lanes[${i}] both use id "${lane.id}" — give one of them a unique id.`
+          );
+          laneErrors++;
+        } else {
+          laneIdFirstIndex.set(lane.id, i);
+        }
 
         // Check patterns compile
         for (const pattern of lane.id_patterns || []) {
           try { new RegExp(pattern); }
-          catch { fail(`lanes.json: lane "${lane.id}" has invalid pattern "${pattern}"`); laneErrors++; }
+          catch {
+            fail(
+              `lanes.json: lane "${lane.id}" has invalid pattern "${pattern}"`,
+              `Fix the regular expression syntax for lane "${lane.id}"'s id_patterns entry "${pattern}".`
+            );
+            laneErrors++;
+          }
         }
       }
       if (laneErrors === 0) { pass('lanes.json: all lane IDs unique, patterns compile'); passes++; }
@@ -198,7 +263,10 @@ export async function run(argv = process.argv.slice(2)) {
     console.log('');
     const dims = rubric.dimensions || [];
     if (dims.length === 0) {
-      fail('rubric.json: no dimensions defined');
+      fail(
+        'rubric.json: no dimensions defined',
+        'Add at least one dimension string to "dimensions" (e.g. ["style_consistency", "composition"]).'
+      );
       failures++;
     } else {
       pass(`rubric.json: ${dims.length} dimensions`);
@@ -206,7 +274,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
     if (!rubric.thresholds) {
-      fail('rubric.json: missing "thresholds"');
+      fail(
+        'rubric.json: missing "thresholds"',
+        'Add a "thresholds" object with approved/borderline/rejected bands — see templates/domains/*/rubric.json for the shape.'
+      );
       failures++;
     } else {
       pass('rubric.json: thresholds present');
@@ -224,7 +295,10 @@ export async function run(argv = process.argv.slice(2)) {
         }
       }
       if (missingDims.size > 0) {
-        fail(`rubric.json: constitution references dimensions not in rubric: ${[...missingDims].join(', ')}`);
+        fail(
+          `rubric.json: constitution references dimensions not in rubric: ${[...missingDims].join(', ')}`,
+          `Add [${[...missingDims].map(d => `"${d}"`).join(', ')}] to rubric.json's "dimensions" array, or fix the referencing rule(s) in constitution.json.`
+        );
         failures++;
       } else {
         pass('rubric.json: all constitution dimensions present in rubric');
@@ -239,7 +313,10 @@ export async function run(argv = process.argv.slice(2)) {
       for (const [mode, ruleList] of Object.entries(rubric.failure_to_rules)) {
         for (const ruleId of ruleList) {
           if (!ruleIds.has(ruleId)) {
-            fail(`rubric.json: failure mode "${mode}" references unknown rule "${ruleId}"`);
+            fail(
+              `rubric.json: failure mode "${mode}" references unknown rule "${ruleId}"`,
+              `Add a rule with id "${ruleId}" to constitution.json, or remove it from rubric.json's failure_to_rules["${mode}"].`
+            );
             badRefs++;
           }
         }
@@ -269,7 +346,10 @@ export async function run(argv = process.argv.slice(2)) {
         const order = terminology[orderKey] || [];
         for (const name of order) {
           if (!terminology.groups[name]) {
-            fail(`terminology.json: ${orderKey} references unknown group "${name}"`);
+            fail(
+              `terminology.json: ${orderKey} references unknown group "${name}"`,
+              `Add "${name}" to terminology.json's "groups" object, or remove it from "${orderKey}".`
+            );
             failures++;
           }
         }
@@ -280,11 +360,23 @@ export async function run(argv = process.argv.slice(2)) {
       for (const [gName, group] of Object.entries(terminology.groups)) {
         for (const pattern of group.id_patterns || []) {
           try { new RegExp(pattern); }
-          catch { fail(`terminology.json: group "${gName}" has invalid id_pattern "${pattern}"`); patternErrors++; }
+          catch {
+            fail(
+              `terminology.json: group "${gName}" has invalid id_pattern "${pattern}"`,
+              `Fix the regular expression syntax for group "${gName}"'s id_patterns entry "${pattern}".`
+            );
+            patternErrors++;
+          }
         }
         for (const pattern of group.prompt_patterns || []) {
           try { new RegExp(pattern); }
-          catch { fail(`terminology.json: group "${gName}" has invalid prompt_pattern "${pattern}"`); patternErrors++; }
+          catch {
+            fail(
+              `terminology.json: group "${gName}" has invalid prompt_pattern "${pattern}"`,
+              `Fix the regular expression syntax for group "${gName}"'s prompt_patterns entry "${pattern}".`
+            );
+            patternErrors++;
+          }
         }
       }
       if (patternErrors === 0) { pass('terminology.json: all detection patterns compile'); passes++; }
@@ -305,46 +397,56 @@ export async function run(argv = process.argv.slice(2)) {
       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; }
+        if (error) {
+          fail(`workflows/profiles/${file} — invalid JSON: ${error}`, `Open workflows/profiles/${file} and fix the syntax error above.`);
+          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(', ')}`);
+          fail(`workflows/profiles/${file} — missing fields: ${missing.join(', ')}`, `Add [${missing.join(', ')}] to workflows/profiles/${file}.`);
           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`);
+          fail(
+            `workflows/profiles/${file} — lane_id "${data.lane_id}" not found in lanes.json`,
+            `Use one of lanes.json's existing lane ids [${[...laneIds].join(', ')}], or add "${data.lane_id}" as a new lane.`
+          );
           wfErrors++;
         }
 
         if (data.subject_mode && !VALID_SUBJECT_MODES.includes(data.subject_mode)) {
-          fail(`workflows/profiles/${file} — invalid subject_mode "${data.subject_mode}"`);
+          fail(`workflows/profiles/${file} — invalid subject_mode "${data.subject_mode}"`, `subject_mode must be one of: ${VALID_SUBJECT_MODES.join(', ')}.`);
           wfErrors++;
         }
 
         if (!VALID_OUTPUT_MODES.includes(data.output_mode)) {
-          fail(`workflows/profiles/${file} — invalid output_mode "${data.output_mode}"`);
+          fail(`workflows/profiles/${file} — invalid output_mode "${data.output_mode}"`, `output_mode must be one of: ${VALID_OUTPUT_MODES.join(', ')}.`);
           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[]`);
+          fail(
+            `workflows/profiles/${file} — prompt_strategy needs style_prefix[], structure, must_include[]`,
+            `Add prompt_strategy.style_prefix (array), .structure (string), and .must_include (array) to workflows/profiles/${file}.`
+          );
           wfErrors++;
         }
 
         const ns = data.negative_strategy;
         if (!ns || !Array.isArray(ns.must_avoid)) {
-          fail(`workflows/profiles/${file} — negative_strategy needs must_avoid[]`);
+          fail(`workflows/profiles/${file} — negative_strategy needs must_avoid[]`, `Add negative_strategy.must_avoid (array) to workflows/profiles/${file}.`);
           wfErrors++;
         }
 
         if (!data.runtime_defaults?.adapter_target) {
-          fail(`workflows/profiles/${file} — runtime_defaults needs adapter_target`);
+          fail(`workflows/profiles/${file} — runtime_defaults needs adapter_target`, `Add runtime_defaults.adapter_target (e.g. "comfyui") to workflows/profiles/${file}.`);
           wfErrors++;
         }
       }
@@ -377,34 +479,41 @@ export async function run(argv = process.argv.slice(2)) {
       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 (error) {
+          fail(`workflows/batch-modes/${file} — invalid JSON: ${error}`, `Open workflows/batch-modes/${file} and fix the syntax error above.`);
+          bmErrors++;
+          continue;
+        }
 
-        if (!data.mode_id) { fail(`workflows/batch-modes/${file} — missing mode_id`); bmErrors++; }
+        if (!data.mode_id) { fail(`workflows/batch-modes/${file} — missing mode_id`, `Add a "mode_id" field to workflows/batch-modes/${file}.`); bmErrors++; }
         if (!data.batch_type || !VALID_BATCH_TYPES.includes(data.batch_type)) {
-          fail(`workflows/batch-modes/${file} — invalid batch_type "${data.batch_type}"`);
+          fail(`workflows/batch-modes/${file} — invalid batch_type "${data.batch_type}"`, `batch_type must be one of: ${VALID_BATCH_TYPES.join(', ')}.`);
           bmErrors++;
         }
         if (data.subject_mode && !VALID_SUBJECT_MODES_BM.includes(data.subject_mode)) {
-          fail(`workflows/batch-modes/${file} — invalid subject_mode "${data.subject_mode}"`);
+          fail(`workflows/batch-modes/${file} — invalid subject_mode "${data.subject_mode}"`, `subject_mode must be one of: ${VALID_SUBJECT_MODES_BM.join(', ')}.`);
           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`);
+          fail(
+            `workflows/batch-modes/${file} — base_workflow_id "${data.base_workflow_id}" not found in profiles`,
+            `Use one of the existing workflow ids [${wfFiles.join(', ')}], or add a matching profile under workflows/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`);
+          fail(`workflows/batch-modes/${file} — variant_plan must be non-empty array`, `Add at least one slot to variant_plan in workflows/batch-modes/${file}.`);
           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(', ')}`);
+            fail(`workflows/batch-modes/${file} — duplicate slot_ids: ${[...new Set(dupes)].join(', ')}`, `Give each entry in variant_plan a unique slot_id.`);
             bmErrors++;
           }
         }
         if (data.assembly?.layout && !VALID_LAYOUTS.includes(data.assembly.layout)) {
-          fail(`workflows/batch-modes/${file} — invalid assembly.layout "${data.assembly.layout}"`);
+          fail(`workflows/batch-modes/${file} — invalid assembly.layout "${data.assembly.layout}"`, `assembly.layout must be one of: ${VALID_LAYOUTS.join(', ')}.`);
           bmErrors++;
         }
       }
@@ -424,17 +533,26 @@ export async function run(argv = process.argv.slice(2)) {
   // ── 11. Runtime templates check ──
   {
     console.log('');
-    const runtimeDir = join(REPO_ROOT, 'runtime', 'comfyui');
+    // PACKAGE-relative, not workspace-relative — `runtime/` ships inside the
+    // npm tarball (see getPackageRoot() in lib/paths.js). Joining it to
+    // REPO_ROOT made doctor report "runtime/comfyui/ — directory not found"
+    // for every installed user while the templates sat in the package.
+    const runtimeDir = join(getRuntimeDir(), '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 (error) {
+            fail(`runtime/comfyui/${file}: invalid JSON — ${error}`, `Open ${join(runtimeDir, file)} and fix the syntax error above.`);
+            templateErrors++;
+            continue;
+          }
+          if (!data.template_id) { fail(`runtime/comfyui/${file}: missing template_id`, `Add a "template_id" field to ${file}.`); templateErrors++; }
           if (!data.compatible_modes || !Array.isArray(data.compatible_modes)) {
-            fail(`runtime/comfyui/${file}: missing compatible_modes[]`); templateErrors++;
+            fail(`runtime/comfyui/${file}: missing compatible_modes[]`, `Add a "compatible_modes" array to ${file}.`);
+            templateErrors++;
           }
         }
         if (templateErrors === 0) {
@@ -464,8 +582,13 @@ export async function run(argv = process.argv.slice(2)) {
       const sample = recordFiles.slice(0, 3);
       for (const f of sample) {
         const { data, error } = tryParseJson(join(recordsDir, f));
-        if (error) { fail(`records/${f}: invalid JSON`); recordErrors++; }
-        else if (!data.id) { fail(`records/${f}: missing "id"`); recordErrors++; }
+        if (error) {
+          fail(`records/${f}: invalid JSON`, `Open records/${f} and fix the syntax error, or delete/regenerate it if it's an aborted write.`);
+          recordErrors++;
+        } else if (!data.id) {
+          fail(`records/${f}: missing "id"`, `Add an "id" field to records/${f} matching its filename stem.`);
+          recordErrors++;
+        }
       }
       if (recordErrors === 0) {
         pass(`${recordFiles.length} records (spot-check passed)`);
@@ -485,7 +608,11 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`═══ ${status} — ${passes} passed, ${failures} failed, ${warnings} warnings ═══`);
 
   if (failures > 0) {
-    throw runtimeError('PROJECT_UNHEALTHY', `Project "${projectName}" has ${failures} issue(s).`);
+    throw runtimeError(
+      'PROJECT_UNHEALTHY',
+      `Project "${projectName}" has ${failures} issue(s).`,
+      `Fix the ✗ lines above — each one now carries its own Hint: with a concrete next action — then re-run: sdlab project doctor --project ${projectName}`
+    );
   }
 }
 

package/scripts/eligibility.js

@@ -10,10 +10,11 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseArgs, getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { loadProjectConfig, loadSelectionProfile } from '../lib/config.js';
 import { handleCliError } from '../lib/errors.js';
 import { evaluateEligibility, categorizeExclusions } from '../lib/eligibility.js';
+import { auditJudgmentProvenance, formatProvenanceWarning, formatReuseNote } from '../lib/judgment-provenance.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
@@ -26,7 +27,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const projectRoot = getProjectRoot(projectName);
 
   const profile = loadSelectionProfile(projectRoot, flags.profile);
   const config = loadProjectConfig(projectRoot);
@@ -42,10 +43,15 @@ export async function run(argv = process.argv.slice(2)) {
   const eligible = [];
   const excluded = [];
   const nearMiss = [];
+  // Retained for the judgment-provenance audit below, which is a corpus-level
+  // question (is this rationale reused across records?) and cannot be answered
+  // one record at a time.
+  const allRecords = [];
 
   for (const file of files) {
     const raw = await readFile(join(recordsDir, file), 'utf-8');
     const record = JSON.parse(raw);
+    allRecords.push(record);
 
     const result = evaluateEligibility(record, profile, config.lanes, config.terminology);
 
@@ -72,6 +78,40 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
+  // Judgment provenance (Law 2). Eligibility asks "does this record have a
+  // judgment"; it has never asked "does that judgment describe THIS image."
+  // On star-freight the difference is 948 of 1,182 records — rationales a
+  // deleted bulk script selected by id-prefix, one string reused on 144
+  // images. Those records pass every eligibility check and land in training
+  // sets carrying an explanation about a category, not a picture.
+  //
+  // Read-only: nothing here mutates a record (Director's ruling, 2026-08-04).
+  const provenance = auditJudgmentProvenance(allRecords);
+  const provenanceWarning = formatProvenanceWarning(provenance);
+  if (provenanceWarning) {
+    console.log('');
+    console.log(`  \x1b[33m⚠\x1b[0m ${provenanceWarning}`);
+    if (provenance.top_reused.length > 0) {
+      console.log('    Most-reused rationales:');
+      for (const r of provenance.top_reused.slice(0, 3)) {
+        const snippet = r.explanation.length > 62
+          ? `${r.explanation.slice(0, 62)}…`
+          : r.explanation;
+        console.log(`      ×${String(r.count).padStart(3)}  "${snippet}"`);
+      }
+    }
+  } else {
+    // No script reviewer. Reuse here is usually a real systematic defect
+    // described accurately across the wave it affected — informational, not a
+    // finding. Printed at the same indent but without the warning glyph, so it
+    // reads as context rather than an accusation.
+    const reuseNote = formatReuseNote(provenance);
+    if (reuseNote) {
+      console.log('');
+      console.log(`    ${reuseNote}`);
+    }
+  }
+
   if (nearMiss.length > 0) {
     console.log(`\n  Improvement opportunities (${nearMiss.length} records with 1 failing check):`);
     const byReason = {};