clean-room-skill 0.1.12 → 0.1.13

package/lib/run-clean-artifacts.cjs

@@ -0,0 +1,276 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  fileHash,
+  readJsonFile,
+} = require('./fs-utils.cjs');
+const {
+  CLEAN_RUN_CONTEXT_NAME,
+  HANDOFF_PACKAGE_NAME,
+} = require('./run-constants.cjs');
+const { runHook } = require('./run-hooks.cjs');
+const { pathIsUnder } = require('./run-roots.cjs');
+
+function readOptionalJson(filePath) {
+  return fs.existsSync(filePath) ? readJsonFile(filePath, null) : null;
+}
+
+function cleanRunContextPath(roots) {
+  return path.join(roots.cleanRoot, CLEAN_RUN_CONTEXT_NAME);
+}
+
+function readCleanRunContext(roots) {
+  const contextPath = cleanRunContextPath(roots);
+  if (!fs.existsSync(contextPath) || !fs.statSync(contextPath).isFile()) {
+    return null;
+  }
+  return readJsonFile(contextPath, null);
+}
+
+function resolveCleanArtifactPath(rawPath, roots, label) {
+  if (typeof rawPath !== 'string' || rawPath.trim() === '') {
+    throw new Error(`${label} must be a non-empty clean artifact path`);
+  }
+  const expanded = rawPath === '~' ? os.homedir() : rawPath.startsWith('~/') ? path.join(os.homedir(), rawPath.slice(2)) : rawPath;
+  const resolved = path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(roots.cleanRoot, expanded);
+  if (!pathIsUnder(resolved, roots.cleanRoot)) {
+    throw new Error(`${label} must resolve under CLEAN_ROOM_CLEAN_ROOTS: ${rawPath}`);
+  }
+  return resolved;
+}
+
+function cleanContextBehaviorSpecPaths(context, roots) {
+  const refs = context?.clean_artifacts?.behavior_specs;
+  if (!Array.isArray(refs)) {
+    return [];
+  }
+  return refs.map((ref, index) => resolveCleanArtifactPath(ref, roots, `clean-run-context behavior_specs[${index}]`));
+}
+
+function cleanContextArtifactPath(context, roots, key, label) {
+  const ref = context?.clean_artifacts?.[key];
+  if (typeof ref !== 'string' || ref.trim() === '') {
+    return null;
+  }
+  return resolveCleanArtifactPath(ref, roots, label);
+}
+
+function cleanCompletionArtifactPath(roots, key, defaultName, label) {
+  const context = readCleanRunContext(roots);
+  const contextPath = context ? cleanContextArtifactPath(context, roots, key, label) : null;
+  return contextPath || path.join(roots.cleanRoot, defaultName);
+}
+
+function readCleanCompletionArtifact(roots, key, defaultName, label) {
+  const artifactPath = cleanCompletionArtifactPath(roots, key, defaultName, label);
+  if (!fs.existsSync(artifactPath) || !fs.statSync(artifactPath).isFile()) {
+    return { artifactPath, artifact: null };
+  }
+  return { artifactPath, artifact: readJsonFile(artifactPath, null) };
+}
+
+function validateReferencedBehaviorSpecs(python, roots, specPaths) {
+  for (const specPath of specPaths) {
+    if (!fs.existsSync(specPath) || !fs.statSync(specPath).isFile()) {
+      throw new Error(`clean-run-context behavior spec does not exist: ${specPath}`);
+    }
+    runHook(python, 'validate-json-schema.py', specPath, roots);
+    runHook(python, 'check-artifact-leakage.py', specPath, roots);
+  }
+}
+
+function normalizeCleanRelativePath(value) {
+  return String(value || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+/g, '/')
+    .replace(/\/$/, '');
+}
+
+function prefixOwnsPath(prefix, relPath) {
+  const owner = normalizeCleanRelativePath(prefix);
+  const target = normalizeCleanRelativePath(relPath);
+  return owner !== '' && (target === owner || target.startsWith(`${owner}/`));
+}
+
+function skeletonAreaMap(skeleton) {
+  const areas = new Map();
+  for (const area of skeleton?.areas || []) {
+    if (area && typeof area.area_id === 'string') {
+      areas.set(area.area_id, area);
+    }
+  }
+  return areas;
+}
+
+function validateSkeletonArchitecture(skeleton) {
+  const areas = skeletonAreaMap(skeleton);
+  for (const area of skeleton?.areas || []) {
+    for (const dependencyRef of area.allowed_area_dependencies || []) {
+      if (dependencyRef === area.area_id) {
+        throw new Error(`skeleton-manifest architecture area must not depend on itself: ${area.area_id}`);
+      }
+      if (!areas.has(dependencyRef)) {
+        throw new Error(`skeleton-manifest architecture area references unknown dependency area: ${dependencyRef}`);
+      }
+    }
+  }
+}
+
+function validateAreaRefs(areaRefs, areas, label) {
+  if (!Array.isArray(areaRefs) || areaRefs.length === 0) {
+    throw new Error(`${label} must reference at least one architecture area`);
+  }
+  for (const areaRef of areaRefs) {
+    if (!areas.has(areaRef)) {
+      throw new Error(`${label} references unknown architecture area: ${areaRef}`);
+    }
+  }
+}
+
+function validatePathsOwnedByAreas(paths, areaRefs, areas, label) {
+  validateAreaRefs(areaRefs, areas, label);
+  const candidateAreas = areaRefs.map((areaRef) => areas.get(areaRef));
+  for (const relPath of paths || []) {
+    const owned = candidateAreas.some((area) => {
+      return (area.owned_path_prefixes || []).some((prefix) => prefixOwnsPath(prefix, relPath));
+    });
+    if (!owned) {
+      throw new Error(`${label} path is outside referenced architecture areas: ${relPath}`);
+    }
+  }
+}
+
+function validateImplementationPlanArchitecture(plan, skeleton, roots, skeletonPath) {
+  const areas = skeletonAreaMap(skeleton);
+  const referencedSkeletonPath = resolveCleanArtifactPath(
+    plan.architecture_manifest_ref,
+    roots,
+    'implementation-plan architecture_manifest_ref'
+  );
+  if (path.resolve(referencedSkeletonPath) !== path.resolve(skeletonPath)) {
+    throw new Error('implementation-plan architecture_manifest_ref must match clean-run-context skeleton_manifest');
+  }
+  for (const workItem of plan.work_items || []) {
+    const label = `implementation-plan work item ${workItem.work_item_id || '<unknown>'}`;
+    validatePathsOwnedByAreas(
+      [...(workItem.target_paths || []), ...(workItem.test_paths || [])],
+      workItem.architecture_area_refs,
+      areas,
+      label
+    );
+  }
+  for (const refactor of plan.planned_refactors || []) {
+    const label = `implementation-plan planned refactor ${refactor.refactor_id || '<unknown>'}`;
+    validatePathsOwnedByAreas(
+      [...(refactor.existing_paths || []), ...(refactor.target_paths || []), ...(refactor.test_paths || [])],
+      refactor.architecture_area_refs,
+      areas,
+      label
+    );
+  }
+}
+
+function handoffArtifactIndex(handoffPath, roots) {
+  const handoff = readJsonFile(handoffPath, null);
+  const index = new Map();
+  for (const item of handoff?.artifacts || []) {
+    if (!item || typeof item !== 'object' || typeof item.path !== 'string') {
+      continue;
+    }
+    const artifactPath = resolveCleanArtifactPath(item.path, roots, 'handoff artifact path');
+    index.set(artifactPath, item);
+  }
+  return index;
+}
+
+function validateHandoffCoversBehaviorSpecs(context, roots, specPaths) {
+  const handoffRef = context?.clean_artifacts?.handoff_package || HANDOFF_PACKAGE_NAME;
+  const handoffPath = resolveCleanArtifactPath(handoffRef, roots, 'clean-run-context handoff_package');
+  if (!fs.existsSync(handoffPath) || !fs.statSync(handoffPath).isFile()) {
+    throw new Error(`clean-run-context handoff package does not exist: ${handoffPath}`);
+  }
+  const artifacts = handoffArtifactIndex(handoffPath, roots);
+  for (const specPath of specPaths) {
+    const item = artifacts.get(specPath);
+    if (!item) {
+      throw new Error(`handoff-package.json does not include clean-run-context behavior spec: ${specPath}`);
+    }
+    const expected = String(item.sha256 || '').toLowerCase();
+    const actual = fileHash(specPath).toLowerCase();
+    if (expected !== actual) {
+      throw new Error(`handoff-package.json sha256 mismatch for behavior spec: ${specPath}`);
+    }
+  }
+}
+
+function validateCleanRunContextReferences(python, roots) {
+  const context = readCleanRunContext(roots);
+  if (!context) {
+    return;
+  }
+  const specPaths = cleanContextBehaviorSpecPaths(context, roots);
+  const skeletonPath = cleanContextArtifactPath(context, roots, 'skeleton_manifest', 'clean-run-context skeleton_manifest');
+  const planPath = cleanContextArtifactPath(context, roots, 'implementation_plan', 'clean-run-context implementation_plan');
+  let skeleton = null;
+  validateReferencedBehaviorSpecs(python, roots, specPaths);
+  if (specPaths.length > 0 || skeletonPath) {
+    if (!skeletonPath || !fs.existsSync(skeletonPath) || !fs.statSync(skeletonPath).isFile()) {
+      throw new Error(`clean-run-context skeleton manifest does not exist: ${skeletonPath || 'missing skeleton_manifest ref'}`);
+    }
+    runHook(python, 'validate-json-schema.py', skeletonPath, roots, 'clean-architect');
+    runHook(python, 'check-artifact-leakage.py', skeletonPath, roots, 'clean-architect');
+    skeleton = readJsonFile(skeletonPath, null);
+    validateSkeletonArchitecture(skeleton);
+  }
+  validateHandoffCoversBehaviorSpecs(context, roots, specPaths);
+  if (planPath && fs.existsSync(planPath) && fs.statSync(planPath).isFile() && skeletonPath) {
+    const plan = readJsonFile(planPath, null);
+    validateImplementationPlanArchitecture(plan, skeleton, roots, skeletonPath);
+  }
+}
+
+function behaviorSpecOpenQuestionTickets(roots) {
+  const context = readCleanRunContext(roots);
+  if (!context) {
+    return [];
+  }
+  const specPaths = cleanContextBehaviorSpecPaths(context, roots);
+  const openSpecCount = specPaths.filter((specPath) => {
+    if (!fs.existsSync(specPath) || !fs.statSync(specPath).isFile()) {
+      return false;
+    }
+    const spec = readJsonFile(specPath, null);
+    return Array.isArray(spec.open_questions) && spec.open_questions.length > 0;
+  }).length;
+  if (openSpecCount === 0) {
+    return [];
+  }
+  return [
+    {
+      ticket_id: 'delta-open-questions',
+      kind: 'ambiguity',
+      summary: `${openSpecCount} approved behavior spec(s) still contain open questions.`,
+      requested_clean_change: 'Resolve or remove approved behavior spec open questions before marking the spec slice complete.',
+      status: 'open',
+    },
+  ];
+}
+
+module.exports = {
+  behaviorSpecOpenQuestionTickets,
+  cleanCompletionArtifactPath,
+  cleanContextArtifactPath,
+  cleanContextBehaviorSpecPaths,
+  readCleanCompletionArtifact,
+  readCleanRunContext,
+  readOptionalJson,
+  resolveCleanArtifactPath,
+  skeletonAreaMap,
+  validateCleanRunContextReferences,
+  validatePathsOwnedByAreas,
+};

