clean-room-skill 0.4.0 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "clean-room",
       "source": "./",
       "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "author": {
         "name": "whit3rabbit"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "clean-room",
   "displayName": "Clean Room",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/agents/clean-architect.md

@@ -49,6 +49,7 @@ Responsibilities:
 - Carry the preflight-derived code hygiene policy into `implementation-plan.json`.
 - 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.
+- In clean artifact prose fields, use plain language instead of implementation syntax such as scoped identifiers, dotted module paths, call expressions, exact test function names, or type constructor text. Put paths only in structured path fields and commands only in structured argv arrays.
 - Preserve public contract refs, dependency constraints, test mappings, and open decisions.
 - Do not choose dependencies by copying source manifests. Add or preserve dependencies only when clean artifacts, destination evidence, or preflight policy justify them.
 - Map every exact-public-contract or behavior-compatible public surface obligation to at least one `implementation-plan.json` work item through `public_contract_refs`; do not replace a public command/API inventory with one generic dispatch work item unless every obligation ref is listed.

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

@@ -36,6 +36,7 @@ Responsibilities:
 - Review leakage risk using `LEAKAGE-RULES.md`.
 - 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 `CLEAN_ROOM_CLEAN_ROOTS/implementation-report.json`.
+- In implementation and QC report prose fields, use plain language instead of implementation syntax such as scoped identifiers, dotted module paths, call expressions, exact test function names, or type constructor text. Put changed paths in `changed_paths`, test paths in `test_paths`, and commands in `verification_results.command`.
 - Keep `CLEAN_ROOM_CLEAN_ROOTS/qc-report.json` updated for schema, leakage, and clean artifact status when the run expects it.
 - Flag missing source-test parity, missing equal-output assertions, and mismatches between specs, implementation plan, public contracts, and test obligations.
 - Verify public-surface inventory parity item by item. Every required `public_surface:<spec_id>:<kind>:<name>` ref must be covered by tests, mapped to a completed work item, and represented in terminal verification; passing test counts or broad command-dispatch coverage is not enough.

package/agents/clean-polish-reviewer.md

@@ -42,6 +42,7 @@ Responsibilities:
 - 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, Agent 4 changed relative paths, verification results, residual risks, git status, commit message, commit hash/status, and abstract delta tickets in `polish-report.json`.
+- In polish report prose fields, use plain language instead of implementation syntax such as scoped identifiers, dotted module paths, call expressions, exact test function names, or type constructor text. Put changed paths in `changed_paths`, included commit paths in `git.include_paths`, and commands in `verification_results.command`.
 - Set `git.include_paths` to the union of terminal `implementation-report.json` `changed_paths` and Agent 4 `polish-report.json` `changed_paths`; do not include unreported dirty files.
 - When the controller must create the commit, write a pre-commit report with `final_status: "blocked"`, `git.commit_required: true`, and `git.commit_status: "not-run"`.
 - Mark `final_status` as `passed` only when high/blocker security, correctness, exception, resource, race, leakage, and verification findings are resolved and either the constrained local commit succeeded or clean-run-context explicitly disables Agent 4 commits with `git.commit_status: "not-needed"`.

package/agents/clean-qa-editor.md

@@ -57,6 +57,7 @@ Responsibilities:
 - Review leakage risk using `LEAKAGE-RULES.md`.
 - 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 `CLEAN_ROOM_CLEAN_ROOTS/implementation-report.json`.
