@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/scripts/asset-ingest.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * asset-ingest.js — `sdlab asset ingest <dir>`: register a provenance-carrying
+ * asset export (asset-source.json + renders + masks + channels) into a
+ * project, through the full contract of lib/asset-source.js and the
+ * receiving-dock gates of lib/asset-ingest.js.
+ *
+ * The manifest-driven, gated sibling of `sdlab ingest` (which takes bare
+ * images with no contract). See docs/asset-lane-design.md.
+ *
+ * PATH NOTE (deliberate deviation from resolveSafeProjectPath): the export
+ * directory is allowed to live OUTSIDE the sdlab workspace — asset exports
+ * live where the asset pipeline puts them (e.g. a training area on another
+ * part of the disk). The source is READ-ONLY here; every path the manifest
+ * references is contained to the export directory by lib/asset-source.js,
+ * and every WRITE stays inside the project. Containment where it protects,
+ * reach where the user explicitly points.
+ *
+ * Usage:
+ *   sdlab asset ingest <dir> --project <name>
+ *   sdlab asset ingest <dir> --project <name> --dry-run
+ *   sdlab asset ingest <dir> --project <name> --json
+ */
+
+import { resolve } from 'node:path';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
+import { ingestAssetSource } from '../lib/asset-ingest.js';
+import { result } from '../lib/log.js';
+
+const USAGE = `Usage: sdlab asset ingest <dir> --project <name> [--dry-run] [--json]
+
+Validate an asset export's asset-source.json (schema, containment, encoding
+proofs, categorical palette proofs, the acceptance verdict) and register its
+renders as candidate records. Refuses loudly on any contract violation —
+nothing registers on a bad manifest.
+
+Positional:
+  dir                  Asset export directory containing asset-source.json.
+                       May live outside the workspace (read-only source).
+
+Flags:
+  --project <name>     Project to register into
+  --dry-run            Validate + run gates + report the plan; write nothing
+  --json               Emit the result as JSON on stdout
+
+What lands on success:
+  records/<asset>__<render>.json     uncurated records (judgment: null),
+                                     provenance.source: "asset", hashes,
+                                     camera/facing, gate measurements
+  outputs/candidates/<asset>__<render>.png
+  assets/<asset>/                    manifest copy, silhouettes, channel
+                                     instances, pairs, ingest-receipt.json
+                                     (the receipt lists every written path —
+                                     it is the undo checklist)
+
+Next steps after ingesting:
+  1. Review: sdlab curate <id> approved/rejected "explanation"
+  2. Bind:   sdlab bind --project <name>`;
+
+export async function run(argv = process.argv.slice(2)) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(USAGE);
+    return;
+  }
+
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const dirArg = positionals[0];
+  if (!dirArg) {
+    throw inputError('INPUT_MISSING_ARGS', 'An asset export directory is required.', USAGE);
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+  const sourceDir = resolve(dirArg);
+
+  if (!flags.json) {
+    console.log(`\x1b[1msdlab asset ingest\x1b[0m — ${projectName}`);
+    console.log(`  Source: ${sourceDir}`);
+    if (dryRun) console.log(`  Mode:   DRY RUN (no files written)`);
+    console.log('');
+  }
+
+  const report = await ingestAssetSource(projectRoot, sourceDir, { dryRun });
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (report.alreadyIngested) {
+    console.log(`  ○ Asset "${report.assetId}" is already ingested (same manifest hash) — nothing to do.`);
+    console.log(`    Receipt: ${report.receiptPath}`);
+    return;
+  }
+
+  console.log(`  \x1b[32m✓\x1b[0m Registered: ${report.created.length} render record(s)${dryRun ? ' (dry run — nothing written)' : ''}`);
+  for (const id of report.created) {
+    const gate = report.gates[id];
+    console.log(`    ✓ ${id}  (off-palette ${gate.offpalette_pct}%${gate.withdrawn_pct_bound ? ' [diagnostic]' : ''}, blob ${gate.largest_blob_px}px)`);
+  }
+
+  if (report.skipped.length > 0) {
+    console.log(`  Skipped: ${report.skipped.length} (already registered by this ingest)`);
+    for (const id of report.skipped) console.log(`    ○ ${id}`);
+  }
+
+  if (report.rejected.length > 0) {
+    console.log(`  \x1b[33m⚠\x1b[0m Rejected by the asset's own palette gate: ${report.rejected.length}`);
+    for (const r of report.rejected) {
+      const d = r.gate.dominant;
+      console.log(`    ✗ ${r.render_id}: blob ${r.gate.largest_blob_px}px (limit ${'≤'} manifest gate)` +
+        (d ? ` — dominant hue ${d.hue_lo}-${d.hue_hi}°, median C* ${d.median_chroma}, rgb(${d.median_rgb})` : ''));
+    }
+  }
+
+  // Provenance notices — what the manifest left undeclared. Not failures:
+  // the ingest succeeded. These are facts about the training data that only
+  // the manifest could have supplied, printed so they are not discovered
+  // later by a split or a training run that quietly assumed them.
+  if (report.notices?.length > 0) {
+    const gaps = report.notices.filter((n) => n.kind === 'gap');
+    const infos = report.notices.filter((n) => n.kind !== 'gap');
+    console.log('');
+    console.log(`  \x1b[36mProvenance notices\x1b[0m (${report.notices.length}) — the ingest SUCCEEDED; these describe the records it created:`);
+    if (gaps.length > 0) {
+      console.log(`  \x1b[33m  gaps\x1b[0m (${gaps.length}) — declarations the manifest did not make; closing them is export-side work:`);
+      for (const n of gaps) console.log(`    • [${n.code}] ${n.message}`);
+    }
+    if (infos.length > 0) {
+      console.log(`    info (${infos.length}) — declarations it DID make that change how these records read:`);
+      for (const n of infos) console.log(`    • [${n.code}] ${n.message}`);
+    }
+  }
+
+  if (!dryRun && report.created.length > 0) {
+    console.log('');
+    result(`Receipt: ${report.receiptPath}`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. Review: sdlab curate <id> approved/rejected "explanation"');
+    console.log('    2. Bind:   sdlab bind --project ' + projectName);
+  }
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('asset-ingest.js') || process.argv[1].endsWith('asset-ingest'))) {
+  run().catch(handleCliError);
+}

