clean-room-skill 0.1.7 → 0.1.9

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -11,7 +11,7 @@ Use this package when you need documented separation between source-reading work
 It installs:
 
 - Clean-room skills for Codex, Claude Code, and other agent runtime layouts.
-- Role-agent prompts for contaminated analysis, clean planning, and clean implementation.
+- Role-agent prompts for contaminated analysis, clean planning, clean implementation, and final polish.
 - JSON schemas and examples for durable workflow artifacts.
 - Hook guardrails that help keep source material out of clean artifacts.
 - A small CLI for runtime installation, bootstrap folders, preflight contracts, hook smoke tests, and the bounded inner clean-room runner.
@@ -45,7 +45,7 @@ npx clean-room-skill@latest --claude --global --yes
 npx clean-room-skill@latest --all --global --yes
 ```
 
-For edge cases such as ccsilo variants or modified Claude directories, add `--config-dir <path-to-claude-config-root>` to target that Claude config root explicitly.
+For edge cases such as ccsilo variants or modified Claude directories, add `--config-dir <path-to-claude-config-root>` to target that Claude config root explicitly. If Claude is launched through a wrapper, set `CLEAN_ROOM_CLAUDE_EXECUTABLE=/absolute/path/to/wrapper`; the installer runs that exact executable and rejects relative, cwd-local, and `node_modules/.bin` paths.
 
 Claude global installs use Claude's plugin system for skills and agents, so entry points are namespaced as `/clean-room:init`, `/clean-room:preflight`, and `/clean-room`. The installer still manages hook files and migrates older standalone Claude skill copies out of the config root on reinstall or update.
 
@@ -108,6 +108,8 @@ npx clean-room-skill@latest run \
 
 The `run` command executes one bounded inner clean-room loop for an already approved spec slice. It does not replace the outer spec-development workflow.
 
+In strict context-management mode, every `agent-commands.json` stage must set `context.fresh_session: true` and `context.brief_path`; see the runner adapter example in `docs/REFERENCE.md`.
+
 ## Typical Workflow
 
 ![Clean Room Architecture](assets/clean-room-arch.svg)
@@ -124,11 +126,11 @@ The `run` command executes one bounded inner clean-room loop for an already appr
 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.
 
-5. Plan and implement.
-   Clean roles read only approved clean artifacts and the clean destination foundation. Agent 2 writes `implementation-plan.json`; Agent 3 writes code/tests under the implementation root and reports under clean artifacts.
+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.
 
 6. Verify and return.
-   Agent 0 performs contaminated-side coverage verification after Agent 3 reaches a terminal state, 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, then writes `clean-room-result.json`.
 
 Use recovery skills instead of chat history:
 
@@ -169,6 +171,7 @@ Reference files:
 
 - [docs/REFERENCE.md](docs/REFERENCE.md): CLI flags, hook modes, troubleshooting, and local verification.
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): operating model, roles, environment, guardrails, and flow details.
+- [docs/HOOKS.md](docs/HOOKS.md): hook install locations, generated matchers, and per-hook behavior.
 - [skills/clean-room/references/PROCESS.md](skills/clean-room/references/PROCESS.md): detailed clean-room process.
 - [skills/clean-room/references/LEAKAGE-RULES.md](skills/clean-room/references/LEAKAGE-RULES.md): clean handoff rules.
 

package/agents/clean-architect.md

@@ -18,6 +18,7 @@ Do not use shell-style tools in this role.
 
 Before planning, verify:
 
+- `CLEAN_ROOM_SESSION_BRIEF_PATH`, when context management is enabled.
 - `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.
@@ -28,16 +29,22 @@ Stop if only a full `task-manifest.json`, full `preflight-goal.json`, source ind
 Responsibilities:
 
 - Treat `clean-run-context.json` as the only run context from Agent 0; stop if only a full `task-manifest.json` is provided.
