clean-room-skill 0.1.0 → 0.1.2

package/README.md

@@ -1,30 +1,30 @@
 # Clean Room
 
-Spec-first clean-room workflow for software to spec. 
+Clean-room workflow for turning authorized source analysis into clean specs and clean implementation code.
 
 This is a POC based on the ideas presented here: 
 
 https://malus.sh/blog.html
 
-This plugin packages the `clean-room`, `attended`, and `unattended` skills, Claude role agents, Codex role-agent templates, JSON schemas, examples, and hook guardrails for separating contaminated source analysis from clean behavioral specification work.
+This plugin packages the `clean-room`, `preflight`, `attended`, `unattended`, `resume`, `start-over`, and `refocus` skills, Claude role agents, Codex role-agent templates, JSON schemas, examples, and hook guardrails for separating contaminated source analysis from clean behavioral specification and clean implementation work.
 
 It is an engineering risk-reduction workflow. It is not legal advice and does not create a legal safe harbor.
 
 ## Use This For
 
-- Authorized source-to-spec migration planning.
+- Authorized source-to-implementation migration work.
 - Clean behavioral specifications for compatibility work.
-- Skeleton manifests, QC reports, open questions, and test plans.
-- Documented separation between source-reading roles and clean artifact roles.
+- Implementation plans, clean code changes, verification reports, QC reports, open questions, and test plans.
+- Documented separation between source-reading roles, clean planning roles, and clean implementation roles.
 
 ## Threat Model And Non-Goals
 
 This workflow protects against:
 
-- accidental source expression crossing into clean specs
+- accidental source expression crossing into clean specs or clean implementation code
 - clean agents reading contaminated roots
 - contaminated agents writing clean artifacts
-- clean or contaminated agents writing outside their role artifact roots
+- clean or contaminated agents writing outside their role artifact or implementation roots
 - unbounded unattended controller loops
 
 It does not protect against:
@@ -37,6 +37,16 @@ It does not protect against:
 
 ## Install
 
