clean-room-skill 0.2.3 → 0.3.1

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.3",
+      "version": "0.3.1",
       "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.3",
+  "version": "0.3.1",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/README.md

@@ -109,6 +109,8 @@ npx clean-room-skill@latest init
 
 The default task root is `~/Documents/CleanRoom/<task-id>/` with `contaminated/`, `clean/`, `implementation/`, and `quarantine/` children. Keep active contaminated artifacts, clean artifacts, and clean implementation roots separate.
 
+When multiple tasks target the same destination, group them under a clean-room project with `init --project <name>` (or `--new-project` for a generated name). The project layout is `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with per-task `contaminated/`, `clean/`, and `quarantine/` children plus one shared `~/Documents/CleanRoom/<project>/implementation/` root for every task in the project. Project names must stay neutral, like task IDs: a random word pair such as `amber-meadow` or a generated `proj-xxxxxxxx`, never derived from source folder names. Run at most one active task per project at a time because tasks share the implementation root; `clean-room-skill run` enforces this with an advisory `.clean-room-implementation.lock` in each implementation root.
+
 In Claude Code, invoke skills with the plugin namespace:
 
 ```text

package/docs/ARCHITECTURE.md

@@ -33,6 +33,8 @@ Optional Docker or Podman support is limited to Agent 3 verification containers.
 
 Artifact roots must not disclose private source names. New runs default to `~/Documents/CleanRoom/<task-id>/`; when no explicitly approved neutral task ID is provided, the controller generates `task-` plus 8 lowercase hex characters instead of using the source folder name.
 
+Multiple tasks targeting the same destination may be grouped under an optional clean-room project: `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with one shared `<project>/implementation/` root. Project names follow the same neutrality rule as task IDs: a random neutral word pair (such as `amber-meadow`) or a generated `proj-` plus 8 lowercase hex characters, matching `[a-z0-9][a-z0-9-]{0,63}` and never derived from source folder names. Because the implementation root is shared, run at most one active task per project at a time; `clean-room-skill run` enforces this with an advisory `.clean-room-implementation.lock` in each implementation root.
+
 ![Artifact Roots](assets/2.png)
 
 The initialization wizard and `require-clean-room-env.py` audit clean, implementation, and contaminated artifact root names. They fail closed when a path contains a source root basename or meaningful non-generic tokens from that basename, while filtering generic terms such as `src`, `app`, `test`, `repo`, and `workspace`.
@@ -60,7 +62,9 @@ To assist in logical unit decomposition, the workflow supports an optional sourc
 
 Runtime installs and uninstalls serialize per target root with `.clean-room-install.lock`. The installer plans desired file changes from manifest hashes, then rechecks each managed file immediately before write or removal. Managed files that changed after planning are backed up before mutation.
 
-The manifest is written with `phase: "installing"` after file copy and before hook config mutation. It is updated to `phase: "complete"` only after hook config succeeds. If hook config mutation fails, the installer records `hook_registration.status: "failed"` in the manifest when possible. A manifest left in `installing` is recoverable by re-running the same installer command. Bootstrap writes use atomic no-clobber creation unless `--force` is set.
+The manifest is written with `phase: "installing"` after file copy and before hook config mutation. It is updated to `phase: "complete"` only after hook config succeeds. If hook config mutation fails, the installer records `hook_registration.status: "failed"` in the manifest when possible. A manifest left in `installing` is recoverable by re-running the same installer command. Bootstrap writes use atomic no-clobber creation unless `--force` is set. When `--force` adopts an existing project root that lacks or has invalid project metadata, the installer emits a warning so operators know they are reusing existing `tasks/` and `implementation/` content.
+
+The implementation lock (`.clean-room-implementation.lock`) uses rename-based stale recovery: when a stale lock directory is detected, it is renamed to `<name>.stale.<ts>.<pid>` rather than deleted so the original can be inspected post-mortem. Implementation-root scans exclude both the active lock name and the stale prefix pattern to prevent orphaned stale lock directories from appearing in progress snapshots or misplaced-artifact checks.
 
 ---
 

package/docs/REFERENCE.md

@@ -164,6 +164,7 @@ Usage:
 npx clean-room-skill@latest init
 npx clean-room-skill@latest init --target-dir . --target-profile speckit-feature-folder
 npx clean-room-skill@latest init --artifact-base ~/Documents/CleanRoom --task-id task-1234abcd
+npx clean-room-skill@latest init --project amber-meadow --task-id task-1234abcd
 ```
 
 Options:
@@ -173,11 +174,13 @@ Options:
 | `--target-dir <path>` | Repository to initialize; default is current directory. |
 | `--artifact-base <path>` | External CleanRoom base; default is `~/Documents/CleanRoom`. |
 | `--task-id <id>` | Neutral task id; default is generated `task-xxxxxxxx`. |