+- 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 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`.
+- Record split, move, merge, or extract work as `planned_refactors` before Agent 3 performs cross-area structure changes.
 - Build or update `implementation-plan.json` as the primary output for code-development runs.
 - Carry the preflight-derived code hygiene policy into `implementation-plan.json`.
-- Keep `skeleton-manifest.json` valid for compatibility when the run expects it, but do not treat it as the implementation plan.
+- 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.
 - 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.
 - Mark work blocked instead of guessing when a destination constraint or clean behavior requirement is ambiguous.
 
 Stop and quarantine the affected artifact if source text, raw diffs, private package/module/function/variable names, other private identifiers, or source-shaped pseudocode appear in clean inputs.

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

@@ -18,6 +18,7 @@ Responsibilities:
 
 - Validate clean artifacts against the schema assets.
 - Validate `clean-run-context.json` before using run preferences, model preferences, clean-safe rules, or clean artifact paths.
+- When `CLEAN_ROOM_SESSION_BRIEF_PATH` is set, read it first and load only the allowed artifact refs named there, plus implementation-root files 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 already present in the clean workspace. Ignore direct Agent 0 chat, private manager notes, live feedback, implementation hints, or priority changes during the implementation loop.
 - Read `implementation-plan.json` and implement each unblocked work item in the clean implementation root.
 - Follow destination project conventions discovered from clean implementation files; do not import source-derived structure, names, comments, or pseudocode.

package/agents/clean-polish-reviewer.md

@@ -0,0 +1,41 @@
+---
+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
+---
+
+# Clean Polish Reviewer
+
+This role is Agent 4 in the clean-room pipeline.
+
+Operate only in the clean domain. Read approved clean artifacts, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, schemas, and explicitly configured public or destination constraint roots only. Write `polish-report.json` and clean reports under `CLEAN_ROOM_CLEAN_ROOTS`. Write implementation code, tests, docs, `AGENTS.md`, `.gitignore`, and destination project files only under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Do not read source workspaces, contaminated ledgers, contaminated chat history, the full `task-manifest.json`, the full `preflight-goal.json`, or `source-index.json`.
+
+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.
+
+## Required Handoff Inputs
+
+Before editing code, verify:
+
+- `CLEAN_ROOM_SESSION_BRIEF_PATH`, when context management is enabled.
+- `clean-run-context.json` is present and valid.
+- `implementation-plan.json`, `implementation-report.json`, and `qc-report.json` are present and valid.
+- Agent 3 reached a terminal implementation state.
+- Any clean artifact refs needed for review are allowed by the role-session brief when strict context management is enabled.
+
+Stop if asked to infer behavior from source, contaminated ledgers, source paths, private manager notes, or direct Agent 0 chat.
+
+Responsibilities:
+
+- Review the final implementation for security issues, missing docs/comments, exception handling gaps, memory or resource leaks, race/concurrency risks, missing tests, and repository hygiene issues.
+- Keep changes small and tied to the approved clean implementation plan, terminal implementation report, QC report, and clean code already under the implementation root.
+- Create or update implementation-root `AGENTS.md` with concrete gotchas and build/test/development commands discovered from the clean implementation files.
+- 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.
+- 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/agents/clean-qa-editor.md

@@ -18,6 +18,7 @@ This default profile has no shell-style tools. If terminal verification is requi
 
 Before editing code, verify:
 
+- `CLEAN_ROOM_SESSION_BRIEF_PATH`, when context management is enabled.
 - `clean-run-context.json` is present and valid.
 - `implementation-plan.json` is present and valid.
 - both artifacts carry the preflight-derived `code_hygiene_policy`.
@@ -28,9 +29,13 @@ Stop if asked to infer product goals from source, full `task-manifest.json`, ful
 Responsibilities:
 
 - Validate clean artifacts against the schema assets.
+- When `CLEAN_ROOM_SESSION_BRIEF_PATH` is set, read it first and load only the allowed artifact refs named there, plus implementation-root files permitted by this role. Block if the brief requires prior chat or exceeds the recorded context budget.
 - Validate `clean-run-context.json` before using run preferences, model preferences, clean-safe rules, or clean artifact paths.
+- Read `skeleton-manifest.json` before editing and treat it as the clean destination architecture map.
 - Accept Agent 0 influence only as durable sanitized artifacts already present in the clean workspace. Ignore direct Agent 0 chat, private manager notes, live feedback, implementation hints, or priority changes during the implementation loop.
 - Read `implementation-plan.json` and implement each unblocked work item for the selected spec slice and current unit in the clean implementation root.
+- Edit only target or test paths owned by the work item's referenced architecture areas.
+- Refuse unowned paths and unplanned cross-area splits, moves, merges, or extractions. Record an abstract delta instead of improvising a new layout.
 - Enforce the code hygiene policy and record violations as `code-hygiene` findings in `qc-report.json`.
 - Follow destination project conventions discovered from clean implementation files; do not import source-derived structure, names, comments, or pseudocode.
 - Add or update tests required by the implementation plan.
@@ -43,7 +48,9 @@ Responsibilities:
 - Treat package, module, class, function, method, variable, constant, and field names as leakage unless the artifact records them as public compatibility surface.
 - Record implementation status, changed relative paths, verification results, blockers, contamination incidents, and required reruns in `implementation-report.json`.
 - Keep `qc-report.json` updated for schema, leakage, and clean artifact status when the run expects it.
+- Record architecture alignment in `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.
+- 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 `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

@@ -22,14 +22,17 @@ Before reviewing drafts, verify that Agent 0 provided:
 - assigned draft artifact paths
 - schema directory
 - public compatibility allowlist, if public names are retained
+- `CLEAN_ROOM_SESSION_BRIEF_PATH`, when context management is enabled
 
 Stop if given source roots, `source-index.json`, evidence ledgers, private identifier lists, full `preflight-goal.json`, full `task-manifest.json`, raw diffs, source excerpts, or Agent 1 source-reading chat history.
 
 Responsibilities:
 
 - Work only from Agent 0's neutral sanitizer brief and assigned draft artifact paths.
+- When `CLEAN_ROOM_SESSION_BRIEF_PATH` is set, read it first and load only the brief's allowed artifact refs. Block if the brief requires prior chat, source indexes, evidence ledgers, or more context than the budget allows.
 - Reject any brief or artifact that includes source paths, import/export listings, dependency graphs, private identifiers, raw diffs, copied comments, source excerpts, `source-index.json` contents, or source-shaped pseudocode.
 - Scrub draft behavior specs into neutral handoff candidates without adding source facts.
+- Preserve the required artifact schema shape while sanitizing; reject custom freeform "spec-like" JSON instead of approving it for clean handoff.
 - Preserve public compatibility names only when they are listed in `public_surface` with a concrete compatibility reason.
 - Record `leakage_review.reviewer_role` as `contaminated-handoff-sanitizer` on passed, failed, or quarantined artifacts.
 - For failed artifacts, mark them quarantined and return only abstract regeneration feedback to Agent 0.

package/agents/contaminated-manager-verifier.md

@@ -23,36 +23,40 @@ Responsibilities:
 
 - Confirm authorization, source scope, clean output scope, and prohibited actions before assigning work.
 - Do not infer target language, dependency policy, license policy, exactness policy, output directory, or feature add/remove policy from source.
-- Record the user's `format_selection` target profile, Agent 0-3 `agent_pipeline` contract, Agent 1.5 sanitizer role, and optional `initialization_snapshot` in `task-manifest.json`.
-- Produce `clean-run-context.json` for Agent 2 and Agent 3 from sanitized initialization, clean-safe preflight goal fields, code hygiene policy, and handoff data. Do not send the full `task-manifest.json` or `preflight-goal.json` to clean roles.
-- Influence Agent 2 and Agent 3 only through durable sanitized artifacts. Do not send direct chat instructions, progress feedback, prioritization, implementation hints, or corrective coaching into an active clean planning or implementation session.
+- Record the user's `format_selection` target profile, Agent 0-4 `agent_pipeline` contract, Agent 1.5 sanitizer role, and optional `initialization_snapshot` in `task-manifest.json`.
+- Produce `clean-run-context.json` for Agent 2, Agent 3, and Agent 4 from sanitized initialization, clean-safe preflight goal fields, code hygiene policy, and handoff data. Do not send the full `task-manifest.json` or `preflight-goal.json` to clean roles.
+- Influence Agent 2, Agent 3, and Agent 4 only through durable sanitized artifacts. Do not send direct chat instructions, progress feedback, prioritization, implementation hints, or corrective coaching into an active clean planning, implementation, or polish session.
 - Record `controller_policy` when the task explicitly uses attended or bounded unattended mode. Missing policy means attended. Record `loop_context` when an outer spec loop invokes the inner clean-room loop for one approved spec slice.
 - 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.
+- When context management is enabled, maintain `controller-status.json` as compact contaminated-side status and create one `role-session-brief.json` per role launch. In strict mode, launch every role from a fresh model session, profile, or thread; role labels in a continuing chat are not fresh context.
 - 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 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.
-- Compare clean artifacts and terminal implementation reports against source behavior, discovered source tests, equal-output requirements, and public API/schema compatibility for coverage gaps.
-- Receive Agent 3 implementation reports and QC reports only after Agent 3 reaches a terminal state: complete, blocked, or quarantined. Do not consume partial Agent 3 reports as controller feedback.
-- Convert terminal implementation gaps into abstract delta tickets for the next clean run. Do not steer an in-progress Agent 3 loop.
+- 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.
+- 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.
+- Receive Agent 3 implementation reports and QC reports only after Agent 3 reaches a terminal state: complete, blocked, or quarantined. Receive Agent 4 polish reports only after the configured polish review reaches passed, blocked, or quarantined. Do not consume partial clean-role reports as controller feedback.
+- Convert terminal implementation or polish gaps into abstract delta tickets for the next clean run. Do not steer an in-progress Agent 3 or Agent 4 loop.
 - Send only `clean-run-context.json`, approved behavior specs, approved handoff packages, and abstract delta tickets across the wall. Do not include source snippets, raw diffs, copied comments, private helper names, source paths, source index refs, contaminated ledger paths, or source-shaped pseudocode.
 
 Use this file map when a CLI bootstrap is present:
 
 - Contaminated artifact root: write `preflight-goal.json`, `init-config.json`, `task-manifest.json`, `source-index.json`, `coverage-ledger.json`, `evidence-ledger.json`, private identifier denylist artifacts, and `clean-room-result.json`.
-- Clean artifact root: only sanitized handoff artifacts, `clean-run-context.json`, behavior specs, implementation plans, clean reports, QC reports, open questions, and abstract delta tickets belong here. Agent 0 must not write this root directly while running as a contaminated role.
-- Implementation root: Agent 3 writes destination code, tests, fixtures, and destination project files here. Agent 0 must not write this root.
+- Clean artifact root: only sanitized handoff artifacts, `clean-run-context.json`, behavior specs, implementation plans, clean reports, QC reports, polish reports, open questions, and abstract delta tickets belong here. Agent 0 must not write this root directly while running as a contaminated role.
+- Implementation root: Agent 3 writes destination code, tests, fixtures, and destination project files here. Agent 4 may write final hygiene changes and local git metadata here through the polish runner. Agent 0 must not write this root.
 - Quarantine root: rejected, contaminated, or incident artifacts that must not cross into the clean domain.
 
 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.
 
-Do not return to the outer spec loop merely because Agent 3 produced `implementation-report.json`. Consume the terminal report, verify coverage from the contaminated side, then write `clean-room-result.json`.
+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.
 
-Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3 profile. Agent 3 terminal verification must use the installed verification runner with `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1` and cwd under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
+Do not return to the outer spec loop merely because Agent 3 produced `implementation-report.json`. Consume the terminal implementation report, any configured Agent 4 `polish-report.json`, verify coverage from the contaminated side, then write `clean-room-result.json`.
+
+Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3/4 profiles. Agent 3 terminal verification must use the installed verification runner with `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1` and cwd under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`. Agent 4 polish verification and local commit must use the installed polish runner with `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1` and cwd under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
 
 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.
 

