@besales/ops-framework 0.1.0

package/bin/lib/check-context-utils.mjs

@@ -0,0 +1,1448 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  deepMerge,
+  readJsonIfExists,
+  resolveProjectContext,
+} from './project-config.mjs';
+
+export const projectContext = resolveProjectContext();
+
+export const frameworkRoot = projectContext.frameworkRoot;
+export const pipelineRoot = frameworkRoot;
+export const projectPipelineRoot = projectContext.pipelineRoot;
+export const repoRoot = projectContext.repoRoot;
+export const tasksRoot = projectContext.tasksRoot;
+export const memoryRoot = projectContext.memoryRoot;
+export const cacheRoot = projectContext.cacheRoot;
+export const promptsRoot = projectContext.promptsRoot;
+export const configRoot = projectContext.configRoot;
+
+export const REQUIRED_TASK_ARTIFACTS = ['brief.md', 'research.md', 'plan.md', 'status.md'];
+export const OPTIONAL_TASK_ARTIFACTS = ['feedback.md', 'execution-feedback.md'];
+export const MEMORY_FILES = [
+  'project-context-digest.md',
+  'module-boundaries.md',
+  'standards-digest.md',
+  'recurring-failures.md',
+  'domain-glossary.md',
+  'checker-rubric.md',
+];
+
+export const RISK_CONFIG = {
+  low: {
+    contextBudgetTokens: 6000,
+    maxRepoReads: 5,
+  },
+  medium: {
+    contextBudgetTokens: 15000,
+    maxRepoReads: 12,
+  },
+  high: {
+    contextBudgetTokens: 30000,
+    maxRepoReads: 25,
+  },
+};
+
+export const ALLOWED_RISK_PROFILES = Object.keys(RISK_CONFIG);
+export const ALLOWED_RISK_TRIGGERS = ['auth-security', 'docs-only', 'dto-readmodel', 'ingestion-provider', 'materializer', 'panel-ui', 'prisma-schema', 'production-runtime', 'source-sync-provider', 'ui-visible-api', 'worker-queue'];
+
+export const CHECKER_CONTEXT_PACK_FILE = 'checker-context-pack.md';
+export const PLAYBOOK_TRIGGER_MAP = new Map([
+  ['panel-ui', ['ui-acceptance', 'complexity-performance']],
+  ['ui-visible-api', ['ui-acceptance']],
+  ['production-runtime', ['production-rollout']],
+  ['prisma-schema', ['production-rollout']],
+  ['auth-security', ['production-rollout']],
+  ['source-sync-provider', ['source-sync-provider']],
+  ['ingestion-provider', ['source-sync-provider']],
+  ['worker-queue', ['complexity-performance']],
+  ['materializer', ['complexity-performance']],
+  ['dto-readmodel', ['complexity-performance']],
+]);
+
+export const ALLOWED_VERDICTS = ['return_to_plan', 'ready_for_human_gate', 'human_arbitration_required', 'context_insufficient', 'checker_failed'];
+
+export const ALLOWED_FAILURE_REASONS = ['provider_unavailable', 'invalid_json', 'schema_validation_failed', 'context_overflow', 'context_insufficient', 'repo_read_limit_exceeded', 'memory_snapshot_mismatch', 'timeout', 'unknown'];
+
+export const ALLOWED_SEVERITIES = ['blocking', 'non_blocking', 'question'];
+export const ALLOWED_CLAIM_CATEGORIES = [
+  'missing_verification',
+  'missing_evidence',
+  'architecture_violation',
+  'risk_unaddressed',
+  'standards_violation',
+  'scope_drift',
+  'human_decision_required',
+  'checker_failure',
+];
+
+export const ALLOWED_REF_TYPES = [
+  'file',
+  'standards',
+  'task_boundary',
+  'plan_section',
+  'research_section',
+  'brief_section',
+  'status_section',
+  'human_decision',
+];
+
+export const ALLOWED_RESOLUTION_DECISIONS = [
+  'accepted',
+  'partially_accepted',
+  'rejected',
+  'needs_research',
+  'needs_human_decision',
+];
+
+export const PLAN_SECTIONS = new Map([
+  ['цель', 'цель'],
+  ['goal', 'цель'],
+  ['опора на findings из research', 'опора на findings из research'],
+  ['опора на research', 'опора на findings из research'],
+  ['допущения', 'допущения'],
+  ['assumptions', 'допущения'],
+  ['затронутые модули и файлы', 'затронутые модули и файлы'],
+  ['scope', 'затронутые модули и файлы'],
+  ['шаги реализации', 'шаги реализации'],
+  ['implementation steps', 'шаги реализации'],
+  ['implementation slices', 'шаги реализации'],
+  ['runtime flow', 'шаги реализации'],
+  ['риски и открытые вопросы', 'риски и открытые вопросы'],
+  ['known risks', 'риски и открытые вопросы'],
+  ['open check items', 'риски и открытые вопросы'],
+  ['verification plan', 'verification plan'],
+  ['verification and replay plan', 'verification plan'],
+  ['план проверки', 'verification plan'],
+  ['ui verification path', 'UI verification path'],
+  ['ui flow', 'UI verification path'],
+  ['ui verification path или явное not applicable', 'UI verification path'],
+  ['global standards alignment', 'global standards alignment'],
+  ['standards alignment', 'global standards alignment'],
+  ['что требует human approval', 'что требует human approval'],
+  ['constraints', 'допущения'],
+  ['core invariants', 'core invariants'],
+  ['инварианты', 'core invariants'],
+]);
+
+export const STRUCTURAL_PLAN_SECTIONS = new Set([
+  'затронутые модули и файлы',
+  'шаги реализации',
+  'verification plan',
+  'UI verification path',
+  'global standards alignment',
+  'что требует human approval',
+  'core invariants',
+]);
+
+export function resolveTaskDir(taskArg) {
+  const candidate = taskArg.startsWith('TASK-')
+    ? path.join(tasksRoot, taskArg)
+    : path.resolve(repoRoot, taskArg);
+
+  const resolved = path.resolve(candidate);
+  const relativeToTasks = path.relative(tasksRoot, resolved);
+  if (relativeToTasks.startsWith('..') || path.isAbsolute(relativeToTasks)) {
+    throw new Error(`Task path must be under ${relativePath(tasksRoot)}: ${taskArg}`);
+  }
+
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(`Task directory not found: ${relativePath(resolved)}`);
+  }
+
+  return resolved;
+}
+
+export function readTaskArtifacts(taskDir) {
+  const artifacts = new Map();
+  for (const fileName of REQUIRED_TASK_ARTIFACTS) {
+    const filePath = path.join(taskDir, fileName);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Missing required task artifact: ${relativePath(filePath)}`);
+    }
+    artifacts.set(fileName, fs.readFileSync(filePath, 'utf8'));
+  }
+  for (const fileName of OPTIONAL_TASK_ARTIFACTS) {
+    const filePath = path.join(taskDir, fileName);
+    if (fs.existsSync(filePath)) {
+      artifacts.set(fileName, fs.readFileSync(filePath, 'utf8'));
+    }
+  }
+  return artifacts;
+}
+
+export function readMemoryFiles() {
+  const files = [];
+  for (const fileName of MEMORY_FILES) {
+    const filePath = path.join(memoryRoot, fileName);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Missing Project Memory file: ${relativePath(filePath)}`);
+    }
+    const content = normalizeLineEndings(fs.readFileSync(filePath, 'utf8'));
+    files.push({
+      path: relativePath(filePath),
+      sha: sha256(content),
+    });
+  }
+  return files;
+}
+
+export function readMemorySnapshot(memoryFiles) {
+  return memoryFiles.map((memoryFile) => {
+    const filePath = path.join(repoRoot, memoryFile.path);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Memory snapshot file missing: ${memoryFile.path}`);
+    }
+    const content = normalizeLineEndings(fs.readFileSync(filePath, 'utf8'));
+    const actualSha = sha256(content);
+    if (actualSha !== memoryFile.sha) {
+      throw new Error(`Memory snapshot mismatch for ${memoryFile.path}: expected ${memoryFile.sha}, got ${actualSha}`);
+    }
+    return {
+      ...memoryFile,
+      content,
+    };
+  });
+}
+
+export function computeTaskContextInputs(taskDir) {
+  const taskArtifacts = readTaskArtifacts(taskDir);
+  const memoryFiles = readMemoryFiles();
+  const planFingerprint = computePlanFingerprint(taskArtifacts.get('plan.md'));
+  const memorySha = computeMemorySha(memoryFiles);
+  const parsedPlanSections = parseMarkdownSections(taskArtifacts.get('plan.md'));
+  const parsedResearchSections = parseMarkdownSections(taskArtifacts.get('research.md'));
+  const structuralLines = collectStructuralLines({
+    planSections: parsedPlanSections,
+    researchSections: parsedResearchSections,
+  });
+  const referencedFiles = extractReferencedFiles(structuralLines);
+  const risk = classifyRisk({
+    structuralLines,
+    referencedFiles,
+    planSections: parsedPlanSections,
+    riskConfig: projectContext.risk,
+  });
+  const qualityGates = analyzePlanQualityGates({
+    planContent: taskArtifacts.get('plan.md'),
+    risk,
+  });
+
+  return {
+    taskArtifacts,
+    memoryFiles,
+    planFingerprint,
+    memorySha,
+    parsedPlanSections,
+    parsedResearchSections,
+    structuralLines,
+    referencedFiles,
+    risk,
+    qualityGates,
+  };
+}
+
+export function riskRootWarnings(riskConfig = projectContext.risk) {
+  const warnings = [];
+  if (!normalizeRoots(riskConfig.uiRoots).length) {
+    warnings.push('risk.uiRoots is empty; path-based UI detection is disabled until the project config is filled.');
+  }
+  if (!normalizeRoots(riskConfig.backendRoots).length) {
+    warnings.push('risk.backendRoots is empty; path-based user-visible API detection is limited to text signals.');
+  }
+  if (!normalizeRoots(riskConfig.workerRoots).length) {
+    warnings.push('risk.workerRoots is empty; path-based worker detection is limited to text signals.');
+  }
+  return warnings;
+}
+
+export function buildCheckContext({ taskId, inputs, createdAt = new Date().toISOString() }) {
+  const budget = RISK_CONFIG[inputs.risk.riskProfile];
+  const checkerContextPack = buildCheckerContextPack({
+    taskId,
+    risk: inputs.risk,
+    qualityGates: inputs.qualityGates,
+    referencedFiles: inputs.referencedFiles,
+    structuralLines: inputs.structuralLines,
+    taskArtifacts: inputs.taskArtifacts,
+  });
+
+  return {
+    taskId,
+    stage: 'Check',
+    planSha: inputs.planFingerprint.planSha,
+    planFingerprintVersion: inputs.planFingerprint.planFingerprintVersion,
+    memorySha: inputs.memorySha,
+    riskProfile: inputs.risk.riskProfile,
+    riskTriggers: inputs.risk.riskTriggers,
+    riskWarnings: riskRootWarnings(),
+    createdAt,
+    memoryFiles: inputs.memoryFiles,
+    taskArtifacts: Array.from(inputs.taskArtifacts.entries()).map(([artifactPath, content]) => ({
+      path: artifactPath,
+      sha: sha256(normalizeLineEndings(content)),
+    })),
+    evidenceFile: 'check-evidence.md',
+    checkerContextPackFile: CHECKER_CONTEXT_PACK_FILE,
+    checkerContextPackSha: sha256(normalizeLineEndings(checkerContextPack)),
+    referencedFiles: inputs.referencedFiles,
+    relevantPlaybooks: readRelevantPlaybookMetadata(inputs.risk.riskTriggers),
+    memoryDeliveryMode: 'inline',
+    contextBudgetTokens: budget.contextBudgetTokens,
+    maxRepoReads: budget.maxRepoReads,
+  };
+}
+
+export function readCheckContext(taskDir) {
+  return readJsonFile(path.join(taskDir, 'check-context.json'));
+}
+
+export function isCheckContextCurrent(taskDir) {
+  try {
+    const taskId = path.basename(taskDir);
+    const inputs = computeTaskContextInputs(taskDir);
+    const expected = buildCheckContext({ taskId, inputs, createdAt: null });
+    const actual = readCheckContext(taskDir);
+    return {
+      current: actual.taskId === expected.taskId
+        && actual.planSha === expected.planSha
+        && actual.planFingerprintVersion === expected.planFingerprintVersion
+        && actual.memorySha === expected.memorySha
+        && actual.checkerContextPackFile === expected.checkerContextPackFile
+        && actual.checkerContextPackSha === expected.checkerContextPackSha
+        && JSON.stringify(actual.riskTriggers) === JSON.stringify(expected.riskTriggers)
+        && actual.riskProfile === expected.riskProfile
+        && JSON.stringify(actual.memoryFiles) === JSON.stringify(expected.memoryFiles)
+        && JSON.stringify(actual.taskArtifacts) === JSON.stringify(expected.taskArtifacts),
+      actual,
+      expected,
+    };
+  } catch (error) {
+    return {
+      current: false,
+      error,
+    };
+  }
+}
+
+export function readAgentsConfig() {
+  const defaultConfigPath = path.join(configRoot, 'default-agents.json');
+  const projectConfig = readJsonIfExists(projectContext.projectAgentsConfigPath);
+  return deepMerge(readJsonIfExists(defaultConfigPath), projectConfig);
+}
+
+export function resolveConfigValue(value, env = process.env) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const match = /^\$\{([A-Z0-9_]+)\}$/.exec(value.trim());
+  if (!match) {
+    return value;
+  }
+  return env[match[1]] || null;
+}
+
+export function parseCliArgs(argv) {
+  const args = {
+    positional: [],
+    flags: new Map(),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      args.positional.push(token);
+      continue;
+    }
+
+    const withoutPrefix = token.slice(2);
+    const [key, inlineValue] = withoutPrefix.split('=', 2);
+    if (inlineValue !== undefined) {
+      args.flags.set(key, inlineValue);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      args.flags.set(key, next);
+      index += 1;
+    } else {
+      args.flags.set(key, true);
+    }
+  }
+
+  return args;
+}
+
+export function getFlag(args, name, fallback = null) {
+  return args.flags.has(name) ? args.flags.get(name) : fallback;
+}
+
+export function readPrompt(name) {
+  return fs.readFileSync(path.join(promptsRoot, name), 'utf8');
+}
+
+export function computePromptSha(name) {
+  return sha256(normalizeMarkdownBody(readPrompt(name)));
+}
+
+export function readTaskFile(taskDir, fileName) {
+  const filePath = path.join(taskDir, fileName);
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+
+export function writeTaskFile(taskDir, fileName, content) {
+  fs.writeFileSync(path.join(taskDir, fileName), content.endsWith('\n') ? content : `${content}\n`);
+}
+
+export function updateMarkdownSection(markdown, heading, body) {
+  const normalized = normalizeLineEndings(markdown);
+  const escapedHeading = escapeRegExp(heading);
+  const pattern = new RegExp(`(^##\\s+${escapedHeading}\\s*\\n)([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'm');
+  const replacement = `## ${heading}\n\n${body.trim()}\n\n`;
+  if (pattern.test(normalized)) {
+    return normalized.replace(pattern, replacement);
+  }
+  return `${normalized.trimEnd()}\n\n${replacement}`;
+}
+
+export function readStatusStage(taskDir) {
+  const status = readTaskFile(taskDir, 'status.md');
+  const sections = parseMarkdownSections(status);
+  const stage = sections.get('Текущий этап') || sections.get('Current stage') || '';
+  return stage.replace(/[`*_]/g, '').trim();
+}
+
+export function updateStatus(taskDir, updates) {
+  let status = readTaskFile(taskDir, 'status.md') || '# Status\n';
+  const sectionMap = new Map([
+    ['stage', 'Текущий этап'],
+    ['owner', 'Текущий owner'],
+    ['routingDecision', 'Latest routing decision'],
+    ['planSha', 'Plan SHA'],
+    ['memorySha', 'Memory SHA'],
+    ['checkVerdict', 'Latest check verdict'],
+    ['checkResult', 'Latest check result'],
+    ['checkResolution', 'Latest check resolution'],
+    ['humanGateSummary', 'Human Gate summary'],
+    ['feedbackIntake', 'Feedback intake'],
+    ['executionFeedback', 'Execution feedback intake'],
+    ['supervisorAction', 'Последнее действие supervisor'],
+    ['nextStep', 'Следующий шаг'],
+    ['humanApproval', 'Нужен ли сейчас human approval'],
+  ]);
+
+  for (const [key, value] of Object.entries(updates)) {
+    const heading = sectionMap.get(key);
+    if (!heading || value === undefined || value === null) {
+      continue;
+    }
+    status = updateMarkdownSection(status, heading, String(value));
+  }
+
+  writeTaskFile(taskDir, 'status.md', status);
+}
+
+export function appendOrchestrationLog(taskDir, entry) {
+  const now = new Date().toISOString();
+  const logPath = path.join(taskDir, 'orchestration-log.md');
+  const existing = fs.existsSync(logPath)
+    ? fs.readFileSync(logPath, 'utf8').trimEnd()
+    : '# Orchestration Log\n\n## Entries';
+  const serialized = typeof entry === 'string' ? entry : JSON.stringify(entry);
+  fs.writeFileSync(logPath, `${existing}\n- \`${now}\` — ${serialized}\n`);
+}
+
+export function buildCheckerFailureResult({
+  taskId,
+  checkContext,
+  checkerProvider,
+  checkerModel,
+  failureReason,
+}) {
+  return {
+    taskId,
+    stage: 'Check',
+    checkerProvider,
+    checkerModel,
+    planSha: checkContext.planSha,
+    memorySha: checkContext.memorySha,
+    riskProfile: checkContext.riskProfile,
+    verdict: 'checker_failed',
+    failureReason,
+    blockingFindings: 0,
+    nonBlockingFindings: 0,
+    humanQuestions: 0,
+    findings: [],
+    readyForHumanGate: false,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function normalizeCheckResult(result, {
+  taskId,
+  checkContext,
+  checkerProvider,
+  checkerModel,
+}) {
+  const findings = (Array.isArray(result.findings) ? result.findings : []).map((finding, index) => ({
+    ...finding,
+    id: `F-${String(index + 1).padStart(3, '0')}`,
+  }));
+  return {
+    taskId,
+    stage: 'Check',
+    checkerProvider,
+    checkerModel,
+    planSha: checkContext.planSha,
+    memorySha: checkContext.memorySha,
+    riskProfile: checkContext.riskProfile,
+    verdict: result.verdict,
+    failureReason: result.failureReason ?? null,
+    blockingFindings: findings.filter((finding) => finding.severity === 'blocking').length,
+    nonBlockingFindings: findings.filter((finding) => finding.severity === 'non_blocking').length,
+    humanQuestions: findings.filter((finding) => finding.severity === 'question').length,
+    findings,
+    readyForHumanGate: result.verdict === 'ready_for_human_gate',
+    createdAt: result.createdAt || new Date().toISOString(),
+  };
+}
+
+export function computeMemorySha(memoryFiles) {
+  return sha256Json(memoryFiles.map(({ path: filePath, sha }) => ({ path: filePath, sha })));
+}
+
+export function computePlanFingerprint(planContent) {
+  const sections = parseMarkdownSections(planContent);
+  const semanticChunks = [];
+  for (const [rawTitle, body] of sections.entries()) {
+    const canonicalTitle = PLAN_SECTIONS.get(normalizeHeading(rawTitle));
+    if (canonicalTitle) {
+      semanticChunks.push(`## ${canonicalTitle}\n${normalizeMarkdownBody(body)}`);
+    }
+  }
+
+  if (semanticChunks.length === 0) {
+    return {
+      planSha: sha256(normalizeMarkdownBody(planContent)),
+      planFingerprintVersion: 'v1-raw-fallback',
+    };
+  }
+
+  return {
+    planSha: sha256(semanticChunks.join('\n\n')),
+    planFingerprintVersion: 'v1',
+  };
+}
+
+export function parseMarkdownSections(content) {
+  const sections = new Map();
+  let currentTitle = null;
+  let currentLines = [];
+
+  for (const line of normalizeLineEndings(content).split('\n')) {
+    const match = /^##\s+(.+?)\s*$/.exec(line);
+    if (match) {
+      if (currentTitle) {
+        sections.set(currentTitle, currentLines.join('\n'));
+      }
+      currentTitle = match[1].trim();
+      currentLines = [];
+      continue;
+    }
+
+    if (currentTitle) {
+      currentLines.push(line);
+    }
+  }
+
+  if (currentTitle) {
+    sections.set(currentTitle, currentLines.join('\n'));
+  }
+
+  return sections;
+}
+
+export function collectStructuralLines({ planSections, researchSections }) {
+  const lines = [];
+
+  for (const [title, body] of planSections.entries()) {
+    const canonicalTitle = PLAN_SECTIONS.get(normalizeHeading(title));
+    const includeWholeSection = canonicalTitle && STRUCTURAL_PLAN_SECTIONS.has(canonicalTitle);
+    for (const line of body.split('\n')) {
+      if (includeWholeSection || isEvidenceLikeLine(line)) {
+        lines.push(line);
+      }
+    }
+  }
+
+  for (const [title, body] of researchSections.entries()) {
+    const normalizedTitle = normalizeHeading(title);
+    const includeWholeSection = /finding|evidence|repo|архитект|модул|файл|провер|verification|standards/.test(normalizedTitle);
+    for (const line of body.split('\n')) {
+      if (includeWholeSection || isEvidenceLikeLine(line)) {
+        lines.push(line);
+      }
+    }
+  }
+
+  return lines.map((line) => line.trim()).filter(Boolean);
+}
+
+export function isEvidenceLikeLine(line) {
+  const trimmed = line.trim();
+  return /(^|\s)(Evidence|Finding|File|Path|Command|Источник|Файл|Команда|Провер|Риск|Модул|Route|API):/i.test(trimmed)
+    || /`?[A-Za-z0-9._@-]+\/[A-Za-z0-9._@/+:-]+/.test(trimmed)
+    || /`?(yarn|node|npm|pnpm|prisma)\s+/.test(trimmed);
+}
+
+export function extractReferencedFiles(lines) {
+  const refs = new Set();
+  const pathPattern = /(?:^|[\s`'"])(?!https?:\/\/)([A-Za-z0-9._@-]+\/[A-Za-z0-9._@/+:-]+)(?=[\s`'",).;:]|$)/g;
+
+  for (const line of lines) {
+    for (const match of line.matchAll(pathPattern)) {
+      const cleaned = match[1]
+        .replace(/:L?\d+$/i, '')
+        .replace(/[),.;:]+$/g, '');
+      refs.add(cleaned);
+    }
+  }
+
+  return Array.from(refs).sort();
+}
+
+export function classifyRisk({ structuralLines, referencedFiles, planSections, riskConfig = {} }) {
+  const triggers = new Set();
+  const structuralText = structuralLines.join('\n').toLowerCase();
+
+  const hasRef = (predicate) => referencedFiles.some(predicate);
+  const hasText = (pattern) => pattern.test(structuralText);
+
+  if (hasRef((ref) => ref === 'prisma/schema.prisma' || ref.startsWith('prisma/migrations/')) || hasText(/\b(prisma migrate|migration|schema\.prisma)\b/)) {
+    triggers.add('prisma-schema');
+  }
+  if (hasText(/\b(auth|session|cookie|security|encryption|secret|credential)\b/)) {
+    triggers.add('auth-security');
+  }
+  const uiRoots = normalizeRoots(riskConfig.uiRoots);
+  const backendRoots = normalizeRoots(riskConfig.backendRoots);
+  const workerRoots = normalizeRoots(riskConfig.workerRoots);
+
+  if (hasRef((ref) => matchesAnyRoot(ref, workerRoots)) || hasText(/\b(worker|scheduler|queue|bullmq|backfill|pacing)\b/)) {
+    triggers.add('worker-queue');
+  }
+  if (hasText(/\b(source ingestion|source-ingestion|connector|oauth|callback|provider api|sync plan)\b/)) {
+    triggers.add('ingestion-provider');
+  }
+  if (hasText(/\b(source sync|source-sync|raw record|raw records|pagination|rate limit|retry|retries|idempotency|partial failure|provider stream|sync worker|sync scheduler)\b/)) {
+    triggers.add('source-sync-provider');
+  }
+  if (hasText(/\b(production|railway|deploy|runtime env|environment variable)\b/)) {
+    triggers.add('production-runtime');
+  }
+  if (hasText(/\b(materialization|materialize|canonical entity|projection)\b/)) {
+    triggers.add('materializer');
+  }
+  if (hasText(/\b(api contract|route|endpoint|payload|read model|ui-visible)\b/)) {
+    triggers.add('ui-visible-api');
+  }
+  if (hasRef((ref) => matchesAnyRoot(ref, uiRoots))) {
+    triggers.add('panel-ui');
+  }
+  if (hasRef((ref) => matchesAnyRoot(ref, backendRoots)) && hasText(/\b(api contract|route|endpoint|payload|read model|ui-visible)\b/)) {
+    triggers.add('ui-visible-api');
+  }
+  if (hasText(/\b(dto|validation|read model|payload shape|contract)\b/)) {
+    triggers.add('dto-readmodel');
+  }
+
+  if (triggers.size === 0 && isDocsOnly(referencedFiles, planSections)) {
+    triggers.add('docs-only');
+  }
+
+  const riskProfile = Array.from(triggers).some((trigger) => [
+    'prisma-schema',
+    'auth-security',
+    'worker-queue',
+    'ingestion-provider',
+    'production-runtime',
+    'source-sync-provider',
+    'materializer',
+  ].includes(trigger))
+    ? 'high'
+    : Array.from(triggers).some((trigger) => [
+        'ui-visible-api',
+        'panel-ui',
+        'dto-readmodel',
+      ].includes(trigger))
+      ? 'medium'
+      : 'low';
+
+  return {
+    riskProfile,
+    riskTriggers: Array.from(triggers).sort(),
+  };
+}
+
+export function isDocsOnly(referencedFiles, planSections) {
+  if (referencedFiles.length > 0) {
+    return referencedFiles.every((ref) => ref.startsWith('docs/') || ref.startsWith('ops/agent-pipeline/'));
+  }
+
+  const titleText = Array.from(planSections.keys()).join('\n').toLowerCase();
+  return /\b(docs|documentation|template|prompt|artifact)\b/.test(titleText);
+}
+
+export function buildEvidenceMarkdown({
+  taskId,
+  risk,
+  qualityGates,
+  referencedFiles,
+  structuralLines,
+  planFingerprint,
+  memorySha,
+  taskArtifacts,
+}) {
+  const missingSignals = [];
+  if (!taskArtifacts.get('research.md').trim()) {
+    missingSignals.push('`research.md` is empty.');
+  }
+  if (!taskArtifacts.get('plan.md').trim()) {
+    missingSignals.push('`plan.md` is empty.');
+  }
+  if (referencedFiles.length === 0) {
+    missingSignals.push('No structural file references were extracted from `plan.md` or `research.md`.');
+  }
+  for (const signal of qualityGates?.missingSignals || []) {
+    missingSignals.push(signal);
+  }
+
+  const claimRows = structuralLines.slice(0, 80).map((line) => `| ${escapeTableCell(line)} | extracted structural line | Checker should verify if relevant |`);
+
+  return `# Check Evidence
+
+Task: \`${taskId}\`
+
+Generated at: \`${new Date().toISOString()}\`
+
+## Fingerprints
+
+- Plan SHA: \`${planFingerprint.planSha}\`
+- Plan fingerprint version: \`${planFingerprint.planFingerprintVersion}\`
+- Memory SHA: \`${memorySha}\`
+
+## Risk trigger summary
+
+- Risk profile: \`${risk.riskProfile}\`
+- Risk triggers: ${risk.riskTriggers.length ? risk.riskTriggers.map((trigger) => `\`${trigger}\``).join(', ') : '`none`'}
+
+## Claims
+
+| Claim | Evidence | Implication |
+| --- | --- | --- |
+${claimRows.length ? claimRows.join('\n') : '| No structural claims extracted | n/a | Checker should rely on task artifacts directly |'}
+
+## Referenced Files
+
+${referencedFiles.length ? referencedFiles.map((ref) => `- \`${ref}\``).join('\n') : '- No referenced files extracted.'}
+
+## Missing Evidence Signals
+
+${missingSignals.length ? missingSignals.map((signal) => `- ${signal}`).join('\n') : '- No missing evidence signals detected by deterministic builder.'}
+`;
+}
+
+export function analyzePlanQualityGates({ planContent, risk }) {
+  const sections = parseMarkdownSections(planContent);
+  const uiRequired = requiresUiAcceptanceScenarios(risk.riskTriggers);
+  const complexityRequired = requiresComplexityBudget(risk.riskTriggers);
+  const optimizationTier = determineOptimizationTier(risk.riskTriggers);
+  const optimizationRequired = requiresOptimizationStrategy(optimizationTier);
+  const productionRolloutRequired = requiresProductionRolloutGate(risk.riskTriggers);
+  const sourceSyncProviderRequired = requiresSourceSyncProviderGate(risk.riskTriggers);
+  const uiAcceptance = inspectUiAcceptanceScenarios(sections);
+  const complexityBudget = inspectComplexityPerformanceBudget(sections);
+  const optimizationStrategy = inspectOptimizationStrategy(sections);
+  const productionRollout = inspectProductionRolloutGate(sections);
+  const sourceSyncProvider = inspectSourceSyncProviderGate(sections);
+  const missingSignals = [];
+
+  if (uiRequired && !uiAcceptance.present) {
+    missingSignals.push('UI-visible risk detected but `## UI Acceptance Scenarios` is missing or incomplete.');
+  }
+  if (uiRequired && uiAcceptance.present && !uiAcceptance.hasMustCatch) {
+    missingSignals.push('`## UI Acceptance Scenarios` exists but does not include a `Must catch` column/field.');
+  }
+  if (complexityRequired && !complexityBudget.present) {
+    missingSignals.push('Complexity/performance risk detected but `## Complexity / Performance Budget` is missing or incomplete.');
+  }
+  if (optimizationRequired && !optimizationStrategy.present) {
+    missingSignals.push(`Optimization tier ${optimizationTier} detected but \`## Optimization Strategy\` is missing or incomplete.`);
+  }
+  if (productionRolloutRequired && !productionRollout.present) {
+    missingSignals.push('Production rollout risk detected but `## Production Rollout Gate` is missing or incomplete.');
+  }
+  if (sourceSyncProviderRequired && !sourceSyncProvider.present) {
+    missingSignals.push('Source sync/provider risk detected but `## Source Sync / Provider Gate` is missing or incomplete.');
+  }
+
+  return {
+    uiRequired,
+    uiAcceptance,
+    complexityRequired,
+    complexityBudget,
+    optimizationTier,
+    optimizationRequired,
+    optimizationStrategy,
+    productionRolloutRequired,
+    productionRollout,
+    sourceSyncProviderRequired,
+    sourceSyncProvider,
+    missingSignals,
+  };
+}
+
+export function requiresUiAcceptanceScenarios(riskTriggers = []) {
+  return riskTriggers.includes('panel-ui') || riskTriggers.includes('ui-visible-api');
+}
+
+export function requiresComplexityBudget(riskTriggers = []) {
+  return riskTriggers.some((trigger) => [
+    'dto-readmodel',
+    'materializer',
+    'panel-ui',
+    'production-runtime',
+    'source-sync-provider',
+    'ui-visible-api',
+    'worker-queue',
+  ].includes(trigger));
+}
+
+export function determineOptimizationTier(riskTriggers = []) {
+  const triggers = new Set(riskTriggers);
+  if ([
+    'source-sync-provider',
+    'ingestion-provider',
+    'worker-queue',
+    'materializer',
+    'production-runtime',
+  ].some((trigger) => triggers.has(trigger))) {
+    return 'O3';
+  }
+  if ([
+    'dto-readmodel',
+    'panel-ui',
+    'ui-visible-api',
+    'prisma-schema',
+  ].some((trigger) => triggers.has(trigger))) {
+    return 'O2';
+  }
+  if (triggers.size > 0 && !triggers.has('docs-only')) {
+    return 'O1';
+  }
+  return 'O0';
+}
+
+export function requiresOptimizationStrategy(optimizationTier) {
+  return optimizationTier === 'O2' || optimizationTier === 'O3';
+}
+
+export function requiresProductionRolloutGate(riskTriggers = []) {
+  return riskTriggers.some((trigger) => [
+    'auth-security',
+    'prisma-schema',
+    'production-runtime',
+    'worker-queue',
+  ].includes(trigger));
+}
+
+export function requiresSourceSyncProviderGate(riskTriggers = []) {
+  return riskTriggers.includes('ingestion-provider') || riskTriggers.includes('source-sync-provider');
+}
+
+export function inspectUiAcceptanceScenarios(sections) {
+  const body = readCanonicalSection(sections, ['ui acceptance scenarios', 'ui acceptance', 'ui scenarios']);
+  if (!body) {
+    return {
+      present: false,
+      scenarioCount: 0,
+      hasUserIntent: false,
+      hasSteps: false,
+      hasExpectedVisibleResult: false,
+      hasMustCatch: false,
+    };
+  }
+
+  const normalized = body.toLowerCase();
+  const scenarioCount = (body.match(/\bUI-\d{3}\b/g) || []).length;
+  const result = {
+    present: true,
+    scenarioCount,
+    hasUserIntent: /user intent|пользователь|намерени/.test(normalized),
+    hasSteps: /steps|шаги|действия/.test(normalized),
+    hasExpectedVisibleResult: /expected visible result|visible result|ожидаем|видим/.test(normalized),
+    hasMustCatch: /must catch|должн[аоы]? поймать|ловит|поймать/.test(normalized),
+  };
+  result.complete = result.scenarioCount > 0
+    && result.hasUserIntent
+    && result.hasSteps
+    && result.hasExpectedVisibleResult
+    && result.hasMustCatch;
+  result.present = result.complete;
+  return result;
+}
+
+export function inspectComplexityPerformanceBudget(sections) {
+  const body = readCanonicalSection(sections, [
+    'complexity / performance budget',
+    'complexity performance budget',
+    'performance budget',
+    'complexity budget',
+  ]);
+  if (!body) {
+    return {
+      present: false,
+      hasHotPaths: false,
+      hasDataSize: false,
+      hasRisks: false,
+      hasBudget: false,
+    };
+  }
+
+  const normalized = body.toLowerCase();
+  const result = {
+    present: true,
+    hasHotPaths: /hot path|hot paths|горяч/.test(normalized),
+    hasDataSize: /data size|row count|rows|объем|строк/.test(normalized),
+    hasRisks: /complexity risk|risk|n\+1|nested|render|риск/.test(normalized),
+    hasBudget: /budget|<\s*\d|ms|sec|seconds|s\b|бюджет|лимит/.test(normalized),
+  };
+  result.complete = result.hasHotPaths && result.hasDataSize && result.hasRisks && result.hasBudget;
+  result.present = result.complete;
+  return result;
+}
+
+export function inspectOptimizationStrategy(sections) {
+  const body = readCanonicalSection(sections, [
+    'optimization strategy',
+    'optimization review strategy',
+    'optimization gate',
+  ]);
+  if (!body) {
+    return {
+      present: false,
+      tier: null,
+      hasHotPaths: false,
+      hasDataSize: false,
+      hasApproach: false,
+      hasAntiPatterns: false,
+      hasBudget: false,
+    };
+  }
+
+  const normalized = body.toLowerCase();
+  const tierMatch = /\bO[0-3]\b/i.exec(body);
+  const result = {
+    present: true,
+    tier: tierMatch ? tierMatch[0].toUpperCase() : null,
+    hasHotPaths: /hot path|hot paths|горяч/.test(normalized),
+    hasDataSize: /data size|row count|rows|объем|строк|expected/.test(normalized),
+    hasApproach: /strategy|approach|chosen|batch|map|set|index|query|window|memo|cache|подход|стратег/.test(normalized),
+    hasAntiPatterns: /n\+1|repeated scan|nested|o\(n\^2\)|unbounded|full scan|render|anti-pattern|антипаттерн/.test(normalized),
+    hasBudget: /budget|stop rule|stop-rule|minutes|минут|measurement|timing|benchmark|explain|defer|бюджет|лимит/.test(normalized),
+  };
+  result.complete = Boolean(result.tier)
+    && result.hasHotPaths
+    && result.hasDataSize
+    && result.hasApproach
+    && result.hasAntiPatterns
+    && result.hasBudget;
+  result.present = result.complete;
+  return result;
+}
+
+export function inspectProductionRolloutGate(sections) {
+  const body = readCanonicalSection(sections, [
+    'production rollout gate',
+    'production rollout',
+    'rollout gate',
+    'deployment gate',
+  ]);
+  if (!body) {
+    return {
+      present: false,
+      hasImpact: false,
+      hasEnvironment: false,
+      hasRollback: false,
+      hasPostDeployEvidence: false,
+    };
+  }
+
+  const normalized = body.toLowerCase();
+  const result = {
+    present: true,
+    hasImpact: /impact|scope|blast radius|migration|worker|cron|auth|billing|api|влияни|радиус/.test(normalized),
+    hasEnvironment: /env|environment|secret|variable|railway|runtime|deploy|окружени|переменн/.test(normalized),
+    hasRollback: /rollback|revert|disable|kill switch|feature flag|откат|выключ/.test(normalized),
+    hasPostDeployEvidence: /post-?deploy|smoke|monitor|logs|metric|evidence|после deploy|лог|метрик/.test(normalized),
+  };
+  result.complete = result.hasImpact && result.hasEnvironment && result.hasRollback && result.hasPostDeployEvidence;
+  result.present = result.complete;
+  return result;
+}
+
+export function inspectSourceSyncProviderGate(sections) {
+  const body = readCanonicalSection(sections, [
+    'source sync / provider gate',
+    'source sync provider gate',
+    'source sync gate',
+    'provider gate',
+  ]);
+  if (!body) {
+    return {
+      present: false,
+      hasScope: false,
+      hasIdempotency: false,
+      hasFailureHandling: false,
+      hasCoverageEvidence: false,
+    };
+  }
+
+  const normalized = body.toLowerCase();
+  const result = {
+    present: true,
+    hasScope: /scope|window|provider|stream|pagination|rate limit|raw record|объем|окно|провайдер/.test(normalized),
+    hasIdempotency: /idempot|dedupe|duplicate|retry|replay|повтор|дубликат/.test(normalized),
+    hasFailureHandling: /partial failure|failure|timeout|backoff|resume|dead letter|ошиб|частич/.test(normalized),
+    hasCoverageEvidence: /coverage|parity|count|sample|audit|evidence|metric|сверк|покрыт/.test(normalized),
+  };
+  result.complete = result.hasScope && result.hasIdempotency && result.hasFailureHandling && result.hasCoverageEvidence;
+  result.present = result.complete;
+  return result;
+}
+
+function readCanonicalSection(sections, names) {
+  const wanted = new Set(names.map(normalizeHeading));
+  for (const [title, body] of sections.entries()) {
+    if (wanted.has(normalizeHeading(title))) {
+      return body;
+    }
+  }
+  return '';
+}
+
+export function buildCheckerContextPack({
+  taskId,
+  risk,
+  qualityGates,
+  referencedFiles,
+  structuralLines,
+  taskArtifacts,
+}) {
+  const statusSections = parseMarkdownSections(taskArtifacts.get('status.md') || '');
+  const planSections = parseMarkdownSections(taskArtifacts.get('plan.md') || '');
+  const activeSlice = statusSections.get('Current slice')
+    || statusSections.get('Active slice')
+    || statusSections.get('Активный slice')
+    || 'Not explicitly declared in status.md.';
+  const decision = statusSections.get('Следующий шаг')
+    || statusSections.get('Next step')
+    || 'Validate whether plan is safe to move to Human Gate.';
+  const requiredFiles = referencedFiles.slice(0, RISK_CONFIG[risk.riskProfile].maxRepoReads);
+  const risks = [
+    ...risk.riskTriggers.map((trigger) => `- \`${trigger}\``),
+    ...(qualityGates.missingSignals || []).map((signal) => `- ${signal}`),
+  ];
+  const checkerQuestions = buildCheckerQuestions({ risk, qualityGates });
+  const relevantPlaybooks = readRelevantPlaybookMetadata(risk.riskTriggers);
+
+  return [
+    '# Checker Context Pack',
+    '',
+    `Task: \`${taskId}\``,
+    '',
+    '## Decision To Validate',
+    '',
+    decision.trim(),
+    '',
+    '## Active Slice',
+    '',
+    activeSlice.trim(),
+    '',
+    '## Why This Is Risky',
+    '',
+    risks.length ? risks.join('\n') : '- No risk triggers detected.',
+    '',
+    '## Required Repo Context',
+    '',
+    requiredFiles.length
+      ? requiredFiles.map((file) => `- \`${file}\` — referenced by current plan/research; inspect if it is material to the claim.`).join('\n')
+      : '- No repo files were deterministically extracted; Checker must rely on task artifacts and ask for better plan context if needed.',
+    '',
+    '## Prior Relevant Failure Hints',
+    '',
+    '- UI smoke without use-case assertions has historically missed important visual/semantic regressions.',
+    '- Execution ledgers that omit changed files or command evidence cause expensive Verify loops.',
+    '- Complexity/performance budgets must be explicit for read-models, materializers, workers and dashboard-like UI.',
+    '',
+    '## UI Acceptance Expectations',
+    '',
+    qualityGates.uiRequired
+      ? [
+          '- UI-visible risk detected.',
+          `- UI Acceptance Scenarios complete: \`${qualityGates.uiAcceptance.present ? 'yes' : 'no'}\`.`,
+          '- Checker must return `return_to_plan` if scenarios do not specify user intent, setup/steps, expected visible result and must-catch regressions.',
+        ].join('\n')
+      : '- UI acceptance scenarios are not required by detected triggers.',
+    '',
+    '## Complexity / Performance Expectations',
+    '',
+    qualityGates.complexityRequired
+      ? [
+          '- Complexity/performance risk detected.',
+          `- Complexity / Performance Budget complete: \`${qualityGates.complexityBudget.present ? 'yes' : 'no'}\`.`,
+          '- Checker must return `return_to_plan` if hot paths, data size, complexity risks and budget/evidence are not named.',
+        ].join('\n')
+      : '- Complexity/performance budget is not required by detected triggers.',
+    '',
+    '## Optimization Expectations',
+    '',
+    qualityGates.optimizationRequired
+      ? [
+          `- Optimization tier detected: \`${qualityGates.optimizationTier}\`.`,
+          `- Optimization Strategy complete: \`${qualityGates.optimizationStrategy.present ? 'yes' : 'no'}\`.`,
+          '- Checker must return `return_to_plan` if O2/O3 hot-path work lacks bounded strategy, anti-pattern review and stop rule.',
+        ].join('\n')
+      : `- Optimization tier: \`${qualityGates.optimizationTier || 'O0'}\`; dedicated strategy section is not required.`,
+    '',
+    '## Production Rollout Expectations',
+    '',
+    qualityGates.productionRolloutRequired
+      ? [
+          '- Production/runtime rollout risk detected.',
+          `- Production Rollout Gate complete: \`${qualityGates.productionRollout.present ? 'yes' : 'no'}\`.`,
+          '- Checker must return `return_to_plan` if impact, environment, rollback and post-deploy evidence are not named.',
+        ].join('\n')
+      : '- Production rollout gate is not required by detected triggers.',
+    '',
+    '## Source Sync / Provider Expectations',
+    '',
+    qualityGates.sourceSyncProviderRequired
+      ? [
+          '- Source sync/provider risk detected.',
+          `- Source Sync / Provider Gate complete: \`${qualityGates.sourceSyncProvider.present ? 'yes' : 'no'}\`.`,
+          '- Checker must return `return_to_plan` if scope/window, idempotency, failure handling and coverage evidence are not named.',
+        ].join('\n')
+      : '- Source sync/provider gate is not required by detected triggers.',
+    '',
+    '## Relevant Playbooks',
+    '',
+    renderRelevantPlaybookIndex(relevantPlaybooks),
+    '',
+    '## Checker Questions',
+    '',
+    checkerQuestions.map((question, index) => `${index + 1}. ${question}`).join('\n'),
+    '',
+    '## Structural Lines Sample',
+    '',
+    structuralLines.slice(0, 30).map((line) => `- ${line}`).join('\n') || '- No structural lines extracted.',
+    '',
+    '## Plan Sections Seen',
+    '',
+    Array.from(planSections.keys()).map((title) => `- ${title}`).join('\n') || '- No level-2 plan sections found.',
+    '',
+  ].join('\n');
+}
+
+export function selectRelevantPlaybookNames(riskTriggers = []) {
+  const names = new Set();
+  for (const trigger of riskTriggers) {
+    for (const playbookName of PLAYBOOK_TRIGGER_MAP.get(trigger) || []) {
+      names.add(playbookName);
+    }
+  }
+  return Array.from(names).sort();
+}
+
+export function readRelevantPlaybooks(riskTriggers = []) {
+  return selectRelevantPlaybookNames(riskTriggers).map((name) => {
+    const fileName = `${name}.md`;
+    const sharedPath = path.join(projectContext.sharedPlaybooksRoot || projectContext.playbooksRoot, fileName);
+    const projectPath = projectContext.projectPlaybooksRoot
+      ? path.join(projectContext.projectPlaybooksRoot, fileName)
+      : null;
+    return {
+      name,
+      title: titleFromPlaybookName(name),
+      sharedPath: fs.existsSync(sharedPath) ? relativePath(sharedPath) : null,
+      sharedContent: fs.existsSync(sharedPath) ? fs.readFileSync(sharedPath, 'utf8') : '',
+      projectPath: projectPath && fs.existsSync(projectPath) ? relativePath(projectPath) : null,
+      projectContent: projectPath && fs.existsSync(projectPath) ? fs.readFileSync(projectPath, 'utf8') : '',
+    };
+  }).filter((playbook) => playbook.sharedContent || playbook.projectContent);
+}
+
+export function readRelevantPlaybookMetadata(riskTriggers = []) {
+  return readRelevantPlaybooks(riskTriggers).map((playbook) => ({
+    name: playbook.name,
+    title: playbook.title,
+    selected: true,
+    sharedPath: playbook.sharedPath,
+    sharedSha: playbook.sharedContent ? sha256(normalizeLineEndings(playbook.sharedContent)) : null,
+    projectPath: playbook.projectPath,
+    projectSha: playbook.projectContent ? sha256(normalizeLineEndings(playbook.projectContent)) : null,
+    hasProjectOverlay: Boolean(playbook.projectContent),
+  }));
+}
+
+export function renderRelevantPlaybooks(playbooks, { mode = 'compact' } = {}) {
+  if (!playbooks.length) {
+    return '- No relevant playbooks selected by risk triggers.';
+  }
+  return playbooks.map((playbook) => [
+    `### Shared Playbook: ${playbook.title}`,
+    '',
+    playbook.sharedPath ? `Path: \`${playbook.sharedPath}\`` : 'Path: not found',
+    '',
+    mode === 'strict' ? playbook.sharedContent.trim() : excerptMarkdown(playbook.sharedContent),
+    '',
+    `### Project Overlay: ${playbook.title}`,
+    '',
+    playbook.projectPath ? `Path: \`${playbook.projectPath}\`` : 'Path: not configured/found',
+    '',
+    playbook.projectContent
+      ? (mode === 'strict' ? playbook.projectContent.trim() : excerptMarkdown(playbook.projectContent))
+      : '- No project overlay for this playbook.',
+  ].join('\n')).join('\n\n');
+}
+
+export function renderRelevantPlaybookIndex(playbooks) {
+  if (!playbooks.length) {
+    return '- No relevant playbooks selected by risk triggers.';
+  }
+  return playbooks.map((playbook) => [
+    `- ${playbook.title} (\`${playbook.name}\`)`,
+    `  - shared: ${playbook.sharedPath ? `\`${playbook.sharedPath}\` (${playbook.sharedSha})` : 'not found'}`,
+    `  - project overlay: ${playbook.projectPath ? `\`${playbook.projectPath}\` (${playbook.projectSha})` : 'not configured/found'}`,
+  ].join('\n')).join('\n');
+}
+
+export function validateExecutionEvidenceForPlan({ planContent, executionContent }) {
+  const errors = [];
+  const planSections = parseMarkdownSections(planContent || '');
+  const executionSections = parseMarkdownSections(executionContent || '');
+
+  if (hasAnySection(planSections, ['ui acceptance scenarios', 'ui acceptance', 'ui scenarios'])) {
+    const evidence = readAnySection(executionSections, ['ui acceptance evidence', 'ui/browser evidence', 'ui smoke evidence']);
+    if (!evidence) {
+      errors.push({
+        category: 'ui_verification_gap',
+        message: 'Plan contains UI Acceptance Scenarios but execution.md is missing UI Acceptance Evidence.',
+      });
+    } else {
+      if (!/\bUI-\d{3}\b/.test(evidence)) {
+        errors.push({
+          category: 'ui_verification_gap',
+          message: 'UI Acceptance Evidence must reference scenario ids like UI-001.',
+        });
+      }
+      if (!/\b(pass|passed|fail|failed|blocked|human-owned)\b/i.test(evidence)) {
+        errors.push({
+          category: 'ui_verification_gap',
+          message: 'UI Acceptance Evidence must record pass/fail/blocked/human-owned result.',
+        });
+      }
+      if (!/(screenshot|payload|visible|observed|browser|api evidence|rendered)/i.test(evidence)) {
+        errors.push({
+          category: 'ui_verification_gap',
+          message: 'UI Acceptance Evidence must include observed UI/payload/screenshot/rendered evidence, not only navigation success.',
+        });
+      }
+    }
+  }
+
+  if (hasAnySection(planSections, ['complexity / performance budget', 'complexity performance budget', 'performance budget', 'complexity budget'])) {
+    const evidence = readAnySection(executionSections, ['complexity / performance evidence', 'performance evidence', 'complexity verify evidence']);
+    if (!evidence) {
+      errors.push({
+        category: 'unrun_required_check',
+        message: 'Plan contains Complexity / Performance Budget but execution.md is missing Complexity / Performance Evidence.',
+      });
+    } else {
+      if (!/(duration|timing|ms|sec|seconds|rows|row count|explain|n\+1|hot path)/i.test(evidence)) {
+        errors.push({
+          category: 'insufficient_evidence',
+          message: 'Complexity / Performance Evidence must include timing, row-count, EXPLAIN, N+1, or hot-path evidence.',
+        });
+      }
+    }
+  }
+
+  if (hasAnySection(planSections, ['optimization strategy', 'optimization review strategy', 'optimization gate'])) {
+    const strategy = readAnySection(planSections, ['optimization strategy', 'optimization review strategy', 'optimization gate']);
+    const requiresEvidence = /\bO[23]\b/.test(strategy);
+    const evidence = readAnySection(executionSections, ['optimization review evidence', 'optimization evidence', 'optimizer evidence']);
+    if (requiresEvidence && !evidence) {
+      errors.push({
+        category: 'unrun_required_check',
+        message: 'Plan contains O2/O3 Optimization Strategy but execution.md is missing Optimization Review Evidence.',
+      });
+    } else if (requiresEvidence && !/(review|finding|n\+1|repeated scan|nested|o\(n\^2\)|timing|rows|row count|benchmark|explain|defer|pass|no obvious)/i.test(evidence)) {
+      errors.push({
+        category: 'insufficient_evidence',
+        message: 'Optimization Review Evidence must include hot-path review, anti-pattern findings, timing/rows/benchmark/EXPLAIN, or explicit deferred findings.',
+      });
+    }
+  }
+
+  if (hasAnySection(planSections, ['production rollout gate', 'production rollout', 'rollout gate', 'deployment gate'])) {
+    const evidence = readAnySection(executionSections, ['production rollout evidence', 'rollout evidence', 'deployment evidence']);
+    if (!evidence) {
+      errors.push({
+        category: 'missing_evidence',
+        message: 'Plan contains Production Rollout Gate but execution.md is missing Production Rollout Evidence.',
+      });
+    } else if (!/(rollback|env|environment|deploy|post-?deploy|logs|metrics|smoke|monitor|evidence)/i.test(evidence)) {
+      errors.push({
+        category: 'insufficient_evidence',
+        message: 'Production Rollout Evidence must include rollback/env/deploy/post-deploy logs, metrics, smoke, or monitor evidence.',
+      });
+    }
+  }
+
+  if (hasAnySection(planSections, ['source sync / provider gate', 'source sync provider gate', 'source sync gate', 'provider gate'])) {
+    const evidence = readAnySection(executionSections, ['source sync / provider evidence', 'source sync evidence', 'provider evidence']);
+    if (!evidence) {
+      errors.push({
+        category: 'missing_evidence',
+        message: 'Plan contains Source Sync / Provider Gate but execution.md is missing Source Sync / Provider Evidence.',
+      });
+    } else if (!/(idempot|retry|pagination|rate limit|raw record|coverage|parity|count|sample|partial failure|replay|audit)/i.test(evidence)) {
+      errors.push({
+        category: 'insufficient_evidence',
+        message: 'Source Sync / Provider Evidence must include idempotency, retry/pagination/rate-limit, raw-record, coverage/parity, sample, replay, or failure-handling evidence.',
+      });
+    }
+  }
+
+  return errors;
+}
+
+function hasAnySection(sections, names) {
+  return Boolean(readAnySection(sections, names));
+}
+
+function readAnySection(sections, names) {
+  const normalizedNames = new Set(names.map(normalizeHeading));
+  for (const [title, body] of sections.entries()) {
+    if (normalizedNames.has(normalizeHeading(title))) {
+      return body.trim();
+    }
+  }
+  return '';
+}
+
+function buildCheckerQuestions({ risk, qualityGates }) {
+  const questions = [
+    'Does the active slice have clear allowed and forbidden scope?',
+    'Are the planned files/modules aligned with current repo boundaries?',
+    'Does the verification plan prove the actual user/operational outcome, not only command success?',
+  ];
+  if (qualityGates.uiRequired) {
+    questions.push('Will the UI Acceptance Scenarios catch the concrete regressions a user would care about?');
+  }
+  if (qualityGates.complexityRequired) {
+    questions.push('Does the plan avoid N+1 queries, repeated scans, heavy render work and unbounded backfills on hot paths?');
+  }
+  if (qualityGates.optimizationRequired) {
+    questions.push('Does the Optimization Strategy prevent likely inefficient implementation before Execute, with a bounded O-tier budget and stop rule?');
+  }
+  if (qualityGates.productionRolloutRequired) {
+    questions.push('Does the plan include production/runtime rollback, environment and post-deploy evidence?');
+  }
+  if (qualityGates.sourceSyncProviderRequired || risk.riskTriggers.includes('worker-queue')) {
+    questions.push('Does the plan bound provider/worker execution by scope, window, credentials, queue ownership and coverage evidence?');
+  }
+  return questions;
+}
+
+function normalizeRoots(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((root) => String(root).replace(/^\.\/+/, '').replace(/\/+$/, '')).filter(Boolean);
+}
+
+function matchesAnyRoot(ref, roots) {
+  return roots.some((root) => ref === root || ref.startsWith(`${root}/`));
+}
+
+function titleFromPlaybookName(name) {
+  const acronyms = new Map([
+    ['ui', 'UI'],
+  ]);
+  return name
+    .split('-')
+    .map((part) => acronyms.get(part) || `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(' ');
+}
+
+function excerptMarkdown(content, maxChars = 1600) {
+  const normalized = normalizeMarkdownBody(content || '');
+  if (!normalized) {
+    return '- Empty playbook.';
+  }
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxChars).trimEnd()}\n\n[...truncated...]`;
+}
+
+export function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function normalizeHeading(value) {
+  return value
+    .replace(/[`*_]/g, '')
+    .replace(/^\s*\d+[\).\s-]+/, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+export function normalizeMarkdownBody(value) {
+  return normalizeLineEndings(value)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function normalizeLineEndings(value) {
+  return value.replace(/\r\n?/g, '\n');
+}
+
+export function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function sha256Json(value) {
+  return sha256(JSON.stringify(value));
+}
+
+export function escapeTableCell(value) {
+  return value.replace(/\|/g, '\\|').replace(/\n/g, ' ').trim();
+}
+
+export function relativePath(filePath) {
+  return path.relative(repoRoot, filePath).split(path.sep).join('/');
+}
+
+export function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}