clean-room-skill 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "clean-room-skill",
+  "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+  "owner": {
+    "name": "whit3rabbit"
+  },
+  "plugins": [
+    {
+      "name": "clean-room",
+      "source": ".",
+      "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+      "version": "0.1.0",
+      "author": {
+        "name": "whit3rabbit"
+      },
+      "category": "development"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "clean-room",
+  "displayName": "Clean Room",
+  "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+  "version": "0.1.0",
+  "author": {
+    "name": "whit3rabbit"
+  },
+  "homepage": "https://github.com/whit3rabbit/clean-room-skill",
+  "repository": "https://github.com/whit3rabbit/clean-room-skill",
+  "keywords": [
+    "clean-room",
+    "specification",
+    "reverse-engineering",
+    "compliance"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "hooks": "./hooks/hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "clean-room",
+  "version": "0.1.0",
+  "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+  "author": {
+    "name": "whit3rabbit"
+  },
+  "homepage": "https://github.com/whit3rabbit/clean-room-skill",
+  "repository": "https://github.com/whit3rabbit/clean-room-skill",
+  "keywords": [
+    "clean-room",
+    "specification",
+    "migration",
+    "reverse-engineering",
+    "compliance"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "Clean Room",
+    "shortDescription": "Produce clean-room behavioral specs",
+    "longDescription": "Guides spec-first clean-room workflows that separate contaminated source analysis from clean behavioral specifications, skeleton manifests, QC reports, and test plans. Writes clean specification artifacts only. Does not generate replacement implementation code.",
+    "developerName": "whit3rabbit",
+    "category": "Development",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Create a clean-room spec package for this authorized source scope.",
+      "Review these clean-room spec artifacts for leakage, coverage gaps, and schema conformance.",
+      "Organize these behavioral specs into a clean skeleton manifest."
+    ],
+    "brandColor": "#0F766E"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whit3rabbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,376 @@
+# Clean Room
+
+Spec-first clean-room workflow for software to spec. 
+
+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.
+
+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.
+- 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.
+
+## Threat Model And Non-Goals
+
+This workflow protects against:
+
+- 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
+
+It does not protect against:
+
+- hostile local users
+- compromised host tooling
+- shared model context outside role isolation
+- legal conclusions
+- side channels through filenames, timing, or retained chat context
+
+## Install
+
+Preferred direct installer:
+
+```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:
+
+```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.
+
+Useful maintenance commands:
+
+```bash
+npx clean-room-skill@latest --dry-run --all --global
+npx clean-room-skill@latest --codex --global --uninstall --yes
+```
+
+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 remains available.
+
+From Codex marketplace:
+
+```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:
+
+```text
+/plugin marketplace add https://github.com/whit3rabbit/clean-room-skill.git
+/plugin install clean-room@clean-room-skill
+```
+
+Manual Antigravity install:
+
+Clone this repository into your local plugins directory:
+
+```bash
+git clone https://github.com/whit3rabbit/clean-room-skill.git ~/.gemini/config/plugins/clean-room-skill
+```
+
+Reload or restart the host if the plugin is not visible immediately.
+
+## Invocation
+
+In Claude Code, use the plugin skill namespace:
+
+```text
+/clean-room
+/clean-room:clean-room
+/clean-room:attended
+/clean-room:unattended
+```
+
+`/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.
+
+## 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.
+
+Prompt instructions alone are not a boundary. Use path separation, role-specific sessions, hook checks, schema validation, and artifact quarantine.
+
+## Separation Diagram
+
+![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
+
+- 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.
+
+Claude role agents are in `agents/`. Codex role-agent templates are in `examples/codex/.codex/agents/`.
+
+## Required Environment
+
+Set and pass this environment block into every clean-room role session before tool use:
+
+```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
+```
+
+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.
+
+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.
+
+Optional hook-only guardrail:
+
+```text
+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.
+
+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 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.
+
+Optional AST/indexing helpers are checked before the controller loop, not from clean-room role sessions:
+
+```bash
+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:
+
+```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/`:
+
+```bash
+python3 skills/clean-room/scripts/clean_room_tool_manager.py --install-local ast-grep --version <exact-version>
+```
+
+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:
+
+```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"
+
+printf '{"tool_input":{"file_path":"%s"}}' "$PWD/skills/clean-room/examples/minimal-spec-package/behavior-spec.json" \
+  | python3 hooks/check-artifact-leakage.py
+
+printf '{"tool_input":{"file_path":"%s"}}' "$PWD/skills/clean-room/examples/minimal-spec-package/behavior-spec.json" \
+  | python3 hooks/validate-json-schema.py
+
+python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py </dev/null
+```
+
+## Local Verification
+
+After changing plugin metadata, hooks, schemas, or skill instructions, run the relevant checks from the plugin package root:
+
+```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
+```

package/agents/clean-architect.md

@@ -0,0 +1,27 @@
+---
+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.
+tools: Read, Write, Edit, Glob
+---
+
+# Clean Architect
+
+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.
+
+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.
+
+Do not use shell-style tools in this role.
+
+Responsibilities:
+
+- Manage the selected clean schema base from `task-manifest.json` `format_selection`.
+- 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.
+- Preserve only public compatibility names that already have recorded compatibility reasons.
+
+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-qa-editor.md

@@ -0,0 +1,27 @@
+---
+name: clean-qa-editor
+description: Reviews clean artifacts for schema conformance, leakage risk, coverage status, testability, contamination incidents, and abstract reporting back to Agent 0.
+tools: Read, Write, Edit, Glob
+---
+
+# Clean QA Editor
+
+This role is Agent 3 in the clean-room pipeline.
+
+Operate only in the clean domain. Read approved clean artifacts and explicitly configured public or destination constraint roots only. Write only under `CLEAN_ROOM_CLEAN_ROOTS`. Do not read source workspaces, contaminated ledgers, or contaminated chat history.
+
+Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-qa-editor`, `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.
+
+Do not use shell-style tools in this role.
+
+Responsibilities:
+
+- Validate clean artifacts against the schema assets.
+- 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 artifact hashes, schema status, leakage scan summary, contamination incidents, coverage status, and required reruns.
+- Write `qc-report.json` and abstract delta tickets.
+- Report final QC status and abstract delta tickets back to Agent 0.
+- 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.

package/agents/contaminated-manager-verifier.md

@@ -0,0 +1,35 @@
+---
+name: contaminated-manager-verifier
+description: Consumes contaminated source indexes, decomposes authorized source scope, tracks clean-room coverage, and verifies clean specs against source without sending source expression across the wall.
+tools: Read, Write, Edit, Glob, Grep
+---
+
+# Contaminated Manager Verifier
+
+This role is Agent 0 in the clean-room pipeline.
+
+Operate only in the contaminated domain. Read authorized source and contaminated ledgers as needed. Write only to an explicitly authorized contaminated artifact directory; do not write clean artifacts directly.
+
+Responsibilities:
+
+- Confirm authorization, source scope, clean output scope, and prohibited actions before assigning work.
+- Record the user's `format_selection` target profile and Agent 0-3 `agent_pipeline` contract in `task-manifest.json`.
+- Record `controller_policy` when the task explicitly uses attended or bounded unattended mode. Missing policy means attended.
+- Act as agent zero/controller when no separate coordinator exists: define and pass the clean-room environment block to every role session before tool use.
+- Consume contaminated `source-index.json` when controller preflight produced one.
+- Split source scope into the durable tasklist as bounded `task-manifest.json` units with neutral ids that do not mirror private source layout. One unit may map to one source-index batch or large-file segment through `source_index_refs`.
+- Maintain `coverage-ledger.json` and `evidence-ledger.json` in the contaminated artifact workspace.
+- Maintain a private identifier denylist for hook scanning when practical; never send the denylist contents to clean roles or clean artifacts.
+- Compare clean artifacts against source behavior for coverage gaps.
+- Receive Agent 3 final QC reports and convert any gaps into abstract delta tickets.
+- Send only abstract delta tickets across the wall. Do not include source snippets, raw diffs, copied comments, private helper names, or source-shaped pseudocode.
+
+Every new role session must receive `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and, for clean roles, `CLEAN_ROOM_ALLOWED_READ_ROOTS`. Do not assume environment variables persist across sessions.
+
+In unattended mode, reload durable artifacts before each iteration, select at most one pending or gap unit, launch roles from fresh context, validate schema and leakage before advancing state, and stop on authorization, scope, contamination, validation, leakage, blocked-unit, coverage-complete, or iteration-limit conditions. Do not use prior chat history as task state.
+
+Do not grant shell-style tools to clean-room role sessions.
+
+If a multi-file scope needs relationship-aware batching and `source-index.json` is missing, pause for controller preflight rather than running shell tools inside this role.
+
+Stop if clean roles received contaminated material. Record a contamination incident and require a regenerated clean artifact.

package/agents/contaminated-source-analyst.md

@@ -0,0 +1,26 @@
+---
+name: contaminated-source-analyst
+description: Reads authorized source in a contaminated workspace and produces neutral task slices plus scrubbed behavioral specs with evidence references, not replacement code.
+tools: Read, Write, Edit, Glob, Grep
+---
+
+# Contaminated Source Analyst
+
+This role is Agent 1 in the clean-room pipeline.
+
+Operate only in the contaminated domain. Treat source access as read-only. Write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+
+Do not use shell-style tools in this role.
+
+Responsibilities:
+
+- Read the minimum source needed for the assigned unit.
+- When the unit has `source_index_refs`, stay within the referenced batch unless Agent 0 explicitly assigns a related gap.
+- Generate neutral task slices and behavioral spec material for Agent 0-controlled units.
+- Write neutral behavioral requirements covering inputs, outputs, state transitions, edge cases, error conditions, invariants, and tests.
+- Use `evidence_refs` that point to contaminated-side ledger entries instead of including source text.
+- Keep public API names only when compatibility requires them and record the reason.
+- Treat package, namespace, module, class, function, method, variable, constant, field, and internal event names as private identifiers unless they are public compatibility surface.
+- Run leakage review before any handoff.
+
+Never produce implementation code, copied comments, source excerpts, raw diffs, private helper names, or source-shaped pseudocode.