@besales/ops-framework 0.1.0

package/bin/lib/task-manifest-utils.test.mjs

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  buildTaskManifest,
+  preflightTask,
+  transitionTaskManifest,
+  updateLoopDetector,
+  writeTaskManifest,
+} from './task-manifest-utils.mjs';
+
+const tempDirs = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('task manifest utilities', () => {
+  it('creates a manifest from a minimal task folder', () => {
+    const taskDir = createTask({
+      plan: [
+        '# Plan',
+        '',
+        '## Risk tier and execution budget',
+        '',
+        '- Speed mode: `Fast`',
+        '',
+        '## Затронутые модули и файлы',
+        '',
+        '- `docs/example.md`',
+      ].join('\n'),
+    });
+
+    const manifest = buildTaskManifest({ taskDir, now: '2026-05-21T00:00:00.000Z' });
+
+    expect(manifest.taskId).toMatch(/^TASK-/);
+    expect(manifest.mode).toBe('fast');
+    expect(manifest.phase).toBe('plan');
+    expect(manifest.context.riskProfile).toBe('low');
+    expect(manifest.gates.uiAcceptance.required).toBe(false);
+  });
+
+  it('updates phase timestamps without losing existing manual fields', () => {
+    const taskDir = createTask();
+    writeTaskManifest(taskDir, {
+      schemaVersion: 1,
+      taskId: path.basename(taskDir),
+      mode: 'standard',
+      phase: 'plan',
+      timestamps: {
+        createdAt: '2026-05-20T00:00:00.000Z',
+        updatedAt: '2026-05-20T00:00:00.000Z',
+        phaseChangedAt: '2026-05-20T00:00:00.000Z',
+      },
+      manualNote: 'keep me',
+    });
+
+    const result = transitionTaskManifest({
+      taskDir,
+      targetPhase: 'check',
+      now: '2026-05-21T00:00:00.000Z',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.manifest.phase).toBe('check');
+    expect(result.manifest.timestamps.createdAt).toBe('2026-05-20T00:00:00.000Z');
+    expect(result.manifest.timestamps.phaseChangedAt).toBe('2026-05-21T00:00:00.000Z');
+  });
+
+  it('blocks execute transition when required UI gate is incomplete', () => {
+    const taskDir = createTask({
+      plan: [
+        '# Plan',
+        '',
+        '## Затронутые модули и файлы',
+        '',
+        '- `web/app/src/features/runs/page.tsx`',
+      ].join('\n'),
+    });
+
+    const result = transitionTaskManifest({ taskDir, targetPhase: 'execute' });
+
+    expect(result.ok).toBe(false);
+    expect(result.issues.map((issue) => issue.category)).toContain('plan_quality_gate');
+  });
+
+  it('allows fast mode preflight when no applicable gates are triggered', () => {
+    const taskDir = createTask({
+      plan: [
+        '# Plan',
+        '',
+        '## Risk tier and execution budget',
+        '',
+        '- Speed mode: `Fast`',
+        '',
+        '## Затронутые модули и файлы',
+        '',
+        '- `docs/example.md`',
+      ].join('\n'),
+    });
+
+    const result = preflightTask({ taskDir, targetPhase: 'check' });
+
+    expect(result.ok).toBe(true);
+    expect(result.manifest.mode).toBe('fast');
+  });
+
+  it('blocks verify preflight when required execution evidence is missing', () => {
+    const taskDir = createTask({
+      plan: [
+        '# Plan',
+        '',
+        '## Complexity / Performance Budget',
+        '',
+        '- Hot paths: read model.',
+        '- Expected data size / row counts: 10000 rows.',
+        '- Complexity risks: N+1.',
+        '- Budget / stop rule: < 2 seconds.',
+      ].join('\n'),
+      execution: '# Execution\n\n## Краткое summary\n\nImplemented.',
+    });
+
+    const result = preflightTask({ taskDir, targetPhase: 'verify' });
+
+    expect(result.ok).toBe(false);
+    expect(result.issues.some((issue) => issue.message.includes('Complexity / Performance Evidence'))).toBe(true);
+    expect(result.issues.map((issue) => issue.category)).toContain('execution_ledger_missing');
+  });
+
+  it('blocks verify preflight when execution ledger changed files are not in execution evidence', () => {
+    const taskDir = createTask({
+      execution: [
+        '# Execution',
+        '',
+        '## Измененные файлы',
+        '',
+        '| File | Change summary | Planned item / reason |',
+        '| --- | --- | --- |',
+        '| `docs/example.md` | docs | planned |',
+      ].join('\n'),
+    });
+    fs.writeFileSync(path.join(taskDir, 'execution-ledger.json'), JSON.stringify({
+      schemaVersion: 1,
+      git: {
+        changedFiles: [
+          { path: 'docs/example.md', isTaskArtifact: false, isOpsFrameworkFile: false },
+          { path: 'web/app/src/features/runs/page.tsx', isTaskArtifact: false, isOpsFrameworkFile: false },
+        ],
+        unrelatedDirtyFiles: [],
+      },
+    }, null, 2));
+
+    const result = preflightTask({ taskDir, targetPhase: 'verify' });
+
+    expect(result.ok).toBe(false);
+    expect(result.issues).toContainEqual({
+      category: 'dirty_evidence_mismatch',
+      message: 'execution.md does not mention changed files from execution-ledger.json: web/app/src/features/runs/page.tsx.',
+    });
+  });
+
+  it('detects repeated checker/verifier return reasons for consolidated remediation', () => {
+    const first = updateLoopDetector({
+      results: [
+        {
+          source: 'checker',
+          value: {
+            verdict: 'return_to_plan',
+            createdAt: '2026-05-21T00:00:00.000Z',
+            findings: [{ claim: 'Plan misses UI Acceptance Evidence for UI-001.' }],
+          },
+        },
+      ],
+    });
+    const second = updateLoopDetector({
+      existing: first,
+      results: [
+        {
+          source: 'verifier',
+          value: {
+            verdict: 'return_to_execute',
+            createdAt: '2026-05-21T01:00:00.000Z',
+            findings: [{ claim: 'Plan misses UI Acceptance Evidence for UI-002.' }],
+          },
+        },
+      ],
+    });
+
+    expect(second.requiresConsolidatedRemediation).toBe(true);
+    expect(second.repeatedReasons[0].count).toBe(2);
+  });
+});
+
+function createTask({ plan = defaultPlan(), execution = '' } = {}) {
+  const taskDir = fs.mkdtempSync(path.join(os.tmpdir(), 'TASK-999-manifest-'));
+  tempDirs.push(taskDir);
+  fs.writeFileSync(path.join(taskDir, 'brief.md'), '# Brief\n\nTest task.\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.trim()}\n`);
+  fs.writeFileSync(path.join(taskDir, 'status.md'), '# Status\n\n## Текущий этап\n\nplan\n');
+  if (execution) {
+    fs.writeFileSync(path.join(taskDir, 'execution.md'), `${execution.trim()}\n`);
+  }
+  return taskDir;
+}
+
+function defaultPlan() {
+  return [
+    '# Plan',
+    '',
+    '## Затронутые модули и файлы',
+    '',
+    '- `docs/example.md`',
+  ].join('\n');
+}

package/bin/lib/task-metrics-utils.mjs

@@ -0,0 +1,63 @@
+export function computeTaskMetricsFromLog(logContent) {
+  const lines = String(logContent || '').split('\n');
+  const events = lines
+    .map(parseOrchestrationEvent)
+    .filter(Boolean)
+    .sort((a, b) => a.at.getTime() - b.at.getTime());
+  const text = lines.join('\n');
+  const externalVerifierRuns = events.filter((event) => /external CLI verifier/i.test(event.body));
+  const returnToExecute = countMatches(text, /return_to_execute/g);
+  const returnToPlan = countMatches(text, /return_to_plan/g);
+  const processBreaks = countMatches(text, /process break|stage discipline issue/gi);
+  const deterministicPreverifyReturns = countMatches(text, /deterministic pre-verify evidence gate returned return_to_execute/gi);
+  const spanMs = events.length > 1 ? events.at(-1).at.getTime() - events[0].at.getTime() : 0;
+
+  return {
+    events: events.length,
+    firstEventAt: events[0]?.at.toISOString() || null,
+    lastEventAt: events.at(-1)?.at.toISOString() || null,
+    spanHours: Number((spanMs / 36e5).toFixed(2)),
+    externalVerifierRuns: externalVerifierRuns.length,
+    returnToExecute,
+    returnToPlan,
+    processBreaks,
+    deterministicPreverifyReturns,
+    loopSignals: returnToExecute + returnToPlan + processBreaks,
+  };
+}
+
+export function parseOrchestrationEvent(line) {
+  const match = /^-\s*`([^`]+)`\s*—\s*(.*)$/.exec(line || '');
+  if (!match) {
+    return null;
+  }
+  const at = parseTaskTimestamp(match[1]);
+  if (!at) {
+    return null;
+  }
+  return {
+    at,
+    body: match[2],
+  };
+}
+
+export function parseTaskTimestamp(value) {
+  let normalized = String(value || '').trim();
+  if (!normalized) {
+    return null;
+  }
+  normalized = normalized.replace(' WITA', '+08:00');
+  if (/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+    normalized += 'T00:00:00+08:00';
+  } else if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(normalized)) {
+    normalized = `${normalized.replace(' ', 'T')}:00+08:00`;
+  } else if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(normalized)) {
+    normalized = `${normalized.replace(' ', 'T')}+08:00`;
+  }
+  const date = new Date(normalized);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function countMatches(value, pattern) {
+  return (String(value || '').match(pattern) || []).length;
+}

package/bin/lib/task-metrics-utils.test.mjs

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import {
+  computeTaskMetricsFromLog,
+  parseTaskTimestamp,
+} from './task-metrics-utils.mjs';
+
+describe('task metrics utils', () => {
+  it('parses WITA and ISO timestamps', () => {
+    expect(parseTaskTimestamp('2026-05-15 13:40 WITA')?.toISOString()).toBe('2026-05-15T05:40:00.000Z');
+    expect(parseTaskTimestamp('2026-05-15T07:08:33.731Z')?.toISOString()).toBe('2026-05-15T07:08:33.731Z');
+  });
+
+  it('computes loop and verifier metrics from orchestration log', () => {
+    const log = [
+      '# Orchestration Log',
+      '',
+      '## Entries',
+      '',
+      '- `2026-05-15 13:40 WITA` — started',
+      '- `2026-05-15T07:08:33.731Z` — external CLI verifier completed via codex-cli; verdict=return_to_execute',
+      '- `2026-05-15T07:14:51.887Z` — external CLI verifier completed via codex-cli; verdict=pass_with_notes',
+      '- `2026-05-15T07:16:00.000Z` — deterministic pre-verify evidence gate returned return_to_execute; findings=1',
+      '- `2026-05-15T07:20:00.000Z` — Checker returned return_to_plan',
+      '- `2026-05-15T07:30:00.000Z` — process break corrected',
+    ].join('\n');
+
+    expect(computeTaskMetricsFromLog(log)).toEqual({
+      events: 6,
+      firstEventAt: '2026-05-15T05:40:00.000Z',
+      lastEventAt: '2026-05-15T07:30:00.000Z',
+      spanHours: 1.83,
+      externalVerifierRuns: 2,
+      returnToExecute: 2,
+      returnToPlan: 1,
+      processBreaks: 1,
+      deterministicPreverifyReturns: 1,
+      loopSignals: 4,
+    });
+  });
+});

package/bin/lib/test-setup.mjs

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-framework-test-project-'));
+const memoryRoot = path.join(root, 'ops', 'agent-pipeline', 'memory');
+fs.mkdirSync(path.join(root, 'ops'), { recursive: true });
+fs.mkdirSync(memoryRoot, { recursive: true });
+fs.writeFileSync(path.join(root, 'ops', 'project.ops.yaml'), `
+name: TestProject
+ops:
+  legacyPipelineDir: ops/agent-pipeline
+  tasksDir: ops/agent-pipeline/tasks
+  memoryDir: ops/agent-pipeline/memory
+  cacheDir: ops/agent-pipeline/cache
+  playbooksDir: ops/agent-pipeline/playbooks
+risk:
+  uiRoots:
+    - web/app
+  backendRoots:
+    - services/api
+  workerRoots:
+    - workers/backend
+`);
+
+for (const fileName of [
+  'project-context-digest.md',
+  'module-boundaries.md',
+  'standards-digest.md',
+  'recurring-failures.md',
+  'domain-glossary.md',
+  'checker-rubric.md',
+]) {
+  fs.writeFileSync(path.join(memoryRoot, fileName), `# ${fileName}\n\nTest memory.\n`);
+}
+
+process.chdir(root);

