clean-room-skill 0.1.5 → 0.1.6

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -45,6 +45,10 @@ npx clean-room-skill@latest --claude --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
+For edge cases such as ccsilo variants or modified Claude directories, add `--config-dir <path-to-claude-config-root>` to target that Claude config root explicitly.
+
+Claude global installs use Claude's plugin system for skills and agents, so entry points are namespaced as `/clean-room:init`, `/clean-room:preflight`, and `/clean-room`. The installer still manages hook files and migrates older standalone Claude skill copies out of the config root on reinstall or update.
+
 Hook modes:
 
 - `--hooks=safe`: default. Hooks are installed but enforce only during clean-room role sessions with the required environment.
@@ -76,14 +80,14 @@ Optionally create neutral external run folders and a clean-safe repository stub:
 npx clean-room-skill@latest init
 ```
 
-The default artifact base is `~/Documents/CleanRoom/<task-id>/`. Keep active contaminated artifacts, clean artifacts, and clean implementation roots separate.
+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.
 
 In Claude Code, invoke skills with the plugin namespace:
 
 ```text
-/clean-room
-/clean-room:preflight
 /clean-room:init
+/clean-room:preflight
+/clean-room
 /clean-room:attended
 /clean-room:unattended
 /clean-room:resume
@@ -108,11 +112,11 @@ The `run` command executes one bounded inner clean-room loop for an already appr
 
 ![Clean Room Architecture](assets/clean-room-arch.svg)
 
-1. Record the goal contract.
-   Use `/clean-room:preflight` or `clean-room-skill preflight` before source discovery. This creates or validates `preflight-goal.json` on the contaminated/controller side.
+1. Initialize or bootstrap the run.
+   Use `npx clean-room-skill@latest init` to create neutral external run folders and a clean-safe repository stub, or use `/clean-room:init` for skill-driven run preferences. The active `init-config.json` stays out of the clean implementation repository.
 
-2. Initialize preferences.
-   Use `/clean-room:init` to record artifact roots, target profile, model preferences, clean-safe rules, and contaminated-only rules. The active `init-config.json` stays out of the clean implementation repository.
+2. Record the goal contract.
+   Use `npx clean-room-skill@latest preflight` or `/clean-room:preflight` before source discovery, attended mode, or unattended mode. This creates or validates `preflight-goal.json` on the contaminated/controller side.
 
 3. Start the controller.
    Use `/clean-room` or `/clean-room:attended` for human review gates. Use `/clean-room:unattended` only after preflight allows bounded unattended work with finite iteration limits and no open questions.
@@ -128,28 +132,38 @@ The `run` command executes one bounded inner clean-room loop for an already appr
 
 Use recovery skills instead of chat history:
 
-- `resume`: continue from durable artifacts.
-- `start-over`: archive or quarantine current artifacts without deletion, then restart with a fresh neutral task id.
-- `refocus`: audit current artifacts against declared scope without expanding scope.
+- `/clean-room:resume`: continue from durable artifacts.
+- `/clean-room:start-over`: archive or quarantine current artifacts without deletion, then restart with a fresh neutral task id.
+- `/clean-room:refocus`: audit current artifacts against declared scope without expanding scope.
+
+## Workflow Entry Points
+
+| Order | Entry point | Type | Use it for |
+| --- | --- | --- | --- |
+| 1 | `npx clean-room-skill@latest init` | CLI command | Create neutral external run folders and a clean-safe `.clean-room/README.md` stub. |
+| 1 | `/clean-room:init` | Skill | Record run preferences, separated roots, schema profile, and model policy. |
+| 2 | `npx clean-room-skill@latest preflight` | CLI command | Create or validate the Stage 0 goal contract. |
+| 2 | `/clean-room:preflight` | Skill | Record the required goal, policy, output, and controller-mode contract. |
+| 3 | `/clean-room` | Skill | Start the setup wizard for authorized clean-room work. |
+| 3 | `/clean-room:attended` | Skill | Start the wizard in attended mode with human review gates. |
+| 3 | `/clean-room:unattended` | Skill | Start the wizard in bounded unattended mode with finite loop limits. |
+| 4 | `npx clean-room-skill@latest run` | CLI command | Execute the bounded inner clean-room runner for one approved spec slice. |
+
+### Maintenance CLI Commands
+
+| Command | Use it for |
+| --- | --- |
+| `npx clean-room-skill@latest doctor` | Smoke test generated Codex or Claude hook registration. |
+| `npx clean-room-skill@latest status` | Report installed runtime version, drift, and hook state. |
+| `npx clean-room-skill@latest update` | Refresh installed runtime files without onboarding. |
 
-## Commands / Skills
+### Recovery Skills
 
-| Command or skill | Use it for |
+| Skill | Use it for |
 | --- | --- |
