@besales/ops-framework 0.1.0

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

@@ -0,0 +1,512 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  computeTaskContextInputs,
+  isCheckContextCurrent,
+  projectContext,
+  parseMarkdownSections,
+  readJsonFile,
+  readStatusStage,
+  readTaskFile,
+  validateExecutionEvidenceForPlan,
+} from './check-context-utils.mjs';
+
+export const TASK_MANIFEST_FILE = 'task-manifest.json';
+export const ALLOWED_TASK_MODES = ['fast', 'standard', 'strict'];
+export const ALLOWED_TASK_PHASES = ['plan', 'check', 'execute', 'verify', 'human_gate', 'retrospective'];
+export const LOOP_REMEDIATION_THRESHOLD = 2;
+
+export function buildTaskManifest({ taskDir, now = new Date().toISOString(), existing = readExistingManifest(taskDir) } = {}) {
+  const taskId = path.basename(taskDir);
+  const preserved = preserveManualManifestFields(existing);
+  const inputs = computeTaskContextInputs(taskDir);
+  const executionContent = readTaskFile(taskDir, 'execution.md');
+  const evidenceIssues = validateExecutionEvidenceForPlan({
+    planContent: inputs.taskArtifacts.get('plan.md'),
+    executionContent,
+  });
+  const checkContextState = isCheckContextCurrent(taskDir);
+  const checkResult = readOptionalJson(taskDir, 'check.result.json');
+  const verifyResult = readOptionalJson(taskDir, 'verify.result.json');
+  const inferredPhase = normalizePhase(existing?.phase || inferPhaseFromTask(taskDir));
+  const mode = normalizeTaskMode(existing?.mode || extractTaskMode(inputs.taskArtifacts.get('plan.md')) || 'standard');
+  const previousPhase = existing?.phase || null;
+  const loopDetector = updateLoopDetector({
+    existing: existing?.loopDetector,
+    results: [
+      { source: 'checker', value: checkResult },
+      { source: 'verifier', value: verifyResult },
+    ],
+  });
+
+  return {
+    ...preserved,
+    schemaVersion: 1,
+    taskId,
+    mode,
+    phase: inferredPhase,
+    gates: {
+      uiAcceptance: {
+        required: inputs.qualityGates.uiRequired,
+        planComplete: inputs.qualityGates.uiAcceptance.present,
+        evidenceRequired: hasPlanGate(inputs.taskArtifacts.get('plan.md'), ['ui acceptance scenarios', 'ui acceptance', 'ui scenarios']),
+        evidenceComplete: !evidenceIssues.some((issue) => issue.category === 'ui_verification_gap'),
+      },
+      complexityPerformance: {
+        required: inputs.qualityGates.complexityRequired,
+        planComplete: inputs.qualityGates.complexityBudget.present,
+        evidenceRequired: hasPlanGate(inputs.taskArtifacts.get('plan.md'), ['complexity / performance budget', 'complexity performance budget', 'performance budget', 'complexity budget']),
+        evidenceComplete: !evidenceIssues.some((issue) => ['unrun_required_check', 'insufficient_evidence'].includes(issue.category)),
+      },
+      optimizationReview: {
+        required: inputs.qualityGates.optimizationRequired,
+        tier: inputs.qualityGates.optimizationTier,
+        planComplete: inputs.qualityGates.optimizationStrategy.present,
+        evidenceRequired: hasPlanGate(inputs.taskArtifacts.get('plan.md'), ['optimization strategy', 'optimization review strategy', 'optimization gate']),
+        evidenceComplete: !evidenceIssues.some((issue) => issue.message.includes('Optimization Review Evidence')),
+      },
+      productionRollout: {
+        required: inputs.qualityGates.productionRolloutRequired,
+        planComplete: inputs.qualityGates.productionRollout.present,
+        evidenceRequired: hasPlanGate(inputs.taskArtifacts.get('plan.md'), ['production rollout gate', 'production rollout', 'rollout gate', 'deployment gate']),
+        evidenceComplete: !evidenceIssues.some((issue) => issue.message.includes('Production Rollout')),
+      },
+      sourceSyncProvider: {
+        required: inputs.qualityGates.sourceSyncProviderRequired,
+        planComplete: inputs.qualityGates.sourceSyncProvider.present,
+        evidenceRequired: hasPlanGate(inputs.taskArtifacts.get('plan.md'), ['source sync / provider gate', 'source sync provider gate', 'source sync gate', 'provider gate']),
+        evidenceComplete: !evidenceIssues.some((issue) => issue.message.includes('Source Sync / Provider')),
+      },
+    },
+    context: {
+      planSha: inputs.planFingerprint.planSha,
+      planFingerprintVersion: inputs.planFingerprint.planFingerprintVersion,
+      memorySha: inputs.memorySha,
+      riskProfile: inputs.risk.riskProfile,
+      riskTriggers: inputs.risk.riskTriggers,
+      riskWarnings: riskConfigWarnings(),
+      checkContextCurrent: checkContextState.current,
+    },
+    requiredEvidenceIssues: evidenceIssues,
+    qualitySignals: inputs.qualityGates.missingSignals,
+    lastCheckResult: summarizeResult(checkResult),
+    lastVerifyResult: summarizeResult(verifyResult),
+    loopDetector,
+    timestamps: {
+      createdAt: existing?.timestamps?.createdAt || now,
+      updatedAt: now,
+      phaseChangedAt: previousPhase && previousPhase !== inferredPhase
+        ? now
+        : existing?.timestamps?.phaseChangedAt || now,
+    },
+  };
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return ['Manifest must be a JSON object.'];
+  }
+  if (manifest.schemaVersion !== 1) {
+    errors.push('schemaVersion must be 1.');
+  }
+  if (!manifest.taskId) {
+    errors.push('taskId is required.');
+  }
+  if (!ALLOWED_TASK_MODES.includes(manifest.mode)) {
+    errors.push(`mode must be one of: ${ALLOWED_TASK_MODES.join(', ')}.`);
+  }
+  if (!ALLOWED_TASK_PHASES.includes(manifest.phase)) {
+    errors.push(`phase must be one of: ${ALLOWED_TASK_PHASES.join(', ')}.`);
+  }
+  for (const [gateName, gate] of Object.entries(manifest.gates || {})) {
+    if (gate.required && !gate.planComplete) {
+      errors.push(`${gateName} is required but planComplete=false.`);
+    }
+  }
+  if (manifest.loopDetector?.requiresConsolidatedRemediation && !hasConsolidatedRemediation(manifest)) {
+    errors.push('Loop detector requires consolidated remediation before another checker/verifier loop.');
+  }
+  return errors;
+}
+
+export function preflightTask({ taskDir, targetPhase }) {
+  const manifest = buildTaskManifest({ taskDir });
+  const warnings = manifest.context.riskWarnings || [];
+  const issues = validateManifest(manifest).map((message) => ({
+    category: 'manifest_validation',
+    message,
+  }));
+
+  if ((targetPhase === 'execute' || targetPhase === 'verify' || targetPhase === 'human_gate') && !manifest.context.checkContextCurrent) {
+    issues.push({
+      category: 'stale_check_context',
+      message: 'check-context.json/checker-context-pack.md is stale or missing. Run agent:build-check-context or agent:run-check before this transition.',
+    });
+  }
+  if ((targetPhase === 'execute' || targetPhase === 'verify' || targetPhase === 'human_gate') && manifest.qualitySignals.length > 0) {
+    for (const signal of manifest.qualitySignals) {
+      issues.push({
+        category: 'plan_quality_gate',
+        message: signal,
+      });
+    }
+  }
+  if ((targetPhase === 'verify' || targetPhase === 'human_gate') && manifest.requiredEvidenceIssues.length > 0) {
+    for (const issue of manifest.requiredEvidenceIssues) {
+      issues.push(issue);
+    }
+  }
+  if (targetPhase === 'verify' || targetPhase === 'human_gate') {
+    issues.push(...inspectExecutionLedgerEvidence(taskDir));
+  }
+  if ((targetPhase === 'execute' || targetPhase === 'verify' || targetPhase === 'human_gate') && manifest.loopDetector.requiresConsolidatedRemediation) {
+    issues.push({
+      category: 'loop_detector',
+      message: 'Repeated checker/verifier return reason detected. Add consolidated remediation before continuing.',
+    });
+  }
+
+  return {
+    ok: issues.length === 0,
+    targetPhase,
+    manifest,
+    issues,
+    warnings,
+  };
+}
+
+export function transitionTaskManifest({ taskDir, targetPhase, now = new Date().toISOString() }) {
+  const normalizedPhase = normalizePhase(targetPhase);
+  const preflight = preflightTask({ taskDir, targetPhase: normalizedPhase });
+  if (!preflight.ok) {
+    return {
+      ok: false,
+      manifest: preflight.manifest,
+      issues: preflight.issues,
+      warnings: preflight.warnings,
+    };
+  }
+  const manifest = {
+    ...preflight.manifest,
+    phase: normalizedPhase,
+    timestamps: {
+      ...preflight.manifest.timestamps,
+      updatedAt: now,
+      phaseChangedAt: preflight.manifest.phase === normalizedPhase
+        ? preflight.manifest.timestamps.phaseChangedAt
+        : now,
+    },
+  };
+  return {
+    ok: true,
+    manifest,
+    issues: [],
+    warnings: preflight.warnings,
+  };
+}
+
+function riskConfigWarnings() {
+  const risk = projectContext.risk || {};
+  const warnings = [];
+  if (!Array.isArray(risk.uiRoots) || risk.uiRoots.length === 0) {
+    warnings.push('risk.uiRoots is empty; path-based UI detection is disabled until the project config is filled.');
+  }
+  if (!Array.isArray(risk.backendRoots) || risk.backendRoots.length === 0) {
+    warnings.push('risk.backendRoots is empty; path-based user-visible API detection is limited to text signals.');
+  }
+  if (!Array.isArray(risk.workerRoots) || risk.workerRoots.length === 0) {
+    warnings.push('risk.workerRoots is empty; path-based worker detection is limited to text signals.');
+  }
+  return warnings;
+}
+
+export function readExistingManifest(taskDir) {
+  const filePath = path.join(taskDir, TASK_MANIFEST_FILE);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return readJsonFile(filePath);
+}
+
+export function writeTaskManifest(taskDir, manifest) {
+  fs.writeFileSync(path.join(taskDir, TASK_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export function recordLlmInputUsage({ taskDir, stage, packMeta, attempts = [], rerunCount = 0, now = new Date().toISOString() }) {
+  const existing = readExistingManifest(taskDir);
+  if (!existing) {
+    return null;
+  }
+  const normalizedAttempts = attempts.length > 0
+    ? attempts
+    : [{
+        mode: packMeta.mode,
+        estimatedTokens: packMeta.estimatedTokens,
+        bytes: packMeta.bytes,
+        capTokens: packMeta.capTokens,
+        overCap: packMeta.overCap,
+        outcome: 'recorded',
+      }];
+  const manifest = {
+    ...existing,
+    llmInput: {
+      ...(existing.llmInput || {}),
+      [stage]: {
+        selectedMode: packMeta.mode,
+        estimatedTokens: packMeta.estimatedTokens,
+        bytes: packMeta.bytes,
+        capTokens: packMeta.capTokens,
+        compactedArtifacts: packMeta.compactedArtifacts,
+        overCap: packMeta.overCap,
+        rerunCount,
+        attempts: normalizedAttempts,
+        cumulativeEstimatedTokens: normalizedAttempts.reduce((sum, attempt) => sum + (attempt.estimatedTokens || 0), 0),
+        updatedAt: now,
+      },
+    },
+    timestamps: {
+      ...(existing.timestamps || {}),
+      updatedAt: now,
+    },
+  };
+  writeTaskManifest(taskDir, manifest);
+  return manifest;
+}
+
+export function extractTaskMode(planContent) {
+  const sections = parseMarkdownSections(planContent || '');
+  const raw = sections.get('Task Mode') || sections.get('Speed mode') || sections.get('Mode') || '';
+  const text = `${raw}\n${planContent || ''}`.toLowerCase();
+  if (/\bfast\b/.test(text)) {
+    return 'fast';
+  }
+  if (/\bstrict\b/.test(text)) {
+    return 'strict';
+  }
+  if (/\bstandard\b/.test(text)) {
+    return 'standard';
+  }
+  return null;
+}
+
+export function normalizeTaskMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!ALLOWED_TASK_MODES.includes(normalized)) {
+    return 'standard';
+  }
+  return normalized;
+}
+
+export function normalizePhase(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+  const aliases = {
+    plan_check: 'check',
+    checked: 'check',
+    execution: 'execute',
+    external_verify: 'verify',
+    verification: 'verify',
+    human: 'human_gate',
+    human_gate_review: 'human_gate',
+    retrospective_ready: 'retrospective',
+  };
+  const phase = aliases[normalized] || normalized;
+  if (!ALLOWED_TASK_PHASES.includes(phase)) {
+    return 'plan';
+  }
+  return phase;
+}
+
+export function updateLoopDetector({ existing = null, results = [] } = {}) {
+  const seenResultKeys = new Set(existing?.seenResultKeys || []);
+  const reasons = { ...(existing?.reasons || {}) };
+
+  for (const { source, value } of results) {
+    if (!isReturnResult(value)) {
+      continue;
+    }
+    const resultKey = buildResultKey(source, value);
+    if (seenResultKeys.has(resultKey)) {
+      continue;
+    }
+    seenResultKeys.add(resultKey);
+    for (const reason of extractResultReasons(value)) {
+      const hash = hashReason(reason);
+      const previous = reasons[hash] || {
+        hash,
+        normalizedReason: normalizeReason(reason),
+        count: 0,
+        sources: [],
+      };
+      reasons[hash] = {
+        ...previous,
+        count: previous.count + 1,
+        sources: Array.from(new Set([...previous.sources, source])).sort(),
+      };
+    }
+  }
+
+  const repeatedReasons = Object.values(reasons)
+    .filter((reason) => reason.count >= LOOP_REMEDIATION_THRESHOLD)
+    .sort((left, right) => right.count - left.count || left.hash.localeCompare(right.hash));
+
+  return {
+    threshold: LOOP_REMEDIATION_THRESHOLD,
+    requiresConsolidatedRemediation: repeatedReasons.length > 0,
+    repeatedReasons,
+    reasons,
+    seenResultKeys: Array.from(seenResultKeys).sort(),
+  };
+}
+
+export function normalizeReason(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/`[^`]+`/g, '`path`')
+    .replace(/\b[a-z0-9._/-]+\.(ts|tsx|js|mjs|json|md)\b/g, 'path')
+    .replace(/\b[fv]-\d{3}\b/g, 'id')
+    .replace(/\b\d+\b/g, 'n')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 240);
+}
+
+function inferPhaseFromTask(taskDir) {
+  const verifyResult = readOptionalJson(taskDir, 'verify.result.json');
+  if (verifyResult?.readyForRetrospective || verifyResult?.verdict === 'pass' || verifyResult?.verdict === 'pass_with_notes') {
+    return 'human_gate';
+  }
+  if (fs.existsSync(path.join(taskDir, 'execution.md'))) {
+    return 'verify';
+  }
+  const checkResult = readOptionalJson(taskDir, 'check.result.json');
+  if (checkResult?.readyForHumanGate || checkResult?.verdict === 'ready_for_human_gate') {
+    return 'execute';
+  }
+  if (fs.existsSync(path.join(taskDir, 'check-context.json'))) {
+    return 'check';
+  }
+  const statusStage = readStatusStage(taskDir);
+  return statusStage ? normalizePhase(statusStage) : 'plan';
+}
+
+function readOptionalJson(taskDir, fileName) {
+  const filePath = path.join(taskDir, fileName);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return readJsonFile(filePath);
+}
+
+function hasPlanGate(planContent, names) {
+  const sections = parseMarkdownSections(planContent || '');
+  const normalizedNames = new Set(names.map((name) => name.toLowerCase()));
+  for (const title of sections.keys()) {
+    if (normalizedNames.has(title.toLowerCase())) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function summarizeResult(result) {
+  if (!result) {
+    return null;
+  }
+  return {
+    verdict: result.verdict || null,
+    createdAt: result.createdAt || null,
+    blockingFindings: result.blockingFindings ?? result.counts?.blockingFindings ?? null,
+    nonBlockingFindings: result.nonBlockingFindings ?? result.counts?.nonBlockingFindings ?? null,
+    questions: result.humanQuestions ?? result.counts?.questions ?? null,
+  };
+}
+
+function inspectExecutionLedgerEvidence(taskDir) {
+  if (!fs.existsSync(path.join(taskDir, 'execution.md'))) {
+    return [];
+  }
+  const ledger = readOptionalJson(taskDir, 'execution-ledger.json');
+  if (!ledger) {
+    return [{
+      category: 'execution_ledger_missing',
+      message: 'execution-ledger.json is missing. Run agent:build-execution-ledger before Verify/Human Gate.',
+    }];
+  }
+
+  const execution = readTaskFile(taskDir, 'execution.md');
+  const changedFiles = Array.isArray(ledger.git?.changedFiles) ? ledger.git.changedFiles : [];
+  const missingFiles = changedFiles
+    .filter((file) => file.isTaskArtifact || file.isOpsFrameworkFile || !isUnrelatedDirtyFile(ledger, file))
+    .map((file) => file.path)
+    .filter((filePath) => filePath && !execution.includes(filePath));
+
+  if (missingFiles.length === 0) {
+    return [];
+  }
+  return [{
+    category: 'dirty_evidence_mismatch',
+    message: `execution.md does not mention changed files from execution-ledger.json: ${missingFiles.slice(0, 10).join(', ')}${missingFiles.length > 10 ? ', ...' : ''}.`,
+  }];
+}
+
+function isUnrelatedDirtyFile(ledger, file) {
+  const unrelated = Array.isArray(ledger.git?.unrelatedDirtyFiles) ? ledger.git.unrelatedDirtyFiles : [];
+  return unrelated.some((candidate) => candidate.path === file.path);
+}
+
+function isReturnResult(result) {
+  return Boolean(result && ['return_to_plan', 'return_to_execute', 'checker_failed', 'verifier_failed'].includes(result.verdict));
+}
+
+function buildResultKey(source, result) {
+  return [
+    source,
+    result.verdict || 'unknown',
+    result.verifierRunId || result.checkerRunId || result.createdAt || 'no-run-id',
+    hashReason(JSON.stringify(extractResultReasons(result))),
+  ].join(':');
+}
+
+function extractResultReasons(result) {
+  const findings = Array.isArray(result.findings) ? result.findings : [];
+  const reasons = findings
+    .map((finding) => finding.claim || finding.message || finding.expectedCorrection || '')
+    .filter(Boolean);
+  if (reasons.length > 0) {
+    return reasons;
+  }
+  return [result.failureReason || result.verdict || 'unknown return reason'];
+}
+
+function hashReason(value) {
+  return crypto.createHash('sha256').update(normalizeReason(value)).digest('hex').slice(0, 16);
+}
+
+function hasConsolidatedRemediation(manifest) {
+  return Boolean(manifest.consolidatedRemediationAccepted);
+}
+
+function preserveManualManifestFields(existing) {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+    return {};
+  }
+  const generatedKeys = new Set([
+    'schemaVersion',
+    'taskId',
+    'mode',
+    'phase',
+    'gates',
+    'context',
+    'requiredEvidenceIssues',
+    'qualitySignals',
+    'lastCheckResult',
+    'lastVerifyResult',
+    'loopDetector',
+    'timestamps',
+  ]);
+  return Object.fromEntries(
+    Object.entries(existing).filter(([key]) => !generatedKeys.has(key)),
+  );
+}