clean-room-skill 0.1.7 → 0.1.8

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -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)
@@ -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,6 +29,7 @@ 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.

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-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,6 +29,7 @@ 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.
 - 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.

package/agents/contaminated-handoff-sanitizer.md

@@ -22,12 +22,14 @@ 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 public compatibility names only when they are listed in `public_surface` with a concrete compatibility reason.

package/agents/contaminated-manager-verifier.md

@@ -28,6 +28,7 @@ Responsibilities:
 - 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 `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.
@@ -50,6 +51,8 @@ Every new role session must receive `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`
 
 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.
 
+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 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`.

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.

package/bin/install.js

@@ -41,6 +41,7 @@ const INSTALL_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_LOCK_WAIT_MS
 const INSTALL_LOCK_POLL_MS = 100;
 const PYTHON_PROBE_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_PYTHON_TIMEOUT_MS', 10_000);
 const CLAUDE_PLUGIN_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_CLAUDE_PLUGIN_TIMEOUT_MS', 120_000);
+const CLAUDE_EXECUTABLE_ENV = 'CLEAN_ROOM_CLAUDE_EXECUTABLE';
 const CLAUDE_PLUGIN_MARKETPLACE_NAME = 'clean-room-skill';
 const CLAUDE_PLUGIN_NAME = 'clean-room';
 const CLAUDE_PLUGIN_ID = `${CLAUDE_PLUGIN_NAME}@${CLAUDE_PLUGIN_MARKETPLACE_NAME}`;
@@ -751,19 +752,155 @@ function truncateCommandOutput(value) {
   return `${text.slice(0, 2000)}...`;
 }
 