+- In implementation and QC report prose fields, use plain language instead of implementation syntax such as scoped identifiers, dotted module paths, call expressions, exact test function names, or type constructor text. Put changed paths in `changed_paths`, test paths in `test_paths`, and commands in `verification_results.command`.
 - Keep `CLEAN_ROOM_CLEAN_ROOTS/qc-report.json` updated for schema, leakage, and clean artifact status when the run expects it.
 - Record architecture alignment in `CLEAN_ROOM_CLEAN_ROOTS/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.

package/agents/contaminated-manager-verifier.md

@@ -24,12 +24,12 @@ Before source discovery, decomposition, or role launch, verify:
 - `preflight-goal.json` exists, validates, and is recorded by hash in `task-manifest.json`.
 - `handoff_sequence` is present and starts with `preflight`.
 - Attended mode records unresolved preflight questions as pause gates.
-- Unattended mode has no open preflight questions and `unattended_allowed_after_preflight: true`.
+- Unattended mode has no open preflight questions, `unattended_allowed_after_preflight: true`, and `intent_confirmation` showing the end goal, target stack, and controller mode came from explicit user answers.
 
 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.
+- Do not infer end goal, target language, runtime, framework, package manager, test framework, dependency policy, license policy, exactness policy, output directory, or feature add/remove policy from source. If goal or target stack is unknown, leave blocking `open_questions`, keep unattended disabled, and do not write runner-ready `task-manifest.json` or `clean-run-context.json`.
 - 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.
@@ -40,7 +40,8 @@ Responsibilities:
 - When no indexable source code exists and screenshots/images are the authorized evidence, consume contaminated `visual-index.json` as fallback input only. In attended mode, pause before decomposition to ask what the screenshots are meant to accomplish: product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and whether visible words are public compatibility surface.
 - Split source scope into the durable tasklist as bounded `task-manifest.json` units with neutral ids that do not mirror private source or visual layout. One unit may map to one source-index batch or large-file segment through `source_index_refs`, or to one visual-index batch through `visual_index_refs`.
 - Create exactly one `unit_kind: "foundation"` unit before behavior units. Set `loop_context.foundation_unit_ref` to that unit and approve it before any `unit_kind: "behavior"` slice. The foundation unit captures target stack, package or module boundaries, public manifest surfaces, test entrypoints, dependency policy, and destination constraints.
-- Maintain `coverage-ledger.json` and `evidence-ledger.json` in the contaminated artifact workspace.
+- Maintain `coverage-ledger.json` and exactly one canonical `evidence-ledger.json` in the contaminated artifact workspace. Preserve existing evidence entries across units; do not allow per-unit evidence-ledger filenames.
+- Require every evidence-ledger entry `source_unit_ref` to be the assigned task-manifest unit id or accepted unit alias. Source paths, source-index refs, visual-index refs, and observation locations belong in `evidence_location_ref` or unit index refs, not in `source_unit_ref`.
 - 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.
@@ -49,7 +50,7 @@ Responsibilities:
 - When Agent 1 records `discovery_leads`, create neutral follow-up task units only when the lead is inside authorized scope. Do not silently expand `loop_context.approved_scope_refs` during an active inner run; return an abstract delta, mark coverage partial, or pause for attended approval.
 - For multi-segment source work, you may include a previous contaminated draft behavior spec in a later contaminated-analysis role-session brief only when it is under the contaminated artifact root, hash-checked, within context budgets, and still forbidden to clean or source-denied roles.
 - 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.
-- Do not mark a unit complete from summaries, claimed test counts, or progress prose alone. Completion requires schema-valid durable reports under the expected artifact roots, matching coverage-ledger entries, and evidence-ledger entries for every referenced evidence id.
+- Do not mark a unit complete from summaries, claimed test counts, or progress prose alone. Completion requires schema-valid durable reports under the expected artifact roots, matching coverage-ledger entries, and canonical evidence-ledger entries for every referenced evidence id.
 - For exact-public-contract or behavior-compatible units, split broad public surfaces into smaller units or maintain `coverage-ledger.json` `public_surface_coverage` entries for every required `public_surface:<spec_id>:<kind>:<name>` obligation. A covered unit requires each obligation to be covered, mapped to clean work, and verified.
 - Source-backed units with `source_index_refs` or `visual_index_refs` must have durable source/evidence coverage before `coverage_state: "covered"`. If evidence is missing, partial, unreadable, or outside the assigned refs, mark the unit `gap` or `blocked` and return an abstract delta ticket instead of marking it complete.
 - For full-parity runs, do not defer TUI, command, CLI, protocol, streaming, MCP, tool, public error, or config behavior while reporting completion. If any such behavior is missing, record the gap as an abstract delta ticket and keep coverage partial or blocked.

package/agents/contaminated-source-analyst.md

@@ -49,6 +49,8 @@ Responsibilities:
 - Treat discovered source tests as behavioral evidence and convert them into clean `test_scenarios` that validate the same observable outputs.
 - Record equal-output expectations for public return values, serialized data, CLI or API responses, errors, state changes, ordering, and compatibility-relevant side effects.
 - Use `evidence_refs` that point to contaminated-side ledger entries instead of including source text.
+- Maintain exactly one canonical contaminated-side `evidence-ledger.json`. Preserve existing entries and append or update entries by stable `evidence_id`; do not create per-unit evidence-ledger filenames.
+- Set each evidence entry `source_unit_ref` to the assigned task-manifest unit id or accepted unit alias, preferably `CLEAN_ROOM_SELECTED_UNIT_ID` when set. Put source file paths, source-index refs, visual-index refs, and observation locations in `evidence_location_ref`, not in `source_unit_ref`.
 - 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.
 - Do not mirror source dependency lists, package manifests, or private module layout. Mention a dependency only when it is public compatibility surface, destination evidence, or explicitly allowed by preflight policy.

package/hooks/check-artifact-leakage.py

@@ -126,6 +126,45 @@ SCAN_LIGHT_JSON_STRING_KEYS = {
     "action",
     "formatting_rules",
 }
+JSON_PATH_KEY_ALLOWLIST = NEVER_SCAN_JSON_STRING_KEYS | DENYLIST_ONLY_JSON_STRING_KEYS | SCAN_LIGHT_JSON_STRING_KEYS | {
+    "acceptance_criteria",
+    "architecture_findings",
+    "architecture_summary",
+    "claim",
+    "constraints",
+    "dependency_constraints",
+    "description",
+    "expected_result",
+    "findings",
+    "formatting_rules",
+    "implementation_forbidden_material",
+    "invariants",
+    "leakage_review",
+    "leakage_scan_summary",
+    "local_patterns",
+    "name",
+    "negative_behaviors",
+    "notes",
+    "observable_behaviors",
+    "observable_surface",
+    "open_decisions",
+    "open_questions",
+    "output_summary",
+    "outputs",
+    "purpose",
+    "reason",
+    "requirements",
+    "residual_risks",
+    "responsibilities",
+    "risks",
+    "scenario",
+    "state_transitions",
+    "summary",
+    "target_constraints",
+    "test_obligations",
+    "test_scenarios",
+    "timing_or_ordering",
+}
 IMPLEMENTATION_METADATA_MANIFESTS = {
     "Cargo.toml",
     "go.mod",
@@ -344,14 +383,43 @@ def strip_allowed_text(text: str, allowed_names: set[str]) -> str:
     return stripped
 
 
+def json_path(path: tuple[str | int, ...]) -> str:
+    if not path:
+        return "$"
+    rendered = "$"
+    for item in path:
+        if isinstance(item, int):
+            rendered += f"[{item}]"
+        elif item in JSON_PATH_KEY_ALLOWLIST:
+            rendered += f".{item}"
+        else:
+            rendered += ".<field>"
+    return rendered
+
+
+def format_finding_details(details: list[tuple[str, str]]) -> str:
+    grouped: dict[str, set[str]] = {}
+    for name, location in details:
+        grouped.setdefault(name, set()).add(location)
+    parts: list[str] = []
+    for name in sorted(grouped):
+        locations = sorted(grouped[name])
+        shown = locations[:3]
+        suffix = f" at {', '.join(shown)}"
+        if len(locations) > len(shown):
+            suffix += f", +{len(locations) - len(shown)} more"
+        parts.append(f"{name}{suffix}")
+    return ", ".join(parts)
+
+
 def json_scan_strings(
     value: object,
     allowed_names: set[str],
     path: tuple[str | int, ...] = (),
-) -> tuple[list[str], list[str], list[str]]:
-    full_scan: list[str] = []
-    light_scan: list[str] = []
-    denylist_scan: list[str] = []
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]], list[tuple[str, str]]]:
+    full_scan: list[tuple[str, str]] = []
+    light_scan: list[tuple[str, str]] = []
+    denylist_scan: list[tuple[str, str]] = []
     if isinstance(value, dict):
         for key, item in value.items():
             child_full, child_light, child_denylist = json_scan_strings(item, allowed_names, path + (key,))
@@ -369,62 +437,69 @@ def json_scan_strings(
         if leaf_key in NEVER_SCAN_JSON_STRING_KEYS:
             return full_scan, light_scan, denylist_scan
         stripped = strip_allowed_text(value, allowed_names)
+        location = json_path(path)
         if leaf_key in DENYLIST_ONLY_JSON_STRING_KEYS:
-            denylist_scan.append(stripped)
+            denylist_scan.append((location, stripped))
         elif leaf_key in SCAN_LIGHT_JSON_STRING_KEYS:
-            light_scan.append(stripped)
+            light_scan.append((location, stripped))
         else:
-            full_scan.append(stripped)
+            full_scan.append((location, stripped))
     return full_scan, light_scan, denylist_scan
 
 
-def scan_private_identifier_denylist(texts: list[str], private_patterns: list[tuple[str, re.Pattern[str]]]) -> list[str]:
-    findings: set[str] = set()
-    for text in texts:
+def scan_private_identifier_denylist(
+    texts: list[tuple[str, str]],
+    private_patterns: list[tuple[str, re.Pattern[str]]],
+) -> list[tuple[str, str]]:
+    findings: set[tuple[str, str]] = set()
+    for location, text in texts:
         for _term, pattern in private_patterns:
             if pattern.search(text):
-                findings.add("private_identifier_denylist")
+                findings.add(("private_identifier_denylist", location))
                 break
     return sorted(findings)
 
 
-def scan_source_derived_names(texts: list[str], source_patterns: list[tuple[str, re.Pattern[str]]]) -> list[str]:
-    findings: set[str] = set()
-    for text in texts:
+def scan_source_derived_names(
+    texts: list[tuple[str, str]],
+    source_patterns: list[tuple[str, re.Pattern[str]]],
+) -> list[tuple[str, str]]:
+    findings: set[tuple[str, str]] = set()
+    for location, text in texts:
         for _term, pattern in source_patterns:
             if pattern.search(text):
-                findings.add("source_derived_name")
+                findings.add(("source_derived_name", location))
                 break
     return sorted(findings)
 
 
 def scan_identifier_patterns(
-    texts: list[str],
+    texts: list[tuple[str, str]],
     private_patterns: list[tuple[str, re.Pattern[str]]],
     skipped_patterns: set[str] | None = None,
-) -> list[str]:
-    findings: set[str] = set()
+) -> list[tuple[str, str]]:
+    findings: set[tuple[str, str]] = set()
     skipped_patterns = skipped_patterns or set()
-    for text in texts:
+    for location, text in texts:
         for _term, pattern in private_patterns:
             if pattern.search(text):
-                findings.add("private_identifier_denylist")
+                findings.add(("private_identifier_denylist", location))
                 break
         for name, pattern in IDENTIFIER_PATTERNS.items():
             if name in skipped_patterns:
                 continue
             if any(identifier_match_is_finding(name, text, match) for match in pattern.finditer(text)):
-                findings.add(name)
+                findings.add((name, location))
     return sorted(findings)
 
 
-def identifier_scan_texts(path: Path, text: str) -> tuple[list[str], list[str], list[str]]:
+def identifier_scan_texts(path: Path, text: str) -> tuple[list[tuple[str, str]], list[tuple[str, str]], list[tuple[str, str]]]:
     if path.suffix.lower() != ".json":
-        return [strip_allowed_text(text, set())], [], []
+        return [("$", strip_allowed_text(text, set()))], [], []
     try:
         data = json.loads(text)
     except json.JSONDecodeError:
-        return [strip_allowed_text(text, set())], [], []
+        return [("$", strip_allowed_text(text, set()))], [], []
     allowed_names = public_names(data)
     return json_scan_strings(data, allowed_names)
 
@@ -465,7 +540,7 @@ def main() -> int:
             print(f"clean-room leakage scan failed: {redact_text(read_error)}", file=sys.stderr)
             return 1
         text = data.decode("utf-8", errors="replace")
-        findings = [name for name, pattern in BLOCKED_PATTERNS.items() if pattern.search(text)]
+        findings = [(name, "$") for name, pattern in BLOCKED_PATTERNS.items() if pattern.search(text)]
         full_scan_texts, light_scan_texts, denylist_scan_texts = identifier_scan_texts(path, text)
         findings.extend(scan_identifier_patterns(full_scan_texts, private_patterns))
         findings.extend(
@@ -484,7 +559,8 @@ def main() -> int:
         )
         if findings:
             print(
-                f"clean-room leakage scan failed for {describe_path(path)}: {', '.join(sorted(set(findings)))}",
+                f"clean-room leakage scan failed for {describe_path(path)}: "
+                f"{format_finding_details(sorted(set(findings)))}",
                 file=sys.stderr,
             )
             return 1

package/lib/preflight-validation.cjs

@@ -9,6 +9,8 @@ const {
   VALID_NETWORK_POLICIES,
 } = require('./preflight-constants.cjs');
 
+const EXPLICIT_USER_ANSWER = 'explicit-user-answer';
+
 /**
  * Assert that a value is an object (not null and not an array), appending errors on failure.
  * @param {any} value - Value to check.
@@ -98,6 +100,43 @@ function validateStringArray(root, field, errors) {
   }
 }
 
+function isPlaceholderText(value) {
+  if (typeof value !== 'string') return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === '' ||
+    normalized === 'tbd' ||
+    normalized.startsWith('tbd:') ||
+    normalized === 'todo' ||
+    normalized.startsWith('todo:') ||
+    normalized === 'unknown';
+}
+
+function validateCompletedGoalFields(goal, errors) {
+  if (isPlaceholderText(goal?.end_goal?.success_definition)) {
+    errors.push('completed preflight input requires user-confirmed end_goal.success_definition, not a placeholder');
+  }
+  if (expectObject(goal?.target_stack, 'target_stack', errors)) {
+    for (const field of ['language', 'runtime', 'framework', 'package_manager', 'test_framework']) {
+      const value = goal.target_stack[field];
+      if (value !== null && isPlaceholderText(value)) {
+        errors.push(`completed preflight input requires user-confirmed target_stack.${field}, not a placeholder`);
+      }
+    }
+  }
+}
+
+function validateIntentConfirmation(goal, errors) {
+  if (!expectObject(goal.intent_confirmation, 'intent_confirmation', errors)) return;
+  expectString(goal.intent_confirmation.confirmed_at, 'intent_confirmation.confirmed_at', errors);
+  for (const field of ['end_goal_source', 'target_stack_source', 'controller_mode_source']) {
+    if (goal.intent_confirmation[field] !== EXPLICIT_USER_ANSWER) {
+      errors.push(`intent_confirmation.${field} must be "${EXPLICIT_USER_ANSWER}"`);
+    }
+  }
+  expectString(goal.intent_confirmation.user_goal_summary, 'intent_confirmation.user_goal_summary', errors);
+  expectString(goal.intent_confirmation.user_target_stack_summary, 'intent_confirmation.user_target_stack_summary', errors);
+}
+
 /**
  * Validate a preflight goal contract object.
  * @param {object} goal - Goal contract object to validate.
@@ -215,6 +254,23 @@ function validateGoalContract(goal, options = {}) {
     if (blocking.length > 0) {
       errors.push('completed preflight input must not contain blocking open_questions');
     }
+    validateCompletedGoalFields(goal, errors);
+    if (goal.intent_confirmation === undefined) {
+      errors.push('completed preflight input requires intent_confirmation with explicit user-confirmed end goal and target stack');
+    } else {
+      validateIntentConfirmation(goal, errors);
+    }
+  } else if (goal.intent_confirmation !== undefined) {
+    validateIntentConfirmation(goal, errors);
+  }
+
+  if (options.requireUnattended) {
+    if (goal.controller_policy?.mode !== 'unattended') {
+      errors.push('runner-ready preflight requires controller_policy.mode="unattended"');
+    }
+    if (!options.requireComplete && goal.intent_confirmation === undefined) {
+      errors.push('runner-ready preflight requires intent_confirmation with explicit user-confirmed end goal and target stack');
+    }
   }
 
   return errors;

package/lib/run-coverage.cjs

@@ -90,6 +90,23 @@ function evidenceEntryMap(roots) {
   return { evidence, map };
 }
 
+function evidenceLedgerMissingMessage(ref) {
+  return [
+    `coverage-ledger references evidence but canonical evidence-ledger.json is missing: ${ref}`,
+    'write one contaminated-side evidence-ledger.json; do not use per-unit evidence-ledger filenames',
+  ].join('; ');
+}
+
+function evidenceSourceUnitMismatchMessage(ref, unitId) {
+  return [
+    `coverage-ledger evidence ref points at a different source unit: ${ref}`,
+    'evidence source_unit_ref was rejected; value not shown because it may contain a source path or private identifier',
+    `coverage unit_id=${unitId}`,
+    `source_unit_ref must be the task-manifest unit id or accepted unit alias (${[...unitRefValues(unitId)].join(', ')})`,
+    'source paths belong in evidence_location_ref or source_index_refs/visual_index_refs, not source_unit_ref',
+  ].join('; ');
+}
+
 function hasUnresolvedCoverageTicket(coverageLedger, unitId) {
   return (coverageLedger?.abstract_delta_tickets || []).some((ticket) => {
     return (!ticket.unit_id || ticket.unit_id === unitId) && ticket.status !== 'resolved';
@@ -304,15 +321,15 @@ function validateCoverageLedgerIntegrity(manifest, roots, coverageLedger) {
   if (evidenceRefs.length > 0) {
     const { evidence, map } = evidenceEntryMap(roots);
     if (!evidence) {
-      throw new Error(`coverage-ledger references evidence but evidence-ledger.json is missing: ${evidenceRefs[0].ref}`);
+      throw new Error(evidenceLedgerMissingMessage(evidenceRefs[0].ref));
     }
     for (const { ref, evidenceId, unitId } of evidenceRefs) {
       const entry = map.get(evidenceId);
       if (!entry) {
-        throw new Error(`coverage-ledger references missing evidence-ledger item: ${ref}`);
+        throw new Error(`coverage-ledger references missing evidence-ledger item in canonical evidence-ledger.json: ${ref}`);
       }
       if (entry.source_unit_ref && !unitRefValues(unitId).has(entry.source_unit_ref)) {
-        throw new Error(`coverage-ledger evidence ref points at a different source unit: ${ref}`);
+        throw new Error(evidenceSourceUnitMismatchMessage(ref, unitId));
       }
     }
   }

package/lib/run-roots.cjs

@@ -4,7 +4,8 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const { fileHash } = require('./fs-utils.cjs');
+const { fileHash, readJsonFile } = require('./fs-utils.cjs');
+const { validateGoalContract } = require('./preflight-validation.cjs');
 const {
   BASE_ENV_ALLOWLIST,
   CI_ENV_ALLOWLIST,
@@ -224,6 +225,14 @@ function verifyPreflightGoal(manifest, manifestDir, roots) {
   if (actual !== expectedHash) {
     throw new Error(`preflight goal sha256 mismatch: ${preflightGoalPath}`);
   }
+  const preflightGoal = readJsonFile(preflightGoalRealPath, null);
+  const errors = validateGoalContract(preflightGoal, { requireComplete: true, requireUnattended: true });
+  if (preflightGoal?.controller_policy?.mode !== manifest.controller_policy?.mode) {
+    errors.push('preflight goal controller_policy.mode must match task-manifest controller_policy.mode');
+  }
+  if (errors.length > 0) {
+    throw new Error(`preflight goal is not runner-ready:\n  ${errors.join('\n  ')}`);
+  }
 }
 
 function pathIsUnder(child, parent) {

package/package.json

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

package/plugin.json

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

package/skills/clean-room/SKILL.md

@@ -44,7 +44,7 @@ Agent zero/controller must set and pass the clean-room environment block into ev
 
 When `context_management.mode` is `role-session-briefs`, every role session starts from `CLEAN_ROOM_SESSION_BRIEF_PATH` plus the environment block. In `strict` enforcement, the controller must start a fresh model session, profile, or thread for each role, pass `CLEAN_ROOM_FRESH_CONTEXT_REQUIRED=1`, and keep the stage prompt, session brief, artifact ref count, and referenced artifact bytes inside the recorded budgets. Do not clear or delete durable artifacts to save tokens. Clear only model/chat context between roles.
 
-`preflight-goal.json` is required before source indexing, visual indexing, or Agent 0 decomposition. It records the end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature policy, code hygiene limits, output policy, and controller mode. It is controller/contaminated-side only; clean roles receive only the clean-safe `goal_contract` subset and `code_hygiene_policy` through `clean-run-context.json`.
+`preflight-goal.json` is required before source indexing, visual indexing, or Agent 0 decomposition. It records the end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature policy, code hygiene limits, output policy, and controller mode. Completed preflight inputs and unattended contracts also record `intent_confirmation` with explicit user-confirmed end goal, target stack, and controller mode. It is controller/contaminated-side only; clean roles receive only the clean-safe `goal_contract` subset and `code_hygiene_policy` through `clean-run-context.json`.
 
 When source scope is larger than a single obvious unit, run `scripts/build_source_index.py` as source-index preflight before starting clean-room role sessions. The resulting `source-index.json` is contaminated-only input for Agent 0. It may contain source paths, import/export names, dependency relationships, large-file segment spans, and optional local AST/indexing tool status, so do not place it in clean handoff packages or expose it to Agent 1.5, Agent 2, Agent 3, or Agent 4.
 
@@ -54,7 +54,7 @@ Optional AST/indexing helpers are detected before the controller loop through `s
 
 Controller mode defaults to `attended` when `task-manifest.json` has no `controller_policy`. The outer loop evolves specs and selects one approved spec slice. Code-development runs start with exactly one `unit_kind: "foundation"` unit named by `loop_context.foundation_unit_ref`; non-foundation behavior slices wait until that unit is covered. The inner clean-room loop completes the approved slice through sanitized handoff, implementation, QC, optional final polish review, and contaminated-side coverage verification, then returns `clean-room-result.json` to the outer loop. In `attended` mode, agent zero pauses for human review at scope gate, handoff, QC deltas, polish deltas, blocked units, and final coverage. In `unattended` mode, agent zero may run a bounded inner loop: reload durable artifacts for each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, start each role from fresh context with the required environment block, validate before advancing, and stop on any configured safety or ambiguity condition.
 
