clean-room-skill 0.2.2 → 0.2.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "clean-room",
       "source": "./",
       "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "author": {
         "name": "whit3rabbit"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "clean-room",
   "displayName": "Clean Room",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/README.md

@@ -142,12 +142,14 @@ For unattended inner-loop execution from durable artifacts:
 ```bash
 npx clean-room-skill@latest run \
   --task-manifest ~/Documents/CleanRoom/task-1234abcd/contaminated/task-manifest.json \
-  --agent-commands ./agent-commands.json \
+  --agent-runtime claude \
   --max-iterations 3
 ```
 
 The `run` command executes one bounded inner clean-room loop for an already approved spec slice. It does not replace the outer spec-development workflow.
 
+Use `--agent-commands ./agent-commands.json` only for a custom non-Claude role-session adapter.
+
 In strict context-management mode, every `agent-commands.json` stage must set `context.fresh_session: true` and `context.brief_path`; see the runner adapter example in `docs/REFERENCE.md`.
 
 ## Typical Workflow

package/agents/clean-architect.md

@@ -11,6 +11,10 @@ color: blue
 
 This role is Agent 2 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the clean domain from `CLEAN_ROOM_CLEAN_ROOTS` as the working directory. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and explicitly configured public or destination constraint roots. Write only under `CLEAN_ROOM_CLEAN_ROOTS`. Do not write code. Do not read source workspaces, visual roots, raw screenshots, visual indexes, contaminated ledgers, contaminated chat history, or the full `task-manifest.json`.
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-architect`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR`. Treat missing environment as a stop condition.

package/agents/clean-implementer-verifier-shell.md

