clean-room-skill 0.3.0 → 0.4.0

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -107,9 +107,9 @@ Optionally create neutral external run folders and a clean-safe repository stub:
 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.
+By default this creates a neutral clean-room project. The default task root is `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with per-task `contaminated/`, `clean/`, and `quarantine/` children, plus one shared `~/Documents/CleanRoom/<project>/implementation/` root. Use `init --single-task` only when you need the legacy flat `~/Documents/CleanRoom/<task-id>/` layout.
 
-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.
+To add another task to the same destination project, pass `init --project <name>` with the existing neutral project name. Plain `init` creates a new generated `proj-xxxxxxxx` 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:
 

package/docs/ARCHITECTURE.md

@@ -62,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

@@ -165,6 +165,7 @@ 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
+npx clean-room-skill@latest init --single-task --task-id task-1234abcd
 ```
 
 Options:
@@ -174,22 +175,14 @@ 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`. |
+| `--project <name>` | Group the task under a named 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` | Explicitly create a project with a generated `proj-xxxxxxxx` name. This is the default unless `--single-task` is passed. Cannot be combined with `--project`. |
+| `--single-task` | Use the legacy flat layout under `<artifact-base>/<task-id>`. Cannot be combined with `--project` or `--new-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 a single-task layout under `<artifact-base>/<task-id>/`:
-
-- `contaminated/`
-- `clean/`
-- `implementation/`
-- `quarantine/`
-- `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:
+By default, `init` creates a project layout. Plain `init` creates a new generated `proj-xxxxxxxx` project; pass `--project <name>` to add a task to an existing project. 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>/
@@ -203,6 +196,15 @@ With `--project` or `--new-project`, `init` creates a project layout instead. Ta
         └── clean-room-bootstrap.json
 ```
 
+With `--single-task`, `init` creates the legacy flat layout under `<artifact-base>/<task-id>/`:
+
+- `contaminated/`
+- `clean/`
+- `implementation/`
+- `quarantine/`
+- `clean-room-bootstrap.json`
+- `.clean-room/README.md` in the target repository
+
 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.

package/lib/bootstrap.cjs

@@ -56,13 +56,16 @@ 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 <name>         Group this task under a named 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
+  --new-project            Explicitly create a project with a generated
+                           proj-xxxxxxxx name (the default unless --single-task
+                           is passed)
+  --single-task            Use the legacy flat layout under <base>/<task-id>
   --target-profile <name>  openspec-delta, gsd-planning-package,
                            speckit-feature-folder, or kiro-spec-folder
                            (default: speckit-feature-folder)
@@ -79,6 +82,7 @@ function parseInitArgs(argv) {
     taskId: null,
     projectId: null,
     newProject: false,
+    singleTask: false,
     targetProfile: 'speckit-feature-folder',
     dryRun: false,
     force: false,
@@ -110,6 +114,8 @@ function parseInitArgs(argv) {
       options.taskId = arg.slice('--task-id='.length);
     } else if (arg === '--new-project') {
       options.newProject = true;
+    } else if (arg === '--single-task') {
+      options.singleTask = true;
     } else if (arg === '--project') {
       i += 1;
       options.projectId = requiredValue(argv, i, '--project');
@@ -130,6 +136,9 @@ function parseInitArgs(argv) {
   if (options.projectId !== null && options.newProject) {
     throw new Error('--project and --new-project cannot be combined');
   }
+  if (options.singleTask && (options.projectId !== null || options.newProject)) {
+    throw new Error('--single-task cannot be combined with --project or --new-project');
+  }
 
   return options;
 }
@@ -148,10 +157,12 @@ function normalizeNameToken(value) {
 function assertNeutralProjectId(projectId, targetDir) {
   const projectToken = normalizeNameToken(projectId);
   const targetToken = normalizeNameToken(path.basename(targetDir));
-  // Substring overlap is only meaningful for tokens long enough to identify a
-  // workspace; short tokens would reject unrelated neutral names.
+  // 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 >= 4 && projectToken.includes(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');
@@ -170,7 +181,7 @@ 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 projectMode = options.projectId !== null || options.newProject === true;
+  const projectMode = !options.singleTask;
   const projectId = projectMode ? (options.projectId || generateProjectId()) : null;
   if (projectMode) {
     if (!PROJECT_ID_PATTERN.test(projectId)) {
@@ -252,18 +263,21 @@ function buildProjectMetadata(options) {
   };
 }
 
-function renderRepoStub(targetProfile) {
+function renderRepoStub(options) {
+  const layoutDescription = options.projectId
+    ? 'The bootstrap task root contains per-task `contaminated/`, `clean/`, and `quarantine/` directories. The project root contains the shared `implementation/` clean destination. Do not commit source roots, contaminated artifact paths, private identifiers, source-derived names, or active `init-config.json`, `task-manifest.json`, or `clean-run-context.json` files here.'
+    : 'The bootstrap task root contains `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. Do not commit source roots, contaminated artifact paths, private identifiers, source-derived names, or active `init-config.json`, `task-manifest.json`, or `clean-run-context.json` files here.';
   return `# Clean Room Bootstrap
 
 This repository has a clean-room bootstrap stub.
 
-Active clean-room run artifacts are stored outside this repository. The bootstrap task root contains \`contaminated/\`, \`clean/\`, \`implementation/\`, and \`quarantine/\`. Do not commit source roots, contaminated artifact paths, private identifiers, source-derived names, or active \`init-config.json\`, \`task-manifest.json\`, or \`clean-run-context.json\` files here.
+Active clean-room run artifacts are stored outside this repository. ${layoutDescription}
 
 The final clean polish stage may create or update implementation-root \`AGENTS.md\`, \`.gitignore\`, and one local git commit through the bounded Agent 4 polish runner. That commit belongs to the clean implementation root, not to contaminated artifacts or source roots.
 
-Default target profile: \`${targetProfile}\`
+Default target profile: \`${options.targetProfile}\`
 
-Start the runtime skill from your agent and provide the external output folder printed by \`clean-room-skill init\`.
+Start the runtime skill from your agent and provide the external task root printed by \`clean-room-skill init\`.
 `;
 }
 