-| `clean-room-skill init` | Create neutral external run folders and a clean-safe `.clean-room/README.md` stub. |
-| `clean-room-skill preflight` | Create or validate the Stage 0 goal contract. |
-| `clean-room-skill run` | Execute the bounded inner clean-room runner for one approved spec slice. |
-| `clean-room-skill doctor` | Smoke test generated Codex or Claude hook registration. |
-| `clean-room-skill status` | Report installed runtime version, drift, and hook state. |
-| `clean-room-skill update` | Refresh installed runtime files without onboarding. |
-| `clean-room` | Start the setup wizard for authorized clean-room work. |
-| `preflight` | Record the required goal, policy, output, and controller-mode contract. |
-| `init` | Record run preferences, separated roots, schema profile, and model policy. |
-| `attended` | Start the wizard in attended mode with human review gates. |
-| `unattended` | Start the wizard in bounded unattended mode with finite loop limits. |
-| `resume` | Continue an existing run from durable artifacts. |
-| `start-over` | Non-destructively archive or quarantine current artifacts and restart. |
-| `refocus` | Audit a run and route it back to missed gates without adding scope. |
+| `/clean-room:resume` | Continue an existing run from durable artifacts. |
+| `/clean-room:start-over` | Non-destructively archive or quarantine current artifacts and restart. |
+| `/clean-room:refocus` | Audit a run and route it back to missed gates without adding scope. |
 
 Reference files:
 

package/agents/contaminated-manager-verifier.md

@@ -39,6 +39,13 @@ Responsibilities:
 - Convert terminal implementation gaps into abstract delta tickets for the next clean run. Do not steer an in-progress Agent 3 loop.
 - Send only `clean-run-context.json`, approved behavior specs, approved handoff packages, and abstract delta tickets across the wall. Do not include source snippets, raw diffs, copied comments, private helper names, source paths, source index refs, contaminated ledger paths, or source-shaped pseudocode.
 
