clean-room-skill 0.2.2 → 0.3.0

package/lib/bootstrap.cjs

@@ -9,6 +9,7 @@ const {
   assertManagedPath,
   atomicWriteFile,
   atomicWriteFileNoOverwrite,
+  lstatIfExists,
   readJsonFile,
 } = require('./fs-utils.cjs');
 const { packageVersion } = require('./install-artifacts.cjs');
@@ -22,7 +23,10 @@ const TARGET_PROFILES = new Set([
 ]);
 
 const TASK_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const BOOTSTRAP_METADATA_FILE = 'clean-room-bootstrap.json';
+const PROJECT_METADATA_FILE = 'clean-room-project.json';
+const PROJECT_TASKS_DIR = 'tasks';
 const BOOTSTRAP_REPO_STUB = '.clean-room/README.md';
 const BOOTSTRAP_DIRS = Object.freeze({
   contaminated: 'contaminated',
@@ -39,6 +43,10 @@ function generateTaskId() {
   return `task-${crypto.randomBytes(4).toString('hex')}`;
 }
 
+function generateProjectId() {
+  return `proj-${crypto.randomBytes(4).toString('hex')}`;
+}
+
 function printInitHelp() {
   console.log(`Usage: clean-room-skill init [options]
 
@@ -48,6 +56,13 @@ Options:
   --target-dir <path>      Repository to initialize (default: current directory)
   --artifact-base <path>   External CleanRoom base (default: ~/Documents/CleanRoom)
   --task-id <id>           Neutral task id (default: generated task-xxxxxxxx)
+  --project <name>         Group this task under a clean-room project; joins the
+                           project when it already exists. Project names must be
+                           neutral ([a-z0-9][a-z0-9-]{0,63}) and never derived
+                           from source or workspace folder names. Project layout:
+                           <base>/<project>/tasks/<task-id> with one shared
+                           <base>/<project>/implementation root for all tasks
+  --new-project            Create a project with a generated proj-xxxxxxxx name
   --target-profile <name>  openspec-delta, gsd-planning-package,
                            speckit-feature-folder, or kiro-spec-folder
                            (default: speckit-feature-folder)
@@ -62,6 +77,8 @@ function parseInitArgs(argv) {
     targetDir: process.cwd(),
     artifactBase: defaultArtifactBase(),
     taskId: null,
+    projectId: null,
+    newProject: false,
     targetProfile: 'speckit-feature-folder',
     dryRun: false,
     force: false,
@@ -91,6 +108,13 @@ function parseInitArgs(argv) {
       options.taskId = requiredValue(argv, i, '--task-id');
     } else if (arg.startsWith('--task-id=')) {
       options.taskId = arg.slice('--task-id='.length);
+    } else if (arg === '--new-project') {
+      options.newProject = true;
+    } else if (arg === '--project') {
+      i += 1;
+      options.projectId = requiredValue(argv, i, '--project');
+    } else if (arg.startsWith('--project=')) {
+      options.projectId = arg.slice('--project='.length);
     } else if (arg === '--target-profile') {
       i += 1;
       options.targetProfile = requiredValue(argv, i, '--target-profile');
@@ -103,6 +127,10 @@ function parseInitArgs(argv) {
     }
   }
 
+  if (options.projectId !== null && options.newProject) {
+    throw new Error('--project and --new-project cannot be combined');
+  }
+
   return options;
 }
 
@@ -113,6 +141,23 @@ function requiredValue(argv, index, flag) {
   return argv[index];
 }
 
+function normalizeNameToken(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function assertNeutralProjectId(projectId, targetDir) {
+  const projectToken = normalizeNameToken(projectId);
+  const targetToken = normalizeNameToken(path.basename(targetDir));
+  // Substring overlap is only meaningful for tokens long enough to identify a
+  // workspace; short tokens would reject unrelated neutral names.
+  const overlapping = projectToken === targetToken
+    || (targetToken.length >= 4 && projectToken.includes(targetToken))
+    || (projectToken.length >= 4 && targetToken.includes(projectToken));
+  if (overlapping) {
+    throw new Error('--project must be a neutral name; do not derive project names from workspace or source folder names');
+  }
+}
+
 function resolveInitOptions(options, env = process.env, homeDir = os.homedir()) {
   const taskId = options.taskId || generateTaskId();
   if (!TASK_ID_PATTERN.test(taskId)) {
@@ -124,12 +169,27 @@ function resolveInitOptions(options, env = process.env, homeDir = os.homedir())
 
   const targetDir = path.resolve(expandTilde(options.targetDir, homeDir));
   const artifactBase = path.resolve(expandTilde(options.artifactBase, homeDir));
-  const outputRoot = path.join(artifactBase, taskId);
+
+  const projectMode = options.projectId !== null || options.newProject === true;
+  const projectId = projectMode ? (options.projectId || generateProjectId()) : null;
+  if (projectMode) {
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+      throw new Error('--project must match [a-z0-9][a-z0-9-]{0,63}');
+    }
+    assertNeutralProjectId(projectId, targetDir);
+  }
+
+  const projectRoot = projectMode ? path.join(artifactBase, projectId) : null;
+  const outputRoot = projectMode
+    ? path.join(projectRoot, PROJECT_TASKS_DIR, taskId)
+    : path.join(artifactBase, taskId);
   const roots = {
-    contaminated: path.join(outputRoot, 'contaminated'),
-    clean: path.join(outputRoot, 'clean'),
-    implementation: path.join(outputRoot, 'implementation'),
-    quarantine: path.join(outputRoot, 'quarantine'),
+    contaminated: path.join(outputRoot, BOOTSTRAP_DIRS.contaminated),
+    clean: path.join(outputRoot, BOOTSTRAP_DIRS.clean),
+    implementation: projectMode
+      ? path.join(projectRoot, BOOTSTRAP_DIRS.implementation)
+      : path.join(outputRoot, BOOTSTRAP_DIRS.implementation),
+    quarantine: path.join(outputRoot, BOOTSTRAP_DIRS.quarantine),
   };
 
   return {
@@ -137,11 +197,14 @@ function resolveInitOptions(options, env = process.env, homeDir = os.homedir())
     env,
     homeDir,
     taskId,
+    projectId,
+    projectRoot,
     targetDir,
     artifactBase,
     outputRoot,
     roots,
     metadataPath: assertManagedPath(outputRoot, BOOTSTRAP_METADATA_FILE),
+    projectMetadataPath: projectMode ? assertManagedPath(projectRoot, PROJECT_METADATA_FILE) : null,
     repoStubPath: assertManagedPath(targetDir, BOOTSTRAP_REPO_STUB),
   };
 }
@@ -152,6 +215,13 @@ function buildBootstrapMetadata(options) {
     package: 'clean-room-skill',
     version: packageVersion(),
     created_at: new Date().toISOString(),
+    ...(options.projectId
+      ? {
+        layout: 'project',
+        project_id: options.projectId,
+        project_root: options.projectRoot,
+      }
+      : {}),
     task_id: options.taskId,
     target_profile: options.targetProfile,
     target_dir: options.targetDir,
@@ -167,6 +237,21 @@ function buildBootstrapMetadata(options) {
   };
 }
 
+function buildProjectMetadata(options) {
+  return {
+    schema: 1,
+    package: 'clean-room-skill',
+    version: packageVersion(),
+    created_at: new Date().toISOString(),
+    project_id: options.projectId,
+    artifact_base_root: options.artifactBase,
+    project_root: options.projectRoot,
+    implementation_root: options.roots.implementation,
+    tasks_dir: path.join(options.projectRoot, PROJECT_TASKS_DIR),
+    note: 'Project metadata only. Tasks are discovered by scanning tasks/; the shared implementation root is the clean destination for every task in this project.',
+  };
+}
+
 function renderRepoStub(targetProfile) {
   return `# Clean Room Bootstrap
 
@@ -182,19 +267,59 @@ Start the runtime skill from your agent and provide the external output folder p
 `;
 }
 
+function resolveExistingProject(options) {
+  if (!options.projectRoot) {
+    return { mode: 'none' };
+  }
+  const projectRootStat = lstatIfExists(options.projectRoot);
+  if (!projectRootStat) {
+    return { mode: 'new' };
+  }
+  if (projectRootStat.isSymbolicLink()) {
+    throw new Error(`project root must not be a symbolic link: ${options.projectRoot}`);
+  }
+  if (!projectRootStat.isDirectory()) {
+    throw new Error(`project root is not a directory: ${options.projectRoot}`);
+  }
+  if (options.force) {
+    return { mode: 'existing' };
+  }
+  if (!fs.existsSync(options.projectMetadataPath)) {
+    throw new Error(`project root exists but ${PROJECT_METADATA_FILE} is missing; use --force to adopt it: ${options.projectRoot}`);
+  }
+  const metadata = readJsonFile(options.projectMetadataPath, null);
+  const errors = [];
+  validateProjectMetadataObject(metadata, options.projectRoot, errors);
+  if (errors.length > 0) {
+    throw new Error(`project root exists but ${PROJECT_METADATA_FILE} is invalid; use --force to adopt it:\n  ${errors.join('\n  ')}`);
+  }
+  return { mode: 'existing' };
+}
+
 function assertWritableTargets(options) {
+  const projectState = resolveExistingProject(options);
+  const joiningExistingProject = projectState.mode === 'existing';
+
   const fileConflicts = [];
-  for (const filePath of [options.metadataPath, options.repoStubPath]) {
-    if (fs.existsSync(filePath) && !options.force) {
-      fileConflicts.push(filePath);
-    }
+  if (fs.existsSync(options.metadataPath) && !options.force) {
+    fileConflicts.push(options.metadataPath);
+  }
+  // A second task joining a project commonly shares the same target repo; its
+  // existing stub is reused, not a conflict.
+  if (fs.existsSync(options.repoStubPath) && !options.force && !joiningExistingProject) {
+    fileConflicts.push(options.repoStubPath);
   }
   if (fileConflicts.length > 0) {
     throw new Error(`bootstrap file already exists; use --force to overwrite: ${fileConflicts.join(', ')}`);
   }
 
   const pathConflicts = [];
-  for (const dirPath of Object.values(options.roots)) {
+  for (const [label, dirPath] of Object.entries(options.roots)) {
+    // The project-level implementation root is shared across tasks, so it may
+    // already exist once the project metadata has been validated.
+    if (label === 'implementation' && joiningExistingProject) {
+      continue;
+    }
     if (fs.existsSync(dirPath) && !options.force) {
       pathConflicts.push(dirPath);
     }
@@ -209,15 +334,8 @@ function assertWritableTargets(options) {
       throw new Error(`bootstrap generated path is not a directory: ${dirPath}`);
     }
   }
-}
 
-function lstatIfExists(filePath) {
-  try {
-    return fs.lstatSync(filePath);
-  } catch (err) {
-    if (err?.code === 'ENOENT') return null;
-    throw err;
-  }
+  return projectState;
 }
 
 function requireDirectory(dirPath, label, errors) {
@@ -242,20 +360,45 @@ function requireFile(filePath, label, errors) {
   }
 }
 
-function expectMetadataString(metadata, field, errors) {
+function expectMetadataString(metadata, field, errors, label = 'bootstrap metadata') {
   if (typeof metadata?.[field] !== 'string' || metadata[field].length === 0) {
-    errors.push(`bootstrap metadata ${field} must be a non-empty string`);
+    errors.push(`${label} ${field} must be a non-empty string`);
     return null;
   }
   return metadata[field];
 }
 
-function assertMetadataPath(metadata, field, expectedPath, errors) {
-  const value = expectMetadataString(metadata, field, errors);
+function assertMetadataPath(metadata, field, expectedPath, errors, label = 'bootstrap metadata') {
+  const value = expectMetadataString(metadata, field, errors, label);
   if (!value) return;
   if (path.resolve(expandTilde(value)) !== expectedPath) {
-    errors.push(`bootstrap metadata ${field} must match ${expectedPath}`);
+    errors.push(`${label} ${field} must match ${expectedPath}`);
+  }
+}
+
+function validateProjectMetadataObject(metadata, projectRoot, errors) {
+  const label = 'project metadata';
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  if (metadata.schema !== 1) {
+    errors.push(`${label} schema must be 1`);
+  }
+  if (metadata.package !== 'clean-room-skill') {
+    errors.push(`${label} package must be clean-room-skill`);
+  }
+  const projectId = expectMetadataString(metadata, 'project_id', errors, label);
+  if (projectId) {
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+      errors.push(`${label} project_id must match [a-z0-9][a-z0-9-]{0,63}`);
+    }
+    if (projectId !== path.basename(projectRoot)) {
+      errors.push(`${label} project_id must match the project root basename`);
+    }
   }
+  assertMetadataPath(metadata, 'project_root', projectRoot, errors, label);
+  assertMetadataPath(metadata, 'implementation_root', path.join(projectRoot, BOOTSTRAP_DIRS.implementation), errors, label);
 }
 
 function validateBootstrapScaffold(taskRoot) {
@@ -282,7 +425,8 @@ function validateBootstrapScaffold(taskRoot) {
 
   const metadata = readJsonFile(metadataPath, null);
   const errors = [];
-  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+  const metadataIsObject = Boolean(metadata) && typeof metadata === 'object' && !Array.isArray(metadata);
+  if (!metadataIsObject) {
     errors.push('bootstrap metadata must be an object');
   } else {
     if (metadata.schema !== 1) {
@@ -298,10 +442,57 @@ function validateBootstrapScaffold(taskRoot) {
     assertMetadataPath(metadata, 'output_root', outputRoot, errors);
   }
 
+  // Project layouts nest the task root under <project>/tasks/ and share one
+  // project-level implementation root. Never trust the metadata paths
+  // directly: derive the project root from the task root location, then
+  // require the metadata to match the derived layout.
+  const projectLayout = metadataIsObject
+    && (metadata.layout !== undefined || metadata.project_id !== undefined || metadata.project_root !== undefined);
+  let projectRoot = null;
+  let projectId = null;
+  let projectMetadataPath = null;
+  if (projectLayout) {
+    if (metadata.layout !== 'project'
+      || typeof metadata.project_id !== 'string'
+      || typeof metadata.project_root !== 'string') {
+      errors.push('bootstrap metadata project layout requires layout "project", project_id, and project_root');
+    }
+    const tasksDir = path.dirname(outputRoot);
+    if (path.basename(tasksDir) !== PROJECT_TASKS_DIR) {
+      errors.push(`bootstrap project task root must live under a ${PROJECT_TASKS_DIR}/ directory: ${outputRoot}`);
+    } else {
+      projectRoot = path.dirname(tasksDir);
+      requireDirectory(projectRoot, 'project root', errors);
+      assertMetadataPath(metadata, 'project_root', projectRoot, errors);
+      projectId = expectMetadataString(metadata, 'project_id', errors);
+      if (projectId) {
+        if (!PROJECT_ID_PATTERN.test(projectId)) {
+          errors.push('bootstrap metadata project_id must match [a-z0-9][a-z0-9-]{0,63}');
+        }
+        if (projectId !== path.basename(projectRoot)) {
+          errors.push('bootstrap metadata project_id must match the project root basename');
+        }
+      }
+      try {
+        projectMetadataPath = assertManagedPath(projectRoot, PROJECT_METADATA_FILE);
+      } catch (err) {
+        errors.push(err.message);
+      }
+      if (projectMetadataPath) {
+        requireFile(projectMetadataPath, 'project metadata', errors);
+        if (fs.existsSync(projectMetadataPath)) {
+          validateProjectMetadataObject(readJsonFile(projectMetadataPath, null), projectRoot, errors);
+        }
+      }
+    }
+  }
+
   const roots = {
     contaminated: path.join(outputRoot, BOOTSTRAP_DIRS.contaminated),
     clean: path.join(outputRoot, BOOTSTRAP_DIRS.clean),
-    implementation: path.join(outputRoot, BOOTSTRAP_DIRS.implementation),
+    implementation: projectRoot
+      ? path.join(projectRoot, BOOTSTRAP_DIRS.implementation)
+      : path.join(outputRoot, BOOTSTRAP_DIRS.implementation),
     quarantine: path.join(outputRoot, BOOTSTRAP_DIRS.quarantine),
   };
   for (const [label, dirPath] of Object.entries(roots)) {
@@ -337,6 +528,9 @@ function validateBootstrapScaffold(taskRoot) {
     metadata,
     roots,
     repoStubPath,
+    projectRoot,
+    projectId,
+    projectMetadataPath,
   };
 }
 
@@ -375,28 +569,84 @@ function writeBootstrapFile(filePath, data, force) {
   }
 }
 
+function writeProjectMetadataFile(options) {
+  const metadata = buildProjectMetadata(options);
+  if (options.force) {
+    // A forced rewrite refreshes the metadata but keeps the project's
+    // original creation time when the prior file is readable. --force is
+    // also the documented way to adopt invalid metadata, so parse failures
+    // fall back to the fresh timestamp instead of aborting.
+    try {
+      const existing = readJsonFile(options.projectMetadataPath, null);
+      if (typeof existing?.created_at === 'string' && existing.created_at.length > 0) {
+        metadata.created_at = existing.created_at;
+      }
+    } catch {
+      // Keep the fresh created_at when existing metadata is unreadable.
+    }
+    atomicWriteFile(options.projectMetadataPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    return;
+  }
+  const data = `${JSON.stringify(metadata, null, 2)}\n`;
+  try {
+    atomicWriteFileNoOverwrite(options.projectMetadataPath, data, 'utf8');
+  } catch (err) {
+    if (err?.code !== 'EEXIST') {
+      throw err;
+    }
+    // Joining an existing project, or losing a creation race: exactly one
+    // writer wins the no-overwrite link; everyone else validates the winner's
+    // metadata and proceeds without rewriting it.
+    const errors = [];
+    validateProjectMetadataObject(readJsonFile(options.projectMetadataPath, null), options.projectRoot, errors);
+    if (errors.length > 0) {
+      throw new Error(`existing ${PROJECT_METADATA_FILE} is invalid; use --force to adopt it:\n  ${errors.join('\n  ')}`);
+    }
+  }
+}
+
 function applyBootstrap(options) {
-  assertWritableTargets(options);
+  const projectState = assertWritableTargets(options);
   if (!options.dryRun) {
+    if (options.projectRoot) {
+      fs.mkdirSync(path.join(options.projectRoot, PROJECT_TASKS_DIR), { recursive: true });
+    }
     for (const dir of Object.values(options.roots)) {
       fs.mkdirSync(dir, { recursive: true });
     }
+    if (options.projectRoot) {
+      writeProjectMetadataFile(options);
+    }
     const metadata = `${JSON.stringify(buildBootstrapMetadata(options), null, 2)}\n`;
     writeBootstrapFile(options.metadataPath, metadata, options.force);
-    writeBootstrapFile(options.repoStubPath, renderRepoStub(options.targetProfile), options.force);
+    if (options.force || !fs.existsSync(options.repoStubPath)) {
+      writeBootstrapFile(options.repoStubPath, renderRepoStub(options.targetProfile), options.force);
+    }
   }
-  printInitResult(options);
+  printInitResult(options, projectState);
 }
 
-function printInitResult(options) {
+function printInitResult(options, projectState = { mode: 'none' }) {
   const verb = options.dryRun ? 'Would create' : 'Created';
   console.log(`${verb} clean-room bootstrap`);
+  if (options.projectId) {
+    const projectLabel = projectState.mode === 'existing' ? 'existing' : 'new';
+    console.log(`  project: ${options.projectId} (${projectLabel})`);
+    console.log(`  project root: ${options.projectRoot}`);
+  }
   console.log(`  output folder: ${options.outputRoot}`);
   console.log(`  contaminated artifacts: ${options.roots.contaminated}`);
   console.log(`  clean artifacts: ${options.roots.clean}`);
-  console.log(`  implementation root: ${options.roots.implementation}`);
+  if (options.projectId) {
+    console.log(`  implementation root (shared): ${options.roots.implementation}`);
+  } else {
+    console.log(`  implementation root: ${options.roots.implementation}`);
+  }
   console.log(`  quarantine: ${options.roots.quarantine}`);
   console.log(`  metadata: ${options.metadataPath}`);
+  if (options.projectId) {
+    console.log(`  project metadata: ${options.projectMetadataPath}`);
+  }
   console.log(`  repo stub: ${options.repoStubPath}`);
   console.log('');
   console.log('Next steps:');
@@ -429,7 +679,9 @@ function runInit(argv, context = {}) {
 
 module.exports = {
   BOOTSTRAP_METADATA_FILE,
+  PROJECT_METADATA_FILE,
   defaultArtifactBase,
+  generateProjectId,
   generateTaskId,
   parseInitArgs,
   resolveBootstrapScaffold,

package/lib/fs-utils.cjs

@@ -217,6 +217,7 @@ module.exports = {
   atomicWriteFileNoOverwrite,
   fileHash,
   listFiles,
+  lstatIfExists,
   normalizeRelativePath,
   readJsonFile,
   removeEmptyParents,

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-constants.cjs

@@ -6,6 +6,9 @@ const MAX_OUTPUT_BYTES = 256 * 1024;
 const RUN_LOCK_NAME = '.clean-room-run.lock';
 const RUN_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_RUN_LOCK_WAIT_MS', 30_000);
 const RUN_LOCK_POLL_MS = 100;
+const IMPLEMENTATION_LOCK_NAME = '.clean-room-implementation.lock';
+const IMPLEMENTATION_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_IMPLEMENTATION_LOCK_WAIT_MS', 30_000);
+const IMPLEMENTATION_LOCK_POLL_MS = 100;
 const RUN_HOOK_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_RUN_HOOK_TIMEOUT_MS', 30_000);
 const LEDGER_NAME = 'controller-run-ledger.json';
 const RESULT_NAME = 'clean-room-result.json';
@@ -97,6 +100,7 @@ const VOLATILE_PROGRESS_KEYS = new Set([
 
 const IMPLEMENTATION_IGNORE_NAMES = Object.freeze([
   '.git',
+  IMPLEMENTATION_LOCK_NAME,
   'node_modules',
   'target',
 ]);
@@ -151,6 +155,9 @@ module.exports = {
   HANDOFF_PACKAGE_NAME,
   HOOK_ONLY_ENV_ALLOWLIST,
   IMPLEMENTATION_IGNORE_NAMES,
+  IMPLEMENTATION_LOCK_NAME,
+  IMPLEMENTATION_LOCK_POLL_MS,
+  IMPLEMENTATION_LOCK_WAIT_MS,
   LEDGER_NAME,
   MAX_LEDGER_ITERATIONS,
   MAX_OUTPUT_BYTES,

package/lib/run-controller.cjs

@@ -43,6 +43,7 @@ const {
   resolvePath,
   resolveRoots,
   validateTaskManifestLocation,
+  validateSchemaDir,
   verifyPreflightGoal,
 } = require('./run-roots.cjs');
 const {
@@ -53,6 +54,7 @@ const {
   loadLedger,
   noProgressResult,
   stageFailureResult,
+  withImplementationRootLocks,
   withRunLock,
   writeLedger,
   writeResult,
@@ -144,6 +146,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 +192,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);
@@ -177,7 +212,7 @@ async function runCleanRoom(options, context = {}) {
     ? { agentConfig: null, configDir: process.cwd() }
     : resolveAgentConfig(options, context, roots, manifest, agentConfigPath);
 
-  return withRunLock(roots.contaminatedRoot, options.dryRun, async () => {
+  return withImplementationRootLocks(roots.implementationRoots, options.dryRun, () => withRunLock(roots.contaminatedRoot, options.dryRun, async () => {
     const coverageLedgerPath = path.join(roots.contaminatedRoot, 'coverage-ledger.json');
     const coverageLedger = validateRunState(options, taskManifestPath, roots, manifest, coverageLedgerPath);
     const selectedUnit = selectUnit(manifest, coverageLedger);
@@ -340,7 +375,7 @@ async function runCleanRoom(options, context = {}) {
     validateFoundationCoverageGate(resultManifest, finalCoverageLedger);
     console.log(`clean-room run: ${terminalResult.result}`);
     return terminalResult;
-  });
+  }));
 }
 
 module.exports = {