@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

package/scripts/generate-controlnet.js

@@ -14,12 +14,13 @@
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -33,27 +34,32 @@ const DEFAULTS = {
   base_seed: 27100,
 };
 
+// H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+// `--flag=value`. The prior `argv.indexOf(flag)`-based get() only matched a
+// token EXACTLY equal to e.g. "--weight" — false for the single token
+// "--weight=1.1" — so the equals form silently fell back to the default
+// with no error and no warning.
 function parseLocalArgs(argv) {
-  const get = (flag, def) => {
-    const i = argv.indexOf(flag);
-    if (i < 0 || i + 1 >= argv.length) return def;
-    const v = argv[i + 1];
-    if (typeof v === 'string' && v.startsWith('--')) {
-      throw inputError('INPUT_MISSING_VALUE', `Flag ${flag} is missing its value (got another flag: ${v}).`);
-    }
-    return v;
+  const get = (flagName, def) => {
+    const v = takeFlagValue(argv, flagName);
+    return v === undefined ? def : v;
   };
   return {
-    subject: get("--subject", "unknown"),
-    guidePath: get("--guide", null),
-    prompt: get("--prompt", null),
-    promptFile: get("--prompt-file", null),
-    negative: get("--negative", null),
-    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
-    weight: parseNumberFlag('weight', get("--weight", "0.70"), { min: 0, max: 2 }),
-    guidanceEnd: parseNumberFlag('guidance-end', get("--guidance-end", "0.65"), { min: 0, max: 1 }),
-    controlModel: get("--model", "controlnet-canny-sdxl-1.0.safetensors"),
+    subject: get("subject", "unknown"),
+    guidePath: get("guide", null),
+    prompt: get("prompt", null),
+    promptFile: get("prompt-file", null),
+    negative: get("negative", null),
+    seeds: parseNumberFlag('seeds', get("seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("weight", "0.70"), { min: 0, max: 2 }),
+    guidanceEnd: parseNumberFlag('guidance-end', get("guidance-end", "0.65"), { min: 0, max: 1 }),
+    controlModel: get("model", "controlnet-canny-sdxl-1.0.safetensors"),
     dryRun: argv.includes("--dry-run"),
+    // H5: skip a seed slot whose output image already exists. This script
+    // (unlike generate.js / generate-identity.js) never writes a
+    // records/<id>.json — only the output PNG — so resumability here is
+    // image-existence only; see scripts/_resume.js's requireRecord doc.
+    resume: argv.includes("--resume"),
   };
 }
 
@@ -169,7 +175,7 @@ function buildControlNetWorkflow(prompt, negativePrompt, seed, guideImagePath, c
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const opts = parseLocalArgs(argv);
@@ -180,8 +186,7 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
   // Supports --i-know + --reason bypass for soft-advisory entries.
-  const reasonFlagIdx = argv.indexOf('--reason');
-  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  const bypassReason = takeFlagValue(argv, 'reason') ?? null;
   await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
     action: 'generate:controlnet',
     allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -236,14 +241,28 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`\x1b[32m+\x1b[0m Guide uploaded: ${guideFilename}`);
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  // SDL-M11: only create the output dir on a real run — a --dry-run preview
+  // must be side-effect-free (README.md promises "preview the effect first").
+  if (!opts.dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  }
 
-  let successes = 0, failures = 0;
+  let successes = 0, failures = 0, skipped = 0;
   for (let si = 0; si < opts.seeds; si++) {
     const seed = DEFAULTS.base_seed + si;
     const assetId = `${opts.subject}_cn_s${si}`;
     const destPath = `outputs/candidates/${assetId}.png`;
 
+    // H5: --resume skips a seed slot whose output image already exists.
+    // Seed here is derived from the loop index (si), not an externally
+    // mutated running counter, so skipping never desyncs a later seed — the
+    // for-loop's own si++ always fires regardless of this continue.
+    if (opts.resume && !opts.dryRun && isResumable(GAME_ROOT, assetId, { requireRecord: false })) {
+      logResumedSkip(si + 1, opts.seeds, assetId);
+      skipped++;
+      continue;
+    }
+
     console.log(`  [${si + 1}/${opts.seeds}] ${assetId} (seed: ${seed})`);
 
     if (opts.dryRun) continue;
@@ -285,7 +304,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  console.log(`\n\x1b[32m+\x1b[0m ControlNet discovery complete (${successes} success, ${failures} failed)`);
+  const skippedSuffix = skipped > 0 ? `, ${skipped} resumed` : '';
+  console.log(`\n\x1b[32m+\x1b[0m ControlNet discovery complete (${successes} success, ${failures} failed${skippedSuffix})`);
   if (opts.dryRun) console.log("  (dry run)");
   if (!opts.dryRun && failures > 0 && successes === 0) {
     throw runtimeError('RUNTIME_ALL_FAILED', `All ${opts.seeds} ControlNet generation attempts failed.`);

package/scripts/generate-identity.js

@@ -18,16 +18,20 @@
  *   --phase MODE    Generation phase: discovery | follow_on (default: discovery)
  *   --anchor FILE   Anchor source image path (required for --phase follow_on)
  *   --denoise N     Denoise strength for follow_on phase (default: 0.38)
+ *   --resume        Skip shots whose record + output image already exist
+ *                    (seed slots still advance, so a resumed run stays
+ *                    bit-identical to an uninterrupted one)
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile, loadProjectMeta, resolveGpuModel } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 // ── Defaults (match existing lab pipeline) ──
 
@@ -378,12 +382,12 @@ function buildRecord(pack, subject, shot, seed, seedIndex, imgData, destPath, el
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
   const gpuModel = resolveGpuModel(loadProjectMeta(GAME_ROOT)?.defaults);
 
   // Collect positionals, skipping values that belong to known flags
-  const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game']);
+  const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game', '--reason']);
   const positionals = [];
   for (let k = 0; k < argv.length; k++) {
     const a = argv[k];
@@ -395,16 +399,23 @@ export async function run(argv = process.argv.slice(2)) {
   }
   const packPath = positionals[0];
   const dryRun = argv.includes("--dry-run");
-  const subjectFilter = argv.includes("--subject")
-    ? argv[argv.indexOf("--subject") + 1]
-    : null;
+  const resume = argv.includes("--resume");
+
+  // H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+  // `--flag=value`. The previous `argv.includes('--x') ?
+  // argv[argv.indexOf('--x')+1] : default` pattern checked argv for a token
+  // EXACTLY EQUAL to "--x" — false for the single token "--phase=follow_on",
+  // so the equals form silently fell back to the default. For --phase that
+  // meant `--phase=follow_on` ran the discovery (txt2img) workflow instead
+  // of follow_on (img2img) — silently, on an hours-long GPU job. Same gap
+  // closed here for --seeds / --anchor / --denoise / --subject / --reason.
+  const subjectFilter = takeFlagValue(argv, 'subject') ?? null;
 
   // Freeze gate (advisory): when --subject is given, refuse if that subject's
   // canon entry is frozen. No-op when --subject is absent (pack-driven) or
   // when the project has no canon-build config.
   if (subjectFilter) {
-    const reasonFlagIdx = argv.indexOf('--reason');
-    const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+    const bypassReason = takeFlagValue(argv, 'reason') ?? null;
     await assertNotFrozenBySubject(GAME_ROOT, subjectFilter, {
       action: 'generate:identity',
       allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -412,17 +423,15 @@ export async function run(argv = process.argv.slice(2)) {
       by: 'mike',
     });
   }
-  const seedCount = argv.includes("--seeds")
-    ? parseNumberFlag('seeds', argv[argv.indexOf("--seeds") + 1], { int: true, min: 1 })
+  const seedsRaw = takeFlagValue(argv, 'seeds');
+  const seedCount = seedsRaw !== undefined
+    ? parseNumberFlag('seeds', seedsRaw, { int: true, min: 1 })
     : 3;
-  const phase = argv.includes("--phase")
-    ? argv[argv.indexOf("--phase") + 1]
-    : "discovery";
-  const anchorPath = argv.includes("--anchor")
-    ? argv[argv.indexOf("--anchor") + 1]
-    : null;
-  const denoise = argv.includes("--denoise")
-    ? parseNumberFlag('denoise', argv[argv.indexOf("--denoise") + 1], { min: 0, max: 1 })
+  const phase = takeFlagValue(argv, 'phase') ?? "discovery";
+  const anchorPath = takeFlagValue(argv, 'anchor') ?? null;
+  const denoiseRaw = takeFlagValue(argv, 'denoise');
+  const denoise = denoiseRaw !== undefined
+    ? parseNumberFlag('denoise', denoiseRaw, { min: 0, max: 1 })
     : 0.38;
 
   if (!packPath) {
@@ -474,11 +483,16 @@ export async function run(argv = process.argv.slice(2)) {
     console.log("\x1b[32m+\x1b[0m ComfyUI online");
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
-  await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  // SDL-M11: only create output dirs on a real run — a --dry-run preview must
+  // be side-effect-free (README.md promises "preview the effect first").
+  if (!dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+    await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  }
 
   let generated = 0;
   let errors = 0;
+  let skipped = 0;
   let imageIndex = 0;
 
   for (const subject of subjects) {
@@ -498,6 +512,21 @@ export async function run(argv = process.argv.slice(2)) {
         const assetId = `${shot.id}_s${si}`;
         const destPath = `outputs/candidates/${assetId}.png`;
 
+        // H5: --resume skips a shot whose record AND output image already
+        // exist, but imageIndex (and therefore seed) still advances exactly
+        // as it would have if the shot had been processed — a resumed run
+        // reproduces the identical seed sequence an uninterrupted run would
+        // have produced. Ported from generate.js, the one generator that had
+        // this; generate-identity is the most expensive per-image generator
+        // in the pipeline, so it is the one that most needed it.
+        if (resume && !dryRun && isResumable(GAME_ROOT, assetId)) {
+          logResumedSkip(generated + 1, totalImages, assetId);
+          generated++;
+          skipped++;
+          imageIndex++;
+          continue;
+        }
+
         console.log(`    [${generated + 1}/${totalImages}] ${assetId} (seed: ${seed})`);
 
         if (dryRun) {
@@ -572,8 +601,9 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  const succeeded = generated - errors;
-  console.log(`\n\x1b[32m+\x1b[0m Generated ${succeeded} images (${errors} errors)`);
+  const succeeded = generated - errors - skipped;
+  const skippedSuffix = skipped > 0 ? `, ${skipped} resumed` : '';
+  console.log(`\n\x1b[32m+\x1b[0m Generated ${succeeded} images (${errors} errors${skippedSuffix})`);
   if (dryRun) console.log("  (dry run — no images produced)");
   if (!dryRun && errors > 0 && succeeded === 0) {
     throw runtimeError('RUNTIME_ALL_FAILED', `All ${generated} generation attempts failed.`);

package/scripts/generate-ipadapter.js

@@ -13,11 +13,12 @@
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -33,26 +34,31 @@ const DEFAULTS = {
   base_seed: 27200,
 };
 
+// H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+// `--flag=value`. The prior `argv.indexOf(flag)`-based get() only matched a
+// token EXACTLY equal to e.g. "--weight" — false for the single token
+// "--weight=1.1" — so the equals form silently fell back to the default
+// with no error and no warning.
 function parseLocalArgs(argv) {
-  const get = (flag, def) => {
-    const i = argv.indexOf(flag);
-    if (i < 0 || i + 1 >= argv.length) return def;
-    const v = argv[i + 1];
-    if (typeof v === 'string' && v.startsWith('--')) {
-      throw inputError('INPUT_MISSING_VALUE', `Flag ${flag} is missing its value (got another flag: ${v}).`);
-    }
-    return v;
+  const get = (flagName, def) => {
+    const v = takeFlagValue(argv, flagName);
+    return v === undefined ? def : v;
   };
   return {
-    subject: get("--subject", "unknown"),
-    refPath: get("--ref", null),
-    prompt: get("--prompt", null),
-    negative: get("--negative", null),
-    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
-    weight: parseNumberFlag('weight', get("--weight", "0.55"), { min: 0, max: 2 }),
-    start: parseNumberFlag('start', get("--start", "0.0"), { min: 0, max: 1 }),
-    end: parseNumberFlag('end', get("--end", "0.8"), { min: 0, max: 1 }),
+    subject: get("subject", "unknown"),
+    refPath: get("ref", null),
+    prompt: get("prompt", null),
+    negative: get("negative", null),
+    seeds: parseNumberFlag('seeds', get("seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("weight", "0.55"), { min: 0, max: 2 }),
+    start: parseNumberFlag('start', get("start", "0.0"), { min: 0, max: 1 }),
+    end: parseNumberFlag('end', get("end", "0.8"), { min: 0, max: 1 }),
     dryRun: argv.includes("--dry-run"),
+    // H5: skip a seed slot whose output image already exists. This script
+    // (unlike generate.js / generate-identity.js) never writes a
+    // records/<id>.json — only the output PNG — so resumability here is
+    // image-existence only; see scripts/_resume.js's requireRecord doc.
+    resume: argv.includes("--resume"),
   };
 }
 
@@ -175,7 +181,7 @@ function buildIPAdapterWorkflow(prompt, negativePrompt, seed, refImageName, weig
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const opts = parseLocalArgs(argv);
@@ -188,8 +194,7 @@ export async function run(argv = process.argv.slice(2)) {
   }
 
   // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
-  const reasonFlagIdx = argv.indexOf('--reason');
-  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  const bypassReason = takeFlagValue(argv, 'reason') ?? null;
   await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
     action: 'generate:ipadapter',
     allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -224,13 +229,28 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`\x1b[32m+\x1b[0m Reference uploaded: ${refFilename}`);
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  // SDL-M11: only create the output dir on a real run — a --dry-run preview
+  // must be side-effect-free (README.md promises "preview the effect first").
+  if (!opts.dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  }
 
+  let skipped = 0;
   for (let si = 0; si < opts.seeds; si++) {
     const seed = DEFAULTS.base_seed + si;
     const assetId = `${opts.subject}_ipa_s${si}`;
     const destPath = `outputs/candidates/${assetId}.png`;
 
+    // H5: --resume skips a seed slot whose output image already exists.
+    // Seed here is derived from the loop index (si), not an externally
+    // mutated running counter, so skipping never desyncs a later seed — the
+    // for-loop's own si++ always fires regardless of this continue.
+    if (opts.resume && !opts.dryRun && isResumable(GAME_ROOT, assetId, { requireRecord: false })) {
+      logResumedSkip(si + 1, opts.seeds, assetId);
+      skipped++;
+      continue;
+    }
+
     console.log(`  [${si + 1}/${opts.seeds}] ${assetId} (seed: ${seed})`);
 
     if (opts.dryRun) continue;
@@ -269,7 +289,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  console.log("\n\x1b[32m+\x1b[0m IP-Adapter discovery complete");
+  const skippedSuffix = skipped > 0 ? ` (${skipped} resumed)` : '';
+  console.log(`\n\x1b[32m+\x1b[0m IP-Adapter discovery complete${skippedSuffix}`);
   if (opts.dryRun) console.log("  (dry run)");
 }
 

package/scripts/generate.js

@@ -14,13 +14,14 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs, getProjectName } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile, loadProjectMeta, resolveGpuModel } from "../lib/config.js";
 import { runtimeError, inputError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 import { pickOutputImage } from "../lib/comfyui-output.js";
 import { buildQwenGraph, QWEN_DEFAULTS } from "../lib/adapters/comfyui-workflows.js";
-import { info, result } from "../lib/log.js";
+import { buildPinning, SEED_POLICIES, createHashCache, flushHashCache } from "../lib/run-manifest.js";
+import { info, result, warn } from "../lib/log.js";
 
 /**
  * Format milliseconds as a human ETA string like "6m 12s" or "42s".
@@ -178,6 +179,34 @@ function buildWorkflow(prompt, negativePrompt, checkpoint, loras, seed, steps, c
   return { nodes, saveNodeId: saveId };
 }
 
+/**
+ * Coordinator addendum (same session as H4/H5): every domain template's
+ * example-wave.json ships subject prompts with a literal `[DESCRIBE ...]`
+ * placeholder (e.g. "[DESCRIBE YOUR HERO — head and shoulders, ...]") that
+ * the user is meant to replace before generating. `sdlab init`'s own
+ * printed next-steps run generate before "edit the pack" is ever a
+ * mandatory step, so following them literally on an unedited pack burns a
+ * GPU wave on template text with no feedback until the images come back
+ * looking like a literal instruction string.
+ *
+ * All 5 domain templates use this exact "[DESCRIBE " shape (verified across
+ * templates/domains/*\/inputs/prompts/example-wave.json), so the check is
+ * narrow and specific to it — it does NOT flag ordinary SD prompt-editing
+ * bracket syntax such as "[word]" or "[from:to:0.5]", neither of which
+ * starts with the literal word DESCRIBE.
+ */
+const PLACEHOLDER_PROMPT_RE = /\[DESCRIBE\b/;
+
+function findPlaceholderPrompts(jobs) {
+  const hits = [];
+  for (const job of jobs) {
+    if (typeof job.prompt === 'string' && PLACEHOLDER_PROMPT_RE.test(job.prompt)) {
+      hits.push(job.assetId);
+    }
+  }
+  return hits;
+}
+
 /**
  * Detect the input schema and normalize to a unified shape:
  *   { lane, style_prefix, negative, defaults, base, jobs:[{assetId, subjectId, variationId, prompt, seed, loras}] }
@@ -263,7 +292,7 @@ function normalizeGenerationInput(raw, projectMeta) {
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const parsed = parseArgs(argv, {
@@ -272,12 +301,18 @@ export async function run(argv = process.argv.slice(2)) {
       game: { type: 'string' },
       'dry-run': { type: 'boolean' },
       resume: { type: 'boolean' },
+      'hash-models': { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
   const packPath = parsed.positionals[0] || "inputs/prompts/rpg-icons-lane1.json";
   const dryRun = parsed.flags['dry-run'] === true;
   const resume = parsed.flags['resume'] === true;
+  // PIN_PER_STEP: --hash-models opts into content hashing of the checkpoint/
+  // unet/clip/vae/LoRA files (best-effort, cached). Without it the pinning block
+  // still records comfy_workflow_sha + model name/size + seed_policy.
+  const hashModels = parsed.flags['hash-models'] === true;
+  const hashCache = hashModels ? createHashCache() : undefined;
 
   const fullPackPath = resolveSafeProjectPath(GAME_ROOT, packPath, { flagName: 'pack-path' });
   const raw = await readJsonFile(fullPackPath);
@@ -316,6 +351,17 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`  Total candidates: ${pack.jobs.length}`);
   console.log("");
 
+  // Coordinator addendum: catch unedited template text before it burns GPU
+  // time (or, under --dry-run, before the user thinks the pack is ready).
+  const placeholderHits = findPlaceholderPrompts(pack.jobs);
+  if (placeholderHits.length > 0) {
+    warn(
+      `${placeholderHits.length} of ${pack.jobs.length} prompt(s) still contain unedited "[DESCRIBE ...]" template ` +
+      `text (e.g. "${placeholderHits[0]}"). Edit the prompt pack before generating for real — otherwise you'll spend ` +
+      `GPU time rendering placeholder instructions instead of your subject.`
+    );
+  }
+
   if (!dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
@@ -324,8 +370,12 @@ export async function run(argv = process.argv.slice(2)) {
     console.log("\x1b[32m✓\x1b[0m ComfyUI online");
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
-  await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  // SDL-M11: only create output dirs on a real run — a --dry-run preview must
+  // be side-effect-free (README.md promises "preview the effect first").
+  if (!dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+    await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  }
 
   let generated = 0;
   let errors = 0;
@@ -432,6 +482,20 @@ export async function run(argv = process.argv.slice(2)) {
         provenance.loras = loras;
       }
 
+      // PIN_PER_STEP: pin the exact graph + model/LoRA content identity + seed
+      // policy via the shared contract (lib/run-manifest.js). Model hashing is
+      // wave-constant; the shared cache means it runs at most once per wave.
+      provenance.pinning = buildPinning({
+        graph: nodes,
+        models: isQwen
+          ? { unet: provenance.unet, clip: provenance.clip, vae: provenance.vae }
+          : { checkpoint: d.checkpoint },
+        loras: isQwen ? (d.loras || []) : loras,
+        seedPolicy: SEED_POLICIES.BASE_INCREMENT,
+        hashModels,
+        cache: hashCache,
+      });
+
       const record = {
         id: assetId,
         schema_version: "1.0.0",
@@ -467,6 +531,9 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
+  // Persist any newly computed model hashes so the next wave reuses them.
+  flushHashCache(hashCache);
+
   console.log("");
   const succeeded = generated - errors - skipped;
   const totalElapsedMs = Date.now() - runStartMs;

package/scripts/implementation-pack.js

@@ -11,7 +11,7 @@
 
 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 { inputError, handleCliError } from '../lib/errors.js';
 import { listTrainingManifests } from '../lib/training-manifests.js';
 import { buildImplementationPack, listImplementationPacks, loadImplementationPack } from '../lib/implementation-packs.js';
@@ -26,7 +26,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 subcommand = positionals.find(a => !a.startsWith('impl-') && !a.startsWith('tm-')) || 'list';
 
   if (subcommand === 'build') {