@mcptoolshop/style-dataset-lab 3.0.1 → 3.2.0

package/scripts/canon-drift.js

@@ -0,0 +1,193 @@
+/**
+ * `sdlab canon drift` — drift report (D7 command).
+ *
+ * For every frozen or on-canon-change entry, computes the current watch-hash
+ * and compares against the hash stamped in the latest canon-build manifest.
+ * Surfaces:
+ *   - Frozen entries whose current projection drifts from their witness.
+ *   - on-canon-change entries where the watch-fields have changed since freeze.
+ *   - Overrides since a given build hash (or since the last clean build).
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadBuildConfig } from '../lib/canon-build/load-config.js';
+import { loadCanonEntriesInDir } from '../lib/canon-build/load-entry.js';
+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';
+
+export async function run(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    options: {
+      project: { type: 'string' },
+      game:    { type: 'string' },
+      since:   { type: 'string' },
+      json:    { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
+
+  // Load latest build manifest for the stamped watch-hashes
+  const latestManifest = await findLatestBuildManifest(projectRoot);
+
+  // Load schemas for version info
+  const schemas = {};
+  for (const schemaName of Object.keys(config.entity_dirs)) {
+    const path = join(config.schema_dir, schemaName);
+    schemas[schemaName] = await loadSchema(path);
+  }
+
+  // Walk entries, compute drift
+  const drifted = [];
+  const cleanFrozen = [];
+  let totalEntries = 0;
+  let autoCount = 0;
+
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    for (const entry of entries) {
+      totalEntries++;
+      const status = readFreezeStatus(entry.frontmatter);
+      if (status === 'auto') { autoCount++; continue; }
+
+      const watchFields = resolveWatchFields(entry.frontmatter, schemaName, config);
+      const currentHash = computeWatchHash(
+        entry.frontmatter,
+        watchFields,
+        schemas[schemaName].version,
+      );
+
+      // Look up stamped hash from latest manifest. The manifest stores a
+      // richer stamp object (status / watch_hash / watch_fields /
+      // locked_at_build); the drift comparison only needs `.watch_hash`.
+      const entityId = entry.frontmatter.id;
+      const stamp = latestManifest?.frozen_entries_hashes?.[entityId] || null;
+      const stampedHash = stamp?.watch_hash || null;
+
+      if (stampedHash && stampedHash !== currentHash) {
+        drifted.push({
+          entity_id: entityId,
+          schema_kind: schemaName.replace('.schema.json', ''),
+          status,
+          locked_at_build: stamp?.locked_at_build || entry.frontmatter.freeze?.locked_at_build || null,
+          witness_hash: stampedHash,
+          current_hash: currentHash,
+          watch_fields: watchFields,
+        });
+      } else if (stampedHash) {
+        cleanFrozen.push({
+          entity_id: entityId,
+          status,
+          witness_hash: stampedHash,
+        });
+      } else {
+        // Entry is frozen now but was not in the last build manifest (e.g.
+        // newly frozen since). Flag as "no witness yet" rather than mis-
+        // classifying as either drifted or clean.
+        cleanFrozen.push({
+          entity_id: entityId,
+          status,
+          witness_hash: null,
+          note: 'no witness in latest build — rebuild to stamp',
+        });
+      }
+    }
+  }
+
+  // Events since a reference build hash
+  const sinceHash = parsed.values.since || latestManifest?.generated_from || null;
+  const eventsSince = sinceHash
+    ? await readEventsSince(projectRoot, sinceHash)
+    : [];
+
+  const report = {
+    project_id: config.project_id,
+    latest_build: latestManifest?.generated_from || null,
+    latest_built_at: latestManifest?.built_at || null,
+    entities_total: totalEntries,
+    entities_auto: autoCount,
+    entities_frozen_clean: cleanFrozen.length,
+    entities_drifted: drifted.length,
+    drifted,
+    overrides_since: eventsSince.filter((e) => e.type !== 'freeze'),
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  renderHumanReport(report);
+}
+
+function renderHumanReport(r) {
+  console.log(`Drift report for ${r.project_id}`);
+  console.log(`  latest build:    ${r.latest_build || '(no build output found)'}`);
+  console.log(`  latest built_at: ${r.latest_built_at || '(unknown)'}`);
+  console.log('');
+  console.log(`  auto entries:            ${r.entities_auto}`);
+  console.log(`  frozen entries (clean):  ${r.entities_frozen_clean}`);
+  console.log(`  frozen entries (drift):  ${r.entities_drifted}`);
+  console.log('');
+
+  if (r.drifted.length > 0) {
+    console.log('Drifted frozen entries:');
+    for (const d of r.drifted) {
+      console.log(`  ${d.schema_kind}:${d.entity_id} (${d.status})`);
+      console.log(`    witness hash:  ${d.witness_hash.slice(0, 16)}...`);
+      console.log(`    current hash:  ${d.current_hash.slice(0, 16)}...`);
+      console.log(`    watch fields:  ${d.watch_fields.join(', ') || '(none)'}`);
+    }
+    console.log('');
+  } else if (r.entities_frozen_clean > 0) {
+    console.log('No drift detected on frozen entries.');
+    console.log('');
+  }
+
+  if (r.overrides_since.length > 0) {
+    console.log(`Overrides since last build (${r.overrides_since.length}):`);
+    for (const e of r.overrides_since) {
+      console.log(`  ${e.type.padEnd(10)} ${e.entity_id} by ${e.by} — ${e.reason}`);
+    }
+  }
+}
+
+async function findLatestBuildManifest(projectRoot) {
+  const canonBuildDir = join(projectRoot, 'canon-build');
+  if (!existsSync(canonBuildDir)) return null;
+  const entries = await readdir(canonBuildDir, { withFileTypes: true });
+  const candidates = entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !e.name.includes('.tmp'))
+    .map((e) => e.name);
+
+  let latest = null;
+  let latestTime = 0;
+  for (const name of candidates) {
+    const manifestPath = join(canonBuildDir, name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = JSON.parse(await readFile(manifestPath, 'utf-8'));
+      const built = new Date(manifest.built_at || 0).getTime();
+      if (built > latestTime) {
+        latestTime = built;
+        latest = manifest;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return latest;
+}

package/scripts/canon-freeze-status.js

@@ -0,0 +1,85 @@
+/**
+ * `sdlab canon freeze-status <entity_id>` — read-only glance at an entry's
+ * freeze state. Human-readable by default; --json for machine consumption.
+ */
+
+import { parseArgs } from 'node:util';
+import { join } from 'node:path';
+import { loadBuildConfig } from '../lib/canon-build/load-config.js';
+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';
+
+export async function run(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    options: {
+      project: { type: 'string' },
+      game:    { type: 'string' },
+      json:    { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  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);
+  const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
+
+  let resolved = null;
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    const hit = entries.find((e) => e.frontmatter?.id === entityIdArg);
+    if (hit) { resolved = { entry: hit, schemaName }; break; }
+  }
+  if (!resolved) throw inputError('CANON_ENTRY_NOT_FOUND', `No canon entry "${entityIdArg}".`);
+
+  const fm = resolved.entry.frontmatter;
+  const status = readFreezeStatus(fm);
+  const block = fm.freeze || {};
+  const events = await readEventsFor(projectRoot, entityIdArg);
+
+  // Entry override OR config default — the same resolution used by the
+  // build, so a reader sees the actual watched fields, not just what's
+  // literally in the entry frontmatter.
+  const resolvedWatchFields = resolveWatchFields(fm, resolved.schemaName, config);
+  const watchFieldsSource = Array.isArray(block.watch_fields) && block.watch_fields.length
+    ? 'entry-override'
+    : (resolvedWatchFields.length ? 'config-default' : 'none');
+
+  const result = {
+    entity_id: entityIdArg,
+    schema_kind: resolved.schemaName.replace('.schema.json', ''),
+    status,
+    locked_at_build: block.locked_at_build || null,
+    frozen_by: block.frozen_by || null,
+    frozen_reason: block.frozen_reason || null,
+    watch_fields: resolvedWatchFields,
+    watch_fields_source: watchFieldsSource,
+    overrides_count: Array.isArray(block.overrides) ? block.overrides.length : 0,
+    event_count: events.length,
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`${entityIdArg} (${result.schema_kind})`);
+  console.log(`  status:          ${status}`);
+  if (status !== 'auto') {
+    console.log(`  locked_at_build: ${result.locked_at_build || '(unset)'}`);
+    console.log(`  frozen_by:       ${result.frozen_by || '(unset)'}`);
+    console.log(`  frozen_reason:   ${result.frozen_reason || '(unset)'}`);
+    const fieldsDisplay = result.watch_fields.length ? result.watch_fields.join(', ') : '(none)';
+    console.log(`  watch_fields:    ${fieldsDisplay} [${result.watch_fields_source}]`);
+  }
+  console.log(`  overrides[]:     ${result.overrides_count} recorded on entry`);
+  console.log(`  event log:       ${result.event_count} events total`);
+}