-In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` when possible. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude`. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`; the runner uses bundled schemas by default. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
+In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` when possible and only after `task-manifest.json` has `loop_context` naming an approved pending or gap unit. If an unattended manifest lacks `loop_context`, treat it as incomplete outer-loop state and finish selected-slice approval before the runner is invoked. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude`. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`; the runner uses bundled schemas by default. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work once runner-ready unattended state exists, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
 
 Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3/4 role sessions. Agent 3 terminal verification may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`, the command cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent3-verification-runner.py`. Agent 4 polish verification and commit may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent4-polish-runner.py`. Use `--hooks=strict` for dedicated Codex, Claude, or OpenCode clean-room homes so hooks fail closed if required environment is missing or shell tools are invoked outside the allowed runner boundaries. Safe hook installs are compatibility-only between runs; during init/onboarding, prepare the role environment block and pass it into every clean-room role session so safe hooks enforce during active work.
 
@@ -93,7 +93,7 @@ Classify the selected candidate before starting the wizard:
 - Invalid `preflight-goal.json`: stop, report canonical schema or required-field errors, and do not create a replacement preflight.
 - No artifacts found: start the normal preflight wizard.
 
-Load or create `preflight-goal.json` only after this discovery step. Do not start attended or unattended execution until the goal contract records the end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature add/remove policy, code hygiene limits, output policy, existing destination policy, and controller mode.
+Load or create `preflight-goal.json` only after this discovery step. Do not start attended or unattended execution until the goal contract records the end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature add/remove policy, code hygiene limits, output policy, existing destination policy, and controller mode. Do not infer end goal, target language, runtime, framework, package manager, or test framework from source contents. If the user's end goal or target stack is unknown, record blocking `open_questions`, keep unattended disabled, and do not write runner-ready `task-manifest.json` or `clean-run-context.json`.
 
 Gather only the setup facts needed to decide whether the workflow may start, or invoke `init` when the user wants a dedicated setup pass:
 
@@ -101,7 +101,7 @@ Gather only the setup facts needed to decide whether the workflow may start, or
 - Artifact base root. Default the task root to `~/Documents/CleanRoom/<project>/tasks/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
 - Project grouping. Default to the clean-room project layout: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root for every task in the project. When the user does not supply an approved neutral project name, generate `proj-` plus 8 lowercase hex characters; it must match `[a-z0-9][a-z0-9-]{0,63}`, must never be derived from source or destination folder basenames or meaningful source-name tokens, and appears in paths clean roles can see. Use the legacy flat `<base>/<task-id>/` layout only when the user explicitly chooses single-task compatibility. Only one task per project may run at a time because tasks share the implementation root; the durable runner enforces this with an advisory `.clean-room-implementation.lock` in each implementation root.
 - Source roots or fallback visual evidence roots, contaminated artifact root, clean artifact root, clean implementation root, quarantine root, and optional public or destination reference roots.