+### Installation Model
+
+The `clean-room-skill` npm package has two separate layers:
+
+*   **Agent/runtime install**: installs clean-room skills, agent prompts, and verification hooks *into* your local or global agent runtimes (e.g., Claude Code, Codex, or Cursor). This is the default command behavior.
+*   **Run bootstrap**: `clean-room-skill init` creates neutral external output folders and a clean-safe repo stub for a specific clean-room run. It does not install hooks, does not write active run artifacts, and does not replace the runtime skill workflow.
+
+*   **Global Installation (Recommended)**: Integrates the clean-room workflow globally into your agent configuration directories (e.g., `~/.claude/` or `~/.codex/`).
+*   **Local Installation**: Places the plugin directly inside your current repository's workspace (e.g., `.claude/` or `.codex/`).
+
 Preferred direct installer:
 
 ```bash
@@ -49,31 +59,178 @@ The installer prompts for runtime and scope when no flags are supplied. For non-
 npx clean-room-skill@latest --codex --global --yes
 npx clean-room-skill@latest --claude --global --yes
 npx clean-room-skill@latest --antigravity --global --yes
+npx clean-room-skill@latest --opencode --global --yes
+npx clean-room-skill@latest --cursor --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
-Supported runtime roots:
+Runtime support tiers:
+
+- Verified: Codex and Claude Code. These installs have tested skill, agent, hook registration, and hook payload behavior.
+- Layout-only / experimental: Antigravity, Gemini, OpenCode, Kilo, Cursor, GitHub Copilot, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, and CodeBuddy. The installer writes files to expected layout roots, but this repo does not verify that those hosts load the files or enforce clean-room behavior.
+
+Runtime install roots:
 
 - Codex global: `CODEX_HOME` or `~/.codex`
 - Claude Code global: `CLAUDE_CONFIG_DIR` or `~/.claude`
-- Antigravity global: `ANTIGRAVITY_PLUGIN_DIR` or `~/.gemini/config/plugins/clean-room-skill`
-
-Local installs are supported for Codex and Claude Code through `--local`. Antigravity local installs are rejected in v1.
+- Antigravity CLI global plugin: `ANTIGRAVITY_PLUGIN_DIR`, `ANTIGRAVITY_CLI_PLUGIN_DIR`, `ANTIGRAVITY_CONFIG_DIR/plugins/clean-room`, or `~/.gemini/antigravity-cli/plugins/clean-room`
+- Gemini global legacy/enterprise: `GEMINI_CONFIG_DIR` or `~/.gemini`
+- OpenCode global: `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG`, `XDG_CONFIG_HOME/opencode`, or `~/.config/opencode`
+- Kilo global: `KILO_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME/kilo`, or `~/.config/kilo`
+- Cursor global: `CURSOR_CONFIG_DIR` or `~/.cursor`
+- GitHub Copilot global: `COPILOT_CONFIG_DIR` or `~/.copilot`
+- Windsurf global: `WINDSURF_CONFIG_DIR` or `~/.codeium/windsurf`
+- Augment global: `AUGMENT_CONFIG_DIR` or `~/.augment`
+- Trae global: `TRAE_CONFIG_DIR` or `~/.trae`
+- Qwen Code global: `QWEN_CONFIG_DIR` or `~/.qwen`
+- Hermes Agent global: `HERMES_HOME` or `~/.hermes`
+- CodeBuddy global: `CODEBUDDY_CONFIG_DIR` or `~/.codebuddy`
+
+Local installs are available through `--local` using each runtime's project config directory. Antigravity local installs write `.agents/plugins/clean-room/`. Claude local, Gemini, **OpenCode, and Kilo** receive generated command wrappers (e.g. `clean-room-clean-room.md`, `clean-room-init.md`); native skill runtimes receive `SKILL.md` directories. Gemini CLI support is legacy/enterprise compatibility because Google is transitioning consumer Gemini CLI users to Antigravity CLI on June 18, 2026. Cline is not included because it has no verified clean-room skill or command layout.
 
 Hook modes:
 
-- `--hooks=safe`: default. Copies hooks and registers a wrapper that no-ops unless `CLEAN_ROOM_HOOK_ENFORCE=1` or clean-room environment variables are present.
+- `--hooks=safe`: default. Copies hooks and registers a wrapper that no-ops unless `CLEAN_ROOM_HOOK_ENFORCE=1` or clean-room environment variables are present. This is compatibility-only; use `--hooks=strict` for dedicated Codex or Claude clean-room homes.
 - `--hooks=copy-only` or `--no-hooks`: copies hook files but does not register Codex or Claude hook config.
-- `--hooks=strict`: registers fail-closed hooks for dedicated clean-room homes.
+- `--hooks=strict`: registers fail-closed hooks for dedicated clean-room homes. Strict mode is supported only for Codex and Claude Code because other runtime hook payloads are not verified. Antigravity receives hook scripts in the plugin directory, but the generated plugin manifest does not enable them until an Antigravity-specific hook payload adapter exists.
+
+### Installer CLI Reference
+
+Execute the installer via `npx` with the following parameters:
+
+```bash
+npx clean-room-skill@latest [runtimes] [scope] [options]
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `--claude` / `--codex` | Runtime | Selects the target agent runtime. (Supports `--all` for all runtimes) |
+| `--global` / `--local` | Scope | Installs to the global user home config or the local project directory. |
+| `--hooks=<mode>` | Option | Sets hook mode: `safe` (default, opt-in), `strict` (fail-closed), or `copy-only`. |
+| `--no-hooks` | Option | Alias for `--hooks=copy-only`. Copies scripts without registering hooks. |
+| `--config-dir <path>` | Option | Overrides the target root directory (only for single-runtime installs). |
+| `--dry-run` | Option | Performs a trial run, logging actions without writing files. |
+| `--uninstall` | Option | Removes all manifest-managed files and hook registrations. |
+| `--yes` | Option | Non-interactive mode. Automatically accepts overwriting known files. |
 
 Useful maintenance commands:
 
 ```bash
 npx clean-room-skill@latest --dry-run --all --global
 npx clean-room-skill@latest --codex --global --uninstall --yes
+npx clean-room-skill@latest doctor --runtime codex --hooks=safe
+npx clean-room-skill@latest preflight --template --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
+npx clean-room-skill@latest run --task-manifest ~/Documents/CleanRoom/task-1234abcd/contaminated/task-manifest.json --agent-commands ./agent-commands.json --dry-run
+```
+
+The installer serializes install and uninstall per target root with `.clean-room-install.lock`. It writes `clean-room-install-manifest.json` into each target root, records `phase: "installing"` before hook config mutation, and switches to `phase: "complete"` only after hook config succeeds. Reinstalling replaces only manifest-managed files automatically. Before each write or removal, the installer rechecks the file state observed during planning; late managed-file changes are backed up under `clean-room-patches/<timestamp>/` before replacement or removal. Unknown existing files are not overwritten in non-interactive mode.
+
+### Bootstrap CLI Reference
+
+Use `init` to prepare a clean implementation repository and external run folder before starting the agent workflow:
+
+```bash
+npx clean-room-skill@latest init
+npx clean-room-skill@latest init --target-dir . --target-profile speckit-feature-folder
+npx clean-room-skill@latest init --artifact-base ~/Documents/CleanRoom --task-id task-1234abcd
+```
+
+By default, `init` writes external run folders under `~/Documents/CleanRoom/<task-id>/` and creates:
+
+- `contaminated/`
+- `clean/`
+- `quarantine/`
+- `clean-room-bootstrap.json`
+- `.clean-room/README.md` in the target repository
+
+The repo-local `.clean-room/README.md` is clean-safe guidance only. Do not commit source roots, contaminated artifact paths, private identifiers, source-derived names, `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json` into the clean implementation repository.
+
+Without `--force`, bootstrap metadata and repo stub writes use atomic no-clobber creation. If another process creates the same task metadata or repo stub between the existence check and write, `init` aborts instead of overwriting it.
+
+`init` prints the output folder, repo stub path, safe hook install command, runtime start guidance, and uninstall command. It never registers strict hooks. For normal use, install safe hooks into your agent home:
+
+```bash
+npx clean-room-skill@latest --codex --global --hooks=safe --yes
+npx clean-room-skill@latest --claude --global --hooks=safe --yes
+```
+
+Use `--hooks=strict` only for dedicated clean-room Codex or Claude homes, not a daily agent profile.
+
+### Preflight CLI Reference
+
+`clean-room-skill preflight` creates or validates the required Stage 0 goal contract. It is a small helper, not an interactive wizard.
+
+```bash
+npx clean-room-skill@latest preflight --template --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
+npx clean-room-skill@latest preflight --input ./preflight-goal.json --output ~/Documents/CleanRoom/task-1234abcd/contaminated/preflight-goal.json
+```
+
+`--template` writes an attended draft with blocking `open_questions`. It rejects `--mode unattended`; unattended runs must use a completed input contract with `unattended_allowed_after_preflight: true`, finite `max_iterations`, and no `open_questions`.
+
+Keep `preflight-goal.json` in the contaminated/controller artifact root. Agent 2 and Agent 3 receive only clean-safe `goal_contract` fields and `code_hygiene_policy` through `clean-run-context.json`.
+
+### Inner Loop Runner Reference
+
+`clean-room-skill run` executes the bounded inner clean-room loop for one approved spec slice. It is not the outer spec-development loop. The task manifest must already contain:
+
+- `preflight_goal_ref` and `preflight_goal_sha256`
+- the required `handoff_sequence`
+- `controller_policy.mode: "unattended"`
+- `controller_policy.max_iterations`
+- `controller_policy.max_units_per_iteration: 1`
+- `loop_context.child_loop_kind: "clean-room"`
+- `loop_context.approved_scope_refs` naming the selected unit or units
+
+The runner locks the contaminated artifact root with `.clean-room-run.lock`, reloads durable artifacts each iteration, validates schema/leakage/handoff state, selects at most one pending or gap unit inside `approved_scope_refs`, spawns configured role commands with `shell: false`, and writes:
+
+- `controller-run-ledger.json` in the contaminated artifact root
+- `clean-room-result.json` in the contaminated artifact root
+
+CLI:
+
+```bash
+npx clean-room-skill@latest run \
+  --task-manifest ~/Documents/CleanRoom/task-1234abcd/contaminated/task-manifest.json \
+  --agent-commands ./agent-commands.json \
+  --max-iterations 3
+```
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `--task-manifest <path>` | Required path to `task-manifest.json`. |
+| `--agent-commands <path>` | Required role command adapter JSON unless `--dry-run` is set. |
+| `--max-iterations <n>` | May only lower the manifest and `loop_context` cap. |
+| `--once` | Runs at most one inner-loop iteration. |
+| `--dry-run` | Validates, selects, and prints the selected unit without writing state or spawning agents. |
+| `--schema-dir <path>` | Overrides bundled schema directory. |
+| `--python <path>` | Python executable for validation hooks. Defaults to `python3`. |
+
+Agent command adapter shape:
+
+```json
+{
+  "version": 1,
+  "stages": [
+    {
+      "phase": "contaminated-analysis",
+      "role": "contaminated-source-analyst",
+      "cwd": "/absolute/contaminated/workspace",
+      "argv": ["agent-cli", "--fresh-session", "--role", "source-analyst"],
+      "timeout_ms": 600000
+    },
+    {
+      "phase": "contaminated-coverage-verify",
+      "role": "contaminated-manager-verifier",
+      "cwd": "/absolute/contaminated/workspace",
+      "argv": ["agent-cli", "--fresh-session", "--role", "manager"]
+    }
+  ]
+}
 ```
 