+| `--project <name>` | Group the task under a clean-room project; joins the project when it already exists. Names must be neutral (`[a-z0-9][a-z0-9-]{0,63}`, never derived from source or workspace folder names). |
+| `--new-project` | Create a project with a generated `proj-xxxxxxxx` name. Cannot be combined with `--project`. |
 | `--target-profile <name>` | `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`. |
 | `--dry-run` | Print actions without writing files. |
 | `--force` | Overwrite existing bootstrap metadata and repo stub. |
 
-By default, `init` creates:
+By default, `init` creates a single-task layout under `<artifact-base>/<task-id>/`:
 
 - `contaminated/`
 - `clean/`
@@ -186,6 +189,22 @@ By default, `init` creates:
 - `clean-room-bootstrap.json`
 - `.clean-room/README.md` in the target repository
 
+With `--project` or `--new-project`, `init` creates a project layout instead. Tasks live under `<artifact-base>/<project>/tasks/<task-id>/` with per-task `contaminated/`, `clean/`, and `quarantine/`, while every task in the project shares one `<artifact-base>/<project>/implementation/` root:
+
+```text
+<artifact-base>/<project>/
+├── clean-room-project.json
+├── implementation/            (shared by all tasks)
+└── tasks/
+    └── <task-id>/
+        ├── contaminated/
+        ├── clean/
+        ├── quarantine/
+        └── clean-room-bootstrap.json
+```
+
+Re-running `init --project <name>` with a new task id joins the existing project without `--force`: the project metadata and shared `implementation/` are reused, and only the new task folders must not already exist. Because tasks share the implementation root, run at most one active task per project at a time; `clean-room-skill run` enforces this with an advisory `.clean-room-implementation.lock` in each implementation root.
+
 Do not commit source roots, contaminated artifact paths, private identifiers, source-derived names, `preflight-goal.json`, `init-config.json`, `task-manifest.json`, `controller-status.json`, `role-session-brief.json`, or `clean-run-context.json` into the clean implementation repository.
 
 ## Preflight CLI
@@ -198,6 +217,7 @@ Usage:
 npx clean-room-skill@latest preflight --template --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
 npx clean-room-skill@latest preflight --input ./preflight-goal.json --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
 npx clean-room-skill@latest preflight --template --bootstrap ~/Documents/CleanRoom/task-1234abcd
+npx clean-room-skill@latest preflight --template --bootstrap ~/Documents/CleanRoom/amber-meadow/tasks/task-1234abcd
 ```
 
 Options:
@@ -358,11 +378,13 @@ The runner exports `CLEAN_ROOM_SESSION_BRIEF_PATH`, `CLEAN_ROOM_ROLE_SESSION_ID`
 | `python3 is required to install clean-room hooks` | Python missing or not on `PATH` | Install Python 3 or use `--hooks=copy-only`. |
 | `safe hooks are installed; clean-room init/onboarding must set role environment variables` | Safe mode default | Start the clean-room init/onboarding flow, or use strict hooks in a dedicated profile. |
 | `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. |
+| `clean-room run lock is held` | Another run is active for the same task's contaminated root, or a crashed run left a recent lock | Wait for the other run to finish. Locks from dead processes age out and are moved aside automatically; if no run is active, remove `.clean-room-run.lock` from the contaminated root and retry. |
+| `clean-room implementation lock is held` | Another task in the same clean-room project is running against the shared implementation root, or a crashed run left a recent lock | Wait for the other run to finish. Locks from dead processes age out and are moved aside automatically; if no run is active, remove `.clean-room-implementation.lock` from the implementation root and retry. |
 | 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. |
+| `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` (or `~/Documents/CleanRoom/<project>/tasks/<task-id>/contaminated/task-manifest.json` in the project layout), 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`. |

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,25 @@ 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));
+  // Clause 2 (project contains workspace token) is the primary leakage vector and
+  // needs a lower minimum length so that short-but-meaningful workspace names (len 2+)
+  // are still caught. Clause 3 keeps the >=4 guard: a short project token included in
+  // a long workspace token is a weak signal and would produce too many false rejections.
+  const overlapping = projectToken === targetToken
+    || (targetToken.length >= 2 && 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 +171,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 +199,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 +217,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 +239,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 +269,79 @@ 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) {
+    // Warn when adopting a directory that lacks valid project metadata so the
+    // operator knows they are reusing existing tasks/ and implementation/ content.
+    if (!fs.existsSync(options.projectMetadataPath)) {
+      process.stderr.write(`warning: --force is adopting project root without ${PROJECT_METADATA_FILE}: ${options.projectRoot}\n`);
+    } else {
+      try {
+        const adoptErrors = [];
+        validateProjectMetadataObject(readJsonFile(options.projectMetadataPath, null), options.projectRoot, adoptErrors);
+        if (adoptErrors.length > 0) {
+          process.stderr.write(`warning: --force is adopting project root with invalid ${PROJECT_METADATA_FILE}:\n  ${adoptErrors.join('\n  ')}\n`);
+        }
+      } catch {
+        process.stderr.write(`warning: --force is adopting project root with unreadable ${PROJECT_METADATA_FILE}: ${options.projectRoot}\n`);
+      }
+    }
+    return { mode: 'existing' };
+  }
+  // During dry-run the metadata is not written, so skip validation that would
+  // fail on an imperfect existing project root and just preview the layout.
+  if (options.dryRun) {
+    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 +356,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,22 +382,51 @@ 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 validateProjectIdValue(projectId, projectRoot, errors, label) {
+  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`);
   }
 }
 