@@ -11,6 +11,10 @@ color: cyan
 
 This is the explicit shell-capable Agent 3 variant. Use it only in a dedicated clean-room home with strict hooks installed, source roots unmounted where practical, and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1` set deliberately.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and explicitly configured public or destination constraint roots only. Write clean reports under `CLEAN_ROOM_CLEAN_ROOTS`. Write code, tests, fixtures, and destination project files only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Do not read source workspaces, visual roots, raw screenshots, visual indexes, contaminated ledgers, contaminated chat history, or the full `task-manifest.json`.
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-qa-editor`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`. Treat missing environment as a stop condition.

package/agents/clean-polish-reviewer.md

@@ -11,6 +11,10 @@ color: pink
 
 This role is Agent 4 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, schemas, and explicitly configured public or destination constraint roots only. Write `polish-report.json` and clean reports under `CLEAN_ROOM_CLEAN_ROOTS`. Write implementation code, tests, docs, `AGENTS.md`, `.gitignore`, and destination project files only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Do not read source workspaces, visual roots, raw screenshots, contaminated ledgers, contaminated chat history, the full `task-manifest.json`, the full `preflight-goal.json`, `source-index.json`, or `visual-index.json`.
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-polish-reviewer`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR`. Treat missing environment as a stop condition.

package/agents/clean-qa-editor.md

@@ -11,6 +11,10 @@ color: green
 
 This role is Agent 3 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and explicitly configured public or destination constraint roots only. Write clean reports under `CLEAN_ROOM_CLEAN_ROOTS`. Write code, tests, fixtures, and destination project files only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Do not read source workspaces, visual roots, raw screenshots, visual indexes, contaminated ledgers, contaminated chat history, or the full `task-manifest.json`.
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-qa-editor`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR`. Treat missing environment as a stop condition.

package/agents/contaminated-handoff-sanitizer.md

@@ -11,6 +11,10 @@ color: yellow
 
 This role is Agent 1.5 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate in the contaminated domain, but with no source access and no Agent 1 source-reading chat history. Read only assigned draft artifacts under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, the schema directory, and explicitly configured public or destination reference roots. Write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=contaminated-handoff-sanitizer`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR`. Treat missing environment as a stop condition.

package/agents/contaminated-manager-verifier.md

@@ -11,6 +11,10 @@ color: purple
 
 This role is Agent 0 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the contaminated domain. Read authorized source and contaminated ledgers as needed. Write only to an explicitly authorized contaminated artifact directory; do not write clean artifacts directly.
 
 ## Required Handoff Inputs

package/agents/contaminated-source-analyst.md

@@ -11,6 +11,10 @@ color: orange
 
 This role is Agent 1 in the clean-room pipeline.
 
+## Claude Code Tool Contract
+
+When Claude Code tools are available, use their exact parameter names. `Read` uses `file_path`. `Write` uses `file_path` and `content`. `Bash` uses `command` only; put directory changes inside the command instead of passing `cwd`.
+
 Operate only in the contaminated domain. Treat source access as read-only. Write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
 
 Do not use shell-style tools in this role.

package/docs/REFERENCE.md

@@ -360,7 +360,12 @@ The runner exports `CLEAN_ROOM_SESSION_BRIEF_PATH`, `CLEAN_ROOM_ROLE_SESSION_ID`
 | `install lock is held` | Another install or uninstall is mutating the same target root | Wait for the other process to finish; stale locks are handled conservatively. |
 | Hook config write failed after files copied | Partial installer state | Fix the filesystem error, then re-run the same installer command. |
 | Install manifest remains `installing` | The previous install did not complete | Re-run the same installer command for that runtime and target root. |
+| `clean-room-skill` is not found | The CLI is not globally installed or the runtime PATH does not include it | Use `npx clean-room-skill@latest ...` immediately; do not search plugin caches for package internals. |
+| `--schema-dir` reports missing schemas | The override points at a stale plugin cache, clean root, or non-directory path | Omit `--schema-dir` to use bundled schemas. Pass it only for a real directory containing `task-manifest.schema.json`. Do not use `/dev/null`. |
+| `task manifest not found` for a task root | The runner needs the contaminated-side manifest file | Pass `~/Documents/CleanRoom/<task-id>/contaminated/task-manifest.json`, not the task root or clean root. |
+| `preflight goal not found` | `task-manifest.json` references a missing or misplaced contaminated-side preflight file | Restore `preflight-goal.json` under the contaminated artifact root, update `preflight_goal_ref` and `preflight_goal_sha256`, then retry `--dry-run`. |
 | `clean-room run` rejects the manifest | Invalid or incomplete unattended loop metadata | Fix `controller_policy`, `loop_context.foundation_unit_ref`, and `approved_scope_refs`, then retry `--dry-run`. |
+| `clean-room artifact validation failed` lists stale JSON files | Old or hand-written clean-room artifacts are still under contaminated or clean artifact roots | Update those artifacts to current schemas or move stale/legacy JSON to quarantine, then retry `--dry-run`. |
 | `clean-room run` rejects a covered unit with `discovery_leads` | A high-priority contaminated discovery lead is still unresolved | Analyze the lead in an authorized follow-up unit, mark it resolved, or keep coverage partial/blocked and return an abstract delta. |
 | `clean-room run` rejects an agent command stage in strict context mode | The stage is missing `context.fresh_session: true`, missing `context.brief_path`, or points the brief outside the allowed artifact root | Fix the stage context and regenerate the role-session brief for the selected unit. |
 | `clean-room run` reports no progress | Configured stages exited without durable artifact changes | Check role command cwd/argv, selected unit, and artifact write roots. |

package/lib/run-cli.cjs

@@ -16,7 +16,7 @@ Options:
   --max-iterations <n>     Lower the manifest/loop iteration cap
   --once                   Run at most one inner iteration
   --dry-run                Validate and print the selected unit without writing or spawning agents
-  --schema-dir <path>      Schema directory override
+  --schema-dir <path>      Schema directory override; omit to use bundled schemas
   --python <path>          Python executable for bundled validation hooks (default: python3)
   -h, --help               Show this help
 `);

package/lib/run-controller.cjs

