@besales/ops-framework 0.1.0

package/bin/supervisor-turn.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  appendOrchestrationLog,
+  getFlag,
+  parseCliArgs,
+  readStatusStage,
+  resolveTaskDir,
+} from './lib/check-context-utils.mjs';
+import {
+  classifyFeedback,
+  recordFeedback,
+} from './intake-execution-feedback.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    fail('Usage: ops-agent supervisor-turn <TASK-id-or-task-path> <message> [--from-file path] [--source user|assistant|tool] [--no-intake]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const source = getFlag(args, 'source', 'user');
+    const message = readMessage(args);
+    const shouldIntake = !args.flags.has('no-intake') && message.trim().length > 0;
+    const classification = shouldIntake
+      ? recordFeedback({ taskDir, taskId, rawFeedback: message, source })
+      : classifyFeedback(message || 'status check');
+
+    appendOrchestrationLog(taskDir, {
+      event: 'supervisor_turn',
+      taskId,
+      source,
+      intakeRecorded: shouldIntake,
+      classification: classification.classification,
+      supervisorDecision: classification.supervisorDecision,
+    });
+
+    const stage = readStatusStage(taskDir) || 'unknown';
+    const contract = buildTurnContract({ taskId, stage, classification, intakeRecorded: shouldIntake });
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify(contract, null, 2));
+      return;
+    }
+    console.log(renderTurnContract(contract));
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function readMessage(args) {
+  const fromFile = getFlag(args, 'from-file');
+  if (fromFile) {
+    return fs.readFileSync(path.resolve(fromFile), 'utf8');
+  }
+  return args.positional.slice(1).join(' ');
+}
+
+export function buildTurnContract({ taskId, stage, classification, intakeRecorded }) {
+  return {
+    task: taskId,
+    stage,
+    supervisor: 'active',
+    intakeRecorded,
+    classification: classification.classification,
+    supervisorDecision: classification.supervisorDecision,
+    allowedNow: allowedNowForClassification(classification),
+    notAllowedNow: notAllowedNowForClassification(classification),
+    nextStep: nextStepForClassification(classification),
+  };
+}
+
+export function renderTurnContract(contract) {
+  return [
+    `TASK: \`${contract.task}\``,
+    `STAGE: \`${contract.stage}\``,
+    `SUPERVISOR: ${contract.supervisor}`,
+    `FEEDBACK INTAKE: ${contract.intakeRecorded ? `recorded (${contract.classification})` : 'not_recorded'}`,
+    `ALLOWED NOW: ${contract.allowedNow}`,
+    `NOT ALLOWED NOW: ${contract.notAllowedNow}`,
+    '',
+    `Следующий шаг: ${contract.nextStep}`,
+  ].join('\n');
+}
+
+function allowedNowForClassification(classification) {
+  switch (classification.supervisorDecision) {
+    case 'stay_current':
+      return 'continue current stage while keeping feedback available for retrospective/learning';
+    case 'stay_execute':
+      return 'continue Execute within approved scope';
+    case 'return_plan':
+      return 'update plan.md and run fresh Check before implementation continues';
+    case 'return_research':
+      return 'refresh research.md before updating plan/check';
+    case 'return_brief':
+      return 'reset task brief/scope before research/plan/check';
+    case 'human_arbitration':
+      return 'ask human to resolve the tradeoff before continuing';
+    default:
+      return 'pause for human triage';
+  }
+}
+
+function notAllowedNowForClassification(classification) {
+  if (classification.requiresFreshCheck) {
+    return 'continue implementation as if the previous Check/Human Gate still applies';
+  }
+  if (classification.supervisorDecision === 'human_triage') {
+    return 'guess intent or mutate task artifacts beyond feedback intake';
+  }
+  return 'drop the feedback on the floor or answer without task header/footer';
+}
+
+function nextStepForClassification(classification) {
+  switch (classification.classification) {
+    case 'acknowledgement':
+      return 'proceed with the previously proposed supervisor action.';
+    case 'learning_capture':
+      return 'continue current stage and include the event in retrospective and learning candidates.';
+    case 'within_approved_scope':
+      return 'continue Execute within the approved plan.';
+    case 'plan_patch_required':
+      return 'return to Plan, update plan.md, run fresh Check and request a new Human Gate if needed.';
+    case 'research_required':
+      return 'return to Research before Plan/Check.';
+    case 'brief_reset_required':
+      return 'return to Brief before Research/Plan/Check.';
+    case 'human_arbitration_required':
+      return 'ask human to resolve the decision explicitly.';
+    default:
+      return 'ask human to classify the message before continuing.';
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}

package/bin/supervisor-turn.test.mjs

@@ -0,0 +1,72 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  buildTurnContract,
+  renderTurnContract,
+} from './supervisor-turn.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const opsAgentBin = path.join(__dirname, 'ops-agent.mjs');
+
+describe('supervisor turn router', () => {
+  it('records a task message and prints the mandatory turn contract', () => {
+    const taskId = 'TASK-999-supervisor-turn';
+    const taskDir = path.join(process.cwd(), 'ops', 'agent-pipeline', 'tasks', taskId);
+    fs.mkdirSync(taskDir, { recursive: true });
+    fs.writeFileSync(path.join(taskDir, 'brief.md'), '# Brief\n\nTest.\n');
+    fs.writeFileSync(path.join(taskDir, 'research.md'), '# Research\n\n## Findings\n\n- `docs/example.md`\n');
+    fs.writeFileSync(path.join(taskDir, 'plan.md'), '# Plan\n\n## Затронутые модули и файлы\n\n- `docs/example.md`\n');
+    fs.writeFileSync(path.join(taskDir, 'status.md'), [
+      '# Status',
+      '',
+      '## Текущий этап',
+      '',
+      'Execute',
+      '',
+      '## Feedback intake',
+      '',
+      '- `feedback.md`: no_events',
+    ].join('\n'));
+    fs.writeFileSync(path.join(taskDir, 'orchestration-log.md'), '# Orchestration Log\n\n## Entries\n');
+
+    const result = spawnSync(process.execPath, [
+      opsAgentBin,
+      'supervisor-turn',
+      taskId,
+      'Да, давай.',
+    ], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain(`TASK: \`${taskId}\``);
+    expect(result.stdout).toContain('SUPERVISOR: active');
+    expect(result.stdout).toContain('FEEDBACK INTAKE: recorded (acknowledgement)');
+    expect(result.stdout).toContain('Следующий шаг: proceed with the previously proposed supervisor action.');
+
+    const feedback = fs.readFileSync(path.join(taskDir, 'feedback.md'), 'utf8');
+    expect(feedback).toContain('- Classification: acknowledgement');
+    const log = fs.readFileSync(path.join(taskDir, 'orchestration-log.md'), 'utf8');
+    expect(log).toContain('supervisor_turn');
+  });
+
+  it('renders a contract from classification metadata', () => {
+    const contract = buildTurnContract({
+      taskId: 'TASK-999-contract',
+      stage: 'Plan',
+      intakeRecorded: true,
+      classification: {
+        classification: 'plan_patch_required',
+        supervisorDecision: 'return_plan',
+        requiresFreshCheck: true,
+      },
+    });
+
+    expect(renderTurnContract(contract)).toContain('NOT ALLOWED NOW: continue implementation as if the previous Check/Human Gate still applies');
+  });
+});

package/bin/task-manifest.mjs

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import {
+  appendOrchestrationLog,
+  parseCliArgs,
+  resolveTaskDir,
+} from './lib/check-context-utils.mjs';
+import {
+  buildTaskManifest,
+  validateManifest,
+  writeTaskManifest,
+} from './lib/task-manifest-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/task-manifest.mjs <TASK-id-or-task-path> [--check] [--json]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const manifest = buildTaskManifest({ taskDir });
+    const errors = validateManifest(manifest);
+
+    if (!args.flags.has('check')) {
+      writeTaskManifest(taskDir, manifest);
+      appendOrchestrationLog(taskDir, `task manifest updated; phase=${manifest.phase}; mode=${manifest.mode}; gatesOk=${errors.length === 0}`);
+    }
+
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify({ ok: errors.length === 0, taskId, manifest, errors }, null, 2));
+    } else {
+      console.log(`Task manifest for ${taskId}: ${errors.length === 0 ? 'ok' : 'needs attention'}`);
+      console.log(`- mode: ${manifest.mode}`);
+      console.log(`- phase: ${manifest.phase}`);
+      console.log(`- risk: ${manifest.context.riskProfile} (${manifest.context.riskTriggers.join(', ') || 'none'})`);
+      if (errors.length > 0) {
+        console.log('Issues:');
+        for (const error of errors) {
+          console.log(`- ${error}`);
+        }
+      }
+    }
+
+    process.exit(errors.length === 0 ? 0 : 1);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/task-metrics.mjs

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import {
+  parseCliArgs,
+  readTaskFile,
+  resolveTaskDir,
+} from './lib/check-context-utils.mjs';
+import { computeTaskMetricsFromLog } from './lib/task-metrics-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/task-metrics.mjs <TASK-id-or-task-path> [--json]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const metrics = {
+      taskId,
+      ...computeTaskMetricsFromLog(readTaskFile(taskDir, 'orchestration-log.md')),
+    };
+
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify(metrics, null, 2));
+      return;
+    }
+
+    console.log(`Task metrics for ${taskId}`);
+    console.log(`- events: ${metrics.events}`);
+    console.log(`- spanHours: ${metrics.spanHours}`);
+    console.log(`- externalVerifierRuns: ${metrics.externalVerifierRuns}`);
+    console.log(`- returnToPlan: ${metrics.returnToPlan}`);
+    console.log(`- returnToExecute: ${metrics.returnToExecute}`);
+    console.log(`- deterministicPreverifyReturns: ${metrics.deterministicPreverifyReturns}`);
+    console.log(`- processBreaks: ${metrics.processBreaks}`);
+    console.log(`- loopSignals: ${metrics.loopSignals}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/transition.mjs

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import {
+  appendOrchestrationLog,
+  parseCliArgs,
+  resolveTaskDir,
+  updateStatus,
+} from './lib/check-context-utils.mjs';
+import {
+  normalizePhase,
+  transitionTaskManifest,
+  writeTaskManifest,
+} from './lib/task-manifest-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  const phaseArg = args.positional[1] || args.flags.get('to') || args.flags.get('phase');
+  if (!taskArg || !phaseArg) {
+    fail('Usage: node ops/agent-pipeline/bin/transition.mjs <TASK-id-or-task-path> <plan|check|execute|verify|human_gate|retrospective> [--json]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const targetPhase = normalizePhase(phaseArg);
+    const result = transitionTaskManifest({ taskDir, targetPhase });
+
+    if (!result.ok) {
+      if (args.flags.has('json')) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Transition blocked for ${taskId} -> ${targetPhase}`);
+        for (const issue of result.issues) {
+          console.log(`- ${issue.category}: ${issue.message}`);
+        }
+      }
+      process.exit(1);
+    }
+
+    writeTaskManifest(taskDir, result.manifest);
+    updateStatus(taskDir, {
+      stage: displayPhase(targetPhase),
+      supervisorAction: `Transitioned to ${targetPhase} via agent:transition.`,
+      nextStep: nextStepForPhase(targetPhase),
+      humanApproval: targetPhase === 'human_gate' ? 'yes' : 'no',
+    });
+    appendOrchestrationLog(taskDir, `transitioned to ${targetPhase}; mode=${result.manifest.mode}; manifest updated`);
+
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Transitioned ${taskId} -> ${targetPhase}`);
+      console.log(`- mode: ${result.manifest.mode}`);
+      console.log(`- risk: ${result.manifest.context.riskProfile}`);
+    }
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function nextStepForPhase(phase) {
+  switch (phase) {
+    case 'check':
+      return 'Run independent check or refresh check artifacts.';
+    case 'execute':
+      return 'Implement the checked plan and record execution evidence.';
+    case 'verify':
+      return 'Run Verify after execution evidence is complete.';
+    case 'human_gate':
+      return 'Ask human to review final gate artifacts and approve closeout.';
+    case 'retrospective':
+      return 'Capture retrospective lessons and delivery metrics.';
+    default:
+      return 'Continue planning until gates are ready.';
+  }
+}
+
+function displayPhase(phase) {
+  return {
+    plan: 'Plan',
+    check: 'Check',
+    execute: 'Execute',
+    verify: 'Verify',
+    human_gate: 'Human Gate',
+    retrospective: 'Retrospective',
+  }[phase] || phase;
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();