avorelo 0.1.0 → 0.3.0

package/scripts/lib/execution-packet.js

@@ -1,559 +0,0 @@
-"use strict";
-
-// ── Execution Packet ──────────────────────────────────────────────────────────
-//
-// Contract: avorelo.executionPacket.v1
-//
-// Transforms messy user intent into a scoped, safe, verifiable execution packet.
-// Includes agent prompt compiler for adapting packets to target workers.
-//
-// No network calls. No LLM calls. No script execution. Local only.
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-const { ensureCcoDirs } = require("./fsx");
-const { appendProductLearningEvent } = require("./product-learning-events");
-
-const CONTRACT = "avorelo.executionPacket.v1";
-const SCHEMA_VERSION = 1;
-
-const LATEST_PACKET_REL = ".claude/cco/orchestration/execution-packet/latest-packet.json";
-
-// ── Modes ─────────────────────────────────────────────────────────────────────
-
-const MODES = Object.freeze([
-  "safe_patch",
-  "fast_prototype",
-  "visual_qa_prep",
-  "security_review",
-  "docs_update",
-  "refactor_plan",
-  "test_verification",
-  "handoff",
-]);
-
-// ── Risk levels ───────────────────────────────────────────────────────────────
-
-const RISK_LEVELS = Object.freeze(["low", "medium", "high", "critical"]);
-
-// ── Approval-required patterns ────────────────────────────────────────────────
-
-const APPROVAL_REQUIRED_PATTERNS = Object.freeze([
-  // Auth / security
-  "auth", "authentication", "login", "oauth", "jwt", "session", "password", "credential",
-  // Billing / payments
-  "billing", "payment", "stripe", "subscription", "invoice", "charge",
-  // Deploy / release
-  "deploy", "deployment", "release", "publish", "production", "prod",
-  // Infrastructure / secrets
-  "secret", "env", "config", "infra", "infrastructure", "database", "migration",
-  // Destructive
-  "delete", "drop", "truncate", "remove all", "wipe",
-]);
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function makePacketId() {
-  return `pkt-${crypto.createHash("sha1").update(`${Date.now()}-${Math.random()}`).digest("hex").slice(0, 12)}`;
-}
-
-function makeRunId() {
-  return `run-${crypto.createHash("sha1").update(`${Date.now()}-${Math.random()}`).digest("hex").slice(0, 12)}`;
-}
-
-// ── Mode inference ────────────────────────────────────────────────────────────
-
-function inferMode(userIntent, taskType) {
-  const intent = (userIntent || "").toLowerCase();
-  const type = (taskType || "").toLowerCase();
-
-  if (/security|vuln|pentest|audit|cve|owasp/.test(intent)) return "security_review";
-  if (/test|spec|coverage|e2e/.test(intent) && /add|fix|improve/.test(intent)) return "test_verification";
-  if (/doc|readme|comment|changelog|guide/.test(intent)) return "docs_update";
-  if (/refactor|restructure|reorganize|rename/.test(intent)) return "refactor_plan";
-  if (/screenshot|visual|ui|design|css|style/.test(intent)) return "visual_qa_prep";
-  if (/handoff|summary|brief|next session/.test(intent)) return "handoff";
-  if (/spike|proto|experiment|try|quick/.test(intent)) return "fast_prototype";
-  if (/fix|bug|patch|hotfix|broken|error|crash/.test(intent)) return "safe_patch";
-
-  if (type === "security_sensitive") return "security_review";
-  if (type === "test_or_verification") return "test_verification";
-  if (type === "documentation") return "docs_update";
-  if (type === "refactor") return "refactor_plan";
-  if (type === "deployment_release") return "safe_patch";
-
-  return "safe_patch";
-}
-
-// ── Risk assessment ───────────────────────────────────────────────────────────
-
-function assessRisk(userIntent, projectProfile, mode) {
-  const intent = (userIntent || "").toLowerCase();
-  const reasons = [];
-  let level = "low";
-  let approvalRequired = false;
-  let escalationRecommended = false;
-
-  // Check against approval-required patterns
-  for (const pattern of APPROVAL_REQUIRED_PATTERNS) {
-    if (intent.includes(pattern)) {
-      reasons.push(`Task mentions '${pattern}' which requires approval.`);
-      if (["auth", "billing", "payment", "deploy", "secret", "credential"].some((k) => pattern.includes(k))) {
-        approvalRequired = true;
-        escalationRecommended = true;
-        level = "high";
-      } else if (level === "low") {
-        level = "medium";
-      }
-    }
-  }
-
-  // Mode-based risk
-  if (mode === "security_review") {
-    level = "high";
-    escalationRecommended = true;
-    if (!approvalRequired) reasons.push("Security review mode requires careful human verification.");
-  }
-  if (mode === "fast_prototype") {
-    if (level === "low") level = "medium";
-    reasons.push("Fast prototype mode may skip normal safety checks.");
-  }
-
-  // Deploy config detected
-  if (projectProfile?.deploy?.requiresApproval) {
-    reasons.push("Deploy config detected. Deploy actions require explicit approval.");
-    approvalRequired = approvalRequired || intent.includes("deploy");
-    if (intent.includes("deploy")) {
-      level = "high";
-      approvalRequired = true;
-    }
-  }
-
-  // Sensitive dirs in intent
-  const sensitiveDirs = projectProfile?.riskBoundaries?.sensitiveDirs || [];
-  for (const dir of sensitiveDirs) {
-    if (intent.includes(dir.replace(/\//g, " ").replace(/-/g, " "))) {
-      reasons.push(`Task may touch sensitive directory: ${dir}`);
-      if (level === "low") level = "medium";
-    }
-  }
-
-  if (reasons.length === 0) reasons.push("No high-risk patterns detected.");
-
-  return {
-    level,
-    reasons: reasons.slice(0, 8),
-    approvalRequired,
-    escalationRecommended,
-  };
-}
-
-// ── Scope compilation ─────────────────────────────────────────────────────────
-
-function compileAllowedScope(userIntent, projectProfile, orchestrationPlan) {
-  const files = [];
-  const dirs = [];
-  const areas = [];
-  const actions = [...(projectProfile?.riskBoundaries?.allowedDefaultActions || [
-    "file_read",
-    "file_write_with_diff",
-    "run_tests",
-    "run_lint",
-    "run_build",
-    "git_status",
-    "git_diff",
-  ])];
-
-  // Add test/lint/build actions when available
-  if (projectProfile?.commands?.test) areas.push("test_files");
-  if (projectProfile?.commands?.lint) areas.push("lint_targets");
-  if (projectProfile?.commands?.build) areas.push("build_targets");
-
-  // Add orchestration stage context
-  if (orchestrationPlan?.stages?.length > 0) {
-    const stageTypes = orchestrationPlan.stages.map((s) => s.lifecycleStage || s.stageId).filter(Boolean);
-    for (const st of stageTypes) {
-      if (!areas.includes(st)) areas.push(st);
-    }
-  }
-
-  return { files, dirs, areas: [...new Set(areas)], actions };
-}
-
-function compileBlockedScope(userIntent, projectProfile) {
-  const blockedFiles = [...(projectProfile?.riskBoundaries?.blockedFiles || [])];
-  const blockedDirs = [...(projectProfile?.riskBoundaries?.sensitiveDirs || [])];
-  const blockedActions = [...(projectProfile?.riskBoundaries?.blockedActions || [])];
-
-  // Always block secrets / env files regardless
-  const alwaysBlock = [".env", ".env.local", ".env.production", ".env.server", "*.pem", "*.key", "secrets.json", "credentials.json"];
-  for (const f of alwaysBlock) {
-    if (!blockedFiles.includes(f)) blockedFiles.push(f);
-  }
-
-  // Always block deploy/publish actions
-  const alwaysBlockActions = ["deploy", "publish", "push_to_production", "charge_customer"];
-  for (const a of alwaysBlockActions) {
-    if (!blockedActions.includes(a)) blockedActions.push(a);
-  }
-
-  return {
-    files: [...new Set(blockedFiles)],
-    dirs: [...new Set(blockedDirs)],
-    areas: ["auth_internals", "billing_internals", "secrets_store"],
-    actions: [...new Set(blockedActions)],
-  };
-}
-
-// ── Proof requirements ────────────────────────────────────────────────────────
-
-function compileProofRequirements(mode, projectProfile, risk) {
-  const proofSteps = [];
-
-  const hasTest = Boolean(projectProfile?.commands?.test);
-  const hasBuild = Boolean(projectProfile?.commands?.build);
-  const hasLint = Boolean(projectProfile?.commands?.lint);
-
-  if (["safe_patch", "fast_prototype", "refactor_plan", "test_verification"].includes(mode)) {
-    if (hasTest) proofSteps.push({ step: "run_tests", command: projectProfile.commands.test, required: true });
-    if (hasBuild) proofSteps.push({ step: "run_build", command: projectProfile.commands.build, required: true });
-    if (hasLint) proofSteps.push({ step: "run_lint", command: projectProfile.commands.lint, required: false });
-  }
-
-  if (mode === "security_review") {
-    proofSteps.push({ step: "security_scan_review", command: null, required: true, note: "Manual security review required." });
-    if (hasTest) proofSteps.push({ step: "run_tests", command: projectProfile?.commands?.test, required: true });
-  }
-
-  if (mode === "docs_update") {
-    proofSteps.push({ step: "review_rendered_docs", command: null, required: false, note: "Review rendered documentation." });
-  }
-
-  if (mode === "visual_qa_prep") {
-    proofSteps.push({ step: "screenshot_capture", command: null, required: false, note: "Screenshot comparison deferred to Visual QA pipeline." });
-  }
-
-  if (risk.approvalRequired) {
-    proofSteps.push({ step: "human_approval", command: null, required: true, note: "Human approval required before proceeding." });
-  }
-
-  if (proofSteps.length === 0) {
-    proofSteps.push({ step: "manual_review", command: null, required: false, note: "No automated proof steps detected. Review manually." });
-  }
-
-  return proofSteps;
-}
-
-// ── Agent instructions ────────────────────────────────────────────────────────
-
-function compileAgentInstructions(goal, mode, allowedScope, blockedScope, proofRequired, diffRequired, risk) {
-  return {
-    goal,
-    mode,
-    principles: [
-      "Work only within the allowed scope.",
-      "Never touch blocked files, dirs, or actions.",
-      "Show a diff before any write to code files.",
-      proofRequired.some((p) => p.step === "run_tests") ? "Run tests after all changes." : null,
-      proofRequired.some((p) => p.step === "run_build") ? "Run build after all changes." : null,
-      risk.approvalRequired ? "STOP and request human approval before proceeding to any destructive or deployment step." : null,
-      "Do not read or include raw secrets, credentials, or PII in any output.",
-      "Summarize what was changed and what proof was collected at the end.",
-    ].filter(Boolean),
-    allowedScopeSummary: {
-      actions: allowedScope.actions,
-      areas: allowedScope.areas,
-    },
-    blockedScopeSummary: {
-      files: blockedScope.files.slice(0, 10),
-      dirs: blockedScope.dirs.slice(0, 6),
-      actions: blockedScope.actions.slice(0, 8),
-    },
-    diffBeforeWrite: diffRequired,
-    proofSteps: proofRequired.filter((p) => p.required).map((p) => p.step),
-  };
-}
-
-// ── Safe next action ──────────────────────────────────────────────────────────
-
-function inferSafeNextAction(mode, risk, projectProfile) {
-  if (risk.approvalRequired) return "Request human approval before proceeding. Do not execute blocked actions.";
-  if (mode === "security_review") return "Begin security review. Flag findings before applying any changes.";
-  if (mode === "refactor_plan") return "Draft the refactor plan. Show scope and impact before making changes.";
-  if (mode === "docs_update") return "Update documentation. Verify rendered output after changes.";
-  if (mode === "test_verification") return "Run existing tests first, then add or fix tests as needed.";
-  if (mode === "safe_patch") return "Show diff of proposed changes before writing. Run tests after.";
-  return "Review the execution packet scope before proceeding.";
-}
-
-// ── Main compiler ─────────────────────────────────────────────────────────────
-
-function compileExecutionPacket(cwd, input, options = {}) {
-  const userIntent = input?.userIntent || input?.task || "";
-  const inputMode = input?.mode || null;
-  const taskId = input?.taskId || null;
-
-  // Load project profile
-  const projectProfile = safeReadJson(
-    path.join(cwd, ".claude", "cco", "orchestration", "project-profile", "latest-profile.json")
-  ) || { status: "unknown", riskBoundaries: {}, commands: {}, deploy: {}, proofDefaults: {} };
-
-  // Load orchestration plan
-  const orchPlan = safeReadJson(
-    path.join(cwd, ".claude", "cco", "orchestration", "work-aware-orchestration", "latest-plan.json")
-  );
-
-  // Load hygiene report
-  const hygieneReport = safeReadJson(
-    path.join(cwd, ".claude", "cco", "orchestration", "ai-workspace-hygiene", "latest-report.json")
-  );
-
-  // Infer mode and risk
-  const taskType = orchPlan?.task?.taskType || "";
-  const mode = inputMode && MODES.includes(inputMode) ? inputMode : inferMode(userIntent, taskType);
-  const risk = assessRisk(userIntent, projectProfile, mode);
-
-  // Compile scope — blocked ALWAYS overrides allowed
-  const allowedScope = compileAllowedScope(userIntent, projectProfile, orchPlan);
-  const blockedScope = compileBlockedScope(userIntent, projectProfile);
-
-  // Proof and diff requirements
-  const diffRequired = ["safe_patch", "fast_prototype", "refactor_plan", "security_review"].includes(mode);
-  const proofRequired = compileProofRequirements(mode, projectProfile, risk);
-
-  // Agent instructions
-  const goal = userIntent || "Complete the task safely within the defined scope.";
-  const agentInstructions = compileAgentInstructions(
-    goal, mode, allowedScope, blockedScope, proofRequired, diffRequired, risk
-  );
-
-  // Target worker from orchestration plan
-  const implementStage = (orchPlan?.stages || []).find((s) => s.lifecycleStage === "implement");
-  const targetWorker = implementStage?.workerSelection?.selected || "claude_code";
-
-  const packet = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    packetId: makePacketId(),
-    runId: makeRunId(),
-    taskId: taskId || null,
-    goal,
-    mode,
-    targetWorker,
-    orchestrationPlanRef: orchPlan ? ".claude/cco/orchestration/work-aware-orchestration/latest-plan.json" : null,
-    contextPackRef: null,
-    projectProfileRef: ".claude/cco/orchestration/project-profile/latest-profile.json",
-    allowedScope,
-    blockedScope,
-    risk,
-    requiredBeforeWrite: diffRequired ? ["show_diff"] : [],
-    requiredAfterWrite: proofRequired.filter((p) => p.required).map((p) => p.step),
-    proofRequired,
-    diffRequired,
-    userApproval: risk.approvalRequired,
-    safeNextAction: inferSafeNextAction(mode, risk, projectProfile),
-    agentInstructions,
-    evidence: {
-      projectProfileStatus: projectProfile.status || "unknown",
-      hygieneScore: hygieneReport?.score || null,
-      orchestrationPlanStages: (orchPlan?.stages || []).length,
-    },
-    caveats: [
-      "Blocked scope always overrides allowed scope.",
-      "No raw secrets, credentials, or PII should appear in agent output.",
-      "Diff required before any code write when diffRequired is true.",
-      "Proof steps must be collected after write when requiredAfterWrite is non-empty.",
-      risk.approvalRequired ? "Human approval required before executing blocked/high-risk actions." : null,
-    ].filter(Boolean),
-    redacted: true,
-  };
-
-  return packet;
-}
-
-// ── Agent prompt compiler ─────────────────────────────────────────────────────
-
-function compileAgentPrompt(packet, options = {}) {
-  const target = options.target || "claude_code";
-
-  const lines = [
-    `# Avorelo Execution Packet`,
-    `Packet: ${packet.packetId}`,
-    `Mode: ${packet.mode}`,
-    `Risk: ${packet.risk?.level || "unknown"}`,
-    packet.userApproval ? `⚠ APPROVAL REQUIRED before executing.` : null,
-    "",
-    `## Goal`,
-    packet.goal,
-    "",
-    `## Principles`,
-    ...(packet.agentInstructions?.principles || []).map((p) => `- ${p}`),
-    "",
-    `## Allowed Scope`,
-    `Actions: ${(packet.allowedScope?.actions || []).join(", ") || "file_read, file_write_with_diff"}`,
-    packet.allowedScope?.areas?.length > 0 ? `Areas: ${packet.allowedScope.areas.join(", ")}` : null,
-    "",
-    `## Blocked Scope`,
-    `Files: ${(packet.blockedScope?.files || []).slice(0, 8).join(", ")}`,
-    `Dirs: ${(packet.blockedScope?.dirs || []).slice(0, 6).join(", ")}`,
-    `Actions: ${(packet.blockedScope?.actions || []).join(", ")}`,
-    "",
-    `## Before Any Write`,
-    packet.diffRequired ? `- Show a unified diff of all proposed changes before writing.` : `- Review changes with user before applying.`,
-    "",
-    `## After Write — Proof Required`,
-    ...(packet.requiredAfterWrite || []).map((s) => `- ${s}`),
-    (packet.requiredAfterWrite || []).length === 0 ? "- Manual review (no automated proof configured)." : null,
-    "",
-    `## Safe Next Action`,
-    packet.safeNextAction,
-    "",
-    `## Output Requirements`,
-    `- Summarize all changes made.`,
-    `- List proof collected (tests passed, build succeeded, etc.).`,
-    `- List any items skipped and why.`,
-    `- Do not include raw secrets, credentials, or PII in output.`,
-    packet.userApproval ? `- STOP before any deploy/publish/billing/auth change. Request approval.` : null,
-  ].filter((l) => l !== null);
-
-  return {
-    target,
-    promptText: lines.join("\n"),
-    packetId: packet.packetId,
-    mode: packet.mode,
-    riskLevel: packet.risk?.level,
-    approvalRequired: packet.userApproval,
-    redacted: true,
-  };
-}
-
-// ── Write and surface ─────────────────────────────────────────────────────────
-
-function writeExecutionPacket(cwd, packet) {
-  ensureCcoDirs(cwd);
-  const dir = path.join(cwd, ".claude", "cco", "orchestration", "execution-packet");
-  fs.mkdirSync(dir, { recursive: true });
-  const absPath = path.join(cwd, LATEST_PACKET_REL);
-  fs.writeFileSync(absPath, JSON.stringify(packet, null, 2), "utf8");
-
-  try {
-    appendProductLearningEvent(cwd, {
-      eventName: "execution_packet_compiled",
-      category: "execution_packet",
-      surface: "local",
-      status: "observed",
-      payload: {
-        packetId: packet.packetId,
-        mode: packet.mode,
-        riskLevel: packet.risk?.level || "unknown",
-        approvalRequired: packet.userApproval || false,
-        diffRequired: packet.diffRequired || false,
-        proofStepCount: (packet.proofRequired || []).filter((p) => p.required).length,
-        allowedActionCount: (packet.allowedScope?.actions || []).length,
-        blockedFileCount: (packet.blockedScope?.files || []).length,
-        blockedActionCount: (packet.blockedScope?.actions || []).length,
-        targetWorker: packet.targetWorker || "unknown",
-      },
-    });
-  } catch {
-    // non-blocking
-  }
-
-  return { packetPath: LATEST_PACKET_REL };
-}
-
-function buildExecutionPacketSurface(cwd, options = {}) {
-  const absPath = path.join(cwd, LATEST_PACKET_REL);
-  const packet = safeReadJson(absPath);
-  if (!packet) {
-    return {
-      status: "not_run",
-      latestPacketPath: null,
-      mode: null,
-      riskLevel: null,
-      approvalRequired: false,
-      proofRequired: false,
-      nextAction: "Run `avorelo execution-packet <task>` to compile an execution packet.",
-    };
-  }
-  return {
-    status: "ready",
-    latestPacketPath: LATEST_PACKET_REL,
-    mode: packet.mode,
-    riskLevel: packet.risk?.level || "unknown",
-    approvalRequired: packet.userApproval || false,
-    proofRequired: (packet.requiredAfterWrite || []).length > 0,
-    nextAction: packet.safeNextAction || null,
-  };
-}
-
-function formatExecutionPacketText(packet, options = {}) {
-  const debug = options.debug || false;
-
-  const lines = [
-    "Avorelo prepared a scoped work packet.",
-    "",
-    "Ready:",
-    `  Goal:      ${packet.goal}`,
-    `  Mode:      ${packet.mode}`,
-    `  Risk:      ${packet.risk?.level || "unknown"}`,
-    "",
-    "Protected:",
-    `  Blocked files: ${(packet.blockedScope?.files || []).length} patterns · Blocked actions: ${(packet.blockedScope?.actions || []).length}`,
-    `  Secrets/auth/billing/deploy blocked by default.`,
-    packet.userApproval ? `  ⚠ Approval required before executing.` : null,
-    "",
-    "Proof required:",
-    ...(packet.requiredAfterWrite || []).length > 0
-      ? (packet.requiredAfterWrite || []).map((s) => `  - ${s}`)
-      : ["  - Manual review (no automated proof configured)."],
-    "",
-    `Next: ${packet.safeNextAction}`,
-    `Packet: ${LATEST_PACKET_REL}`,
-  ].filter((l) => l !== null);
-
-  if (debug) {
-    lines.push(
-      "",
-      "--- Debug ---",
-      `Packet ID: ${packet.packetId}`,
-      `Target worker: ${packet.targetWorker}`,
-      `Diff before write: ${packet.diffRequired}`,
-      `Allowed areas: ${(packet.allowedScope?.areas || []).join(", ") || "none"}`,
-      `Allowed actions: ${(packet.allowedScope?.actions || []).join(", ")}`,
-      `Blocked dirs: ${(packet.blockedScope?.dirs || []).join(", ")}`,
-      `Risk reasons: ${(packet.risk?.reasons || []).join("; ")}`,
-      `Orchestration ref: ${packet.orchestrationPlanRef || "none"}`,
-      `Project profile ref: ${packet.projectProfileRef || "none"}`,
-      ...(packet.caveats || []).map((c) => `Caveat: ${c}`),
-    );
-  }
-
-  return lines.join("\n") + "\n";
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  LATEST_PACKET_REL,
-  MODES,
-  compileExecutionPacket,
-  compileAgentPrompt,
-  writeExecutionPacket,
-  buildExecutionPacketSurface,
-  formatExecutionPacketText,
-};