+Use this file map when a CLI bootstrap is present:
+
+- Contaminated artifact root: write `preflight-goal.json`, `init-config.json`, `task-manifest.json`, `source-index.json`, `coverage-ledger.json`, `evidence-ledger.json`, private identifier denylist artifacts, and `clean-room-result.json`.
+- Clean artifact root: only sanitized handoff artifacts, `clean-run-context.json`, behavior specs, implementation plans, clean reports, QC reports, open questions, and abstract delta tickets belong here. Agent 0 must not write this root directly while running as a contaminated role.
+- Implementation root: Agent 3 writes destination code, tests, fixtures, and destination project files here. Agent 0 must not write this root.
+- Quarantine root: rejected, contaminated, or incident artifacts that must not cross into the clean domain.
+
 Every new role session must receive `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and, for clean or source-denied roles, `CLEAN_ROOM_ALLOWED_READ_ROOTS`. Do not assume environment variables persist across sessions.
 
 In unattended mode, reload durable artifacts before each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, launch roles from fresh context, validate schema and leakage before advancing state, and stop on authorization, scope, contamination, validation, leakage, blocked-unit, implementation-complete, coverage-complete, spec-slice, no-progress, repeated-selection, or iteration-limit conditions. Do not use prior chat history as task state.

package/bin/install.js

@@ -40,6 +40,12 @@ const INSTALL_LOCK_NAME = '.clean-room-install.lock';
 const INSTALL_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_LOCK_WAIT_MS', 30_000);
 const INSTALL_LOCK_POLL_MS = 100;
 const PYTHON_PROBE_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_PYTHON_TIMEOUT_MS', 10_000);
+const CLAUDE_PLUGIN_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_CLAUDE_PLUGIN_TIMEOUT_MS', 120_000);
+const CLAUDE_PLUGIN_MARKETPLACE_NAME = 'clean-room-skill';
+const CLAUDE_PLUGIN_NAME = 'clean-room';
+const CLAUDE_PLUGIN_ID = `${CLAUDE_PLUGIN_NAME}@${CLAUDE_PLUGIN_MARKETPLACE_NAME}`;
+const CLAUDE_PLUGIN_SOURCE_URL = 'https://github.com/whit3rabbit/clean-room-skill.git';
+const CLAUDE_PLUGIN_SCOPE = 'user';
 
 function envPositiveInteger(name, fallback) {
   const value = process.env[name];
@@ -448,7 +454,7 @@ function defaultRuntimeSelections(statuses, action = 'install') {
     return statuses.filter((status) => isInstalledStatus(status)).map((status) => status.runtime);
   }
   if (action === 'update') {
-    return statuses.filter((status) => status.state === 'installed').map((status) => status.runtime);
+    return selectableRuntimeSelections(statuses, action);
   }
   if (action === 'status') {
     return statuses.map((status) => status.runtime);
@@ -458,11 +464,57 @@ function defaultRuntimeSelections(statuses, action = 'install') {
 
 function detectedRuntimeSelections(statuses, action = 'install') {
   if (action === 'update') {
-    return statuses.filter((status) => status.state === 'installed').map((status) => status.runtime);
+    return selectableRuntimeSelections(statuses, action);
   }
   return statuses.filter((status) => isInstalledStatus(status)).map((status) => status.runtime);
 }
 
+function isUpdateTargetStatus(status) {
+  return status?.state === 'installed' || status?.state === 'update-available';
+}
+
+function isSelectableRuntimeStatus(status, action = 'install') {
+  if (action === 'update') {
+    return isUpdateTargetStatus(status);
+  }
+  return true;
+}
+
+function selectableRuntimeSelections(statuses, action = 'install') {
+  return statuses
+    .filter((status) => isSelectableRuntimeStatus(status, action))
+    .map((status) => status.runtime);
+}
+
+function statusForRuntime(statuses, runtime) {
+  return statuses.find((status) => status.runtime === runtime) || {
+    runtime,
+    state: 'not-installed',
+  };
+}
+
+function unavailableRuntimeSelectionMessage(status, action) {
+  if (action === 'update') {
+    return `${status.runtime} is not installed in this scope; choose Install to add it.`;
+  }
+  return `${status.runtime} cannot be selected for ${action}.`;
+}
+
+function emptyRuntimeSelectionMessage(statuses, action) {
+  if (action === 'update' && selectableRuntimeSelections(statuses, action).length === 0) {
+    return 'No installed runtimes detected for update. Choose Install instead.';
+  }
+  return 'Select at least one runtime.';
+}
+
+function addRuntimeSelection(selected, runtime, statuses, action) {
+  const status = statusForRuntime(statuses, runtime);
+  if (!isSelectableRuntimeStatus(status, action)) {
+    throw new Error(unavailableRuntimeSelectionMessage(status, action));
+  }
+  selected.push(runtime);
+}
+
 function parseRuntimeSelection(answer, statuses, action = 'install') {
   const text = answer.trim().toLowerCase();
   if (text === '') {
@@ -480,7 +532,7 @@ function parseRuntimeSelection(answer, statuses, action = 'install') {
   const tokens = text.split(/[,\s]+/).filter(Boolean);
   for (const token of tokens) {
     if (token === 'all') {
-      selected.push(...RUNTIMES);
+      selected.push(...(action === 'update' ? selectableRuntimeSelections(statuses, action) : RUNTIMES));
       continue;
     }
     if (token === 'installed') {
@@ -495,16 +547,16 @@ function parseRuntimeSelection(answer, statuses, action = 'install') {
         throw new Error(`invalid runtime range: ${token}`);
       }
       for (let index = start; index <= end; index += 1) {
-        selected.push(runtimeForSelectionIndex(statuses, index));
+        addRuntimeSelection(selected, runtimeForSelectionIndex(statuses, index), statuses, action);
       }
       continue;
     }
     if (/^\d+$/.test(token)) {
-      selected.push(runtimeForSelectionIndex(statuses, Number(token)));
+      addRuntimeSelection(selected, runtimeForSelectionIndex(statuses, Number(token)), statuses, action);
       continue;
     }
     if (RUNTIMES.includes(token)) {
-      selected.push(token);
+      addRuntimeSelection(selected, token, statuses, action);
       continue;
     }
     throw new Error(`unsupported runtime selection: ${token}`);
@@ -528,12 +580,12 @@ function isInstalledStatus(status) {
 }
 
 function nextTuiStage(options, flags) {
-  if (!flags.actionResolved) {
-    return 'action';
-  }
   if (!options.scope) {
     return 'scope';
   }
+  if (!flags.actionResolved) {
+    return 'action';
+  }
   if (operationForOptions(options) === 'status') {
     return 'complete';
   }
@@ -580,14 +632,18 @@ function RuntimeMultiSelect({ React, Box, Text, useInput, h, action, statuses, o
   const [selected, setSelected] = React.useState(initialSelected);
   const [error, setError] = React.useState('');
 
-  function toggle(runtime) {
+  function toggle(status) {
     setError('');
+    if (!isSelectableRuntimeStatus(status, action)) {
+      setError(unavailableRuntimeSelectionMessage(status, action));
+      return;
+    }
     setSelected((current) => {
       const next = new Set(current);
-      if (next.has(runtime)) {
-        next.delete(runtime);
+      if (next.has(status.runtime)) {
+        next.delete(status.runtime);
       } else {
-        next.add(runtime);
+        next.add(status.runtime);
       }
       return next;
     });
@@ -603,17 +659,17 @@ function RuntimeMultiSelect({ React, Box, Text, useInput, h, action, statuses, o
     } else if (key.end) {
       setIndex(statuses.length - 1);
     } else if (input === ' ') {
-      toggle(statuses[index].runtime);
+      toggle(statuses[index]);
     } else if (input === 'a') {
       setError('');
-      setSelected(new Set(RUNTIMES));
+      setSelected(new Set(action === 'update' ? selectableRuntimeSelections(statuses, action) : RUNTIMES));
     } else if (input === 'i') {
       setError('');
       setSelected(new Set(detectedRuntimeSelections(statuses, action)));
     } else if (key.return || /[\r\n]/.test(input)) {
       const runtimes = RUNTIMES.filter((runtime) => selected.has(runtime));
       if (runtimes.length === 0) {
-        setError('Select at least one runtime.');
+        setError(emptyRuntimeSelectionMessage(statuses, action));
         return;
       }
       onSubmit(runtimes);
@@ -622,7 +678,7 @@ function RuntimeMultiSelect({ React, Box, Text, useInput, h, action, statuses, o
 
   return h(Box, { flexDirection: 'column' },
     h(Text, { bold: true }, `Runtimes to ${action}`),
-    h(Text, { dimColor: true }, 'Space toggles. a selects all. i selects detected installs. Enter continues.'),
+    h(Text, { dimColor: true }, `${action === 'update' ? 'Space toggles installed runtimes. a selects installed runtimes.' : 'Space toggles. a selects all.'} i selects detected installs. Enter continues.`),
     ...statuses.map((status, itemIndex) => {
       const checked = selected.has(status.runtime) ? '[x]' : '[ ]';
       const cursor = itemIndex === index ? '>' : ' ';
@@ -681,6 +737,200 @@ function displayPath(filePath) {
   return filePath;
 }
 
+function usesClaudeGlobalPlugin(layout) {
+  return layout.runtime === 'claude' && layout.scope === 'global';
+}
+
+function claudePluginSource() {
+  return `${CLAUDE_PLUGIN_SOURCE_URL}#v${packageVersion()}`;
+}
+
+function truncateCommandOutput(value) {
+  const text = String(value || '').trim();
+  if (text.length <= 2000) return text;
+  return `${text.slice(0, 2000)}...`;
+}
+
+function claudePluginEnv(layout) {
+  return {
+    ...process.env,
+    CLAUDE_CONFIG_DIR: layout.targetRoot,
+  };
+}
+
+function claudeCommandLabel(args) {
+  return ['claude', ...args].join(' ');
+}
+
+function claudePluginCommandFailure(args, result) {
+  const parts = [`Claude plugin command failed: ${claudeCommandLabel(args)}`];
+  if (result.error) {
+    parts.push(result.error.message);
+  }
+  if (result.status !== null && result.status !== undefined) {
+    parts.push(`status ${result.status}`);
+  }
+  if (result.signal) {
+    parts.push(`signal ${result.signal}`);
+  }
+  const stdout = truncateCommandOutput(result.stdout);
+  const stderr = truncateCommandOutput(result.stderr);
+  if (stdout) parts.push(`stdout: ${stdout}`);
+  if (stderr) parts.push(`stderr: ${stderr}`);
+  return parts.join('; ');
+}
+
+function runClaudePluginCommand(layout, args, options = {}) {
+  const result = spawnSync('claude', args, {
+    encoding: 'utf8',
+    env: claudePluginEnv(layout),
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: CLAUDE_PLUGIN_TIMEOUT_MS,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(claudePluginCommandFailure(args, result));
+  }
+  if (!options.silent) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  return result;
+}
+
+function readClaudePluginJson(layout, args) {
+  const result = runClaudePluginCommand(layout, args, { silent: true });
+  try {
+    const parsed = JSON.parse(result.stdout || '[]');
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (err) {
+    throw new Error(
+      `Claude plugin command returned invalid JSON: ${claudeCommandLabel(args)}; ` +
+      `stdout: ${truncateCommandOutput(result.stdout)}; ${err.message}`
+    );
+  }
+}
+
+function claudeMarketplaceExists(layout) {
+  return readClaudePluginJson(layout, ['plugin', 'marketplace', 'list', '--json'])
+    .some((entry) => entry && entry.name === CLAUDE_PLUGIN_MARKETPLACE_NAME);
+}
+
+function claudePluginEntry(layout) {
+  return readClaudePluginJson(layout, ['plugin', 'list', '--json'])
+    .find((entry) => entry && entry.id === CLAUDE_PLUGIN_ID) || null;
+}
+
+function claudePluginExists(layout) {
+  return Boolean(claudePluginEntry(layout));
+}
+
+function claudePluginMetadata(manifest, state = {}) {
+  const previous = manifest?.claude_plugin || {};
+  const metadata = {
+    plugin_id: CLAUDE_PLUGIN_ID,
+    plugin_name: CLAUDE_PLUGIN_NAME,
+    marketplace_name: CLAUDE_PLUGIN_MARKETPLACE_NAME,
+    source_url: CLAUDE_PLUGIN_SOURCE_URL,
+    source: claudePluginSource(),
+    scope: CLAUDE_PLUGIN_SCOPE,
+    version: packageVersion(),
+    marketplace_added_by_installer: previous.marketplace_added_by_installer === true ||
+      state.marketplaceAdded === true,
+    plugin_installed_by_installer: previous.plugin_installed_by_installer === true ||
+      state.pluginInstalled === true,
+    recorded_at: new Date().toISOString(),
+  };
+  if (state.installPath || previous.install_path) {
+    metadata.install_path = state.installPath || previous.install_path;
+  }
+  return metadata;
+}
+
+function ensureClaudeGlobalPlugin(layout, manifest, options, action) {
+  if (!usesClaudeGlobalPlugin(layout)) return null;
+
+  const source = claudePluginSource();
+  if (options.dryRun) {
+    const marketplaceVerb = action === 'update' ? 'refresh' : 'add';
+    const pluginVerb = action === 'update' ? 'update or install' : 'install';
+    console.log(`  Claude plugin marketplace: would ${marketplaceVerb} ${source}`);
+    console.log(`  Claude plugin: would ${pluginVerb} ${CLAUDE_PLUGIN_ID}`);
+    return claudePluginMetadata(manifest);
+  }
+
+  const marketplaceWasPresent = claudeMarketplaceExists(layout);
+  console.log(`  Claude plugin marketplace: ${source}`);
+  runClaudePluginCommand(layout, [
+    'plugin',
+    'marketplace',
+    'add',
+    source,
+    '--scope',
+    CLAUDE_PLUGIN_SCOPE,
+  ]);
+
+  const pluginBefore = claudePluginEntry(layout);
+  const pluginWasPresent = Boolean(pluginBefore);
+  if (action === 'update' && pluginWasPresent) {
+    console.log(`  Claude plugin: updating ${CLAUDE_PLUGIN_ID}`);
+    runClaudePluginCommand(layout, ['plugin', 'update', CLAUDE_PLUGIN_ID]);
+  } else if (!pluginWasPresent) {
+    console.log(`  Claude plugin: installing ${CLAUDE_PLUGIN_ID}`);
+    runClaudePluginCommand(layout, [
+      'plugin',
+      'install',
+      CLAUDE_PLUGIN_ID,
+      '--scope',
+      CLAUDE_PLUGIN_SCOPE,
+    ]);
+  } else {
+    console.log(`  Claude plugin: already installed ${CLAUDE_PLUGIN_ID}`);
+  }
+
+  const pluginAfter = claudePluginEntry(layout) || pluginBefore;
+  return claudePluginMetadata(manifest, {
+    marketplaceAdded: !marketplaceWasPresent,
+    pluginInstalled: !pluginWasPresent,
+    installPath: pluginAfter?.installPath,
+  });
+}
+
+function removeClaudeGlobalPlugin(layout, manifest, options) {
+  if (!usesClaudeGlobalPlugin(layout)) return;
+  const plugin = manifest?.claude_plugin;
+  if (!plugin) return;
+
+  if (options.dryRun) {
+    if (plugin.plugin_installed_by_installer) {
+      console.log(`  Claude plugin: would uninstall ${plugin.plugin_id || CLAUDE_PLUGIN_ID}`);
+    }
+    if (plugin.marketplace_added_by_installer) {
+      console.log(`  Claude plugin marketplace: would remove ${plugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME}`);
+    }
+    return;
+  }
+
+  if (plugin.plugin_installed_by_installer) {
+    const pluginId = plugin.plugin_id || CLAUDE_PLUGIN_ID;
+    if (claudePluginExists(layout)) {
+      console.log(`  Claude plugin: uninstalling ${pluginId}`);
+      runClaudePluginCommand(layout, ['plugin', 'uninstall', pluginId]);
+    } else {
+      console.log(`  Claude plugin: already absent ${pluginId}`);
+    }
+  }
+
+  if (plugin.marketplace_added_by_installer) {
+    const marketplaceName = plugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME;
+    if (claudeMarketplaceExists(layout)) {
+      console.log(`  Claude plugin marketplace: removing ${marketplaceName}`);
+      runClaudePluginCommand(layout, ['plugin', 'marketplace', 'remove', marketplaceName]);
+    } else {
+      console.log(`  Claude plugin marketplace: already absent ${marketplaceName}`);
+    }
+  }
+}
+
 function collectRuntimeStatus(runtime, scope, configDir) {
   const layout = resolveRuntimeLayout(runtime, scope, { configDir });
   const base = {
@@ -701,6 +951,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     unknownConflicts: 0,
     hookRegistration: layout.supportsHookRegistration ? 'none' : 'unsupported',
     updateAvailable: false,
+    claudePlugin: null,
     issues: [],
   };
 
@@ -790,6 +1041,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     unknownConflicts: plan.unknownConflicts.length,
     hookRegistration: hookState,
     updateAvailable,
+    claudePlugin: manifest.claude_plugin || null,
     issues,
   };
 }
@@ -835,6 +1087,9 @@ function printStatusReport(statuses) {
       console.log(`  phase: ${status.phase || 'unknown'}`);
       console.log(`  hooks: ${status.hooksMode || 'unknown'}; registration ${status.hookRegistration}`);
       console.log(`  files: ${status.files}; missing ${status.missing}; modified ${status.modified}; stale ${status.stale}; conflicts ${status.unknownConflicts}`);
+      if (status.claudePlugin) {
+        console.log(`  plugin: ${status.claudePlugin.plugin_id || CLAUDE_PLUGIN_ID}; marketplace ${status.claudePlugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME}`);
+      }
     } else if (status.hookRegistration === 'present') {
       console.log('  hooks: managed hook registration present without install manifest');
     }
@@ -853,7 +1108,7 @@ function selectedUpdateRuntimes(options) {
     return options.runtimes;
   }
   return runtimeInstallStatuses(options.scope, options.configDir)
-    .filter((status) => status.state === 'installed')
+    .filter((status) => isUpdateTargetStatus(status))
     .map((status) => status.runtime);
 }
 
