avorelo 0.1.0

package/scripts/lib/work-control-receipts.js

@@ -0,0 +1,577 @@
+"use strict";
+
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const WORK_CONTROL_CONTRACT = "avorelo.workControlReceipt.v1";
+const WORK_CONTROL_SCHEMA_VERSION = 1;
+const LATEST_WC_RECEIPT_REL_PATH = ".claude/cco/orchestration/work-control/latest-receipt.json";
+const WC_HISTORY_DIR_REL_PATH = ".claude/cco/orchestration/work-control/history";
+const WC_EVENT_LOG_REL_PATH = ".claude/cco/events/work-control.jsonl";
+
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*\S+)/i;
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function redactIfSecret(text) {
+  if (!text) return text;
+  const s = String(text);
+  return SECRET_PATTERN.test(s) ? "[REDACTED]" : s;
+}
+
+function createReceiptId() {
+  return `wc-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function readLatestWorkControlReceipt(cwd) {
+  return safeReadJson(cwd, LATEST_WC_RECEIPT_REL_PATH, null);
+}
+
+function computeFinalState(controls) {
+  const { guard, governance, safePath, installIntake } = controls;
+
+  const isBlocked =
+    guard?.decision === "block"
+    || governance?.decision === "block"
+    || safePath?.lastDecision === "block";
+
+  if (isBlocked) return "blocked";
+
+  const requiresApproval =
+    guard?.decision === "approval_required"
+    || governance?.decision === "approval_required"
+    || governance?.approvalBoundary === true
+    || safePath?.lastDecision === "approval_required"
+    || safePath?.approvalBoundary === true;
+
+  if (requiresApproval) return "approval_required";
+
+  const hasAttention =
+    (installIntake?.highRiskItems > 0)
+    || (installIntake?.unknownItems > 0)
+    || (governance?.subjectTrustStatus === "unknown")
+    || (guard?.riskLevel === "high" || guard?.riskLevel === "critical");
+
+  if (hasAttention) return "attention";
+
+  const hasEvidence =
+    guard?.evidencePath
+    || governance?.latestReceiptPath
+    || safePath?.latestReceiptPath
+    || installIntake?.latestReceiptPath;
+
+  return hasEvidence ? "ok" : "missing";
+}
+
+function computeNextSafestAction(controls, finalState) {
+  const { guard, governance, safePath, installIntake } = controls;
+
+  if (finalState === "blocked") {
+    return "Preserve the block — do not execute the destructive or blocked action.";
+  }
+  if (governance?.subjectTrustStatus === "unknown" || installIntake?.unknownItems > 0) {
+    return "Review unknown intake source or subject before proceeding.";
+  }
+  if (finalState === "approval_required") {
+    return safePath?.nextAction
+      || governance?.nextAction
+      || "Approve only the reduced scope before proceeding.";
+  }
+  if (finalState === "attention") {
+    return installIntake?.nextAction
+      || guard?.nextAction
+      || "Review high-risk intake items and confirm reduced scope.";
+  }
+  if (!guard?.evidencePath && !governance?.latestReceiptPath) {
+    return "Run `avorelo guard` on a risky action to generate the first control receipt.";
+  }
+  return "Continue with the smallest local scope. Re-run proof before next session.";
+}
+
+function buildDoNotRepeat(controls, proof) {
+  const items = [
+    "Do not rerun from scratch — use current proof/work-control receipt.",
+    "Do not trust unknown MCP server or package without running intake review first.",
+    "Do not paste huge status JSON into context — use `avorelo work-control --json` instead.",
+  ];
+  if (proof?.route?.selectedRoute?.includes("broad") || proof?.route?.safetyNotes?.some((n) => /broad/i.test(n))) {
+    items.push("Do not perform broad repo scan — route already recorded the relevant context.");
+  }
+  if (controls.installIntake?.unknownItems > 0) {
+    items.push("Do not execute tool or MCP call for unknown/unreviewed source.");
+  }
+  if (controls.safePath?.lastDecision === "recommend_reduced_scope") {
+    items.push("Do not use broad scope — safe path already recommended a reduced alternative.");
+  }
+  return unique(items);
+}
+
+function buildCarryForward(cwd, controls, proof, finalState, nextSafestAction) {
+  const items = {};
+
+  if (proof?.route?.selectedRoute) {
+    items.lastRoute = proof.route.selectedRoute;
+  }
+  if (proof?.task) {
+    items.lastTaskSummary = String(proof.task).slice(0, 200);
+  }
+  if (proof?.runId) {
+    items.lastRunId = proof.runId;
+  }
+  items.finalState = finalState;
+  items.nextSafestAction = nextSafestAction;
+
+  items.receiptPaths = [
+    controls.guard?.evidencePath ? `guard: ${controls.guard.evidencePath}` : null,
+    controls.governance?.latestReceiptPath ? `governance: ${controls.governance.latestReceiptPath}` : null,
+    controls.safePath?.latestReceiptPath ? `safe-path: ${controls.safePath.latestReceiptPath}` : null,
+    controls.installIntake?.latestReceiptPath ? `intake: ${controls.installIntake.latestReceiptPath}` : null,
+    controls.skills?.latestRouteReceiptPath ? `skills: ${controls.skills.latestRouteReceiptPath}` : null,
+  ].filter(Boolean);
+
+  const unchecked = [];
+  if (!controls.governance?.latestReceiptPath) unchecked.push("governance receipt missing");
+  if (!controls.safePath?.latestReceiptPath) unchecked.push("safe-path receipt missing");
+  if (!controls.skills?.latestRouteReceiptPath) unchecked.push("skills route receipt missing");
+  if (unchecked.length) items.uncheckedItems = unchecked;
+
+  items.restoreCommands = [
+    "node bin/avorelo work-control --json",
+    "node bin/avorelo proof",
+  ];
+
+  return items;
+}
+
+function buildWorkControlSummary(controls, finalState, nextSafestAction, doNotRepeat, carryForward) {
+  const { guard, governance, safePath, installIntake, skills } = controls;
+
+  const allowedCount = guard?.decision === "allow" ? 1 : 0;
+  const warnedCount = guard?.decision === "warn" ? 1 : 0;
+  const approvalRequiredCount = (guard?.decision === "approval_required" || finalState === "approval_required") ? 1 : 0;
+  const blockedCount = guard?.decision === "block" ? 1 : 0;
+  const reductionsRecommendedCount = safePath?.reductionsRecommended || 0;
+  const reviewedSourcesCount = skills?.reviewedSources || 0;
+  const unknownSourcesCount = skills?.deferredSources || 0;
+  const highRiskIntakeCount = installIntake?.highRiskItems || 0;
+
+  return {
+    allowedCount,
+    warnedCount,
+    approvalRequiredCount,
+    blockedCount,
+    reductionsRecommendedCount,
+    reviewedSourcesCount,
+    unknownSourcesCount,
+    highRiskIntakeCount,
+    finalState,
+    nextSafestAction,
+    doNotRepeat,
+    carryForward,
+  };
+}
+
+function buildWorkControlReceipt(cwd, options = {}) {
+  const { buildAgentAccessGovernanceSurface } = require("./agent-access-governance");
+  const { buildSafePathSurface } = require("./safe-path-engine");
+  const { buildInstallIntakeRiskSurface } = require("./install-intake-risk");
+  const { buildSkillsOperatingLayerSurface } = require("./skills-operating-layer");
+
+  let proof = null;
+  try {
+    const { readCurrentProof } = require("./orchestration");
+    proof = readCurrentProof(cwd);
+  } catch {}
+
+  const governanceSurface = buildAgentAccessGovernanceSurface(cwd);
+  const safePathSurface = buildSafePathSurface(cwd);
+  const intakeSurface = buildInstallIntakeRiskSurface(cwd);
+  const skillsSurface = buildSkillsOperatingLayerSurface(cwd);
+
+  const rawTask = (options.task || proof?.task || "");
+  const taskText = redactIfSecret(rawTask) || "";
+
+  const taskSection = {
+    text: taskText.slice(0, 400),
+    type: proof?.route?.task?.taskType || options.taskType || "unknown",
+    risk: proof?.route?.task?.risk || options.taskRisk || "unknown",
+    sensitivity: proof?.route?.task?.sensitivity || options.taskSensitivity || "unknown",
+    surface: proof?.surface || options.surface || "avorelo_cli",
+  };
+
+  const routeSection = proof?.route
+    ? {
+        selectedRoute: proof.route.selectedRoute || null,
+        chosenTool: proof.route.chosenTool || null,
+        selectedModel: proof.route.selectedModel || null,
+        chosenModelProfile: proof.route.chosenModelProfile || null,
+        fallbackTool: proof.route.fallbackTool || null,
+        safetyNotes: (proof.route.safetyNotes || []).slice(0, 5),
+        whyChosen: (proof.route.whyChosen || []).slice(0, 3),
+        whyNotChosen: (proof.route.whyNotChosen || []).slice(0, 3),
+      }
+    : {
+        selectedRoute: null,
+        chosenTool: null,
+        selectedModel: null,
+        chosenModelProfile: null,
+        fallbackTool: null,
+        safetyNotes: [],
+        whyChosen: [],
+        whyNotChosen: [],
+      };
+
+  const latestGovernanceReceipt = governanceSurface.latestReceipt;
+  const latestSafePathReceipt = safePathSurface.latestReceipt;
+
+  const guardSection = latestGovernanceReceipt
+    ? {
+        decision: latestGovernanceReceipt.decision || "unknown",
+        riskLevel: latestGovernanceReceipt.severity || "unknown",
+        reasonCodes: (latestGovernanceReceipt.reasonCodes || []).slice(0, 5),
+        matchedRules: [],
+        evidencePath: governanceSurface.latestReceiptPath || null,
+        nextAction: null,
+      }
+    : {
+        decision: "missing",
+        riskLevel: "unknown",
+        reasonCodes: [],
+        matchedRules: [],
+        evidencePath: null,
+        nextAction: "Run `avorelo guard` to generate the first governance receipt.",
+      };
+
+  const governanceSection = {
+    status: governanceSurface.status,
+    latestReceiptPath: governanceSurface.latestReceiptPath,
+    decision: latestGovernanceReceipt?.decision || "missing",
+    subjectType: latestGovernanceReceipt?.subjectSummary?.type || null,
+    subjectTrustStatus: latestGovernanceReceipt?.subjectSummary?.trustStatus || null,
+    requestedActionType: latestGovernanceReceipt?.requestedActionSummary?.type || null,
+    scopeSummary: latestGovernanceReceipt?.scopeSummary || null,
+    approvalBoundary: latestGovernanceReceipt?.approvalBoundary?.required === true,
+    nextAction: governanceSurface.nextAction,
+  };
+
+  const safePathSection = {
+    status: safePathSurface.status,
+    latestReceiptPath: safePathSurface.latestReceiptPath,
+    lastDecision: safePathSurface.lastDecision,
+    recommendedBoundary: latestSafePathReceipt?.recommendedBoundary || null,
+    reductionSummary: latestSafePathReceipt?.reductionSummary || null,
+    approvalBoundary: latestSafePathReceipt?.approvalBoundary?.required === true,
+    nextAction: safePathSurface.nextAction,
+    reductionsRecommended: safePathSurface.reductionsRecommended,
+  };
+
+  const intakeSection = {
+    status: intakeSurface.status,
+    latestReceiptPath: intakeSurface.latestReceiptPath,
+    totalItems: intakeSurface.totalItems,
+    unknownItems: intakeSurface.unknownItems,
+    highRiskItems: intakeSurface.highRiskItems,
+    topReasonCodes: (intakeSurface.topReasonCodes || []).slice(0, 5),
+    nextAction: intakeSurface.nextAction,
+  };
+
+  const skillsSection = {
+    status: skillsSurface.status,
+    primarySkill: null,
+    reviewedSources: skillsSurface.reviewedSources,
+    deferredSources: skillsSurface.deferredSources,
+    latestRouteReceiptPath: skillsSurface.latestSkillRouteReceiptPath || null,
+    evidenceRequirements: [],
+  };
+
+  const controls = {
+    guard: guardSection,
+    governance: governanceSection,
+    safePath: safePathSection,
+    installIntake: intakeSection,
+    skills: skillsSection,
+  };
+
+  const verification = {
+    status: proof?.verification?.status || "missing",
+    commandsRun: [],
+    passed: [],
+    failed: [],
+    notChecked: [
+      !governanceSurface.latestReceiptPath && "governance receipt",
+      !safePathSurface.latestReceiptPath && "safe-path receipt",
+      !skillsSurface.latestSkillRouteReceiptPath && "skills route receipt",
+    ].filter(Boolean),
+    proofPath: proof ? ".claude/cco/orchestration/current-proof.json" : null,
+  };
+
+  const finalState = computeFinalState(controls);
+  const nextSafestAction = computeNextSafestAction(controls, finalState);
+  const doNotRepeat = buildDoNotRepeat(controls, proof);
+  const carryForward = buildCarryForward(cwd, controls, proof, finalState, nextSafestAction);
+  const workControl = buildWorkControlSummary(controls, finalState, nextSafestAction, doNotRepeat, carryForward);
+
+  const allReceiptPaths = [
+    governanceSurface.latestReceiptPath,
+    safePathSurface.latestReceiptPath,
+    intakeSurface.latestReceiptPath,
+    skillsSurface.latestSkillRouteReceiptPath,
+  ].filter(Boolean);
+
+  const receipt = {
+    schemaVersion: WORK_CONTROL_SCHEMA_VERSION,
+    contract: WORK_CONTROL_CONTRACT,
+    receiptType: "work_control",
+    receiptId: createReceiptId(),
+    createdAt: nowIso(),
+    cwd,
+    task: taskSection,
+    route: routeSection,
+    controls,
+    verification,
+    workControl,
+    evidencePaths: allReceiptPaths,
+    productLearning: {
+      eventsWritten: 0,
+      suggestedEvents: ["work_control_receipt_written"],
+    },
+    redacted: true,
+  };
+
+  return receipt;
+}
+
+function writeWorkControlReceipt(cwd, receipt, options = {}) {
+  ensureCcoDirs(cwd);
+
+  const relPath = LATEST_WC_RECEIPT_REL_PATH;
+  safeWriteJson(cwd, relPath, receipt);
+
+  const fs = require("fs");
+  const path = require("path");
+  const historyDir = path.join(cwd, WC_HISTORY_DIR_REL_PATH);
+  fs.mkdirSync(historyDir, { recursive: true });
+
+  const canExport = options.plan && options.plan !== "free";
+  if (canExport) {
+    safeWriteJson(cwd, `${WC_HISTORY_DIR_REL_PATH}/${receipt.receiptId}.json`, receipt);
+  }
+
+  const eventLine = {
+    receiptId: receipt.receiptId,
+    finalState: receipt.workControl.finalState,
+    blockedCount: receipt.workControl.blockedCount,
+    approvalRequiredCount: receipt.workControl.approvalRequiredCount,
+    highRiskIntakeCount: receipt.workControl.highRiskIntakeCount,
+    receiptPath: relPath,
+    createdAt: receipt.createdAt,
+  };
+
+  try {
+    const abs = require("path").join(cwd, WC_EVENT_LOG_REL_PATH);
+    fs.mkdirSync(require("path").dirname(abs), { recursive: true });
+    fs.appendFileSync(abs, `${JSON.stringify(eventLine)}\n`, "utf8");
+  } catch {}
+
+  let eventsWritten = 0;
+
+  const productEvents = [];
+  productEvents.push({
+    eventName: "work_control_receipt_written",
+    category: "work_control",
+    status: "completed",
+    payload: {
+      finalState: receipt.workControl.finalState,
+      blockedCount: receipt.workControl.blockedCount,
+      approvalRequiredCount: receipt.workControl.approvalRequiredCount,
+      highRiskIntakeCount: receipt.workControl.highRiskIntakeCount,
+      evidencePathsCount: receipt.evidencePaths.length,
+    },
+  });
+
+  if (receipt.workControl.finalState === "blocked") {
+    productEvents.push({
+      eventName: "work_control_block_preserved",
+      category: "work_control",
+      status: "completed",
+      payload: {
+        receiptId: receipt.receiptId,
+        blockedCount: receipt.workControl.blockedCount,
+      },
+    });
+  }
+
+  if (receipt.workControl.finalState === "approval_required") {
+    productEvents.push({
+      eventName: "work_control_approval_required",
+      category: "work_control",
+      status: "recommended",
+      payload: {
+        approvalRequiredCount: receipt.workControl.approvalRequiredCount,
+      },
+    });
+  }
+
+  if (receipt.workControl.nextSafestAction) {
+    productEvents.push({
+      eventName: "work_control_next_action_recommended",
+      category: "work_control",
+      status: "recommended",
+      payload: {
+        finalState: receipt.workControl.finalState,
+      },
+    });
+  }
+
+  if (receipt.workControl.doNotRepeat?.length) {
+    productEvents.push({
+      eventName: "work_control_do_not_repeat_generated",
+      category: "work_control",
+      status: "completed",
+      payload: {
+        count: receipt.workControl.doNotRepeat.length,
+      },
+    });
+  }
+
+  productEvents.forEach((event) => {
+    try {
+      appendProductLearningEvent(cwd, event);
+      eventsWritten += 1;
+    } catch {}
+  });
+
+  receipt.productLearning.eventsWritten = eventsWritten;
+
+  return relPath;
+}
+
+function buildWorkControlSurface(cwd) {
+  const latestReceipt = readLatestWorkControlReceipt(cwd);
+  if (!latestReceipt) {
+    return {
+      status: "missing",
+      latestReceiptPath: null,
+      finalState: "missing",
+      nextSafestAction: "Run `avorelo work-control` to generate the first receipt.",
+      blockedCount: 0,
+      approvalRequiredCount: 0,
+      highRiskIntakeCount: 0,
+      unknownSourcesCount: 0,
+      proofAvailable: false,
+      carryForwardAvailable: false,
+      showInStatus: true,
+      showInDashboard: true,
+      statusLine: "Work Control: MISSING · no receipt yet",
+    };
+  }
+
+  const wc = latestReceipt.workControl || {};
+  const finalState = wc.finalState || "missing";
+  const stateLabel = finalState.toUpperCase().replace(/_/g, " ");
+
+  return {
+    status: "foundation",
+    latestReceiptPath: LATEST_WC_RECEIPT_REL_PATH,
+    finalState,
+    nextSafestAction: wc.nextSafestAction || null,
+    blockedCount: wc.blockedCount || 0,
+    approvalRequiredCount: wc.approvalRequiredCount || 0,
+    highRiskIntakeCount: wc.highRiskIntakeCount || 0,
+    unknownSourcesCount: wc.unknownSourcesCount || 0,
+    proofAvailable: Boolean(latestReceipt.verification?.proofPath),
+    carryForwardAvailable: Boolean(wc.carryForward?.receiptPaths?.length),
+    showInStatus: true,
+    showInDashboard: true,
+    statusLine: `Work Control: ${stateLabel} · blocked=${wc.blockedCount || 0} · approval=${wc.approvalRequiredCount || 0} · high-risk-intake=${wc.highRiskIntakeCount || 0} · latest receipt ${LATEST_WC_RECEIPT_REL_PATH}`,
+  };
+}
+
+function formatWorkControlText(surfaceOrReceipt, options = {}) {
+  const isHandoff = options.handoff === true;
+
+  if (!surfaceOrReceipt) {
+    return "Work Control: MISSING · no receipt yet\nNext: Run `avorelo work-control` to generate the first receipt.\n";
+  }
+
+  if (surfaceOrReceipt.contract === WORK_CONTROL_CONTRACT) {
+    const receipt = surfaceOrReceipt;
+    const wc = receipt.workControl || {};
+    const stateLabel = (wc.finalState || "missing").toUpperCase().replace(/_/g, " ");
+    const taskText = receipt.task?.text ? String(receipt.task.text).slice(0, 120) : "unknown";
+
+    const lines = [
+      `Work Control: ${stateLabel}`,
+      `Task: ${taskText}`,
+      `State: ${wc.finalState || "missing"}`,
+    ];
+
+    if (receipt.controls?.guard?.decision && receipt.controls.guard.decision !== "missing") {
+      lines.push(`Guard: ${receipt.controls.guard.decision} · ${(receipt.controls.guard.reasonCodes || []).join(", ") || "no codes"}`);
+    }
+    if (receipt.controls?.installIntake?.totalItems) {
+      lines.push(`Install Intake: ${receipt.controls.installIntake.totalItems} items · ${receipt.controls.installIntake.unknownItems} unknown · ${receipt.controls.installIntake.highRiskItems} high`);
+    }
+    if (receipt.controls?.safePath?.lastDecision) {
+      lines.push(`Safe Path: ${receipt.controls.safePath.lastDecision}`);
+    }
+    if (wc.nextSafestAction) {
+      lines.push(`Next: ${wc.nextSafestAction}`);
+    }
+    if (receipt.evidencePaths?.length) {
+      lines.push(`Evidence paths: ${receipt.evidencePaths.join(", ")}`);
+    }
+    lines.push(`Receipt: ${LATEST_WC_RECEIPT_REL_PATH}`);
+
+    if (isHandoff) {
+      lines.push("");
+      lines.push("## Handoff");
+      lines.push(`State: ${wc.finalState || "missing"}`);
+      lines.push("");
+      lines.push("### What was checked");
+      (receipt.evidencePaths || []).forEach((p) => lines.push(`- ${p}`));
+      if (!receipt.evidencePaths?.length) lines.push("- No evidence paths recorded");
+      lines.push("");
+      lines.push("### What was not checked");
+      (receipt.verification?.notChecked || []).forEach((item) => lines.push(`- ${item}`));
+      if (!receipt.verification?.notChecked?.length) lines.push("- Nothing explicitly unchecked");
+      lines.push("");
+      lines.push("### What to do next");
+      lines.push(wc.nextSafestAction || "Continue with smallest local scope.");
+      lines.push("");
+      lines.push("### Do not repeat");
+      (wc.doNotRepeat || []).forEach((item) => lines.push(`- ${item}`));
+      lines.push("");
+      lines.push("### Receipt paths");
+      (wc.carryForward?.receiptPaths || []).forEach((p) => lines.push(`- ${p}`));
+      lines.push(`- work-control: ${LATEST_WC_RECEIPT_REL_PATH}`);
+    }
+
+    return lines.join("\n") + "\n";
+  }
+
+  const surface = surfaceOrReceipt;
+  const stateLabel = (surface.finalState || "missing").toUpperCase().replace(/_/g, " ");
+  const lines = [
+    `Work Control: ${stateLabel}`,
+    `Final state: ${surface.finalState || "missing"}`,
+  ];
+  if (surface.nextSafestAction) lines.push(`Next: ${surface.nextSafestAction}`);
+  if (surface.latestReceiptPath) lines.push(`Receipt: ${surface.latestReceiptPath}`);
+  return lines.join("\n") + "\n";
+}
+
+module.exports = {
+  WORK_CONTROL_CONTRACT,
+  WORK_CONTROL_SCHEMA_VERSION,
+  LATEST_WC_RECEIPT_REL_PATH,
+  WC_EVENT_LOG_REL_PATH,
+  readLatestWorkControlReceipt,
+  buildWorkControlReceipt,
+  writeWorkControlReceipt,
+  buildWorkControlSurface,
+  formatWorkControlText,
+};