package/scripts/brief-compile.js

@@ -14,6 +14,7 @@ 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';
+import { handleCliError } from '../lib/errors.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
@@ -130,5 +131,5 @@ export async function run(argv = process.argv.slice(2)) {
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('brief-compile.js') || process.argv[1].endsWith('brief-compile'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/brief-show.js

@@ -13,6 +13,7 @@ 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';
+import { handleCliError } from '../lib/errors.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
@@ -49,5 +50,5 @@ export async function run(argv = process.argv.slice(2)) {
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('brief-show.js') || process.argv[1].endsWith('brief-show'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/canon-bind.js

@@ -19,7 +19,7 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 
@@ -155,7 +155,7 @@ function generateAssertions(record, constitutionRules, lanesConfig, rubricConfig
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const PROJECT_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const PROJECT_ROOT = getProjectRoot(projectName);
   const RECORDS_DIR = join(PROJECT_ROOT, 'records');
   const DRY_RUN = argv.includes('--dry-run');
   const STATS_ONLY = argv.includes('--stats');

package/scripts/canon-build.js

@@ -7,27 +7,35 @@
  */
 
 import { parseArgs } from 'node:util';
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { getProjectRoot } from '../lib/paths.js';
 import { runBuild } from '../lib/canon-build/build.js';
 import { inputError } from '../lib/errors.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project:  { type: 'string' },
+    game:     { type: 'string' },           // deprecated alias
+    full:     { type: 'boolean', default: false },
+    'no-cache': { type: 'boolean', default: false },
+    'dry-run':  { type: 'boolean', default: false },
+    only:     { type: 'string' },
+    json:     { type: 'boolean', default: false },
+    quiet:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project:  { type: 'string' },
-      game:     { type: 'string' },           // deprecated alias
-      full:     { type: 'boolean', default: false },
-      'no-cache': { type: 'boolean', default: false },
-      'dry-run':  { type: 'boolean', default: false },
-      only:     { type: 'string' },
-      json:     { type: 'boolean', default: false },
-      quiet:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: strict:false is deliberate (it lets the entity-id positional through
+  // unrejected) but its side effect is that ANY unrecognized --flag is
+  // silently accepted too — a misspelled OPTIONAL flag (--ful instead of
+  // --full, --dry-Run) produces no error, no warning, and the option you
+  // meant to set just quietly keeps its default. Post-validate instead of
+  // trusting strict:false's leniency for everything.
+  assertKnownOptions(parsed.values, options, { command: 'canon build' });
 
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) {
@@ -38,14 +46,13 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
-  if (!existsSync(projectRoot)) {
-    throw inputError(
-      'INPUT_PROJECT_NOT_FOUND',
-      `Project directory not found: ${projectRoot}`,
-      `Run from the style-dataset-lab repo root, or scaffold the project with "sdlab init ${projectName}".`,
-    );
-  }
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver instead of
+  // join(process.cwd(), 'projects', projectName) — for a globally-installed
+  // sdlab the user is never inside the package directory, so process.cwd()
+  // silently pointed at the wrong place. getProjectRoot() also subsumes the
+  // existence check this used to do by hand (same INPUT_UNKNOWN_PROJECT shape
+  // as every other command, with an accurate "sdlab init" hint).
+  const projectRoot = getProjectRoot(projectName);
 
   const only = parsed.values.only
     ? parsed.values.only.split(',').map((s) => s.trim()).filter(Boolean)

package/scripts/canon-draft.js

@@ -0,0 +1,82 @@
+/**
+ * `sdlab canon draft <class_id> --endpoint <url> --brief "<text>" --out <path>`
+ *
+ * CLI wrapper for the Lane 2 canon and prompt authoring adapter (DESIGN-v3 §3.2,
+ * §11, G10). Calls a loopback-only OpenAI-compatible server (e.g., llama-server
+ * serving Muse-Glimmer-30B-A3B under Apache-2.0) and writes `prompts.jsonl`
+ * (+ `prompts.jsonl.sha256`) with `status: "draft"` and `judgment: null`.
+ */
+
+import { parseArgs } from 'node:util';
+import {
+  draftCanonClassViaEndpoint,
+  verifyGlimmerRuntime,
+  writePromptsJsonl,
+} from '../lib/canon-author.js';
+import { inputError } from '../lib/errors.js';
+import { assertKnownOptions } from './_shared-args.js';
+
+export async function run(argv) {
+  const options = {
+    endpoint:    { type: 'string', default: 'http://127.0.0.1:8080/v1/chat/completions' },
+    brief:       { type: 'string' },
+    out:         { type: 'string' },
+    build:       { type: 'string', default: 'b10353' },
+    vision:      { type: 'boolean', default: false },
+    mmproj:      { type: 'string' },
+    'mmproj-sha': { type: 'string' },
+    json:        { type: 'boolean', default: false },
+  };
+  const parsed = parseArgs({
+    args: argv,
+    options,
+    allowPositionals: true,
+    strict: false,
+  });
+  assertKnownOptions(parsed.values, options, { command: 'canon draft' });
+
+  const classId = parsed.positionals?.[0];
+  if (!classId) {
+    throw inputError(
+      'INPUT_MISSING_ARG',
+      'sdlab canon draft requires a <class_id> positional argument.'
+    );
+  }
+  if (!parsed.values.brief) {
+    throw inputError(
+      'INPUT_MISSING_FLAG',
+      'sdlab canon draft requires --brief "<description>".'
+    );
+  }
+
+  verifyGlimmerRuntime({
+    llamaServerBuild: parsed.values.build,
+    vision: Boolean(parsed.values.vision),
+    mmprojPath: parsed.values.mmproj || null,
+    mmprojSha256: parsed.values['mmproj-sha'] || null,
+    verifyFiles: false,
+  });
+
+  const draft = await draftCanonClassViaEndpoint({
+    endpoint: parsed.values.endpoint,
+    classId,
+    brief: parsed.values.brief,
+  });
+
+  let written = null;
+  if (parsed.values.out) {
+    written = writePromptsJsonl(parsed.values.out, [draft]);
+  }
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify({ ok: true, draft, written }, null, 2));
+    return;
+  }
+
+  console.log(`drafted "${classId}" (status=${draft.status}, judgment=${draft.judgment})`);
+  console.log(`  draft_sha256:    ${draft.draft_sha256}`);
+  console.log(`  messages_sha256: ${draft.messages_sha256}`);
+  if (written) {
+    console.log(`  prompts.jsonl:   ${written.promptsPath} (${written.sha256})`);
+  }
+}

package/scripts/canon-drift.js

@@ -19,24 +19,33 @@ import { loadSchema } from '../lib/canon-build/load-schema.js';
 import { readFreezeStatus, resolveWatchFields, computeWatchHash } from '../lib/freeze-stamp.js';
 import { readEventsSince } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    since:   { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      since:   { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag (e.g. --sinse instead of --since)
+  // silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon drift' });
 
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
 
   // Load latest build manifest for the stamped watch-hashes

package/scripts/canon-freeze-status.js

@@ -10,25 +10,33 @@ import { loadCanonEntriesInDir } from '../lib/canon-build/load-entry.js';
 import { readFreezeStatus, resolveWatchFields } from '../lib/freeze-stamp.js';
 import { readEventsFor } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon freeze-status' });
 
   const entityIdArg = (parsed.positionals || [])[0];
   if (!entityIdArg) throw inputError('INPUT_MISSING_ARG', 'sdlab canon freeze-status requires an entity id.');
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
 
   let resolved = null;

package/scripts/canon-freeze.js

@@ -17,24 +17,35 @@ import { loadBuildConfig } from '../lib/canon-build/load-config.js';
 import { loadCanonEntriesInDir, entryId } from '../lib/canon-build/load-entry.js';
 import { buildFreezeBlock, FREEZE_STATUSES, resolveWatchFields } from '../lib/freeze-stamp.js';
 import { appendEvent } from '../lib/freeze-events.js';
+import { assertDirectorRatifiedForFreeze } from '../lib/canon-review-gate.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    reason:  { type: 'string' },
+    status:  { type: 'string', default: 'frozen' },
+    watch:   { type: 'string' },
+    build:   { type: 'string' },
+    by:      { type: 'string', default: 'mike' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      reason:  { type: 'string' },
-      status:  { type: 'string', default: 'frozen' },
-      watch:   { type: 'string' },
-      build:   { type: 'string' },
-      by:      { type: 'string', default: 'mike' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  // This one matters more than most: `sdlab canon freeze X --staus
+  // soft-advisory` (typo) would silently keep status at its default
+  // 'frozen' — a HARD block — instead of the 'soft-advisory' the operator
+  // typed, and a typo'd --watch/--build silently drops a real override too.
+  assertKnownOptions(parsed.values, options, { command: 'canon freeze' });
 
   const positional = parsed.positionals || [];
   const entityIdArg = positional[0];
@@ -72,7 +83,13 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: was join(process.cwd(), 'projects', projectName) — wrong base for
+  // a globally-installed sdlab. getProjectRoot() resolves from the workspace
+  // root (not cwd) and throws a clear INPUT_UNKNOWN_PROJECT before ever
+  // reaching loadBuildConfig(), instead of a deeper, misleading
+  // CANON_BUILD_CONFIG_NOT_FOUND pointed at a config that "already exists" —
+  // just under a different (correct) project root.
+  const projectRoot = getProjectRoot(projectName);
   const configPath = join(projectRoot, 'canon-build', 'config.json');
   const config = await loadBuildConfig(configPath, projectRoot);
 
@@ -86,6 +103,9 @@ export async function run(argv) {
     );
   }
 
+  // G11: Refuse to freeze a model-drafted canon entry unless explicitly ratified by the Director
+  assertDirectorRatifiedForFreeze(resolved.entry.frontmatter);
+
   // Resolve the witness build hash
   const lockedAtBuild = parsed.values.build || await findLatestBuildHash(projectRoot);
   if (!lockedAtBuild) {

package/scripts/canon-unfreeze.js

@@ -18,21 +18,27 @@ import { loadCanonEntriesInDir } from '../lib/canon-build/load-entry.js';
 import { appendOverrideToFreezeBlock, readFreezeStatus } from '../lib/freeze-stamp.js';
 import { appendEvent } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    reason:  { type: 'string' },
+    by:      { type: 'string', default: 'mike' },
+    build:   { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      reason:  { type: 'string' },
-      by:      { type: 'string', default: 'mike' },
-      build:   { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon unfreeze' });
 
   const entityIdArg = (parsed.positionals || [])[0];
   if (!entityIdArg) {
@@ -48,7 +54,9 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
   const resolved = await findEntryFile(config, entityIdArg);
   if (!resolved) {

package/scripts/card.js

@@ -10,7 +10,7 @@
 import { join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
 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 { listSnapshots } from '../lib/snapshot.js';
 import { listSplits } from '../lib/split.js';
@@ -27,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 subcommand = positionals[0] || 'generate';
 
   if (subcommand === 'generate') {

package/scripts/colab/REAL_SERVICE_ASSUMPTIONS.md

@@ -0,0 +1,14 @@
+# Real-Service Assumption Audit (`scripts/colab/colab_window.sh`, `scripts/colab/launch_lane1_stub.sh`, `scripts/colab/launch_lane3_stub.sh`, `scripts/colab/remote_runner.py`, & `scripts/colab/launch_guards.py`)
+
+This document audits every interaction the style-dataset-lab Colab kits (`scripts/colab/colab_window.sh`, `scripts/colab/launch_lane1_stub.sh`, `scripts/colab/launch_lane3_stub.sh`, `scripts/colab/remote_runner.py`, and `scripts/colab/launch_guards.py`) have with the `colab` CLI (`google-colab-cli` v0.7.4, captured in `tests/colab/fixtures/colab_help.txt` and `tests/colab/fixtures/colab-cli-contract.json`) and the remote Colab IPython runtime.
+
+| # | Subcommand / Area | Help Line Relied On (`tests/colab/fixtures/colab_help.txt`) | Where Code Calls / Relies On It (`path:line`) | Fake Enforcement (`tests/colab/fixtures/fake_colab.py`) |
+|---:|---|---|---|---|
+| 1 | `usage` (text format, balance, and burn rate) | `Usage: colab usage [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:143`); live output lines `Current balance: <float> compute units`, `Usage rate: <float>/hr` (or `/h`), `Active assignments: <int>`. | `scripts/colab/colab_window.sh:43-128`, `scripts/colab/launch_guards.py:122-177`, `scripts/colab/launch_guards.py:180-217`, `scripts/colab/launch_lane1_stub.sh:109`, `scripts/colab/launch_lane3_stub.sh:110` | **Enforced** (`tests/colab/fixtures/fake_colab.py:390-416`): rejects any positionals or unknown flags; prints the 3-line text format; supports `usage_fail_start`, `usage_fail_midrun`, and `cap_burn` modes. `launch_guards.py:122-177` parses with anchored regexes (`CURRENT_BALANCE_RE`, `USAGE_RATE_RE`), removes any `10.0` fallback, records `null` plus `usage_parse_error` in `window.json`, and refuses/stops with `COLAB_USAGE_PARSE_FAILED` (including before `colab new` if the initial read fails). |
+| 2 | `new` (session open under lock) | `Usage: colab new [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:54`); options `--session -s <str>`, `--gpu <str>`, `--high-mem` (`tests/colab/fixtures/colab_help.txt:59-67`). | `scripts/colab/colab_window.sh:292-327`, `scripts/colab/launch_lane1_stub.sh:125-126`, `scripts/colab/launch_lane3_stub.sh:126-127` | **Enforced** (`tests/colab/fixtures/fake_colab.py:424-441`): validates options against `colab-cli-contract.json`, rejects any positional arguments, requires `-s/--session`, and records whether `/tmp/colab-window-open.lock` was held. |
+| 3 | `upload` (stage scripts and overrides to `/content/`) | `Usage: colab upload [OPTIONS] {local_path} {remote_path}` (`tests/colab/fixtures/colab_help.txt:95`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:104`). | `scripts/colab/launch_lane1_stub.sh:248-250`, `scripts/colab/launch_lane3_stub.sh:308-310` | **Enforced** (`tests/colab/fixtures/fake_colab.py:443-467`): requires `-s/--session` and exactly 2 positional arguments (`{local_path}` `{remote_path}`), verifies the local file exists and `{remote_path}` starts with `/content/`, and copies the file into the fake `/content` directory. |
+| 4 | `exec` (execute local `.py` file via `-f` with `--timeout` and `--env`) | `Usage: colab exec [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:80`); options `--session -s <str>`, `--file -f <str>`, `--timeout <float>`, `--env <str>` (`KEY=VALUE`, repeatable), `--output-image <str>` (`tests/colab/fixtures/colab_help.txt:85-90`). | `scripts/colab/colab_window.sh:181-282`, `scripts/colab/remote_runner.py:16-47`, `scripts/colab/launch_lane1_stub.sh:252-260`, `scripts/colab/launch_lane3_stub.sh:312-319` | **Enforced** (`tests/colab/fixtures/fake_colab.py:368-373` & `498-563`): refuses any positional command (`expected 0 positional arguments`), requires `-s/--session` and an existing `.py` file for `-f/--file`, validates `--timeout > 0` and `--env KEY=VALUE`, strips rig `PINNED_*` / `SDLAB_*` variables so only `--env` values reach the remote kernel, and executes the `.py` source with `cwd` set to the fake `/content` directory and `__file__` undefined. |
+| 5 | `exec` (unreliable CLI exit code; marker and bundle verification) | Inside `colab exec -f`, `__file__` is undefined, `cwd` is `/content`, and the CLI exit code is not reliable on remote exceptions or `sys.exit`. | `scripts/colab/remote_runner.py:30-46`, `scripts/colab/colab_window.sh:259-272`, `scripts/colab/launch_lane1_stub.sh:263-267`, `scripts/colab/launch_lane3_stub.sh:322-326` | **Enforced** (`tests/colab/fixtures/fake_colab.py:559-561`): `FAKE_COLAB_FORCE_EXEC_RC_ZERO` defaults to `"1"` (returning `0` from `colab exec` even when the remote script exits non-zero), so `colab_window.sh` and the kits decide success strictly from the streamed `SDLAB_REMOTE_RC=<rc>` marker line and the downloaded non-empty result bundle. |
+| 6 | `download` (fetch result bundle from `/content/` to rig) | `Usage: colab download [OPTIONS] {remote_path} {local_path}` (`tests/colab/fixtures/colab_help.txt:109`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:118`). | `scripts/colab/launch_lane1_stub.sh:263`, `scripts/colab/launch_lane3_stub.sh:322` | **Enforced** (`tests/colab/fixtures/fake_colab.py:469-486`): requires `-s/--session` and exactly 2 positional arguments (`{remote_path}` `{local_path}`), verifies `{remote_path}` is under `/content/`, and copies the artifact to `{local_path}`. |
+| 7 | `stop` (close session in `EXIT` trap) | `Usage: colab stop [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:123`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:128`). | `scripts/colab/colab_window.sh:284-290`, `scripts/colab/launch_lane1_stub.sh:93`, `scripts/colab/launch_lane3_stub.sh:94` | **Enforced** (`tests/colab/fixtures/fake_colab.py:488-496`): rejects any positional arguments, requires `-s/--session`, and logs `STOP -s <session>` to `stops.log`. |
+| 8 | `sessions` (verify active sessions after stop) | `Usage: colab sessions [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:71`); options `--help -h` (`tests/colab/fixtures/colab_help.txt:76`). | `scripts/colab/colab_window.sh:288` | **Enforced** (`tests/colab/fixtures/fake_colab.py:418-422`): rejects any positional arguments or unknown options and prints `[colab] No active sessions found on server.`. |

package/scripts/colab/ai-toolkit-override-py315.txt

@@ -0,0 +1,45 @@
+# CPython 3.15.1 dependency override file for ostris/ai-toolkit (Lane 3 LoRA training)
+# Upstream tracking issue: https://github.com/ostris/ai-toolkit/issues/1087
+# Reference: DESIGN-v3.md section 3.5 (CPython 3.15.1 wheel audit)
+# Note: av==16.0.1 and torchcodec==0.9.1 are dropped for image LoRA lanes.
+scipy==1.18.1
+matplotlib==3.11.2
+torchao==0.18.0
+safetensors==0.7.0
+transformers==5.5.3
+lycoris-lora==1.8.3
+flatten_json==0.1.14
+pyyaml==6.0.3
+oyaml==1.0
+tensorboard==2.20.0
+kornia==0.9.0
+invisible-watermark==0.2.0
+einops==0.8.2
+accelerate==1.13.0
+toml==0.10.2
+albumentations==1.4.15
+albucore==0.0.16
+pydantic==2.13.2
+omegaconf==2.3.0
+k-diffusion==0.1.1.post1
+open_clip_torch==3.3.0
+timm==1.0.22
+prodigyopt==1.1.2
+controlnet_aux==0.0.10
+python-dotenv==1.2.2
+bitsandbytes==0.49.2
+hf_transfer==0.1.9
+lpips==0.1.4
+pytorch_fid==0.3.0
+optimum-quanto==0.2.4
+sentencepiece==0.2.1
+huggingface_hub==1.10.1
+peft==0.18.1
+python-slugify==8.0.4
+opencv-python==4.13.0.92
+pytorch-wavelets==1.3.0
+setuptools==82.0.1
+librosa==0.11.0
+mutagen==1.47.0
+pillow==12.2.0
+numpy==2.4.4