@@ -985,6 +1240,8 @@ async function installRuntime(runtime, options) {
     }
 
     const hookResult = prepareHookRegistration(layout, options.hookMode, { dryRun: options.dryRun });
+    const pluginState = ensureClaudeGlobalPlugin(layout, manifest, options, verb);
+    const installState = pluginState ? { claude_plugin: pluginState } : {};
     // Install order is files, installing manifest, hook config, then complete manifest.
     // The installing manifest gives repair/uninstall a durable handle if hook config write fails.
     let result;
@@ -1002,6 +1259,7 @@ async function installRuntime(runtime, options) {
       try {
         writeInstallManifest(targetRoot, result.manifest, runtime, options.scope, options.hookMode, options.dryRun, {
           phase: 'installing',
+          ...installState,
         });
       } catch (err) {
         throw new Error(partialInstallMessage(targetRoot, {
@@ -1027,13 +1285,14 @@ async function installRuntime(runtime, options) {
               result.manifest,
               runtime,
               options.scope,
-              options.hookMode,
-              false,
-              {
-                phase: 'installing',
-                ...hookRegistrationFailureState(hookResult, err),
-              }
-            );
+                options.hookMode,
+                false,
+                {
+                  phase: 'installing',
+                  ...installState,
+                  ...hookRegistrationFailureState(hookResult, err),
+                }
+              );
             manifestStatus = 'install manifest records the failed hook registration';
           } catch {
             manifestStatus = 'install manifest could not record the failed hook registration';
@@ -1061,6 +1320,7 @@ async function installRuntime(runtime, options) {
       try {
         writeInstallManifest(targetRoot, result.manifest, runtime, options.scope, options.hookMode, options.dryRun, {
           phase: 'complete',
+          ...installState,
         });
       } catch (err) {
         throw new Error(partialInstallMessage(targetRoot, {
@@ -1141,6 +1401,7 @@ async function uninstallRuntime(runtime, options) {
       console.log(`  untracked package-path files left in place: ${plan.untracked.length}`);
     }
 
+    removeClaudeGlobalPlugin(layout, manifest, options);
     const result = applyUninstall(targetRoot, plan, options.dryRun);
     if (!options.dryRun) {
       removeHookRegistrations(layout, false);

package/docs/ARCHITECTURE.md

@@ -45,6 +45,7 @@ To assist in logical unit decomposition, the workflow supports an optional sourc
 
 *   **Execution Boundary**: This tooling runs exclusively in the contaminated domain before clean-room role sessions are initialized.
 *   **Traversal Bounds**: Source indexing enforces file count, per-file byte, total byte, batch token, and segment caps. It validates file size again after reading, skips files that change during read, records directory walk errors, and prunes traversal after global limits are exhausted with an aggregate skipped entry.
+*   **Agent 0 Use**: Agent 0 consumes `source-index.json` only to create neutral `task-manifest.json` units and per-unit `source_index_refs`. The index stays contaminated-only and does not cross to Agent 1.5, Agent 2, Agent 3, or clean handoff packages.
 *   **Tool Trust Policy**: By default, tool discovery operates in `stat-only` mode and does not execute third-party binaries. It queries version strings only when explicitly invoked with `--probe-tools`. Tools discovered under `/opt/homebrew` or `/usr/local` remain stat-only unless `--allow-user-toolchain-probes` is also supplied. Project-local directories (such as `.bin` or `node_modules/.bin`) are ignored unless the environment variable `RE_SKILLS_TRUST_PROJECT_TOOLS=1` or the flag `--allow-working-project-tools` is supplied.
 *   **Local Tool Install Safety**: Explicit npm-backed helper installs are strict-version pinned and serialized with a cache-local lock before mutating `~/.cache/re-skills/clean-room-tools/npm`. Prefix creation failures, subprocess timeouts, and subprocess launch errors are returned as structured JSON facts instead of raw tracebacks.
 
@@ -196,6 +197,7 @@ The architecture delegates work across five distinct custom role agents to enfor
     *   Requires clean-safe `goal_contract` fields and `code_hygiene_policy` in `clean-run-context.json`.
     *   Accepts Agent 0 input only as schema-valid durable sanitized artifacts.
     *   Reads the clean destination foundation under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
+    *   Cannot write to `CLEAN_ROOM_IMPLEMENTATION_ROOTS`; the write hook rejects Agent 2 implementation-root writes.
     *   Merges approved handoff artifacts into the clean workspace.
     *   Writes `implementation-plan.json` with relative destination paths, tests, code hygiene policy, constraints, risks, and argv-array verification commands.
     *   Keeps `skeleton-manifest.json` valid when the target profile expects it.
@@ -229,7 +231,7 @@ Agent 3's terminal report is not enough to return. Agent 0 must consume that rep
 *   Records controller memory in contaminated-side `controller-run-ledger.json`.
 *   Writes `clean-room-result.json` before returning to the outer spec loop.
 
-Progress is durable-artifact based. Chat output alone is not progress.
+Progress is durable-artifact based. `clean-room-skill run` compares semantic JSON artifact hashes that ignore volatile timestamp and artifact-hash fields, plus raw file hashes under implementation roots. Chat output alone and timestamp-only artifact churn do not count as progress.
 
 ---
 
@@ -258,13 +260,13 @@ Matcher coverage depends on the host runtime emitting hook events for the tool i
 Post-write hook failures are deny-by-default and redacted. If an artifact disappears, becomes unreadable, is replaced between `stat` and read, or a referenced handoff artifact cannot be hashed, the hook reports a controlled validation failure instead of a Python traceback. `doctor` is only an install smoke test, but its failures include spawn status, signal/error, and bounded stdout/stderr snippets to make hook command problems diagnosable.
 
 *   [clean-room-hook.py](../hooks/clean-room-hook.py): The main safe/strict dispatch wrapper for the policy checks.
-*   [agent3-verification-runner.py](../hooks/agent3-verification-runner.py): Runs Agent 3 argv-array verification commands with `shell=False`, a small allowlist, sanitized env, bounded output, timeout, and root traversal checks.
+*   [agent3-verification-runner.py](../hooks/agent3-verification-runner.py): Runs Agent 3 argv-array verification commands with `shell=False`, sanitized env, bounded output, timeout, root traversal checks, and a small allowlist covering npm, pnpm, yarn, bun, and deno test commands; pytest directly or through `python -m` / `python3 -m`; `cargo test`; `go test`; and `zig build test`.
 *   [require-clean-room-env.py](../hooks/require-clean-room-env.py): Fails closed if the required role and root environment variables are missing, if trust-domain roots overlap, or if clean, implementation, or contaminated artifact root names appear source-derived.
 *   [deny-clean-room-shell.py](../hooks/deny-clean-room-shell.py): Denies shell-style tool execution inside clean-room role sessions except installed Agent 3 verification-runner invocations under implementation roots.
 *   [deny-clean-source-read.py](../hooks/deny-clean-source-read.py): Enforces that clean roles and Agent 1.5 cannot read source roots or unapproved paths; clean roles may read implementation roots, and source-denied roles are denied direct `preflight-goal.json` reads. Agent 1.5 is also denied clean roots, implementation roots, and direct `source-index.json` reads.
 *   [deny-contaminated-clean-write.py](../hooks/deny-contaminated-clean-write.py): Enforces role write roots. Agent 2 writes clean artifacts only, Agent 3 writes implementation files and clean reports, and contaminated roles write only to `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
 *   [check-artifact-leakage.py](../hooks/check-artifact-leakage.py): Scans clean artifacts and Agent 1.5 staged contaminated artifacts for high-risk leakage markers, source-like identifiers, and private identifier denylist terms. The private identifier denylist (loaded via `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST`) is subject to hard limits to protect hook execution performance: a maximum of 1,000,000 bytes per file, 20,000 total terms, and 512 characters per individual term.
-*   [validate-json-schema.py](../hooks/validate-json-schema.py): Verifies JSON syntax and structural conformance against schemas under `CLEAN_ROOM_SCHEMA_DIR`. Under clean roots, any unrecognized JSON files that do not conform to canonical schemas will trigger a failure unless they are explicitly registered in the path-separated `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` environment variable.
+*   [validate-json-schema.py](../hooks/validate-json-schema.py): Verifies JSON syntax and structural conformance against schemas under `CLEAN_ROOM_SCHEMA_DIR`, including controller-side `preflight-goal.schema.json` and `init-config.schema.json`. Under clean roots, any unrecognized JSON files that do not conform to canonical schemas will trigger a failure unless they are explicitly registered in the path-separated `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` environment variable.
 *   [validate-handoff-package.py](../hooks/validate-handoff-package.py): Verifies that handoff packages stay within clean roots, do not reference contaminated paths, `task-manifest.json`, `preflight-goal.json`, or `source-index.json`, and match declared `sha256` checksums.
 
 For detailed guidelines on the clean-room process, refer to:

package/docs/REFERENCE.md

@@ -150,6 +150,7 @@ By default, `init` creates:
 
 - `contaminated/`
 - `clean/`
+- `implementation/`
 - `quarantine/`
 - `clean-room-bootstrap.json`
 - `.clean-room/README.md` in the target repository
@@ -175,7 +176,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. |
+| `--bootstrap <path>` | Generated task root or `clean-room-bootstrap.json`; writes to the generated contaminated artifact root after scaffold validation and requires completed input roots to match the bootstrap. |
 | `--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

@@ -27,6 +27,7 @@ const BOOTSTRAP_REPO_STUB = '.clean-room/README.md';
 const BOOTSTRAP_DIRS = Object.freeze({
   contaminated: 'contaminated',
   clean: 'clean',
+  implementation: 'implementation',
   quarantine: 'quarantine',
 });
 
@@ -127,6 +128,7 @@ function resolveInitOptions(options, env = process.env, homeDir = os.homedir())
   const roots = {
     contaminated: path.join(outputRoot, 'contaminated'),
     clean: path.join(outputRoot, 'clean'),
+    implementation: path.join(outputRoot, 'implementation'),
     quarantine: path.join(outputRoot, 'quarantine'),
   };
 
@@ -158,6 +160,7 @@ function buildBootstrapMetadata(options) {
     roots: {
       contaminated_artifacts: options.roots.contaminated,
       clean_artifacts: options.roots.clean,
+      implementation_root: options.roots.implementation,
       quarantine: options.roots.quarantine,
     },
     note: 'Bootstrap metadata only. The clean-room skill creates active init-config.json, task-manifest.json, and clean-run-context.json artifacts.',
@@ -169,7 +172,7 @@ function renderRepoStub(targetProfile) {
 
 This repository has a clean-room bootstrap stub.
 
-Active clean-room run artifacts are stored outside this repository. 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. 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.
 
 Default target profile: \`${targetProfile}\`
 
@@ -282,6 +285,7 @@ function validateBootstrapScaffold(taskRoot) {
   const roots = {
     contaminated: path.join(outputRoot, BOOTSTRAP_DIRS.contaminated),
     clean: path.join(outputRoot, BOOTSTRAP_DIRS.clean),
+    implementation: path.join(outputRoot, BOOTSTRAP_DIRS.implementation),
     quarantine: path.join(outputRoot, BOOTSTRAP_DIRS.quarantine),
   };
   for (const [label, dirPath] of Object.entries(roots)) {
@@ -294,6 +298,7 @@ function validateBootstrapScaffold(taskRoot) {
     } else {
       assertMetadataPath(metadata.roots, 'contaminated_artifacts', roots.contaminated, errors);
       assertMetadataPath(metadata.roots, 'clean_artifacts', roots.clean, errors);
+      assertMetadataPath(metadata.roots, 'implementation_root', roots.implementation, errors);
       assertMetadataPath(metadata.roots, 'quarantine', roots.quarantine, errors);
     }
   }
@@ -373,6 +378,7 @@ function printInitResult(options) {
   console.log(`  output folder: ${options.outputRoot}`);
   console.log(`  contaminated artifacts: ${options.roots.contaminated}`);
   console.log(`  clean artifacts: ${options.roots.clean}`);
+  console.log(`  implementation root: ${options.roots.implementation}`);
   console.log(`  quarantine: ${options.roots.quarantine}`);
   console.log(`  metadata: ${options.metadataPath}`);
   console.log(`  repo stub: ${options.repoStubPath}`);

package/lib/doctor.cjs

@@ -187,6 +187,15 @@ function mkdirs(...dirs) {
   }
 }
 
+function schemaDirForLayout(layout) {
+  const manifest = readJsonFile(path.join(layout.targetRoot, 'clean-room-install-manifest.json'), null);
+  const pluginInstallPath = manifest?.claude_plugin?.install_path;
+  if (typeof pluginInstallPath === 'string' && pluginInstallPath) {
+    return path.join(path.resolve(pluginInstallPath), 'skills', 'clean-room', 'assets');
+  }
+  return path.join(layout.targetRoot, 'skills', 'clean-room', 'assets');
+}
+
 function smokeEnv(layout, tmpRoot, role) {
   const source = path.join(tmpRoot, 'source');
   const contaminated = path.join(tmpRoot, 'contaminated');
@@ -201,7 +210,7 @@ function smokeEnv(layout, tmpRoot, role) {
     CLEAN_ROOM_CLEAN_ROOTS: clean,
     CLEAN_ROOM_IMPLEMENTATION_ROOTS: implementation,
     CLEAN_ROOM_ALLOWED_READ_ROOTS: allowed,
-    CLEAN_ROOM_SCHEMA_DIR: path.join(layout.targetRoot, 'skills', 'clean-room', 'assets'),
+    CLEAN_ROOM_SCHEMA_DIR: schemaDirForLayout(layout),
   };
 }
 

package/lib/preflight.cjs

@@ -122,6 +122,31 @@ function resolveInputPath(value, cwd = process.cwd(), homeDir = os.homedir()) {
   return path.resolve(cwd, expanded);
 }
 
+function resolveGoalPath(value, cwd, homeDir) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return null;
+  }
+  return path.resolve(cwd, expandTilde(value, homeDir));
+}
+
+function applyBootstrapOutputPolicy(goal, bootstrap) {
+  goal.output_policy.artifact_base_root = bootstrap.outputRoot;
+  goal.output_policy.implementation_root = bootstrap.roots.implementation;
+}
+
+function validateBootstrapOutputPolicy(goal, bootstrap, cwd, homeDir) {
+  const errors = [];
+  const artifactBaseRoot = resolveGoalPath(goal?.output_policy?.artifact_base_root, cwd, homeDir);
+  const implementationRoot = resolveGoalPath(goal?.output_policy?.implementation_root, cwd, homeDir);
+  if (artifactBaseRoot !== bootstrap.outputRoot) {
+    errors.push(`output_policy.artifact_base_root must match bootstrap task root: ${bootstrap.outputRoot}`);
+  }
+  if (implementationRoot !== bootstrap.roots.implementation) {
+    errors.push(`output_policy.implementation_root must match bootstrap implementation root: ${bootstrap.roots.implementation}`);
+  }
+  return errors;
+}
+
 function buildTemplate(mode = 'attended') {
   if (mode !== 'attended') {
     throw new Error('preflight --template supports attended mode only');
@@ -467,6 +492,9 @@ function runPreflight(argv, context = {}) {
   let goal;
   if (parsed.template) {
     goal = buildTemplate(parsed.mode);
+    if (bootstrap) {
+      applyBootstrapOutputPolicy(goal, bootstrap);
+    }
   } else {
     const inputPath = resolveInputPath(parsed.input, cwd, homeDir);
     goal = readJsonFile(inputPath, null);
@@ -479,6 +507,12 @@ function runPreflight(argv, context = {}) {
   if (errors.length > 0) {
     throw new Error(`preflight goal is invalid:\n  ${errors.join('\n  ')}`);
   }
+  if (bootstrap && parsed.input) {
+    const bootstrapErrors = validateBootstrapOutputPolicy(goal, bootstrap, cwd, homeDir);
+    if (bootstrapErrors.length > 0) {
+      throw new Error(`preflight goal does not match bootstrap scaffold:\n  ${bootstrapErrors.join('\n  ')}`);
+    }
+  }
   writePreflightOutput(outputPath, goal, parsed);
   return { ...parsed, outputPath, goal };
 }

package/lib/runtime-layout.cjs

@@ -45,7 +45,7 @@ const RUNTIME_DEFS = Object.freeze({
     localDir: '.claude',
     hooks: true,
     artifacts: {
-      global: [STANDARD_SKILLS, CLAUDE_AGENTS, HOOKS],
+      global: [HOOKS],
       local: [
         {
           kind: 'commands',

package/package.json

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

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` 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`.
+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. 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`.
 
-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.
+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.
 
 ## Gather
 

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`, 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`.
+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/`, `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`.
 
 ## Required Contract
 
@@ -50,7 +50,7 @@ clean-room-skill preflight --input ./preflight-goal.json --output ~/Documents/Cl
 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. `--bootstrap` accepts either the generated task root or `clean-room-bootstrap.json` and writes to the generated contaminated artifact root after scaffold validation.
+`--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.
 
 ## Handoff