atris 3.56.1 → 3.56.2

package/commands/status.js

@@ -7,7 +7,9 @@ const { checkoutBehindMessage } = require('../lib/checkout-sync');
 const {
   isFreshWorkspace,
   isKeepWorkingMinute,
+  isClaimMinute,
   buildFirstMinute,
+  speakFirstMinute,
   speakKeepWorkingMinute,
   speakNothingRunning,
 } = require('../lib/first-minute');
@@ -146,13 +148,19 @@ function statusAtris(isQuick = false, jsonMode = false, verbose = false) {
   }
 
   // Just-minted file folder, nothing running: same two lines as
-  // first-minute / the next do. A live mission still gets the board.
-  // --verbose keeps the factory dump because the operator asked for it.
+  // first-minute / the next keep-working ready. After init, next is claim: same
+  // two lines as bare atris / now. Not factory let-it-run.
+  // A live mission still gets the board. --verbose keeps the
+  // factory dump because the operator asked for it. --json on
+  // the claim path keeps the factory board for scripts.
   if (!verbose && !hasLiveKeepWorkingRun()) {
     const minute = buildFirstMinute({ root: process.cwd() });
     if (isKeepWorkingMinute(minute)) {
       process.exit(speakKeepWorkingMinute({ asJson: jsonMode }));
     }
+    if (!jsonMode && isClaimMinute(minute)) {
+      process.exit(speakFirstMinute());
+    }
   }
 
   const targetDir = path.join(process.cwd(), 'atris');

package/commands/workflow.js

