clean-room-skill 0.3.0 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "clean-room",
       "source": "./",
       "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "author": {
         "name": "whit3rabbit"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "clean-room",
   "displayName": "Clean Room",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

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/lib/bootstrap.cjs

@@ -148,10 +148,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');
@@ -282,6 +284,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 +398,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 +421,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 +472,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 +494,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);
@@ -648,6 +671,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/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.3.1",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "bin": {
     "clean-room-skill": "bin/install.js"

package/plugin.json

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