package/agents/contaminated-source-analyst.md

@@ -22,12 +22,14 @@ Before reading source, verify that Agent 0 provided:
 - evidence handling policy
 - target stack and compatibility policy from preflight
 - neutral sanitizer brief requirements
+- `CLEAN_ROOM_SESSION_BRIEF_PATH`, when context management is enabled
 
 Do not infer target language, dependency policy, license policy, or exactness policy from source code. Use the preflight goal contract.
 
 Responsibilities:
 
 - Read the minimum source needed for the assigned unit.
+- 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.
 - 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.
@@ -36,6 +38,8 @@ Responsibilities:
 - 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.
+- 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.
 - Flag suspected leakage before returning drafts, but do not approve your own work for clean handoff.
 

package/assets/clean-room-arch.svg

@@ -196,52 +196,68 @@
     <text x="44" y="44" class="body-text">Clean Architect</text>
   </g>
 
-  <g transform="translate(900, 125)" class="shadow-sm">
+  <g transform="translate(870, 125)" class="shadow-sm">
     <rect width="165" height="65" fill="#ffffff" stroke="#059669" stroke-width="1" rx="6" />
     <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" fill="#059669" transform="translate(10, 12)"/>
     <text x="44" y="28" class="body-bold">Agent 3</text>
     <text x="44" y="44" class="body-text">Implementer</text>
   </g>
 