@@ -882,9 +882,10 @@ async function doAtris() {
   const targetDir = path.join(cwd, 'atris');
 
   // Empty folder talks like bare atris. Files already here start
-  // first-talk, then next is atris do. A second do stays two first-minute
-  // lines. Missing executor.md after init --minimal is optional
-  // context, not a factory bounce.
+  // first-talk, then next is atris do. After that work is yours,
+  // next is task ready so keep-working is not a do loop. Missing
+  // executor.md after init --minimal is optional context, not a
+  // factory bounce.
   if (!fs.existsSync(targetDir)) {
     const visible = listUserVisibleWork(cwd);
     if (visible.length) {

package/commands/youtube.js

@@ -53,7 +53,7 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('Options:');
   output('  --limit <n>         Max search results (default: 5)');
   output('  --paid              Bill 5 credits for watch permalinks (search only)');
-  output('  --save              File brief, journal line, and apply stub (notes and teach)');
+  output('  --save              File brief, journal, apply stub; teach also mints a keep/revert experiment');
   output('  --section <n>       Chapter to teach, 1-based (teach only, default: 1)');
   output('  --unsave            Delete filed brief and apply stub (no paid calls)');
   output('  --query, -q <text>  Focus question for the analysis');
@@ -1938,7 +1938,9 @@ async function runYoutubeSearch(args = [], deps = {}) {
 
 const YTTEACH_USAGE = 'usage: atris youtube teach <youtube-url> [--section N] [--save]';
 const TEACH_PAID_REFUSE = 'teach is free local captions. drop --paid.';
+const TEACH_THIN_REFUSE = 'thin: no number or named mechanism. no brief.';
 const TEACH_APPLY_NEXT_MESSAGE = APPLY_NEXT_MESSAGE;
+const TEACH_KEEP_RULE = 'keep only if measure.py moves 0→1. scores 1 only when the fixture contains the check tokens.';
 const MECHANISM_STOP = new Set([
   'the', 'this', 'that', 'and', 'but', 'for', 'with', 'from', 'you', 'we', 'they',
   'what', 'when', 'how', 'why', 'there', 'here', 'then', 'just', 'also', 'very',
@@ -2137,7 +2139,7 @@ function quoteYoutubeUrl(url) {
   return `"${String(url || '').replace(/"/g, '')}"`;
 }
 
-function formatTeachLesson({ url, section, chapters, chapter, cues, title } = {}) {
+function teachLessonFromCues({ url, section, chapters, chapter, cues, title } = {}) {
   const total = Array.isArray(chapters) && chapters.length ? chapters.length : 1;
   const heading = String(chapter?.title || 'full video').trim().toLowerCase();
   const videoTitle = String(title || '').trim().toLowerCase();
@@ -2166,13 +2168,293 @@ function formatTeachLesson({ url, section, chapters, chapter, cues, title } = {}
     lines.push('');
     lines.push('next: last section');
   }
-  return lines.join('\n');
+  return { text: lines.join('\n'), numbers, mechanisms };
+}
+
+function formatTeachLesson(opts) {
+  return teachLessonFromCues(opts).text;
+}
+
+function isThinTeachLesson(lesson = {}) {
+  const numbers = Array.isArray(lesson.numbers) ? lesson.numbers : [];
+  const mechanisms = Array.isArray(lesson.mechanisms) ? lesson.mechanisms : [];
+  return numbers.length === 0 && mechanisms.length === 0;
 }
 
 function teachBriefRel(id, section) {
   return `atris/wiki/briefs/youtube-${id}-s${section}.md`;
 }
 
+function teachExperimentSlug(id, section) {
+  const safe = String(id || 'video')
+    .toLowerCase()
+    .replace(/_/g, '-')
+    .replace(/[^a-z0-9-]+/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'video';
+  return `teach-${safe}-s${Number(section) || 1}`;
+}
+
+function teachExperimentRel(id, section) {
+  return `atris/experiments/${teachExperimentSlug(id, section)}`;
+}
+
+function teachCheckNeedles(lesson = {}) {
+  const mechanisms = Array.isArray(lesson.mechanisms) ? lesson.mechanisms : [];
+  const numbers = Array.isArray(lesson.numbers) ? lesson.numbers : [];
+  if (mechanisms[0]) return [String(mechanisms[0]).toLowerCase()];
+  if (numbers[0]) return [String(numbers[0]).toLowerCase()];
+  return [];
+}
+
+function teachCheckLine(lesson = {}) {
+  return oneTeachCheck(lesson.mechanisms || [], lesson.numbers || [], '');
+}
+
+function fileTeachExperiment({ cwd, url, section, lesson } = {}) {
+  try {
+    const id = videoIdFromUrl(url);
+    if (!id || !cwd) return null;
+    const slug = teachExperimentSlug(id, section);
+    const rel = `atris/experiments/${slug}`;
+    const dir = path.join(cwd, rel);
+    fs.mkdirSync(dir, { recursive: true });
+
+    const check = teachCheckLine(lesson);
+    const needles = teachCheckNeedles(lesson);
+    const applyRel = applySidecarRel(`${id}-s${section}`);
+    const program = [
+      '# Program',
+      '',
+      `Target: the taught fail-able check ${JSON.stringify(check)}. measure.py scores 1 only when the fixture contains ${needles.map((n) => JSON.stringify(n)).join(' and ') || 'the check tokens'}. The default fixture is the teach apply sidecar. Score is 0 if that file is missing or omits the token. Keep a candidate only when the score moves from 0 to 1.`,
+      '',
+    ].join('\n');
+
+    const measurePy = [
+      '"""Score whether the taught check is present in the product fixture."""',
+      '',
+      'from __future__ import annotations',
+      '',
+      'import json',
+      'import os',
+      'from pathlib import Path',
+      '',
+      '',
+      'EXPERIMENT_DIR = Path(__file__).resolve().parent',
+      `CHECK = ${JSON.stringify(check)}`,
+      `NEEDLES = ${JSON.stringify(needles)}`,
+      `DEFAULT_TARGET = ${JSON.stringify(applyRel)}`,
+      '',
+      '',
+      'def repo_root() -> Path:',
+      '    env = os.environ.get("ATRIS_REPO_ROOT")',
+      '    if env:',
+      '        return Path(env).resolve()',
+      '    return EXPERIMENT_DIR.parents[2]',
+      '',
+      '',
+      'def fixture_path():',
+      '    env = os.environ.get("ATRIS_TEACH_MEASURE_FIXTURE")',
+      '    if env:',
+      '        return Path(env).resolve()',
+      '    target = repo_root() / DEFAULT_TARGET',
+      '    return target if target.is_file() else None',
+      '',
+      '',
+      'def fail_payload(reason: str) -> dict:',
+      '    return {',
+      '        "score": 0,',
+      '        "passed": 0,',
+      '        "total": 1,',
+      '        "status": "fail",',
+      '        "reason": reason,',
+      '        "check": CHECK,',
+      '    }',
+      '',
+      '',
+      'def score_text(text: str) -> dict:',
+      '    blob = text.lower()',
+      '    found = bool(NEEDLES) and all(needle.lower() in blob for needle in NEEDLES)',
+      '    score = 1 if found else 0',
+      '    return {',
+      '        "score": score,',
+      '        "passed": score,',
+      '        "total": 1,',
+      '        "status": "pass" if score == 1 else "fail",',
+      '        "check": CHECK,',
+      '    }',
+      '',
+      '',
+      'def main() -> int:',
+      '    path = fixture_path()',
+      '    if path is None or not path.is_file():',
+      '        payload = fail_payload("fixture missing")',
+      '    else:',
+      '        payload = score_text(path.read_text(encoding="utf-8"))',
+      '    print(json.dumps(payload))',
+      '    return 0',
+      '',
+      '',
+      'if __name__ == "__main__":',
+      '    raise SystemExit(main())',
+      '',
+    ].join('\n');
+
+    const loopPy = [
+      '"""Keep a candidate only when the taught-check score moves from 0 to 1."""',
+      '',
+      'from __future__ import annotations',
+      '',
+      'import argparse',
+      'import csv',
+      'import json',
+      'import os',
+      'from pathlib import Path',
+      'import subprocess',
+      'import sys',
+      'from datetime import datetime, timezone',
+      '',
+      '',
+      'EXPERIMENT_DIR = Path(__file__).resolve().parent',
+      'DEFAULT_MEASURE = EXPERIMENT_DIR / "measure.py"',
+      'DEFAULT_RESULTS = EXPERIMENT_DIR / "results.tsv"',
+      '',
+      '',
+      'def run_measure(measure_path: Path) -> dict:',
+      '    proc = subprocess.run(',
+      '        [sys.executable, str(measure_path)],',
+      '        cwd=str(EXPERIMENT_DIR),',
+      '        capture_output=True,',
+      '        text=True,',
+      '        check=True,',
+      '    )',
+      '    return json.loads(proc.stdout.strip().splitlines()[-1])',
+      '',
+      '',
+      'def append_result(results_path: Path, row: dict) -> None:',
+      '    write_header = not results_path.exists() or results_path.stat().st_size == 0',
+      '    with results_path.open("a", newline="", encoding="utf-8") as handle:',
+      '        writer = csv.DictWriter(',
+      '            handle,',
+      '            fieldnames=[',
+      '                "timestamp",',
+      '                "trial",',
+      '                "status",',
+      '                "old_score",',
+      '                "new_score",',
+      '                "proposal",',
+      '                "description",',
+      '            ],',
+      '            delimiter="\\t",',
+      '        )',
+      '        if write_header:',
+      '            writer.writeheader()',
+      '        writer.writerow(row)',
+      '',
+      '',
+      'def main() -> int:',
+      '    parser = argparse.ArgumentParser(description="Run the taught-check keep/revert loop.")',
+      '    parser.add_argument("--proposal", action="append", default=[])',
+      '    args = parser.parse_args()',
+      '',
+      '    measure_path = DEFAULT_MEASURE.resolve()',
+      '    results_path = DEFAULT_RESULTS.resolve()',
+      '',
+      '    baseline = run_measure(measure_path)',
+      '    current_score = float(baseline["score"])',
+      '    print(f"BASELINE {current_score:.4f}")',
+      '',
+      '    if not args.proposal:',
+      '        append_result(',
+      '            results_path,',
+      '            {',
+      '                "timestamp": datetime.now(timezone.utc).isoformat(),',
+      '                "trial": 0,',
+      '                "status": "baseline",',
+      '                "old_score": f"{current_score:.4f}",',
+      '                "new_score": f"{current_score:.4f}",',
+      '                "proposal": "measure.py",',
+      '                "description": "current taught-check fixture score",',
+      '            },',
+      '        )',
+      '',
+      '    for trial_index, proposal in enumerate(args.proposal, start=1):',
+      '        proposal_path = Path(proposal).resolve()',
+      '        status = "error"',
+      '        old_score = current_score',
+      '        new_score = current_score',
+      '        description = ""',
+      '',
+      '        try:',
+      '            proc = subprocess.run(',
+      '                [sys.executable, str(proposal_path)],',
+      '                cwd=str(EXPERIMENT_DIR),',
+      '                capture_output=True,',
+      '                text=True,',
+      '                check=True,',
+      '                env={**os.environ, "EXPERIMENT_DIR": str(EXPERIMENT_DIR)},',
+      '            )',
+      '            if proc.stdout.strip():',
+      '                description = proc.stdout.strip().splitlines()[-1][:200]',
+      '',
+      '            measured = run_measure(measure_path)',
+      '            new_score = float(measured["score"])',
+      '            if old_score < 1 and new_score > old_score:',
+      '                status = "kept"',
+      '                current_score = new_score',
+      '            else:',
+      '                status = "reverted"',
+      '        except subprocess.CalledProcessError as exc:',
+      '            stderr = (exc.stderr or exc.stdout or "").strip()',
+      '            description = (stderr.splitlines()[-1] if stderr else "proposal failed")[:200]',
+      '            status = "error"',
+      '',
+      '        append_result(',
+      '            results_path,',
+      '            {',
+      '                "timestamp": datetime.now(timezone.utc).isoformat(),',
+      '                "trial": trial_index,',
+      '                "status": status,',
+      '                "old_score": f"{old_score:.4f}",',
+      '                "new_score": f"{new_score:.4f}",',
+      '                "proposal": proposal_path.name,',
+      '                "description": description,',
+      '            },',
+      '        )',
+      '        print(f"TRIAL {trial_index} {status.upper()} score={new_score:.4f} proposal={proposal_path.name}")',
+      '',
+      '    final_measure = run_measure(measure_path)',
+      '    print(f"FINAL {final_measure[\'score\']:.4f}")',
+      '    return 0',
+      '',
+      '',
+      'if __name__ == "__main__":',
+      '    raise SystemExit(main())',
+      '',
+    ].join('\n');
+
+    fs.writeFileSync(path.join(dir, 'program.md'), program);
+    fs.writeFileSync(path.join(dir, 'measure.py'), measurePy);
+    fs.writeFileSync(path.join(dir, 'loop.py'), loopPy);
+    fs.writeFileSync(
+      path.join(dir, 'reset.py'),
+      [
+        '"""The target is the product fixture, not a local candidate file."""',
+        '',
+        'print("teach experiment target is the apply sidecar or ATRIS_TEACH_MEASURE_FIXTURE; nothing local to restore")',
+        '',
+      ].join('\n'),
+    );
+    fs.writeFileSync(
+      path.join(dir, 'results.tsv'),
+      'timestamp\ttrial\tstatus\told_score\tnew_score\tproposal\tdescription\n',
+    );
+    return rel;
+  } catch {
+    return null;
+  }
+}
+
 function fileTeachBrief({ cwd, url, section, lesson, now } = {}) {
   try {
     const id = videoIdFromUrl(url);
@@ -2208,16 +2490,22 @@ function fileTeachBrief({ cwd, url, section, lesson, now } = {}) {
   }
 }
 
-function ensureTeachApply({ cwd, url, section, now, output } = {}) {
+function ensureTeachApply({ cwd, url, section, packRel, now, output } = {}) {
   const id = videoIdFromUrl(url);
+  const pack = packRel || (id ? teachExperimentRel(id, section) : null);
   return applyGate.ensureApply({
     cwd,
     source: url,
     rel: id ? applySidecarRel(`${id}-s${section}`) : null,
     now,
     output,
-    incompleteMessage: TEACH_APPLY_NEXT_MESSAGE,
+    incompleteMessage: pack
+      ? `next: apply ${pack}. keep only if measure.py moves 0→1`
+      : TEACH_APPLY_NEXT_MESSAGE,
     required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
   });
 }
 
@@ -2285,7 +2573,7 @@ async function runYoutubeTeach(args = [], deps = {}) {
 
   const chapter = chapters[parsed.section - 1];
   const cues = sliceCuesForChapter(source.cues, chapter);
-  const lesson = formatTeachLesson({
+  const lesson = teachLessonFromCues({
     url: parsed.url,
     section: parsed.section,
     chapters,
@@ -2293,22 +2581,33 @@ async function runYoutubeTeach(args = [], deps = {}) {
     cues,
     title: source.title,
   });
-  output(lesson);
+  output(lesson.text);
 
   if (!parsed.save) return 0;
+  if (isThinTeachLesson(lesson)) {
+    output(TEACH_THIN_REFUSE);
+    return 2;
+  }
 
   fileTeachBrief({
     cwd: deps.cwd || process.cwd(),
     url: parsed.url,
     section: parsed.section,
-    lesson,
+    lesson: lesson.text,
     now: deps.now,
   });
+  const packRel = fileTeachExperiment({
+    cwd: deps.cwd || process.cwd(),
+    url: parsed.url,
+    section: parsed.section,
+    lesson,
+  });
   const ensureApply = deps.ensureApply || ensureTeachApply;
   return ensureApply({
     cwd: deps.cwd || process.cwd(),
     url: parsed.url,
     section: parsed.section,
+    packRel,
     now: deps.now,
     output,
   });
@@ -2404,5 +2703,8 @@ module.exports = {
   extractTeachNumbers,
   extractTeachMechanisms,
   extractTeachSource,
+  isThinTeachLesson,
+  TEACH_THIN_REFUSE,
+  teachExperimentSlug,
   youtubeCommand,
 };

package/lib/apply-gate.js

@@ -46,7 +46,7 @@ function readApplyReceipt({ cwd, rel } = {}) {
   return { rel, text: fs.readFileSync(abs, 'utf8') };
 }
 
-function writeApplyStub({ cwd, source, rel, now } = {}) {
+function writeApplyStub({ cwd, source, rel, now, change, receipt, journalLine } = {}) {
   try {
     if (!rel || !cwd) return null;
     const wikiDir = path.join(cwd, 'atris', 'wiki');
@@ -54,11 +54,17 @@ function writeApplyStub({ cwd, source, rel, now } = {}) {
 
     const abs = path.join(cwd, rel);
     fs.mkdirSync(path.dirname(abs), { recursive: true });
-    if (!fs.existsSync(abs)) {
+    const changeText = change || 'fill this';
+    const receiptText = receipt || 'fill this';
+    let shouldWrite = !fs.existsSync(abs);
+    if (!shouldWrite && change && receipt) {
+      shouldWrite = !isFilledApply(parseApplyFields(fs.readFileSync(abs, 'utf8')));
+    }
+    if (shouldWrite) {
       fs.writeFileSync(abs, [
         `source: ${source}`,
-        'change: fill this',
-        'receipt: fill this',
+        `change: ${changeText}`,
+        `receipt: ${receiptText}`,
       ].join('\n') + '\n');
     }
 
@@ -67,7 +73,7 @@ function writeApplyStub({ cwd, source, rel, now } = {}) {
     fs.mkdirSync(path.dirname(journalPath), { recursive: true });
     let existing = '';
     if (fs.existsSync(journalPath)) existing = fs.readFileSync(journalPath, 'utf8');
-    const line = `- [claimable] apply: fill this -> ${rel}`;
+    const line = journalLine || `- [claimable] apply: fill this -> ${rel}`;
     if (!existing.includes(line)) {
       const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
       fs.writeFileSync(journalPath, `${existing}${prefix}${line}\n`);
@@ -78,11 +84,13 @@ function writeApplyStub({ cwd, source, rel, now } = {}) {
   }
 }
 
-function ensureApply({ cwd, source, rel, now, output, incompleteMessage, required = true } = {}) {
+function ensureApply({
+  cwd, source, rel, now, output, incompleteMessage, required = true, change, receipt, journalLine,
+} = {}) {
   const print = typeof output === 'function' ? output : (line = '') => console.error(line);
   const existing = readApplyReceipt({ cwd, rel });
   if (existing && isFilledApply(parseApplyFields(existing.text))) return 0;
-  if (!(required && existing)) writeApplyStub({ cwd, source, rel, now });
+  if (!(required && existing)) writeApplyStub({ cwd, source, rel, now, change, receipt, journalLine });
   print(incompleteMessage);
   return required ? 2 : 0;
 }

package/lib/config-guard.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+const SETTINGS_NAME = 'settings.json';
+const CLAUDE_DIR_NAME = '.claude';
+const DENY_REASON = 'pack runs cannot change .claude/settings.json to add SessionStart or disable hooks';
+
+function expandUserPath(value, home) {
+  const text = String(value);
+  if (text === '~') return home;
+  if (text.startsWith('~/') || text.startsWith('~\\')) return path.join(home, text.slice(2));
+  return text;
+}
+
+function asText(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function settingsPlantPersistence(value) {
+  if (!value || typeof value !== 'object') return false;
+  if (value.disableAllHooks === true) return true;
+  if (value.hooks && Object.prototype.hasOwnProperty.call(value.hooks, 'SessionStart')) return true;
+  return Object.values(value).some((entry) => settingsPlantPersistence(entry));
+}
+
+function plantsPersistence(text) {
+  const source = asText(text);
+  if (!source) return false;
+  if (/\bSessionStart\b/.test(source)) return true;
+  if (/["']?disableAllHooks["']?\s*:\s*true\b/.test(source)) return true;
+  try {
+    return settingsPlantPersistence(JSON.parse(source));
+  } catch {
+    return false;
+  }
+}
+
+function isClaudeSettingsPath(value, options = {}) {
+  if (typeof value !== 'string' || !value.trim()) return false;
+  const home = options.home || os.homedir();
+  const cwd = options.cwd || process.cwd();
+  const expanded = expandUserPath(value.trim(), home);
+  const resolved = path.resolve(cwd, expanded);
+  if (path.basename(resolved) === SETTINGS_NAME && path.basename(path.dirname(resolved)) === CLAUDE_DIR_NAME) {
+    return true;
+  }
+  const configDir = path.resolve(
+    options.configDir
+      || process.env.CLAUDE_CONFIG_DIR
+      || path.join(home, CLAUDE_DIR_NAME),
+  );
+  return resolved === path.join(configDir, SETTINGS_NAME);
+}
+
+function commandMentionsClaudeSettings(command) {
+  const text = String(command || '');
+  if (!text.trim()) return false;
+  return /(?:^|[^\w])(?:~\/|\.\/|(?:\.\.\/)+)?(?:\$\{?HOME\}?\/)?\.claude\/settings\.json\b/.test(text)
+    || /\$\{?CLAUDE_CONFIG_DIR\}?\/settings\.json/.test(text)
+    || /(?:^|[^\w])(?:\$HOME|\$\{HOME\})\/\.claude\/settings\.json\b/.test(text);
+}
+
+function fileToolPath(input) {
+  const toolInput = (input && input.tool_input) || {};
+  return toolInput.file_path || toolInput.path || null;
+}
+
+function bashCommand(input) {
+  const toolInput = (input && input.tool_input) || {};
+  return toolInput.command || toolInput.cmd || '';
+}
+
+function writeContents(input) {
+  const toolInput = (input && input.tool_input) || {};
+  return toolInput.contents ?? toolInput.content ?? toolInput.new_string ?? '';
+}
+
+function enforceConfigGuard(input, options = {}) {
+  const tool = input && input.tool_name;
+  if (tool === 'Write' || tool === 'Edit') {
+    if (!isClaudeSettingsPath(fileToolPath(input), options)) return { allowed: true };
+    if (!plantsPersistence(writeContents(input))) return { allowed: true };
+    return { allowed: false, reason: DENY_REASON };
+  }
+  if (tool === 'Bash') {
+    if (!commandMentionsClaudeSettings(bashCommand(input))) return { allowed: true };
+    return { allowed: false, reason: DENY_REASON };
+  }
+  return { allowed: true };
+}
+
+module.exports = {
+  DENY_REASON,
+  commandMentionsClaudeSettings,
+  enforceConfigGuard,
+  isClaudeSettingsPath,
+  plantsPersistence,
+};

package/lib/engine-registry.js

@@ -68,6 +68,14 @@ function engineRegistryFile(root = process.cwd()) {
   return path.join(root, '.atris', 'state', 'engines.json');
 }
 
+// A scratch folder is not a room. First-touch seed must not mint .atris/.
+// Updates stay allowed once the file or a real workspace already exists.
+function canPersistEngineRegistry(root = process.cwd()) {
+  if (fs.existsSync(engineRegistryFile(root))) return true;
+  return fs.existsSync(path.join(root, 'atris'))
+    || fs.existsSync(path.join(root, '.atris', 'business.json'));
+}
+
 // Machine probe. Routing never calls this on a settled registry: it runs once
 // when an engine first appears (seeding the policy file), at the execution
 // stage right before a spawn, and on the explicit `atris engine doctor`.
@@ -239,14 +247,16 @@ function setEngineOverrides(name, overrides = {}, root = process.cwd()) {
 }
 
 // A read only writes when normalization actually changed the saved engines
-// (first seed, schema drift). Settled registries stay untouched, so read
-// paths cannot stomp a mutation another process just landed. The comparison
-// uses the same raw snapshot the seed was built from: one read, one decision.
+// (first seed, schema drift) and this folder is already a room or already
+// has engines.json. Empty scratch stays empty. Settled registries stay
+// untouched, so read paths cannot stomp a mutation another process just
+// landed. The comparison uses the same raw snapshot the seed was built from:
+// one read, one decision.
 function readEngineRegistry(root = process.cwd(), options = {}) {
   const raw = readRawRegistry(engineRegistryFile(root));
   const registry = seededRegistry(root, raw);
   const needsPersist = JSON.stringify(raw.engines || []) !== JSON.stringify(registry.engines);
-  if (options.persist !== false && needsPersist) {
+  if (options.persist !== false && needsPersist && canPersistEngineRegistry(root)) {
     writeEngineRegistry(root, registry);
   }
   return registry;