@@ -43,6 +43,7 @@ const {
   resolvePath,
   resolveRoots,
   validateTaskManifestLocation,
+  validateSchemaDir,
   verifyPreflightGoal,
 } = require('./run-roots.cjs');
 const {
@@ -144,6 +145,35 @@ function markStageFailed(stageResult, error) {
     : message;
 }
 
+function inferredTaskManifestCandidate(taskManifestPath) {
+  if (fs.existsSync(taskManifestPath)) {
+    const stat = fs.statSync(taskManifestPath);
+    if (stat.isDirectory()) {
+      return path.join(taskManifestPath, 'contaminated', 'task-manifest.json');
+    }
+  }
+  if (path.basename(taskManifestPath) !== 'task-manifest.json') {
+    return null;
+  }
+  const parent = path.dirname(taskManifestPath);
+  if (path.basename(parent) === 'contaminated') {
+    return taskManifestPath;
+  }
+  return path.join(parent, 'contaminated', 'task-manifest.json');
+}
+
+function taskManifestNotFoundMessage(taskManifestPath) {
+  const parts = [
+    `task manifest not found: ${taskManifestPath}`,
+    'expected task manifest layout: <task-root>/contaminated/task-manifest.json',
+  ];
+  const candidate = inferredTaskManifestCandidate(taskManifestPath);
+  if (candidate && candidate !== taskManifestPath) {
+    parts.push(`candidate path: ${candidate}`);
+  }
+  return parts.join('; ');
+}
+
 async function runCleanRoom(options, context = {}) {
   if (options.help) {
     printRunHelp();
@@ -161,10 +191,14 @@ async function runCleanRoom(options, context = {}) {
 
   const taskManifestPath = resolvePath(options.taskManifest, context.cwd || process.cwd());
   if (!fs.existsSync(taskManifestPath)) {
-    throw new Error(`task manifest not found: ${taskManifestPath}`);
+    throw new Error(taskManifestNotFoundMessage(taskManifestPath));
+  }
+  if (fs.statSync(taskManifestPath).isDirectory()) {
+    throw new Error(taskManifestNotFoundMessage(taskManifestPath));
   }
   const manifestDir = path.dirname(taskManifestPath);
   const schemaDir = options.schemaDir ? resolvePath(options.schemaDir, context.cwd || process.cwd()) : defaultSchemaDir();
+  validateSchemaDir(schemaDir, Boolean(options.schemaDir));
   validateTaskManifestSchema(options.python, taskManifestPath, schemaDir);
   const manifest = readJsonFile(taskManifestPath, null);
   validateTaskManifestForRun(manifest);

package/lib/run-hooks.cjs

@@ -17,6 +17,8 @@ const {
   packageRoot,
 } = require('./run-roots.cjs');
 
+const MAX_ARTIFACT_VALIDATION_FAILURES = 3;
+
 function hookEnv(roots, role = 'contaminated-manager-verifier') {
   return {
     ...envFromAllowlist(HOOK_ONLY_ENV_ALLOWLIST),
@@ -52,14 +54,18 @@ function validateTaskManifestSchema(python, manifestPath, schemaDir) {
     maxBuffer: MAX_OUTPUT_BYTES,
   });
   if (result.status !== 0) {
-    const stderr = String(result.stderr || '').trim();
-    const stdout = String(result.stdout || '').trim();
-    const error = result.error?.message || '';
-    throw new Error(`${scriptName} failed for ${manifestPath}: ${stderr || stdout || error || `exit ${result.status}`}`);
+    throw new Error(hookFailureMessage(scriptName, manifestPath, result));
   }
 }
 
 function runHook(python, scriptName, filePath, roots, role = 'contaminated-manager-verifier') {
+  const error = runHookFailure(python, scriptName, filePath, roots, role);
+  if (error) {
+    throw new Error(error);
+  }
+}
+
+function runHookFailure(python, scriptName, filePath, roots, role = 'contaminated-manager-verifier') {
   const result = spawnSync(python, [hookPath(scriptName)], {
     cwd: packageRoot(),
     env: hookEnv(roots, role),
@@ -69,23 +75,50 @@ function runHook(python, scriptName, filePath, roots, role = 'contaminated-manag
     maxBuffer: MAX_OUTPUT_BYTES,
   });
   if (result.status !== 0) {
-    const stderr = String(result.stderr || '').trim();
-    const stdout = String(result.stdout || '').trim();
-    const error = result.error?.message || '';
-    throw new Error(`${scriptName} failed for ${filePath}: ${stderr || stdout || error || `exit ${result.status}`}`);
+    return hookFailureMessage(scriptName, filePath, result);
   }
+  return null;
+}
+
+function hookFailureMessage(scriptName, filePath, result) {
+  const stderr = String(result.stderr || '').trim();
+  const stdout = String(result.stdout || '').trim();
+  const error = result.error?.message || '';
+  return `${scriptName} failed for ${filePath}: ${stderr || stdout || error || `exit ${result.status}`}`;
 }
 
 function validateArtifacts(python, manifestPath, roots, filePaths = null) {
   const paths = filePaths || trackedArtifactPaths(manifestPath, roots);
+  const failures = [];
   for (const filePath of paths) {
     if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) continue;
-    runHook(python, 'validate-json-schema.py', filePath, roots);
-    runHook(python, 'check-artifact-leakage.py', filePath, roots);
+    const schemaError = runHookFailure(python, 'validate-json-schema.py', filePath, roots);
+    if (schemaError) {
+      failures.push(schemaError);
+      if (failures.length >= MAX_ARTIFACT_VALIDATION_FAILURES) break;
+      continue;
+    }
+    const leakageError = runHookFailure(python, 'check-artifact-leakage.py', filePath, roots);
+    if (leakageError) {
+      failures.push(leakageError);
+      if (failures.length >= MAX_ARTIFACT_VALIDATION_FAILURES) break;
+      continue;
+    }
     if (path.basename(filePath) === HANDOFF_PACKAGE_NAME) {
-      runHook(python, 'validate-handoff-package.py', filePath, roots);
+      const handoffError = runHookFailure(python, 'validate-handoff-package.py', filePath, roots);
+      if (handoffError) {
+        failures.push(handoffError);
+        if (failures.length >= MAX_ARTIFACT_VALIDATION_FAILURES) break;
+      }
     }
   }
+  if (failures.length > 0) {
+    throw new Error([
+      'clean-room artifact validation failed:',
+      ...failures.map((failure) => `- ${failure}`),
+      'Recovery: update stale artifacts to current schemas or move stale/legacy JSON out of contaminated and clean artifact roots, for example into quarantine/, then retry --dry-run.',
+    ].join('\n'));
+  }
 }
 
 module.exports = {

package/lib/run-roots.cjs

@@ -18,6 +18,40 @@ function defaultSchemaDir() {
   return path.join(packageRoot(), 'skills', 'clean-room', 'assets');
 }
 
+function validateSchemaDir(schemaDir, explicit = false) {
+  let stat;
+  try {
+    stat = fs.statSync(schemaDir);
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      throw new Error(schemaDirError('schema directory not found', schemaDir, explicit));
+    }
+    throw err;
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(schemaDirError('schema path is not a directory', schemaDir, explicit));
+  }
+  const taskManifestSchema = path.join(schemaDir, 'task-manifest.schema.json');
+  try {
+    const schemaStat = fs.statSync(taskManifestSchema);
+    if (!schemaStat.isFile()) {
+      throw new Error(schemaDirError('schema directory is missing task-manifest.schema.json', schemaDir, explicit));
+    }
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      throw new Error(schemaDirError('schema directory is missing task-manifest.schema.json', schemaDir, explicit));
+    }
+    throw err;
+  }
+}
+
+function schemaDirError(reason, schemaDir, explicit) {
+  if (explicit) {
+    return `${reason}: ${schemaDir}. Omit --schema-dir to use bundled schemas at ${defaultSchemaDir()}.`;
+  }
+  return `${reason}: ${schemaDir}. The bundled schema directory should contain task-manifest.schema.json.`;
+}
+
 function hookPath(scriptName) {
   return path.join(packageRoot(), 'hooks', scriptName);
 }
@@ -115,13 +149,18 @@ function validateRootSeparation(roots) {
 }
 
 function validateTaskManifestLocation(taskManifestPath, roots) {
+  const expected = path.join(roots.contaminatedRoot, 'task-manifest.json');
   if (!pathIsUnder(taskManifestPath, roots.contaminatedRoot)) {
-    throw new Error('task manifest must be under contaminated artifact root');
+    throw new Error(
+      `task manifest must be under contaminated artifact root; resolved path: ${taskManifestPath}; expected: ${expected}`
+    );
   }
   const realTaskManifestPath = realpathIfExists(taskManifestPath);
   const realContaminatedRoot = realpathIfExists(roots.contaminatedRoot) || roots.contaminatedRoot;
   if (!realTaskManifestPath || !pathIsUnder(realTaskManifestPath, realContaminatedRoot)) {
-    throw new Error('task manifest must resolve under contaminated artifact root');
+    throw new Error(
+      `task manifest must resolve under contaminated artifact root; resolved path: ${taskManifestPath}; expected: ${expected}`
+    );
   }
 }
 
@@ -144,41 +183,46 @@ function envFromAllowlist(extraNames = []) {
 
 function verifyPreflightGoal(manifest, manifestDir, roots) {
   const preflightGoalPath = resolveManifestRoot(manifest.preflight_goal_ref, manifestDir);
+  const expected = path.join(roots.contaminatedRoot, 'preflight-goal.json');
   if (!preflightGoalPath) {
-    throw new Error('clean-room run requires task-manifest preflight_goal_ref');
+    throw new Error(`clean-room run requires task-manifest preflight_goal_ref; expected: ${expected}`);
   }
   if (!pathIsUnder(preflightGoalPath, roots.contaminatedRoot)) {
-    throw new Error('preflight goal must resolve under contaminated artifact root');
+    throw new Error(
+      `preflight goal must resolve under contaminated artifact root; resolved path: ${preflightGoalPath}; expected under: ${roots.contaminatedRoot}`
+    );
   }
   let preflightGoalRealPath;
   try {
     preflightGoalRealPath = fs.realpathSync(preflightGoalPath);
   } catch (err) {
     if (err?.code === 'ENOENT') {
-      throw new Error('preflight goal not found');
+      throw new Error(`preflight goal not found: ${preflightGoalPath}; expected: ${expected}`);
     }
     throw err;
   }
   const contaminatedRootRealPath = realpathIfExists(roots.contaminatedRoot) || roots.contaminatedRoot;
   if (!pathIsUnder(preflightGoalRealPath, contaminatedRootRealPath)) {
-    throw new Error('preflight goal must resolve under contaminated artifact root');
+    throw new Error(
+      `preflight goal must resolve under contaminated artifact root; resolved path: ${preflightGoalPath}; expected under: ${roots.contaminatedRoot}`
+    );
   }
   let stat;
   try {
     stat = fs.statSync(preflightGoalRealPath);
   } catch (err) {
     if (err?.code === 'ENOENT') {
-      throw new Error('preflight goal not found');
+      throw new Error(`preflight goal not found: ${preflightGoalPath}; expected: ${expected}`);
     }
     throw err;
   }
   if (!stat.isFile()) {
-    throw new Error('preflight goal is not a file');
+    throw new Error(`preflight goal is not a file: ${preflightGoalPath}`);
   }
   const actual = fileHash(preflightGoalRealPath).toLowerCase();
-  const expected = manifest.preflight_goal_sha256.toLowerCase();
-  if (actual !== expected) {
-    throw new Error('preflight goal sha256 mismatch');
+  const expectedHash = manifest.preflight_goal_sha256.toLowerCase();
+  if (actual !== expectedHash) {
+    throw new Error(`preflight goal sha256 mismatch: ${preflightGoalPath}`);
   }
 }
 
@@ -226,5 +270,6 @@ module.exports = {
   resolvePath,
   resolveRoots,
   validateTaskManifestLocation,
+  validateSchemaDir,
   verifyPreflightGoal,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room-skill",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "bin": {
     "clean-room-skill": "bin/install.js"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/skills/clean-room/SKILL.md

@@ -54,7 +54,7 @@ Optional AST/indexing helpers are detected before the controller loop through `s
 
 Controller mode defaults to `attended` when `task-manifest.json` has no `controller_policy`. The outer loop evolves specs and selects one approved spec slice. Code-development runs start with exactly one `unit_kind: "foundation"` unit named by `loop_context.foundation_unit_ref`; non-foundation behavior slices wait until that unit is covered. The inner clean-room loop completes the approved slice through sanitized handoff, implementation, QC, optional final polish review, and contaminated-side coverage verification, then returns `clean-room-result.json` to the outer loop. In `attended` mode, agent zero pauses for human review at scope gate, handoff, QC deltas, polish deltas, blocked units, and final coverage. In `unattended` mode, agent zero may run a bounded inner loop: reload durable artifacts for each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, start each role from fresh context with the required environment block, validate before advancing, and stop on any configured safety or ambiguity condition.
 
-In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available) when possible. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
+In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` when possible. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude`. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`; the runner uses bundled schemas by default. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
 
 Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3/4 role sessions. Agent 3 terminal verification may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`, the command cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent3-verification-runner.py`. Agent 4 polish verification and commit may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent4-polish-runner.py`. Use `--hooks=strict` for dedicated Codex, Claude, or OpenCode clean-room homes so hooks fail closed if required environment is missing or shell tools are invoked outside the allowed runner boundaries. Safe hook installs are compatibility-only between runs; during init/onboarding, prepare the role environment block and pass it into every clean-room role session so safe hooks enforce during active work.
 

package/skills/resume-cr/SKILL.md

@@ -11,7 +11,7 @@ Resume an existing clean-room run from durable artifacts. Never use prior chat h
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` when the manifest records `loop_context` or unattended mode. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available) and let the durable runner assign role agents. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
+If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` and let the durable runner assign role agents. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
 
 ## Load Order
 

package/skills/unattended/SKILL.md

@@ -15,7 +15,7 @@ Use the canonical `clean-room` skill workflow and references in this plugin. Rea
 
 Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
-When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available). The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
+When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude`. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
 
 Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, and a finite `controller_policy.max_iterations`.