@besales/ops-framework 0.1.0

package/bin/guard-task.mjs

@@ -0,0 +1,384 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  isCheckContextCurrent,
+  normalizeMarkdownBody,
+  pipelineRoot,
+  projectContext,
+  readJsonFile,
+  readStatusStage,
+  readTaskFile,
+  repoRoot,
+  resolveTaskDir,
+  sha256,
+  validateExecutionEvidenceForPlan,
+} from './lib/check-context-utils.mjs';
+
+function main() {
+  const taskArg = process.argv[2];
+  if (!taskArg) {
+    fail('Usage: node ops/agent-pipeline/bin/guard-task.mjs <TASK-id-or-task-path>');
+  }
+
+  const errors = [];
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    validateContext(taskDir, errors);
+    validatePlanCheckFreshness(taskDir, errors);
+    validateStructuredArtifacts(taskArg, errors);
+    validateCheckResult(taskDir, errors);
+    validateVerifyResult(taskDir, errors);
+    validateHumanGateSummary(taskDir, errors);
+    validateFeedback(taskDir, errors);
+    validateExecutionEvidence(taskDir, errors);
+    validateStatusSync(taskDir, errors);
+
+    if (errors.length > 0) {
+      console.error(`Agent pipeline guard failed for ${taskId}:`);
+      for (const error of errors) {
+        console.error(`- ${error}`);
+      }
+      process.exit(1);
+    }
+
+    console.log(`Agent pipeline guard ok for ${taskId}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function validateHumanGateSummary(taskDir, errors) {
+  const stage = readStatusStage(taskDir);
+  if (stage !== 'Human Gate') {
+    return;
+  }
+  const summaryPath = path.join(taskDir, 'human-gate-summary.md');
+  if (!fs.existsSync(summaryPath)) {
+    errors.push('human-gate-summary.md is missing at Human Gate.');
+    return;
+  }
+  const summary = readTaskFile(taskDir, 'human-gate-summary.md');
+  for (const heading of [
+    '## Decision Needed',
+    '## Problem We Are Solving',
+    '## Approved Plan Summary',
+    '## Execution Approach',
+    '## Human Gate Requirements',
+    '## What Approval Allows',
+    '## What Remains Forbidden',
+  ]) {
+    if (!summary.includes(heading)) {
+      errors.push(`human-gate-summary.md is missing section: ${heading}.`);
+    }
+  }
+}
+
+function validatePlanCheckFreshness(taskDir, errors) {
+  const planPath = path.join(taskDir, 'plan.md');
+  const checkPath = path.join(taskDir, 'check.md');
+  if (!fs.existsSync(planPath)) {
+    errors.push('plan.md is missing.');
+    return;
+  }
+  if (!fs.existsSync(checkPath)) {
+    errors.push('check.md is missing.');
+    return;
+  }
+  const planMtime = fs.statSync(planPath).mtimeMs;
+  const checkMtime = fs.statSync(checkPath).mtimeMs;
+  if (planMtime > checkMtime) {
+    errors.push('plan.md is newer than check.md; fresh Check is required.');
+  }
+}
+
+function validateContext(taskDir, errors) {
+  const contextPath = path.join(taskDir, 'check-context.json');
+  if (!fs.existsSync(contextPath)) {
+    errors.push('check-context.json is missing.');
+    return;
+  }
+  const state = isCheckContextCurrent(taskDir);
+  if (!state.current) {
+    errors.push(state.error ? `check-context.json is stale or invalid: ${state.error.message}` : 'check-context.json is stale.');
+  }
+}
+
+function validateStructuredArtifacts(taskArg, errors) {
+  const validatorPath = path.join(pipelineRoot, 'bin', 'validate-check-artifacts.mjs');
+  const result = spawnSync(process.execPath, [validatorPath, taskArg], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    errors.push(`structured artifact validator failed: ${output}`);
+  }
+}
+
+function validateCheckResult(taskDir, errors) {
+  const resultPath = path.join(taskDir, 'check.result.json');
+  if (!fs.existsSync(resultPath)) {
+    errors.push('check.result.json is missing.');
+    return;
+  }
+
+  let result;
+  try {
+    result = readJsonFile(resultPath);
+  } catch (error) {
+    errors.push(`check.result.json is invalid JSON: ${error.message}`);
+    return;
+  }
+
+  if (result.verdict !== 'ready_for_human_gate') {
+    errors.push(`Human Gate is blocked by check.result.json verdict=${result.verdict}.`);
+  }
+  if (result.verdict === 'return_to_plan' && !fs.existsSync(path.join(taskDir, 'check-resolution.md'))) {
+    errors.push('check-resolution.md is missing after return_to_plan.');
+  }
+  if (result.verdict === 'checker_failed') {
+    errors.push(`checker_failed requires remediation before Human Gate: ${result.failureReason}.`);
+  }
+  if (result.verdict === 'human_arbitration_required') {
+    errors.push('Human Arbitration must resolve before Human Gate.');
+  }
+}
+
+function validateVerifyResult(taskDir, errors) {
+  const stage = readStatusStage(taskDir);
+  const resultPath = path.join(taskDir, 'verify.result.json');
+  const stagesRequiringVerifyResult = new Set([
+    'Retrospective',
+    'Closeout Audit',
+    'Human Closeout Gate',
+    'Closed',
+    'Accepted',
+    'Ready To Pause',
+  ]);
+
+  if (!fs.existsSync(resultPath)) {
+    if (stagesRequiringVerifyResult.has(stage)) {
+      errors.push('verify.result.json is missing before Retrospective/Closeout.');
+    }
+    return;
+  }
+
+  let result;
+  try {
+    result = readJsonFile(resultPath);
+  } catch (error) {
+    errors.push(`verify.result.json is invalid JSON: ${error.message}`);
+    return;
+  }
+
+  const allowedVerdicts = new Set([
+    'pass',
+    'pass_with_notes',
+    'return_to_execute',
+    'return_to_plan',
+    'human_arbitration_required',
+    'verifier_failed',
+  ]);
+  const allowedFailureReasons = new Set([
+    'provider_unavailable',
+    'invalid_json',
+    'schema_validation_failed',
+    'context_overflow',
+    'repo_read_limit_exceeded',
+    'memory_snapshot_mismatch',
+    'timeout',
+    'unknown',
+  ]);
+  const allowedSeverities = new Set(['blocking', 'non_blocking', 'question']);
+  const allowedCategories = new Set([
+    'plan_mismatch',
+    'implementation_gap',
+    'regression_risk',
+    'insufficient_evidence',
+    'unrun_required_check',
+    'scope_drift',
+    'runtime_risk',
+    'ui_verification_gap',
+    'documentation_gap',
+    'execution_record_gap',
+    'verifier_failure',
+  ]);
+  const externalVerifierProviders = readExternalVerifierProviders();
+  const verificationMode = result.verificationMode;
+
+  if (result.schemaVersion !== 1) {
+    errors.push('verify.result.json schemaVersion must be 1.');
+  }
+  if (!allowedVerdicts.has(result.verdict)) {
+    errors.push(`verify.result.json has invalid verdict: ${result.verdict}.`);
+  }
+  if (result.verdict === 'verifier_failed' && !allowedFailureReasons.has(result.failureReason)) {
+    errors.push(`verify.result.json has invalid failureReason: ${result.failureReason}.`);
+  }
+  if (result.verdict !== 'verifier_failed' && result.failureReason !== null) {
+    errors.push('verify.result.json failureReason must be null unless verdict=verifier_failed.');
+  }
+  if (['pass', 'pass_with_notes'].includes(result.verdict)) {
+    if (!['internal_supervisor', 'external_cli'].includes(verificationMode)) {
+      errors.push('verify.result.json pass/pass_with_notes requires verificationMode="internal_supervisor" or "external_cli".');
+    }
+    if (verificationMode === 'internal_supervisor' && result.verifierProvider !== 'supervisor') {
+      errors.push(`verify.result.json internal_supervisor requires verifierProvider="supervisor", got ${result.verifierProvider}.`);
+    }
+    if (verificationMode === 'external_cli' && !externalVerifierProviders.has(result.verifierProvider)) {
+      errors.push(`verify.result.json external_cli verifierProvider must be an external CLI provider (${[...externalVerifierProviders].join(', ')}), got ${result.verifierProvider}.`);
+    }
+    if (!result.verifierRunId || typeof result.verifierRunId !== 'string') {
+      errors.push('verify.result.json pass/pass_with_notes requires verifierRunId.');
+    }
+  }
+
+  const planPath = path.join(taskDir, 'plan.md');
+  if (fs.existsSync(planPath)) {
+    const planSha = sha256(normalizeMarkdownBody(fs.readFileSync(planPath, 'utf8')));
+    if (result.planSha && result.planSha !== planSha) {
+      errors.push('verify.result.json is stale relative to plan.md.');
+    }
+  }
+
+  const executionPath = path.join(taskDir, 'execution.md');
+  if (fs.existsSync(executionPath)) {
+    const executionSha = sha256(normalizeMarkdownBody(fs.readFileSync(executionPath, 'utf8')));
+    if (result.executionSha && result.executionSha !== executionSha) {
+      errors.push('verify.result.json is stale relative to execution.md.');
+    }
+  }
+
+  const findings = Array.isArray(result.findings) ? result.findings : [];
+  if (!Array.isArray(result.findings)) {
+    errors.push('verify.result.json findings must be an array.');
+  }
+  findings.forEach((finding, index) => {
+    const expectedId = `V-${String(index + 1).padStart(3, '0')}`;
+    if (finding.id !== expectedId) {
+      errors.push(`verify.result.json finding id must be stable/sequential: expected ${expectedId}, got ${finding.id}.`);
+    }
+    if (!allowedSeverities.has(finding.severity)) {
+      errors.push(`verify.result.json finding ${finding.id || index + 1} has invalid severity.`);
+    }
+    if (!allowedCategories.has(finding.claimCategory)) {
+      errors.push(`verify.result.json finding ${finding.id || index + 1} has invalid claimCategory.`);
+    }
+  });
+
+  const blockingFindings = findings.filter((finding) => finding.severity === 'blocking').length;
+  const nonBlockingFindings = findings.filter((finding) => finding.severity === 'non_blocking').length;
+  const questions = findings.filter((finding) => finding.severity === 'question').length;
+  if (result.counts?.blockingFindings !== blockingFindings) {
+    errors.push('verify.result.json counts.blockingFindings does not match findings[].');
+  }
+  if (result.counts?.nonBlockingFindings !== nonBlockingFindings) {
+    errors.push('verify.result.json counts.nonBlockingFindings does not match findings[].');
+  }
+  if (result.counts?.questions !== questions) {
+    errors.push('verify.result.json counts.questions does not match findings[].');
+  }
+
+  if (['pass', 'pass_with_notes'].includes(result.verdict) && blockingFindings > 0) {
+    errors.push('verify.result.json cannot pass with blocking findings.');
+  }
+  if (result.readyForRetrospective !== ['pass', 'pass_with_notes'].includes(result.verdict)) {
+    errors.push('verify.result.json readyForRetrospective disagrees with verdict.');
+  }
+
+  if (stagesRequiringVerifyResult.has(stage) && !['pass', 'pass_with_notes'].includes(result.verdict)) {
+    errors.push(`Retrospective/Closeout is blocked by verify.result.json verdict=${result.verdict}.`);
+  }
+}
+
+function readExternalVerifierProviders() {
+  const configPath = projectContext.projectAgentsConfigPath || path.join(projectContext.configRoot, 'default-agents.json');
+  const config = fs.existsSync(configPath) ? readJsonFile(configPath) : {};
+  const providerNames = Object.keys(config.checkerProviders || {});
+  const cliProviders = providerNames.filter((providerName) => providerName.endsWith('-cli') || providerName === 'custom-cli');
+  const configuredVerifierProvider = config.verifier?.provider;
+  if (configuredVerifierProvider && !cliProviders.includes(configuredVerifierProvider)) {
+    cliProviders.push(configuredVerifierProvider);
+  }
+  return new Set(cliProviders);
+}
+
+function validateFeedback(taskDir, errors) {
+  const feedbackPath = path.join(taskDir, 'feedback.md');
+  const legacyFeedbackPath = path.join(taskDir, 'execution-feedback.md');
+  if (!fs.existsSync(feedbackPath) && !fs.existsSync(legacyFeedbackPath)) {
+    return;
+  }
+  const feedback = [
+    readTaskFile(taskDir, 'feedback.md'),
+    readTaskFile(taskDir, 'execution-feedback.md'),
+  ].join('\n');
+  if (/Classification:\s*(pending|todo|unclassified|\.\.\.)/i.test(feedback) || !/Classification:\s*\w+/i.test(feedback)) {
+    errors.push('Task has unclassified feedback event. Run ops-agent intake-feedback or classify feedback before continuing.');
+  }
+}
+
+function validateStatusSync(taskDir, errors) {
+  const resultPath = path.join(taskDir, 'check.result.json');
+  if (!fs.existsSync(resultPath)) {
+    return;
+  }
+  const result = readJsonFile(resultPath);
+  const stage = readStatusStage(taskDir);
+  if (!stage) {
+    errors.push('status.md current stage is empty.');
+    return;
+  }
+
+  const allowedStages = {
+    ready_for_human_gate: new Set([
+      'Human Gate',
+      'Execute',
+      'Verify',
+      'Retrospective',
+      'Closeout Audit',
+      'Human Closeout Gate',
+      'Closed',
+      'Accepted',
+      'Ready To Pause',
+    ]),
+    return_to_plan: new Set(['Plan']),
+    human_arbitration_required: new Set(['Human Arbitration']),
+    checker_failed: new Set(['Check']),
+  }[result.verdict];
+
+  if (allowedStages && !allowedStages.has(stage)) {
+    errors.push(`status.md stage "${stage}" disagrees with check verdict ${result.verdict}.`);
+  }
+}
+
+function validateExecutionEvidence(taskDir, errors) {
+  const stage = readStatusStage(taskDir);
+  const stagesAfterExecute = new Set([
+    'Verify',
+    'Retrospective',
+    'Closeout Audit',
+    'Human Closeout Gate',
+    'Closed',
+    'Accepted',
+    'Ready To Pause',
+  ]);
+  if (!stagesAfterExecute.has(stage)) {
+    return;
+  }
+
+  const plan = readTaskFile(taskDir, 'plan.md');
+  const execution = readTaskFile(taskDir, 'execution.md');
+  for (const issue of validateExecutionEvidenceForPlan({ planContent: plan, executionContent: execution })) {
+    errors.push(issue.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/hash-task-artifacts.mjs

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  computePlanFingerprint,
+  normalizeMarkdownBody,
+  parseCliArgs,
+  resolveTaskDir,
+  sha256,
+} from './lib/check-context-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    throw new Error('Usage: node ops/agent-pipeline/bin/hash-task-artifacts.mjs <TASK-id-or-task-path> [file ...]');
+  }
+
+  const taskDir = resolveTaskDir(taskArg);
+  const fileNames = args.positional.length > 1 ? args.positional.slice(1) : ['plan.md', 'execution.md'];
+  const artifacts = fileNames.map((fileName) => hashTaskFile(taskDir, fileName));
+
+  console.log(JSON.stringify({
+    taskId: path.basename(taskDir),
+    hashMode: 'pipeline-normalized-markdown',
+    note: 'These hashes match run-verify/guard-task markdown normalization; raw shasum is intentionally different.',
+    artifacts,
+  }, null, 2));
+}
+
+function hashTaskFile(taskDir, fileName) {
+  const filePath = path.join(taskDir, fileName);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Task artifact not found: ${fileName}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  return {
+    fileName,
+    normalizedSha: sha256(normalizeMarkdownBody(content)),
+    ...(fileName === 'plan.md' ? { semanticPlanSha: computePlanFingerprint(content).planSha } : {}),
+  };
+}
+
+main();

package/bin/init-project.mjs

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import {
+  getFlag,
+  parseCliArgs,
+} from './lib/check-context-utils.mjs';
+import {
+  initProject,
+  summarizeChanges,
+} from './lib/bootstrap-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const projectRoot = process.cwd();
+  const projectName = getFlag(args, 'project-name', path.basename(projectRoot));
+  const opsRoot = getFlag(args, 'ops-root', 'ops');
+  const installScripts = args.flags.has('install-scripts');
+  const frameworkPackage = getFlag(args, 'framework-package', null);
+  const frameworkVersion = getFlag(args, 'framework-version', null);
+  const force = args.flags.has('force');
+
+  try {
+    const result = initProject({
+      projectRoot,
+      projectName,
+      opsRoot,
+      installScripts,
+      frameworkPackage,
+      frameworkVersion,
+      force,
+    });
+    const summary = summarizeChanges(result.changes);
+
+    console.log(`Ops project initialized: ${result.projectName}`);
+    console.log(`- projectRoot: ${result.projectRoot}`);
+    console.log(`- opsRoot: ${result.opsRoot}`);
+    console.log(`- created: ${summary.created}`);
+    console.log(`- existing: ${summary.existing}`);
+    console.log(`- overwritten: ${summary.overwritten}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/intake-execution-feedback.mjs

@@ -0,0 +1,207 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  appendOrchestrationLog,
+  getFlag,
+  parseCliArgs,
+  readStatusStage,
+  readTaskFile,
+  resolveTaskDir,
+  updateStatus,
+  writeTaskFile,
+} from './lib/check-context-utils.mjs';
+
+export function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    fail('Usage: ops-agent intake-feedback <TASK-id-or-task-path> <feedback> [--from-file path] [--source user|assistant|tool]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const dryRun = getFlag(args, 'dry-run', false) === true;
+    const source = getFlag(args, 'source', 'user');
+    const rawFeedback = readFeedback(args);
+    if (!rawFeedback.trim()) {
+      throw new Error('Feedback is empty.');
+    }
+
+    const classification = classifyFeedback(rawFeedback);
+    if (dryRun) {
+      console.log(`Feedback dry-run for ${taskId}`);
+      console.log(`- classification: ${classification.classification}`);
+      console.log(`- supervisorDecision: ${classification.supervisorDecision}`);
+      console.log(`- requiresFreshCheck: ${classification.requiresFreshCheck ? 'yes' : 'no'}`);
+      return;
+    }
+
+    recordFeedback({ taskDir, taskId, rawFeedback, classification, source });
+
+    console.log(`Feedback recorded for ${taskId}`);
+    console.log(`- classification: ${classification.classification}`);
+    console.log(`- supervisorDecision: ${classification.supervisorDecision}`);
+    console.log(`- requiresFreshCheck: ${classification.requiresFreshCheck ? 'yes' : 'no'}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function readFeedback(args) {
+  const fromFile = getFlag(args, 'from-file');
+  if (fromFile) {
+    return fs.readFileSync(path.resolve(fromFile), 'utf8');
+  }
+  return args.positional.slice(1).join(' ');
+}
+
+export function classifyFeedback(rawFeedback) {
+  const text = rawFeedback.toLowerCase();
+
+  if (/^(да[\s,]+давай|да|давай|ок|окей|yes|yep|go|go ahead|approved|approve|подтверждаю|согласен)[\s.,!?]*$/i.test(rawFeedback.trim())) {
+    return classificationResult('acknowledgement', 'stay_current', false, false, 'Human acknowledged or approved the current supervisor-proposed next step.');
+  }
+  if (/\b(feedback|memory|playbook|learning|retrospective|framework|supervisor|status|log|artifact|фидбэк|памят|плейбук|лернинг|ретроспектив|фреймворк|супервизор|статус|лог|артефакт)\b/.test(text)) {
+    return classificationResult('learning_capture', 'stay_current', false, false, 'Feedback should be captured for retrospective, memory or playbook learning without changing current task scope by itself.');
+  }
+  if (/\b(scope|цель|outcome|dashboard|data model|canonical|lifecycle|новая задача|новый контур|границ[аы])\b/.test(text)) {
+    return classificationResult('brief_reset_required', 'return_brief', true, true, 'Feedback changes task frame or product/data-model boundary.');
+  }
+  if (/\b(unclear|unknown|research|исслед|проверь факты|provider behavior|production data|impact|непонятно)\b/.test(text)) {
+    return classificationResult('research_required', 'return_research', true, true, 'Feedback reveals missing facts.');
+  }
+  if (/\b(risk appetite|tradeoff|trade-off|accept risk|architecture decision|реши|выбрать|компромисс|риск)\b/.test(text)) {
+    return classificationResult('human_arbitration_required', 'human_arbitration', false, false, 'Feedback requires human risk or architecture arbitration.');
+  }
+  if (/\b(plan|implementation|file|module|verification|api|route|endpoint|worker|queue|schema|migration|auth|deploy|runtime|status|log|artifact|retrospective|memory|playbook|план|файл|модуль|провер|реализац|воркер|схем|миграц|статус|лог|артефакт|ретроспектив|памят|плейбук)\b/.test(text)) {
+    return classificationResult('plan_patch_required', 'return_plan', true, true, 'Feedback changes implementation path or verification surface.');
+  }
+  if (/\b(copy|text|label|typo|spacing|цвет|текст|опечат|лейбл|полиш|polish)\b/.test(text)) {
+    return classificationResult('within_approved_scope', 'stay_execute', false, false, 'Feedback appears to be within approved execution scope.');
+  }
+
+  return classificationResult('human_triage_required', 'human_triage', false, false, 'Feedback is ambiguous and needs classification.');
+}
+
+function classificationResult(classification, supervisorDecision, requiresFreshCheck, requiresNewHumanGate, rationale) {
+  return {
+    classification,
+    supervisorDecision,
+    requiresFreshCheck,
+    requiresNewHumanGate,
+    rationale,
+  };
+}
+
+export function appendFeedbackEvent({ taskDir, taskId, rawFeedback, classification, source = 'user' }) {
+  const fileName = 'feedback.md';
+  const statusStage = readStatusStage(taskDir) || 'unknown';
+  const existing = readTaskFile(taskDir, fileName).trimEnd() || '# Feedback Log';
+  const eventNumber = (existing.match(/^## Feedback Event /gm) || []).length + 1;
+  const receivedAt = new Date().toISOString();
+  const event = [
+    `## Feedback Event ${eventNumber}`,
+    '',
+    `- Received at: ${receivedAt}`,
+    `- Source: ${source}`,
+    `- Raw feedback: ${rawFeedback.replace(/\n/g, ' ')}`,
+    `- Current stage when received: ${statusStage}`,
+    `- Classification: ${classification.classification}`,
+    `- Rationale: ${classification.rationale}`,
+    '- Affected artifacts: plan.md, research.md, brief.md, execution.md, verify.md',
+    `- Supervisor decision: ${classification.supervisorDecision}`,
+    `- Requires fresh Check: ${classification.requiresFreshCheck ? 'yes' : 'no'}`,
+    `- Requires new Human Gate: ${classification.requiresNewHumanGate ? 'yes' : 'no'}`,
+    '',
+    '```json',
+    JSON.stringify({
+      event: 'feedback',
+      taskId,
+      receivedAt,
+      source,
+      rawFeedback,
+      stageWhenReceived: statusStage,
+      classification: classification.classification,
+      rationale: classification.rationale,
+      supervisorDecision: classification.supervisorDecision,
+      requiresFreshCheck: classification.requiresFreshCheck,
+      requiresNewHumanGate: classification.requiresNewHumanGate,
+    }, null, 2),
+    '```',
+  ].join('\n');
+
+  writeTaskFile(taskDir, fileName, `${existing}\n\n${event}\n`);
+}
+
+export function recordFeedback({ taskDir, taskId = path.basename(taskDir), rawFeedback, classification = classifyFeedback(rawFeedback), source = 'user' }) {
+  appendFeedbackEvent({ taskDir, taskId, rawFeedback, classification, source });
+  updateStatusForFeedback(taskDir, classification);
+  appendOrchestrationLog(taskDir, {
+    event: 'feedback_intake',
+    taskId,
+    source,
+    classification: classification.classification,
+    supervisorDecision: classification.supervisorDecision,
+    requiresFreshCheck: classification.requiresFreshCheck,
+    requiresNewHumanGate: classification.requiresNewHumanGate,
+  });
+  return classification;
+}
+
+export function updateStatusForFeedback(taskDir, classification) {
+  const currentStage = readStatusStage(taskDir) || 'Human Triage';
+  const stageByDecision = {
+    stay_execute: 'Execute',
+    stay_current: currentStage,
+    return_plan: 'Plan',
+    return_research: 'Research',
+    return_brief: 'Brief',
+    human_triage: 'Human Triage',
+    human_arbitration: 'Human Arbitration',
+  };
+
+  updateStatus(taskDir, {
+    stage: stageByDecision[classification.supervisorDecision] || 'Human Triage',
+    routingDecision: `feedback:${classification.classification}`,
+    feedbackIntake: '- `feedback.md`: classified',
+    supervisorAction: classification.rationale,
+    nextStep: nextStepForClassification(classification),
+    humanApproval: classification.requiresNewHumanGate ? 'yes, after fresh Check' : 'no',
+  });
+}
+
+function nextStepForClassification(classification) {
+  if (classification.classification === 'within_approved_scope') {
+    return 'Continue Execute within approved plan.';
+  }
+  if (classification.classification === 'learning_capture') {
+    return 'Keep current task stage; include feedback in retrospective and learning candidates.';
+  }
+  if (classification.classification === 'acknowledgement') {
+    return 'Proceed with the current supervisor-proposed next step.';
+  }
+  if (classification.classification === 'plan_patch_required') {
+    return 'Planner updates plan.md, then fresh Check and Human Gate before Execute resumes.';
+  }
+  if (classification.classification === 'research_required') {
+    return 'Researcher updates research.md, then Planner updates plan.md and fresh Check runs.';
+  }
+  if (classification.classification === 'brief_reset_required') {
+    return 'Update brief.md before Research, Plan, fresh Check and Human Gate.';
+  }
+  if (classification.classification === 'human_arbitration_required') {
+    return 'Human decides unresolved tradeoff before implementation continues.';
+  }
+  return 'Human classifies feedback before implementation continues.';
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}