clean-room-skill 0.1.11 → 0.1.13

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "clean-room",
       "source": "./",
       "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-      "version": "0.1.11",
+      "version": "0.1.13",
       "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.11",
+  "version": "0.1.13",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/README.md

@@ -52,10 +52,10 @@ Claude global installs use Claude's plugin system for skills and agents, so entr
 Hook modes:
 
 - `--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=strict`: fail-closed hook mode for dedicated Codex, Claude, or OpenCode clean-room homes.
 - `--hooks=copy-only` or `--no-hooks`: copy hook files without registering runtime hook config.
 
-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.
+Verified runtimes are Codex, Claude Code, and OpenCode. OpenCode support uses native skills, commands, and a generated local plugin bridge for hook enforcement. 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.
 
 Marketplace install is also supported.
 
@@ -72,6 +72,15 @@ Claude Code:
 /plugin install clean-room@clean-room-skill
 ```
 
+Pi:
+
+```bash
+pi install npm:clean-room-skill@latest
+pi install https://github.com/whit3rabbit/clean-room-skill
+```
+
+Pi loads bundled skills as `/skill:<name>`, for example `/skill:clean-room`. Pi package install is skill compatibility only; it does not register clean-room hooks. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
+
 ## How To Run
 
 Optionally create neutral external run folders and a clean-safe repository stub:
@@ -97,6 +106,19 @@ In Claude Code, invoke skills with the plugin namespace:
 
 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.
 
+In Pi, invoke package skills with `/skill:<name>`:
+
+```text
+/skill:init
+/skill:preflight
+/skill:clean-room
+/skill:attended
+/skill:unattended
+/skill:resume
+/skill:start-over
+/skill:refocus
+```
+
 For unattended inner-loop execution from durable artifacts:
 
 ```bash
