clean-room-skill 0.1.0 → 0.1.3

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "clean-room",
   "displayName": "Clean Room",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "author": {
     "name": "whit3rabbit"
   },
@@ -15,6 +15,5 @@
     "compliance"
   ],
   "skills": "./skills/",
-  "agents": "./agents/",
-  "hooks": "./hooks/hooks.json"
+  "agents": "./agents/"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"
@@ -15,7 +15,6 @@
     "compliance"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks/hooks.json",
   "interface": {
     "displayName": "Clean Room",
     "shortDescription": "Produce clean-room behavioral specs",

package/README.md

@@ -1,376 +1,205 @@
 # Clean Room
 
-Spec-first clean-room workflow for software to spec. 
+Clean Room is an agent workflow for turning authorized source analysis into clean behavioral specs, clean implementation plans, and clean destination code.
 
-This is a POC based on the ideas presented here: 
+It is a POC based on ideas from [malus.sh](https://malus.sh/blog.html). It is an engineering risk-reduction workflow, not legal advice, and it does not create a legal safe harbor.
 
-https://malus.sh/blog.html
+## What This Is / Does
 
-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.
+Use this package when you need documented separation between source-reading work and clean implementation work.
 
-It is an engineering risk-reduction workflow. It is not legal advice and does not create a legal safe harbor.
+It installs:
 
-## Use This For
+- Clean-room skills for Codex, Claude Code, and other agent runtime layouts.
+- Role-agent prompts for contaminated analysis, clean planning, and clean implementation.
+- JSON schemas and examples for durable workflow artifacts.
+- Hook guardrails that help keep source material out of clean artifacts.
+- A small CLI for runtime installation, bootstrap folders, preflight contracts, hook smoke tests, and the bounded inner clean-room runner.
 
-- Authorized source-to-spec migration planning.
-- 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.
+The workflow creates clean behavioral spec packages and clean implementation outputs. It does not generate replacement code directly from source.
 
-## Threat Model And Non-Goals
+Core boundary:
 
-This workflow protects against:
+- Contaminated roles may read authorized source and write contaminated artifacts.
+- Source-denied roles may read only clean artifacts, implementation roots, schemas, and approved public/reference roots.
+- Clean implementation code is written only under the clean implementation root.
+- Raw source, source paths, private identifiers, raw diffs, copied comments, and source-shaped pseudocode must not cross into clean handoff artifacts.
 
-- accidental source expression crossing into clean specs
-- clean agents reading contaminated roots
-- contaminated agents writing clean artifacts
-- clean or contaminated agents writing outside their role artifact roots
-- unbounded unattended controller loops
+For the full boundary model, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). For CLI and troubleshooting details, see [docs/REFERENCE.md](docs/REFERENCE.md).
 
-It does not protect against:
+## How To Install
 
-- hostile local users
-- compromised host tooling
-- shared model context outside role isolation
-- legal conclusions
-- side channels through filenames, timing, or retained chat context
+Requires Node.js `>=22`.
 
-## Install
-
-Preferred direct installer:
+Preferred interactive install:
 
 ```bash
 npx clean-room-skill@latest
 ```
 
-The installer prompts for runtime and scope when no flags are supplied. For non-interactive installs, pass the runtime and scope explicitly:
+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 --antigravity --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
-Supported runtime 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.
-
 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=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=safe`: default. Hooks are installed but enforce only during clean-room role sessions with the required environment.
+- `--hooks=strict`: fail-closed hook mode for dedicated Codex or Claude clean-room homes.
+- `--hooks=copy-only` or `--no-hooks`: copy hook files without registering runtime hook config.
 
-Useful maintenance commands:
-
-```bash
-npx clean-room-skill@latest --dry-run --all --global
-npx clean-room-skill@latest --codex --global --uninstall --yes
-```
+Verified runtimes are Codex and Claude Code. Other runtime layouts are installed on a best-effort basis. See [docs/REFERENCE.md](docs/REFERENCE.md#runtime-support) for the full support table and install roots.
 
-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.
+Marketplace install is also supported.
 
-Marketplace install remains available.
-
-From Codex marketplace:
+Codex:
 
 ```bash
 codex plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
 ```
 
-Then install or enable `clean-room` from the `clean-room-skill` marketplace. Enable plugin hooks in trusted Codex config before relying on guardrails:
-
-```toml
-[features]
-plugin_hooks = true
-```
-
-From Claude Code marketplace:
+Claude Code:
 
 ```text
 /plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
 /plugin install clean-room@clean-room-skill
 ```
 
-Manual Antigravity install:
+## How To Run
 
-Clone this repository into your local plugins directory:
+Optionally create neutral external run folders and a clean-safe repository stub:
 
 ```bash
-git clone https://github.com/whit3rabbit/clean-room-skill.git ~/.gemini/config/plugins/clean-room-skill
+npx clean-room-skill@latest init
 ```
 
-Reload or restart the host if the plugin is not visible immediately.
-
-## Invocation
+The default artifact base is `~/Documents/CleanRoom/<task-id>/`. Keep active contaminated artifacts, clean artifacts, and clean implementation roots separate.
 
-In Claude Code, use the plugin skill namespace:
+In Claude Code, invoke skills with the plugin 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.
-
-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.
+In Codex, invoke the `clean-room` plugin or bundled skills through `@` or the skills UI. Do not rely on Claude-style slash namespacing in Codex.
 
-## Operating Model
+For unattended inner-loop execution from durable artifacts:
 
-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.
+```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
+```
 
-Prompt instructions alone are not a boundary. Use path separation, role-specific sessions, hook checks, schema validation, and artifact quarantine.
+The `run` command executes one bounded inner clean-room loop for an already approved spec slice. It does not replace the outer spec-development workflow.
 
-## Separation Diagram
+## Typical Workflow
 
 ![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;
-```
-
-## Roles
+1. Record the goal contract.
+   Use `/clean-room:preflight` or `clean-room-skill preflight` before source discovery. This creates or validates `preflight-goal.json` on the contaminated/controller side.
 
-- 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.
+2. Initialize preferences.
+   Use `/clean-room:init` to record artifact roots, target profile, model preferences, clean-safe rules, and contaminated-only rules. The active `init-config.json` stays out of the clean implementation repository.
 
-Claude role agents are in `agents/`. Codex role-agent templates are in `examples/codex/.codex/agents/`.
+3. Start the controller.
+   Use `/clean-room` or `/clean-room:attended` for human review gates. Use `/clean-room:unattended` only after preflight allows bounded unattended work with finite iteration limits and no open questions.
 
-## Required Environment
+4. Analyze and sanitize.
+   Source-reading roles produce neutral draft behavior specs. A source-denied sanitizer reviews handoff candidates before anything enters the clean domain.
 
-Set and pass this environment block into every clean-room role session before tool use:
+5. Plan and implement.
+   Clean roles read only approved clean artifacts and the clean destination foundation. Agent 2 writes `implementation-plan.json`; Agent 3 writes code/tests under the implementation root and reports under clean artifacts.
 
-```text
-CLEAN_ROOM_ROLE
-CLEAN_ROOM_SOURCE_ROOTS
-CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS
-CLEAN_ROOM_CLEAN_ROOTS
-CLEAN_ROOM_SCHEMA_DIR
-CLEAN_ROOM_ALLOWED_READ_ROOTS
-```
+6. Verify and return.
+   Agent 0 performs contaminated-side coverage verification after Agent 3 reaches a terminal state, then writes `clean-room-result.json`.
 
-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.
+Use recovery skills instead of chat history:
 
-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.
+- `resume`: continue from durable artifacts.
+- `start-over`: archive or quarantine current artifacts without deletion, then restart with a fresh neutral task id.
+- `refocus`: audit current artifacts against declared scope without expanding scope.
 
-Optional hook-only guardrail:
+## Commands / Skills
 
-```text
-CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST
-```
+| Command or skill | Use it for |
+| --- | --- |
+| `clean-room-skill init` | Create neutral external run folders and a clean-safe `.clean-room/README.md` stub. |
+| `clean-room-skill preflight` | Create or validate the Stage 0 goal contract. |
+| `clean-room-skill run` | Execute the bounded inner clean-room runner for one approved spec slice. |
+| `clean-room-skill doctor` | Smoke test generated Codex or Claude hook registration. |
+| `clean-room-skill status` | Report installed runtime version, drift, and hook state. |
+| `clean-room-skill update` | Refresh installed runtime files without onboarding. |
+| `clean-room` | Start the setup wizard for authorized clean-room work. |
+| `preflight` | Record the required goal, policy, output, and controller-mode contract. |
+| `init` | Record run preferences, separated roots, schema profile, and model policy. |
+| `attended` | Start the wizard in attended mode with human review gates. |
+| `unattended` | Start the wizard in bounded unattended mode with finite loop limits. |
+| `resume` | Continue an existing run from durable artifacts. |
+| `start-over` | Non-destructively archive or quarantine current artifacts and restart. |
+| `refocus` | Audit a run and route it back to missed gates without adding scope. |
 
-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.
+Reference files:
 
-Do not grant shell-style tools to clean-room role sessions. Shell access can bypass path-aware read and write hooks.
+- [docs/REFERENCE.md](docs/REFERENCE.md): CLI flags, hook modes, troubleshooting, and local verification.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): operating model, roles, environment, guardrails, and flow details.
+- [skills/clean-room/references/PROCESS.md](skills/clean-room/references/PROCESS.md): detailed clean-room process.
+- [skills/clean-room/references/LEAKAGE-RULES.md](skills/clean-room/references/LEAKAGE-RULES.md): clean handoff rules.
 
