clean-room-skill 0.2.2 → 0.3.0

package/lib/run-hooks.cjs

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

package/lib/run-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/lib/run-roots.cjs

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

package/package.json

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

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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

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

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