-- Target stack and destination constraints from `preflight-goal.json`.
+- Explicit user-confirmed end goal, target stack, and destination constraints from `preflight-goal.json`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
 - Default model plus optional clean, contaminated, or per-role overrides.
 - Additional user rules split into clean-safe and contaminated-only rules.
@@ -113,7 +113,7 @@ Before indexing or artifact generation, confirm that source roots, contaminated
 
 For `attended` mode, record a `controller_policy` that pauses for human review at scope gate, clean handoff, terminal implementation deltas, blocked units, and final coverage. Include stop conditions for `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, and `coverage-complete`; attended mode does not add an iteration-limit stop unless the user explicitly sets one.
 
-For `unattended` mode, require explicit authorization, separated roots, finite bounds, `loop_context`, and a complete `preflight-goal.json` with no `open_questions` and `unattended_allowed_after_preflight: true` before work starts. Record `controller_policy.mode` as `unattended`, `max_units_per_iteration` as `1`, `max_iterations` from preflight, and include these stop conditions: `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, `coverage-complete`, `iteration-limit-reached`, `spec-slice-complete`, `spec-slice-blocked`, `spec-delta-required`, `no-progress-detected`, `repeated-unit-selection`, and `clean-room-returned`.
+For `unattended` mode, require explicit authorization, separated roots, finite bounds, `loop_context`, and a complete `preflight-goal.json` with no `open_questions`, `intent_confirmation` for explicit user-confirmed goal and target stack, and `unattended_allowed_after_preflight: true` before work starts. Record `controller_policy.mode` as `unattended`, `max_units_per_iteration` as `1`, `max_iterations` from preflight, and include these stop conditions: `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, `coverage-complete`, `iteration-limit-reached`, `spec-slice-complete`, `spec-slice-blocked`, `spec-delta-required`, `no-progress-detected`, `repeated-unit-selection`, and `clean-room-returned`.
 
 Default sequence:
 

package/skills/clean-room/assets/evidence-ledger.schema.json

@@ -41,6 +41,7 @@
           },
           "source_unit_ref": {
             "type": "string",
+            "description": "Task-manifest unit id or accepted unit alias for the assigned unit. Do not put source paths here; use evidence_location_ref and source_index_refs or visual_index_refs for source/index location details.",
             "minLength": 1
           },
           "evidence_type": {
@@ -58,6 +59,7 @@
           },
           "evidence_location_ref": {
             "type": "string",
+            "description": "Contaminated-only pointer to where the evidence was observed, such as a source-index ref, visual-index ref, or other non-clean location reference.",
             "minLength": 1
           },
           "source_hash": {

package/skills/clean-room/assets/preflight-goal.schema.json

@@ -26,6 +26,41 @@
       "type": "string",
       "format": "date-time"
     },
+    "intent_confirmation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "confirmed_at",
+        "end_goal_source",
+        "target_stack_source",
+        "controller_mode_source",
+        "user_goal_summary",
+        "user_target_stack_summary"
+      ],
+      "properties": {
+        "confirmed_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "end_goal_source": {
+          "const": "explicit-user-answer"
+        },
+        "target_stack_source": {
+          "const": "explicit-user-answer"
+        },
+        "controller_mode_source": {
+          "const": "explicit-user-answer"
+        },
+        "user_goal_summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "user_target_stack_summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "end_goal": {
       "type": "object",
       "additionalProperties": false,
@@ -371,6 +406,9 @@
         ]
       },
       "then": {
+        "required": [
+          "intent_confirmation"
+        ],
         "properties": {
           "controller_policy": {
             "properties": {

package/skills/clean-room/examples/contaminated-side/preflight-goal.json

@@ -1,6 +1,14 @@
 {
   "goal_id": "goal-task-example",
   "created_at": "2024-01-01T00:00:00Z",
+  "intent_confirmation": {
+    "confirmed_at": "2024-01-01T00:00:00Z",
+    "end_goal_source": "explicit-user-answer",
+    "target_stack_source": "explicit-user-answer",
+    "controller_mode_source": "explicit-user-answer",
+    "user_goal_summary": "Build a behavior-compatible clean implementation from approved clean specs.",
+    "user_target_stack_summary": "JavaScript on Node.js with npm and node:test."
+  },
   "end_goal": {
     "intent": "clean-room-reimplementation",
     "success_definition": "Build a behavior-compatible clean implementation from approved clean specs.",

package/skills/clean-room/examples/contaminated-side/task-manifest.json

@@ -17,7 +17,7 @@
   "source_acquisition_basis": "Authorized local source access.",
   "license_contract_notes": "No legal conclusion recorded.",
   "preflight_goal_ref": "preflight-goal.json",
-  "preflight_goal_sha256": "7c06e4696a4f116c7f62823facad18c9ccc666f9efbfd48cf561eed5f3a1330d",
+  "preflight_goal_sha256": "a168b62605d5e3e262ba388e9fc75d99b1413450cd8aa0d96861e6d6496e9420",
   "source_index_ref": "source-index.json",
   "run_state": {
     "generation": 1,

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

@@ -8,6 +8,7 @@ Ask only enough to fill `preflight-goal.json`:
 
 - End goal: clean reimplementation, behavior-compatible port, API-compatible clone, modernization, partial extraction, or spec/test generation only.
 - Target stack: language, runtime, framework, package manager, and test framework.
+- Intent confirmation: completed and unattended contracts must record that end goal, target stack, and controller mode came from explicit user answers.
 - Exactness: public APIs, CLI behavior, config files, output formats, error codes, UI behavior, or behavior-only.
 - Visual fallback: when no source code is available, confirm what authorized screenshots are meant to accomplish, the target user flow, screenshot coverage, target stack, UI exactness boundary, and whether visible words are public compatibility surface.
 - Forbidden mirroring: internal names, private structure, comments, source file layout, private helper behavior, and dependencies.
@@ -20,7 +21,7 @@ Ask only enough to fill `preflight-goal.json`:
 
 ## Defaults
 
-Record every default as an assumption. Good defaults:
+Record every default as an assumption. Do not default the end goal or target stack from source code. Source language, runtime, framework, package manager, and test framework describe the input, not the user's requested destination. If either the end goal or target stack is unknown, keep a blocking `open_questions` entry and do not mark an unattended contract complete. Good defaults:
 
 - Artifact base: `~/Documents/CleanRoom/<project>/tasks/<task-id>/`.
 - Implementation root: `~/Documents/CleanRoom/<project>/implementation/`.

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

@@ -118,7 +118,7 @@ Contaminated manager/verifier:
 
 - Confirm authorization and source scope.
 - Create or validate `preflight-goal.json` before source discovery and record its ref/hash in `task-manifest.json`.
-- Do not infer target language, dependency policy, license policy, exactness policy, output directory, or feature add/remove policy from source.
+- Do not infer end goal, target language, runtime, framework, package manager, test framework, dependency policy, license policy, exactness policy, output directory, or feature add/remove policy from source. Completed and unattended preflight contracts require explicit user intent confirmation.
 - Create or update controller-side `init-config.json` when the user invokes initialization, then snapshot effective preferences into `task-manifest.json`.
 - Produce sanitized `clean-run-context.json` for Agent 2, Agent 3, and Agent 4. Include clean artifact paths, implementation root environment references, target profile, clean-safe goal contract fields, code hygiene policy, approved public refs, clean-safe rules, clean-side model preferences, and artifact-only coordination policy only.
 - Record optional `context_management` budgets in `task-manifest.json` and `clean-run-context.json` when low-context handoffs are enabled.

package/skills/clean-room/scripts/build_visual_index.py

@@ -260,7 +260,7 @@ def collect_images(
     ignore_dirs = set(DEFAULT_IGNORE_DIRS) | set(args.ignore_dir)
     images: list[dict[str, Any]] = []
     skipped_entries: list[dict[str, str]] = []
-    counters = {"skipped_count": 0, "total_bytes": 0}
+    counters = {"skipped_count": 0, "total_bytes": 0, "attempted_total_bytes": 0}
     next_image_id = 1
 
     for root in roots:
@@ -270,7 +270,7 @@ def collect_images(
         def limit_reached_reason() -> str | None:
             if len(images) >= args.max_files:
                 return "file-count-limit"
-            if counters["total_bytes"] >= args.max_total_bytes:
+            if counters["attempted_total_bytes"] >= args.max_total_bytes:
                 return "total-byte-limit"
             return None
 
@@ -347,7 +347,7 @@ def collect_images(
                 if stat.st_size > args.max_file_bytes:
                     add_skipped(skipped_entries, counters, rel, "file-byte-limit", "file")
                     continue
-                if counters["total_bytes"] + stat.st_size > args.max_total_bytes:
+                if counters["attempted_total_bytes"] + stat.st_size > args.max_total_bytes:
                     add_skipped(skipped_entries, counters, rel, "total-byte-limit", "file")
                     continue
 
@@ -367,9 +367,10 @@ def collect_images(
                 if len(data) > args.max_file_bytes:
                     add_skipped(skipped_entries, counters, rel, "file-byte-limit-after-read", "file")
                     continue
-                if counters["total_bytes"] + len(data) > args.max_total_bytes:
+                counters["attempted_total_bytes"] += len(data)
+                if counters["attempted_total_bytes"] > args.max_total_bytes:
                     add_skipped(skipped_entries, counters, rel, "total-byte-limit-after-read", "file")
-                    continue
+                    break
 
                 metadata = image_metadata(data, suffix)
                 if metadata is None:

package/skills/init/SKILL.md

@@ -13,7 +13,9 @@ Initialize or revise durable Clean Room run preferences before source analysis s
 
 ## Preflight Goal Contract
 
-Before creating active artifacts, collect or confirm `preflight-goal.json`. Do not start attended or unattended execution until the goal contract records end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature add/remove policy, code hygiene limits, output policy, existing destination policy, and controller mode.
+Before creating active artifacts, collect or confirm `preflight-goal.json`. Do not start attended or unattended execution until the goal contract records end goal, target stack, license policy, dependency policy, compatibility/exactness policy, feature add/remove policy, code hygiene limits, output policy, existing destination policy, and controller mode. Completed preflight inputs and unattended contracts must also record `intent_confirmation` proving the end goal, target stack, and controller mode came from explicit user answers.
+
+Do not infer the user's end goal or target stack from the source repository. A source stack is not a destination stack; ports and rewrites often intentionally change language, runtime, framework, package manager, and test framework. If end goal or target stack is unknown, leave blocking `open_questions`, keep `controller_policy.unattended_allowed_after_preflight` false, and do not write runner-ready `task-manifest.json` or `clean-run-context.json`.
 
 Keep `preflight-goal.json` in the controller/contaminated artifact domain. Clean roles receive only the clean-safe `goal_contract` subset, `code_hygiene_policy`, and optional Agent 4 local commit policy through `clean-run-context.json`.
 
@@ -32,7 +34,7 @@ Collect only setup decisions that affect correctness, safety, resumability, or o
 - Artifact base root. Default the task root to `~/Documents/CleanRoom/<project>/tasks/<task-id>/`, never to the source workspace or a temporary directory unless the user explicitly chooses it. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
 - Project grouping. Default to a clean-room project with shared `~/Documents/CleanRoom/<project>/implementation/`. When adding a task to an existing destination project, record the user-supplied `project_id` and `project_root`; otherwise generate a neutral `proj-` plus 8 lowercase hex project id. Project names follow the same neutrality rules as task IDs, match `[a-z0-9][a-z0-9-]{0,63}`, and are never derived from source folder names. Record both fields in `init-config.json` and the manifest `initialization_snapshot`. Use the legacy flat `~/Documents/CleanRoom/<task-id>/` layout only when the user explicitly chooses single-task compatibility.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
-- Goal contract choices from `preflight-goal.json`, including target stack, dependency/license policy, exactness policy, feature policy, code hygiene, output policy, and controller mode.
+- Goal contract choices from `preflight-goal.json`, including explicit user-confirmed end goal, target stack, dependency/license policy, exactness policy, feature policy, code hygiene, output policy, controller mode, and `intent_confirmation`.
 - Default model plus optional overrides for contaminated roles, clean roles, or individual roles. Keep model ids as runtime-specific strings.
 - Additional user rules split into `clean_safe` and `contaminated_only`. Put anything containing source paths, private identifiers, private dependency names, or source-derived specifics into `contaminated_only`.
 - Role hook environment values derived from the approved roots: `CLEAN_ROOM_ROLE`, `CLEAN_ROOM_SOURCE_ROOTS`, `CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS`, `CLEAN_ROOM_CLEAN_ROOTS`, `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, `CLEAN_ROOM_ALLOWED_READ_ROOTS`, `CLEAN_ROOM_SCHEMA_DIR`, and optional hook-only denylist paths. The controller must pass these into each role session; do not require the user to set `CLEAN_ROOM_HOOK_ENFORCE` for normal safe-hook runs.