-The installer writes `clean-room-install-manifest.json` into each target root. Reinstalling replaces only manifest-managed files automatically. If a managed file was locally modified, the previous version is backed up under `clean-room-patches/<timestamp>/`. Unknown existing files are not overwritten in non-interactive mode.
+Supported phases are `contaminated-analysis`, `sanitize-handoff`, `clean-plan`, `clean-implement-qc`, and `contaminated-coverage-verify`. The coverage verification phase is required because Agent 3's terminal report is not enough to return to the outer loop. Adapter `env` values may add non-clean-room variables, but must not override `CLEAN_ROOM_*`.
 
 Marketplace install remains available.
 
@@ -114,22 +271,116 @@ In Claude Code, use the plugin skill namespace:
 ```text
 /clean-room
 /clean-room:clean-room
+/clean-room:preflight
+/clean-room:init
 /clean-room:attended
 /clean-room:unattended
+/clean-room:resume
+/clean-room:start-over
+/clean-room:refocus
 ```
 
-`/clean-room` and `/clean-room:clean-room` start the setup wizard. `/clean-room:attended` starts the same wizard with attended review gates. `/clean-room:unattended` starts it with bounded unattended defaults: one unit per iteration, finite max iterations, and the configured safety stop conditions.
+`/clean-room` and `/clean-room:clean-room` start the setup wizard. `/clean-room:preflight` creates or reviews the required goal contract. `/clean-room:init` records reusable setup preferences before a run starts or changes. `/clean-room:attended` starts the same wizard with attended review gates. `/clean-room:unattended` starts it with bounded unattended defaults: one unit per iteration, finite max iterations, and the configured safety stop conditions. `/clean-room:resume`, `/clean-room:start-over`, and `/clean-room:refocus` recover runs from durable artifacts. `clean-room-skill run` executes the bounded inner clean-room loop from a schema-valid `task-manifest.json` and a user-supplied agent command adapter.
 
 In Codex, invoke the `clean-room` plugin or one of its bundled skills explicitly with `@` or the skills UI. Do not rely on Claude-style `/clean-room:...` namespacing in Codex.
 
+## Run Workflow
+
+Use this sequence for normal runs and recovery:
+
+| Situation | Claude command | Codex action | What the skill does |
+| --- | --- | --- | --- |
+| Record goal contract | `/clean-room:preflight` | Invoke `preflight` | Records end goal, target stack, dependency/license policy, exactness policy, feature policy, code hygiene, output policy, mode, and open questions. |
+| Initialize preferences | `/clean-room:init` | Invoke `init` | Records artifact roots, target profile, model preferences, clean-safe rules, and contaminated-only rules. Defaults artifacts to `~/Documents/CleanRoom/<task-id>/`. |
+| New run, default review gates | `/clean-room` or `/clean-room:attended` | Invoke `clean-room` or `attended` | Confirms authorization, separated roots, target profile, and starts the scope gate in attended mode. |
+| New bounded unattended run | `/clean-room:unattended` | Invoke `unattended` | Starts from the same scope gate, then records finite unattended bounds and stop conditions. |
+| Continue an interrupted run | `/clean-room:resume` | Invoke `resume` | Reloads `task-manifest.json`, the initialization snapshot, ledgers, `clean-run-context.json`, `qc-report.json`, handoff artifacts, and abstract delta tickets, then continues from the earliest incomplete gate. |
+| Restart a bad or obsolete run | `/clean-room:start-over` | Invoke `start-over` | Requires explicit confirmation, archives or quarantines current artifacts without deletion, then returns to the scope gate with a fresh `task_id`. |
+| Correct drift without changing scope | `/clean-room:refocus` | Invoke `refocus` | Audits current artifacts against declared scope and routes Agent 0 back to missed gates without expanding scope. |
+
+Before starting, prepare separate paths for source, contaminated artifacts, clean artifacts, optional clean reference docs, and quarantine. The default artifact base is `~/Documents/CleanRoom/<task-id>/`; if no explicitly approved neutral task ID is provided, use `task-` plus 8 lowercase hex characters. For recovery, provide the existing `task-manifest.json` or the artifact roots so the skill can reload durable state. Prior chat history is not task state.
+
+## Quick Start: Onboarding your Codebase
+
+Once the skill package is installed in your runtime, follow these steps to initialize and execute a clean-room specification task.
+
+### Optional: Bootstrap Run Folders
+Before invoking the runtime skill, you can create the external output folders and a clean-safe repository stub:
+
+```bash
+npx clean-room-skill@latest init
+```
+
+The command prints the output folder path to pass into the runtime skill. It does not write `preflight-goal.json`, `init-config.json`, `task-manifest.json`, or `clean-run-context.json`; those are still created or validated by the runtime workflow.
+
+### Step 1: Record the Goal Contract
+
+Create or review `preflight-goal.json` before source discovery:
+
+```text
+/clean-room:preflight
+```
+
+The goal contract records what is being built, which target stack to use, what public behavior may be mirrored exactly, what must not be mirrored, feature add/remove policy, dependency/license policy, code hygiene, output roots, and attended/unattended mode. `preflight-goal.json` stays on the contaminated/controller side.
+
+### Step 2: Initialize Workspace Preferences
+In your agent session (e.g., Claude Code), run the initialization subcommand:
+
+```text
+/clean-room:init
+```
+
+The agent will prompt you for setup choices and write an `init-config.json` file on the contaminated side (defaults to `~/Documents/CleanRoom/<task-id>/`). This file holds:
+*   The paths to your **Authorized Source Roots** and **Clean Output Roots**.
+*   Your output schema target profile (e.g., `speckit-feature-folder` or `openspec-delta`).
+*   Model configurations and `clean_safe` or `contaminated_only` rules.
+
+*Note: For security, `init-config.json` should never be written to or committed within your clean workspace.*
+
+### Step 3: Establish the Scope and Task Manifest
+Start the clean-room controller wizard:
+
+```text
+/clean-room
+```
+
+The agent (Agent 0) will:
+1. Re-verify the path separation of your source, contaminated, and clean workspace roots.
+2. Capture your authorization details and compile them into `task-manifest.json` with `preflight_goal_ref`, `preflight_goal_sha256`, and the required `handoff_sequence`.
+3. Create `clean-run-context.json` with only clean-safe `goal_contract` fields and `code_hygiene_policy`.
+4. If analyzing a complex scope, guide you to run the local source-index preflight to generate a `source-index.json` under your contaminated artifacts directory.
+5. Decompose the workspace files into neutral, logical task units.
+
+### Step 4: Run the Implementation Pipeline
+Choose either **Attended** (with explicit manual approval checkpoints) or **Unattended** mode to begin work on the logical units:
+
+```text
+/clean-room:attended
+/clean-room:unattended
+```
+
+*   **Agent 1** analyzes the source files mapped to the active unit and writes neutral draft specs under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+*   **Agent 1.5** sanitizes the drafts, ensuring no private symbols, code snippets, or structure are leaked.
+*   **Agent 2** reads sanitized specs plus the clean destination foundation and writes `implementation-plan.json`.
+*   **Agent 3** implements the selected spec slice under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, records verification status, and writes `implementation-report.json` plus `qc-report.json`.
+
+The outer loop evolves specs and chooses one approved spec slice. The inner clean-room loop completes that slice through sanitized handoff, implementation, QC, and contaminated-side coverage verification, then writes `clean-room-result.json` before returning to the outer loop. Agent 3's terminal report alone is not an inner-loop return.
+
 ## Operating Model
 
 Use separate workspaces, worktrees, repositories, or profiles for contaminated and clean work:
 
 - Contaminated source workspace: source-readable, read-only where practical.