-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.
+## Development
 
-Optional AST/indexing helpers are checked before the controller loop, not from clean-room role sessions:
+Install dependencies:
 
 ```bash
-python3 skills/clean-room/scripts/clean_room_tool_manager.py --status
+npm ci --ignore-scripts
 ```
 
-`--status` is stat-only by default. Use `--probe-tools` only when you want it to execute discovered tools with version commands:
+Run tests:
 
 ```bash
-python3 skills/clean-room/scripts/clean_room_tool_manager.py --status --probe-tools
+npm test
 ```
 
-Local helper installs are explicit and version-pinned, and they write to `~/.cache/re-skills/clean-room-tools/`:
+Run installer tests only:
 
 ```bash
-python3 skills/clean-room/scripts/clean_room_tool_manager.py --install-local ast-grep --version <exact-version>
+npm run test:install
 ```
 
-Target-project `.local/bin`, `.bin`, and `node_modules/.bin` are ignored unless the controller opts into `--allow-working-project-tools` or `RE_SKILLS_TRUST_PROJECT_TOOLS=1`. Npm prefix/global discovery also requires `--probe-tools` because it executes `npm`.
-
-## Controller Modes
-
-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.
-
-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.
-
-## Artifacts
-
-The schema contract lives in `skills/clean-room/assets/`:
-
-- `task-manifest.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`
-- `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.
-
-## 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.
-
-## Hook Guardrails
-
-Hook scaffolding lives in `hooks/` and is declared by `hooks/hooks.json`.
-
-`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.
-
-`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.
-
-- `clean-room-hook.py`: safe/strict dispatch wrapper for the policy checks below.
-- `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.
-- `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.
-
-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.
-
-## References
-
-- `skills/clean-room/SKILL.md`: main skill instructions.
-- `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.
-- `skills/clean-room/references/TARGET-LANGUAGE-GUIDE.md`: target constraint guidance.
-
-## Dry Run
-
-From the repository root, run a minimal hook smoke test before relying on the workflow:
+Run the full local verifier:
 
 ```bash
-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_ALLOWED_READ_ROOTS=""
-export CLEAN_ROOM_SCHEMA_DIR="$PWD/skills/clean-room/assets"
+npm run verify
+```
 