package/skills/preflight/SKILL.md

@@ -25,9 +25,10 @@ Record these decisions:
 - Code hygiene policy: file line caps, max files per iteration, split strategy, exceptions, and forbidden patterns.
 - Output policy: artifact base root, implementation root, assumed output directory, and write mode.
 - Controller policy: attended or unattended, iteration cap, and whether unattended is allowed after preflight.
+- Intent confirmation: `intent_confirmation` with explicit-user-answer sources for end goal, target stack, and controller mode, plus user-facing summaries of the goal and target stack.
 - Open questions, with blocking questions clearly marked.
 
-The artifact must use the canonical `preflight-goal.schema.json` shape. Required top-level keys are `goal_id`, `created_at`, `end_goal`, `target_stack`, `license_policy`, `dependency_policy`, `compatibility_policy`, `feature_policy`, `code_hygiene_policy`, `output_policy`, `controller_policy`, and `open_questions`.
+The artifact must use the canonical `preflight-goal.schema.json` shape. Required top-level keys are `goal_id`, `created_at`, `end_goal`, `target_stack`, `license_policy`, `dependency_policy`, `compatibility_policy`, `feature_policy`, `code_hygiene_policy`, `output_policy`, `controller_policy`, and `open_questions`. Completed preflight inputs and unattended contracts also require `intent_confirmation`.
 
 Reject non-canonical or legacy-shaped preflight artifacts instead of treating them as complete. Do not accept invented fields such as `version`, `created`, `source`, `destination`, `exactness_policy`, `output_policy.artifact_base`, `output_policy.contaminated_root`, `output_policy.clean_root`, or `output_policy.quarantine_root` as substitutes for canonical fields. Report the missing or invalid canonical fields and stop for review.
 