-- Contaminated artifact workspace: source indexes, task manifests, coverage ledgers, evidence ledgers, draft specs, and abstract delta tickets. Configure as `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
-- Clean spec workspace: approved behavior specs, handoff packages, skeleton manifests, QC reports, and test plans.
-- Clean allowed reference workspace: public documentation or destination constraints explicitly approved for clean-role reads.
+- Contaminated artifact workspace: preflight goals, init configs, source indexes, task manifests, coverage ledgers, evidence ledgers, draft specs, and abstract delta tickets. Configure as `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+- Clean artifact workspace: clean run contexts, approved behavior specs, handoff packages, skeleton manifests, implementation plans, implementation reports, QC reports, and test plans. Configure as `CLEAN_ROOM_CLEAN_ROOTS`.
+- Clean implementation workspace: clean destination code and tests. Configure as `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
+- Clean allowed reference workspace: public documentation or destination constraints explicitly approved for clean and source-denied role reads.
+
+### Path Naming Guards
+
+Artifact paths must be neutral. Do not name task IDs, clean roots, implementation roots, or contaminated artifact roots after private source folders or private code identifiers.
+
+When no explicitly approved neutral task ID is provided, the controller should generate `task-` plus 8 lowercase hex characters under `~/Documents/CleanRoom/`. The initialization wizard and `require-clean-room-env.py` preflight reject clean, implementation, or contaminated artifact paths that contain source root basenames or meaningful non-generic tokens from those basenames. Guard errors avoid printing the private source name.
 
 Prompt instructions alone are not a boundary. Use path separation, role-specific sessions, hook checks, schema validation, and artifact quarantine.
 
@@ -137,79 +388,15 @@ Prompt instructions alone are not a boundary. Use path separation, role-specific
 
 ![Clean Room Architecture](assets/clean-room-arch.svg)
 
-### Flowchart Representation
-
-```mermaid
-flowchart LR
-  subgraph contaminated["Contaminated domain: source-readable"]
-    source["Authorized source roots<br/>CLEAN_ROOM_SOURCE_ROOTS"]
-    manager["Agent 0: contaminated-manager-verifier<br/>Scope, decompose, track coverage, verify"]
-    analyst["Agent 1: contaminated-source-analyst<br/>Read source, write neutral tasks and specs"]
-    ledgers["Contaminated artifacts<br/>CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS<br/>source-index.json<br/>task-manifest.json<br/>coverage-ledger.json<br/>evidence-ledger.json"]
-    scrub["Leakage review<br/>Remove source expression"]
-  end
-
-  subgraph wall["Clean-room wall"]
-    handoff["Approved handoff only<br/>handoff-package.json<br/>scrubbed behavior-spec.json"]
-    blocked["Blocked from crossing<br/>source excerpts, raw diffs, copied comments,<br/>private identifiers, source-shaped pseudocode"]
-  end
-
-  subgraph clean["Clean domain: source-denied"]
-    cleanroots["Clean artifact roots<br/>CLEAN_ROOM_CLEAN_ROOTS"]
-    publicrefs["Allowed public refs<br/>CLEAN_ROOM_ALLOWED_READ_ROOTS"]
-    architect["Agent 2: clean-architect<br/>Manage schema base and skeleton manifest"]
-    qa["Agent 3: clean-qa-editor<br/>Validate schema, leakage, coverage, testability"]
-    outputs["Clean outputs<br/>skeleton-manifest.json<br/>qc-report.json<br/>test plan notes"]
-  end
-
-  subgraph guardrails["Guardrails and audit"]
-    env["require-clean-room-env.py"]
-    denyread["deny-clean-source-read.py"]
-    denywrite["deny-contaminated-clean-write.py<br/>write root policy"]
-    denyshell["deny-clean-room-shell.py"]
-    scan["check-artifact-leakage.py<br/>validate-json-schema.py"]
-  end
-
-  source --> manager
-  manager --> analyst
-  manager --> ledgers
-  analyst --> ledgers
-  analyst --> scrub
-  scrub --> handoff
-  handoff --> cleanroots
-  cleanroots --> architect
-  publicrefs --> architect
-  architect --> outputs
-  outputs --> qa
-  qa --> outputs
-  qa -. abstract delta tickets only .-> manager
-
-  blocked -. quarantine do not hand off .-> ledgers
-  env -. required for every role session .-> manager
-  env -. required for every role session .-> architect
-  denyread -. clean roles cannot read source roots .-> cleanroots
-  denywrite -. contaminated writes only to contaminated artifact roots .-> ledgers
-  denywrite -. clean writes only to clean roots .-> cleanroots
-  denyshell -. no shell-style tools in role sessions .-> manager
-  denyshell -. no shell-style tools in role sessions .-> architect
-  scan -. post-write checks .-> outputs
-
-  classDef contaminatedDomain fill:#fff7ed,stroke:#c2410c,color:#111827;
-  classDef cleanDomain fill:#ecfeff,stroke:#0e7490,color:#111827;
-  classDef wallClass fill:#f8fafc,stroke:#475569,color:#111827;
-  classDef guardClass fill:#f0fdf4,stroke:#15803d,color:#111827;
-  class source,manager,analyst,ledgers,scrub contaminatedDomain;
-  class cleanroots,publicrefs,architect,qa,outputs cleanDomain;
-  class handoff,blocked wallClass;
-  class env,denyread,denywrite,denyshell,scan guardClass;
-```
+For a detailed breakdown of the flowchart representation, agent responsibilities, environment boundaries, and guardrail scripts, see the [Clean Room Architecture Documentation](docs/ARCHITECTURE.md).
 
 ## Roles
 
-- Agent 0 / `contaminated-manager-verifier`: consumes contaminated source indexes, decomposes scope into logical batches, tracks coverage, verifies clean specs against source, and receives Agent 3 final QC reports.
-- Agent 1 / `contaminated-source-analyst`: reads authorized source and writes neutral task/spec material with evidence references, not code.
-- Agent 2 / `clean-architect`: reads approved clean artifacts, manages the selected clean schema base, and organizes artifacts into target-neutral skeleton manifests.
-- Agent 3 / `clean-qa-editor`: validates schema conformance, leakage risk, terminology, coverage gaps, and testability, then reports abstract findings back to Agent 0.
+- Agent 0 / `contaminated-manager-verifier`: consumes contaminated source indexes, decomposes scope into logical batches, tracks coverage, verifies clean specs and terminal implementation reports against source, and influences Agent 2/3 only through durable sanitized artifacts.
+- Agent 1 / `contaminated-source-analyst`: reads authorized source and writes neutral draft task/spec material with evidence references, not code.
+- Agent 1.5 / `contaminated-handoff-sanitizer`: reviews Agent 1 drafts from a fresh source-denied contaminated context and approves only sanitized handoff candidates.
+- Agent 2 / `clean-architect`: reads clean artifacts and the clean implementation foundation, then writes `implementation-plan.json` with relative destination paths, tests, constraints, risks, and argv-array verification commands.
+- Agent 3 / `clean-qa-editor`: implements the selected spec-slice work under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, records verification status, maintains `qc-report.json`, and emits one terminal report for Agent 0 only when the assigned slice is complete, blocked, or quarantined.
 
 Claude role agents are in `agents/`. Codex role-agent templates are in `examples/codex/.codex/agents/`.
 
@@ -222,13 +409,18 @@ CLEAN_ROOM_ROLE
 CLEAN_ROOM_SOURCE_ROOTS
 CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS
 CLEAN_ROOM_CLEAN_ROOTS
+CLEAN_ROOM_IMPLEMENTATION_ROOTS
 CLEAN_ROOM_SCHEMA_DIR
 CLEAN_ROOM_ALLOWED_READ_ROOTS
 ```
 
