clean-room-skill 0.1.8 → 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.8",
+      "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.8",
+  "version": "0.1.9",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.1.8",
+  "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.
@@ -126,11 +126,11 @@ In strict context-management mode, every `agent-commands.json` stage must set `c
 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:
 

package/agents/clean-architect.md

@@ -33,13 +33,18 @@ Responsibilities:
 - 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-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

@@ -31,8 +31,11 @@ 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.
@@ -45,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

@@ -32,6 +32,7 @@ Responsibilities:
 - 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,9 +23,9 @@ 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.
@@ -35,16 +35,17 @@ Responsibilities:
 - 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.
@@ -53,9 +54,9 @@ In unattended mode, reload durable artifacts before each iteration, select at mo
 
 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 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`.
+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 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 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

@@ -38,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)">

package/docs/ARCHITECTURE.md

@@ -51,7 +51,7 @@ To assist in logical unit decomposition, the workflow supports an optional sourc
 
 *   **Execution Boundary**: This tooling runs exclusively in the contaminated domain before clean-room role sessions are initialized.
 *   **Traversal Bounds**: Source indexing enforces file count, per-file byte, total byte, batch token, and segment caps. It validates file size again after reading, skips files that change during read, records directory walk errors, and prunes traversal after global limits are exhausted with an aggregate skipped entry.
-*   **Agent 0 Use**: Agent 0 consumes `source-index.json` only to create neutral `task-manifest.json` units and per-unit `source_index_refs`. The index stays contaminated-only and does not cross to Agent 1.5, Agent 2, Agent 3, or clean handoff packages.
+*   **Agent 0 Use**: Agent 0 consumes `source-index.json` only to create neutral `task-manifest.json` units and per-unit `source_index_refs`. The index stays contaminated-only and does not cross to Agent 1.5, Agent 2, Agent 3, Agent 4, or clean handoff packages.
 *   **Tool Trust Policy**: By default, tool discovery operates in `stat-only` mode and does not execute third-party binaries. It queries version strings only when explicitly invoked with `--probe-tools`. Tools discovered under `/opt/homebrew` or `/usr/local` remain stat-only unless `--allow-user-toolchain-probes` is also supplied. Project-local directories (such as `.bin` or `node_modules/.bin`) are ignored unless the environment variable `RE_SKILLS_TRUST_PROJECT_TOOLS=1` or the flag `--allow-working-project-tools` is supplied.
 *   **Local Tool Install Safety**: Explicit npm-backed helper installs are strict-version pinned and serialized with a cache-local lock before mutating `~/.cache/re-skills/clean-room-tools/npm`. Prefix creation failures, subprocess timeouts, and subprocess launch errors are returned as structured JSON facts instead of raw tracebacks.
 
@@ -94,8 +94,9 @@ flowchart LR
     publicrefs["Allowed public refs<br/>CLEAN_ROOM_ALLOWED_READ_ROOTS"]
     architect["Agent 2: clean-architect<br/>Plan implementation from clean specs and foundation"]
     qa["Agent 3: clean-qa-editor<br/>Implement, record verification, terminal report"]
+    polish["Agent 4: clean-polish-reviewer<br/>Final code polish, repo hygiene, local commit"]
     outputs["Clean artifacts<br/>implementation-plan.json<br/>qc-report.json<br/>test plan notes"]
-    imploutputs["Implementation outputs<br/>code and tests<br/>implementation-report.json"]
+    imploutputs["Implementation outputs<br/>code, tests, AGENTS.md, .gitignore<br/>implementation-report.json<br/>polish-report.json"]
   end
 
   subgraph guardrails["Guardrails and audit"]
@@ -128,6 +129,10 @@ flowchart LR
   implroots --> qa
   qa --> imploutputs
   qa --> outputs
+  imploutputs --> polish
+  outputs --> polish
+  polish --> imploutputs
+  polish -. terminal polish report only<br/>abstract delta tickets .-> manager
   qa -. terminal report only<br/>abstract delta tickets .-> manager
 
   blocked -. quarantine do not hand off .-> ledgers
@@ -137,10 +142,10 @@ flowchart LR
   denyread -. clean roles may read implementation roots .-> implroots
   denyread -. Agent 1.5 cannot read source roots, clean roots, implementation roots, source-index.json, or preflight-goal.json .-> sanitizer
   denywrite -. contaminated writes only to contaminated artifact roots .-> ledgers
-  denywrite -. Agent 2 writes clean artifacts only; Agent 3 writes implementation roots .-> cleanroots
-  denywrite -. Agent 3 writes code and tests only here .-> implroots
+  denywrite -. Agent 2 writes clean artifacts only; Agents 3 and 4 write implementation roots .-> cleanroots
+  denywrite -. Agents 3 and 4 write code, tests, docs, and repo hygiene only here .-> implroots
   denyshell -. no shell-style tools in role sessions .-> manager