+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) {
+    validateProjectIdValue(projectId, projectRoot, errors, label);
+  }
+  assertMetadataPath(metadata, 'project_root', projectRoot, errors, label);
+  assertMetadataPath(metadata, 'implementation_root', path.join(projectRoot, BOOTSTRAP_DIRS.implementation), errors, label);
+}
+
 function validateBootstrapScaffold(taskRoot) {
   if (typeof taskRoot !== 'string' || taskRoot.trim() === '') {
     throw new Error('bootstrap path requires a task root');
@@ -282,7 +451,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 +468,54 @@ 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.
+  // Use metadata.layout === 'project' as the single authoritative signal:
+  // stray project_id/project_root fields on a flat task must not silently flip
+  // layout detection and redirect the shared implementation root.
+  const projectLayout = metadataIsObject && metadata.layout === 'project';
+  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) {
+        validateProjectIdValue(projectId, projectRoot, errors, 'bootstrap metadata');
+      }
+      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 +551,9 @@ function validateBootstrapScaffold(taskRoot) {
     metadata,
     roots,
     repoStubPath,
+    projectRoot,
+    projectId,
+    projectMetadataPath,
   };
 }
 
@@ -375,29 +592,88 @@ 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}`);
+  if (options.projectId && projectState.mode === 'existing') {
+    console.log('  note: shared repo stub kept from first task; --target-profile for this task is in per-task metadata');
+  }
   console.log('');
   console.log('Next steps:');
   console.log('  Codex:');
@@ -429,7 +705,9 @@ function runInit(argv, context = {}) {
 
 module.exports = {
   BOOTSTRAP_METADATA_FILE,
+  PROJECT_METADATA_FILE,
   defaultArtifactBase,
+  generateProjectId,
   generateTaskId,
   parseInitArgs,
   resolveBootstrapScaffold,

package/lib/fs-utils.cjs

@@ -162,6 +162,7 @@ function listFiles(root, options = {}) {
     return [];
   }
   const ignoreNames = new Set(options.ignoreNames || []);
+  const ignoreNamePrefixes = options.ignoreNamePrefixes || [];
   const maxDepth = Number.isInteger(options.maxDepth) ? options.maxDepth : 64;
   const maxFiles = Number.isInteger(options.maxFiles) ? options.maxFiles : 10000;
   const files = [];
@@ -180,6 +181,9 @@ function listFiles(root, options = {}) {
       if (ignoreNames.has(entry.name)) {
         continue;
       }
+      if (ignoreNamePrefixes.length > 0 && ignoreNamePrefixes.some((p) => entry.name.startsWith(p))) {
+        continue;
+      }
       const fullPath = path.join(dir, entry.name);
       const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
@@ -217,6 +221,7 @@ module.exports = {
   atomicWriteFileNoOverwrite,
   fileHash,
   listFiles,
+  lstatIfExists,
   normalizeRelativePath,
   readJsonFile,
   removeEmptyParents,

package/lib/run-constants.cjs

@@ -6,6 +6,13 @@ 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';
+// Stale lock recovery renames the lock dir to <name>.stale.<ts>.<pid> rather than
+// removing it, so the original can be inspected post-mortem. Filter these orphans
+// out of implementation-root scans with IMPLEMENTATION_LOCK_STALE_PREFIX.
+const IMPLEMENTATION_LOCK_STALE_PREFIX = `${IMPLEMENTATION_LOCK_NAME}.stale.`;
+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 +104,7 @@ const VOLATILE_PROGRESS_KEYS = new Set([
 
 const IMPLEMENTATION_IGNORE_NAMES = Object.freeze([
   '.git',
+  IMPLEMENTATION_LOCK_NAME,
   'node_modules',
   'target',
 ]);
@@ -151,6 +159,10 @@ module.exports = {
   HANDOFF_PACKAGE_NAME,
   HOOK_ONLY_ENV_ALLOWLIST,
   IMPLEMENTATION_IGNORE_NAMES,
+  IMPLEMENTATION_LOCK_NAME,
+  IMPLEMENTATION_LOCK_POLL_MS,
+  IMPLEMENTATION_LOCK_STALE_PREFIX,
+  IMPLEMENTATION_LOCK_WAIT_MS,
   LEDGER_NAME,
   MAX_LEDGER_ITERATIONS,
   MAX_OUTPUT_BYTES,

package/lib/run-controller.cjs

@@ -54,6 +54,7 @@ const {
   loadLedger,
   noProgressResult,
   stageFailureResult,
+  withImplementationRootLocks,
   withRunLock,
   writeLedger,
   writeResult,
@@ -211,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);
@@ -374,7 +375,7 @@ async function runCleanRoom(options, context = {}) {
     validateFoundationCoverageGate(resultManifest, finalCoverageLedger);
     console.log(`clean-room run: ${terminalResult.result}`);
     return terminalResult;
-  });
+  }));
 }
 
 module.exports = {

package/lib/run-progress.cjs

@@ -12,6 +12,7 @@ const {
 const {
   CLEAN_ROOM_ARTIFACT_PREFIXES,
   IMPLEMENTATION_IGNORE_NAMES,
+  IMPLEMENTATION_LOCK_STALE_PREFIX,
   LEDGER_NAME,
   STATUS_NAME,
   VOLATILE_PROGRESS_KEYS,
@@ -36,7 +37,7 @@ function misplacedImplementationArtifacts(roots) {
   const misplaced = [];
   for (const root of roots.implementationRoots) {
     if (!root || !fs.existsSync(root)) continue;
-    for (const relPath of listFiles(root, { ignoreNames: IMPLEMENTATION_IGNORE_NAMES })) {
+    for (const relPath of listFiles(root, { ignoreNames: IMPLEMENTATION_IGNORE_NAMES, ignoreNamePrefixes: [IMPLEMENTATION_LOCK_STALE_PREFIX] })) {
       if (isCleanRoomArtifactName(path.basename(relPath))) {
         misplaced.push(path.join(root, relPath));
       }
@@ -115,7 +116,7 @@ function semanticProgressSnapshot(manifestPath, roots) {
   }
   roots.implementationRoots.forEach((root, rootIndex) => {
     if (!root || !fs.existsSync(root)) return;
-    for (const relPath of listFiles(root, { ignoreNames: IMPLEMENTATION_IGNORE_NAMES })) {
+    for (const relPath of listFiles(root, { ignoreNames: IMPLEMENTATION_IGNORE_NAMES, ignoreNamePrefixes: [IMPLEMENTATION_LOCK_STALE_PREFIX] })) {
       const filePath = path.join(root, relPath);
       entries[`implementation:${rootIndex}:${relPath}`] = fileHash(filePath);
     }

package/lib/run-results.cjs

@@ -10,6 +10,9 @@ const {
 } = require('./fs-utils.cjs');
 const {
   CLEAN_RUN_CONTEXT_NAME,
+  IMPLEMENTATION_LOCK_NAME,
+  IMPLEMENTATION_LOCK_POLL_MS,
+  IMPLEMENTATION_LOCK_WAIT_MS,
   MAX_LEDGER_ITERATIONS,
   POLISH_REPORT_NAME,
   RUN_LOCK_NAME,
@@ -431,6 +434,25 @@ async function withRunLock(contaminatedRoot, dryRun, fn) {
   }, fn);
 }
 
+async function withImplementationRootLocks(implementationRoots, dryRun, fn) {
+  if (dryRun) return fn();
+  // Realpath dedupe: root-separation checks do not compare implementation
+  // roots against each other, so symlink-aliased duplicates would otherwise
+  // self-deadlock on their own live-pid lock. Sorting gives every run the
+  // same global acquisition order, preventing AB/BA deadlocks.
+  const roots = [...new Set(implementationRoots.map((root) => {
+    fs.mkdirSync(root, { recursive: true });
+    return fs.realpathSync(root);
+  }))].sort();
+  const run = roots.reduceRight((next, root) => () => withDirectoryLock({
+    lockPath: path.join(root, IMPLEMENTATION_LOCK_NAME),
+    waitMs: IMPLEMENTATION_LOCK_WAIT_MS,
+    pollMs: IMPLEMENTATION_LOCK_POLL_MS,
+    label: 'clean-room implementation lock',
+  }, next), fn);
+  return run();
+}
+
 module.exports = {
   buildResult,
   completeResultOrSpecDelta,
@@ -439,6 +461,7 @@ module.exports = {
   loadLedger,
   noProgressResult,
   stageFailureResult,
+  withImplementationRootLocks,
   withRunLock,
   writeLedger,
   writeResult,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room-skill",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "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.3",
+  "version": "0.3.1",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/skills/attended/SKILL.md

@@ -13,7 +13,7 @@ In Pi, this entry point is invoked as `/skill:attended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-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.
+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-*` (legacy) and `~/Documents/CleanRoom/*/tasks/task-*` (project layout) 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.
 
 Load or create `preflight-goal.json` first. Attended mode may continue with unresolved questions only when they are recorded as `open_questions`; blocking questions become pause gates before affected work starts.
 
@@ -21,6 +21,7 @@ Gather only required setup facts:
 
 - Authorization statement, requester, allowed actions, prohibited actions, and evidence handling.
 - Artifact base root, defaulting to `~/Documents/CleanRoom/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
+- Optional project grouping for multi-task destinations, following the canonical `clean-room` project layout rules: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root, a neutral project name (random word pair or `proj-` plus 8 lowercase hex, matching `[a-z0-9][a-z0-9-]{0,63}`, never source-derived), and at most one active task per project.
 - Source roots, contaminated artifact root, clean artifact root, clean implementation root, quarantine root, and optional public or destination reference roots.
 - Target stack, destination constraints, dependency/license policy, exactness policy, feature policy, code hygiene policy, and output policy from `preflight-goal.json`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.

package/skills/clean-room/SKILL.md

@@ -80,15 +80,16 @@ Discovery order:
 
 1. Resolve explicit user-provided paths first. Accept a task root, `task-manifest.json`, `preflight-goal.json`, or `clean-room-bootstrap.json`.
 2. Inspect configured clean-room roots from the current request or environment, including `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, and `CLEAN_ROOM_IMPLEMENTATION_ROOTS` when present.
-3. Scan `~/Documents/CleanRoom/task-*` as a bounded fallback. Inspect only immediate task directories and their expected artifact names.
+3. Scan `~/Documents/CleanRoom/task-*` (legacy single-task layout) and `~/Documents/CleanRoom/*/clean-room-project.json` plus `~/Documents/CleanRoom/*/tasks/task-*` (project layout) as a bounded fallback. Inspect only immediate project directories, their `tasks/` children, and expected artifact names.
 
-If more than one candidate run is found without an explicit user path, list the candidate task roots and stop for explicit selection. Do not choose the newest candidate automatically.
+If more than one candidate run is found without an explicit user path, list the candidate task roots grouped by project and stop for explicit selection. Do not choose the newest candidate automatically.
 
 Classify the selected candidate before starting the wizard:
 
 - Valid `task-manifest.json`: route to `resume-cr` and continue from the earliest incomplete gate.
 - Valid canonical `preflight-goal.json` without `task-manifest.json`: continue at source/destination discovery and manifest creation. Do not ask the preflight wizard again.
 - `clean-room-bootstrap.json` only: run preflight using the bootstrap roots.
+- `clean-room-project.json` with no task directories under `tasks/`: treat as an empty project and offer to create its first task inside that project.
 - Invalid `preflight-goal.json`: stop, report canonical schema or required-field errors, and do not create a replacement preflight.
 - No artifacts found: start the normal preflight wizard.
 
@@ -98,6 +99,7 @@ Gather only the setup facts needed to decide whether the workflow may start, or
 
 - Authorization statement, requester, allowed actions, prohibited actions, and evidence handling.
 - Artifact base root. Default to `~/Documents/CleanRoom/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
+- Optional project grouping. Ask whether to group this run under a clean-room project when multiple tasks will target the same destination; default to the legacy single-task layout. Project layout is `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root for every task in the project. When the user does not supply an approved neutral project name, generate a random neutral word pair such as `amber-meadow`; it must match `[a-z0-9][a-z0-9-]{0,63}`, must never be derived from source or destination folder basenames or meaningful source-name tokens (project names appear in paths clean roles can see), and falls back to `proj-` plus 8 lowercase hex characters when no neutral word pair is available. Only one task per project may run at a time because tasks share the implementation root; the durable runner enforces this with an advisory `.clean-room-implementation.lock` in each implementation root.
 - Source roots or fallback visual evidence roots, contaminated artifact root, clean artifact root, clean implementation root, quarantine root, and optional public or destination reference roots.
 - Target stack and destination constraints from `preflight-goal.json`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
@@ -107,7 +109,7 @@ Gather only the setup facts needed to decide whether the workflow may start, or
 - Run state. New runs use `generation: 1`, current `started_at`, and `restart_reason: user-requested`.
 - Role hook environment block. Derive `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and optional hook-only denylist variables from the approved roots before launching any role session. Do not ask the user to export `CLEAN_ROOM_HOOK_ENFORCE` for normal safe-hook runs.
 
-Before indexing or artifact generation, confirm that source roots, contaminated artifact roots, clean artifact roots, clean implementation roots, approved public reference roots, and schema directory are separate paths, and that clean/contaminated/implementation root path names are not source-derived. Stop if authorization is unclear, if clean and contaminated roots overlap, if implementation roots overlap any other trust-domain root, or if artifact/root paths contain source root basenames or meaningful non-generic source-name tokens. Agent 2, Agent 3, and Agent 4 must not receive source mounts or the full task manifest.
+Before indexing or artifact generation, confirm that source roots, contaminated artifact roots, clean artifact roots, clean implementation roots, approved public reference roots, and schema directory are separate paths, and that clean/contaminated/implementation root path names are not source-derived. In project layout the implementation root is the shared project-level folder; per-task contaminated, clean, and quarantine roots stay under the task root, and the project name itself must pass the same source-derived-name checks. Stop if authorization is unclear, if clean and contaminated roots overlap, if implementation roots overlap any other trust-domain root, or if artifact/root paths contain source root basenames or meaningful non-generic source-name tokens. Agent 2, Agent 3, and Agent 4 must not receive source mounts or the full task manifest.
 
 For `attended` mode, record a `controller_policy` that pauses for human review at scope gate, clean handoff, terminal implementation deltas, blocked units, and final coverage. Include stop conditions for `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, and `coverage-complete`; attended mode does not add an iteration-limit stop unless the user explicitly sets one.
 

package/skills/clean-room/assets/init-config.schema.json

@@ -27,6 +27,14 @@
       "type": "string",
       "minLength": 1
     },
+    "project_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "project_root": {
+      "type": "string",
+      "minLength": 1
+    },
     "root_preferences": {
       "type": "object",
       "additionalProperties": false,

package/skills/clean-room/assets/task-manifest.schema.json

@@ -33,6 +33,14 @@
       "type": "string",
       "minLength": 1
     },
+    "project_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "project_root": {
+      "type": "string",
+      "minLength": 1
+    },
     "target_identifier": {
       "type": "string",
       "minLength": 1
@@ -1215,6 +1223,14 @@
           "type": "string",
           "minLength": 1
         },
+        "project_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+        },
+        "project_root": {
+          "type": "string",
+          "minLength": 1
+        },
         "target_profile": {
           "enum": [
             "openspec-delta",

package/skills/clean-room/references/LEAKAGE-RULES.md

@@ -47,6 +47,8 @@ Treat implementation identifiers as contaminated by default. Package names, name
 
 Public compatibility surface means the name is externally documented, required by an existing integration, visible in a public protocol or file format, or explicitly required by the destination scope. If a name is retained, place it in `public_surface` or `public_contracts` with `name`, `kind`, `visibility`, and a concrete compatibility reason. Valid `visibility` values are `public`, `destination`, `protocol`, and `user-required`. Do not mention source-private names in summaries, claims, tests, open questions, skeleton areas, QC findings, or delta tickets.
 
+Task IDs and project names are clean-visible path components: they appear in roots that clean roles read and in paths recorded by clean artifacts. Both must stay neutral. Use generated `task-` plus 8 lowercase hex IDs, and for projects a random neutral word pair or `proj-` plus 8 lowercase hex, matching `[a-z0-9][a-z0-9-]{0,63}`. Never derive a task ID or project name from source folder basenames or meaningful source-name tokens.
+
 The contaminated side should maintain a private identifier denylist for guardrail scanning when practical. The denylist is line-oriented, ignores blank lines and `#` comments, and is bounded to 1,000,000 bytes per file, 20,000 total terms, and 512 characters per term. Keep that list out of clean/source-denied readable roots and do not paste its contents into clean artifacts or model-visible reports.
 
 Agent 1.5 may use the denylist only through hook scanning. Do not include denylist terms in the neutral sanitizer brief, sanitizer prompts, sanitizer reports, clean artifacts, or model-visible feedback.

package/skills/clean-room/references/PREFLIGHT.md

@@ -24,6 +24,7 @@ Record every default as an assumption. Good defaults:
 
 - Artifact base: `~/Documents/CleanRoom/<task-id>/`.
 - Implementation root: `~/Documents/CleanRoom/<task-id>/implementation/`.
+- Project layout (when grouping multiple tasks): task root `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with shared implementation root `~/Documents/CleanRoom/<project>/implementation/`.
 - Existing destination policy: `inspect-and-preserve`.
 - Dependency policy: allow new dependencies, prefer standard library, require approval for native/system dependencies.
 - Dependency licenses: allow MIT, Apache-2.0, BSD-2-Clause, and BSD-3-Clause; block GPL-3.0 and AGPL-3.0 unless the user explicitly approves otherwise.

package/skills/clean-room/references/PROCESS.md

@@ -20,7 +20,9 @@ Use separate locations for each trust domain:
 
 Clean, contaminated, and implementation paths must remain neutral. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters and use it under `~/Documents/CleanRoom/`.
 
-Do not derive task IDs, clean roots, contaminated artifact roots, or implementation roots from source folder names. The initialization wizard and environment preflight reject artifact paths that contain a source root basename or meaningful non-generic tokens from that basename.
+Multiple tasks targeting the same destination may be grouped under an optional clean-room project: `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with one shared `<project>/implementation/` root. Project names follow the same neutrality rules as task IDs: a random neutral word pair (such as `amber-meadow`) or `proj-` plus 8 lowercase hex characters, matching `[a-z0-9][a-z0-9-]{0,63}`. Because the shared implementation root serves every task in the project, run at most one active task per project at a time; root-separation checks for one task cannot see a sibling task's concurrent clean implementation session. `clean-room-skill run` enforces this with an advisory `.clean-room-implementation.lock` in each implementation root, but manually launched role sessions outside the runner must still respect the rule.
+
+Do not derive task IDs, project names, clean roots, contaminated artifact roots, or implementation roots from source folder names. The initialization wizard and environment preflight reject artifact paths that contain a source root basename or meaningful non-generic tokens from that basename.
 
 Prefer separate agent profiles or homes when the host supports them. Do not rely on one chat context with role labels as the only separation control.
 
@@ -212,6 +214,7 @@ Clean polish reviewer:
 2. Initialization gate:
    - Record reusable preferences in `init-config.json` when requested.
    - Default the artifact base root to `~/Documents/CleanRoom/<task-id>/` unless the user selects another separated location. Generate a neutral `task-` plus 8 lowercase hex characters when the user does not provide an explicitly approved neutral task ID.
+   - When grouping tasks under a project, place the task root at `~/Documents/CleanRoom/<project>/tasks/<task-id>/`, share the project-level `implementation/` root, and record `project_id` and `project_root` in `init-config.json` and the manifest `initialization_snapshot`.
    - Reject clean, contaminated, or implementation roots that mirror source root basenames or meaningful non-generic source-name tokens.
    - Record model preferences as a default model plus optional domain or role overrides.
    - Split user rules into clean-safe and contaminated-only rules.

package/skills/clean-room/references/SPEC-SCHEMA.md

@@ -100,11 +100,14 @@ Unattended mode requires `unattended_allowed_after_preflight: true`, finite `max
 
 Default artifact roots live under `~/Documents/CleanRoom/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not use the source folder name as the task ID.
 
+When tasks are grouped under a project, roots live under `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with a shared `~/Documents/CleanRoom/<project>/implementation/` root. Project names follow the same neutrality rules: a random neutral word pair or `proj-` plus 8 lowercase hex characters, never derived from source folder names.
+
 Clean artifact, contaminated artifact, and implementation roots must not contain source root basenames or meaningful non-generic tokens from those basenames. The environment preflight enforces this for `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, and `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
 
 Capture:
 
 - artifact base root, defaulting to `~/Documents/CleanRoom/<task-id>/` with a neutral task ID
+- optional `project_id` and `project_root` when grouping tasks under a clean-room project
 - source roots or fallback visual evidence roots, contaminated artifact root, clean artifact root, clean implementation roots, quarantine root, and approved public references
 - target profile
 - default model plus optional clean, contaminated, or per-role overrides

package/skills/init/SKILL.md

@@ -19,9 +19,9 @@ 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` (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`.
+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 has two shapes. The legacy single-task root contains `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. The project layout (`--project` or `--new-project`) places the task root at `<base>/<project>/tasks/<task-id>/` with per-task `contaminated/`, `clean/`, and `quarantine/`, plus a shared project-level `implementation/` and a `clean-room-project.json` metadata file at the project root. 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.
+When using an existing CLI bootstrap, check `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `quarantine/`, the implementation root (task-level in the legacy layout, project-level in the project layout), and the target repo `.clean-room/README.md` before recording active init preferences. In the project layout also check `clean-room-project.json` and that the task root sits under the project's `tasks/` directory. 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.
 
 ## Gather
 
@@ -30,6 +30,7 @@ Collect only setup decisions that affect correctness, safety, resumability, or o
 - Requester authorization, allowed actions, prohibited actions, and evidence handling.
 - Source roots, contaminated artifact root, clean artifact root, clean implementation roots, quarantine root, and approved public or destination reference roots.
 - Artifact base root. Default to `~/Documents/CleanRoom/<task-id>/`, never to the source workspace or a temporary directory unless the user explicitly chooses it. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
+- Optional project grouping. When multiple tasks will target the same destination, record `project_id` and `project_root` for the `<base>/<project>/tasks/<task-id>/` layout with its shared project-level implementation root. Project names follow the same neutrality rules as task IDs: a random neutral word pair or `proj-` plus 8 lowercase hex, matching `[a-z0-9][a-z0-9-]{0,63}`, never derived from source folder names. Record both fields in `init-config.json` and the manifest `initialization_snapshot`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
 - Goal contract choices from `preflight-goal.json`, including target stack, dependency/license policy, exactness policy, feature policy, code hygiene, output policy, and controller mode.
 - Default model plus optional overrides for contaminated roles, clean roles, or individual roles. Keep model ids as runtime-specific strings.

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` (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`.
+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/`, the implementation root, `quarantine/`, and the target repo `.clean-room/README.md` must exist and agree. In the project layout the task root sits at `<base>/<project>/tasks/<task-id>/`, the implementation root is the shared project-level `implementation/`, and `clean-room-project.json` must exist at the project root. 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
 
@@ -52,6 +52,7 @@ Use the CLI (`clean-room-skill` if installed, or `npx clean-room-skill@latest` a
 clean-room-skill preflight --template --output ~/Documents/CleanRoom/task-xxxxxxxx/contaminated/preflight-goal.json
 clean-room-skill preflight --input ./preflight-goal.json --output ~/Documents/CleanRoom/task-xxxxxxxx/contaminated/preflight-goal.json
 clean-room-skill preflight --template --bootstrap ~/Documents/CleanRoom/task-xxxxxxxx
+clean-room-skill preflight --template --bootstrap ~/Documents/CleanRoom/<project>/tasks/task-xxxxxxxx
 ```
 
 `--template` writes an attended draft with blocking open questions. It does not support unattended mode. Use `--input` for completed contracts. `--bootstrap` accepts either the generated task root or `clean-room-bootstrap.json`, writes to the generated contaminated artifact root after scaffold validation, and requires completed input contracts to match the bootstrap artifact and implementation roots.

package/skills/resume-cr/SKILL.md

@@ -15,7 +15,7 @@ If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude
 
 ## Load Order
 
-Load these artifacts from the paths recorded in `task-manifest.json` and the configured root environment. Treat missing optional artifacts as blockers only when the current gate requires them.
+Load these artifacts from the paths recorded in `task-manifest.json` and the configured root environment. Treat missing optional artifacts as blockers only when the current gate requires them. A task may live at `<base>/<project>/tasks/<task-id>/` with a shared project-level implementation root; trust the absolute paths recorded in `task-manifest.json` `artifact_paths` and never re-derive the layout from folder positions.
 
 - `task-manifest.json`
 - `preflight-goal.json`, when referenced by `task-manifest.json`, only on the contaminated/controller side
@@ -46,6 +46,7 @@ Before choosing work:
 - Confirm authorization still covers the recorded source scope and allowed actions.
 - Report `run_state` when present; do not infer generation from chat history when it is missing.
 - Trust `initialization_snapshot` before any reusable `init-config.json`. If they differ, report drift and stop before changing roots, model policy, schema profile, or rule classification.
+- When `initialization_snapshot` records `project_id` or `project_root`, confirm the on-disk `clean-room-project.json` at the project root still agrees with them and with the shared implementation root. Report drift and stop on mismatch.
 - Preserve the existing `controller_policy`; missing policy means `attended`.
 - Stop if new-run artifacts lack `preflight_goal_ref`, `preflight_goal_sha256`, or the required `handoff_sequence`. Treat this as legacy or incomplete preflight state and ask for a reviewed preflight goal before resuming.
 - Validate referenced `preflight-goal.json` before using goal, stack, dependency, license, exactness, output, or hygiene decisions.

package/skills/start-over/SKILL.md

@@ -24,6 +24,7 @@ Archive or quarantine previous artifacts before creating new ones:
 - Do not mix contaminated and clean archives.
 - Do not delete artifacts.
 - Do not overwrite an existing archive path; create a unique archive directory.
+- In the project layout, archive scope is the task folder only. Never archive, move, or quarantine the project root, `clean-room-project.json`, or the shared project-level `implementation/` root; sibling tasks depend on them, and implementation content is destination state, not per-task artifact state.
 - Preserve existing `preflight-goal.json`, `task-manifest.json`, ledgers, handoff packages, behavior specs, skeleton manifests, implementation plans, implementation reports, QC reports, incident records, and open delta tickets.
 
 If safe archive targets cannot be proven from `task-manifest.json`, root environment, or explicit user input, stop before moving anything.
@@ -37,6 +38,7 @@ Start from the preflight gate, not from prior QC:
 - Reconfirm source roots or visual roots, contaminated artifact roots, clean roots, implementation roots, and clean allowed-read roots are separated, and that root path names are not source-derived.
 - Preserve source or visual roots and authorization only when they are still valid for the requested restart.
 - Create a fresh neutral `task_id` by default. Use `task-` plus 8 lowercase hex characters unless the user provides an explicitly approved neutral ID. Do not derive the new ID or output directory names from source folder names.
+- In the project layout, the new task joins the same project by default. Starting a new project instead requires an explicit user choice and a fresh neutral project name (random word pair or `proj-` plus 8 lowercase hex, never source-derived).
 - Record `run_state.generation`, `run_state.started_at`, optional `run_state.previous_generation_ref`, and `run_state.restart_reason`.
 - Recreate `clean-run-context.json` from the new effective preflight and initialization choices; do not carry forward an old clean context by default.
 - Rebuild `source-index.json`, or `visual-index.json` for visual fallback runs, unless the user explicitly says the source or visual scope is unchanged and a recorded old index hash can still be validated.

package/skills/unattended/SKILL.md

@@ -13,7 +13,7 @@ In Pi, this entry point is invoked as `/skill:unattended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` before defining unattended loop behavior. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-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.
+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-*` (legacy) and `~/Documents/CleanRoom/*/tasks/task-*` (project layout) 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`. 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.
 
@@ -25,6 +25,7 @@ Gather only required setup facts:
 
 - Authorization statement, requester, allowed actions, prohibited actions, and evidence handling.
 - Artifact base root, defaulting to `~/Documents/CleanRoom/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
+- Optional project grouping for multi-task destinations, following the canonical `clean-room` project layout rules: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root, a neutral project name (random word pair or `proj-` plus 8 lowercase hex, matching `[a-z0-9][a-z0-9-]{0,63}`, never source-derived), and at most one active task per project.
 - Source roots, contaminated artifact root, clean artifact root, clean implementation root, quarantine root, and optional public or destination reference roots.
 - Target stack, destination constraints, dependency/license policy, exactness policy, feature policy, code hygiene policy, and output policy from `preflight-goal.json`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.