-For clean roles, reads are deny-by-default. They may read only `CLEAN_ROOM_CLEAN_ROOTS` plus explicit public or destination constraint roots in `CLEAN_ROOM_ALLOWED_READ_ROOTS`. Source roots in `CLEAN_ROOM_SOURCE_ROOTS` stay denied.
+For clean roles, reads are deny-by-default. They may read only `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and explicit public or destination constraint roots in `CLEAN_ROOM_ALLOWED_READ_ROOTS`. Agent 2 and Agent 3 receive `clean-run-context.json`, not the full `task-manifest.json` or `preflight-goal.json`. Agent 1.5 is also source-denied: it may read only assigned contaminated artifacts, `CLEAN_ROOM_SCHEMA_DIR`, and explicit public or destination constraint roots. Source roots in `CLEAN_ROOM_SOURCE_ROOTS` stay denied.
+
+Agent 0 must not directly steer Agent 2 or Agent 3. Clean roles accept Agent 0 input only as schema-valid durable sanitized artifacts already present in the clean workspace. Direct chat instructions, progress feedback, priority changes, implementation hints, or corrective coaching from Agent 0 are out of bounds. Agent 3 reports back to Agent 0 only at the terminal report gate, never during an active implementation loop.
 
-Writes are also deny-by-default. Clean roles may write only under `CLEAN_ROOM_CLEAN_ROOTS`. Contaminated roles may write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`. Source roots stay read-only for contaminated roles unless a separate, explicit process outside this plugin changes that policy.
+Writes are also deny-by-default. Agent 2 writes only clean artifacts under `CLEAN_ROOM_CLEAN_ROOTS`. Agent 3 writes reports under `CLEAN_ROOM_CLEAN_ROOTS` and code/tests only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Contaminated roles may write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`. Source roots stay read-only for contaminated roles unless a separate, explicit process outside this plugin changes that policy.
+
+The environment preflight also audits root names. `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS` must not contain source-derived project basenames or meaningful non-generic source-name tokens.
 
 Optional hook-only guardrail:
 
@@ -236,11 +428,13 @@ Optional hook-only guardrail:
 CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST
 ```
 
-Set it to path-separated, line-oriented files containing private source package, module, class, function, method, variable, constant, field, or other internal identifiers to reject from clean artifacts. Blank lines and `#` comments are ignored. Files are bounded to 1,000,000 bytes each, 20,000 total terms, and 512 characters per term. Keep those files outside clean-role readable roots and do not paste their contents into model-visible artifacts.
+Set it to path-separated, line-oriented files containing private source package, module, class, function, method, variable, constant, field, or other internal identifiers to reject from clean artifacts. Blank lines and `#` comments are ignored. Files are bounded to 1,000,000 bytes each, 20,000 total terms, and 512 characters per term. Keep those files outside clean/source-denied readable roots and do not paste their contents into model-visible artifacts.
+
+Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3 profile. If Agent 3 verification needs a terminal, use an isolated verification home with strict hooks and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`, then invoke only the installed `agent3-verification-runner.py` from an implementation-root cwd. The runner reads argv-array verification commands from `implementation-plan.json`, applies a small allowlist, strips clean-room root env values, and executes with `shell=False`. Shell access still does not replace OS/profile isolation for untrusted test code.
 
-Do not grant shell-style tools to clean-room role sessions. Shell access can bypass path-aware read and write hooks.
+For multi-file scopes, run `skills/clean-room/scripts/build_source_index.py` as source-index controller preflight before clean-room role sessions. Store `source-index.json` under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, or pass `--contaminated-artifact-root` explicitly. The script refuses `--output` outside those roots. It is contaminated-only and must not be included in clean handoff packages or shown to Agent 1.5.
 
-For multi-file scopes, run `skills/clean-room/scripts/build_source_index.py` as controller preflight before clean-room role sessions. Store `source-index.json` under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, or pass `--contaminated-artifact-root` explicitly. The script refuses `--output` outside those roots. It is contaminated-only and must not be included in clean handoff packages.
+`source-index.json` includes bounded `skipped_entries` when the indexer intentionally or unavoidably omits input. Expected reasons include ignored directories, file count and byte caps, total byte caps, binary files, file stat/read errors, post-read size changes, files that changed during read, symlinks that resolve outside the source root, and directory traversal errors. After a global file or byte cap is reached, traversal is pruned and represented by an aggregate `remaining-files-skipped-after-limit:*` entry instead of enumerating the rest of a large tree. Treat skipped entries as coverage metadata: inspect them before deciding that a source index fully represents the authorized root.
 
 Optional AST/indexing helpers are checked before the controller loop, not from clean-room role sessions:
 
@@ -248,13 +442,15 @@ Optional AST/indexing helpers are checked before the controller loop, not from c
 python3 skills/clean-room/scripts/clean_room_tool_manager.py --status
 ```
 
