clean-room-skill 0.1.13 → 0.1.14

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.13",
+      "version": "0.1.14",
       "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.13",
+  "version": "0.1.14",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/README.md

@@ -99,7 +99,7 @@ In Claude Code, invoke skills with the plugin namespace:
 /clean-room
 /clean-room:attended
 /clean-room:unattended
-/clean-room:resume
+/clean-room:resume-cr
 /clean-room:start-over
 /clean-room:refocus
 ```
@@ -114,7 +114,7 @@ In Pi, invoke package skills with `/skill:<name>`:
 /skill:clean-room
 /skill:attended
 /skill:unattended
-/skill:resume
+/skill:resume-cr
 /skill:start-over
 /skill:refocus
 ```
@@ -156,7 +156,7 @@ In strict context-management mode, every `agent-commands.json` stage must set `c
 
 Use recovery skills instead of chat history:
 
-- `/clean-room:resume`: continue from durable artifacts.
+- `/clean-room:resume-cr`: continue from durable artifacts.
 - `/clean-room:start-over`: archive or quarantine current artifacts without deletion, then restart with a fresh neutral task id.
 - `/clean-room:refocus`: audit current artifacts against declared scope without expanding scope.
 
@@ -190,7 +190,7 @@ Use recovery skills instead of chat history:
 
 | Skill | Use it for |
 | --- | --- |
-| `/clean-room:resume` | Continue an existing run from durable artifacts. |
+| `/clean-room:resume-cr` | Continue an existing run from durable artifacts. |
 | `/clean-room:start-over` | Non-destructively archive or quarantine current artifacts and restart. |
 | `/clean-room:refocus` | Audit a run and route it back to missed gates without adding scope. |
 

package/docs/HOOKS.md

@@ -68,6 +68,7 @@ Role sessions must provide the full clean-room environment block so the hooks ca
 | `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST` | Optional path-separated denylist files for leakage scanning. |
 | `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` | Optional path-separated allowlist for unrecognized auxiliary JSON files under clean roots. |
 | `CLEAN_ROOM_ALLOW_AGENT3_SHELL` | Must be `1` before Agent 3 can invoke the verification runner through a shell-style tool. |
+| `CLEAN_ROOM_ALLOW_AGENT4_SHELL` | Must be `1` before Agent 4 can invoke the polish runner through a shell-style tool. |
 | `CLEAN_ROOM_HOOK_ENFORCE` | Forces enforcement in `safe` mode when truthy. |
 | `CLEAN_ROOM_HOOK_CHECK_TIMEOUT_SECONDS` | Optional per-check wrapper timeout. Defaults to 10 seconds. |
 

package/hooks/agent3-verification-runner.py

@@ -472,6 +472,8 @@ def run_command(
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         timeout=effective_timeout,
         shell=False,
         check=False,

package/hooks/agent4-polish-runner.py

@@ -138,6 +138,8 @@ def run_command(argv: list[str], cwd: Path, timeout: int, blocked_roots: list[Pa
         cwd=cwd,
         env=safe_env(blocked_roots),
         text=True,
+        encoding="utf-8",
+        errors="replace",
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         shell=False,

package/package.json

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

package/plugin.json

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

package/skills/attended/SKILL.md

@@ -13,7 +13,7 @@ In Pi, this entry point is invoked as `/skill:attended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
+Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
 Load or create `preflight-goal.json` first. Attended mode may continue with unresolved questions only when they are recorded as `open_questions`; blocking questions become pause gates before affected work starts.
 