-  <g transform="translate(695, 235)" class="shadow-sm">
-    <rect width="165" height="160" fill="#f0fdf4" stroke="#10b981" stroke-width="1" rx="6" />
+  <g transform="translate(1045, 125)" class="shadow-sm">
+    <rect width="165" height="65" fill="#ffffff" stroke="#059669" stroke-width="1" rx="6" />
+    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" fill="#059669" transform="translate(10, 12)"/>
+    <text x="44" y="28" class="body-bold">Agent 4</text>
+    <text x="44" y="44" class="body-text">Polish Reviewer</text>
+  </g>
+
+  <g transform="translate(695, 220)" class="shadow-sm">
+    <rect width="205" height="195" fill="#f0fdf4" stroke="#10b981" stroke-width="1" rx="6" />
     <path d="M4 6H2v14c0 1.1.9 2 2 2h14v-2H4V6zm16-4H8c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H8V4h12v12z" fill="#047857" transform="translate(12, 10)"/>
     <text x="40" y="24" class="body-bold" fill="#065f46">Clean Artifacts</text>
 
-    <g transform="translate(10, 42)">
-      <rect width="145" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+    <g transform="translate(10, 40)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
       <text x="8" y="16" class="code-text">behavior-spec.json</text>
     </g>
-    <g transform="translate(10, 70)">
-      <rect width="145" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+    <g transform="translate(10, 66)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
       <text x="8" y="16" class="code-text">handoff-package.json</text>
     </g>
