@besales/ops-framework 0.1.0

package/bin/run-plan-check-loop.mjs

@@ -0,0 +1,392 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  appendOrchestrationLog,
+  getFlag,
+  parseCliArgs,
+  pipelineRoot,
+  readAgentsConfig,
+  readJsonFile,
+  readTaskFile,
+  repoRoot,
+  resolveTaskDir,
+  parseMarkdownSections,
+  updateStatus,
+  writeTaskFile,
+} from './lib/check-context-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    fail('Usage: node ops/agent-pipeline/bin/run-plan-check-loop.mjs <TASK-id-or-task-path> [--checker-provider openai] [--checker-model model]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const config = readAgentsConfig();
+    let iteration = 0;
+    let lastResult = null;
+    const maxIterations = resolveMaxIterations(taskDir, config);
+
+    while (iteration < maxIterations) {
+      iteration += 1;
+      const startedAt = Date.now();
+      const runResult = runCheck(taskArg, args);
+      lastResult = readCheckResult(taskDir);
+      const elapsedMs = Date.now() - startedAt;
+
+      appendIterationLog({
+        taskDir,
+        taskId,
+        iteration,
+        result: lastResult,
+        elapsedMs,
+        maxIterations,
+      });
+
+      routeAfterCheck({ taskDir, result: lastResult, iteration, maxIterations });
+
+      if (lastResult.verdict === 'ready_for_human_gate') {
+        console.log(`Plan/Check loop ready for Human Gate after ${iteration} iteration(s).`);
+        return;
+      }
+      if (lastResult.verdict === 'human_arbitration_required') {
+        fail(`Plan/Check loop routed to Human Arbitration after ${iteration} iteration(s).`);
+      }
+      if (lastResult.verdict === 'checker_failed') {
+        fail(`Checker failed with ${lastResult.failureReason}. Stage routed according to failure reason.`);
+      }
+      if (lastResult.verdict === 'return_to_plan') {
+        if (!fs.existsSync(path.join(taskDir, 'check-resolution.md'))) {
+          fail('Checker returned return_to_plan. Planner must update plan.md and write check-resolution.md before the loop can continue.');
+        }
+      }
+
+      if (runResult.status !== 0 && lastResult.verdict !== 'return_to_plan') {
+        fail(`run-check exited with ${runResult.status}.`);
+      }
+    }
+
+    updateStatus(taskDir, {
+      stage: 'Human Arbitration',
+      routingDecision: `max_iterations_reached:${maxIterations}`,
+      checkVerdict: lastResult?.verdict || 'unknown',
+      supervisorAction: 'Plan/Check loop reached max iterations.',
+      nextStep: 'Human Arbitration: resolve Planner/Checker non-convergence.',
+      humanApproval: 'yes',
+    });
+    appendOrchestrationLog(taskDir, {
+      event: 'plan_check_max_iterations',
+      taskId,
+      maxIterations,
+      verdict: lastResult?.verdict || null,
+    });
+    fail(`Plan/Check loop reached max iterations (${maxIterations}).`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function runCheck(taskArg, args) {
+  const runCheckPath = path.join(pipelineRoot, 'bin', 'run-check.mjs');
+  const childArgs = [runCheckPath, taskArg];
+  for (const flagName of ['checker-provider', 'checker-model']) {
+    const value = getFlag(args, flagName);
+    if (value) {
+      childArgs.push(`--${flagName}`, value);
+    }
+  }
+
+  const result = spawnSync(process.execPath, childArgs, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  return result;
+}
+
+function readCheckResult(taskDir) {
+  const resultPath = path.join(taskDir, 'check.result.json');
+  if (!fs.existsSync(resultPath)) {
+    throw new Error('run-check did not produce check.result.json.');
+  }
+  return readJsonFile(resultPath);
+}
+
+function resolveMaxIterations(taskDir, config) {
+  const contextPath = path.join(taskDir, 'check-context.json');
+  const riskProfile = fs.existsSync(contextPath)
+    ? readJsonFile(contextPath).riskProfile
+    : config.planCheckLoop?.defaultRiskProfile || 'medium';
+  return config.planCheckLoop?.maxIterations?.[riskProfile] || 3;
+}
+
+function appendIterationLog({ taskDir, taskId, iteration, result, elapsedMs, maxIterations }) {
+  const expectedOutputTokens = 3000;
+  const estimatedInputTokens = readJsonFile(path.join(taskDir, 'check-context.json')).contextBudgetTokens;
+  const resolutionCounts = readResolutionCounts(taskDir);
+  const estimatedTotalTokens = iteration * (estimatedInputTokens + expectedOutputTokens);
+  const derivedBudgetTokens = maxIterations * (estimatedInputTokens + expectedOutputTokens);
+  appendOrchestrationLog(taskDir, {
+    event: 'plan_check_iteration',
+    taskId,
+    iteration,
+    maxIterations,
+    riskProfile: result.riskProfile,
+    planSha: result.planSha,
+    memorySha: result.memorySha,
+    checkerProvider: result.checkerProvider,
+    checkerModel: result.checkerModel,
+    verdict: result.verdict,
+    failureReason: result.failureReason,
+    blockingFindings: result.blockingFindings,
+    acceptedCount: resolutionCounts.accepted,
+    partiallyAcceptedCount: resolutionCounts.partiallyAccepted,
+    rejectedWithEvidence: resolutionCounts.rejectedWithEvidence,
+    needsResearch: resolutionCounts.needsResearch,
+    needsHumanTriage: 0,
+    needsHumanDecision: resolutionCounts.needsHumanDecision,
+    elapsedMs,
+    estimatedInputTokens,
+    estimatedOutputTokens,
+    estimatedTotalTokens,
+    derivedBudgetTokens,
+    derivedBudgetWarning: estimatedTotalTokens >= derivedBudgetTokens,
+  });
+}
+
+function readResolutionCounts(taskDir) {
+  const defaults = {
+    accepted: 0,
+    partiallyAccepted: 0,
+    rejectedWithEvidence: 0,
+    needsResearch: 0,
+    needsHumanDecision: 0,
+  };
+  const resolutionPath = path.join(taskDir, 'check-resolution.md');
+  if (!fs.existsSync(resolutionPath)) {
+    return defaults;
+  }
+
+  const markdown = readTaskFile(taskDir, 'check-resolution.md');
+  const markerIndex = markdown.indexOf('## Structured Resolution');
+  if (markerIndex === -1) {
+    return defaults;
+  }
+  const match = /```json\s*([\s\S]*?)```/.exec(markdown.slice(markerIndex));
+  if (!match) {
+    return defaults;
+  }
+
+  try {
+    const resolution = JSON.parse(match[1]);
+    for (const response of resolution.responses || []) {
+      if (response.decision === 'accepted') {
+        defaults.accepted += 1;
+      }
+      if (response.decision === 'partially_accepted') {
+        defaults.partiallyAccepted += 1;
+      }
+      if (response.decision === 'rejected' && Array.isArray(response.evidenceRefs) && response.evidenceRefs.length > 0) {
+        defaults.rejectedWithEvidence += 1;
+      }
+      if (response.decision === 'needs_research') {
+        defaults.needsResearch += 1;
+      }
+      if (response.decision === 'needs_human_decision') {
+        defaults.needsHumanDecision += 1;
+      }
+    }
+  } catch {
+    return defaults;
+  }
+  return defaults;
+}
+
+function routeAfterCheck({ taskDir, result, iteration, maxIterations }) {
+  if (result.verdict === 'ready_for_human_gate') {
+    const summary = buildHumanGateSummary(taskDir, result);
+    writeTaskFile(taskDir, 'human-gate-summary.md', summary);
+    updateStatus(taskDir, {
+      stage: 'Human Gate',
+      routingDecision: 'ready_for_human_gate',
+      planSha: `\`${result.planSha}\``,
+      memorySha: `\`${result.memorySha}\``,
+      checkVerdict: '`ready_for_human_gate`',
+      checkResult: '- `check.result.json`: current',
+      humanGateSummary: '- `human-gate-summary.md`: present',
+      supervisorAction: `Plan/Check loop converged at iteration ${iteration}/${maxIterations}.`,
+      nextStep: 'Ask human approval before Execute.',
+      humanApproval: 'yes',
+    });
+    console.log('\n--- Human Gate Summary ---\n');
+    console.log(summary);
+    return;
+  }
+
+  if (result.verdict === 'return_to_plan') {
+    updateStatus(taskDir, {
+      stage: 'Plan',
+      routingDecision: 'return_to_plan',
+      planSha: `\`${result.planSha}\``,
+      memorySha: `\`${result.memorySha}\``,
+      checkVerdict: '`return_to_plan`',
+      checkResult: '- `check.result.json`: current',
+      checkResolution: '- `check-resolution.md`: missing | present',
+      supervisorAction: 'Checker returned blockers; Planner must resolve each blocking finding.',
+      nextStep: 'Planner updates artifacts and writes check-resolution.md, then fresh Check.',
+      humanApproval: 'no',
+    });
+    return;
+  }
+
+  if (result.verdict === 'human_arbitration_required') {
+    updateStatus(taskDir, {
+      stage: 'Human Arbitration',
+      routingDecision: 'human_arbitration_required',
+      checkVerdict: '`human_arbitration_required`',
+      supervisorAction: 'Checker routed unresolved tradeoff to Human Arbitration.',
+      nextStep: 'Human decides unresolved finding or risk appetite.',
+      humanApproval: 'yes',
+    });
+    return;
+  }
+
+  if (result.verdict === 'checker_failed') {
+    updateStatus(taskDir, {
+      stage: 'Check',
+      routingDecision: `checker_failed:${result.failureReason}`,
+      checkVerdict: '`checker_failed`',
+      supervisorAction: `Checker failed with ${result.failureReason}.`,
+      nextStep: nextStepForFailure(result.failureReason),
+      humanApproval: result.failureReason === 'context_overflow' || result.failureReason === 'repo_read_limit_exceeded' ? 'yes' : 'no',
+    });
+  }
+}
+
+function buildHumanGateSummary(taskDir, result) {
+  const taskId = path.basename(taskDir);
+  const briefSections = parseMarkdownSections(readTaskFile(taskDir, 'brief.md'));
+  const planSections = parseMarkdownSections(readTaskFile(taskDir, 'plan.md'));
+  const problem = firstNonEmpty([
+    briefSections.get('Задача'),
+    briefSections.get('Task'),
+    briefSections.get('Зачем это нужно'),
+    briefSections.get('Why'),
+  ]);
+  const planSummary = firstNonEmpty([
+    planSections.get('Goal'),
+    planSections.get('Цель'),
+    planSections.get('Implementation Steps'),
+    planSections.get('Шаги реализации'),
+  ]);
+  const executionApproach = firstNonEmpty([
+    planSections.get('Dependency Order'),
+    planSections.get('Implementation Steps'),
+    planSections.get('Verification and replay plan'),
+  ]);
+  const humanRequirements = firstNonEmpty([
+    planSections.get('Verification and replay plan'),
+    planSections.get('Known Risks'),
+    planSections.get('Constraints'),
+  ]);
+
+  return [
+    '# Human Gate Summary',
+    '',
+    '## Task',
+    '',
+    `\`${taskId}\``,
+    '',
+    '## Decision Needed',
+    '',
+    'Approve moving from `Human Gate` to `Execute`, or ask a clarifying question before approval.',
+    '',
+    '## Problem We Are Solving',
+    '',
+    truncateMarkdown(problem, 900),
+    '',
+    '## Approved Plan Summary',
+    '',
+    truncateMarkdown(planSummary, 1200),
+    '',
+    '## Execution Approach',
+    '',
+    truncateMarkdown(executionApproach, 1200),
+    '',
+    '## Human Gate Requirements',
+    '',
+    truncateMarkdown(humanRequirements, 1200),
+    '',
+    '## What Approval Allows',
+    '',
+    '- Executor may start implementation according to `plan.md`.',
+    '- Executor may touch only modules and artifacts covered by the approved plan.',
+    '- Executor may run local verification commands required by the plan.',
+    '',
+    '## What Remains Forbidden',
+    '',
+    '- Do not run non-local replay/backfill without separate Human Gate approval.',
+    '- Do not apply Prisma schema changes outside local development without explicit approval.',
+    '- Do not expand scope beyond `brief.md` / `plan.md` without returning to Brief/Plan and fresh Check.',
+    '',
+    '## Check Result',
+    '',
+    `- Verdict: \`${result.verdict}\``,
+    `- Blocking findings: \`${result.blockingFindings}\``,
+    `- Plan SHA: \`${result.planSha}\``,
+    `- Memory SHA: \`${result.memorySha}\``,
+    '',
+    '## Next Step',
+    '',
+    'Human approves Execute or asks a clarifying question.',
+  ].join('\n');
+}
+
+function firstNonEmpty(values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+  }
+  return 'n/a';
+}
+
+function truncateMarkdown(value, maxLength) {
+  const normalized = String(value || 'n/a').trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxLength).trimEnd()}\n\n...`;
+}
+
+function nextStepForFailure(failureReason) {
+  if (failureReason === 'provider_unavailable' || failureReason === 'timeout') {
+    return 'Retry once or use secondary checker provider.';
+  }
+  if (failureReason === 'invalid_json' || failureReason === 'schema_validation_failed') {
+    return 'Rerun checker once with schema repair instruction, then Human Arbitration if repeated.';
+  }
+  if (failureReason === 'context_overflow' || failureReason === 'repo_read_limit_exceeded') {
+    return 'Shrink context or ask human to approve deeper check budget.';
+  }
+  if (failureReason === 'memory_snapshot_mismatch') {
+    return 'Rebuild check context with fresh memorySha.';
+  }
+  return 'Inspect checker failure and decide retry or Human Arbitration.';
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();