-`--status` is stat-only by default. Use `--probe-tools` only when you want it to execute discovered tools with version commands:
+`--status` is stat-only by default. Use `--probe-tools` only when you want it to execute version commands for explicitly configured, cache-local, skill-local, system-path, or explicitly allowed project tools:
 
 ```bash
 python3 skills/clean-room/scripts/clean_room_tool_manager.py --status --probe-tools
 ```
 
-Local helper installs are explicit and version-pinned, and they write to `~/.cache/re-skills/clean-room-tools/`:
+Tools discovered under `/opt/homebrew` or `/usr/local` remain stat-only during `--probe-tools` unless you also pass `--allow-user-toolchain-probes`.
+
+Local helper installs are explicit and strict SemVer version-pinned, and they write to `~/.cache/re-skills/clean-room-tools/`. Local npm-backed installs are serialized with a cache-local lock so concurrent setup processes do not mutate the shared npm prefix at the same time. Prefix creation failures, subprocess timeouts, and subprocess launch errors are reported as structured JSON error facts:
 
 ```bash
 python3 skills/clean-room/scripts/clean_room_tool_manager.py --install-local ast-grep --version <exact-version>
@@ -266,65 +462,117 @@ Target-project `.local/bin`, `.bin`, and `node_modules/.bin` are ignored unless
 
 Missing `controller_policy` means `attended`.
 
-- `attended`: agent zero pauses for human review at scope gate, clean handoff, QC deltas, blocked units, and final coverage.
-- `unattended`: agent zero runs a bounded controller loop. It reloads durable artifacts each iteration, selects at most one pending or gap unit, starts each role from fresh context with the required environment block, validates before advancing state, and stops on any configured safety or ambiguity condition.
+- `attended`: agent zero pauses for human review at scope gate, clean handoff, terminal implementation deltas, blocked units, and final coverage.
+- `unattended`: agent zero runs a bounded inner clean-room loop only after preflight allows unattended mode with no open questions. It reloads durable artifacts each iteration, selects at most one pending or gap unit inside the approved spec slice, starts each role from fresh context with the required environment block, validates before advancing state, and stops on any configured safety or ambiguity condition.
 
-Agent zero generates the durable tasklist as neutral `task-manifest.json` `units`. For larger scopes, it may use `source-index.json` recommended batches and record `source_index_ref` plus per-unit `source_index_refs`. Progress is tracked in `coverage-ledger.json`, `evidence-ledger.json`, `qc-report.json`, and abstract delta tickets, not in prior chat history.
+`task-manifest.json` may include `run_state` with the generation, start timestamp, previous generation reference, and restart reason. It may also include `initialization_snapshot`, which is the per-run copy of `init-config.json` preferences. Use durable artifacts to recover or start over without relying on chat history.
+
+Agent zero generates the durable tasklist as neutral `task-manifest.json` `units`. For larger scopes, it may use `source-index.json` recommended batches and record `source_index_ref` plus per-unit `source_index_refs`. Progress is tracked in `coverage-ledger.json`, `evidence-ledger.json`, terminal `implementation-report.json`, `qc-report.json`, and abstract delta tickets, not in prior chat history or live clean-role feedback.
+
+## Recovery Entry Points
+
+- `resume`: reload durable artifacts, including referenced preflight goal and implementation plan/report when present, validate schema and leakage state, compare reusable init config against the manifest snapshot when present, and continue from the earliest incomplete gate using the recorded `controller_policy`.
+- `start-over`: require explicit confirmation, archive or quarantine the current artifact set without deletion, and restart from the preflight gate with a fresh `task_id`.
+- `refocus`: audit current artifacts against declared scope and preflight goal, then steer Agent 0 back to missed gates without expanding scope.
 
 ## Artifacts
 
 The schema contract lives in `skills/clean-room/assets/`:
 
 - `task-manifest.schema.json`
+- `preflight-goal.schema.json`
+- `init-config.schema.json`
+- `clean-run-context.schema.json`
 - `source-index.schema.json`
 - `coverage-ledger.schema.json`
 - `evidence-ledger.schema.json`
 - `handoff-package.schema.json`
 - `behavior-spec.schema.json`
 - `skeleton-manifest.schema.json`
+- `implementation-plan.schema.json`
+- `implementation-report.schema.json`
+- `clean-room-result.schema.json`
 - `qc-report.schema.json`
 - `contamination-incident.schema.json`
 
-Example artifact shapes are in `skills/clean-room/examples/minimal-spec-package/`. They are examples only, not outputs from a real source review.
+Clean-side example artifact shapes are in `skills/clean-room/examples/minimal-spec-package/`. Verification commands in clean plans and reports are argv arrays, not shell strings. Contaminated-side controller examples, including `source-index.json`, are in `skills/clean-room/examples/contaminated-side/`. They are examples only, not outputs from a real source review.
 
 ## Workflow
 
-1. Record authorization, scope, prohibited actions, evidence handling, and role root paths in `task-manifest.json`.
-2. Record the user's selected target profile and Agent 0-3 pipeline in `task-manifest.json`.
-3. Run source index preflight when the source scope needs relationship-aware batching.
-4. Decompose the source scope into bounded, neutral `task-manifest.json` units. One unit may map to one source-index batch or, for large files, one preflight segment.
-5. Write contaminated-side behavior specs from observed behavior, public contracts, states, errors, invariants, and test scenarios.
-6. Scrub specs using `skills/clean-room/references/LEAKAGE-RULES.md`.
-7. Move only approved structured artifacts into the clean workspace through `handoff-package.json`. Do not include `source-index.json`.
-8. Build or merge the clean schema base and `skeleton-manifest.json` from clean specs, target profile, and target constraints.
-9. Produce `qc-report.json` with schema status, leakage status, gaps, and testability notes.
-10. Verify coverage from the contaminated side and repeat only with abstract delta tickets.
-11. Stop at the spec package. Do not implement replacement code in this plugin workflow.
+1. Create or validate `preflight-goal.json`.
+2. Record reusable setup preferences in `init-config.json` when requested, then snapshot effective choices into `task-manifest.json`.
+3. Record authorization, scope, prohibited actions, evidence handling, preflight goal ref/hash, role root paths, and the required `handoff_sequence` in `task-manifest.json`.
+4. Record the user's selected target profile, model policy, `run_state`, Agent 0-3 pipeline, and required Agent 1.5 sanitizer role in `task-manifest.json`.
+5. Create `clean-run-context.json` for Agent 2 and Agent 3. It must record artifact-only coordination, clean-safe `goal_contract` fields, and `code_hygiene_policy`, and must not contain source roots, contaminated roots, source index refs, ledger paths, or full preflight/task manifests.
+6. Run source index preflight when the source scope needs relationship-aware batching.
+7. Decompose the source scope into bounded, neutral `task-manifest.json` units. One unit may map to one source-index batch or, for large files, one preflight segment.
+8. Write contaminated-side draft behavior specs from observed behavior, public contracts, states, errors, invariants, and test scenarios.
+9. Sanitize specs through Agent 1.5 using `skills/clean-room/references/LEAKAGE-RULES.md`; Agent 1.5 gets only a neutral brief and assigned draft paths.
+10. Move only Agent 1.5-approved structured artifacts and `clean-run-context.json` into the clean workspace through `handoff-package.json`. Do not include `task-manifest.json`, `preflight-goal.json`, or `source-index.json`.
+11. Agent 2 writes `implementation-plan.json` from clean specs, clean run context, target constraints, preflight code hygiene policy, and the clean implementation foundation.
+12. Agent 3 implements work items under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, records verification status, and writes `implementation-report.json` without Agent 0 guidance. Run terminal verification only through the installed Agent 3 verification runner.
+13. Produce or update `qc-report.json` with schema status, leakage status, gaps, code hygiene findings, and testability notes.
+14. After Agent 3 reaches complete, blocked, or quarantined, Agent 0 verifies coverage from the contaminated side.
+15. Write `clean-room-result.json` with `spec-slice-complete`, `spec-slice-blocked`, `spec-delta-required`, `contamination-suspected`, `iteration-limit-reached`, or `no-progress-detected`.
+16. Repeat only through updated durable clean artifacts and abstract delta tickets. Do not steer an in-progress Agent 2 or Agent 3 session.
 
 ## Hook Guardrails
 
-Hook scaffolding lives in `hooks/` and is declared by `hooks/hooks.json`.
+Agent/tool hook scaffolding lives in `hooks/`. Security enforcement uses installer-generated Codex or Claude hook configs with absolute wrapper paths. Runtime plugin manifests do not declare static package hooks because cwd-relative hook commands are fragile.
+
+The generated hook configs route through `hooks/clean-room-hook.py`. In safe mode, the wrapper exits successfully unless `CLEAN_ROOM_HOOK_ENFORCE=1` or clean-room environment variables are present. Safe mode is compatibility-only until enforcement is enabled. In strict mode, it runs the configured checks immediately and fails closed when required role or path configuration is missing. Prefer strict mode for dedicated Codex or Claude clean-room homes.
+
+After install, run a smoke check:
+
+```bash
+clean-room-skill doctor --runtime codex --hooks=strict
+```
+
+Use `--runtime claude` for Claude Code, and add `--config-dir <path>` when testing an alternate config root.
+
+Expanded matcher coverage applies only to tool events the host runtime actually emits; do not treat matcher names as proof that an unsupported host tool is guarded.
+
+### What Doctor Verifies
 
-`hooks/hooks.json` routes through `hooks/clean-room-hook.py`. In safe mode, the wrapper exits successfully unless `CLEAN_ROOM_HOOK_ENFORCE=1` or clean-room environment variables are present. In strict mode, it runs the configured checks immediately and fails closed when required role or path configuration is missing.
+`doctor` verifies that Codex or Claude hook config exists, contains four generated clean-room hooks, uses absolute wrapper paths, uses the requested safe or strict mode, and that smoke payloads fail for missing environment, source reads, source writes, shell use, and malformed post-write JSON. It also verifies that safe hooks no-op without clean-room env.
 
-`hooks/hooks.json` uses commands relative to the plugin package root, such as `python3 hooks/clean-room-hook.py --mode safe ...`. Confirm the host executes plugin hooks from that directory during install smoke tests.
+It does not verify every runtime tool event, every matcher name emitted by the host, host-side hook enablement outside the config file, legal clean-room sufficiency, or full JSON Schema conformance. Treat it as an install smoke test, not a complete enforcement proof.
 
 - `clean-room-hook.py`: safe/strict dispatch wrapper for the policy checks below.
+- `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.
 - `require-clean-room-env.py`: fails closed when required role and root environment is missing.