-  denyshell -. no shell for Agent 2; explicit Agent 3 verification runner only .-> architect
+  denyshell -. no shell for Agent 2; explicit Agent 3 and Agent 4 runners only .-> architect
   scan -. post-write checks .-> outputs
   scan -. Agent 1.5 staged-output checks .-> staged
 
@@ -149,7 +154,7 @@ flowchart LR
   classDef wallClass fill:#f8fafc,stroke:#475569,color:#111827;
   classDef guardClass fill:#f0fdf4,stroke:#15803d,color:#111827;
   class source,preflight,manager,analyst,sanitizer,brief,ledgers,drafts,staged contaminatedDomain;
-  class cleanroots,implroots,publicrefs,architect,qa,outputs,imploutputs cleanDomain;
+  class cleanroots,implroots,publicrefs,architect,qa,polish,outputs,imploutputs cleanDomain;
   class handoff,blocked wallClass;
   class env,denyread,denywrite,denyshell,scan guardClass;
 ```
@@ -158,7 +163,7 @@ flowchart LR
 
 ## Agent Roles
 
-The architecture delegates work across five distinct custom role agents to enforce separation between source reading, independent sanitization, clean planning, and clean implementation.
+The architecture delegates work across six distinct custom role agents to enforce separation between source reading, independent sanitization, clean planning, clean implementation, and final clean polish review.
 
 ### [Agent 0: Contaminated Manager Verifier](../agents/contaminated-manager-verifier.md)
 *   **Domain**: Contaminated (Source-readable)
@@ -169,11 +174,11 @@ The architecture delegates work across five distinct custom role agents to enfor
     *   Decomposes source scope into stable, neutral units that do not mirror private source layout.
     *   Controls execution flow and nested loop state.
     *   Provides Agent 1.5 only a neutral sanitizer brief containing domain purpose, target profile, unit intent, public compatibility allowlist, and blocked categories.
-    *   Produces `clean-run-context.json` for Agent 2 and Agent 3 instead of handing over the full `task-manifest.json` or full `preflight-goal.json`.
-    *   Influences Agent 2 and Agent 3 only through durable sanitized artifacts, never direct chat, progress feedback, implementation hints, or priority changes.
+    *   Produces `clean-run-context.json` for Agent 2, Agent 3, and Agent 4 instead of handing over the full `task-manifest.json` or full `preflight-goal.json`.
+    *   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.
     *   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, then sends only abstract delta tickets into a fresh clean artifact cycle.
+    *   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.
 
 ### [Agent 1: Contaminated Source Analyst](../agents/contaminated-source-analyst.md)
 *   **Domain**: Contaminated (Source-readable, Read-only access to source)
@@ -206,7 +211,8 @@ The architecture delegates work across five distinct custom role agents to enfor
     *   Cannot write to `CLEAN_ROOM_IMPLEMENTATION_ROOTS`; the write hook rejects Agent 2 implementation-root writes.
     *   Merges approved handoff artifacts into the clean workspace.
     *   Writes `implementation-plan.json` with relative destination paths, tests, code hygiene policy, constraints, risks, and argv-array verification commands.
-    *   Keeps `skeleton-manifest.json` valid when the target profile expects it.
+    *   Maintains `skeleton-manifest.json` as the clean destination architecture map for code-development runs, with owned path prefixes and refactor triggers.
+    *   Assigns each implementation-plan target and test path to one or more architecture areas.
 
 ### [Agent 3: Clean Implementer Verifier](../agents/clean-qa-editor.md)
 *   **Domain**: Clean (Source-denied)
@@ -221,13 +227,24 @@ The architecture delegates work across five distinct custom role agents to enfor
     *   Does not report progress or ask Agent 0 for guidance during implementation.
     *   Emits one terminal report for Agent 0 only when the assigned spec slice is complete, blocked, or quarantined.
 
+### [Agent 4: Clean Polish Reviewer](../agents/clean-polish-reviewer.md)
+*   **Domain**: Clean (Source-denied)
+*   **Write Target**: Clean polish reports in `CLEAN_ROOM_CLEAN_ROOTS`; code, docs, repo hygiene files, and local git metadata in `CLEAN_ROOM_IMPLEMENTATION_ROOTS`
+*   **Responsibilities**:
+    *   Reviews final clean implementation for security, docs/comments, exception handling, resource leaks, race conditions, missing tests, and repository hygiene.
+    *   Creates or updates implementation-root `AGENTS.md` with gotchas and build/test/dev commands discovered from clean implementation files.
+    *   Updates `.gitignore` only for real generated outputs, dependencies, caches, or build/test artifacts.
+    *   Writes `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.
+
 ### Nested Controller Loop
 
 ![Nested Controller Loop](assets/4.png)
 