@@ -115,22 +137,22 @@ In strict context-management mode, every `agent-commands.json` stage must set `c
 ![Clean Room Architecture](assets/clean-room-arch.svg)
 
 1. Initialize or bootstrap the run.
-   Use `npx clean-room-skill@latest init` to create neutral external run folders and a clean-safe repository stub, or use `/clean-room:init` for skill-driven run preferences. The active `init-config.json` stays out of the clean implementation repository.
+   Use `npx clean-room-skill@latest init` to create neutral external run folders and a clean-safe repository stub, or use `/clean-room:init` in Claude Code or `/skill:init` in Pi for skill-driven run preferences. The active `init-config.json` stays out of the clean implementation repository.
 
 2. Record the goal contract.
    Use `npx clean-room-skill@latest preflight` or `/clean-room:preflight` before source discovery, attended mode, or unattended mode. This creates or validates `preflight-goal.json` on the contaminated/controller side.
 
 3. Start the controller.
-   Use `/clean-room` or `/clean-room:attended` for human review gates. Use `/clean-room:unattended` only after preflight allows bounded unattended work with finite iteration limits and no open questions.
+   Use `/clean-room` or `/clean-room:attended` in Claude Code, or `/skill:clean-room` or `/skill:attended` in Pi, for human review gates. Use unattended entry points only after preflight allows bounded unattended work with finite iteration limits and no open questions.
 
 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.
+   Source-reading roles produce neutral draft behavior specs and record contaminated-only `discovery_leads` when authorized related surfaces are detected but not analyzed in the assigned unit. A source-denied sanitizer reviews handoff candidates before anything enters the clean domain.
 
 5. Plan, implement, and polish.
-   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. Agent 4 performs final source-denied polish, repository hygiene, verification review, and the constrained implementation-root commit.
+   Clean roles read only approved clean artifacts and the clean destination foundation. The first approved code-development slice is the foundation unit; behavior slices wait until that unit is covered. Agent 2 writes `implementation-plan.json`; Agent 3 writes code/tests under the implementation root and reports under clean artifacts. Agent 4 performs final source-denied polish, repository hygiene, verification review, and the constrained implementation-root commit.
 
 6. Verify and return.
-   Agent 0 performs contaminated-side coverage verification after Agent 3 reaches a terminal state and any configured Agent 4 polish review passes, then writes `clean-room-result.json`.
+   Agent 0 performs contaminated-side coverage verification after Agent 3 reaches a terminal state and any configured Agent 4 polish review passes, rejects covered units with unresolved high-priority discovery leads, then writes `clean-room-result.json`.
 
 Use recovery skills instead of chat history:
 
@@ -144,18 +166,23 @@ Use recovery skills instead of chat history:
 | --- | --- | --- | --- |
 | 1 | `npx clean-room-skill@latest init` | CLI command | Create neutral external run folders and a clean-safe `.clean-room/README.md` stub. |
 | 1 | `/clean-room:init` | Skill | Record run preferences, separated roots, schema profile, and model policy. |
+| 1 | `/skill:init` | Pi skill | Record run preferences, separated roots, schema profile, and model policy. |
 | 2 | `npx clean-room-skill@latest preflight` | CLI command | Create or validate the Stage 0 goal contract. |
 | 2 | `/clean-room:preflight` | Skill | Record the required goal, policy, output, and controller-mode contract. |
+| 2 | `/skill:preflight` | Pi skill | Record the required goal, policy, output, and controller-mode contract. |
 | 3 | `/clean-room` | Skill | Start the setup wizard for authorized clean-room work. |
 | 3 | `/clean-room:attended` | Skill | Start the wizard in attended mode with human review gates. |
 | 3 | `/clean-room:unattended` | Skill | Start the wizard in bounded unattended mode with finite loop limits. |
+| 3 | `/skill:clean-room` | Pi skill | Start the setup wizard for authorized clean-room work. |
+| 3 | `/skill:attended` | Pi skill | Start the wizard in attended mode with human review gates. |
+| 3 | `/skill:unattended` | Pi skill | Start the wizard in bounded unattended mode with finite loop limits. |
 | 4 | `npx clean-room-skill@latest run` | CLI command | Execute the bounded inner clean-room runner for one approved spec slice. |
 
 ### Maintenance CLI Commands
 
 | Command | Use it for |
 | --- | --- |
-| `npx clean-room-skill@latest doctor` | Smoke test generated Codex or Claude hook registration. |
+| `npx clean-room-skill@latest doctor` | Smoke test generated Codex, Claude, or OpenCode hook registration. |
 | `npx clean-room-skill@latest status` | Report installed runtime version, drift, and hook state. |
 | `npx clean-room-skill@latest update` | Refresh installed runtime files without onboarding. |
 

package/agents/clean-architect.md

@@ -2,6 +2,9 @@
 name: clean-architect
 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
+model: opus
+effort: high
+color: blue
 ---
 
 # Clean Architect
@@ -22,6 +25,7 @@ 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.
+- for behavior slices, the approved clean artifacts include the completed foundation spec or equivalent clean-run-context constraints.
 - the implementation root is available through `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
 
 Stop if only a full `task-manifest.json`, full `preflight-goal.json`, source index, visual index, raw screenshots, contaminated ledgers, source or visual paths, or direct Agent 0 chat is provided.
@@ -32,7 +36,7 @@ Responsibilities:
 - When `CLEAN_ROOM_SESSION_BRIEF_PATH` is set, read it first and load only the allowed artifact refs named there, plus destination foundation reads permitted by this role. Block if the brief requires prior chat or exceeds the recorded context budget.
 - 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.
-- Read the clean destination foundation under `CLEAN_ROOM_IMPLEMENTATION_ROOTS` to identify local project structure, test conventions, public APIs, dependencies, and constraints.
+- Read the clean destination foundation under `CLEAN_ROOM_IMPLEMENTATION_ROOTS` and the approved foundation spec to identify local project structure, test conventions, public APIs, dependency policy, package boundaries, and constraints.
 - Read any existing `skeleton-manifest.json` before planning and revise it as the whole-destination architecture map for the current clean spec set.
 - Maintain clean architecture areas with owned relative path prefixes, responsibilities, forbidden responsibilities, allowed area dependencies, and refactor triggers.
 - Assign every implementation and test target path in `implementation-plan.json` to one or more architecture areas from `skeleton-manifest.json`.
@@ -42,6 +46,8 @@ Responsibilities:
 - Keep `skeleton-manifest.json` valid and current for code-development runs. Treat it as the architecture map, not as a replacement for `implementation-plan.json`.
 - 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.