package/bin/new-task.mjs

@@ -0,0 +1,42 @@
+import {
+  getFlag,
+  parseCliArgs,
+} from './lib/check-context-utils.mjs';
+import {
+  createTask,
+  summarizeChanges,
+} from './lib/bootstrap-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskId = args.positional[0];
+  if (!taskId) {
+    fail('Usage: ops-agent new-task <TASK-000-slug> --title "Task title" [--owner Supervisor] [--force]');
+  }
+
+  try {
+    const result = createTask({
+      projectRoot: process.cwd(),
+      taskId,
+      title: getFlag(args, 'title', null),
+      owner: getFlag(args, 'owner', 'Supervisor'),
+      force: args.flags.has('force'),
+    });
+    const summary = summarizeChanges(result.changes);
+
+    console.log(`Ops task created: ${result.taskId}`);
+    console.log(`- taskDir: ${result.taskDir}`);
+    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/ops-agent.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const binRoot = path.dirname(__filename);
+
+const COMMANDS = new Map([
+  ['init', 'init-project.mjs'],
+  ['new-task', 'new-task.mjs'],
+  ['manifest', 'task-manifest.mjs'],
+  ['preflight', 'preflight.mjs'],
+  ['transition', 'transition.mjs'],
+  ['build-check-context', 'build-check-context.mjs'],
+  ['validate-check-artifacts', 'validate-check-artifacts.mjs'],
+  ['estimate-llm-input', 'estimate-llm-input.mjs'],
+  ['quality-gates', 'quality-gates.mjs'],
+  ['run-check', 'run-check.mjs'],
+  ['run-verify', 'run-verify.mjs'],
+  ['hash-task-artifacts', 'hash-task-artifacts.mjs'],
+  ['build-execution-ledger', 'build-execution-ledger.mjs'],
+  ['task-metrics', 'task-metrics.mjs'],
+  ['run-plan-check-loop', 'run-plan-check-loop.mjs'],
+  ['supervisor-turn', 'supervisor-turn.mjs'],
+  ['intake-feedback', 'intake-execution-feedback.mjs'],
+  ['intake-execution-feedback', 'intake-execution-feedback.mjs'],
+  ['guard-task', 'guard-task.mjs'],
+  ['memory-candidates', 'learning-loop.mjs'],
+  ['learning-index', 'learning-loop.mjs'],
+  ['learning-review', 'learning-loop.mjs'],
+  ['update-memory', 'learning-loop.mjs'],
+  ['learning-audit', 'learning-loop.mjs'],
+  ['learning-report', 'learning-loop.mjs'],
+  ['test/self-test', null],
+]);
+
+function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(command ? 0 : 1);
+  }
+  if (command === '--version' || command === '-v') {
+    console.log('0.1.0');
+    return;
+  }
+  if (!COMMANDS.has(command)) {
+    console.error(`Unknown ops-agent command: ${command}`);
+    printHelp();
+    process.exit(1);
+  }
+  if (command === 'test/self-test') {
+    console.log('ops-agent self-test: ok');
+    return;
+  }
+
+  const script = path.join(binRoot, COMMANDS.get(command));
+  const scriptArgs = COMMANDS.get(command) === 'learning-loop.mjs' ? [command, ...args] : args;
+  const result = spawnSync(process.execPath, [script, ...scriptArgs], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    console.error(`Failed to run ${command}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}
+
+function printHelp() {
+  console.log('Usage: ops-agent <command> [args]');
+  console.log('');
+  console.log('Commands:');
+  for (const name of COMMANDS.keys()) {
+    console.log(`  ${name}`);
+  }
+}
+
+main();

package/bin/preflight.mjs

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import {
+  parseCliArgs,
+  resolveTaskDir,
+} from './lib/check-context-utils.mjs';
+import {
+  normalizePhase,
+  preflightTask,
+} 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/preflight.mjs <TASK-id-or-task-path> [--target execute|verify|human_gate] [--json]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const targetPhase = normalizePhase(args.flags.get('target') || args.flags.get('phase') || 'execute');
+    const result = preflightTask({ taskDir, targetPhase });
+
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Preflight for ${taskId} -> ${targetPhase}: ${result.ok ? 'ok' : 'blocked'}`);
+      console.log(`- mode: ${result.manifest.mode}`);
+      console.log(`- current phase: ${result.manifest.phase}`);
+      console.log(`- check context current: ${result.manifest.context.checkContextCurrent ? 'yes' : 'no'}`);
+      if (result.warnings?.length > 0) {
+        console.log('Warnings:');
+        for (const warning of result.warnings) {
+          console.log(`- ${warning}`);
+        }
+      }
+      if (result.issues.length > 0) {
+        console.log('Issues:');
+        for (const issue of result.issues) {
+          console.log(`- ${issue.category}: ${issue.message}`);
+        }
+      }
+    }
+
+    process.exit(result.ok ? 0 : 1);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();