-function claudePluginEnv(layout) {
+function pathIsUnder(candidate, root) {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+function currentWorkingRoots() {
+  const cwd = path.resolve(process.cwd());
+  const roots = [cwd];
+  try {
+    const real = fs.realpathSync.native(cwd);
+    if (!roots.includes(real)) roots.push(real);
+  } catch {
+    // Keep the resolved cwd as the policy root if realpath is unavailable.
+  }
+  return roots;
+}
+
+function pathIsUnderAny(candidate, roots) {
+  return roots.some((root) => pathIsUnder(candidate, root));
+}
+
+function pathContainsNodeModulesBin(candidate) {
+  const parts = path.resolve(candidate).split(path.sep);
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (parts[i] === 'node_modules' && parts[i + 1] === '.bin') return true;
+  }
+  return false;
+}
+
+function unsafeClaudeExecutableReason(filePath, label) {
+  if (!filePath || typeof filePath !== 'string' || !path.isAbsolute(filePath)) {
+    return `${label} must be an absolute path`;
+  }
+  const resolved = path.resolve(filePath);
+  const cwdRoots = currentWorkingRoots();
+  if (pathIsUnderAny(resolved, cwdRoots)) {
+    return `${label} must not be under the current working directory`;
+  }
+  if (pathContainsNodeModulesBin(resolved)) {
+    return `${label} must not be under node_modules/.bin`;
+  }
+  let real;
+  try {
+    real = fs.realpathSync.native(resolved);
+  } catch {
+    return `${label} must resolve to an executable file`;
+  }
+  if (pathIsUnderAny(real, cwdRoots)) {
+    return `${label} target must not be under the current working directory`;
+  }
+  if (pathContainsNodeModulesBin(real)) {
+    return `${label} target must not be under node_modules/.bin`;
+  }
+  try {
+    const stat = fs.statSync(real);
+    fs.accessSync(real, fs.constants.X_OK);
+    if (!stat.isFile()) {
+      return `${label} must be an executable regular file`;
+    }
+  } catch {
+    return `${label} must be an executable regular file`;
+  }
+  return null;
+}
+
+function assertClaudeExecutable(filePath, label) {
+  const reason = unsafeClaudeExecutableReason(filePath, label);
+  if (reason) throw new Error(reason);
+  return path.resolve(filePath);
+}
+
+function sanitizedPathEntriesForClaude(value) {
+  const entries = String(value || '').split(path.delimiter).filter(Boolean);
+  const cwdRoots = currentWorkingRoots();
+  const seen = new Set();
+  return entries.filter((entry) => {
+    if (!path.isAbsolute(entry)) return false;
+    const normalized = path.resolve(entry);
+    if (pathIsUnderAny(normalized, cwdRoots)) return false;
+    try {
+      if (pathIsUnderAny(fs.realpathSync.native(normalized), cwdRoots)) return false;
+    } catch {
+      // Nonexistent PATH entries cannot provide claude; leave candidate validation to fail later.
+    }
+    if (pathContainsNodeModulesBin(normalized)) return false;
+    if (seen.has(normalized)) return false;
+    seen.add(normalized);
+    return true;
+  });
+}
+
+function sanitizePathForClaude(value) {
+  return sanitizedPathEntriesForClaude(value).join(path.delimiter);
+}
+
+function resolveClaudeExecutable() {
+  const configuredExecutable = process.env[CLAUDE_EXECUTABLE_ENV];
+  const searchPath = sanitizePathForClaude(process.env.PATH);
+  if (configuredExecutable) {
+    return {
+      executable: assertClaudeExecutable(configuredExecutable, CLAUDE_EXECUTABLE_ENV),
+      searchPath,
+    };
+  }
+
+  const entries = sanitizedPathEntriesForClaude(process.env.PATH);
+  if (entries.length === 0) {
+    throw new Error(`Claude plugin command requires ${CLAUDE_EXECUTABLE_ENV} or a non-empty sanitized PATH`);
+  }
+
+  const candidates = [];
+  const seenCandidates = new Set();
+  for (const entry of entries) {
+    const candidate = path.join(entry, 'claude');
+    if (unsafeClaudeExecutableReason(candidate, 'Claude executable')) continue;
+    const resolved = path.resolve(candidate);
+    let realCandidate;
+    try {
+      realCandidate = fs.realpathSync.native(resolved);
+    } catch {
+      continue;
+    }
+    if (seenCandidates.has(realCandidate)) continue;
+    seenCandidates.add(realCandidate);
+    candidates.push(resolved);
+  }
+
+  if (candidates.length === 1) {
+    return { executable: candidates[0], searchPath };
+  }
+  if (candidates.length > 1) {
+    throw new Error(`Claude plugin command found multiple claude executables on sanitized PATH; set ${CLAUDE_EXECUTABLE_ENV} to the intended absolute executable`);
+  }
+  throw new Error(`Claude plugin command requires ${CLAUDE_EXECUTABLE_ENV} or a claude executable on sanitized PATH`);
+}
+
+function claudePluginEnv(layout, searchPath) {
   return {
     ...process.env,
+    PATH: searchPath,
     CLAUDE_CONFIG_DIR: layout.targetRoot,
   };
 }
 
-function claudeCommandLabel(args) {
-  return ['claude', ...args].join(' ');
+function claudeCommandLabel(command, args) {
+  return [command, ...args].join(' ');
 }
 
-function claudePluginCommandFailure(args, result) {
-  const parts = [`Claude plugin command failed: ${claudeCommandLabel(args)}`];
+function claudePluginCommandFailure(command, args, result) {
+  const parts = [`Claude plugin command failed: ${claudeCommandLabel(command, args)}`];
   if (result.error) {
     parts.push(result.error.message);
   }
@@ -781,14 +918,16 @@ function claudePluginCommandFailure(args, result) {
 }
 
 function runClaudePluginCommand(layout, args, options = {}) {
-  const result = spawnSync('claude', args, {
+  const { executable: claudeExecutable, searchPath } = resolveClaudeExecutable();
+  const result = spawnSync(claudeExecutable, args, {
     encoding: 'utf8',
-    env: claudePluginEnv(layout),
+    env: claudePluginEnv(layout, searchPath),
     stdio: ['ignore', 'pipe', 'pipe'],
     timeout: CLAUDE_PLUGIN_TIMEOUT_MS,
   });
+  result.command = claudeExecutable;
   if (result.error || result.status !== 0) {
-    throw new Error(claudePluginCommandFailure(args, result));
+    throw new Error(claudePluginCommandFailure(claudeExecutable, args, result));
   }
   if (!options.silent) {
     if (result.stdout) process.stdout.write(result.stdout);
@@ -804,7 +943,7 @@ function readClaudePluginJson(layout, args) {
     return Array.isArray(parsed) ? parsed : [];
   } catch (err) {
     throw new Error(
-      `Claude plugin command returned invalid JSON: ${claudeCommandLabel(args)}; ` +
+      `Claude plugin command returned invalid JSON: ${claudeCommandLabel(result.command || 'claude', args)}; ` +
       `stdout: ${truncateCommandOutput(result.stdout)}; ${err.message}`
     );
   }

package/docs/ARCHITECTURE.md

@@ -14,11 +14,13 @@ The Clean Room workflow acts as an engineering risk-reduction process by establi
 
 ## Operating Model
 
+![Operating Model](assets/1.png)
+
 To maintain compliance and mitigate leakage risks, the workflow utilizes strictly separated workspaces, worktrees, repositories, or profiles for contaminated and clean work:
 
 *   **Contaminated Source Workspace**: Source-readable, read-only where practical. Contains the codebase under analysis.
-*   **Contaminated Artifact Workspace**: Holds intermediate outputs like preflight goals, init configs, source indexes, task manifests, coverage ledgers, evidence ledgers, draft specs, and abstract delta tickets. Configure via `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
-*   **Clean Artifact Workspace**: Houses sanitized clean run contexts, approved behavioral specifications, handoff packages, skeleton manifests, implementation plans, implementation reports, QC reports, and test plans. Configure via `CLEAN_ROOM_CLEAN_ROOTS`.
+*   **Contaminated Artifact Workspace**: Holds intermediate outputs like preflight goals, init configs, source indexes, task manifests, controller status, coverage ledgers, evidence ledgers, draft specs, contaminated-role session briefs, and abstract delta tickets. Configure via `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+*   **Clean Artifact Workspace**: Houses sanitized clean run contexts, approved behavioral specifications, handoff packages, clean-role session briefs, skeleton manifests, implementation plans, implementation reports, QC reports, and test plans. Configure via `CLEAN_ROOM_CLEAN_ROOTS`.
 *   **Clean Implementation Workspace**: Houses clean destination code and tests. Configure via `CLEAN_ROOM_IMPLEMENTATION_ROOTS`.
 *   **Clean Allowed Reference Workspace**: Public documentation, specifications, or destination constraints explicitly approved for clean and source-denied role reads. Configure via `CLEAN_ROOM_ALLOWED_READ_ROOTS`.
 
@@ -31,10 +33,14 @@ Optional Docker or Podman support is limited to Agent 3 verification containers.
 
 Artifact roots must not disclose private source names. New runs default to `~/Documents/CleanRoom/<task-id>/`; when no explicitly approved neutral task ID is provided, the controller generates `task-` plus 8 lowercase hex characters instead of using the source folder name.
 
+![Artifact Roots](assets/2.png)
+
 The initialization wizard and `require-clean-room-env.py` audit clean, implementation, and contaminated artifact root names. They fail closed when a path contains a source root basename or meaningful non-generic tokens from that basename, while filtering generic terms such as `src`, `app`, `test`, `repo`, and `workspace`.
 
 ### Stage 0 Goal Contract
 
+![Stage 0 Goal Contract](assets/3.png)
+
 Every new run starts with `preflight-goal.json` before source discovery, source indexing, Agent 0 decomposition, attended execution, or unattended execution. The contract records end goal, target stack, license policy, dependency policy, compatibility exactness, feature changes, code hygiene, output policy, controller mode, and open questions.
 
 `preflight-goal.json` is controller/contaminated-side only. Clean roles receive only clean-safe `goal_contract` fields and `code_hygiene_policy` through `clean-run-context.json`.
@@ -217,6 +223,8 @@ The architecture delegates work across five distinct custom role agents to enfor
 
 ### 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`.
 
 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`.
@@ -227,11 +235,12 @@ Agent 3's terminal report is not enough to return. Agent 0 must consume that rep
 *   Reloads durable artifacts before each iteration.
 *   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.
 *   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.
 
-Progress is durable-artifact based. `clean-room-skill run` compares semantic JSON artifact hashes that ignore volatile timestamp and artifact-hash fields, plus raw file hashes under implementation roots. Chat output alone and timestamp-only artifact churn do not count as progress.
+Progress is durable-artifact based. `clean-room-skill run` compares semantic JSON artifact hashes that ignore volatile timestamp and artifact-hash fields, plus raw file hashes under implementation roots. Chat output, timestamp-only artifact churn, and `controller-status.json` updates alone do not count as progress.
 
 ---
 
@@ -247,6 +256,8 @@ Every clean-room role session requires a populated environment block before any
 *   `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.
 
 ---

package/docs/HOOKS.md

@@ -0,0 +1,230 @@
+# Clean Room Hooks
+
+This page documents the hook guardrails installed by `clean-room-skill`: where they are installed, which runtime hook entries are generated, and what each hook script checks.
+
+The hooks are engineering guardrails. They reduce accidental cross-domain reads and writes, but they are not legal advice, a sandbox boundary, or proof that a host runtime emits every event needed for enforcement.
+
+## Install Locations
+
+The installer copies the Python hook files for every supported runtime layout. Runtime hook registration is verified only for Codex and Claude Code.
+
+| Runtime | Hook files copied to | Active hook config |
+| --- | --- | --- |
+| Codex | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/hooks.json` |
+| Claude Code | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/settings.json` |
+| Antigravity | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Gemini CLI | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| OpenCode | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Kilo | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Cursor | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| GitHub Copilot | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Windsurf | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Augment | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Trae | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Qwen Code | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| Hermes Agent | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| CodeBuddy | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+
+Codex uses `CODEX_HOME` or `~/.codex` for global installs. Claude Code uses `CLAUDE_CONFIG_DIR` or `~/.claude`. Other runtime roots are listed in [REFERENCE.md](REFERENCE.md#runtime-support).
+
+## Hook Modes
+
+| Mode | Behavior |
+| --- | --- |
+| `safe` | Default. Registers hooks for Codex or Claude, but `clean-room-hook.py` no-ops until a clean-room role environment is present or `CLEAN_ROOM_HOOK_ENFORCE` is truthy. |
+| `strict` | Registers hooks for Codex or Claude and fails closed even without clean-room role environment. Use only in dedicated clean-room runtime homes. |
+| `copy-only` | Copies hook files without modifying runtime hook config. This is also the effective behavior for runtimes without verified hook registration support. |
+
+`--no-hooks` is an alias for `--hooks=copy-only`.
+
+## Generated Runtime Hooks
+
+When hook mode is `safe` or `strict`, the installer registers four managed hook entries for Codex and Claude. Each entry invokes the installed `clean-room-hook.py` wrapper with an absolute Python path, an absolute wrapper path, the requested hook mode, and one or more `--check` scripts.
+
+| Event | Matcher | Checks |
+| --- | --- | --- |
+| `PreToolUse` | <code>Bash&#124;Shell&#124;PowerShell&#124;Monitor&#124;exec_command&#124;shell_command&#124;write_stdin</code> | `require-clean-room-env.py`, `deny-clean-room-shell.py` |
+| `PreToolUse` | <code>Read&#124;Glob&#124;Grep&#124;LS&#124;LSP&#124;NotebookRead&#124;view_image&#124;list_dir&#124;ListMcpResourcesTool&#124;ReadMcpResourceTool&#124;ListMcpResourceTemplatesTool&#124;list_mcp_resources&#124;list_mcp_resource_templates&#124;read_mcp_resource</code> | `require-clean-room-env.py`, `deny-clean-source-read.py` |
+| `PreToolUse` | <code>Write&#124;Edit&#124;MultiEdit&#124;NotebookEdit&#124;apply_patch</code> | `require-clean-room-env.py`, `deny-contaminated-clean-write.py` |
+| `PostToolUse` | <code>Write&#124;Edit&#124;MultiEdit&#124;NotebookEdit&#124;apply_patch</code> | `require-clean-room-env.py`, `check-artifact-leakage.py`, `validate-json-schema.py`, `validate-handoff-package.py` |
+
+Matcher names only matter if the host runtime emits the corresponding hook event. A host tool that reads files without a hook event is not protected by listing its name here.
+
+## Required Environment
+
+Role sessions must provide the full clean-room environment block so the hooks can validate boundaries:
+
+| Variable | Use |
+| --- | --- |
+| `CLEAN_ROOM_ROLE` | Active role. Valid roles are `contaminated-manager-verifier`, `contaminated-source-analyst`, `contaminated-handoff-sanitizer`, `clean-architect`, and `clean-qa-editor`. |
+| `CLEAN_ROOM_SOURCE_ROOTS` | Authorized source roots. Clean and source-denied roles must not read these. |
+| `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS` | Write roots for contaminated roles. |
+| `CLEAN_ROOM_CLEAN_ROOTS` | Write roots for clean artifacts and reports. |
+| `CLEAN_ROOM_IMPLEMENTATION_ROOTS` | Write roots for Agent 3 implementation code and tests. |
+| `CLEAN_ROOM_ALLOWED_READ_ROOTS` | Approved clean-safe reference roots for clean and source-denied roles. |
+| `CLEAN_ROOM_SCHEMA_DIR` | JSON schema directory. Must exist. |
+| `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST` | Optional path-separated denylist files for leakage scanning. |
+| `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` | Optional path-separated allowlist for unrecognized auxiliary JSON files under clean roots. |
+| `CLEAN_ROOM_ALLOW_AGENT3_SHELL` | Must be `1` before Agent 3 can invoke the verification runner through a shell-style tool. |
+| `CLEAN_ROOM_HOOK_ENFORCE` | Forces enforcement in `safe` mode when truthy. |
+| `CLEAN_ROOM_HOOK_CHECK_TIMEOUT_SECONDS` | Optional per-check wrapper timeout. Defaults to 10 seconds. |
+
+Root variables may contain multiple paths separated by the platform path separator.
+
+## Hook Scripts
+
+### `clean-room-hook.py`
+
+Dispatch wrapper used by generated runtime hook entries.
+
+- Enforces immediately in `strict` mode.
+- In `safe` mode, enforces only when `CLEAN_ROOM_HOOK_ENFORCE` is truthy or clean-room environment variables are present.
+- Reads the hook payload once from stdin and passes the same payload to each configured check.
+- Runs child checks with `sys.executable -I`, `PYTHONNOUSERSITE=1`, and `PYTHONDONTWRITEBYTECODE=1`.
+- Rejects invalid check names and missing check scripts.
+- Fails if any check fails or exceeds `CLEAN_ROOM_HOOK_CHECK_TIMEOUT_SECONDS`.
+
+### `require-clean-room-env.py`
+
+Precondition check for role sessions.
+
+- Requires non-empty role, source, contaminated artifact, clean, implementation, and schema root variables.
+- Requires `CLEAN_ROOM_ALLOWED_READ_ROOTS` for clean roles and the source-denied sanitizer role.
+- Validates the role name.
+- Resolves configured roots and requires `CLEAN_ROOM_SCHEMA_DIR` to exist.
+- Rejects overlap between source, clean, implementation, contaminated artifact, allowed-read, and schema roots where overlap would break separation.
+- Rejects clean, implementation, and contaminated artifact root names that appear source-derived from the source root basename.
+
+### `deny-clean-room-shell.py`
+
+Pre-tool shell policy.
+
+- Denies shell-style tools for all clean-room roles by default.
+- Allows Agent 3 (`clean-qa-editor`) only when `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`.
+- Agent 3 shell use must run from an implementation root and must invoke the installed `agent3-verification-runner.py`.
+- Rejects shell metacharacters, file URLs, unexpected runner flags, blocked source or contaminated roots, and runner plans outside clean roots.
+- Allows runner selectors only through `--command-index <n>` or `--all`, with optional `--plan`, `--timeout`, and `--backend host|docker|podman`.
+
+### `agent3-verification-runner.py`
+
+Bounded verification runner for Agent 3. This is not a host runtime hook entry by itself; it is the only shell target that `deny-clean-room-shell.py` permits for Agent 3.
+
+- Requires `CLEAN_ROOM_ROLE=clean-qa-editor` and `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`.
+- Loads verification commands from `implementation-plan.json` in clean roots, or from `--plan`.
+- Accepts argv-array commands only and executes with `shell=False`.
+- Requires command cwd values to use `CLEAN_ROOM_IMPLEMENTATION_ROOTS[n]`.
+- Allows a small command prefix set: npm, pnpm, yarn, bun, deno test commands; pytest directly or through Python; `cargo test`; `go test`; and `zig build test`.
+- Rejects shell syntax, blocked root references, file URLs, paths resolving outside the implementation root, and source or contaminated root traversal.
+- Runs with a sanitized environment and bounded stdout/stderr output.
+- Supports optional Docker or Podman execution with read-only clean/schema/reference mounts, a writable implementation mount, no network by default, dropped capabilities, no-new-privileges, resource limits, and no source or contaminated mounts.
+
+### `deny-clean-source-read.py`
+
+Pre-tool read policy for source-denied roles.
+
+- Applies to `clean-architect`, `clean-qa-editor`, and `contaminated-handoff-sanitizer`.
+- Clean roles may read clean roots, implementation roots, allowed-read roots, and schema roots.
+- The sanitizer may read contaminated artifact roots, allowed-read roots, and schema roots.
+- Denies reads from source roots.
+- Denies sanitizer reads from clean roots.
+- Denies direct reads of `preflight-goal.json` for source-denied roles.
+- Denies sanitizer reads of `source-index.json`.
+- Denies MCP resource access because no MCP resource allowlist is configured.
+- Fails closed when a path-required read tool has no resolvable path.
+
+### `deny-contaminated-clean-write.py`
+
+Pre-tool write policy for role-specific write roots.
+
+- Applies to contaminated and clean roles.
+- Clean roles cannot write source roots or read-only allowed-read roots.
+- Agent 2 (`clean-architect`) writes only under clean roots and is denied implementation roots.
+- Agent 3 (`clean-qa-editor`) may write under implementation roots and clean roots.
+- Contaminated roles cannot write clean, implementation, or source roots.
+- Contaminated roles may write only under `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`.
+- Fails closed for active clean-room roles when write paths cannot be resolved from the hook payload.
+
+### `check-artifact-leakage.py`
+
+Post-write leakage scanner.
+
+- Scans `.json`, `.md`, `.yaml`, `.yml`, and `.txt` artifacts under clean roots.
+- Also scans staged sanitizer artifacts under contaminated artifact roots.
+- Does not scan contaminated source analyst drafts.
+- Caps scanned artifact size at 1,000,000 bytes.
+- Detects raw diffs, source code fences, decompiler/source excerpt markers, stack-source lines, package/module identifiers, source-like calls, source-like scoped identifiers, and configured private denylist terms.
+- Loads denylist files from `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST`, capped at 1,000,000 bytes per file, 20,000 terms total, and 512 characters per term.
+- Treats selected JSON fields as unscanned, denylist-only, or light-scan fields to reduce false positives in path-like and metadata fields.
+- Allows public names declared in `public_surface` and `public_contracts` records when marked with public/destination/protocol/user-required visibility.
+
+### `validate-json-schema.py`
+
+Post-write JSON artifact validator.
+
+- Parses written `.json` files and validates recognized artifacts against schemas from `CLEAN_ROOM_SCHEMA_DIR`.
+- Recognizes canonical clean-room artifact kinds by filename and conservative field heuristics.
+- Fails closed for unrecognized JSON objects under clean roots unless the exact path is in `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST`.
+- Rejects `source-index`, `init-config`, and `preflight-goal` artifacts under clean roots.
+- Implements the lightweight schema keywords used by bundled schemas, including object and array constraints, required fields, enum/const, patterns, `format: date-time`, `$ref`, `allOf`, `anyOf`, `oneOf`, and `if`/`then`/`else`.
+- Adds clean-run-context path checks so clean artifact paths stay relative, do not use `~`, do not contain `..`, and do not resolve into source or contaminated roots.
+- Requires task manifest handoff stages to match the expected clean-room sequence when validating the task manifest schema.
+
+### `validate-handoff-package.py`
+
+Post-write handoff integrity validator.
+
+- Runs on written JSON files that look like handoff packages.
+- Requires handoff `artifacts` to be an array of object entries with non-empty paths.
+- Rejects `source-index.json`, `task-manifest.json`, and `preflight-goal.json` in clean handoff packages.
+- Resolves relative artifact paths against clean roots and rejects ambiguous paths across multiple clean roots.
+- Rejects artifact paths outside clean roots or inside source or contaminated roots.
+- Requires referenced artifacts to exist and have a 64-character `sha256`.
+- Hashes referenced files and fails on checksum mismatch.
+
+### `clean_room_paths.py`
+
+Shared helper module imported by the hook scripts.
+
+- Loads and bounds hook JSON payloads at 10 MiB.
+- Resolves candidate paths from common tool payload keys.
+- Resolves `cwd` safely from payload data or the current process.
+- Provides root parsing, path containment, root overlap checks, and active role detection.
+- Redacts configured roots and source-derived private path tokens in errors for clean-room roles by default.
+- Provides fail-closed written-file checks plus controlled `stat`, byte-read, and text-read helpers.
+
+## Failure Behavior
+
+The hook policy is deny-by-default during active clean-room role sessions.
+
+- Malformed hook payloads fail.
+- Oversized hook payloads fail.
+- Missing paths for path-required write checks fail.
+- Files that disappear, cannot be statted, cannot be read, or cannot be hashed fail with controlled errors.
+- Expected filesystem validation failures are reported without Python tracebacks.
+- Error output is redacted through root labels such as `source-root[0]`, `clean-root[0]`, and `contaminated-root[0]` for clean-room role contexts by default.
+
+## Verification
+
+Use `doctor` after installing Codex or Claude hooks:
+
+```bash
+clean-room-skill doctor --runtime codex --hooks=safe
+clean-room-skill doctor --runtime codex --hooks=strict
+clean-room-skill doctor --runtime codex --hooks=strict --coverage
+clean-room-skill doctor --runtime claude --hooks=strict --coverage
+```
+
+Add `--config-dir <path>` when checking a non-default runtime config root.
+
+`doctor` verifies that:
+
+- The hook config exists.
+- Exactly four managed clean-room hook entries are present.
+- Managed commands use absolute Python and wrapper paths.
+- The requested safe or strict mode is configured.
+- Safe mode no-ops without clean-room environment.
+- Strict mode and enforced safe mode fail without required environment.
+- Smoke payloads fail for source reads, source writes, shell bypasses, and malformed post-write JSON.
+- `--coverage` prints matcher and check coverage for the generated entries.
+
+`doctor` is a smoke test. It does not prove host event coverage, legal sufficiency, or full runtime isolation.