switchman-dev 0.1.1 → 0.1.3

package/src/core/git.js

@@ -4,8 +4,17 @@
  */
 
 import { execSync, spawnSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, realpathSync } from 'fs';
 import { join, relative, resolve, basename } from 'path';
+import { filterIgnoredPaths } from './ignore.js';
+
+function normalizeFsPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
 
 /**
  * Find the switchman database root from cwd or a given path.
@@ -55,12 +64,26 @@ export function findRepoRoot(startPath = process.cwd()) {
   }
 }
 
+export function getGitCommonDir(startPath = process.cwd()) {
+  try {
+    const commonDir = execSync('git rev-parse --git-common-dir', {
+      cwd: startPath,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return resolve(startPath, commonDir);
+  } catch {
+    throw new Error('Not inside a git repository. Run switchman from inside a git repo.');
+  }
+}
+
 /**
  * List all git worktrees for this repo
  * Returns: [{ name, path, branch, isMain, HEAD }]
  */
 export function listGitWorktrees(repoRoot) {
   try {
+    const normalizedRepoRoot = normalizeFsPath(repoRoot);
     const output = execSync('git worktree list --porcelain', {
       cwd: repoRoot,
       encoding: 'utf8',
@@ -83,8 +106,9 @@ export function listGitWorktrees(repoRoot) {
       }
 
       if (wt.path) {
-        wt.name = wt.path === repoRoot ? 'main' : wt.path.split('/').pop();
-        wt.isMain = wt.path === repoRoot;
+        const normalizedPath = normalizeFsPath(wt.path);
+        wt.name = normalizedPath === normalizedRepoRoot ? 'main' : wt.path.split('/').pop();
+        wt.isMain = normalizedPath === normalizedRepoRoot;
         worktrees.push(wt);
       }
     }
@@ -95,6 +119,12 @@ export function listGitWorktrees(repoRoot) {
   }
 }
 
+export function getCurrentWorktree(repoRoot, startPath = process.cwd()) {
+  const currentPath = normalizeFsPath(startPath);
+  const worktrees = listGitWorktrees(repoRoot);
+  return worktrees.find((wt) => normalizeFsPath(wt.path) === currentPath) || null;
+}
+
 /**
  * Get files changed in a worktree relative to its base branch
  * Returns array of file paths (relative to repo root)
@@ -114,12 +144,19 @@ export function getWorktreeChangedFiles(worktreePath, repoRoot) {
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
 
+    const untracked = execSync('git ls-files --others --exclude-standard', {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
     const allFiles = [
       ...staged.split('\n'),
       ...unstaged.split('\n'),
+      ...untracked.split('\n'),
     ].filter(Boolean);
 
-    return [...new Set(allFiles)];
+    return filterIgnoredPaths([...new Set(allFiles)]);
   } catch {
     return [];
   }
@@ -262,4 +299,4 @@ export function getWorktreeStats(worktreePath) {
   } catch {
     return { modified: 0, added: 0, deleted: 0, total: 0, raw: '' };
   }
-}
+}

package/src/core/ignore.js

@@ -0,0 +1,47 @@
+export const DEFAULT_SCAN_IGNORE_PATTERNS = [
+  'node_modules/**',
+  '.git/**',
+  '.switchman/**',
+  'dist/**',
+  'build/**',
+  'coverage/**',
+  '.next/**',
+  '.nuxt/**',
+  '.svelte-kit/**',
+  '.turbo/**',
+  '.cache/**',
+  '.parcel-cache/**',
+  'target/**',
+  'out/**',
+  'tmp/**',
+  'temp/**',
+];
+
+function normalizePath(filePath) {
+  return String(filePath || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\/+/, '')
+    .replace(/^\/+/, '');
+}
+
+function patternPrefix(pattern) {
+  return normalizePath(pattern).replace(/\/\*\*$/, '');
+}
+
+export function matchesPathPatterns(filePath, patterns = DEFAULT_SCAN_IGNORE_PATTERNS) {
+  const normalized = normalizePath(filePath);
+  if (!normalized) return false;
+
+  return patterns.some((pattern) => {
+    const prefix = patternPrefix(pattern);
+    return normalized === prefix || normalized.startsWith(`${prefix}/`) || normalized.includes(`/${prefix}/`);
+  });
+}
+
+export function isIgnoredPath(filePath, patterns = DEFAULT_SCAN_IGNORE_PATTERNS) {
+  return matchesPathPatterns(filePath, patterns);
+}
+
+export function filterIgnoredPaths(filePaths, patterns = DEFAULT_SCAN_IGNORE_PATTERNS) {
+  return filePaths.filter((filePath) => !isIgnoredPath(filePath, patterns));
+}

package/src/core/mcp.js

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export function getSwitchmanMcpConfig() {
+  return {
+    mcpServers: {
+      switchman: {
+        command: 'switchman-mcp',
+        args: [],
+      },
+    },
+  };
+}
+
+export function upsertProjectMcpConfig(targetDir) {
+  const configPath = join(targetDir, '.mcp.json');
+  let config = {};
+  let created = true;
+
+  if (existsSync(configPath)) {
+    created = false;
+    const raw = readFileSync(configPath, 'utf8').trim();
+    config = raw ? JSON.parse(raw) : {};
+  }
+
+  const nextConfig = {
+    ...config,
+    mcpServers: {
+      ...(config.mcpServers || {}),
+      ...getSwitchmanMcpConfig().mcpServers,
+    },
+  };
+
+  const before = JSON.stringify(config);
+  const after = JSON.stringify(nextConfig);
+  const changed = before !== after;
+
+  if (changed) {
+    writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`);
+  }
+
+  return {
+    path: configPath,
+    created,
+    changed,
+  };
+}

package/src/core/merge-gate.js

@@ -0,0 +1,305 @@
+import { getTask, listBoundaryValidationStates, listDependencyInvalidations, logAuditEvent } from './db.js';
+import { scanAllWorktrees } from './detector.js';
+
+const RISK_PATTERNS = [
+  { key: 'auth', regex: /(^|\/)(auth|login|session|permissions?|rbac|acl)(\/|$)/i, label: 'authentication or permissions' },
+  { key: 'schema', regex: /(^|\/)(schema|migrations?|db|database|sql)(\/|$)|schema\./i, label: 'schema or database' },
+  { key: 'config', regex: /(^|\/)(config|configs|settings)(\/|$)|(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock|tsconfig.*|vite\.config.*|webpack\.config.*|dockerfile|docker-compose.*)$/i, label: 'shared configuration' },
+  { key: 'api', regex: /(^|\/)(api|routes?|controllers?)(\/|$)/i, label: 'API surface' },
+];
+
+function isTestPath(filePath) {
+  return /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(filePath);
+}
+
+function isSourcePath(filePath) {
+  return /(^|\/)(src|app|lib|server|client)(\/|$)/i.test(filePath) && !isTestPath(filePath);
+}
+
+function classifyRiskTags(filePath) {
+  return RISK_PATTERNS.filter((pattern) => pattern.regex.test(filePath)).map((pattern) => pattern.key);
+}
+
+function describeRiskTag(tag) {
+  return RISK_PATTERNS.find((pattern) => pattern.key === tag)?.label || tag;
+}
+
+function pathAreas(filePath) {
+  const parts = filePath.split('/').filter(Boolean);
+  if (parts.length === 0) return [];
+  if (parts.length === 1) return [parts[0]];
+  if (['src', 'app', 'lib', 'tests', 'test', 'spec'].includes(parts[0])) {
+    return [`${parts[0]}/${parts[1]}`];
+  }
+  return [parts[0]];
+}
+
+function intersection(a, b) {
+  const setB = new Set(b);
+  return [...new Set(a)].filter((item) => setB.has(item));
+}
+
+function summarizeWorktree(worktree, changedFiles, complianceState) {
+  const sourceFiles = changedFiles.filter(isSourcePath);
+  const testFiles = changedFiles.filter(isTestPath);
+  const riskTags = [...new Set(changedFiles.flatMap(classifyRiskTags))];
+  const areas = [...new Set(changedFiles.flatMap(pathAreas))];
+  const findings = [];
+  let score = 0;
+
+  if (sourceFiles.length > 0 && testFiles.length === 0) {
+    findings.push('source changes without corresponding test updates');
+    score += 15;
+  }
+
+  if (riskTags.length > 0) {
+    findings.push(`touches ${riskTags.map(describeRiskTag).join(', ')}`);
+    score += Math.min(25, riskTags.length * 10);
+  }
+
+  if (complianceState === 'non_compliant' || complianceState === 'stale') {
+    findings.push(`worktree is ${complianceState}`);
+    score += 60;
+  }
+
+  return {
+    worktree: worktree.name,
+    branch: worktree.branch ?? 'unknown',
+    changed_files: changedFiles,
+    source_files: sourceFiles,
+    test_files: testFiles,
+    risk_tags: riskTags,
+    areas,
+    findings,
+    score,
+  };
+}
+
+function buildPairAnalysis(left, right, report) {
+  const directFileConflict = report.fileConflicts.filter((conflict) =>
+    conflict.worktrees.includes(left.worktree) && conflict.worktrees.includes(right.worktree),
+  );
+  const branchConflict = report.conflicts.find((conflict) =>
+    (conflict.worktreeA === left.worktree && conflict.worktreeB === right.worktree)
+    || (conflict.worktreeA === right.worktree && conflict.worktreeB === left.worktree),
+  ) || null;
+  const ownershipConflicts = (report.ownershipConflicts || []).filter((conflict) =>
+    (conflict.worktreeA === left.worktree && conflict.worktreeB === right.worktree)
+    || (conflict.worktreeA === right.worktree && conflict.worktreeB === left.worktree),
+  );
+  const semanticConflicts = (report.semanticConflicts || []).filter((conflict) =>
+    (conflict.worktreeA === left.worktree && conflict.worktreeB === right.worktree)
+    || (conflict.worktreeA === right.worktree && conflict.worktreeB === left.worktree),
+  );
+  const sharedAreas = intersection(left.areas, right.areas);
+  const sharedRiskTags = intersection(left.risk_tags, right.risk_tags);
+
+  const reasons = [];
+  let score = 0;
+
+  if (branchConflict) {
+    reasons.push(`git merge conflict predicted between ${left.branch} and ${right.branch}`);
+    score = 100;
+  }
+
+  if (directFileConflict.length > 0) {
+    reasons.push(`direct file overlap in ${directFileConflict.map((item) => item.file).join(', ')}`);
+    score = Math.max(score, 95);
+  }
+
+  if (ownershipConflicts.length > 0) {
+    for (const conflict of ownershipConflicts) {
+      if (conflict.type === 'subsystem_overlap') {
+        reasons.push(`both worktrees reserve the ${conflict.subsystemTag} subsystem`);
+        score = Math.max(score, 85);
+      } else if (conflict.type === 'scope_overlap') {
+        reasons.push(`both worktrees reserve overlapping scopes (${conflict.scopeA} vs ${conflict.scopeB})`);
+        score = Math.max(score, 90);
+      }
+    }
+  }
+
+  if (semanticConflicts.length > 0) {
+    for (const conflict of semanticConflicts) {
+      if (conflict.type === 'semantic_object_overlap') {
+        reasons.push(`both worktrees changed exported ${conflict.object_kind} ${conflict.object_name}`);
+        score = Math.max(score, 92);
+      } else if (conflict.type === 'semantic_name_overlap') {
+        reasons.push(`both worktrees changed semantically similar object ${conflict.object_name}`);
+        score = Math.max(score, 65);
+      }
+    }
+  }
+
+  if (sharedAreas.length > 0) {
+    reasons.push(`both worktrees touch ${sharedAreas.join(', ')}`);
+    score += 35;
+  }
+
+  if (sharedRiskTags.length > 0) {
+    reasons.push(`both worktrees change ${sharedRiskTags.map(describeRiskTag).join(', ')}`);
+    score += 25;
+  }
+
+  if (left.source_files.length > 0 && left.test_files.length === 0 && sharedAreas.length > 0) {
+    reasons.push(`${left.worktree} changes shared source areas without tests`);
+    score += 10;
+  }
+
+  if (right.source_files.length > 0 && right.test_files.length === 0 && sharedAreas.length > 0) {
+    reasons.push(`${right.worktree} changes shared source areas without tests`);
+    score += 10;
+  }
+
+  if (left.changed_files.length >= 5 && right.changed_files.length >= 5) {
+    reasons.push('both worktrees are large enough to raise integration risk');
+    score += 10;
+  }
+
+  const status = score >= 80 ? 'blocked' : score >= 40 ? 'warn' : 'pass';
+
+  return {
+    worktree_a: left.worktree,
+    worktree_b: right.worktree,
+    branch_a: left.branch,
+    branch_b: right.branch,
+    status,
+    score: Math.min(score, 100),
+    reasons,
+    shared_areas: sharedAreas,
+    shared_risk_tags: sharedRiskTags,
+    ownership_conflicts: ownershipConflicts,
+    semantic_conflicts: semanticConflicts,
+    conflicting_files: branchConflict?.conflictingFiles || directFileConflict.map((item) => item.file),
+  };
+}
+
+function summarizeOverall(pairAnalyses, worktreeAnalyses, boundaryValidations, dependencyInvalidations) {
+  const blockedPairs = pairAnalyses.filter((item) => item.status === 'blocked');
+  const warnedPairs = pairAnalyses.filter((item) => item.status === 'warn');
+  const riskyWorktrees = worktreeAnalyses.filter((item) => item.score >= 40);
+  const blockedValidations = boundaryValidations.filter((item) => item.severity === 'blocked');
+  const warnedValidations = boundaryValidations.filter((item) => item.severity === 'warn');
+  const blockedInvalidations = dependencyInvalidations.filter((item) => item.severity === 'blocked');
+  const warnedInvalidations = dependencyInvalidations.filter((item) => item.severity === 'warn');
+
+  if (blockedPairs.length > 0 || blockedValidations.length > 0 || blockedInvalidations.length > 0) {
+    return {
+      status: 'blocked',
+      summary: `AI merge gate blocked: ${blockedPairs.length} risky pair(s), ${blockedValidations.length} boundary validation issue(s), and ${blockedInvalidations.length} stale dependency issue(s) need resolution.`,
+    };
+  }
+  if (warnedPairs.length > 0 || riskyWorktrees.length > 0 || warnedValidations.length > 0 || warnedInvalidations.length > 0) {
+    return {
+      status: 'warn',
+      summary: `AI merge gate warns: ${warnedPairs.length} pair(s), ${riskyWorktrees.length} worktree(s), ${warnedValidations.length} boundary validation issue(s), or ${warnedInvalidations.length} stale dependency issue(s) need review.`,
+    };
+  }
+  return {
+    status: 'pass',
+    summary: 'AI merge gate passed: no elevated semantic merge risks detected.',
+  };
+}
+
+function evaluateBoundaryValidations(db) {
+  return listBoundaryValidationStates(db)
+    .filter((state) => state.status === 'blocked' || state.status === 'pending_validation')
+    .map((state) => {
+      const task = getTask(db, state.task_id);
+      return {
+        pipeline_id: state.pipeline_id,
+        task_id: state.task_id,
+        worktree: task?.worktree || null,
+        severity: state.status === 'blocked' ? 'blocked' : 'warn',
+        missing_task_types: state.missing_task_types || [],
+        rationale: state.details?.rationale || [],
+        subsystem_tags: state.details?.subsystem_tags || [],
+        summary: `${task?.title || state.task_id} is missing completed ${(state.missing_task_types || []).join(', ')} validation work`,
+        touched_at: state.touched_at,
+        validation_status: state.status,
+      };
+    });
+}
+
+function evaluateDependencyInvalidations(db) {
+  return listDependencyInvalidations(db, { status: 'stale' })
+    .map((state) => {
+      const affectedTask = getTask(db, state.affected_task_id);
+      const severity = affectedTask?.status === 'done' ? 'blocked' : 'warn';
+      const staleArea = state.reason_type === 'subsystem_overlap'
+        ? `subsystem:${state.subsystem_tag}`
+        : `${state.source_scope_pattern} ↔ ${state.affected_scope_pattern}`;
+      return {
+        source_lease_id: state.source_lease_id,
+        source_task_id: state.source_task_id,
+        source_pipeline_id: state.source_pipeline_id,
+        source_worktree: state.source_worktree,
+        affected_task_id: state.affected_task_id,
+        affected_pipeline_id: state.affected_pipeline_id,
+        affected_worktree: state.affected_worktree,
+        affected_task_status: affectedTask?.status || null,
+        severity,
+        reason_type: state.reason_type,
+        subsystem_tag: state.subsystem_tag,
+        source_scope_pattern: state.source_scope_pattern,
+        affected_scope_pattern: state.affected_scope_pattern,
+        summary: `${affectedTask?.title || state.affected_task_id} is stale because ${state.details?.source_task_title || state.source_task_id} changed shared ${staleArea}`,
+        stale_area: staleArea,
+        created_at: state.created_at,
+      };
+    });
+}
+
+export async function runAiMergeGate(db, repoRoot) {
+  const report = await scanAllWorktrees(db, repoRoot);
+  const worktreeAnalyses = report.worktrees.map((worktree) => {
+    const changedFiles = report.fileMap?.[worktree.name] ?? [];
+    const complianceState = report.worktreeCompliance?.find((entry) => entry.worktree === worktree.name)?.compliance_state
+      ?? worktree.compliance_state
+      ?? 'observed';
+    return summarizeWorktree(worktree, changedFiles, complianceState);
+  });
+
+  const pairAnalyses = [];
+  for (let i = 0; i < worktreeAnalyses.length; i++) {
+    for (let j = i + 1; j < worktreeAnalyses.length; j++) {
+      pairAnalyses.push(buildPairAnalysis(worktreeAnalyses[i], worktreeAnalyses[j], report));
+    }
+  }
+
+  const boundaryValidations = evaluateBoundaryValidations(db);
+  const dependencyInvalidations = evaluateDependencyInvalidations(db);
+  const overall = summarizeOverall(pairAnalyses, worktreeAnalyses, boundaryValidations, dependencyInvalidations);
+  const result = {
+    ok: overall.status === 'pass',
+    status: overall.status,
+    summary: overall.summary,
+    worktrees: worktreeAnalyses,
+    pairs: pairAnalyses,
+    boundary_validations: boundaryValidations,
+    dependency_invalidations: dependencyInvalidations,
+    compliance: report.complianceSummary,
+    unclaimed_changes: report.unclaimedChanges,
+    branch_conflicts: report.conflicts,
+    file_conflicts: report.fileConflicts,
+    ownership_conflicts: report.ownershipConflicts || [],
+    semantic_conflicts: report.semanticConflicts || [],
+  };
+
+  logAuditEvent(db, {
+    eventType: 'ai_merge_gate',
+    status: overall.status === 'blocked' ? 'denied' : (overall.status === 'warn' ? 'warn' : 'allowed'),
+    reasonCode: overall.status === 'blocked' ? 'semantic_merge_risk' : null,
+    details: JSON.stringify({
+      status: result.status,
+      blocked_pairs: pairAnalyses.filter((item) => item.status === 'blocked').length,
+      warned_pairs: pairAnalyses.filter((item) => item.status === 'warn').length,
+      blocked_boundary_validations: boundaryValidations.filter((item) => item.severity === 'blocked').length,
+      warned_boundary_validations: boundaryValidations.filter((item) => item.severity === 'warn').length,
+      blocked_dependency_invalidations: dependencyInvalidations.filter((item) => item.severity === 'blocked').length,
+      warned_dependency_invalidations: dependencyInvalidations.filter((item) => item.severity === 'warn').length,
+    }),
+  });
+
+  return result;
+}

package/src/core/monitor.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+export function getMonitorStatePath(repoRoot) {
+  return join(repoRoot, '.switchman', 'monitor.json');
+}
+
+export function readMonitorState(repoRoot) {
+  const statePath = getMonitorStatePath(repoRoot);
+  if (!existsSync(statePath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeMonitorState(repoRoot, state) {
+  const statePath = getMonitorStatePath(repoRoot);
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  return statePath;
+}
+
+export function clearMonitorState(repoRoot) {
+  const statePath = getMonitorStatePath(repoRoot);
+  rmSync(statePath, { force: true });
+}
+
+export function isProcessRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/outcome.js

@@ -0,0 +1,153 @@
+import { getActiveFileClaims, getTask, getTaskSpec, getWorktree } from './db.js';
+import { getWorktreeChangedFiles } from './git.js';
+import { matchesPathPatterns } from './ignore.js';
+
+function isTestPath(filePath) {
+  return /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(filePath);
+}
+
+function isDocsPath(filePath) {
+  return /(^|\/)(docs?|readme)(\/|$)|(^|\/)README(\.[^.]+)?$/i.test(filePath);
+}
+
+function isSourcePath(filePath) {
+  return /(^|\/)(src|app|lib|server|client)(\/|$)/i.test(filePath) && !isTestPath(filePath);
+}
+
+function fileMatchesKeyword(filePath, keyword) {
+  const normalizedPath = String(filePath || '').toLowerCase();
+  const normalizedKeyword = String(keyword || '').toLowerCase();
+  return normalizedKeyword.length >= 3 && normalizedPath.includes(normalizedKeyword);
+}
+
+export function evaluateTaskOutcome(db, repoRoot, { taskId }) {
+  const task = getTask(db, taskId);
+  const taskSpec = getTaskSpec(db, taskId);
+  if (!task || !task.worktree) {
+    return {
+      status: 'failed',
+      reason_code: 'task_not_assigned',
+      changed_files: [],
+      findings: ['task has no assigned worktree'],
+    };
+  }
+
+  const worktree = getWorktree(db, task.worktree);
+  if (!worktree) {
+    return {
+      status: 'failed',
+      reason_code: 'worktree_missing',
+      changed_files: [],
+      findings: ['assigned worktree is not registered'],
+    };
+  }
+
+  const changedFiles = getWorktreeChangedFiles(worktree.path, repoRoot);
+  const activeClaims = getActiveFileClaims(db)
+    .filter((claim) => claim.task_id === taskId && claim.worktree === task.worktree)
+    .map((claim) => claim.file_path);
+  const changedOutsideClaims = changedFiles.filter((filePath) => !activeClaims.includes(filePath));
+  const changedInsideClaims = changedFiles.filter((filePath) => activeClaims.includes(filePath));
+  const allowedPaths = taskSpec?.allowed_paths || [];
+  const changedOutsideTaskScope = allowedPaths.length > 0
+    ? changedFiles.filter((filePath) => !matchesPathPatterns(filePath, allowedPaths))
+    : [];
+  const expectedOutputTypes = taskSpec?.expected_output_types || [];
+  const requiredDeliverables = taskSpec?.required_deliverables || [];
+  const objectiveKeywords = taskSpec?.objective_keywords || [];
+  const findings = [];
+
+  if (changedFiles.length === 0) {
+    findings.push('command exited successfully but produced no tracked file changes');
+    return {
+      status: 'needs_followup',
+      reason_code: 'no_changes_detected',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  if (activeClaims.length > 0 && changedOutsideClaims.length > 0) {
+    findings.push(`changed files outside claimed scope: ${changedOutsideClaims.join(', ')}`);
+    return {
+      status: 'needs_followup',
+      reason_code: 'changes_outside_claims',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  if (changedOutsideTaskScope.length > 0) {
+    findings.push(`changed files outside task scope: ${changedOutsideTaskScope.join(', ')}`);
+    return {
+      status: 'needs_followup',
+      reason_code: 'changes_outside_task_scope',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  const title = String(task.title || '').toLowerCase();
+  const expectsTests = expectedOutputTypes.includes('tests') || title.includes('test');
+  const expectsDocs = expectedOutputTypes.includes('docs') || title.includes('docs') || title.includes('readme') || title.includes('integration notes');
+  const expectsSource = expectedOutputTypes.includes('source') || title.startsWith('implement:') || title.includes('implement');
+  const changedTestFiles = changedFiles.filter(isTestPath);
+  const changedDocsFiles = changedFiles.filter(isDocsPath);
+  const changedSourceFiles = changedFiles.filter(isSourcePath);
+
+  if ((expectsTests || requiredDeliverables.includes('tests')) && changedTestFiles.length === 0) {
+    findings.push('task looks like a test task but no test files changed');
+    return {
+      status: 'needs_followup',
+      reason_code: 'missing_expected_tests',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  if ((expectsDocs || requiredDeliverables.includes('docs')) && changedDocsFiles.length === 0) {
+    findings.push('task looks like a docs task but no docs files changed');
+    return {
+      status: 'needs_followup',
+      reason_code: 'missing_expected_docs',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  if ((expectsSource || requiredDeliverables.includes('source')) && changedSourceFiles.length === 0) {
+    findings.push('implementation task finished without source-file changes');
+    return {
+      status: 'needs_followup',
+      reason_code: 'missing_expected_source_changes',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  const matchedObjectiveKeywords = objectiveKeywords.filter((keyword) =>
+    changedFiles.some((filePath) => fileMatchesKeyword(filePath, keyword)),
+  );
+  const minimumKeywordMatches = taskSpec?.risk_level === 'high'
+    ? Math.min(2, objectiveKeywords.length)
+    : Math.min(1, objectiveKeywords.length);
+
+  if (objectiveKeywords.length > 0 && matchedObjectiveKeywords.length < minimumKeywordMatches) {
+    findings.push(`changed files do not clearly satisfy task objective keywords: ${objectiveKeywords.join(', ')}`);
+    return {
+      status: 'needs_followup',
+      reason_code: 'objective_not_evidenced',
+      changed_files: changedFiles,
+      findings,
+    };
+  }
+
+  return {
+    status: 'accepted',
+    reason_code: null,
+    changed_files: changedFiles,
+    task_spec: taskSpec,
+    claimed_files: activeClaims,
+    findings: changedInsideClaims.length > 0 ? ['changes stayed within claimed scope'] : [],
+  };
+}