-- `deny-clean-room-shell.py`: denies shell-style tools for clean-room role sessions.
-- `deny-clean-source-read.py`: denies clean-role reads from source roots and unapproved paths.
-- `deny-contaminated-clean-write.py`: enforces role write roots. Clean roles write only under clean roots; contaminated roles write only under contaminated artifact roots.
-- `check-artifact-leakage.py`: scans clean artifacts for high-risk leakage markers, source-like identifiers, and optional private identifier denylist matches.
+- `deny-clean-room-shell.py`: denies shell-style tools for clean-room role sessions except installed Agent 3 verification-runner invocations explicitly allowed under implementation roots.
+- `deny-clean-source-read.py`: denies clean and source-denied role reads from source roots and unapproved paths.
+- `deny-contaminated-clean-write.py`: enforces role write roots. Agent 2 writes clean artifacts only, Agent 3 may write clean reports and implementation-root files, and contaminated roles write only under contaminated artifact roots.
+- `check-artifact-leakage.py`: scans clean artifacts, plus Agent 1.5 staged contaminated artifacts, for high-risk leakage markers, source-like identifiers, and optional private identifier denylist matches.
 - `validate-json-schema.py`: checks JSON syntax and common bundled clean-room schema constraints, including the conditional and bounded fields used by these schemas. Under clean roots, unknown JSON artifacts are rejected unless explicitly allowlisted through `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST`. It is a lightweight guardrail, not a full JSON Schema 2020-12 validator.