+- Do not choose dependencies by copying source manifests. Add or preserve dependencies only when clean artifacts, destination evidence, or preflight policy justify them.
+- Map every exact-public-contract or behavior-compatible public surface obligation to at least one `implementation-plan.json` work item through `public_contract_refs`; do not replace a public command/API inventory with one generic dispatch work item unless every obligation ref is listed.
 - 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.
 - Do not resolve public-contract, callable, protocol, async, serialization, or data-shape ambiguity by narrowing semantics. Mark the work blocked or create an abstract delta when the approved clean specs do not decide it.

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

@@ -2,6 +2,9 @@
 name: clean-implementer-verifier-shell
 description: Shell-capable Agent 3 profile for isolated clean implementation verification homes.
 tools: Read, Write, Edit, Glob, Bash
+model: sonnet
+effort: high
+color: cyan
 ---
 
 # Clean Implementer Verifier Shell
@@ -31,6 +34,7 @@ Responsibilities:
 - Record implementation status, changed relative paths, verification results, blockers, contamination incidents, and required reruns in `CLEAN_ROOM_CLEAN_ROOTS/implementation-report.json`.
 - Keep `CLEAN_ROOM_CLEAN_ROOTS/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.
+- Verify public-surface inventory parity item by item. Every required `public_surface:<spec_id>:<kind>:<name>` ref must be covered by tests, mapped to a completed work item, and represented in terminal verification; passing test counts or broad command-dispatch coverage is not enough.
 - 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 `CLEAN_ROOM_CLEAN_ROOTS/implementation-report.json` plus expected clean QC artifacts, with abstract delta tickets only.
 - Edit clean wording for clarity without adding new source facts.
 

package/agents/clean-polish-reviewer.md

@@ -2,6 +2,9 @@
 name: clean-polish-reviewer
 description: Performs final source-denied clean code polish, repository hygiene, verification review, and constrained implementation-root commit after Agent 3 completes.
 tools: Read, Write, Edit, Glob
+model: sonnet
+effort: high
+color: pink
 ---
 
 # Clean Polish Reviewer

package/agents/clean-qa-editor.md

@@ -2,6 +2,9 @@
 name: clean-qa-editor
 description: Implements the clean implementation plan, verifies the clean destination code, records implementation status, and emits one terminal report for Agent 0.
 tools: Read, Write, Edit, Glob
+model: sonnet
+effort: high
+color: green
 ---
 
 # Clean Implementer Verifier
@@ -53,6 +56,7 @@ Responsibilities:
 - Keep `CLEAN_ROOM_CLEAN_ROOTS/qc-report.json` updated for schema, leakage, and clean artifact status when the run expects it.
 - Record architecture alignment in `CLEAN_ROOM_CLEAN_ROOTS/qc-report.json`. Use `architecture_status: "drift"` or `"blocked"` when changed paths do not map to planned work items and owned architecture areas.
 - Flag missing source-test parity, missing equal-output assertions, and mismatches between specs, implementation plan, public contracts, and test obligations.
+- Verify public-surface inventory parity item by item. Every required `public_surface:<spec_id>:<kind>:<name>` ref must be covered by tests, mapped to a completed work item, and represented in terminal verification; passing test counts or broad command-dispatch coverage is not enough.
 - Require invariant-level tests for compatibility-critical behavior. Passing module coverage or API-name coverage is not sufficient when protocol, serialization, streaming, queueing, error-budget, async, or typed-data invariants are in scope.
 - 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 `CLEAN_ROOM_CLEAN_ROOTS/implementation-report.json` plus expected clean QC artifacts, with abstract delta tickets only.
 - Edit clean wording for clarity without adding new source facts.

package/agents/contaminated-handoff-sanitizer.md

@@ -2,6 +2,9 @@
 name: contaminated-handoff-sanitizer
 description: Reviews Agent 1 draft specs from a fresh source-denied contaminated context, removes identifying material, and approves only scrubbed artifacts for clean handoff.
 tools: Read, Write, Edit, Glob
+model: sonnet
+effort: high
+color: yellow
 ---
 
 # Contaminated Handoff Sanitizer

package/agents/contaminated-manager-verifier.md

@@ -2,6 +2,9 @@
 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
+model: opus
+effort: high
+color: purple
 ---
 
 # Contaminated Manager Verifier
@@ -32,12 +35,18 @@ Responsibilities:
 - Consume contaminated `source-index.json` when controller preflight produced one.
 - When no indexable source code exists and screenshots/images are the authorized evidence, consume contaminated `visual-index.json` as fallback input only. In attended mode, pause before decomposition to ask what the screenshots are meant to accomplish: product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and whether visible words are public compatibility surface.
 - Split source scope into the durable tasklist as bounded `task-manifest.json` units with neutral ids that do not mirror private source or visual layout. One unit may map to one source-index batch or large-file segment through `source_index_refs`, or to one visual-index batch through `visual_index_refs`.
+- Create exactly one `unit_kind: "foundation"` unit before behavior units. Set `loop_context.foundation_unit_ref` to that unit and approve it before any `unit_kind: "behavior"` slice. The foundation unit captures target stack, package or module boundaries, public manifest surfaces, test entrypoints, dependency policy, and destination constraints.
 - 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 Agent 1.5, clean roles, or clean artifacts.
 - Provide Agent 1.5 only a neutral sanitizer brief with domain purpose, target profile, unit intent, public compatibility allowlist, and blocked categories.
 - Send Agent 1 draft specs to Agent 1.5 for independent source-denied sanitization before clean handoff.
+- Do not send a spec slice to handoff or mark coverage complete while the assigned unit has unresolved high-priority `coverage-ledger.json` `discovery_leads` or open discovery questions.
+- Do not approve or complete non-foundation behavior slices until the foundation unit is covered. Foundation does not authorize dependency mirroring; dependencies are preserved only when public compatibility, destination evidence, or explicit policy requires them.
+- When Agent 1 records `discovery_leads`, create neutral follow-up task units only when the lead is inside authorized scope. Do not silently expand `loop_context.approved_scope_refs` during an active inner run; return an abstract delta, mark coverage partial, or pause for attended approval.
+- For multi-segment source work, you may include a previous contaminated draft behavior spec in a later contaminated-analysis role-session brief only when it is under the contaminated artifact root, hash-checked, within context budgets, and still forbidden to clean or source-denied roles.
 - Compare clean artifacts and terminal implementation or polish reports against source behavior, discovered source tests, equal-output requirements, and public API/schema compatibility for coverage gaps.
 - Do not mark a unit complete from summaries, claimed test counts, or progress prose alone. Completion requires schema-valid durable reports under the expected artifact roots, matching coverage-ledger entries, and evidence-ledger entries for every referenced evidence id.
+- For exact-public-contract or behavior-compatible units, split broad public surfaces into smaller units or maintain `coverage-ledger.json` `public_surface_coverage` entries for every required `public_surface:<spec_id>:<kind>:<name>` obligation. A covered unit requires each obligation to be covered, mapped to clean work, and verified.
 - Source-backed units with `source_index_refs` or `visual_index_refs` must have durable source/evidence coverage before `coverage_state: "covered"`. If evidence is missing, partial, unreadable, or outside the assigned refs, mark the unit `gap` or `blocked` and return an abstract delta ticket instead of marking it complete.
 - For full-parity runs, do not defer TUI, command, CLI, protocol, streaming, MCP, tool, public error, or config behavior while reporting completion. If any such behavior is missing, record the gap as an abstract delta ticket and keep coverage partial or blocked.
 - Reject `complete` when source-test-derived parity, protocol invariants, public-contract tests, or approved behavior-spec open questions remain unresolved. Convert the gap into abstract delta tickets for a fresh clean cycle.
@@ -54,7 +63,7 @@ Use this file map when a CLI bootstrap is present:
 
 Every new role session must receive `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and, for clean or source-denied roles, `CLEAN_ROOM_ALLOWED_READ_ROOTS`. Do not assume environment variables persist across sessions.
 