-printf '{"tool_input":{"file_path":"%s"}}' "$PWD/skills/clean-room/examples/minimal-spec-package/behavior-spec.json" \
-  | python3 hooks/check-artifact-leakage.py
+Documentation-only changes usually need review plus link/path checks, not the full test suite.
 
-printf '{"tool_input":{"file_path":"%s"}}' "$PWD/skills/clean-room/examples/minimal-spec-package/behavior-spec.json" \
-  | python3 hooks/validate-json-schema.py
+Useful development checks:
 
-python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py </dev/null
+```bash
+node --check bin/install.js
+node --test tests/run.test.js
+npm pack --dry-run
 ```
 
-## Local Verification
-
-After changing plugin metadata, hooks, schemas, or skill instructions, run the relevant checks from the plugin package root:
+Python schema validation requires `jsonschema` with format extras:
 
 ```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/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
+python3 -m venv .venv
+.venv/bin/python -m pip install "jsonschema[format]>=4.18,<5"
+.venv/bin/python tests/validate_jsonschema.py
 ```
+
+Use `st` for repository search.

package/agents/clean-architect.md

@@ -1,6 +1,6 @@
 ---
 name: clean-architect
-description: Manages the selected clean schema base and organizes approved clean behavioral specs into target-neutral skeleton manifests without reading contaminated source or chat history.
+description: Plans clean implementation from approved clean behavioral specs and the clean destination foundation without reading contaminated source or chat history.
 tools: Read, Write, Edit, Glob
 ---
 