@@ -40,9 +41,10 @@ Unattended runs require a complete `preflight-goal.json` with:
 - `controller_policy.mode: "unattended"`
 - `controller_policy.unattended_allowed_after_preflight: true`
 - finite `controller_policy.max_iterations`
+- `intent_confirmation` showing the end goal, target stack, and controller mode came from explicit user answers
 - empty `open_questions`
 
-Do not infer target language, license, dependency policy, exactness policy, output directory, or feature add/remove policy from source code.
+Do not infer end goal, target language, runtime, framework, package manager, test framework, license, dependency policy, exactness policy, output directory, or feature add/remove policy from source code. If the user's end goal or target stack is unknown, leave blocking `open_questions`, keep unattended disabled, and do not write runner-ready `task-manifest.json` or `clean-run-context.json`.
 
 ## CLI Helper
 

package/skills/resume-cr/SKILL.md

@@ -11,7 +11,7 @@ Resume an existing clean-room run from durable artifacts. Never use prior chat h
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` when the manifest records `loop_context` or unattended mode. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` and let the durable runner assign role agents. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
+If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` only when `loop_context` exists and names approved pending or gap units. If an unattended manifest lacks `loop_context`, treat it as incomplete outer-loop state: finish decomposition or selected-slice approval first, or stop with the missing outer-loop fields instead of launching the runner. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work once runner-ready unattended state exists. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
 
 ## Load Order
 

package/skills/unattended/SKILL.md

@@ -15,11 +15,11 @@ Use the canonical `clean-room` skill workflow and references in this plugin. Rea
 
 Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` (legacy) and `~/Documents/CleanRoom/*/tasks/task-*` (project layout) candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