-In unattended mode, reload durable artifacts before each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, launch roles from fresh context, validate schema and leakage before advancing state, and stop on authorization, scope, contamination, validation, leakage, blocked-unit, implementation-complete, coverage-complete, spec-slice, no-progress, repeated-selection, or iteration-limit conditions. Do not use prior chat history as task state.
+In unattended mode, reload durable artifacts before each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, require `loop_context.foundation_unit_ref` to point at the one foundation unit, launch roles from fresh context, validate schema and leakage before advancing state, and stop on authorization, scope, contamination, validation, leakage, blocked-unit, implementation-complete, coverage-complete, spec-slice, no-progress, repeated-selection, or iteration-limit conditions. Do not use prior chat history as task state.
 
 Role session briefs must contain only compact status, next action, allowed artifact refs with hashes, and forbidden inputs. Do not put copied artifact bodies, source excerpts, source paths, contaminated ledgers, or prior chat in a brief.
 

package/agents/contaminated-source-analyst.md

@@ -2,6 +2,9 @@
 name: contaminated-source-analyst
 description: Reads authorized source in a contaminated workspace and produces neutral draft task slices plus behavioral specs with evidence references, not replacement code.
 tools: Read, Write, Edit, Glob, Grep, view_image
+model: sonnet
+effort: medium
+color: orange
 ---
 
 # Contaminated Source Analyst