package/scripts/canon-freeze.js

@@ -0,0 +1,211 @@
+/**
+ * `sdlab canon freeze <entity_id> --reason "<text>"` — stamp a freeze block
+ * on a canon entry (D7 command).
+ *
+ * Validates the entry exists, that a canon-build output exists to witness
+ * against (so the `locked_at_build` field has a real value — D1), rewrites
+ * the entry's frontmatter with the new `freeze` block, and appends a
+ * `freeze` event to freeze-events.jsonl (D4).
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+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 { inputError } from '../lib/errors.js';
+
+export async function run(argv) {
+  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 },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const positional = parsed.positionals || [];
+  const entityIdArg = positional[0];
+  if (!entityIdArg) {
+    throw inputError(
+      'INPUT_MISSING_ARG',
+      'sdlab canon freeze requires an entity id as the first positional argument.',
+      'Example: sdlab canon freeze heracles --reason "Labor III reference plate approved"',
+    );
+  }
+
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) {
+    throw inputError('INPUT_MISSING_FLAG', 'sdlab canon freeze requires --project <name>', 'Example: --project greek-rpg');
+  }
+
+  if (!parsed.values.reason) {
+    throw inputError(
+      'FREEZE_REASON_REQUIRED',
+      'sdlab canon freeze requires --reason "<short text>".',
+      'The reason lands in both the entry frontmatter and canon-build/freeze-events.jsonl as the audit record. Future you (and the LLM crew) need it to understand why.',
+    );
+  }
+
+  if (!FREEZE_STATUSES.includes(parsed.values.status)) {
+    throw inputError(
+      'INPUT_INVALID_VALUE',
+      `--status must be one of ${FREEZE_STATUSES.join(', ')} (got "${parsed.values.status}")`,
+    );
+  }
+  if (parsed.values.status === 'auto') {
+    throw inputError(
+      'INPUT_INVALID_VALUE',
+      '--status auto means "no freeze" — use `sdlab canon unfreeze` instead of freezing with status=auto.',
+    );
+  }
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  const configPath = join(projectRoot, 'canon-build', 'config.json');
+  const config = await loadBuildConfig(configPath, projectRoot);
+
+  // Find the entry file
+  const resolved = await findEntryFile(config, entityIdArg);
+  if (!resolved) {
+    throw inputError(
+      'CANON_ENTRY_NOT_FOUND',
+      `No canon entry with id "${entityIdArg}" found under ${config.canon_root}.`,
+      `Check the entry filename matches the id field, and that the schema-subdirectory mapping in canon-build/config.json covers this entity type.`,
+    );
+  }
+
+  // Resolve the witness build hash
+  const lockedAtBuild = parsed.values.build || await findLatestBuildHash(projectRoot);
+  if (!lockedAtBuild) {
+    throw inputError(
+      'FREEZE_NO_BUILD_WITNESS',
+      'No canon-build output exists to witness this freeze against.',
+      'Run `sdlab canon build` first to produce a build artifact, then retry the freeze. The witness chain (D1) requires a real build hash to stamp.',
+    );
+  }
+
+  // Resolve watch-fields: --watch override > entry override > config default
+  const watchFields = resolveEffectiveWatchFields({
+    entry: resolved.entry,
+    schemaName: resolved.schemaName,
+    buildConfig: config,
+    cliOverride: parsed.values.watch,
+  });
+
+  // Build the new freeze block, preserving existing overrides[] if any
+  const existing = resolved.entry.frontmatter.freeze || {};
+  const priorStatus = existing.status || 'auto';
+  const newBlock = buildFreezeBlock({
+    status: parsed.values.status,
+    lockedAtBuild,
+    frozenBy: parsed.values.by,
+    frozenReason: parsed.values.reason,
+    watchFields,
+    overrides: existing.overrides,
+  });
+
+  // Rewrite the entry file
+  const updatedFm = { ...resolved.entry.frontmatter, freeze: newBlock };
+  await rewriteEntryFrontmatter(resolved.filePath, updatedFm, resolved.entry.body);
+
+  // Append audit event
+  const event = await appendEvent(projectRoot, {
+    type: 'freeze',
+    entity_id: entityIdArg,
+    schema_kind: resolved.schemaName.replace('.schema.json', ''),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    new_status: parsed.values.status,
+    watch_fields: watchFields,
+    build_hash: lockedAtBuild,
+  });
+
+  const result = {
+    ok: true,
+    entity_id: entityIdArg,
+    status: parsed.values.status,
+    locked_at_build: lockedAtBuild,
+    watch_fields: watchFields,
+    event_at: event.at,
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`froze "${entityIdArg}" (${parsed.values.status}) witnessed at ${lockedAtBuild}`);
+  console.log(`  watching: ${watchFields.length ? watchFields.join(', ') : '(no fields — build-config has no default for this schema and no --watch was passed)'}`);
+  console.log(`  reason:   ${parsed.values.reason}`);
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+async function findEntryFile(config, entityId) {
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    for (const entry of entries) {
+      const id = entry.frontmatter?.id;
+      if (id === entityId) {
+        return { entry, schemaName, filePath: entry.filePath };
+      }
+    }
+  }
+  return null;
+}
+
+async function findLatestBuildHash(projectRoot) {
+  const canonBuildDir = join(projectRoot, 'canon-build');
+  if (!existsSync(canonBuildDir)) return null;
+  const entries = await readdir(canonBuildDir, { withFileTypes: true });
+  const buildDirs = entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !e.name.endsWith('.tmp') && !e.name.includes('.tmp-'))
+    .map((e) => e.name);
+  if (buildDirs.length === 0) return null;
+
+  // Pick the most recent by mtime of its manifest.json
+  let latest = null;
+  let latestMtime = 0;
+  for (const name of buildDirs) {
+    const manifestPath = join(canonBuildDir, name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = JSON.parse(await readFile(manifestPath, 'utf-8'));
+      const built = new Date(manifest.built_at || 0).getTime();
+      if (built > latestMtime) {
+        latestMtime = built;
+        latest = manifest.generated_from || name;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return latest;
+}
+
+function resolveEffectiveWatchFields({ entry, schemaName, buildConfig, cliOverride }) {
+  if (cliOverride) {
+    return cliOverride.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return resolveWatchFields(entry.frontmatter, schemaName, buildConfig);
+}
+
+async function rewriteEntryFrontmatter(filePath, frontmatter, body) {
+  const yaml = stringifyYaml(frontmatter).trimEnd();
+  const content = `---\n${yaml}\n---\n${body}`;
+  await writeFile(filePath, content, 'utf-8');
+}

package/scripts/canon-unfreeze.js

@@ -0,0 +1,137 @@
+/**
+ * `sdlab canon unfreeze <entity_id> --reason "<text>"` — lift a freeze (D7).
+ *
+ * Writes the entry's `freeze.status` to `auto`, appends an `unfreeze` event
+ * with the prior state captured. Preserves the `overrides[]` history on the
+ * entry (append-only) so re-freeze later shows the full lifecycle.
+ *
+ * --reason is REQUIRED — unfreezes are where shipping studios (Sabotage,
+ * Supergiant, Pentiment) most often wished they had captured intent.
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { loadBuildConfig } from '../lib/canon-build/load-config.js';
+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';
+
+export async function run(argv) {
+  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 },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const entityIdArg = (parsed.positionals || [])[0];
+  if (!entityIdArg) {
+    throw inputError('INPUT_MISSING_ARG', 'sdlab canon unfreeze requires an entity id.');
+  }
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
+  if (!parsed.values.reason) {
+    throw inputError(
+      'FREEZE_REASON_REQUIRED',
+      'sdlab canon unfreeze requires --reason "<text>".',
+      'Unfreezes are where shipping studios most often regret not capturing intent. The reason lands in canon-build/freeze-events.jsonl and in the entry frontmatter\'s overrides[] append-only log.',
+    );
+  }
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
+  const resolved = await findEntryFile(config, entityIdArg);
+  if (!resolved) {
+    throw inputError('CANON_ENTRY_NOT_FOUND', `No canon entry with id "${entityIdArg}".`);
+  }
+
+  const fm = resolved.entry.frontmatter;
+  const priorStatus = readFreezeStatus(fm);
+  if (priorStatus === 'auto') {
+    throw inputError(
+      'FREEZE_ALREADY_AUTO',
+      `Canon entry "${entityIdArg}" is already at status=auto; nothing to unfreeze.`,
+    );
+  }
+
+  const priorFreeze = fm.freeze || {};
+  const buildHash = parsed.values.build || priorFreeze.locked_at_build || null;
+
+  // Append override record to the entry's overrides[] log
+  const overrideRecord = {
+    at: buildHash || new Date().toISOString(),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    prior_build_hash: priorFreeze.locked_at_build || null,
+  };
+  const updatedBlock = appendOverrideToFreezeBlock(
+    { ...priorFreeze, status: 'auto' },
+    overrideRecord,
+  );
+  // Drop fields that only make sense on an active freeze
+  delete updatedBlock.locked_at_build;
+  delete updatedBlock.locked_at_canon_version;
+  delete updatedBlock.frozen_by;
+  delete updatedBlock.frozen_reason;
+  delete updatedBlock.watch_fields;
+
+  const updatedFm = { ...fm, freeze: updatedBlock };
+  await rewriteEntryFrontmatter(resolved.filePath, updatedFm, resolved.entry.body);
+
+  const event = await appendEvent(projectRoot, {
+    type: 'unfreeze',
+    entity_id: entityIdArg,
+    schema_kind: resolved.schemaName.replace('.schema.json', ''),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    new_status: 'auto',
+    prior_build_hash: priorFreeze.locked_at_build || null,
+    build_hash: buildHash,
+  });
+
+  const result = {
+    ok: true,
+    entity_id: entityIdArg,
+    prior_status: priorStatus,
+    new_status: 'auto',
+    event_at: event.at,
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`unfroze "${entityIdArg}" (was ${priorStatus})`);
+  console.log(`  reason: ${parsed.values.reason}`);
+  console.log(`  overrides[] history preserved with ${updatedBlock.overrides.length} entries`);
+}
+
+async function findEntryFile(config, entityId) {
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    for (const entry of entries) {
+      if (entry.frontmatter?.id === entityId) {
+        return { entry, schemaName, filePath: entry.filePath };
+      }
+    }
+  }
+  return null;
+}
+
+async function rewriteEntryFrontmatter(filePath, frontmatter, body) {
+  const yaml = stringifyYaml(frontmatter).trimEnd();
+  await writeFile(filePath, `---\n${yaml}\n---\n${body}`, 'utf-8');
+}

package/scripts/curate.js

@@ -17,6 +17,7 @@ import { REPO_ROOT } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { result } from "../lib/log.js";
+import { assertNotFrozenByAssetPath } from "../lib/freeze-gate.js";
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
@@ -27,6 +28,7 @@ export async function run(argv = process.argv.slice(2)) {
       notes: { type: 'string' },
       list: { type: 'boolean', default: false },
       'dry-run': { type: 'boolean', default: false },
+      'i-know': { type: 'boolean', default: false },
     },
     deprecated: { game: 'project' },
   });
@@ -106,6 +108,16 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
+  // Freeze gate: refuse to recurate to a path that a frozen canon entry owns.
+  // No-op when the project has no canon-build config. The explanation doubles
+  // as the bypass reason when the target entry is soft-advisory.
+  await assertNotFrozenByAssetPath(GAME_ROOT, newPath, {
+    action: 'curate',
+    allowSoftAdvisoryBypass: flags['i-know'],
+    bypassReason: explanation,
+    by: 'mike',
+  });
+
   await mkdir(join(GAME_ROOT, newDir), { recursive: true });
 
   // Move image FIRST — if the rename fails we still have a clean record.

package/scripts/generate-controlnet.js

@@ -19,6 +19,7 @@ import { REPO_ROOT, 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";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -177,6 +178,17 @@ export async function run(argv = process.argv.slice(2)) {
     throw inputError('INPUT_MISSING_FLAG', "--guide <path> is required");
   }
 
+  // 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;
+  await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
+    action: 'generate:controlnet',
+    allowSoftAdvisoryBypass: argv.includes('--i-know'),
+    bypassReason,
+    by: 'mike',
+  });
+
   // Validate guide stays inside the project tree.
   const safeGuide = resolveSafeProjectPath(GAME_ROOT, opts.guidePath, { flagName: 'guide' });