clean-room-skill 0.2.1 → 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

@@ -31,7 +31,19 @@ For the full boundary model, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). F
 
 Requires Node.js `>=22`.
 
-Preferred interactive install:
+You can either install the CLI globally on your system, or run the commands on-demand using `npx`.
+
+### Global Installation (npm)
+
+To install the `clean-room-skill` executable globally:
+
+```bash
+npm install -g clean-room-skill
+```
+
+### Direct On-Demand Execution (npx)
+
+Preferred interactive install/onboarding flow:
 
 ```bash
 npx clean-room-skill@latest
@@ -130,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.1",
+  "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` 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/init/SKILL.md

@@ -19,7 +19,7 @@ Keep `preflight-goal.json` in the controller/contaminated artifact domain. Clean
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-The CLI command `clean-room-skill init` may have pre-created neutral external folders and a clean-safe `.clean-room/README.md` stub in the target repository. The bootstrap task root must contain `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. Treat that bootstrap output as convenience scaffolding only. It does not replace this skill's initialization workflow, and it must not be treated as an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
+The CLI command `clean-room-skill init` (or `npx clean-room-skill@latest init` if the binary is not available) may have pre-created neutral external folders and a clean-safe `.clean-room/README.md` stub in the target repository. The bootstrap task root must contain `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. Treat that bootstrap output as convenience scaffolding only. It does not replace this skill's initialization workflow, and it must not be treated as an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
 
 When using an existing CLI bootstrap, check `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `implementation/`, `quarantine/`, and the target repo `.clean-room/README.md` before recording active init preferences. Stop if metadata is missing, invalid, mismatched with the task root, or any generated path is missing or the wrong type. Do not infer active workflow state from those bootstrap files.
 

package/skills/preflight/SKILL.md

@@ -11,7 +11,7 @@ Create or validate `preflight-goal.json` before active clean-room artifacts star
 
 Use the canonical `clean-room` workflow and read `skills/clean-room/references/PREFLIGHT.md` when collecting missing goal details. Preserve the clean-room boundary: `preflight-goal.json` is a controller/contaminated-side artifact and must not be placed in clean-role readable roots.
 
-If the user provides output from CLI `clean-room-skill init`, check the generated bootstrap scaffold before creating or copying `preflight-goal.json`: `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `implementation/`, `quarantine/`, and the target repo `.clean-room/README.md` must exist and agree. Treat that scaffold as convenience output only; it is not an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
+If the user provides output from CLI `clean-room-skill init` (or `npx clean-room-skill@latest init` if the binary is not available), check the generated bootstrap scaffold before creating or copying `preflight-goal.json`: `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `implementation/`, `quarantine/`, and the target repo `.clean-room/README.md` must exist and agree. Treat that scaffold as convenience output only; it is not an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
 
 ## Required Contract
 
@@ -46,7 +46,7 @@ Do not infer target language, license, dependency policy, exactness policy, outp
 
 ## CLI Helper
 
-Use the CLI only for template creation or validation/copying:
+Use the CLI (`clean-room-skill` if installed, or `npx clean-room-skill@latest` as fallback) only for template creation or validation/copying:
 
 ```bash
 clean-room-skill preflight --template --output ~/Documents/CleanRoom/task-xxxxxxxx/contaminated/preflight-goal.json

package/skills/refocus/SKILL.md

@@ -53,7 +53,7 @@ Emit missed-gate findings only:
 - Stale implementation report compared with latest implementation plan.
 - Controller policy not preserved.
 - Missing, invalid, or drifted preflight goal.
-- Noncanonical manifests, reports, ledgers, or manual result summaries used as completion evidence. Mark these `not verified` unless `clean-room-skill run --dry-run` succeeds against the canonical `task-manifest.json`.
+- Noncanonical manifests, reports, ledgers, or manual result summaries used as completion evidence. Mark these `not verified` unless `clean-room-skill run --dry-run` (or `npx clean-room-skill@latest run --dry-run` if the binary is not available) succeeds against the canonical `task-manifest.json`.
 - Missing public-surface inventory parity: required public commands, APIs, config keys, protocol entries, or user-visible behaviors listed in approved specs are not mapped through behavior spec tests, implementation-plan `public_contract_refs`, terminal implementation reports, and coverage-ledger `public_surface_coverage`.
 
 Do not suggest speculative improvements. Do not change source scope, target profile, public API, or implementation plan.

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` 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`. 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`.