clean-room-skill 0.1.14 → 0.2.0

package/lib/claude-agents.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { readJsonFile } = require('./fs-utils.cjs');
+
+const CLAUDE_AGENT_FILES = Object.freeze([
+  'clean-architect.md',
+  'clean-implementer-verifier-shell.md',
+  'clean-polish-reviewer.md',
+  'clean-qa-editor.md',
+  'contaminated-handoff-sanitizer.md',
+  'contaminated-manager-verifier.md',
+  'contaminated-source-analyst.md',
+]);
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function localClaudePluginDir() {
+  return packageRoot();
+}
+
+function defaultClaudeConfigDir(env = process.env) {
+  if (env.CLAUDE_CONFIG_DIR) {
+    return path.resolve(expandTilde(env.CLAUDE_CONFIG_DIR));
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+function expandTilde(value) {
+  if (value === '~') return os.homedir();
+  if (typeof value === 'string' && value.startsWith('~/')) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function claudePluginDirFromInstallManifest(configDir) {
+  const manifestPath = path.join(configDir, 'clean-room-install-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  const manifest = readJsonFile(manifestPath, null);
+  const installPath = manifest?.claude_plugin?.install_path;
+  return typeof installPath === 'string' && installPath !== '' ? path.resolve(installPath) : null;
+}
+
+function claudePluginCandidates(configDir, options = {}) {
+  const candidates = [];
+  const add = (label, pluginDir) => {
+    if (typeof pluginDir !== 'string' || pluginDir === '') return;
+    const resolved = path.resolve(pluginDir);
+    if (candidates.some((candidate) => candidate.pluginDir === resolved)) return;
+    candidates.push({ label, pluginDir: resolved });
+  };
+
+  if (options.pluginDir) {
+    add('explicit', options.pluginDir);
+  }
+  if (configDir) {
+    add('installed-plugin', claudePluginDirFromInstallManifest(path.resolve(configDir)));
+  }
+  if (options.includePackageFallback !== false) {
+    add('package-plugin', localClaudePluginDir());
+  }
+  if (configDir) {
+    add('local-claude-agents', path.resolve(configDir));
+  }
+  return candidates;
+}
+
+function claudeAgentStatus(configDir, options = {}) {
+  const candidates = claudePluginCandidates(configDir, options);
+  for (const candidate of candidates) {
+    const agentDir = path.join(candidate.pluginDir, 'agents');
+    const missing = missingClaudeAgentFiles(candidate.pluginDir);
+    if (missing.length === 0) {
+      return {
+        status: 'ok',
+        source: candidate.label,
+        pluginDir: candidate.pluginDir,
+        agentDir,
+        present: CLAUDE_AGENT_FILES.length,
+        missing,
+      };
+    }
+  }
+
+  const preferred = candidates[0] || { label: 'none', pluginDir: configDir ? path.resolve(configDir) : null };
+  const missing = preferred.pluginDir ? missingClaudeAgentFiles(preferred.pluginDir) : [...CLAUDE_AGENT_FILES];
+  return {
+    status: 'missing',
+    source: preferred.label,
+    pluginDir: preferred.pluginDir,
+    agentDir: preferred.pluginDir ? path.join(preferred.pluginDir, 'agents') : null,
+    present: CLAUDE_AGENT_FILES.length - missing.length,
+    missing,
+  };
+}
+
+function missingClaudeAgentFiles(pluginDir) {
+  const agentDir = path.join(pluginDir, 'agents');
+  return CLAUDE_AGENT_FILES.filter((name) => {
+    const filePath = path.join(agentDir, name);
+    try {
+      return !fs.statSync(filePath).isFile();
+    } catch {
+      return true;
+    }
+  });
+}
+
+function assertClaudeAgentsAvailable(configDir, options = {}) {
+  const status = claudeAgentStatus(configDir, options);
+  if (status.status !== 'ok') {
+    const base = status.pluginDir || String(configDir || '<unknown>');
+    throw new Error(`Claude role-agent dispatch unavailable: missing ${status.missing.join(', ')} under ${base}`);
+  }
+  return status;
+}
+
+module.exports = {
+  CLAUDE_AGENT_FILES,
+  assertClaudeAgentsAvailable,
+  claudeAgentStatus,
+  defaultClaudeConfigDir,
+  localClaudePluginDir,
+};

package/lib/doctor.cjs

@@ -6,6 +6,7 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const { readJsonFile } = require('./fs-utils.cjs');
+const { claudeAgentStatus } = require('./claude-agents.cjs');
 const {
   CLEAN_ROOM_HOOKS,
   configPathForRuntime,
@@ -397,6 +398,22 @@ function printOpenCodeCoverage(plugin, hookMode) {
   console.log(`  strict required: ${hookMode === 'strict' ? 'yes' : 'no'}`);
 }
 
+function assertClaudeAgentAvailability(layout) {
+  const status = claudeAgentStatus(layout.targetRoot, { includePackageFallback: false });
+  if (status.status !== 'ok') {
+    const base = status.pluginDir || layout.targetRoot;
+    throw new Error(`Claude role-agent dispatch unavailable: missing ${status.missing.join(', ')} under ${base}`);
+  }
+  return status;
+}
+
+function printClaudeAgentCoverage(status) {
+  console.log('clean-room Claude plugin agent coverage:');
+  console.log(`  ok             agents ${status.present}`);
+  console.log(`  source: ${status.source}`);
+  console.log(`  path: ${status.agentDir}`);
+}
+
 function runOpenCodeDoctor(options, layout) {
   const plugin = assertOpenCodePlugin(layout, options.hookMode);
   const pathEnv = { PATH: process.env.PATH || '' };
@@ -497,6 +514,10 @@ function runDoctor(argv) {
   if (options.coverage) {
     printCoverage(entries, options.hookMode);
   }
+  const claudeAgents = layout.runtime === 'claude' ? assertClaudeAgentAvailability(layout) : null;
+  if (options.coverage && claudeAgents) {
+    printClaudeAgentCoverage(claudeAgents);
+  }
   if (options.hookMode === 'strict') {
     assertStrictCoverage(entries);
   }
@@ -556,8 +577,11 @@ function runDoctor(argv) {
   console.log(`clean-room doctor passed for ${options.runtime}`);
   console.log(`  hooks config: ${configPath}`);
   console.log(`  managed hooks: ${entries.length}`);
+  if (claudeAgents) {
+    console.log(`  plugin agents: ${claudeAgents.present}`);
+  }
   console.log(`  mode: ${options.hookMode}`);
-  return { configPath, managedHooks: entries.length };
+  return { configPath, managedHooks: entries.length, pluginAgents: claudeAgents?.present || 0 };
 }
 
 module.exports = {

package/lib/install-status.cjs

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 
+const { claudeAgentStatus } = require('./claude-agents.cjs');
 const { assertManagedPath, fileHash } = require('./fs-utils.cjs');
 const {
   configPathForRuntime,
@@ -98,6 +99,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     hookRegistration: layout.supportsHookRegistration ? 'none' : 'unsupported',
     updateAvailable: false,
     claudePlugin: null,
+    claudeAgents: null,
     issues: [],
   };
 
@@ -167,11 +169,18 @@ function collectRuntimeStatus(runtime, scope, configDir) {
   if (layout.supportsHookRegistration && hooksMode !== 'copy-only' && hookState !== 'present') {
     issues.push('managed hook registration missing');
   }
+  const claudeAgents = runtime === 'claude'
+    ? claudeAgentStatus(layout.targetRoot, { includePackageFallback: false })
+    : null;
+  if (claudeAgents && claudeAgents.status !== 'ok') {
+    issues.push(`Claude role-agent dispatch unavailable: missing ${claudeAgents.missing.join(', ')}`);
+  }
 
-  const updateAvailable = manifest.version !== packageVersion() ||
+  const updateAvailable = Boolean(manifest.version !== packageVersion() ||
     plan.removals.length > 0 ||
     plan.unknownConflicts.length > 0 ||
-    fileStats.missing > 0;
+    fileStats.missing > 0 ||
+    (claudeAgents && claudeAgents.status !== 'ok'));
 
   return {
     ...base,
@@ -188,6 +197,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     hookRegistration: hookState,
     updateAvailable,
     claudePlugin: manifest.claude_plugin || null,
+    claudeAgents,
     issues,
   };
 }
@@ -243,6 +253,9 @@ function printStatusReport(statuses) {
       if (status.claudePlugin) {
         console.log(`  plugin: ${status.claudePlugin.plugin_id || CLAUDE_PLUGIN_ID}; marketplace ${status.claudePlugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME}`);
       }
+      if (status.claudeAgents) {
+        console.log(`  plugin agents: ${status.claudeAgents.status}; present ${status.claudeAgents.present}; missing ${status.claudeAgents.missing.length}`);
+      }
     } else if (status.hookRegistration === 'present') {
       console.log('  hooks: managed hook registration present without install manifest');
     }

package/lib/run-claude-agent-runtime.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+const path = require('node:path');
+
+const { assertClaudeAgentsAvailable, defaultClaudeConfigDir } = require('./claude-agents.cjs');
+const { resolveClaudeExecutable } = require('./install-claude-plugin.cjs');
+const {
+  MANAGER_PREPARE_PHASE,
+  REQUIRED_COVERAGE_PHASE,
+  ROLE_BY_PHASE,
+} = require('./run-constants.cjs');
+const { resolvePath } = require('./run-roots.cjs');
+
+const CLAUDE_PERMISSION_MODE = 'acceptEdits';
+
+function buildClaudeAgentCommandConfig(options, roots, cwd = process.cwd()) {
+  const agentConfigDir = options.agentConfigDir
+    ? resolvePath(options.agentConfigDir, cwd)
+    : defaultClaudeConfigDir();
+  const agentStatus = assertClaudeAgentsAvailable(agentConfigDir);
+  const { executable, searchPath } = resolveClaudeExecutable();
+  const env = {
+    CLAUDE_CONFIG_DIR: agentConfigDir,
+    PATH: searchPath,
+  };
+  const pluginArgs = agentStatus.source === 'installed-plugin' || agentStatus.source === 'package-plugin'
+    ? ['--plugin-dir', agentStatus.pluginDir]
+    : [];
+
+  return {
+    configDir: agentConfigDir,
+    config: {
+      version: 1,
+      stages: claudeStages(roots, executable, env, pluginArgs),
+    },
+  };
+}
+
+function claudeStages(roots, executable, env, pluginArgs) {
+  const contaminatedCwd = roots.contaminatedRoot;
+  const cleanCwd = roots.cleanRoot;
+  const implementationCwd = roots.implementationRoots[0] || roots.cleanRoot;
+  return [
+    claudeStage(MANAGER_PREPARE_PHASE, contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('contaminated-analysis', contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('sanitize-handoff', contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('clean-plan', cleanCwd, executable, env, pluginArgs),
+    claudeStage('clean-implement-qc', implementationCwd, executable, env, pluginArgs),
+    claudeStage(REQUIRED_COVERAGE_PHASE, contaminatedCwd, executable, env, pluginArgs),
+  ];
+}
+
+function claudeStage(phase, cwd, executable, env, pluginArgs) {
+  const role = ROLE_BY_PHASE[phase];
+  return {
+    phase,
+    role,
+    cwd,
+    argv: [
+      executable,
+      '--print',
+      '--input-format',
+      'text',
+      '--output-format',
+      'text',
+      '--no-session-persistence',
+      '--permission-mode',
+      CLAUDE_PERMISSION_MODE,
+      '--agent',
+      `clean-room:${role}`,
+      ...pluginArgs,
+    ],
+    env,
+  };
+}
+
+module.exports = {
+  buildClaudeAgentCommandConfig,
+};

package/lib/run-cli.cjs

@@ -1,13 +1,18 @@
 'use strict';
 
+const AGENT_RUNTIMES = new Set(['claude']);
+
 function printRunHelp() {
-  console.log(`Usage: clean-room-skill run --task-manifest <path> --agent-commands <path> [options]
+  console.log(`Usage: clean-room-skill run --task-manifest <path> (--agent-commands <path> | --agent-runtime claude) [options]
 
 Run one bounded inner clean-room controller loop for an approved spec slice.
 
 Options:
   --task-manifest <path>   Required task-manifest.json path
-  --agent-commands <path>  Required role command adapter JSON unless --dry-run is set
+  --agent-commands <path>  Role command adapter JSON unless --agent-runtime or --dry-run is set
+  --agent-runtime <name>   Built-in role agent runtime; currently supports claude
+  --agent-config-dir <path>
+                           Runtime config dir for --agent-runtime claude
   --max-iterations <n>     Lower the manifest/loop iteration cap
   --once                   Run at most one inner iteration
   --dry-run                Validate and print the selected unit without writing or spawning agents
@@ -21,6 +26,8 @@ function parseRunArgs(argv) {
   const options = {
     taskManifest: null,
     agentCommands: null,
+    agentRuntime: null,
+    agentConfigDir: null,
     maxIterations: null,
     once: false,
     dryRun: false,
@@ -47,6 +54,16 @@ function parseRunArgs(argv) {
       options.agentCommands = requiredValue(argv, index, '--agent-commands');
     } else if (arg.startsWith('--agent-commands=')) {
       options.agentCommands = arg.slice('--agent-commands='.length);
+    } else if (arg === '--agent-runtime') {
+      index += 1;
+      options.agentRuntime = parseAgentRuntime(requiredValue(argv, index, '--agent-runtime'));
+    } else if (arg.startsWith('--agent-runtime=')) {
+      options.agentRuntime = parseAgentRuntime(arg.slice('--agent-runtime='.length));
+    } else if (arg === '--agent-config-dir') {
+      index += 1;
+      options.agentConfigDir = requiredValue(argv, index, '--agent-config-dir');
+    } else if (arg.startsWith('--agent-config-dir=')) {
+      options.agentConfigDir = arg.slice('--agent-config-dir='.length);
     } else if (arg === '--max-iterations') {
       index += 1;
       options.maxIterations = parsePositiveInteger(requiredValue(argv, index, '--max-iterations'), '--max-iterations');
@@ -70,6 +87,13 @@ function parseRunArgs(argv) {
   return options;
 }
 
+function parseAgentRuntime(value) {
+  if (!AGENT_RUNTIMES.has(value)) {
+    throw new Error('--agent-runtime must be claude');
+  }
+  return value;
+}
+
 function requiredValue(argv, index, flag) {
   if (index >= argv.length || argv[index] === '') {
     throw new Error(`${flag} requires a value`);
@@ -85,6 +109,7 @@ function parsePositiveInteger(value, flag) {
 }
 
 module.exports = {
+  AGENT_RUNTIMES,
   parseRunArgs,
   printRunHelp,
 };

package/lib/run-constants.cjs

@@ -13,6 +13,7 @@ const STATUS_NAME = 'controller-status.json';
 const CLEAN_RUN_CONTEXT_NAME = 'clean-run-context.json';
 const HANDOFF_PACKAGE_NAME = 'handoff-package.json';
 const POLISH_REPORT_NAME = 'polish-report.json';
+const MANAGER_PREPARE_PHASE = 'contaminated-manager-prepare';
 const REQUIRED_COVERAGE_PHASE = 'contaminated-coverage-verify';
 const POLISH_PHASE = 'clean-polish-review';
 const PUBLIC_SURFACE_COMPLETION_LEVELS = new Set(['exact-public-contract', 'behavior-compatible']);
@@ -65,6 +66,7 @@ const HOOK_ONLY_ENV_ALLOWLIST = Object.freeze([
 ]);
 
 const ROLE_BY_PHASE = Object.freeze({
+  [MANAGER_PREPARE_PHASE]: 'contaminated-manager-verifier',
   'contaminated-analysis': 'contaminated-source-analyst',
   'sanitize-handoff': 'contaminated-handoff-sanitizer',
   'clean-plan': 'clean-architect',
@@ -153,6 +155,7 @@ module.exports = {
   MAX_LEDGER_ITERATIONS,
   MAX_OUTPUT_BYTES,
   MAX_TIMEOUT_MS,
+  MANAGER_PREPARE_PHASE,
   POLISH_PHASE,
   POLISH_REPORT_NAME,
   PUBLIC_SURFACE_COMPLETION_LEVELS,

package/lib/run-controller.cjs

@@ -24,6 +24,7 @@ const {
   validateArtifacts,
   validateTaskManifestSchema,
 } = require('./run-hooks.cjs');
+const { buildClaudeAgentCommandConfig } = require('./run-claude-agent-runtime.cjs');
 const {
   effectiveIterationCap,
   validateTaskManifestForRun,
@@ -70,6 +71,70 @@ function repeatedUnitSelection(previous, selectedUnit) {
   return previous?.unit_id === selectedUnit.unit_id && previous?.stop_reason === 'no-progress-detected';
 }
 
+function validateRunState(options, taskManifestPath, roots, manifest, coverageLedgerPath) {
+  validateImplementationArtifactPlacement(roots);
+  validateArtifacts(options.python, taskManifestPath, roots);
+  validateCleanRunContextReferences(options.python, roots);
+  const coverageLedger = readOptionalJson(coverageLedgerPath);
+  validateCoverageLedgerIntegrity(manifest, roots, coverageLedger);
+  validateFoundationCoverageGate(manifest, coverageLedger);
+  return coverageLedger;
+}
+
+function rootListEqual(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function assertStableRunRoots(initialRoots, currentRoots) {
+  if (
+    !rootListEqual(initialRoots.sourceRoots, currentRoots.sourceRoots) ||
+    initialRoots.contaminatedRoot !== currentRoots.contaminatedRoot ||
+    initialRoots.cleanRoot !== currentRoots.cleanRoot ||
+    !rootListEqual(initialRoots.implementationRoots, currentRoots.implementationRoots) ||
+    !rootListEqual(initialRoots.allowedReadRoots, currentRoots.allowedReadRoots) ||
+    initialRoots.schemaDir !== currentRoots.schemaDir
+  ) {
+    throw new Error('task manifest root drift detected during unattended run');
+  }
+}
+
+function reloadManifestForIteration(options, taskManifestPath, manifestDir, roots, schemaDir) {
+  validateTaskManifestSchema(options.python, taskManifestPath, schemaDir);
+  const currentManifest = readJsonFile(taskManifestPath, null);
+  validateTaskManifestForRun(currentManifest);
+  const currentRoots = resolveRoots(currentManifest, manifestDir, schemaDir);
+  assertStableRunRoots(roots, currentRoots);
+  validateTaskManifestLocation(taskManifestPath, currentRoots);
+  verifyPreflightGoal(currentManifest, manifestDir, currentRoots);
+  return currentManifest;
+}
+
+function resolveAgentConfig(options, context, roots, manifest, agentConfigPath) {
+  if (options.agentCommands && options.agentRuntime) {
+    throw new Error('--agent-runtime cannot be used with --agent-commands');
+  }
+  if (!options.agentCommands && !options.agentRuntime) {
+    return { agentConfig: null, configDir: process.cwd() };
+  }
+  if (options.agentRuntime === 'claude') {
+    const builtIn = buildClaudeAgentCommandConfig(options, roots, context.cwd || process.cwd());
+    validateCommandConfig(builtIn.config, {
+      roots,
+      configDir: builtIn.configDir,
+      contextManagement: manifest.context_management,
+    });
+    return { agentConfig: builtIn.config, configDir: builtIn.configDir };
+  }
+  const agentConfig = readJsonFile(agentConfigPath, null);
+  const configDir = path.dirname(agentConfigPath);
+  validateCommandConfig(agentConfig, { roots, configDir, contextManagement: manifest.context_management });
+  return { agentConfig, configDir };
+}
+
+function shouldContinueAfterUnitComplete(manifest, coverageLedger) {
+  return Boolean(selectUnit(manifest, coverageLedger));
+}
+
 async function runCleanRoom(options, context = {}) {
   if (options.help) {
     printRunHelp();
@@ -78,8 +143,11 @@ async function runCleanRoom(options, context = {}) {
   if (!options.taskManifest) {
     throw new Error('--task-manifest is required');
   }
-  if (!options.dryRun && !options.agentCommands) {
-    throw new Error('--agent-commands is required unless --dry-run is set');
+  if (!options.dryRun && !options.agentCommands && !options.agentRuntime) {
+    throw new Error('--agent-commands or --agent-runtime is required unless --dry-run is set');
+  }
+  if (options.agentCommands && options.agentRuntime) {
+    throw new Error('--agent-runtime cannot be used with --agent-commands');
   }
 
   const taskManifestPath = resolvePath(options.taskManifest, context.cwd || process.cwd());
@@ -96,20 +164,13 @@ async function runCleanRoom(options, context = {}) {
   verifyPreflightGoal(manifest, manifestDir, roots);
   const cap = effectiveIterationCap(manifest, options);
   const agentConfigPath = options.agentCommands ? resolvePath(options.agentCommands, context.cwd || process.cwd()) : null;
-  const agentConfig = agentConfigPath ? readJsonFile(agentConfigPath, null) : null;
-  const configDir = agentConfigPath ? path.dirname(agentConfigPath) : process.cwd();
-  if (agentConfig) {
-    validateCommandConfig(agentConfig, { roots, configDir, contextManagement: manifest.context_management });
-  }
+  const { agentConfig, configDir } = options.dryRun
+    ? { agentConfig: null, configDir: process.cwd() }
+    : resolveAgentConfig(options, context, roots, manifest, agentConfigPath);
 
   return withRunLock(roots.contaminatedRoot, options.dryRun, async () => {
     const coverageLedgerPath = path.join(roots.contaminatedRoot, 'coverage-ledger.json');
-    validateImplementationArtifactPlacement(roots);
-    validateArtifacts(options.python, taskManifestPath, roots);
-    validateCleanRunContextReferences(options.python, roots);
-    const coverageLedger = readOptionalJson(coverageLedgerPath);
-    validateCoverageLedgerIntegrity(manifest, roots, coverageLedger);
-    validateFoundationCoverageGate(manifest, coverageLedger);
+    const coverageLedger = validateRunState(options, taskManifestPath, roots, manifest, coverageLedgerPath);
     const selectedUnit = selectUnit(manifest, coverageLedger);
     if (!selectedUnit) {
       const result = completeResultOrSpecDelta(manifest, roots, coverageLedger);
@@ -121,28 +182,6 @@ async function runCleanRoom(options, context = {}) {
     const ledgerPath = path.join(roots.contaminatedRoot, LEDGER_NAME);
     const resultPath = path.join(roots.contaminatedRoot, RESULT_NAME);
     const ledger = loadLedger(ledgerPath, manifest);
-    const previous = previousIteration(ledger);
-    if (repeatedUnitSelection(previous, selectedUnit)) {
-      const result = buildResult(manifest, 'no-progress-detected', 'partial', null, null, [
-        {
-          kind: 'other',
-          summary: 'The same unit was selected again after a no-progress iteration.',
-          status: 'open',
-        },
-      ]);
-      if (!options.dryRun) {
-        writeResult(resultPath, result);
-        ledger.iterations.push({
-          iteration: ledger.iterations.length + 1,
-          unit_id: selectedUnit.unit_id,
-          stop_reason: 'repeated-unit-selection',
-          phases: [],
-        });
-        writeLedger(ledgerPath, ledger);
-      }
-      console.log('clean-room run: repeated-unit-selection');
-      return result;
-    }
 
     if (options.dryRun) {
       console.log(`clean-room run dry-run: selected ${selectedUnit.unit_id}`);
@@ -156,10 +195,39 @@ async function runCleanRoom(options, context = {}) {
     }
 
     let terminalResult = null;
+    let resultManifest = manifest;
     const polishRequired = agentConfig.stages.some((stage) => stage.phase === POLISH_PHASE);
-    const strictContext = strictContextManagement(manifest.context_management);
     for (let offset = 0; offset < cap; offset += 1) {
-      const iteration = (manifest.loop_context.inner_iteration || 0) + offset + 1;
+      const currentManifest = reloadManifestForIteration(options, taskManifestPath, manifestDir, roots, schemaDir);
+      resultManifest = currentManifest;
+      const strictContext = strictContextManagement(currentManifest.context_management);
+      const currentCoverageLedger = validateRunState(options, taskManifestPath, roots, currentManifest, coverageLedgerPath);
+      const selected = selectUnit(currentManifest, currentCoverageLedger);
+      if (!selected) {
+        terminalResult = completeResultOrSpecDelta(currentManifest, roots, currentCoverageLedger);
+        break;
+      }
+      const previous = previousIteration(ledger);
+      if (repeatedUnitSelection(previous, selected)) {
+        terminalResult = buildResult(currentManifest, 'no-progress-detected', 'partial', null, null, [
+          {
+            kind: 'other',
+            summary: 'The same unit was selected again after a no-progress iteration.',
+            status: 'open',
+          },
+        ]);
+        ledger.iterations.push({
+          iteration: ledger.iterations.length + 1,
+          unit_id: selected.unit_id,
+          stop_reason: 'repeated-unit-selection',
+          phases: [],
+        });
+        writeLedger(ledgerPath, ledger);
+        console.log('clean-room run: repeated-unit-selection');
+        break;
+      }
+
+      const iteration = (currentManifest.loop_context.inner_iteration || 0) + offset + 1;
       const before = semanticProgressSnapshot(taskManifestPath, roots);
       const phaseResults = [];
       let coveragePhaseRan = false;
@@ -172,19 +240,19 @@ async function runCleanRoom(options, context = {}) {
           stage,
           configDir,
           roots,
-          manifest,
-          selectedUnit,
+          currentManifest,
+          selected,
           strictContext
         );
-        const stageResult = runStage(stage, configDir, roots, manifest, selectedUnit, iteration, sessionContext);
+        const stageResult = runStage(stage, configDir, roots, currentManifest, selected, iteration, sessionContext);
         const afterStage = artifactSnapshot(taskManifestPath, roots);
         phaseResults.push(stageResult);
         validateImplementationArtifactPlacement(roots);
         validateArtifacts(options.python, taskManifestPath, roots, changedSnapshotPaths(beforeStage, afterStage));
         validateCleanRunContextReferences(options.python, roots);
         const stageCoverageLedger = readOptionalJson(coverageLedgerPath);
-        validateCoverageLedgerIntegrity(manifest, roots, stageCoverageLedger);
-        validateFoundationCoverageGate(manifest, stageCoverageLedger);
+        validateCoverageLedgerIntegrity(currentManifest, roots, stageCoverageLedger);
+        validateFoundationCoverageGate(currentManifest, stageCoverageLedger);
         if (stage.phase === REQUIRED_COVERAGE_PHASE && stageResult.status === 'passed') {
           coveragePhaseRan = true;
         }
@@ -198,25 +266,37 @@ async function runCleanRoom(options, context = {}) {
       const progressDetected = !snapshotsEqual(before, after);
       const ledgerEntry = {
         iteration,
-        unit_id: selectedUnit.unit_id,
-        spec_slice_ref: manifest.loop_context.spec_slice_ref,
+        unit_id: selected.unit_id,
+        spec_slice_ref: currentManifest.loop_context.spec_slice_ref,
         phases: phaseResults,
         progress_detected: progressDetected,
       };
 
       if (failedStage) {
-        terminalResult = stageFailureResult(manifest, failedStage);
+        terminalResult = stageFailureResult(currentManifest, failedStage);
         ledgerEntry.stop_reason = 'spec-slice-blocked';
       } else if (!progressDetected) {
-        terminalResult = noProgressResult(manifest);
+        terminalResult = noProgressResult(currentManifest);
         ledgerEntry.stop_reason = 'no-progress-detected';
       } else if (coveragePhaseRan) {
-        terminalResult = inferTerminalResult(manifest, roots, selectedUnit, {
+        terminalResult = inferTerminalResult(currentManifest, roots, selected, {
           polishRequired,
           observedChangedPaths: changedImplementationPaths(before, after),
         });
         if (terminalResult) {
-          ledgerEntry.stop_reason = terminalResult.result;
+          if (terminalResult.result === 'spec-slice-complete') {
+            const latestCoverageLedger = readOptionalJson(coverageLedgerPath);
+            validateCoverageLedgerIntegrity(currentManifest, roots, latestCoverageLedger);
+            validateFoundationCoverageGate(currentManifest, latestCoverageLedger);
+            if (shouldContinueAfterUnitComplete(currentManifest, latestCoverageLedger)) {
+              ledgerEntry.stop_reason = 'unit-complete';
+              terminalResult = null;
+            } else {
+              ledgerEntry.stop_reason = terminalResult.result;
+            }
+          } else {
+            ledgerEntry.stop_reason = terminalResult.result;
+          }
         }
       }
 
@@ -228,15 +308,15 @@ async function runCleanRoom(options, context = {}) {
     }
 
     if (!terminalResult) {
-      terminalResult = iterationLimitResult(manifest);
+      terminalResult = iterationLimitResult(resultManifest);
     }
     writeResult(resultPath, terminalResult);
     validateImplementationArtifactPlacement(roots);
     validateArtifacts(options.python, taskManifestPath, roots);
     validateCleanRunContextReferences(options.python, roots);
     const finalCoverageLedger = readOptionalJson(coverageLedgerPath);
-    validateCoverageLedgerIntegrity(manifest, roots, finalCoverageLedger);
-    validateFoundationCoverageGate(manifest, finalCoverageLedger);
+    validateCoverageLedgerIntegrity(resultManifest, roots, finalCoverageLedger);
+    validateFoundationCoverageGate(resultManifest, finalCoverageLedger);
     console.log(`clean-room run: ${terminalResult.result}`);
     return terminalResult;
   });