-The outer loop owns spec development: scope, behavior specs, acceptance criteria, and abstract delta resolution. The inner clean-room loop owns one approved spec slice. It repeats analyze, sanitize, plan, implement, QC, and contaminated-side coverage verification until it can return `spec-slice-complete`, `spec-slice-blocked`, `spec-delta-required`, `contamination-suspected`, `iteration-limit-reached`, or `no-progress-detected`.
+The outer loop owns spec development: scope, behavior specs, acceptance criteria, and abstract delta resolution. The inner clean-room loop owns one approved spec slice. It repeats analyze, sanitize, plan, implement, QC, optional final polish review, and contaminated-side coverage verification until it can return `spec-slice-complete`, `spec-slice-blocked`, `spec-delta-required`, `contamination-suspected`, `iteration-limit-reached`, or `no-progress-detected`.
 
-Agent 3's terminal report is not enough to return. Agent 0 must consume that report, verify contaminated-side coverage, and then write `clean-room-result.json`.
+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`.
 
 `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 a user-supplied agent command adapter. It does not automate outer spec development. The runner:
 
@@ -236,6 +253,7 @@ Agent 3's terminal report is not enough to return. Agent 0 must consume that rep
 *   Selects at most one pending or gap unit inside `loop_context.approved_scope_refs`.
 *   Spawns configured role commands with `shell: false`, bounded output, and bounded timeout.
 *   In strict context-management mode, requires each configured stage to provide `context.fresh_session: true` and `context.brief_path`, then validates the session brief before spawn.
+*   Supports the optional `clean-polish-review` phase between `clean-implement-qc` and `contaminated-coverage-verify`.
 *   Validates schema, leakage, and handoff integrity before advancing state.
 *   Records controller memory in contaminated-side `controller-run-ledger.json`.
 *   Writes `clean-room-result.json` before returning to the outer spec loop.
@@ -252,13 +270,13 @@ Every clean-room role session requires a populated environment block before any
 *   `CLEAN_ROOM_SOURCE_ROOTS`: Source roots (only readable by source-reading contaminated roles, not Agent 1.5).
 *   `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`: Target write directory for contaminated roles.
 *   `CLEAN_ROOM_CLEAN_ROOTS`: Target write directory for clean artifacts and reports.
-*   `CLEAN_ROOM_IMPLEMENTATION_ROOTS`: Target write directory for Agent 3 clean implementation code and tests.
+*   `CLEAN_ROOM_IMPLEMENTATION_ROOTS`: Target write directory for Agent 3 clean implementation code and tests, plus Agent 4 implementation-root hygiene changes and local git metadata.
 *   `CLEAN_ROOM_ALLOWED_READ_ROOTS`: Approved reference docs or constraints readable by clean and source-denied roles.
 *   `CLEAN_ROOM_SCHEMA_DIR`: Path to the directory containing JSON schema assets.
 
 When context management is enabled, role sessions also receive `CLEAN_ROOM_SESSION_BRIEF_PATH`, `CLEAN_ROOM_ROLE_SESSION_ID`, and, in strict mode, `CLEAN_ROOM_FRESH_CONTEXT_REQUIRED=1`. The brief is the low-context launch packet: compact status, next action, allowed artifact refs with SHA-256, and forbidden inputs. `controller-status.json` stays contaminated-side and is not clean input.
 
-Note: Even though clean and source-denied roles (such as Agent 1.5, 2, and 3) are restricted from accessing contaminated or source workspaces, they must still be configured with the full environment block. The hook guardrails require these paths to validate that tool inputs do not cross-pollinate or violate boundary constraints.
+Note: Even though clean and source-denied roles (such as Agent 1.5, 2, 3, and 4) are restricted from accessing contaminated or source workspaces, they must still be configured with the full environment block. The hook guardrails require these paths to validate that tool inputs do not cross-pollinate or violate boundary constraints.
 
 ---
 
@@ -272,10 +290,11 @@ Post-write hook failures are deny-by-default and redacted. If an artifact disapp
 
 *   [clean-room-hook.py](../hooks/clean-room-hook.py): The main safe/strict dispatch wrapper for the policy checks.
 *   [agent3-verification-runner.py](../hooks/agent3-verification-runner.py): Runs Agent 3 argv-array verification commands with `shell=False`, sanitized env, bounded output, timeout, root traversal checks, and a small allowlist covering npm, pnpm, yarn, bun, and deno test commands; pytest directly or through `python -m` / `python3 -m`; `cargo test`; `go test`; and `zig build test`.