-- `validate-handoff-package.py`: verifies handoff artifact paths stay under clean roots, do not point into source or contaminated roots, do not include `source-index.json`, and match declared `sha256` values.
+- `validate-handoff-package.py`: verifies handoff artifact paths stay under clean roots, do not point into source or contaminated roots, do not include `task-manifest.json`, `preflight-goal.json`, or `source-index.json`, and match declared `sha256` values.
 
 These scripts are guardrail and audit support. They are not a substitute for separate workspaces and role isolation.
 
 For release-quality schema assurance, run a full JSON Schema validator in addition to the bundled lightweight hook.
 
+## Troubleshooting
+
+| Symptom | Likely cause | Recovery |
+| --- | --- | --- |
+| `python3 is required to install clean-room hooks` | Python missing or not on `PATH` | Install Python 3 or use `--hooks=copy-only` |
+| `safe hooks are installed but not enforcing` | Safe mode default | Set `CLEAN_ROOM_HOOK_ENFORCE=1`, set clean-room env vars, or reinstall with `--hooks=strict` in a dedicated profile |
+| `install lock is held` | Another install or uninstall is mutating the same target root, or a prior process died while holding `.clean-room-install.lock` | Wait for the other process to finish; inspect and remove the lock only after confirming no installer is active |
+| Hook config write failed after files copied | Partial installer state; manifest records `hook_registration.status: "failed"` when possible | Fix the filesystem error, then re-run the same installer command to repair hook registration |
+| Install manifest write failed after files copied | Manifest may be absent or left at `phase: "installing"` | Re-run the same installer command before relying on uninstall tracking |
+| `phase` remains `installing` in `clean-room-install-manifest.json` | The previous install did not complete hook config or manifest finalization | Re-run the same installer command for that runtime and target root |
+| `clean-room run` rejects the manifest | The manifest is not unattended, lacks `loop_context`, raises `--max-iterations`, or has no approved unit | Fix `controller_policy`, `loop_context`, and `approved_scope_refs`, then retry `--dry-run` |
+| `clean-room run` reports no progress | The configured stages exited successfully but no tracked durable JSON artifact changed | Check role command cwd/argv, selected unit, and artifact write roots |
+| `clean-room run` reports repeated unit selection | The same unit was selected after a prior no-progress iteration | Resolve the blocker or update durable artifacts before retrying |
+| Hook reports `could not read` or `could not stat` | Artifact disappeared, permissions changed, or path was replaced during post-write validation | Restore readable artifact state and retry; hooks fail closed without printing private paths |
+| `source-index.json` is missing files | Limits, unreadable directories, ignored directories, binary files, changed-during-read files, or symlinks outside the source root | Inspect `skipped_entries` and adjust limits or permissions if the omissions matter |
+
 ## References
 
 - `skills/clean-room/SKILL.md`: main skill instructions.
+- `skills/clean-room/references/CONTROLLER-LOOP.md`: nested outer/inner loop contract.
+- `skills/clean-room/references/PREFLIGHT.md`: Stage 0 goal contract.
 - `skills/clean-room/references/PROCESS.md`: detailed process.
 - `skills/clean-room/references/LEAKAGE-RULES.md`: clean handoff rules.
 - `skills/clean-room/references/SPEC-SCHEMA.md`: artifact schema guidance.
@@ -339,6 +587,7 @@ export CLEAN_ROOM_ROLE=clean-qa-editor
 export CLEAN_ROOM_SOURCE_ROOTS="$PWD/source"
 export CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS="$PWD/contaminated-artifacts"
 export CLEAN_ROOM_CLEAN_ROOTS="$PWD/skills/clean-room/examples/minimal-spec-package"
+export CLEAN_ROOM_IMPLEMENTATION_ROOTS="$PWD/implementation"
 export CLEAN_ROOM_ALLOWED_READ_ROOTS=""
 export CLEAN_ROOM_SCHEMA_DIR="$PWD/skills/clean-room/assets"
 
@@ -353,24 +602,30 @@ python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py <
 
 ## Local Verification
 
-After changing plugin metadata, hooks, schemas, or skill instructions, run the relevant checks from the plugin package root:
+After changing plugin metadata, hooks, schemas, or skill instructions, run the same local checks used for pull request CI:
+
+```bash
+npm run verify
+```
+
+Note: The unit test suite (`npm test`) utilizes the native Node.js test runner and requires Node.js >= 22 to execute successfully.
+
+The full JSON Schema validation requires Python `jsonschema` with format extras. On macOS with Homebrew Python, use a repo-local venv:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install "jsonschema[format]>=4.18,<5"
+npm run verify
+```
+
+Optional, if an external skill-creator `quick_validate` command is installed on your machine:
 
 ```bash
-python3 -m json.tool plugin.json >/dev/null
-python3 -m json.tool .codex-plugin/plugin.json >/dev/null
-python3 -m json.tool .claude-plugin/plugin.json >/dev/null
-python3 -m json.tool hooks/hooks.json >/dev/null
-python3 -m py_compile hooks/*.py
-python3 -m py_compile skills/clean-room/scripts/*.py
-node --test
-npm pack --dry-run
-node bin/install.js --dry-run --all --global
-python3 skills/clean-room/scripts/build_source_index.py --help
-# Optional, if skill-creator quick_validate is installed:
 quick_validate skills/attended
 quick_validate skills/clean-room
+quick_validate skills/init
+quick_validate skills/refocus
+quick_validate skills/resume
+quick_validate skills/start-over
 quick_validate skills/unattended
-for f in skills/clean-room/examples/minimal-spec-package/*.json; do printf '{"tool_input":{"file_path":"%s"}}' "$PWD/$f" | CLEAN_ROOM_SCHEMA_DIR="$PWD/skills/clean-room/assets" python3 hooks/validate-json-schema.py || exit 1; done
-for f in skills/clean-room/examples/minimal-spec-package/*.json; do if [ "$(basename "$f")" = source-index.json ]; then continue; fi; printf '{"tool_input":{"file_path":"%s"}}' "$PWD/$f" | CLEAN_ROOM_CLEAN_ROOTS="$PWD/skills/clean-room/examples/minimal-spec-package" python3 hooks/check-artifact-leakage.py || exit 1; done
-find . -maxdepth 4 -type d -name bin -print
 ```