@@ -30,4 +30,4 @@ Before indexing or artifact generation, confirm that source roots, contaminated
 
 Record `preflight_goal_ref`, `preflight_goal_sha256`, required `handoff_sequence`, and `controller_policy.mode` as `attended`. Pause for human review at preflight open questions, scope gate, clean handoff, terminal implementation or polish deltas, blocked units, and final coverage. Include stop conditions for `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, and `coverage-complete`; attended mode does not add an iteration-limit stop unless the user explicitly sets one.
 
-For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, guide agent zero/controller to run `skills/clean-room/scripts/build_visual_index.py` instead, store `visual-index.json` only under the contaminated artifact root, include visual roots in `CLEAN_ROOM_SOURCE_ROOTS`, and pause before decomposition to clarify the product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and public-compatibility status of visible words.
+For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, guide agent zero/controller to run `skills/clean-room/scripts/build_visual_index.py` instead, store `visual-index.json` only under the contaminated artifact root, include visual roots in `CLEAN_ROOM_SOURCE_ROOTS` (ensuring screenshot evidence directories are explicitly added to `CLEAN_ROOM_SOURCE_ROOTS` during execution so that path-aware read hooks such as `hooks/deny-clean-source-read.py` can protect them as expected), and pause before decomposition to clarify the product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and public-compatibility status of visible words.

package/skills/clean-room/SKILL.md

@@ -62,7 +62,7 @@ Post-write hook failures are policy failures, not implementation guidance. If a
 
 Use the recovery skills when a run already has durable artifacts:
 
-- `resume`: reload `task-manifest.json`, its `initialization_snapshot`, ledgers, `implementation-plan.json`, `implementation-report.json`, `qc-report.json`, and abstract delta tickets, then continue from the earliest incomplete gate using the recorded `controller_policy`. If `init-config.json` differs from the snapshot, report drift and wait for explicit confirmation.
+- `resume-cr`: reload `task-manifest.json`, its `initialization_snapshot`, ledgers, `implementation-plan.json`, `implementation-report.json`, `qc-report.json`, and abstract delta tickets, then continue from the earliest incomplete gate using the recorded `controller_policy`. If `init-config.json` differs from the snapshot, report drift and wait for explicit confirmation.
 - `start-over`: after explicit confirmation, non-destructively archive or quarantine existing artifacts and restart from the scope gate with a fresh `task_id`.
 - `refocus`: audit declared scope against current artifacts and steer the workflow back to missed gates without expanding scope.
 
@@ -84,7 +84,7 @@ If more than one candidate run is found without an explicit user path, list the
 
 Classify the selected candidate before starting the wizard:
 
-- Valid `task-manifest.json`: route to `resume` and continue from the earliest incomplete gate.
+- Valid `task-manifest.json`: route to `resume-cr` and continue from the earliest incomplete gate.
 - Valid canonical `preflight-goal.json` without `task-manifest.json`: continue at source/destination discovery and manifest creation. Do not ask the preflight wizard again.
 - `clean-room-bootstrap.json` only: run preflight using the bootstrap roots.
 - Invalid `preflight-goal.json`: stop, report canonical schema or required-field errors, and do not create a replacement preflight.

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

@@ -75,6 +75,6 @@ When `context_management.enforcement` is `strict`, no role can start until Agent
 
 ## Recovery
 
-`resume` and `refocus` must stop when new-run artifacts lack `preflight_goal_ref`, `preflight_goal_sha256`, or a complete `handoff_sequence`. Report this as legacy or incomplete preflight state; do not infer intent from prior chat or source.
+`resume-cr` and `refocus` must stop when new-run artifacts lack `preflight_goal_ref`, `preflight_goal_sha256`, or a complete `handoff_sequence`. Report this as legacy or incomplete preflight state; do not infer intent from prior chat or source.
 
 `start-over` must create a new preflight goal or explicitly reuse a reviewed goal contract before recreating active artifacts.

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

@@ -104,7 +104,7 @@ The durable tasklist is `task-manifest.json` `units`, generated by agent zero du
 
 Use recovery entry points only when durable artifacts already exist:
 
-- `resume`: reload the manifest, referenced preflight goal, initialization snapshot, ledgers, clean run context, handoff artifacts, implementation plan, implementation report, QC report, and abstract delta tickets; validate schema and leakage state; continue from the earliest incomplete gate under the recorded controller policy. Agent 0 may write or refresh `controller-status.json`, then create the next role-specific `role-session-brief.json`. Clean roles must receive the brief and clean artifact refs, not full resume state. If reusable `init-config.json` differs from the manifest snapshot, report drift and stop before applying changes. If new-run artifacts lack preflight refs or handoff sequence, stop for reviewed preflight migration.
+- `resume-cr`: reload the manifest, referenced preflight goal, initialization snapshot, ledgers, clean run context, handoff artifacts, implementation plan, implementation report, QC report, and abstract delta tickets; validate schema and leakage state; continue from the earliest incomplete gate under the recorded controller policy. Agent 0 may write or refresh `controller-status.json`, then create the next role-specific `role-session-brief.json`. Clean roles must receive the brief and clean artifact refs, not full resume state. If reusable `init-config.json` differs from the manifest snapshot, report drift and stop before applying changes. If new-run artifacts lack preflight refs or handoff sequence, stop for reviewed preflight migration.
 - `start-over`: require explicit confirmation, archive or quarantine current artifacts without deletion, then return to the preflight gate with a fresh `task_id`.
 - `refocus`: compare current artifacts to declared scope and preflight goal, identify missed gates or open deltas, and steer Agent 0 back to the earliest required gate without expanding scope.
 

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

@@ -112,7 +112,7 @@ Capture:
 - user rules split into `clean_safe` and `contaminated_only`
 - reconfiguration policy requiring confirmation for root, schema, and model changes
 
-`clean-run-context.json` is the only run context Agent 2, Agent 3, and Agent 4 should read. It may contain clean artifact paths, implementation root environment references, target profile, native artifact expectations, clean-safe goal contract fields, code hygiene policy, approved public references, clean-safe rules, clean-side model preferences, optional Agent 4 local commit policy, and the artifact-only coordination boundary. It must not contain source roots, visual roots, contaminated artifact roots, source index refs, visual index refs, coverage ledgers, evidence ledgers, contaminated-only rules, full `preflight-goal.json`, or the full `task-manifest.json`.
+`clean-run-context.json` is the only run context Agent 2, Agent 3, and Agent 4 should read. It may contain clean artifact paths, implementation root environment references, target profile, native artifact expectations, clean-safe goal contract fields, code hygiene policy, approved public references, clean-safe rules, clean-side model preferences, optional Agent 4 local commit policy (e.g. `implementation.polish_commit` with `agent4_shell_allowed`, `cwd_policy`, and `git_policy`), and the artifact-only coordination boundary. It must not contain source roots, visual roots, contaminated artifact roots, source index refs, visual index refs, coverage ledgers, evidence ledgers, contaminated-only rules, full `preflight-goal.json`, or the full `task-manifest.json`.
 
 `context_management` is optional on `task-manifest.json` and `clean-run-context.json`. When present with `mode: "role-session-briefs"`, it records advisory or strict enforcement plus budgets for prompt characters, brief characters, artifact refs, and referenced artifact bytes. Strict mode requires a fresh role session and a valid `role-session-brief.json` for each stage.
 

package/skills/{resume → resume-cr}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: resume
+name: resume-cr
 description: Continues an existing Clean Room run from durable artifacts without relying on prior chat history.
 argument-hint: [existing task-manifest.json or artifact roots]
 disable-model-invocation: true

package/skills/unattended/SKILL.md

@@ -13,7 +13,7 @@ In Pi, this entry point is invoked as `/skill:unattended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` before defining unattended loop behavior. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
+Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
 Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, and a finite `controller_policy.max_iterations`.
 
@@ -36,4 +36,4 @@ Record `preflight_goal_ref`, `preflight_goal_sha256`, required `handoff_sequence
 
 The inner loop returns only after Agent 0 consumes the terminal Agent 3 report, any configured Agent 4 `polish-report.json`, and completes contaminated-side coverage verification. Write `clean-room-result.json` before returning control to the outer spec loop.
 
-For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, unattended mode may use `skills/clean-room/scripts/build_visual_index.py` only after preflight already answers the visual-fallback questions with no open questions. Store `visual-index.json` only under the contaminated artifact root and include visual roots in `CLEAN_ROOM_SOURCE_ROOTS`.
+For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, unattended mode may use `skills/clean-room/scripts/build_visual_index.py` only after preflight already answers the visual-fallback questions with no open questions. Store `visual-index.json` only under the contaminated artifact root and include visual roots in `CLEAN_ROOM_SOURCE_ROOTS` (ensuring screenshot evidence directories are explicitly added to `CLEAN_ROOM_SOURCE_ROOTS` during execution so that path-aware read hooks such as `hooks/deny-clean-source-read.py` can protect them as expected).