@@ -29,18 +32,22 @@ Do not infer target language, dependency policy, license policy, or exactness po
 
 Responsibilities:
 
-- Read the minimum source needed for the assigned unit.
+- Read the bounded source needed to fully inventory the assigned unit's observable surface. Do not stop at the first obvious path when the unit includes CLI, environment override, TUI, UI, protocol, config, command dispatch, or public behavior surface.
 - When `CLEAN_ROOM_SESSION_BRIEF_PATH` is set, read it first and load only the allowed artifact refs named there, except for direct source reads already permitted by the assigned unit and role policy.
 - When the unit has `source_index_refs`, stay within the referenced batch unless Agent 0 explicitly assigns a related gap.
 - When the unit has `visual_index_refs`, use `view_image` only in this contaminated role and stay within the referenced visual batch unless Agent 0 explicitly assigns a related gap.
 - Generate neutral draft 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.
+- For a `unit_kind: "foundation"` assignment, inventory target stack, package or module boundaries, public manifest surfaces, test entrypoints, dependency policy, and destination constraints. Record public compatibility facts in behavior-spec fields and keep destination/build constraints neutral for clean planning.
+- When relevant to the assigned unit, locate and account for every observable CLI argument, flag, environment variable override, TUI command, keyboard shortcut, menu state, associated UI element, view state, accessibility expectation, config key, protocol entry point, and public user-visible behavior.
+- If you detect related files, modules, visual components, or public surfaces that are inside authorized scope but outside the assigned refs or too large to analyze in the current context, record contaminated `coverage-ledger.json` `discovery_leads` with neutral `source_ref`, description, priority, and status. Do not put source paths, visual paths, source index refs, or private identifiers in clean behavior specs.
 - For visual fallback units, write UI behavior/spec claims about intent, screen states, hierarchy, accessibility expectations, interaction purpose, and broad style goals. Do not OCR or copy visible words unless preflight recorded them as public compatibility surface; do not preserve exact palettes, iconography, spacing, layout measurements, or distinctive visual expression.
 - Treat discovered source tests as behavioral evidence and convert them into clean `test_scenarios` that validate the same observable outputs.
 - Record equal-output expectations for public return values, serialized data, CLI or API responses, errors, state changes, ordering, and compatibility-relevant side effects.
 - 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.
 - Capture public API, protocol, config, and data/schema compatibility using existing behavior spec fields.
+- Do not mirror source dependency lists, package manifests, or private module layout. Mention a dependency only when it is public compatibility surface, destination evidence, or explicitly allowed by preflight policy.
 - For behavior-compatible ports, extract compatibility-critical invariants into `invariants`, `compatibility_notes`, and `test_scenarios`; broad module coverage is not enough.
 - When present, treat protocol transcript shape, request/response ID pairing, error budgets, streaming order, queue bounds, sampling registry aliases, async behavior, and typed JSON argument preservation as first-class observable behavior.
 - Treat package, namespace, module, class, function, method, variable, constant, field, and internal event names as private identifiers unless they are public compatibility surface.