clean-room-skill 0.1.15 → 0.2.1

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -42,6 +42,7 @@ 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 --pi --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
@@ -77,9 +78,14 @@ Pi:
 ```bash
 pi install npm:clean-room-skill@latest
 pi install https://github.com/whit3rabbit/clean-room-skill
+npx clean-room-skill@latest --pi --global --yes
 ```
 
-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.
+Pi-native package install is preferred. This package declares `pi.skills: ["./skills"]`, so `pi install npm:clean-room-skill@latest` lets Pi discover the bundled `SKILL.md` entry points directly. Use the `npx ... --pi` installer only when you want this repo's compatibility installer to manage the same files alongside other runtimes. Global Pi compatibility installs target `~/.pi/agent`; local installs target `.pi`.
+
+Both Pi install paths load bundled skills as `/skill:<name>`, for example `/skill:clean-room`. Pi installs do not currently register clean-room hooks. Installer-managed Pi layouts copy the hook scripts to `hooks/clean-room/` for inspection and future bridge work, but those files are not active enforcement in Pi.
+
+Pi hook enforcement would need a Pi extension, not a `settings.json` edit. Pi extensions can subscribe to tool events such as `tool_call` and `tool_result`, block or mutate tool calls, and are declared with `pi.extensions` in `package.json`; see the [Pi extension docs](https://pi.dev/docs/latest/extensions). This package does not ship that extension yet, so clean-room safety in Pi still depends on role separation, path isolation, schema validation, and any supported hook runtime used for enforcement.
 
 ## How To Run
 

package/agents/clean-polish-reviewer.md

@@ -15,7 +15,7 @@ Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMP
 
 Before tool use, confirm this session has `CLEAN_ROOM_ROLE=clean-polish-reviewer`, `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.
 
-This default profile has no shell-style tools. If final verification or commit is required, use an isolated polish profile where strict hooks are installed, `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1` is intentional, and the only allowed terminal command invokes the installed `agent4-polish-runner.py` from an implementation root. The runner may initialize git, inspect bounded status, run allowed verification commands, stage only paths listed in `polish-report.json`, and create one local commit. Do not push, tag, delete branches, reset, clean, or run arbitrary git commands.
+This default profile has no shell-style tools. If final verification or commit is required, use an isolated polish profile where strict hooks are installed, `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1` is intentional, and the only allowed terminal command invokes the installed `agent4-polish-runner.py` from an implementation root. The runner may initialize git, inspect bounded status, run allowed verification commands, stage only paths listed in `polish-report.json` `git.include_paths`, and create one local commit. Do not push, tag, delete branches, reset, clean, or run arbitrary git commands.
 
 ## Required Handoff Inputs
 
@@ -37,8 +37,10 @@ Responsibilities:
 - Update implementation-root `.gitignore` only for real generated outputs, dependency folders, local caches, or build/test artifacts relevant to the clean implementation stack.
 - Do not add speculative ignores, speculative docs, broad refactors, new dependencies, or new behavior.
 - Re-run relevant verification through `agent4-polish-runner.py` only when shell verification is enabled for this role.
-- Record findings, changed relative paths, verification results, residual risks, git status, commit message, commit hash/status, and abstract delta tickets in `polish-report.json`.
-- Mark `final_status` as `passed` only when high/blocker security, correctness, exception, resource, race, leakage, and verification findings are resolved and the constrained local commit succeeded.
+- Record findings, Agent 4 changed relative paths, verification results, residual risks, git status, commit message, commit hash/status, and abstract delta tickets in `polish-report.json`.
+- Set `git.include_paths` to the union of terminal `implementation-report.json` `changed_paths` and Agent 4 `polish-report.json` `changed_paths`; do not include unreported dirty files.
+- When the controller must create the commit, write a pre-commit report with `final_status: "blocked"`, `git.commit_required: true`, and `git.commit_status: "not-run"`.
+- Mark `final_status` as `passed` only when high/blocker security, correctness, exception, resource, race, leakage, and verification findings are resolved and either the constrained local commit succeeded or clean-run-context explicitly disables Agent 4 commits with `git.commit_status: "not-needed"`.
 - Convert major behavior gaps or scope expansion into abstract delta tickets instead of implementing new scope.
 
 If contamination is found, mark `polish-report.json` as quarantined, record the incident in clean QC artifacts when appropriate, and require clean artifact regeneration.

package/docs/ARCHITECTURE.md

@@ -179,6 +179,7 @@ The architecture delegates work across six distinct custom role agents to enforc
     *   Influences Agent 2, Agent 3, and Agent 4 only through durable sanitized artifacts, never direct chat, progress feedback, implementation hints, or priority changes.
     *   Performs final verification of clean specification and implementation coverage against the source scope.
     *   Blocks handoff or coverage completion when high-priority contaminated discovery leads remain unresolved.
+    *   Treats completion as deny-by-default unless durable canonical artifacts prove the clean behavior gate.
     *   Writes the inner-loop `clean-room-result.json` only after contaminated-side coverage verification.
     *   Consumes Agent 3 reports only after Agent 3 reaches a terminal state, and consumes Agent 4 reports only after the configured polish review reaches a terminal state, then sends only abstract delta tickets into a fresh clean artifact cycle.
 
@@ -240,7 +241,7 @@ The architecture delegates work across six distinct custom role agents to enforc
     *   Updates `.gitignore` only for real generated outputs, dependencies, caches, or build/test artifacts.
     *   Writes `CLEAN_ROOM_CLEAN_ROOTS/polish-report.json`.
     *   Uses `agent4-polish-runner.py` only with `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd under implementation roots, and strict hooks.
-    *   May initialize git and create one local commit containing only paths listed in `polish-report.json`; it must not push, tag, reset, clean, or delete branches.
+    *   May initialize git and create one local commit containing only paths listed in `polish-report.json` `git.include_paths`; that list must include terminal Agent 3 implementation changes plus Agent 4 polish changes. It must not push, tag, reset, clean, or delete branches.
 
 ### Nested Controller Loop
 
@@ -250,6 +251,8 @@ The outer loop owns spec development: scope, behavior specs, acceptance criteria
 
 Agent 3's terminal report is not enough to return. If configured, Agent 4 must produce a passing `polish-report.json`. Agent 0 must then consume the terminal clean reports, verify contaminated-side coverage, and write `clean-room-result.json`.
 
+Completion is deny-by-default. `task-manifest.json`, `coverage-ledger.json`, and `clean-room-result*.json` writes that claim completion must be backed by durable canonical clean artifacts: a matching clean behavior spec, implementation plan mappings, a terminal implementation report, a passed QC report, valid evidence references, and required public-surface mappings. Synthetic or manual completion summaries are not completion evidence.
+
 `clean-room-skill run` is the executable v1 inner-loop runner. It requires preflight refs, the required handoff sequence, unattended `controller_policy`, schema-valid `loop_context`, and either a user-supplied agent command adapter or the built-in Claude Code agent runtime. It does not automate outer spec development. The runner:
 
 *   Locks the contaminated artifact root with `.clean-room-run.lock`.
@@ -261,6 +264,7 @@ Agent 3's terminal report is not enough to return. If configured, Agent 4 must p
 *   Supports the optional `clean-polish-review` phase between `clean-implement-qc` and `contaminated-coverage-verify`.
 *   Validates schema, leakage, and handoff integrity before advancing state.
 *   Rejects `covered` coverage-ledger units that still have unresolved high-priority `discovery_leads`.
+*   Rejects completion claims that lack canonical clean specs, plans, terminal reports, QC, evidence, or public-surface coverage mappings.
 *   Records controller memory in contaminated-side `controller-run-ledger.json`.
 *   Writes `clean-room-result.json` before returning to the outer spec loop.
 
@@ -302,7 +306,7 @@ Post-write hook failures are deny-by-default and redacted. If an artifact disapp
 *   [deny-clean-source-read.py](../hooks/deny-clean-source-read.py): Enforces that clean roles and Agent 1.5 cannot read source or visual roots or unapproved paths; clean roles may read implementation roots, and source-denied roles are denied direct `preflight-goal.json` reads. Agent 1.5 is also denied clean roots, implementation roots, and direct `source-index.json` or `visual-index.json` reads.
 *   [deny-contaminated-clean-write.py](../hooks/deny-contaminated-clean-write.py): Enforces role write roots. Agent 2 writes clean artifacts only, Agent 3 writes implementation files and clean reports, Agent 4 writes clean polish reports and implementation-root polish changes, contaminated roles write only to `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, and clean-room artifact JSON files are denied under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
 *   [check-artifact-leakage.py](../hooks/check-artifact-leakage.py): Scans clean artifacts and Agent 1.5 staged contaminated artifacts for high-risk leakage markers, source-like identifiers, and private identifier denylist terms. The private identifier denylist (loaded via `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST`) is subject to hard limits to protect hook execution performance: a maximum of 1,000,000 bytes per file, 20,000 total terms, and 512 characters per individual term.
-*   [validate-json-schema.py](../hooks/validate-json-schema.py): Verifies JSON syntax and structural conformance against schemas under `CLEAN_ROOM_SCHEMA_DIR`, including controller-side `preflight-goal.schema.json` and `init-config.schema.json`. Under clean roots, any unrecognized JSON files that do not conform to canonical schemas will trigger a failure unless they are explicitly registered in the path-separated `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` environment variable.
+*   [validate-json-schema.py](../hooks/validate-json-schema.py): Verifies JSON syntax and structural conformance against schemas under `CLEAN_ROOM_SCHEMA_DIR`, including controller-side `preflight-goal.schema.json` and `init-config.schema.json`. Under clean roots, any unrecognized JSON files that do not conform to canonical schemas will trigger a failure unless they are explicitly registered in the path-separated `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` environment variable. Post-write validation also rejects completion claims in `task-manifest.json`, `coverage-ledger.json`, and `clean-room-result*.json` unless durable canonical completion artifacts prove the gate.
 *   [validate-handoff-package.py](../hooks/validate-handoff-package.py): Verifies that handoff packages stay within clean roots, do not reference contaminated paths, `task-manifest.json`, `preflight-goal.json`, `source-index.json`, or `visual-index.json`, and match declared `sha256` checksums.
 
 For detailed guidelines on the clean-room process, refer to:

package/docs/HOOKS.md

@@ -15,6 +15,7 @@ The installer copies the Python hook files for every supported runtime layout. R
 | Antigravity | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Gemini CLI | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | OpenCode | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/plugins/clean-room.ts` |
+| Pi | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Kilo | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Cursor | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | GitHub Copilot | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
@@ -171,6 +172,8 @@ Post-write JSON artifact validator.
 - Implements the lightweight schema keywords used by bundled schemas, including object and array constraints, required fields, enum/const, patterns, `format: date-time`, `$ref`, `allOf`, `anyOf`, `oneOf`, and `if`/`then`/`else`.
 - Adds clean-run-context path checks so clean artifact paths stay relative, do not use `~`, do not contain `..`, and do not resolve into source or contaminated roots.
 - Requires task manifest handoff stages to match the expected clean-room sequence when validating the task manifest schema.
+- Performs semantic completion validation for `task-manifest.json`, `coverage-ledger.json`, and `clean-room-result*.json` post-write payloads.
+- Rejects completion claims unless canonical durable artifacts prove the gate: matching clean behavior specs, implementation-plan work item mappings, terminal implementation reports, passed QC reports, valid evidence references, and required public-surface coverage mappings.
 
 ### `validate-handoff-package.py`
 

package/docs/REFERENCE.md

@@ -21,6 +21,7 @@ Runtime flags:
 | `--antigravity` | Antigravity |
 | `--gemini` | Gemini CLI |
 | `--opencode` | OpenCode |
+| `--pi` | Pi |
 | `--kilo` | Kilo |
 | `--cursor` | Cursor |
 | `--copilot` | GitHub Copilot |
@@ -70,6 +71,7 @@ Layout-only or experimental:
 
 - Antigravity
 - Gemini CLI
+- Pi
 - Kilo
 - Cursor
 - GitHub Copilot
@@ -82,7 +84,7 @@ Layout-only or experimental:
 
 Layout-only installs write files to expected runtime locations, but this repository does not verify that those hosts load the files or emit all hook events needed for clean-room enforcement. OpenCode installs are verified through a generated local plugin bridge at `plugins/clean-room.ts`; `doctor` verifies that bridge and the Python guardrails, not every OpenCode tool surface.
 
-### Pi Package Compatibility
+### Pi Compatibility
 
 Pi can install this package and load the bundled skills from the package metadata:
 
@@ -91,7 +93,13 @@ pi install npm:clean-room-skill@latest
 pi install https://github.com/whit3rabbit/clean-room-skill
 ```
 
-Pi invokes skills as `/skill:<name>`. Use `/skill:init` for the setup pass, `/skill:clean-room` for the startup wizard, `/skill:attended` for attended controller mode, and `/skill:unattended` for bounded unattended mode. Pi support is package compatibility only: it does not add a `--pi` installer target, does not participate in `--all`, and does not register clean-room hooks. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
+Pi-native package install is preferred. The installer also supports a layout target:
+
+```bash
+npx clean-room-skill@latest --pi --global --yes
+```
+
+Pi invokes skills as `/skill:<name>`. Use `/skill:init` for the setup pass, `/skill:clean-room` for the startup wizard, `/skill:attended` for attended controller mode, and `/skill:unattended` for bounded unattended mode. Pi installs do not register clean-room hooks; installer-managed Pi layouts copy hook scripts only. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
 
 Global install roots:
 
@@ -102,6 +110,7 @@ Global install roots:
 | Antigravity | `ANTIGRAVITY_PLUGIN_DIR`, `ANTIGRAVITY_CLI_PLUGIN_DIR`, `ANTIGRAVITY_CONFIG_DIR/plugins/clean-room`, or `~/.gemini/antigravity-cli/plugins/clean-room` |
 | Gemini CLI | `GEMINI_CONFIG_DIR` or `~/.gemini` |
 | OpenCode | `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG`, `XDG_CONFIG_HOME/opencode`, or `~/.config/opencode` |
+| Pi | `~/.pi/agent` |
 | Kilo | `KILO_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME/kilo`, or `~/.config/kilo` |
 | Cursor | `CURSOR_CONFIG_DIR` or `~/.cursor` |
 | GitHub Copilot | `COPILOT_CONFIG_DIR` or `~/.copilot` |
@@ -112,7 +121,7 @@ Global install roots:
 | Hermes Agent | `HERMES_HOME` or `~/.hermes` |
 | CodeBuddy | `CODEBUDDY_CONFIG_DIR` or `~/.codebuddy` |
 
-Local installs use each runtime's project config directory. Antigravity local installs write `.agents/plugins/clean-room/`.
+Local installs use each runtime's project config directory. Pi local installs write `.pi/`. Antigravity local installs write `.agents/plugins/clean-room/`.
 
 ## Agent Metadata Compatibility
 
@@ -238,6 +247,8 @@ Unattended code-development manifests must include exactly one `unit_kind: "foun
 
 `coverage-ledger.json` may record contaminated-only `source_units[].discovery_leads` for authorized related surfaces that were detected but not analyzed in the assigned unit. The runner rejects a `covered` unit while any high-priority discovery lead remains open or deferred. It does not add follow-up units or expand `loop_context.approved_scope_refs`; Agent 0 must return an abstract delta, mark coverage partial or blocked, or pause for attended approval.
 
+Completion is valid only when canonical durable artifacts prove the gate. A completed behavior unit or `spec-slice-complete` result must have a matching clean behavior spec, implementation-plan work item mapping, terminal implementation report, passed QC report, valid contaminated evidence refs, and required public-surface mappings across the behavior spec, coverage ledger, implementation plan, and terminal report. Manual summaries or synthetic result files are not completion evidence.
+
 Minimal agent command adapter shape for advisory or disabled context management:
 
 ```json

package/hooks/check-artifact-leakage.py

@@ -83,6 +83,7 @@ DENYLIST_ONLY_JSON_STRING_KEYS = {
     "expected_artifacts",
     "implementation_root_ref",
     "implementation_root_refs",
+    "include_paths",
     "incident_id",
     "manifest_id",
     "native_artifacts",