clean-room-skill 0.1.3 → 0.1.5

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.1.3",
+      "version": "0.1.5",
       "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.1.3",
+  "version": "0.1.5",
   "author": {
     "name": "whit3rabbit"
   },
@@ -14,6 +14,5 @@
     "reverse-engineering",
     "compliance"
   ],
-  "skills": "./skills/",
-  "agents": "./agents/"
+  "skills": "./skills/"
 }

package/.codex-plugin/plugin.json

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

package/bin/verify.sh

@@ -39,6 +39,11 @@ echo "Validating JSON metadata..."
 "$python_cmd" -m json.tool .codex-plugin/plugin.json >/dev/null
 "$python_cmd" -m json.tool .claude-plugin/plugin.json >/dev/null
 
+if command -v claude >/dev/null 2>&1; then
+  echo "Validating Claude plugin manifest..."
+  claude plugin validate .claude-plugin/plugin.json
+fi
+
 echo "Compiling Python hooks and scripts..."
 "$python_cmd" -m compileall -q hooks skills/clean-room/scripts
 

package/docs/REFERENCE.md

@@ -165,6 +165,7 @@ Usage:
 ```bash
 npx clean-room-skill@latest preflight --template --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
 npx clean-room-skill@latest preflight --input ./preflight-goal.json --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
+npx clean-room-skill@latest preflight --template --bootstrap ~/Documents/CleanRoom/task-1234abcd
 ```
 
 Options:
@@ -174,6 +175,7 @@ Options:
 | `--template` | Write an attended draft with blocking open questions. |
 | `--input <path>` | Validate and normalize/copy a completed preflight goal. |
 | `--output <path>` | Destination `preflight-goal.json`. |
+| `--bootstrap <path>` | Generated task root or `clean-room-bootstrap.json`; writes to the generated contaminated artifact root after scaffold validation. |
 | `--mode <mode>` | `attended` or `unattended`; template supports attended only. |
 | `--dry-run` | Print actions without writing files. |
 | `--force` | Overwrite output if it already exists. |

package/lib/bootstrap.cjs

@@ -9,6 +9,7 @@ const {
   assertManagedPath,
   atomicWriteFile,
   atomicWriteFileNoOverwrite,
+  readJsonFile,
 } = require('./fs-utils.cjs');
 const { packageVersion } = require('./install-artifacts.cjs');
 const { expandTilde } = require('./runtime-layout.cjs');
@@ -21,6 +22,13 @@ const TARGET_PROFILES = new Set([
 ]);
 
 const TASK_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const BOOTSTRAP_METADATA_FILE = 'clean-room-bootstrap.json';
+const BOOTSTRAP_REPO_STUB = '.clean-room/README.md';
+const BOOTSTRAP_DIRS = Object.freeze({
+  contaminated: 'contaminated',
+  clean: 'clean',
+  quarantine: 'quarantine',
+});
 
 function defaultArtifactBase(homeDir = os.homedir()) {
   return path.join(homeDir, 'Documents', 'CleanRoom');
@@ -131,8 +139,8 @@ function resolveInitOptions(options, env = process.env, homeDir = os.homedir())
     artifactBase,
     outputRoot,
     roots,
-    metadataPath: assertManagedPath(outputRoot, 'clean-room-bootstrap.json'),
-    repoStubPath: assertManagedPath(targetDir, '.clean-room/README.md'),
+    metadataPath: assertManagedPath(outputRoot, BOOTSTRAP_METADATA_FILE),
+    repoStubPath: assertManagedPath(targetDir, BOOTSTRAP_REPO_STUB),
   };
 }
 