@@ -282,6 +296,26 @@ function resolveExistingProject(options) {
     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)) {
@@ -376,6 +410,15 @@ function assertMetadataPath(metadata, field, expectedPath, errors, label = 'boot
   }
 }
 
+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)) {
@@ -390,12 +433,7 @@ function validateProjectMetadataObject(metadata, projectRoot, errors) {
   }
   const projectId = expectMetadataString(metadata, 'project_id', errors, label);
   if (projectId) {
-    if (!PROJECT_ID_PATTERN.test(projectId)) {
-      errors.push(`${label} project_id must match [a-z0-9][a-z0-9-]{0,63}`);
-    }
-    if (projectId !== path.basename(projectRoot)) {
-      errors.push(`${label} project_id must match the project root basename`);
-    }
+    validateProjectIdValue(projectId, projectRoot, errors, label);
   }
   assertMetadataPath(metadata, 'project_root', projectRoot, errors, label);
   assertMetadataPath(metadata, 'implementation_root', path.join(projectRoot, BOOTSTRAP_DIRS.implementation), errors, label);
@@ -446,8 +484,10 @@ function validateBootstrapScaffold(taskRoot) {
   // project-level implementation root. Never trust the metadata paths
   // directly: derive the project root from the task root location, then
   // require the metadata to match the derived layout.
-  const projectLayout = metadataIsObject
-    && (metadata.layout !== undefined || metadata.project_id !== undefined || metadata.project_root !== undefined);
+  // 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;
@@ -466,12 +506,7 @@ function validateBootstrapScaffold(taskRoot) {
       assertMetadataPath(metadata, 'project_root', projectRoot, errors);
       projectId = expectMetadataString(metadata, 'project_id', errors);
       if (projectId) {
-        if (!PROJECT_ID_PATTERN.test(projectId)) {
-          errors.push('bootstrap metadata project_id must match [a-z0-9][a-z0-9-]{0,63}');
-        }
-        if (projectId !== path.basename(projectRoot)) {
-          errors.push('bootstrap metadata project_id must match the project root basename');
-        }
+        validateProjectIdValue(projectId, projectRoot, errors, 'bootstrap metadata');
       }
       try {
         projectMetadataPath = assertManagedPath(projectRoot, PROJECT_METADATA_FILE);
@@ -620,7 +655,7 @@ function applyBootstrap(options) {
     const metadata = `${JSON.stringify(buildBootstrapMetadata(options), null, 2)}\n`;
     writeBootstrapFile(options.metadataPath, metadata, options.force);
     if (options.force || !fs.existsSync(options.repoStubPath)) {
-      writeBootstrapFile(options.repoStubPath, renderRepoStub(options.targetProfile), options.force);
+      writeBootstrapFile(options.repoStubPath, renderRepoStub(options), options.force);
     }
   }
   printInitResult(options, projectState);
@@ -634,7 +669,7 @@ function printInitResult(options, projectState = { mode: 'none' }) {
     console.log(`  project: ${options.projectId} (${projectLabel})`);
     console.log(`  project root: ${options.projectRoot}`);
   }
-  console.log(`  output folder: ${options.outputRoot}`);
+  console.log(`  task root: ${options.outputRoot}`);
   console.log(`  contaminated artifacts: ${options.roots.contaminated}`);
   console.log(`  clean artifacts: ${options.roots.clean}`);
   if (options.projectId) {
@@ -648,6 +683,9 @@ function printInitResult(options, projectState = { mode: 'none' }) {
     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:');

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()) {

package/lib/install-cli.cjs

@@ -4,6 +4,7 @@ const { runInit } = require('./bootstrap.cjs');
 const { runDoctor } = require('./doctor.cjs');
 const { runPreflight } = require('./preflight.cjs');
 const { parseRunArgs, runCleanRoom } = require('./run.cjs');
+const { packageVersion } = require('./install-artifacts.cjs');
 const { resolveInteractiveOptions } = require('./install-tui.cjs');
 const {
   operationForOptions,
@@ -22,6 +23,10 @@ const {
 
 async function main() {
   const argv = process.argv.slice(2);
+  if (argv.length === 1 && argv[0] === '--version') {
+    console.log(packageVersion());
+    return;
+  }
   if (argv[0] === 'init') {
     runInit(argv.slice(1));
     return;

package/lib/install-options.cjs

@@ -117,6 +117,7 @@ Options:
   --dry-run            Print actions without writing files
   --yes                Non-interactive mode; unknown conflicts still abort
   --uninstall          Remove manifest-managed files and clean-room hook entries
+  --version            Print the installed clean-room-skill version
 
 Run without runtime and scope flags for interactive install or uninstall.
 Interactive runtime selection accepts names, numbers, ranges, all, or installed.

package/lib/run-constants.cjs

@@ -7,6 +7,10 @@ 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);
@@ -157,6 +161,7 @@ module.exports = {
   IMPLEMENTATION_IGNORE_NAMES,
   IMPLEMENTATION_LOCK_NAME,
   IMPLEMENTATION_LOCK_POLL_MS,
+  IMPLEMENTATION_LOCK_STALE_PREFIX,
   IMPLEMENTATION_LOCK_WAIT_MS,
   LEDGER_NAME,
   MAX_LEDGER_ITERATIONS,

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/package.json

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

package/skills/attended/SKILL.md

@@ -20,8 +20,8 @@ Load or create `preflight-goal.json` first. Attended mode may continue with unre
 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.
+- Artifact base root, defaulting the task root to `~/Documents/CleanRoom/<project>/tasks/<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.
+- Project grouping, following the canonical `clean-room` project layout rules: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root, a neutral project name (`proj-` plus 8 lowercase hex unless the user supplies an approved neutral name, matching `[a-z0-9][a-z0-9-]{0,63}`, never source-derived), and at most one active task per project. Use legacy flat `<base>/<task-id>/` roots only when the user explicitly chooses single-task compatibility.
 - 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

@@ -98,8 +98,8 @@ Load or create `preflight-goal.json` only after this discovery step. Do not star
 Gather only the setup facts needed to decide whether the workflow may start, or invoke `init` when the user wants a dedicated setup pass:
 
 - 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.
+- Artifact base root. Default the task root to `~/Documents/CleanRoom/<project>/tasks/<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.
+- Project grouping. Default to the clean-room project layout: `<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 `proj-` plus 8 lowercase hex characters; 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, and appears in paths clean roles can see. Use the legacy flat `<base>/<task-id>/` layout only when the user explicitly chooses single-task compatibility. 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`.

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

@@ -22,9 +22,9 @@ Ask only enough to fill `preflight-goal.json`:
 
 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/`.
+- Artifact base: `~/Documents/CleanRoom/<project>/tasks/<task-id>/`.
+- Implementation root: `~/Documents/CleanRoom/<project>/implementation/`.
+- Single-task compatibility layout: task root `~/Documents/CleanRoom/<task-id>/` with implementation root `~/Documents/CleanRoom/<task-id>/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/SPEC-SCHEMA.md

@@ -98,16 +98,16 @@ Unattended mode requires `unattended_allowed_after_preflight: true`, finite `max
 
 ### Path Naming Guards
 
-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.
+Default artifact roots live under `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with a shared `~/Documents/CleanRoom/<project>/implementation/` root. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. If the user does not provide an explicitly approved neutral project ID, generate one as `proj-` plus 8 lowercase hex characters. Do not use the source folder name as the task ID or project 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.
+The legacy flat `~/Documents/CleanRoom/<task-id>/` layout remains valid only for explicit single-task compatibility. Project names follow the same neutrality rules as task IDs and are 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
+- artifact base root, defaulting to `~/Documents/CleanRoom/<project>/tasks/<task-id>/` with neutral project and task IDs
+- `project_id` and `project_root` for the default project layout, omitted only for explicit single-task compatibility
 - 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,7 +19,7 @@ Keep `preflight-goal.json` in the controller/contaminated artifact domain. Clean
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-The CLI command `clean-room-skill init` (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`.
+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 default project layout 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. The legacy single-task root is created only when `--single-task` is passed and contains `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. Treat that bootstrap output as convenience scaffolding only. It does not replace this skill's initialization workflow, and it must not be treated as an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
 
 When using an existing CLI bootstrap, check `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `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.
 
@@ -29,8 +29,8 @@ 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`.
+- Artifact base root. Default the task root to `~/Documents/CleanRoom/<project>/tasks/<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.
+- Project grouping. Default to a clean-room project with shared `~/Documents/CleanRoom/<project>/implementation/`. When adding a task to an existing destination project, record the user-supplied `project_id` and `project_root`; otherwise generate a neutral `proj-` plus 8 lowercase hex project id. Project names follow the same neutrality rules as task IDs, match `[a-z0-9][a-z0-9-]{0,63}`, and are never derived from source folder names. Record both fields in `init-config.json` and the manifest `initialization_snapshot`. Use the legacy flat `~/Documents/CleanRoom/<task-id>/` layout only when the user explicitly chooses single-task compatibility.
 - 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/unattended/SKILL.md

@@ -24,8 +24,8 @@ Do not assume target language, license policy, dependency policy, exactness poli
 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.
+- Artifact base root, defaulting the task root to `~/Documents/CleanRoom/<project>/tasks/<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.
+- Project grouping, following the canonical `clean-room` project layout rules: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root, a neutral project name (`proj-` plus 8 lowercase hex unless the user supplies an approved neutral name, matching `[a-z0-9][a-z0-9-]{0,63}`, never source-derived), and at most one active task per project. Use legacy flat `<base>/<task-id>/` roots only when the user explicitly chooses single-task compatibility.
 - 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`.