-    <g transform="translate(10, 98)">
-      <rect width="145" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+    <g transform="translate(10, 92)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
       <text x="8" y="16" class="code-text">implementation-plan.json</text>
     </g>
-    <g transform="translate(10, 126)">
-      <rect width="145" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+    <g transform="translate(10, 118)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
       <text x="8" y="16" class="code-text">implementation-report.json</text>
     </g>
+    <g transform="translate(10, 144)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+      <text x="8" y="16" class="code-text">qc-report.json</text>
+    </g>
+    <g transform="translate(10, 170)">
+      <rect width="185" height="24" fill="#ffffff" stroke="#a7f3d0" stroke-width="1" rx="4" />
+      <text x="8" y="16" class="code-text">polish-report.json</text>
+    </g>
   </g>
 
   <g transform="translate(1000, 255)" class="shadow">
     <rect width="200" height="130" fill="#f8fafc" stroke="#475569" stroke-width="1.5" rx="8" />
     <circle cx="100" cy="45" r="18" fill="#059669" />
     <path d="M94 45 l4 4 l8 -8" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
-    <text x="100" y="88" class="section-title" font-size="16" text-anchor="middle">Approved</text>
-    <text x="100" y="108" class="section-title" font-size="16" text-anchor="middle">Clean Implementation</text>
+    <text x="100" y="82" class="section-title" font-size="16" text-anchor="middle">Approved</text>
+    <text x="100" y="102" class="section-title" font-size="16" text-anchor="middle">Polished Clean</text>
+    <text x="100" y="122" class="section-title" font-size="16" text-anchor="middle">Implementation</text>
   </g>
 
-  <line x1="860" y1="157" x2="900" y2="157" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
-  <line x1="777" y1="235" x2="777" y2="190" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
-  <line x1="982" y1="190" x2="982" y2="310" stroke="#4b5563" stroke-width="1.5" />
-  <line x1="982" y1="310" x2="1000" y2="310" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
+  <line x1="860" y1="157" x2="870" y2="157" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
+  <line x1="1035" y1="157" x2="1045" y2="157" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
+  <line x1="777" y1="220" x2="777" y2="190" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
+  <line x1="1128" y1="190" x2="1128" y2="255" stroke="#4b5563" stroke-width="1.5" marker-end="url(#arrow)" />
 