+*   [agent4-polish-runner.py](../hooks/agent4-polish-runner.py): Runs Agent 4 bounded status, verification, git init, staging, and one local commit from implementation roots only, using paths and policy recorded in `polish-report.json`.
 *   [require-clean-room-env.py](../hooks/require-clean-room-env.py): Fails closed if the required role and root environment variables are missing, if trust-domain roots overlap, or if clean, implementation, or contaminated artifact root names appear source-derived.
-*   [deny-clean-room-shell.py](../hooks/deny-clean-room-shell.py): Denies shell-style tool execution inside clean-room role sessions except installed Agent 3 verification-runner invocations under implementation roots.
+*   [deny-clean-room-shell.py](../hooks/deny-clean-room-shell.py): Denies shell-style tool execution inside clean-room role sessions except installed Agent 3 verification-runner invocations under implementation roots and installed Agent 4 polish-runner invocations under implementation roots.
 *   [deny-clean-source-read.py](../hooks/deny-clean-source-read.py): Enforces that clean roles and Agent 1.5 cannot read source 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` 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, and contaminated roles write only to `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+*   [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, and contaminated roles write only to `CLEAN_ROOM_CONTAMINATED_ARTIFACT_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-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`, or `source-index.json`, and match declared `sha256` checksums.

package/docs/REFERENCE.md

@@ -235,7 +235,7 @@ Minimal agent command adapter shape for advisory or disabled context management:
 }
 ```
 
-Supported phases are `contaminated-analysis`, `sanitize-handoff`, `clean-plan`, `clean-implement-qc`, and `contaminated-coverage-verify`. The coverage verification phase is required.
+Supported phases are `contaminated-analysis`, `sanitize-handoff`, `clean-plan`, `clean-implement-qc`, optional `clean-polish-review`, and `contaminated-coverage-verify`. The coverage verification phase is required. When present, `clean-polish-review` must run after `clean-implement-qc` and before `contaminated-coverage-verify`.
 
 When `task-manifest.json` sets `context_management.mode` to `role-session-briefs` and `context_management.enforcement` to `strict`, every configured stage must include `context.fresh_session: true` and `context.brief_path`. The runner validates the brief before spawn, passes only the brief path plus environment facts in the stage prompt, and records the brief ref/hash in `controller-run-ledger.json`.
 
@@ -286,6 +286,16 @@ Strict context-management adapter example:
         "brief_path": "/tmp/clean-room/task-1234abcd/clean/session-briefs/iter-001-agent-3.json"
       }
     },
+    {
+      "phase": "clean-polish-review",
+      "role": "clean-polish-reviewer",
+      "cwd": "/tmp/clean-room/task-1234abcd/implementation",
+      "argv": ["agent-cli", "--fresh-session", "--role", "clean-polish-reviewer"],
+      "context": {
+        "fresh_session": true,
+        "brief_path": "/tmp/clean-room/task-1234abcd/clean/session-briefs/iter-001-agent-4.json"
+      }
+    },
     {
       "phase": "contaminated-coverage-verify",
       "role": "contaminated-manager-verifier",

package/examples/codex/.codex/agents/clean-architect.toml

@@ -18,10 +18,15 @@ Stop if full preflight-goal.json, source index, contaminated ledgers, source pat
 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 to identify local structure, conventions, tests, 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 architecture areas with owned relative path prefixes, responsibilities, forbidden responsibilities, allowed area dependencies, and refactor triggers.
+Assign every target and test path in implementation-plan.json to one or more skeleton-manifest.json architecture areas.
+Record split, move, merge, or extract work as planned_refactors before Agent 3 performs cross-area structure changes.
 Create 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 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 relative implementation-root paths.
 Preserve source-test-derived scenarios as clean test obligations for equal output without copying source test structure.
+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.
 Stop if contaminated material appears in clean inputs.
 """

package/examples/codex/.codex/agents/clean-polish-reviewer.toml

@@ -0,0 +1,25 @@
+name = "clean-polish-reviewer"
+description = "Performs final clean code polish, repo hygiene, verification review, and constrained implementation-root commit."
+sandbox_mode = "workspace-write"
+model_reasoning_effort = "high"
+enabled_skills = ["clean-room"]
+
+instructions = """
+Act as Agent 4 in the clean-room pipeline.
+Run only in the clean domain after Agent 3 has produced terminal implementation and QC reports.
+Before tool use, require 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.
+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, source-index.json, the full task-manifest.json, or the full preflight-goal.json.
+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.
+Review final clean code 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 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.
+Do not use shell commands from this default profile. Use a separate isolated polish profile only when CLEAN_ROOM_ALLOW_AGENT4_SHELL=1, strict hooks are installed, the command cwd is inside CLEAN_ROOM_IMPLEMENTATION_ROOTS, and the command invokes the installed agent4-polish-runner.py.
+The polish 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.
+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.
+"""