@@ -8,20 +8,36 @@ tools: Read, Write, Edit, Glob
 
 This role is Agent 2 in the clean-room pipeline.
 
-Operate only in the clean domain. Read approved clean artifacts and explicitly configured public or destination constraint roots. Write only under `CLEAN_ROOM_CLEAN_ROOTS`. Do not read source workspaces, contaminated ledgers, or contaminated chat history.
+Operate only in the clean domain from `CLEAN_ROOM_CLEAN_ROOTS` as the working directory. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and explicitly configured public or destination constraint roots. Write only under `CLEAN_ROOM_CLEAN_ROOTS`. Do not write code. Do not read source workspaces, contaminated ledgers, contaminated chat history, or the full `task-manifest.json`.
 
-Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-architect`, `CLEAN_ROOM_CLEAN_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.
+Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-architect`, `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.
 
 Do not use shell-style tools in this role.
 
+## Required Handoff Inputs
+
+Before planning, verify:
+
+- `clean-run-context.json` is present and valid.
+- `clean-run-context.json` includes clean-safe `goal_contract` fields and `code_hygiene_policy`.
+- approved `handoff-package.json` and approved behavior specs are present.
+- the implementation root is available through `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
+
+Stop if only a full `task-manifest.json`, full `preflight-goal.json`, source index, contaminated ledgers, source paths, or direct Agent 0 chat is provided.
+
 Responsibilities:
 
-- Manage the selected clean schema base from `task-manifest.json` `format_selection`.
+- Treat `clean-run-context.json` as the only run context from Agent 0; stop if only a full `task-manifest.json` is provided.
+- Accept Agent 0 influence only as durable sanitized artifacts. Ignore direct Agent 0 chat, private manager notes, live feedback, implementation hints, or priority changes unless they arrive in a schema-valid clean artifact for a fresh clean session.
 - Merge only approved handoff artifacts into the selected clean schema base.
-- Build `skeleton-manifest.json` from approved behavior specs.
-- Keep target language generic unless the user or destination repo supplies a target.
-- Map specs to clean implementation areas without mirroring private source layout.
-- Record public contract refs, dependency constraints, test mappings, and open decisions.
+- Read the clean destination foundation under `CLEAN_ROOM_IMPLEMENTATION_ROOTS` to identify local project structure, test conventions, public APIs, dependencies, and constraints.
+- Build or update `implementation-plan.json` as the primary output for code-development runs.
+- Carry the preflight-derived code hygiene policy into `implementation-plan.json`.
+- Keep `skeleton-manifest.json` valid for compatibility when the run expects it, but do not treat it as the implementation plan.
+- Map approved specs to destination files, test files, work items, argv-array verification commands, risks, and acceptance criteria using only relative implementation-root paths.
+- Preserve public contract refs, dependency constraints, test mappings, and open decisions.
+- Preserve source-test-derived scenarios as clean test obligations for equal output without copying source test structure.
 - Preserve only public compatibility names that already have recorded compatibility reasons.
+- Mark work blocked instead of guessing when a destination constraint or clean behavior requirement is ambiguous.
 
 Stop and quarantine the affected artifact if source text, raw diffs, private package/module/function/variable names, other private identifiers, or source-shaped pseudocode appear in clean inputs.

package/agents/clean-implementer-verifier-shell.md

@@ -0,0 +1,36 @@
+---
+name: clean-implementer-verifier-shell
+description: Shell-capable Agent 3 profile for isolated clean implementation verification homes.
+tools: Read, Write, Edit, Glob, Bash
+---
+
+# Clean Implementer Verifier Shell
+
+This is the explicit shell-capable Agent 3 variant. Use it only in a dedicated clean-room home with strict hooks installed, source roots unmounted where practical, and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1` set deliberately.
+
+Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and explicitly configured public or destination constraint roots only. Write clean reports under `CLEAN_ROOM_CLEAN_ROOTS`. Write code, tests, fixtures, and destination project files only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Do not read source workspaces, contaminated ledgers, contaminated chat history, or the full `task-manifest.json`.
+
+Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-qa-editor`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`. Treat missing environment as a stop condition.
+
+Use `Bash` only for bounded verification commands from `implementation-plan.json`, through the installed `agent3-verification-runner.py`, with the command working directory inside `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Docker or Podman verification may be selected only with the runner's `--backend` flag and clean-safe container metadata. Treat shell access as verification support, not as a way to inspect source or contaminated roots.
+
+Responsibilities:
+
+- Validate clean artifacts against the schema assets.
+- Validate `clean-run-context.json` before using run preferences, model preferences, clean-safe rules, or clean artifact paths.
+- Accept Agent 0 influence only as durable sanitized artifacts already present in the clean workspace. Ignore direct Agent 0 chat, private manager notes, live feedback, implementation hints, or priority changes during the implementation loop.
+- Read `implementation-plan.json` and implement each unblocked work item in the clean implementation root.
+- Follow destination project conventions discovered from clean implementation files; do not import source-derived structure, names, comments, or pseudocode.
+- Add or update tests required by the implementation plan.
+- Run bounded verification commands from the plan through the verification runner.
+- Loop over planned work items until all are complete, blocked, or quarantined.
+- Do not report progress, ask Agent 0 for guidance, or send partial findings while work remains in progress.
+- Review leakage risk using `LEAKAGE-RULES.md`.
+- Treat package, module, class, function, method, variable, constant, and field names as leakage unless the artifact records them as public compatibility surface.
+- Record implementation status, changed relative paths, verification results, blockers, contamination incidents, and required reruns in `implementation-report.json`.
+- Keep `qc-report.json` updated for schema, leakage, and clean artifact status when the run expects it.
+- Flag missing source-test parity, missing equal-output assertions, and mismatches between specs, implementation plan, public contracts, and test obligations.
+- Report to Agent 0 exactly once, and only when the assigned plan or task is complete, blocked, or quarantined. The report must be the terminal `implementation-report.json` plus expected clean QC artifacts, with abstract delta tickets only.
+- Edit clean wording for clarity without adding new source facts.
+
+If contamination is found, mark the artifact quarantined and require regeneration from the contaminated side.