clean-room-skill 0.2.0 → 0.2.2

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.2.0",
+      "version": "0.2.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.2.0",
+  "version": "0.2.1",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/README.md

@@ -31,7 +31,19 @@ For the full boundary model, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). F
 
 Requires Node.js `>=22`.
 
-Preferred interactive install:
+You can either install the CLI globally on your system, or run the commands on-demand using `npx`.
+
+### Global Installation (npm)
+
+To install the `clean-room-skill` executable globally:
+
+```bash
+npm install -g clean-room-skill
+```
+
+### Direct On-Demand Execution (npx)
+
+Preferred interactive install/onboarding flow:
 
 ```bash
 npx clean-room-skill@latest
@@ -42,6 +54,7 @@ Non-interactive installs:
 ```bash
 npx clean-room-skill@latest --codex --global --yes
 npx clean-room-skill@latest --claude --global --yes
+npx clean-room-skill@latest --pi --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
@@ -77,9 +90,14 @@ Pi:
 ```bash
 pi install npm:clean-room-skill@latest
 pi install https://github.com/whit3rabbit/clean-room-skill
+npx clean-room-skill@latest --pi --global --yes
 ```
 
-Pi loads bundled skills as `/skill:<name>`, for example `/skill:clean-room`. Pi package install is skill compatibility only; it does not register clean-room hooks. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
+Pi-native package install is preferred. This package declares `pi.skills: ["./skills"]`, so `pi install npm:clean-room-skill@latest` lets Pi discover the bundled `SKILL.md` entry points directly. Use the `npx ... --pi` installer only when you want this repo's compatibility installer to manage the same files alongside other runtimes. Global Pi compatibility installs target `~/.pi/agent`; local installs target `.pi`.
+
+Both Pi install paths load bundled skills as `/skill:<name>`, for example `/skill:clean-room`. Pi installs do not currently register clean-room hooks. Installer-managed Pi layouts copy the hook scripts to `hooks/clean-room/` for inspection and future bridge work, but those files are not active enforcement in Pi.
+
+Pi hook enforcement would need a Pi extension, not a `settings.json` edit. Pi extensions can subscribe to tool events such as `tool_call` and `tool_result`, block or mutate tool calls, and are declared with `pi.extensions` in `package.json`; see the [Pi extension docs](https://pi.dev/docs/latest/extensions). This package does not ship that extension yet, so clean-room safety in Pi still depends on role separation, path isolation, schema validation, and any supported hook runtime used for enforcement.
 
 ## How To Run
 

package/agents/clean-polish-reviewer.md

@@ -15,7 +15,7 @@ Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMP
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-polish-reviewer`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, and `CLEAN_ROOM_SCHEMA_DIR`. Treat missing environment as a stop condition.
 
-This default profile has no shell-style tools. If final verification or commit is required, use an isolated polish profile where strict hooks are installed, `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1` is intentional, and the only allowed terminal command invokes the installed `agent4-polish-runner.py` from an implementation root. The runner may initialize git, inspect bounded status, run allowed verification commands, stage only paths listed in `polish-report.json`, and create one local commit. Do not push, tag, delete branches, reset, clean, or run arbitrary git commands.
+This default profile has no shell-style tools. If final verification or commit is required, use an isolated polish profile where strict hooks are installed, `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1` is intentional, and the only allowed terminal command invokes the installed `agent4-polish-runner.py` from an implementation root. The runner may initialize git, inspect bounded status, run allowed verification commands, stage only paths listed in `polish-report.json` `git.include_paths`, and create one local commit. Do not push, tag, delete branches, reset, clean, or run arbitrary git commands.
 
 ## Required Handoff Inputs
 
@@ -37,8 +37,10 @@ Responsibilities:
 - Update implementation-root `.gitignore` only for real generated outputs, dependency folders, local caches, or build/test artifacts relevant to the clean implementation stack.
 - Do not add speculative ignores, speculative docs, broad refactors, new dependencies, or new behavior.
 - Re-run relevant verification through `agent4-polish-runner.py` only when shell verification is enabled for this role.
-- Record findings, changed relative paths, verification results, residual risks, git status, commit message, commit hash/status, and abstract delta tickets in `polish-report.json`.
-- Mark `final_status` as `passed` only when high/blocker security, correctness, exception, resource, race, leakage, and verification findings are resolved and the constrained local commit succeeded.
+- Record findings, Agent 4 changed relative paths, verification results, residual risks, git status, commit message, commit hash/status, and abstract delta tickets in `polish-report.json`.
+- Set `git.include_paths` to the union of terminal `implementation-report.json` `changed_paths` and Agent 4 `polish-report.json` `changed_paths`; do not include unreported dirty files.
+- When the controller must create the commit, write a pre-commit report with `final_status: "blocked"`, `git.commit_required: true`, and `git.commit_status: "not-run"`.
+- Mark `final_status` as `passed` only when high/blocker security, correctness, exception, resource, race, leakage, and verification findings are resolved and either the constrained local commit succeeded or clean-run-context explicitly disables Agent 4 commits with `git.commit_status: "not-needed"`.
 - Convert major behavior gaps or scope expansion into abstract delta tickets instead of implementing new scope.
 
 If contamination is found, mark `polish-report.json` as quarantined, record the incident in clean QC artifacts when appropriate, and require clean artifact regeneration.

package/docs/ARCHITECTURE.md

@@ -241,7 +241,7 @@ The architecture delegates work across six distinct custom role agents to enforc
     *   Updates `.gitignore` only for real generated outputs, dependencies, caches, or build/test artifacts.
     *   Writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`.
     *   Uses `agent4-polish-runner.py` only with `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd under implementation roots, and strict hooks.
-    *   May initialize git and create one local commit containing only paths listed in `polish-report.json`; it must not push, tag, reset, clean, or delete branches.
+    *   May initialize git and create one local commit containing only paths listed in `polish-report.json` `git.include_paths`; that list must include terminal Agent 3 implementation changes plus Agent 4 polish changes. It must not push, tag, reset, clean, or delete branches.
 
 ### Nested Controller Loop
 

package/docs/HOOKS.md

@@ -15,6 +15,7 @@ The installer copies the Python hook files for every supported runtime layout. R
 | Antigravity | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Gemini CLI | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | OpenCode | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/plugins/clean-room.ts` |
+| Pi | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Kilo | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Cursor | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | GitHub Copilot | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |

package/docs/REFERENCE.md

@@ -21,6 +21,7 @@ Runtime flags:
 | `--antigravity` | Antigravity |
 | `--gemini` | Gemini CLI |
 | `--opencode` | OpenCode |
+| `--pi` | Pi |
 | `--kilo` | Kilo |
 | `--cursor` | Cursor |
 | `--copilot` | GitHub Copilot |
@@ -70,6 +71,7 @@ Layout-only or experimental:
 
 - Antigravity
 - Gemini CLI
+- Pi
 - Kilo
 - Cursor
 - GitHub Copilot
@@ -82,7 +84,7 @@ Layout-only or experimental:
 
 Layout-only installs write files to expected runtime locations, but this repository does not verify that those hosts load the files or emit all hook events needed for clean-room enforcement. OpenCode installs are verified through a generated local plugin bridge at `plugins/clean-room.ts`; `doctor` verifies that bridge and the Python guardrails, not every OpenCode tool surface.
 
-### Pi Package Compatibility
+### Pi Compatibility
 
 Pi can install this package and load the bundled skills from the package metadata:
 
@@ -91,7 +93,13 @@ pi install npm:clean-room-skill@latest
 pi install https://github.com/whit3rabbit/clean-room-skill
 ```
 
-Pi invokes skills as `/skill:<name>`. Use `/skill:init` for the setup pass, `/skill:clean-room` for the startup wizard, `/skill:attended` for attended controller mode, and `/skill:unattended` for bounded unattended mode. Pi support is package compatibility only: it does not add a `--pi` installer target, does not participate in `--all`, and does not register clean-room hooks. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
+Pi-native package install is preferred. The installer also supports a layout target:
+
+```bash
+npx clean-room-skill@latest --pi --global --yes
+```
+
+Pi invokes skills as `/skill:<name>`. Use `/skill:init` for the setup pass, `/skill:clean-room` for the startup wizard, `/skill:attended` for attended controller mode, and `/skill:unattended` for bounded unattended mode. Pi installs do not register clean-room hooks; installer-managed Pi layouts copy hook scripts only. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
 
 Global install roots:
 
@@ -102,6 +110,7 @@ Global install roots:
 | Antigravity | `ANTIGRAVITY_PLUGIN_DIR`, `ANTIGRAVITY_CLI_PLUGIN_DIR`, `ANTIGRAVITY_CONFIG_DIR/plugins/clean-room`, or `~/.gemini/antigravity-cli/plugins/clean-room` |
 | Gemini CLI | `GEMINI_CONFIG_DIR` or `~/.gemini` |
 | OpenCode | `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG`, `XDG_CONFIG_HOME/opencode`, or `~/.config/opencode` |
+| Pi | `~/.pi/agent` |
 | Kilo | `KILO_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME/kilo`, or `~/.config/kilo` |
 | Cursor | `CURSOR_CONFIG_DIR` or `~/.cursor` |
 | GitHub Copilot | `COPILOT_CONFIG_DIR` or `~/.copilot` |
@@ -112,7 +121,7 @@ Global install roots:
 | Hermes Agent | `HERMES_HOME` or `~/.hermes` |
 | CodeBuddy | `CODEBUDDY_CONFIG_DIR` or `~/.codebuddy` |
 
-Local installs use each runtime's project config directory. Antigravity local installs write `.agents/plugins/clean-room/`.
+Local installs use each runtime's project config directory. Pi local installs write `.pi/`. Antigravity local installs write `.agents/plugins/clean-room/`.
 
 ## Agent Metadata Compatibility
 

package/hooks/check-artifact-leakage.py

@@ -83,6 +83,7 @@ DENYLIST_ONLY_JSON_STRING_KEYS = {
     "expected_artifacts",
     "implementation_root_ref",
     "implementation_root_refs",
+    "include_paths",
     "incident_id",
     "manifest_id",
     "native_artifacts",

package/lib/bootstrap.cjs

@@ -410,8 +410,9 @@ function printInitResult(options) {
   console.log('    uninstall runtime install: npx clean-room-skill@latest --claude --global --uninstall --yes');
   console.log('  Pi:');
   console.log('    install package skills: pi install npm:clean-room-skill@latest');
+  console.log('    installer compatibility: npx clean-room-skill@latest --pi --global --yes');
   console.log('    start in Pi: /skill:init, then /skill:clean-room or /skill:attended');
-  console.log('    Pi package install does not register clean-room hooks');
+  console.log('    Pi installs do not register clean-room hooks');
   console.log('  strict hooks are only for dedicated clean-room Codex, Claude, or OpenCode homes');
 }
 

package/lib/install-options.cjs

@@ -94,6 +94,7 @@ Runtime:
   --antigravity        Install for Antigravity
   --gemini             Install for Gemini CLI
   --opencode           Install for OpenCode
+  --pi                 Install for Pi
   --kilo               Install for Kilo
   --cursor             Install for Cursor
   --copilot            Install for GitHub Copilot

package/lib/run-claude-agent-runtime.cjs

@@ -6,6 +6,7 @@ const { assertClaudeAgentsAvailable, defaultClaudeConfigDir } = require('./claud
 const { resolveClaudeExecutable } = require('./install-claude-plugin.cjs');
 const {
   MANAGER_PREPARE_PHASE,
+  POLISH_PHASE,
   REQUIRED_COVERAGE_PHASE,
   ROLE_BY_PHASE,
 } = require('./run-constants.cjs');
@@ -46,6 +47,7 @@ function claudeStages(roots, executable, env, pluginArgs) {
     claudeStage('sanitize-handoff', contaminatedCwd, executable, env, pluginArgs),
     claudeStage('clean-plan', cleanCwd, executable, env, pluginArgs),
     claudeStage('clean-implement-qc', implementationCwd, executable, env, pluginArgs),
+    claudeStage(POLISH_PHASE, implementationCwd, executable, env, pluginArgs),
     claudeStage(REQUIRED_COVERAGE_PHASE, contaminatedCwd, executable, env, pluginArgs),
   ];
 }

package/lib/run-controller.cjs

@@ -37,6 +37,7 @@ const {
   snapshotsEqual,
   validateImplementationArtifactPlacement,
 } = require('./run-progress.cjs');
+const { finalizeAgent4PolishCommit } = require('./run-polish-commit.cjs');
 const {
   defaultSchemaDir,
   resolvePath,
@@ -135,6 +136,14 @@ function shouldContinueAfterUnitComplete(manifest, coverageLedger) {
   return Boolean(selectUnit(manifest, coverageLedger));
 }
 
+function markStageFailed(stageResult, error) {
+  stageResult.status = 'failed';
+  const message = error?.message || String(error);
+  stageResult.stderr = stageResult.stderr
+    ? `${stageResult.stderr}\n${message}`
+    : message;
+}
+
 async function runCleanRoom(options, context = {}) {
   if (options.help) {
     printRunHelp();
@@ -256,6 +265,18 @@ async function runCleanRoom(options, context = {}) {
         if (stage.phase === REQUIRED_COVERAGE_PHASE && stageResult.status === 'passed') {
           coveragePhaseRan = true;
         }
+        if (stage.phase === POLISH_PHASE && stageResult.status === 'passed') {
+          try {
+            const commitResult = finalizeAgent4PolishCommit(options.python, roots, currentManifest, selected);
+            stageResult.agent4_commit = commitResult;
+            const afterCommit = artifactSnapshot(taskManifestPath, roots);
+            validateImplementationArtifactPlacement(roots);
+            validateArtifacts(options.python, taskManifestPath, roots, changedSnapshotPaths(afterStage, afterCommit));
+            validateCleanRunContextReferences(options.python, roots);
+          } catch (err) {
+            markStageFailed(stageResult, err);
+          }
+        }
         if (stageResult.status !== 'passed') {
           failedStage = stageResult;
           break;

package/lib/run-polish-commit.cjs

@@ -0,0 +1,259 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const {
+  readJsonFile,
+  writeJsonFile,
+} = require('./fs-utils.cjs');
+const {
+  DEFAULT_TIMEOUT_MS,
+  MAX_OUTPUT_BYTES,
+  POLISH_REPORT_NAME,
+} = require('./run-constants.cjs');
+const {
+  readCleanCompletionArtifact,
+  readCleanRunContext,
+} = require('./run-clean-artifacts.cjs');
+const {
+  envFromAllowlist,
+  hookPath,
+} = require('./run-roots.cjs');
+
+const COMMIT_HASH_RE = /^[a-fA-F0-9]{40,64}$/;
+
+function normalizeCommitPath(rawPath) {
+  if (typeof rawPath !== 'string' || rawPath.trim() === '') {
+    throw new Error('polish commit paths must be non-empty strings');
+  }
+  const normalized = rawPath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/').replace(/\/$/, '');
+  if (
+    normalized === '' ||
+    normalized.startsWith('/') ||
+    normalized.startsWith('~') ||
+    /^[A-Za-z]:/.test(normalized)
+  ) {
+    throw new Error(`polish commit path must be relative: ${rawPath}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.includes('..') || parts.includes('.git')) {
+    throw new Error(`polish commit path must not contain '..' or '.git': ${rawPath}`);
+  }
+  return normalized;
+}
+
+function changedPathSet(entries, options = {}) {
+  const paths = new Set();
+  for (const entry of entries || []) {
+    if (!entry || typeof entry !== 'object') continue;
+    if (options.skipUnchanged && entry.action === 'unchanged') continue;
+    paths.add(normalizeCommitPath(entry.path));
+  }
+  return paths;
+}
+
+function sortedPathSet(paths) {
+  return [...paths].sort((left, right) => left.localeCompare(right));
+}
+
+function expectedPolishCommitPaths(implementationReport, polishReport) {
+  return sortedPathSet(new Set([
+    ...changedPathSet(implementationReport?.changed_paths),
+    ...changedPathSet(polishReport?.changed_paths, { skipUnchanged: true }),
+  ]));
+}
+
+function polishIncludePaths(polishReport) {
+  return sortedPathSet(new Set((polishReport?.git?.include_paths || []).map((item) => normalizeCommitPath(item))));
+}
+
+function diffPaths(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((item) => !rightSet.has(item));
+}
+
+function polishCommitPathGap(implementationReport, polishReport) {
+  const expected = expectedPolishCommitPaths(implementationReport, polishReport);
+  const included = polishIncludePaths(polishReport);
+  const missing = diffPaths(expected, included);
+  if (missing.length > 0) {
+    return `Final clean polish commit is missing changed implementation path: ${missing[0]}`;
+  }
+  const unexpected = diffPaths(included, expected);
+  if (unexpected.length > 0) {
+    return `Final clean polish commit includes an unreported implementation path: ${unexpected[0]}`;
+  }
+  return null;
+}
+
+function polishCommitCompletionGap(implementationReport, polishReport) {
+  if (!polishReport) return null;
+  const git = polishReport.git || {};
+  if (git.commit_required === true) {
+    if (git.commit_status !== 'committed') {
+      return 'Final clean polish commit has not completed.';
+    }
+    if (typeof git.commit_hash !== 'string' || !COMMIT_HASH_RE.test(git.commit_hash)) {
+      return 'Final clean polish commit hash is missing.';
+    }
+    return polishCommitPathGap(implementationReport, polishReport);
+  }
+  if (git.commit_required === false) {
+    if (git.commit_status !== 'not-needed') {
+      return 'Final clean polish commit status does not match commit_required=false.';
+    }
+    if (git.commit_hash !== null) {
+      return 'Final clean polish commit hash must be null when commit_required=false.';
+    }
+  }
+  return null;
+}
+
+function unresolvedPolishItems(polishReport) {
+  const unresolvedFinding = (polishReport.findings || []).find((item) => item?.status !== 'resolved');
+  if (unresolvedFinding) {
+    return 'polish-report has unresolved findings';
+  }
+  const unresolvedTicket = (polishReport.abstract_delta_tickets || []).find((item) => item?.status !== 'resolved');
+  if (unresolvedTicket) {
+    return 'polish-report has unresolved abstract delta tickets';
+  }
+  const unpassedVerification = (polishReport.verification_results || []).find((item) => item?.status !== 'passed');
+  if (unpassedVerification) {
+    return 'polish-report has verification results that did not pass';
+  }
+  return null;
+}
+
+function boundedOutput(value) {
+  const text = String(value || '');
+  if (Buffer.byteLength(text, 'utf8') <= 4096) {
+    return text;
+  }
+  return `${text.slice(0, 4096)}\n[truncated]`;
+}
+
+function runnerEnv(roots, manifest, selectedUnit) {
+  return {
+    ...envFromAllowlist(),
+    CLEAN_ROOM_ROLE: 'clean-polish-reviewer',
+    CLEAN_ROOM_ALLOW_AGENT4_SHELL: '1',
+    CLEAN_ROOM_SOURCE_ROOTS: roots.sourceRoots.join(path.delimiter),
+    CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS: roots.contaminatedRoot,
+    CLEAN_ROOM_CLEAN_ROOTS: roots.cleanRoot,
+    CLEAN_ROOM_IMPLEMENTATION_ROOTS: roots.implementationRoots.join(path.delimiter),
+    CLEAN_ROOM_ALLOWED_READ_ROOTS: roots.allowedReadRoots.join(path.delimiter),
+    CLEAN_ROOM_SCHEMA_DIR: roots.schemaDir,
+    CLEAN_ROOM_SELECTED_UNIT_ID: selectedUnit.unit_id,
+    CLEAN_ROOM_SPEC_SLICE_REF: manifest.loop_context.spec_slice_ref,
+  };
+}
+
+function parseRunnerOutput(result) {
+  if (result.error) {
+    throw new Error(`Agent 4 polish commit runner failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const output = boundedOutput(result.stderr || result.stdout);
+    throw new Error(`Agent 4 polish commit runner failed: ${output}`);
+  }
+  const parsed = JSON.parse(result.stdout || '{}');
+  if (parsed?.commit?.commit_status !== 'committed' || typeof parsed.commit.commit_hash !== 'string') {
+    throw new Error('Agent 4 polish commit runner did not report a committed result');
+  }
+  return parsed.commit;
+}
+
+function updatePolishReportAfterCommit(polishReportPath, commit) {
+  const polishReport = readJsonFile(polishReportPath, null);
+  const priorStatus = polishReport.git?.repository_status;
+  polishReport.git = {
+    ...polishReport.git,
+    repository_status: priorStatus === 'existing' ? 'existing' : 'initialized',
+    commit_required: true,
+    commit_status: 'committed',
+    include_paths: commit.staged_paths || polishReport.git.include_paths,
+    commit_hash: commit.commit_hash,
+    status_summary: 'Committed listed implementation-root paths only.',
+  };
+  polishReport.final_status = 'passed';
+  writeJsonFile(polishReportPath, polishReport);
+  return polishReport;
+}
+
+function finalizeAgent4PolishCommit(python, roots, manifest, selectedUnit) {
+  const context = readCleanRunContext(roots);
+  const policy = context?.implementation?.polish_commit || null;
+  const polishReportPath = path.join(roots.cleanRoot, POLISH_REPORT_NAME);
+  if (!fs.existsSync(polishReportPath)) {
+    return { status: 'not-needed' };
+  }
+  const polishReport = readJsonFile(polishReportPath, null);
+  const git = polishReport.git || {};
+
+  if (git.commit_required !== true) {
+    if (git.commit_required !== false) {
+      throw new Error('polish-report git.commit_required must be true or false');
+    }
+    if (policy?.git_policy !== 'disabled') {
+      throw new Error('polish-report sets commit_required=false, but clean-run-context does not disable Agent 4 commits');
+    }
+    const commitGap = polishCommitCompletionGap(null, polishReport);
+    if (commitGap) {
+      throw new Error(commitGap);
+    }
+    return { status: 'not-needed' };
+  }
+  const { artifact: implementationReport } = readCleanCompletionArtifact(
+    roots,
+    'implementation_report',
+    'implementation-report.json',
+    'clean-run-context implementation_report'
+  );
+  if (!implementationReport) {
+    throw new Error('Agent 4 commit requires terminal implementation-report.json');
+  }
+  const pathGap = polishCommitPathGap(implementationReport, polishReport);
+  if (pathGap) {
+    throw new Error(pathGap);
+  }
+  if (git.commit_status === 'committed') {
+    return { status: 'already-committed' };
+  }
+  if (git.commit_status !== 'not-run') {
+    throw new Error(`polish-report git.commit_status must be not-run before controller commit, got ${git.commit_status}`);
+  }
+  if (policy?.git_policy !== 'local-init-and-commit-only') {
+    throw new Error('clean-run-context does not allow Agent 4 local init-and-commit');
+  }
+  if (policy.agent4_shell_allowed !== true || policy.cwd_policy !== 'implementation-root') {
+    throw new Error('clean-run-context Agent 4 commit policy does not allow the bounded polish runner');
+  }
+  if (polishReport.final_status !== 'blocked') {
+    throw new Error('pre-commit polish-report final_status must be blocked');
+  }
+  const unresolved = unresolvedPolishItems(polishReport);
+  if (unresolved) {
+    throw new Error(unresolved);
+  }
+
+  const result = spawnSync(python, [hookPath('agent4-polish-runner.py'), '--report', polishReportPath, '--commit'], {
+    cwd: roots.implementationRoots[0],
+    env: runnerEnv(roots, manifest, selectedUnit),
+    encoding: 'utf8',
+    shell: false,
+    timeout: DEFAULT_TIMEOUT_MS,
+    maxBuffer: MAX_OUTPUT_BYTES,
+  });
+  const commit = parseRunnerOutput(result);
+  updatePolishReportAfterCommit(polishReportPath, commit);
+  return { status: 'committed', commit_hash: commit.commit_hash };
+}
+
+module.exports = {
+  expectedPolishCommitPaths,
+  finalizeAgent4PolishCommit,
+  polishCommitCompletionGap,
+};

package/lib/run-results.cjs

@@ -28,6 +28,10 @@ const {
   skeletonAreaMap,
   validatePathsOwnedByAreas,
 } = require('./run-clean-artifacts.cjs');
+const {
+  expectedPolishCommitPaths,
+  polishCommitCompletionGap,
+} = require('./run-polish-commit.cjs');
 const {
   approvedUnitIds,
   coverageMap,
@@ -94,7 +98,7 @@ function validateImplementationReportArchitecture(report, plan, skeleton) {
   }
 }
 
-function implementationReportArchitectureTickets(roots, observedChangedPaths = null) {
+function implementationReportArchitectureTickets(roots, observedChangedPaths = null, polish = null) {
   const { artifact: report } = readCleanCompletionArtifact(roots, 'implementation_report', 'implementation-report.json', 'clean-run-context implementation_report');
   if (!report || !Array.isArray(report.changed_paths)) {
     return [];
@@ -119,7 +123,10 @@ function implementationReportArchitectureTickets(roots, observedChangedPaths = n
     }
   }
   if (Array.isArray(observedChangedPaths)) {
-    const normalizedReported = [...new Set(report.changed_paths.map((entry) => entry?.path).filter((value) => typeof value === 'string' && value.trim() !== ''))].sort();
+    const reportedPaths = polish
+      ? expectedPolishCommitPaths(report, polish)
+      : report.changed_paths.map((entry) => entry?.path).filter((value) => typeof value === 'string' && value.trim() !== '');
+    const normalizedReported = [...new Set(reportedPaths)].sort();
     const normalizedObserved = [...new Set(observedChangedPaths.filter((value) => typeof value === 'string' && value.trim() !== ''))].sort();
     if (normalizedReported.length !== normalizedObserved.length || normalizedReported.some((value, index) => value !== normalizedObserved[index])) {
       return [architectureDeltaTicket('Implementation report changed paths did not match observed implementation-root file changes. Re-run clean implementation with accurate changed_paths.')];
@@ -164,10 +171,10 @@ function completionQualityTickets(qc) {
   return tickets;
 }
 
-function architectureDeltaTickets(roots, qc, observedChangedPaths = null) {
+function architectureDeltaTickets(roots, qc, observedChangedPaths = null, polish = null) {
   return [
     ...qcArchitectureTickets(qc),
-    ...implementationReportArchitectureTickets(roots, observedChangedPaths),
+    ...implementationReportArchitectureTickets(roots, observedChangedPaths, polish),
   ];
 }
 
@@ -181,7 +188,7 @@ function polishDeltaTicket(summary) {
   };
 }
 
-function polishReviewTickets(polish, polishRequired) {
+function polishReviewTickets(polish, polishRequired, implementationReport = null) {
   if (!polish) {
     return polishRequired
       ? [polishDeltaTicket('The configured clean polish review stage did not produce polish-report.json.')]
@@ -195,12 +202,16 @@ function polishReviewTickets(polish, polishRequired) {
   } else if (polish.final_status === 'passed-with-gaps') {
     tickets.push(polishDeltaTicket('Final clean polish review passed with unresolved gaps.'));
   }
+  const commitGap = polishCommitCompletionGap(implementationReport, polish);
+  if (commitGap) {
+    tickets.push(polishDeltaTicket(commitGap));
+  }
   return tickets;
 }
 
-function polishBlocksCompletion(polish, polishRequired) {
+function polishBlocksCompletion(polish, polishRequired, implementationReport = null) {
   if (!polish) return polishRequired;
-  return polish.final_status !== 'passed';
+  return polish.final_status !== 'passed' || Boolean(polishCommitCompletionGap(implementationReport, polish));
 }
 
 function validateTerminalCompletionArtifacts(roots) {
@@ -261,9 +272,9 @@ function inferTerminalResult(manifest, roots, selectedUnit, options = {}) {
     polish,
     coverage,
     { abstract_delta_tickets: behaviorSpecOpenQuestionTickets(roots) },
-    { abstract_delta_tickets: architectureDeltaTickets(roots, qc, options.observedChangedPaths || null) },
+    { abstract_delta_tickets: architectureDeltaTickets(roots, qc, options.observedChangedPaths || null, polish) },
     { abstract_delta_tickets: completionQualityTickets(qc) },
-    { abstract_delta_tickets: polishReviewTickets(polish, polishRequired) }
+    { abstract_delta_tickets: polishReviewTickets(polish, polishRequired, report) }
   );
 
   if (
@@ -280,7 +291,7 @@ function inferTerminalResult(manifest, roots, selectedUnit, options = {}) {
   if (report?.final_status === 'blocked' || qc?.final_status === 'blocked' || polish?.final_status === 'blocked' || selectedUnit.status === 'blocked') {
     return buildResult(manifest, 'spec-slice-blocked', coverageState(state, qc), report, qc, tickets, polish);
   }
-  if (polishBlocksCompletion(polish, polishRequired)) {
+  if (polishBlocksCompletion(polish, polishRequired, report)) {
     return null;
   }
   if (state === 'covered' || (qc?.coverage_status === 'complete' && qc?.final_status === 'passed')) {
@@ -302,7 +313,8 @@ function completeResultOrSpecDelta(manifest, roots, coverageLedger, coverageStat
     coverageLedger,
     { abstract_delta_tickets: behaviorSpecOpenQuestionTickets(roots) },
     { abstract_delta_tickets: architectureDeltaTickets(roots, qc) },
-    { abstract_delta_tickets: completionQualityTickets(qc) }
+    { abstract_delta_tickets: completionQualityTickets(qc) },
+    { abstract_delta_tickets: polishReviewTickets(polish, Boolean(polish), report) }
   );
   if (tickets.some((ticket) => ticket.status !== 'resolved')) {
     return buildResult(manifest, 'spec-delta-required', coverageStateValue, null, null, tickets);

package/lib/runtime-layout.cjs

@@ -9,6 +9,7 @@ const RUNTIMES = Object.freeze([
   'antigravity',
   'gemini',
   'opencode',
+  'pi',
   'kilo',
   'cursor',
   'copilot',
@@ -104,6 +105,12 @@ const RUNTIME_DEFS = Object.freeze({
       HOOKS,
     ],
   },
+  pi: {
+    globalDefault: ['.pi', 'agent'],
+    localDir: '.pi',
+    hooks: false,
+    artifacts: [STANDARD_SKILLS, HOOKS],
+  },
   kilo: {
     globalResolver: resolveKiloGlobalRoot,
     localDir: '.kilo',

package/package.json

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

package/plugin.json

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

package/skills/clean-room/SKILL.md

@@ -34,7 +34,7 @@ Use these roles conceptually. If the host supports subagents, map each role to a
 - Agent 1.5 / contaminated handoff sanitizer: works in a fresh source-denied contaminated context, reads only Agent 0's neutral brief plus assigned draft artifacts, scrubs identifying material, and approves or quarantines handoff candidates.
 - Agent 2 / clean architect/planner: starts from the clean workspace, reads `clean-run-context.json`, approved clean handoff artifacts, the completed foundation spec, and the clean destination foundation under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`; then writes `CLEAN_ROOM_CLEAN_ROOTS/implementation-plan.json` with relative destination paths, tests, constraints, risks, and argv-array verification commands. It writes no code.
 - Agent 3 / clean implementer/verifier: starts in the clean domain, reads `implementation-plan.json` and clean artifacts, writes code and tests only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, writes reports under `CLEAN_ROOM_CLEAN_ROOTS`, records verification status, and emits exactly one terminal report for Agent 0 only after the assigned plan or task is complete, blocked, or quarantined. Run verification only through the installed Agent 3 verification runner; optional Docker or Podman verification must not mount source or contaminated artifact roots.
-- Agent 4 / clean polish reviewer: starts in the clean domain after Agent 3 terminal reports, reviews final code for security, comments/docs, exception handling, resource leaks, race conditions, missing tests, and repo hygiene, writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`, may update implementation-root `AGENTS.md` and `.gitignore`, and may create one local implementation-root commit only through the installed Agent 4 polish runner.
+- Agent 4 / clean polish reviewer: starts in the clean domain after Agent 3 terminal reports, reviews final code for security, comments/docs, exception handling, resource leaks, race conditions, missing tests, and repo hygiene, writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`, may update implementation-root `AGENTS.md` and `.gitignore`, and may create one local implementation-root commit only through the installed Agent 4 polish runner. The commit path list must cover terminal Agent 3 changed paths plus Agent 4 polish changed paths.
 
 ## Workflow
 
@@ -54,7 +54,7 @@ Optional AST/indexing helpers are detected before the controller loop through `s
 
 Controller mode defaults to `attended` when `task-manifest.json` has no `controller_policy`. The outer loop evolves specs and selects one approved spec slice. Code-development runs start with exactly one `unit_kind: "foundation"` unit named by `loop_context.foundation_unit_ref`; non-foundation behavior slices wait until that unit is covered. The inner clean-room loop completes the approved slice through sanitized handoff, implementation, QC, optional final polish review, and contaminated-side coverage verification, then returns `clean-room-result.json` to the outer loop. In `attended` mode, agent zero pauses for human review at scope gate, handoff, QC deltas, polish deltas, blocked units, and final coverage. In `unattended` mode, agent zero may run a bounded inner loop: reload durable artifacts for each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, start each role from fresh context with the required environment block, validate before advancing, and stop on any configured safety or ambiguity condition.
 
-In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` when possible. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
+In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available) when possible. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
 
 Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3/4 role sessions. Agent 3 terminal verification may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`, the command cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent3-verification-runner.py`. Agent 4 polish verification and commit may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent4-polish-runner.py`. Use `--hooks=strict` for dedicated Codex, Claude, or OpenCode clean-room homes so hooks fail closed if required environment is missing or shell tools are invoked outside the allowed runner boundaries. Safe hook installs are compatibility-only between runs; during init/onboarding, prepare the role environment block and pass it into every clean-room role session so safe hooks enforce during active work.
 
@@ -124,7 +124,7 @@ Default sequence:
 7. Clean handoff: move only Agent 1.5-approved structured artifacts plus `clean-run-context.json` to the clean workspace. Do not hand off the full `task-manifest.json`. For each role launch, Agent 0 writes a compact `role-session-brief.json` for that role and phase; the brief carries status, next action, allowed artifact refs with hashes, and forbidden inputs. It is not a replacement for durable artifacts.
 8. Clean planning: Agent 2 starts from the clean artifact root, reads `clean-run-context.json`, approved handoff artifacts, any existing `skeleton-manifest.json`, and the clean implementation foundation, then updates `skeleton-manifest.json` as the durable destination architecture map and produces `implementation-plan.json` with code hygiene policy. Use `implementation-plan.json` as the code-development work contract, and require every planned target/test path to be owned by a referenced architecture area.
 9. Clean implementation and QC: Agent 3 reads `implementation-plan.json`, writes code and tests only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, writes `implementation-report.json` under `CLEAN_ROOM_CLEAN_ROOTS`, maintains `CLEAN_ROOM_CLEAN_ROOTS/qc-report.json`, and loops without Agent 0 guidance until selected-slice work items are complete, blocked, or quarantined.
-10. Clean polish review: when configured, Agent 4 reviews final code, updates only implementation-root polish files such as `AGENTS.md` or `.gitignore` when needed, writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`, and commits only through `agent4-polish-runner.py`.
+10. Clean polish review: when configured, Agent 4 reviews final code, updates only implementation-root polish files such as `AGENTS.md` or `.gitignore` when needed, writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`, and commits only through `agent4-polish-runner.py`. If the controller finalizes the commit, Agent 4 records `git.commit_status: "not-run"` and `final_status: "blocked"` until the bounded runner records the real commit hash.
 11. Contaminated coverage verification: only after Agent 3 marks the report as terminal and any configured Agent 4 polish review passes may Agent 0 consume `implementation-report.json`, `qc-report.json`, `polish-report.json`, and `coverage-ledger.json`, compare against source coverage, and write `clean-room-result.json`. Exact-public-contract and behavior-compatible public-surface items must map item by item from behavior spec test coverage to implementation-plan `public_contract_refs`, terminal report completion, and coverage-ledger `public_surface_coverage`.
 12. Repeat clean planning, implementation, and polish only from updated durable artifacts, never by steering an in-progress Agent 2, Agent 3, or Agent 4 session.
 

package/skills/clean-room/assets/polish-report.schema.json

@@ -214,10 +214,21 @@
         "properties": {
           "final_status": {
             "const": "passed"
+          },
+          "git": {
+            "properties": {
+              "commit_required": {
+                "const": true
+              }
+            },
+            "required": [
+              "commit_required"
+            ]
           }
         },
         "required": [
-          "final_status"
+          "final_status",
+          "git"
         ]
       },
       "then": {
@@ -226,6 +237,78 @@
             "properties": {
               "commit_status": {
                 "const": "committed"
+              },
+              "commit_hash": {
+                "type": "string",
+                "pattern": "^[a-fA-F0-9]{40,64}$"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "final_status": {
+            "const": "passed"
+          },
+          "git": {
+            "properties": {
+              "commit_required": {
+                "const": false
+              }
+            },
+            "required": [
+              "commit_required"
+            ]
+          }
+        },
+        "required": [
+          "final_status",
+          "git"
+        ]
+      },
+      "then": {
+        "properties": {
+          "git": {
+            "properties": {
+              "commit_status": {
+                "const": "not-needed"
+              },
+              "commit_hash": {
+                "const": null
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "git": {
+            "properties": {
+              "commit_status": {
+                "const": "committed"
+              }
+            },
+            "required": [
+              "commit_status"
+            ]
+          }
+        },
+        "required": [
+          "git"
+        ]
+      },
+      "then": {
+        "properties": {
+          "git": {
+            "properties": {
+              "commit_hash": {
+                "type": "string",
+                "pattern": "^[a-fA-F0-9]{40,64}$"
               }
             }
           }

package/skills/clean-room/examples/minimal-spec-package/implementation-report.json

@@ -4,15 +4,32 @@
   "plan_ref": "implementation-plan.json",
   "implementer_role": "clean-qa-editor",
   "updated_at": "2024-01-01T00:00:00Z",
-  "implementation_status": "not-started",
+  "implementation_status": "complete",
   "agent0_reporting": {
-    "report_state": "internal-draft",
+    "report_state": "terminal-report",
     "terminal_report_target": "agent_0",
     "interim_updates_allowed": false
   },
-  "completed_work_items": [],
+  "completed_work_items": [
+    "work-example-flow"
+  ],
   "blocked_work_items": [],
-  "changed_paths": [],
+  "changed_paths": [
+    {
+      "path": "src/example-flow.js",
+      "kind": "code",
+      "work_item_ids": [
+        "work-example-flow"
+      ]
+    },
+    {
+      "path": "test/example-flow.test.js",
+      "kind": "test",
+      "work_item_ids": [
+        "work-example-flow"
+      ]
+    }
+  ],
   "verification_results": [
     {
       "command": [
@@ -20,11 +37,11 @@
         "test"
       ],
       "cwd": "CLEAN_ROOM_IMPLEMENTATION_ROOTS[0]",
-      "status": "not-run",
-      "output_summary": "Example report has not run verification."
+      "status": "passed",
+      "output_summary": "Example verification passed."
     }
   ],
   "findings": [],
   "abstract_delta_tickets": [],
-  "final_status": "partial"
+  "final_status": "complete"
 }

package/skills/clean-room/examples/minimal-spec-package/polish-report.json

@@ -41,6 +41,8 @@
     "commit_required": true,
     "commit_status": "committed",
     "include_paths": [
+      "src/example-flow.js",
+      "test/example-flow.test.js",
       "AGENTS.md",
       ".gitignore"
     ],

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

@@ -197,8 +197,10 @@ Clean polish reviewer:
 - Update implementation-root `AGENTS.md` with gotchas and build/test/dev commands discovered from clean files.
 - Update implementation-root `.gitignore` only for real generated outputs, dependencies, caches, or build/test artifacts.
 - Run verification and commit only through `agent4-polish-runner.py` with `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`.
-- Stage only paths listed in `polish-report.json` and create at most one local implementation-root commit.
+- Stage only paths listed in `polish-report.json` `git.include_paths` and create at most one local implementation-root commit.
+- Set `git.include_paths` to the union of terminal Agent 3 `implementation-report.json` `changed_paths` and Agent 4 `polish-report.json` `changed_paths`; leave unreported dirty files uncommitted.
 - Write `polish-report.json` with findings, changed paths, verification results, git status, commit hash/status, residual risks, and abstract delta tickets.
+- For controller-finalized commits, write a pre-commit `polish-report.json` with `final_status: "blocked"`, `git.commit_required: true`, and `git.commit_status: "not-run"`.
 - Do not report progress or ask Agent 0 for guidance while implementing. Mark `implementation-report.json` as terminal only after the selected slice work is complete, blocked, or quarantined.
 
 ## Workflow
@@ -284,7 +286,7 @@ Clean polish reviewer:
    - Start from a fresh role session brief when context management is enabled.
    - Agent 4 starts from the clean domain, reviews only clean implementation-root files and clean artifacts, and writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`.
    - Create or update implementation-root `AGENTS.md` and `.gitignore` only when the clean implementation actually needs them.
-   - Commit only through `agent4-polish-runner.py`, with no push, tag, reset, clean, branch deletion, or arbitrary git commands.
+   - Commit only through `agent4-polish-runner.py`, with `git.include_paths` covering terminal Agent 3 changed paths plus Agent 4 polish paths, and with no push, tag, reset, clean, branch deletion, or arbitrary git commands.
 13. Verify coverage:
    - Contaminated manager checks gaps against source behavior, discovered source tests, equal-output requirements, public contract compatibility, terminal implementation reports, and terminal polish reports when configured.
    - Reject completion when any required public-surface obligation is missing from behavior spec test coverage, implementation-plan `public_contract_refs`, terminal implementation completion, or coverage-ledger `public_surface_coverage`.

package/skills/clean-room/references/SPEC-SCHEMA.md

@@ -344,7 +344,7 @@ Do not include raw source excerpts, contaminated evidence, or source stack trace
 - residual risks and abstract delta tickets
 - final status
 
-Do not include source excerpts, contaminated evidence, source paths, private identifiers, raw diffs, or source-shaped pseudocode. A passing polish report requires the constrained local commit to have succeeded.
+Do not include source excerpts, contaminated evidence, source paths, private identifiers, raw diffs, or source-shaped pseudocode. A passing polish report with `git.commit_required: true` requires the constrained local commit to have succeeded and a real commit hash to be recorded. A passing report with `git.commit_required: false` is valid only when the clean-run-context commit policy is disabled and `git.commit_status` is `not-needed`.
 
 ## Clean-Room Result Content
 

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` may have pre-created neutral external folders and a clean-safe `.clean-room/README.md` stub in the target repository. The bootstrap task root must contain `contaminated/`, `clean/`, `implementation/`, and `quarantine/`. Treat that bootstrap output as convenience scaffolding only. It does not replace this skill's initialization workflow, and it must not be treated as an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
+The CLI command `clean-room-skill init` (or `npx clean-room-skill@latest init` if the binary is not available) may have pre-created neutral external folders and a clean-safe `.clean-room/README.md` stub in the target repository. The bootstrap 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/`, `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.
 

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/`, `implementation/`, `quarantine/`, and the target repo `.clean-room/README.md` must exist and agree. Treat that scaffold as convenience output only; it is not an active `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`.
+If the user provides output from CLI `clean-room-skill init` (or `npx clean-room-skill@latest init` if the binary is not available), check the generated bootstrap scaffold before creating or copying `preflight-goal.json`: `clean-room-bootstrap.json`, `contaminated/`, `clean/`, `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
 
@@ -46,7 +46,7 @@ Do not infer target language, license, dependency policy, exactness policy, outp
 
 ## CLI Helper
 
-Use the CLI only for template creation or validation/copying:
+Use the CLI (`clean-room-skill` if installed, or `npx clean-room-skill@latest` as fallback) only for template creation or validation/copying:
 
 ```bash
 clean-room-skill preflight --template --output ~/Documents/CleanRoom/task-xxxxxxxx/contaminated/preflight-goal.json

package/skills/refocus/SKILL.md

@@ -53,7 +53,7 @@ Emit missed-gate findings only:
 - Stale implementation report compared with latest implementation plan.
 - Controller policy not preserved.
 - Missing, invalid, or drifted preflight goal.
-- Noncanonical manifests, reports, ledgers, or manual result summaries used as completion evidence. Mark these `not verified` unless `clean-room-skill run --dry-run` succeeds against the canonical `task-manifest.json`.
+- Noncanonical manifests, reports, ledgers, or manual result summaries used as completion evidence. Mark these `not verified` unless `clean-room-skill run --dry-run` (or `npx clean-room-skill@latest run --dry-run` if the binary is not available) succeeds against the canonical `task-manifest.json`.
 - Missing public-surface inventory parity: required public commands, APIs, config keys, protocol entries, or user-visible behaviors listed in approved specs are not mapped through behavior spec tests, implementation-plan `public_contract_refs`, terminal implementation reports, and coverage-ledger `public_surface_coverage`.
 
 Do not suggest speculative improvements. Do not change source scope, target profile, public API, or implementation plan.

package/skills/resume-cr/SKILL.md

@@ -11,7 +11,7 @@ Resume an existing clean-room run from durable artifacts. Never use prior chat h
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` when the manifest records `loop_context` or unattended mode. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` and let the durable runner assign role agents. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
+If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available) and let the durable runner assign role agents. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
 
 ## Load Order
 

package/skills/unattended/SKILL.md

@@ -15,7 +15,7 @@ Use the canonical `clean-room` skill workflow and references in this plugin. Rea
 
 Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
-When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude`. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
+When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` (or `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` if the binary is not available). The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
 
 Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, and a finite `controller_policy.max_iterations`.