package/lib/run-cli.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+function printRunHelp() {
+  console.log(`Usage: clean-room-skill run --task-manifest <path> --agent-commands <path> [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
+  --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
+  --schema-dir <path>      Schema directory override
+  --python <path>          Python executable for bundled validation hooks (default: python3)
+  -h, --help               Show this help
+`);
+}
+
+function parseRunArgs(argv) {
+  const options = {
+    taskManifest: null,
+    agentCommands: null,
+    maxIterations: null,
+    once: false,
+    dryRun: false,
+    schemaDir: null,
+    python: 'python3',
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--once') {
+      options.once = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--task-manifest') {
+      index += 1;
+      options.taskManifest = requiredValue(argv, index, '--task-manifest');
+    } else if (arg.startsWith('--task-manifest=')) {
+      options.taskManifest = arg.slice('--task-manifest='.length);
+    } else if (arg === '--agent-commands') {
+      index += 1;
+      options.agentCommands = requiredValue(argv, index, '--agent-commands');
+    } else if (arg.startsWith('--agent-commands=')) {
+      options.agentCommands = arg.slice('--agent-commands='.length);
+    } else if (arg === '--max-iterations') {
+      index += 1;
+      options.maxIterations = parsePositiveInteger(requiredValue(argv, index, '--max-iterations'), '--max-iterations');
+    } else if (arg.startsWith('--max-iterations=')) {
+      options.maxIterations = parsePositiveInteger(arg.slice('--max-iterations='.length), '--max-iterations');
+    } else if (arg === '--schema-dir') {
+      index += 1;
+      options.schemaDir = requiredValue(argv, index, '--schema-dir');
+    } else if (arg.startsWith('--schema-dir=')) {
+      options.schemaDir = arg.slice('--schema-dir='.length);
+    } else if (arg === '--python') {
+      index += 1;
+      options.python = requiredValue(argv, index, '--python');
+    } else if (arg.startsWith('--python=')) {
+      options.python = arg.slice('--python='.length);
+    } else {
+      throw new Error(`unknown run option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function requiredValue(argv, index, flag) {
+  if (index >= argv.length || argv[index] === '') {
+    throw new Error(`${flag} requires a value`);
+  }
+  return argv[index];
+}
+
+function parsePositiveInteger(value, flag) {
+  if (!/^[1-9][0-9]*$/.test(String(value))) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return Number(value);
+}
+
+module.exports = {
+  parseRunArgs,
+  printRunHelp,
+};

package/lib/run-constants.cjs

@@ -0,0 +1,171 @@
+'use strict';
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_TIMEOUT_MS = 60 * 60 * 1000;
+const MAX_OUTPUT_BYTES = 256 * 1024;
+const RUN_LOCK_NAME = '.clean-room-run.lock';
+const RUN_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_RUN_LOCK_WAIT_MS', 30_000);
+const RUN_LOCK_POLL_MS = 100;
+const RUN_HOOK_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_RUN_HOOK_TIMEOUT_MS', 30_000);
+const LEDGER_NAME = 'controller-run-ledger.json';
+const RESULT_NAME = 'clean-room-result.json';
+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 REQUIRED_COVERAGE_PHASE = 'contaminated-coverage-verify';
+const POLISH_PHASE = 'clean-polish-review';
+const PUBLIC_SURFACE_COMPLETION_LEVELS = new Set(['exact-public-contract', 'behavior-compatible']);
+const MAX_LEDGER_ITERATIONS = 50;
+
+const BASE_ENV_ALLOWLIST = Object.freeze([
+  'PATH',
+  'HOME',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'TMPDIR',
+  'TEMP',
+  'TMP',
+]);
+
+const CI_ENV_ALLOWLIST = Object.freeze([
+  'CI',
+  'CONTINUOUS_INTEGRATION',
+  'BUILD_ID',
+  'BUILD_NUMBER',
+  'RUN_ID',
+  'TEAMCITY_VERSION',
+  'TF_BUILD',
+  'GITHUB_ACTIONS',
+  'GITHUB_ACTOR',
+  'GITHUB_EVENT_NAME',
+  'GITHUB_JOB',
+  'GITHUB_REF',
+  'GITHUB_REF_NAME',
+  'GITHUB_REF_TYPE',
+  'GITHUB_REPOSITORY',
+  'GITHUB_REPOSITORY_OWNER',
+  'GITHUB_RUN_ATTEMPT',
+  'GITHUB_RUN_ID',
+  'GITHUB_RUN_NUMBER',
+  'GITHUB_SHA',
+  'GITHUB_WORKFLOW',
+  'GITLAB_CI',
+  'CI_COMMIT_REF_NAME',
+  'CI_COMMIT_SHA',
+  'CI_JOB_ID',
+  'CI_PIPELINE_ID',
+  'CI_PROJECT_PATH',
+]);
+
+const HOOK_ONLY_ENV_ALLOWLIST = Object.freeze([
+  'CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST',
+  'CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST',
+]);
+
+const ROLE_BY_PHASE = Object.freeze({
+  'contaminated-analysis': 'contaminated-source-analyst',
+  'sanitize-handoff': 'contaminated-handoff-sanitizer',
+  'clean-plan': 'clean-architect',
+  'clean-implement-qc': 'clean-qa-editor',
+  [POLISH_PHASE]: 'clean-polish-reviewer',
+  'contaminated-coverage-verify': 'contaminated-manager-verifier',
+});
+
+const TERMINAL_RESULTS = new Set([
+  'spec-slice-complete',
+  'spec-slice-blocked',
+  'spec-delta-required',
+  'contamination-suspected',
+  'iteration-limit-reached',
+  'no-progress-detected',
+]);
+
+const VOLATILE_PROGRESS_KEYS = new Set([
+  'artifact_hashes',
+  'created_at',
+  'generated_at',
+  'recorded_at',
+  'returned_at',
+  'reviewed_at',
+  'started_at',
+  'updated_at',
+]);
+
+const IMPLEMENTATION_IGNORE_NAMES = Object.freeze([
+  '.git',
+  'node_modules',
+  'target',
+]);
+
+const SOURCE_DENIED_BRIEF_BLOCKED_NAMES = new Set([
+  'source-index.json',
+  'visual-index.json',
+  'coverage-ledger.json',
+  'evidence-ledger.json',
+  'task-manifest.json',
+  'init-config.json',
+  'preflight-goal.json',
+  'controller-status.json',
+]);
+
+const CLEAN_ROOM_ARTIFACT_PREFIXES = Object.freeze([
+  'behavior-spec',
+  'clean-room-result',
+  'clean-run-context',
+  'contamination-incident',
+  'controller-status',
+  'coverage-ledger',
+  'evidence-ledger',
+  'handoff-package',
+  'implementation-plan',
+  'implementation-report',
+  'init-config',
+  'polish-report',
+  'preflight-goal',
+  'qc-report',
+  'role-session-brief',
+  'skeleton-manifest',
+  'source-index',
+  'task-manifest',
+  'visual-index',
+]);
+
+function envPositiveInteger(name, fallback) {
+  const value = process.env[name];
+  if (value === undefined || value === '') {
+    return fallback;
+  }
+  return /^[1-9][0-9]*$/.test(value) ? Number(value) : fallback;
+}
+
+module.exports = {
+  BASE_ENV_ALLOWLIST,
+  CI_ENV_ALLOWLIST,
+  CLEAN_ROOM_ARTIFACT_PREFIXES,
+  CLEAN_RUN_CONTEXT_NAME,
+  DEFAULT_TIMEOUT_MS,
+  HANDOFF_PACKAGE_NAME,
+  HOOK_ONLY_ENV_ALLOWLIST,
+  IMPLEMENTATION_IGNORE_NAMES,
+  LEDGER_NAME,
+  MAX_LEDGER_ITERATIONS,
+  MAX_OUTPUT_BYTES,
+  MAX_TIMEOUT_MS,
+  POLISH_PHASE,
+  POLISH_REPORT_NAME,
+  PUBLIC_SURFACE_COMPLETION_LEVELS,
+  REQUIRED_COVERAGE_PHASE,
+  RESULT_NAME,
+  ROLE_BY_PHASE,
+  RUN_HOOK_TIMEOUT_MS,
+  RUN_LOCK_NAME,
+  RUN_LOCK_POLL_MS,
+  RUN_LOCK_WAIT_MS,
+  SOURCE_DENIED_BRIEF_BLOCKED_NAMES,
+  STATUS_NAME,
+  TERMINAL_RESULTS,
+  VOLATILE_PROGRESS_KEYS,
+  envPositiveInteger,
+};