@@ -170,15 +178,165 @@ Start the runtime skill from your agent and provide the external output folder p
 }
 
 function assertWritableTargets(options) {
-  const conflicts = [];
+  const fileConflicts = [];
   for (const filePath of [options.metadataPath, options.repoStubPath]) {
     if (fs.existsSync(filePath) && !options.force) {
-      conflicts.push(filePath);
+      fileConflicts.push(filePath);
     }
   }
-  if (conflicts.length > 0) {
-    throw new Error(`bootstrap file already exists; use --force to overwrite: ${conflicts.join(', ')}`);
+  if (fileConflicts.length > 0) {
+    throw new Error(`bootstrap file already exists; use --force to overwrite: ${fileConflicts.join(', ')}`);
   }
+
+  const pathConflicts = [];
+  for (const dirPath of Object.values(options.roots)) {
+    if (fs.existsSync(dirPath) && !options.force) {
+      pathConflicts.push(dirPath);
+    }
+  }
+  if (pathConflicts.length > 0) {
+    throw new Error(`bootstrap generated path already exists; use --force to reuse it: ${pathConflicts.join(', ')}`);
+  }
+
+  for (const dirPath of Object.values(options.roots)) {
+    const stat = lstatIfExists(dirPath);
+    if (stat && !stat.isDirectory()) {
+      throw new Error(`bootstrap generated path is not a directory: ${dirPath}`);
+    }
+  }
+}
+
+function lstatIfExists(filePath) {
+  try {
+    return fs.lstatSync(filePath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function requireDirectory(dirPath, label, errors) {
+  const stat = lstatIfExists(dirPath);
+  if (!stat) {
+    errors.push(`${label} missing: ${dirPath}`);
+    return;
+  }
+  if (!stat.isDirectory()) {
+    errors.push(`${label} is not a directory: ${dirPath}`);
+  }
+}
+
+function requireFile(filePath, label, errors) {
+  const stat = lstatIfExists(filePath);
+  if (!stat) {
+    errors.push(`${label} missing: ${filePath}`);
+    return;
+  }
+  if (!stat.isFile()) {
+    errors.push(`${label} is not a file: ${filePath}`);
+  }
+}
+
+function expectMetadataString(metadata, field, errors) {
+  if (typeof metadata?.[field] !== 'string' || metadata[field].length === 0) {
+    errors.push(`bootstrap metadata ${field} must be a non-empty string`);
+    return null;
+  }
+  return metadata[field];
+}
+
+function assertMetadataPath(metadata, field, expectedPath, errors) {
+  const value = expectMetadataString(metadata, field, errors);
+  if (!value) return;
+  if (path.resolve(expandTilde(value)) !== expectedPath) {
+    errors.push(`bootstrap metadata ${field} must match ${expectedPath}`);
+  }
+}
+
+function validateBootstrapScaffold(taskRoot) {
+  if (typeof taskRoot !== 'string' || taskRoot.trim() === '') {
+    throw new Error('bootstrap path requires a task root');
+  }
+  const outputRoot = path.resolve(taskRoot);
+  const metadataPath = assertManagedPath(outputRoot, BOOTSTRAP_METADATA_FILE);
+  requireFileOrThrow(metadataPath, 'bootstrap metadata');
+
+  const metadata = readJsonFile(metadataPath, null);
+  const errors = [];
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    errors.push('bootstrap metadata must be an object');
+  } else {
+    if (metadata.schema !== 1) {
+      errors.push('bootstrap metadata schema must be 1');
+    }
+    if (metadata.package !== 'clean-room-skill') {
+      errors.push('bootstrap metadata package must be clean-room-skill');
+    }
+    const taskId = expectMetadataString(metadata, 'task_id', errors);
+    if (taskId && taskId !== path.basename(outputRoot)) {
+      errors.push('bootstrap metadata task_id must match the task root basename');
+    }
+    assertMetadataPath(metadata, 'output_root', outputRoot, errors);
+  }
+
+  const roots = {
+    contaminated: path.join(outputRoot, BOOTSTRAP_DIRS.contaminated),
+    clean: path.join(outputRoot, BOOTSTRAP_DIRS.clean),
+    quarantine: path.join(outputRoot, BOOTSTRAP_DIRS.quarantine),
+  };
+  for (const [label, dirPath] of Object.entries(roots)) {
+    requireDirectory(dirPath, `bootstrap ${label} directory`, errors);
+  }
+
+  if (metadata && typeof metadata === 'object' && !Array.isArray(metadata)) {
+    if (!metadata.roots || typeof metadata.roots !== 'object' || Array.isArray(metadata.roots)) {
+      errors.push('bootstrap metadata roots must be an object');
+    } else {
+      assertMetadataPath(metadata.roots, 'contaminated_artifacts', roots.contaminated, errors);
+      assertMetadataPath(metadata.roots, 'clean_artifacts', roots.clean, errors);
+      assertMetadataPath(metadata.roots, 'quarantine', roots.quarantine, errors);
+    }
+  }
+
+  const targetDir = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+    ? expectMetadataString(metadata, 'target_dir', errors)
+    : null;
+  const repoStubPath = targetDir ? assertManagedPath(path.resolve(expandTilde(targetDir)), BOOTSTRAP_REPO_STUB) : null;
+  if (repoStubPath) {
+    requireFile(repoStubPath, 'bootstrap repo stub', errors);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`bootstrap scaffold is invalid:\n  ${errors.join('\n  ')}`);
+  }
+
+  return {
+    outputRoot,
+    metadataPath,
+    metadata,
+    roots,
+    repoStubPath,
+  };
+}
+
+function requireFileOrThrow(filePath, label) {
+  const errors = [];
+  requireFile(filePath, label, errors);
+  if (errors.length > 0) {
+    throw new Error(`bootstrap scaffold is invalid:\n  ${errors.join('\n  ')}`);
+  }
+}
+
+function resolveBootstrapScaffold(value, cwd = process.cwd(), homeDir = os.homedir()) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('--bootstrap requires a path');
+  }
+  const expanded = expandTilde(value, homeDir);
+  const resolved = path.resolve(cwd, expanded);
+  const taskRoot = path.basename(resolved) === BOOTSTRAP_METADATA_FILE
+    ? path.dirname(resolved)
+    : resolved;
+  return validateBootstrapScaffold(taskRoot);
 }
 
 function writeBootstrapFile(filePath, data, force) {
@@ -220,9 +378,14 @@ function printInitResult(options) {
   console.log(`  repo stub: ${options.repoStubPath}`);
   console.log('');
   console.log('Next steps:');
-  console.log('  install safe hooks: npx clean-room-skill@latest --codex --global --hooks=safe --yes');
-  console.log('  start in your runtime: invoke the clean-room init skill, then clean-room');
-  console.log('  uninstall runtime install: npx clean-room-skill@latest --codex --global --uninstall --yes');
+  console.log('  Codex:');
+  console.log('    install safe hooks: npx clean-room-skill@latest --codex --global --hooks=safe --yes');
+  console.log('    start in Codex: invoke the init skill, then clean-room through @ or the skills UI');
+  console.log('    uninstall runtime install: npx clean-room-skill@latest --codex --global --uninstall --yes');
+  console.log('  Claude Code:');
+  console.log('    install safe hooks: npx clean-room-skill@latest --claude --global --hooks=safe --yes');
+  console.log('    start in Claude Code: /clean-room:init, then /clean-room or /clean-room:attended');
+  console.log('    uninstall runtime install: npx clean-room-skill@latest --claude --global --uninstall --yes');
   console.log('  strict hooks are only for dedicated clean-room Codex or Claude homes');
 }
 
@@ -238,10 +401,13 @@ function runInit(argv, context = {}) {
 }
 
 module.exports = {
+  BOOTSTRAP_METADATA_FILE,
   defaultArtifactBase,
   generateTaskId,
   parseInitArgs,
+  resolveBootstrapScaffold,
   resolveInitOptions,
   runInit,
   TARGET_PROFILES,
+  validateBootstrapScaffold,
 };

package/lib/preflight.cjs

@@ -9,6 +9,7 @@ const {
   atomicWriteFileNoOverwrite,
   readJsonFile,
 } = require('./fs-utils.cjs');
+const { resolveBootstrapScaffold } = require('./bootstrap.cjs');
 
 const VALID_MODES = new Set(['attended', 'unattended']);
 const VALID_INTENTS = new Set([
@@ -26,7 +27,7 @@ const VALID_NETWORK_POLICIES = new Set(['off', 'deps-only', 'on']);
 const VALID_DEPENDENCY_INSTALL_POLICIES = new Set(['offline', 'locked', 'allow-new']);
 
 function printPreflightHelp() {
-  console.log(`Usage: clean-room-skill preflight (--template | --input <path>) --output <path> [options]
+  console.log(`Usage: clean-room-skill preflight (--template | --input <path>) (--output <path> | --bootstrap <path>) [options]
 
 Create or validate a clean-room preflight goal contract.
 
@@ -34,6 +35,7 @@ Options:
   --template             Write an attended draft with blocking open questions
   --input <path>         Validate and normalize/copy a completed preflight goal
   --output <path>        Destination preflight-goal.json
+  --bootstrap <path>     Generated task root or clean-room-bootstrap.json
   --mode <mode>          attended or unattended (template supports attended only)
   --dry-run              Print actions without writing files
   --force                Overwrite output if it already exists
@@ -46,6 +48,7 @@ function parsePreflightArgs(argv) {
     template: false,
     input: null,
     output: null,
+    bootstrap: null,
     mode: 'attended',
     dryRun: false,
     force: false,
@@ -72,6 +75,11 @@ function parsePreflightArgs(argv) {
       options.output = requiredValue(argv, index, '--output');
     } else if (arg.startsWith('--output=')) {
       options.output = arg.slice('--output='.length);
+    } else if (arg === '--bootstrap') {
+      index += 1;
+      options.bootstrap = requiredValue(argv, index, '--bootstrap');
+    } else if (arg.startsWith('--bootstrap=')) {
+      options.bootstrap = arg.slice('--bootstrap='.length);
     } else if (arg === '--mode') {
       index += 1;
       options.mode = requiredValue(argv, index, '--mode');
@@ -444,9 +452,18 @@ function runPreflight(argv, context = {}) {
   if (parsed.template === Boolean(parsed.input)) {
     throw new Error('specify exactly one of --template or --input');
   }
+  if (parsed.bootstrap && parsed.output) {
+    throw new Error('--bootstrap conflicts with --output');
+  }
+  if (!parsed.bootstrap && !parsed.output) {
+    throw new Error('specify exactly one of --output or --bootstrap');
+  }
   const cwd = context.cwd || process.cwd();
   const homeDir = context.homeDir || os.homedir();
-  const outputPath = resolveOutputPath(parsed.output, cwd, homeDir);
+  const bootstrap = parsed.bootstrap ? resolveBootstrapScaffold(parsed.bootstrap, cwd, homeDir) : null;
+  const outputPath = bootstrap
+    ? path.join(bootstrap.roots.contaminated, 'preflight-goal.json')
+    : resolveOutputPath(parsed.output, cwd, homeDir);
   let goal;
   if (parsed.template) {
     goal = buildTemplate(parsed.mode);

package/package.json

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

package/skills/init/SKILL.md

@@ -21,6 +21,8 @@ Use the canonical `clean-room` skill workflow and references in this plugin. Pre
 
 The CLI command `clean-room-skill init` may have pre-created neutral external folders and a clean-safe `.clean-room/README.md` stub in the target repository. 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/`, 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.
+
 ## Gather
 
 Collect only setup decisions that affect correctness, safety, resumability, or output shape:

package/skills/preflight/SKILL.md

@@ -11,6 +11,8 @@ 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`, check the generated bootstrap scaffold before creating or copying `preflight-goal.json`: `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `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`.
+
 ## Required Contract
 
 Record these decisions:
@@ -45,9 +47,10 @@ Use the CLI only for template creation or validation/copying:
 ```bash
 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
 ```
 
-`--template` writes an attended draft with blocking open questions. It does not support unattended mode. Use `--input` for completed contracts.
+`--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` and writes to the generated contaminated artifact root after scaffold validation.
 
 ## Handoff