-When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude`. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
+When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` only after the manifest has `loop_context` with an approved pending or gap unit. If an unattended manifest lacks `loop_context`, treat it as incomplete outer-loop state: finish decomposition or selected-slice approval first, or stop with the missing outer-loop fields instead of launching the runner. If `clean-room-skill` is not on `PATH`, immediately use `npx clean-room-skill@latest run --task-manifest <path> --agent-runtime claude` instead of searching for the installed package. Do not search plugin cache paths for schema files, and do not pass `--schema-dir /dev/null`. The runner uses bundled schemas by default; pass `--schema-dir` only when the user provides a real schema directory. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work once runner-ready unattended state exists. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
 
-Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, and a finite `controller_policy.max_iterations`.
+Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, finite `controller_policy.max_iterations`, and `intent_confirmation` showing the end goal, target stack, and controller mode came from explicit user answers.
 
-Do not assume target language, license policy, dependency policy, exactness policy, output directory, or feature add/remove policy during the unattended loop. Stop on ambiguity instead of inventing product decisions.
+Do not assume end goal, target language, runtime, framework, package manager, test framework, license policy, dependency policy, exactness policy, output directory, or feature add/remove policy during the unattended loop. Source language and build tooling are not destination choices. If the user's end goal or target stack is unknown, leave blocking `open_questions`, keep unattended disabled, and stop on ambiguity instead of inventing product decisions.
 
 Gather only required setup facts:
 