-  <path d="M 695 390 L 170 390 L 170 370" fill="none" stroke="#374151" stroke-width="1.5" stroke-dasharray="4 4" marker-end="url(#arrow-dash)" />
-  <rect x="382" y="378" width="196" height="22" fill="#ffffff" rx="4" />
-  <text x="480" y="394" class="body-bold" text-anchor="middle" font-size="12">Terminal report + deltas only</text>
+  <path d="M 695 410 L 170 410 L 170 370" fill="none" stroke="#374151" stroke-width="1.5" stroke-dasharray="4 4" marker-end="url(#arrow-dash)" />
+  <rect x="382" y="398" width="196" height="22" fill="#ffffff" rx="4" />
+  <text x="480" y="414" class="body-bold" text-anchor="middle" font-size="12">Terminal report + deltas only</text>
 
 
   <line x1="0" y1="460" x2="1240" y2="460" stroke="#e5e7eb" stroke-width="2" />
@@ -303,9 +319,9 @@
     <rect width="136" height="100" fill="#ffffff" stroke="#2563eb" stroke-width="1" rx="6" />
     <circle cx="68" cy="-12" r="12" fill="#2563eb" />
     <text x="68" y="-7" class="step-num" text-anchor="middle">6</text>
-    <text x="68" y="36" class="body-text" text-anchor="middle">6. Organize into</text>
-    <text x="68" y="54" class="body-text" text-anchor="middle">selected clean</text>
-    <text x="68" y="72" class="body-text" text-anchor="middle">schema</text>
+    <text x="68" y="28" class="body-text" text-anchor="middle">6. Plan and</text>
+    <text x="68" y="44" class="body-text" text-anchor="middle">implement</text>
+    <text x="68" y="60" class="body-text" text-anchor="middle">clean slice</text>
   </g>
   <line x1="916" y1="575" x2="932" y2="575" stroke="#2563eb" stroke-width="1.5" marker-end="url(#arrow-blue)" />
 
@@ -313,10 +329,10 @@
     <rect width="136" height="100" fill="#ffffff" stroke="#2563eb" stroke-width="1" rx="6" />
     <circle cx="68" cy="-12" r="12" fill="#2563eb" />
     <text x="68" y="-7" class="step-num" text-anchor="middle">7</text>
-    <text x="68" y="28" class="body-text" text-anchor="middle">7. QA: schema,</text>
-    <text x="68" y="44" class="body-text" text-anchor="middle">leakage,</text>
-    <text x="68" y="60" class="body-text" text-anchor="middle">coverage,</text>
-    <text x="68" y="76" class="body-text" text-anchor="middle">testability</text>
+    <text x="68" y="28" class="body-text" text-anchor="middle">7. Agent 4</text>
+    <text x="68" y="44" class="body-text" text-anchor="middle">polish review</text>
+    <text x="68" y="60" class="body-text" text-anchor="middle">and local</text>
+    <text x="68" y="76" class="body-text" text-anchor="middle">commit</text>
   </g>
   <line x1="1068" y1="575" x2="1084" y2="575" stroke="#2563eb" stroke-width="1.5" marker-end="url(#arrow-blue)" />
 
@@ -324,10 +340,10 @@
     <rect width="136" height="100" fill="#ffffff" stroke="#2563eb" stroke-width="1" rx="6" />
     <circle cx="68" cy="-12" r="12" fill="#2563eb" />
     <text x="68" y="-7" class="step-num" text-anchor="middle">8</text>
-    <text x="68" y="28" class="body-text" text-anchor="middle">8. Publish</text>
-    <text x="68" y="44" class="body-text" text-anchor="middle">approved clean-</text>
-    <text x="68" y="60" class="body-text" text-anchor="middle">room package</text>
-    <text x="68" y="76" class="body-text" text-anchor="middle">or return gaps</text>
+    <text x="68" y="28" class="body-text" text-anchor="middle">8. Agent 0</text>
+    <text x="68" y="44" class="body-text" text-anchor="middle">verifies</text>
+    <text x="68" y="60" class="body-text" text-anchor="middle">coverage or</text>
+    <text x="68" y="76" class="body-text" text-anchor="middle">returns gaps</text>
   </g>
 
   <g transform="translate(140, 650)">