@@ -27,7 +27,7 @@ Gather only required setup facts:
 - Artifact base root, defaulting the task root to `~/Documents/CleanRoom/<project>/tasks/<task-id>/`. If the user does not provide an explicitly approved neutral task ID, generate one as `task-` plus 8 lowercase hex characters. Do not derive task IDs or output directory names from source folder names.
 - Project grouping, following the canonical `clean-room` project layout rules: `<base>/<project>/tasks/<task-id>/` with one shared `<base>/<project>/implementation/` root, a neutral project name (`proj-` plus 8 lowercase hex unless the user supplies an approved neutral name, matching `[a-z0-9][a-z0-9-]{0,63}`, never source-derived), and at most one active task per project. Use legacy flat `<base>/<task-id>/` roots only when the user explicitly chooses single-task compatibility.
 - Source roots, contaminated artifact root, clean artifact root, clean implementation root, quarantine root, and optional public or destination reference roots.
-- Target stack, destination constraints, dependency/license policy, exactness policy, feature policy, code hygiene policy, and output policy from `preflight-goal.json`.
+- Explicit user-confirmed end goal, target stack, destination constraints, dependency/license policy, exactness policy, feature policy, code hygiene policy, and output policy from `preflight-goal.json`.
 - Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
 - Default model plus optional clean, contaminated, or per-role overrides.
 - Finite maximum iteration count for the inner clean-room loop from `preflight-goal.json`.