avorelo 0.1.0 → 0.3.0

package/scripts/lib/work-aware-orchestration.js

@@ -1,976 +0,0 @@
-"use strict";
-
-// ── Work-Aware Orchestration ──────────────────────────────────────────────────
-//
-// Contract: avorelo.workOrchestration.v1
-//
-// Deterministic work orchestration: classifies a task, splits it into stages,
-// selects cheapest capable safe worker per stage, selects focused context per
-// stage from workspace hygiene metadata, builds stage-aware handoff, and writes
-// evidence-backed value receipts.
-//
-// No network calls. No LLM calls. No script execution. Local only.
-
-const fs = require("fs");
-const path = require("path");
-
-const CONTRACT = "avorelo.workOrchestration.v1";
-const SCHEMA_VERSION = 1;
-
-const LATEST_PLAN_REL = ".claude/cco/orchestration/work-aware-orchestration/latest-plan.json";
-const STAGES_DIR_REL = ".claude/cco/orchestration/work-aware-orchestration/stages";
-
-// ── Task types ────────────────────────────────────────────────────────────────
-
-const TASK_TYPES = [
-  "repo_inspection",
-  "planning",
-  "implementation",
-  "refactor",
-  "bug_fix",
-  "test_or_verification",
-  "security_sensitive",
-  "deployment_release",
-  "documentation",
-  "handoff",
-  "summarization",
-  "unknown",
-];
-
-const COMPLEXITY = ["low", "medium", "high"];
-const RISK_LEVELS = ["low", "medium", "high", "critical"];
-const CONTEXT_PRESSURE = ["low", "medium", "high"];
-
-// ── Worker roles ──────────────────────────────────────────────────────────────
-
-const WORKER_ROLES = [
-  "local_or_cheap",
-  "strong_model",
-  "local_test_runner",
-  "reviewed_tool",
-  "human_approval",
-  "none_available",
-];
-
-// ── Reason codes ──────────────────────────────────────────────────────────────
-
-const WORKER_REASON_CODES = {
-  WORKER_SUPPORTS_STAGE: "WORKER_SUPPORTS_STAGE",
-  WORKER_LOW_COST_FOR_LOW_RISK: "WORKER_LOW_COST_FOR_LOW_RISK",
-  STRONG_WORKER_RESERVED_FOR_CRITICAL_STAGE: "STRONG_WORKER_RESERVED_FOR_CRITICAL_STAGE",
-  LOCAL_TEST_RUNNER_FOR_VERIFICATION: "LOCAL_TEST_RUNNER_FOR_VERIFICATION",
-  WORKER_UNAVAILABLE: "WORKER_UNAVAILABLE",
-  WORKER_RECENTLY_LIMITED: "WORKER_RECENTLY_LIMITED",
-  WORKER_CONTEXT_TOO_SMALL: "WORKER_CONTEXT_TOO_SMALL",
-  WORKER_TRUST_TOO_LOW: "WORKER_TRUST_TOO_LOW",
-  WORKER_RISK_TOO_HIGH: "WORKER_RISK_TOO_HIGH",
-  FALLBACK_ALLOWED: "FALLBACK_ALLOWED",
-  FALLBACK_BLOCKED_QUALITY: "FALLBACK_BLOCKED_QUALITY",
-  FALLBACK_BLOCKED_SAFETY: "FALLBACK_BLOCKED_SAFETY",
-};
-
-const CONTEXT_REASON_CODES = {
-  UNKNOWN_ASSET_EXCLUDED: "UNKNOWN_ASSET_EXCLUDED",
-  HIGH_CONTEXT_COST_EXCLUDED: "HIGH_CONTEXT_COST_EXCLUDED",
-  HIGH_RISK_ASSET_EXCLUDED: "HIGH_RISK_ASSET_EXCLUDED",
-  SKILL_BODY_EXCLUDED: "SKILL_BODY_EXCLUDED",
-  SECRET_LIKE_EXCLUDED: "SECRET_LIKE_EXCLUDED",
-  STAGE_BUDGET_EXCEEDED: "STAGE_BUDGET_EXCEEDED",
-  WORKSPACE_HYGIENE_USED: "WORKSPACE_HYGIENE_USED",
-  NO_HYGIENE_REPORT: "NO_HYGIENE_REPORT",
-  INSPECT_MAP_FIRST: "INSPECT_MAP_FIRST",
-};
-
-// ── Stage budgets (tokens) ────────────────────────────────────────────────────
-
-const STAGE_TOKEN_BUDGETS = {
-  inspect: 4000,
-  plan: 8000,
-  implement: 16000,
-  verify: 4000,
-  review: 8000,
-  handoff: 4000,
-  summarize: 4000,
-};
-
-const LOCAL_WORKER_TOKEN_CAP = 4000;
-
-// ── Keyword helpers ───────────────────────────────────────────────────────────
-
-function includesAny(text, patterns) {
-  const t = String(text || "").toLowerCase();
-  return patterns.some((p) => t.includes(p.toLowerCase()));
-}
-
-// ── Phase 4: Task Classification ─────────────────────────────────────────────
-
-const SECURITY_KEYWORDS = ["security", "auth", "authentication", "authorization", "secret", "secrets", "token", "tokens", "key", "credential", "credentials", "permission", "permissions", "policy", "policies", "oauth", "jwt", "password", "encrypt"];
-const DEPLOY_KEYWORDS = ["deploy", "deployment", "release", "ship", "ci/cd", "pipeline", "prod", "production", "infra", "terraform", "docker", "publish", "migrate"];
-const CUSTOMER_DATA_KEYWORDS = ["customer", "customer data", "pii", "personal data", "user data", "billing", "payment", "subscription"];
-const DESTRUCTIVE_KEYWORDS = ["delete", "remove", "drop", "truncate", "rm -rf", "destroy", "wipe", "rollback", "revert", "reset"];
-const REFACTOR_KEYWORDS = ["refactor", "rename", "cleanup", "reorganize", "restructure", "extract", "move", "split", "merge module"];
-const IMPLEMENTATION_KEYWORDS = ["implement", "build", "add", "create", "write", "develop", "feature", "functionality", "endpoint", "api", "component"];
-const INSPECT_KEYWORDS = ["inspect", "read", "scan", "review files", "look at", "examine", "explore", "understand", "find", "grep"];
-const DOCS_KEYWORDS = ["docs", "documentation", "readme", "guide", "summary", "summarize", "explain", "describe", "changelog"];
-const TEST_KEYWORDS = ["test", "tests", "spec", "coverage", "verify", "validation", "assert", "check"];
-const BUG_KEYWORDS = ["bug", "fix", "broken", "error", "issue", "crash", "regression", "debug", "patch"];
-const BROAD_KEYWORDS = ["all files", "entire codebase", "all skills", "every file", "broad", "full scan", "review all", "check all"];
-
-function classifyWorkTask(input) {
-  const text = String(input || "");
-
-  // Task type
-  let taskType = "unknown";
-  if (includesAny(text, SECURITY_KEYWORDS)) taskType = "security_sensitive";
-  else if (includesAny(text, DEPLOY_KEYWORDS)) taskType = "deployment_release";
-  else if (includesAny(text, REFACTOR_KEYWORDS)) taskType = "refactor";
-  else if (includesAny(text, BUG_KEYWORDS)) taskType = "bug_fix";
-  else if (includesAny(text, TEST_KEYWORDS)) taskType = "test_or_verification";
-  else if (includesAny(text, DOCS_KEYWORDS)) taskType = "documentation";
-  else if (includesAny(text, INSPECT_KEYWORDS) && !includesAny(text, IMPLEMENTATION_KEYWORDS)) taskType = "repo_inspection";
-  else if (includesAny(text, IMPLEMENTATION_KEYWORDS)) taskType = "implementation";
-  else if (text.trim()) taskType = "implementation";
-
-  // Handoff/summarization overrides
-  if (includesAny(text, ["handoff", "hand off", "hand-off", "next worker", "next session"])) taskType = "handoff";
-  if (includesAny(text, ["summarize", "summarization", "summary"])) taskType = "summarization";
-
-  // Risk level
-  let riskLevel = "medium";
-  if (includesAny(text, SECURITY_KEYWORDS) || includesAny(text, CUSTOMER_DATA_KEYWORDS)) riskLevel = "critical";
-  else if (includesAny(text, DEPLOY_KEYWORDS) || includesAny(text, DESTRUCTIVE_KEYWORDS)) riskLevel = "high";
-  else if (["refactor", "bug_fix", "implementation"].includes(taskType)) riskLevel = "medium";
-  else if (["documentation", "repo_inspection", "summarization", "handoff", "test_or_verification"].includes(taskType)) riskLevel = "low";
-
-  // Complexity
-  let complexity = "medium";
-  if (["security_sensitive", "deployment_release"].includes(taskType)) complexity = "high";
-  else if (["refactor"].includes(taskType) && includesAny(text, ["multi-file", "architecture", "restructure", "all"])) complexity = "high";
-  else if (["documentation", "repo_inspection", "summarization", "handoff"].includes(taskType)) complexity = "low";
-  else if (text.length > 200) complexity = "high";
-
-  // Context pressure
-  let contextPressure = "medium";
-  if (includesAny(text, BROAD_KEYWORDS)) contextPressure = "high";
-  else if (["documentation", "summarization", "handoff", "repo_inspection"].includes(taskType)) contextPressure = "low";
-  else if (["security_sensitive", "deployment_release"].includes(taskType)) contextPressure = "low";
-
-  return {
-    summary: text.slice(0, 120),
-    taskType,
-    riskLevel,
-    complexity,
-    contextPressure,
-    redacted: true,
-  };
-}
-
-// ── Phase 5: Stage Planner ────────────────────────────────────────────────────
-
-function getStageQualityRequirement(stageId, riskLevel) {
-  if (stageId === "implement" && ["high", "critical"].includes(riskLevel)) return "high";
-  if (stageId === "review") return "high";
-  if (stageId === "verify") return "deterministic";
-  if (stageId === "inspect" && riskLevel === "critical") return "medium";
-  return "medium";
-}
-
-function getStageContextNeed(stageId) {
-  return { inspect: "small", plan: "medium", implement: "large", verify: "small", review: "medium", handoff: "small", summarize: "small" }[stageId] || "medium";
-}
-
-function getStageObjective(stageId, taskType, riskLevel) {
-  const objectives = {
-    inspect: "Scan relevant files and workspace state to understand scope before acting.",
-    plan: "Propose a safe, bounded implementation approach based on inspect findings.",
-    implement: "Make scoped changes with tests, following the plan from inspect/plan stages.",
-    verify: "Run focused tests, build checks, and proof gates to confirm correctness.",
-    review: "Adversarially review changes for security, quality, and correctness.",
-    handoff: "Summarize what was done, what not to redo, and the exact next action for the next worker.",
-    summarize: "Produce a compact human-readable summary of the work done and evidence collected.",
-  };
-  return objectives[stageId] || `Execute ${stageId} stage.`;
-}
-
-function getVerificationNextStep(stageId, taskType) {
-  if (stageId === "verify") return "Check test output and proof artifact for pass/fail.";
-  if (stageId === "implement") return "Run `avorelo verify` and focused tests for the changed files.";
-  if (stageId === "review") return "Confirm no security/quality issues remain before continuing.";
-  if (stageId === "handoff") return "Next worker reads handoff receipt and continues from last safe state.";
-  if (stageId === "inspect") return "Review inspect output before proceeding to plan/implement.";
-  return "Check output before proceeding to next stage.";
-}
-
-function getRecommendedWorkerRole(stageId, riskLevel, complexity, taskType) {
-  if (stageId === "verify") return "local_test_runner";
-  if (stageId === "inspect") return "local_or_cheap";
-  if (stageId === "handoff") return "local_or_cheap";
-  if (stageId === "summarize") return "local_or_cheap";
-  if (stageId === "review" && ["high", "critical"].includes(riskLevel)) return "reviewed_tool";
-  if (stageId === "implement" && riskLevel === "critical") return "strong_model";
-  if (stageId === "implement" && complexity === "high") return "strong_model";
-  if (stageId === "plan" && ["high", "critical"].includes(riskLevel)) return "strong_model";
-  return "local_or_cheap";
-}
-
-function getFallbackWorkerRole(recommendedRole, riskLevel) {
-  if (recommendedRole === "strong_model") return "none_available";
-  if (recommendedRole === "reviewed_tool" && ["high", "critical"].includes(riskLevel)) return "strong_model";
-  if (recommendedRole === "local_test_runner") return "local_or_cheap";
-  if (recommendedRole === "local_or_cheap") return "strong_model";
-  return "none_available";
-}
-
-function buildStagePlan(cwd, taskText, options = {}) {
-  const task = classifyWorkTask(taskText);
-  const { taskType, riskLevel, complexity, contextPressure } = task;
-
-  const stageIds = [];
-
-  // Always start with inspect
-  stageIds.push("inspect");
-
-  // Add plan stage for complex or security-sensitive work
-  if (["security_sensitive", "deployment_release"].includes(taskType) || complexity === "high") {
-    stageIds.push("plan");
-  }
-
-  // Core work stage
-  if (["documentation", "summarization"].includes(taskType)) {
-    stageIds.push("summarize");
-  } else if (taskType !== "repo_inspection" && taskType !== "handoff") {
-    stageIds.push("implement");
-  }
-
-  // Review for security/deploy
-  if (["security_sensitive", "deployment_release"].includes(taskType)) {
-    stageIds.push("review");
-  }
-
-  // Always verify for non-trivial work
-  if (!["documentation", "summarization", "repo_inspection", "handoff"].includes(taskType)) {
-    stageIds.push("verify");
-  }
-
-  // Always end with handoff
-  stageIds.push("handoff");
-
-  const stages = stageIds.map((stageId) => {
-    const recommendedWorker = getRecommendedWorkerRole(stageId, riskLevel, complexity, taskType);
-    const fallbackWorker = getFallbackWorkerRole(recommendedWorker, riskLevel);
-    const isCustomerVisible = stageId === "handoff" || stageId === "summarize";
-    return {
-      stageId,
-      objective: getStageObjective(stageId, taskType, riskLevel),
-      lifecycleStage: stageId,
-      riskLevel: (stageId === "implement" && ["high", "critical"].includes(riskLevel)) ? riskLevel : (["inspect", "handoff", "summarize"].includes(stageId) ? "low" : riskLevel),
-      contextNeed: getStageContextNeed(stageId),
-      qualityRequirement: getStageQualityRequirement(stageId, riskLevel),
-      recommendedWorker,
-      fallbackWorker,
-      workerSelection: null,
-      contextSelection: null,
-      continuation: {
-        safeNextAction: getVerificationNextStep(stageId, taskType),
-        verificationNextStep: stageId === "implement" ? "Run focused tests and `avorelo proof`." : null,
-        handoffRequired: stageId === "handoff" || stageId === "implement",
-      },
-      proofExpected: ["implement", "verify", "review"].includes(stageId),
-      customerVisible: isCustomerVisible,
-      debugVisible: true,
-      redacted: true,
-    };
-  });
-
-  return stages;
-}
-
-// ── Phase 6: Worker Selection Policy ─────────────────────────────────────────
-
-function selectWorkerForStage(cwd, stage, inventory, options = {}) {
-  const { stageId, riskLevel, recommendedWorker, fallbackWorker, contextNeed } = stage;
-  const tools = Array.isArray(inventory?.tools) ? inventory.tools : [];
-
-  const localCheapTools = tools.filter((t) =>
-    ["local_or_cheap"].includes(t.workerRole) ||
-    ["free_local", "local"].includes(t.costTier) ||
-    ["local", "lm_studio", "ollama", "aider", "opencode"].includes(t.toolId)
-  );
-
-  const strongTools = tools.filter((t) =>
-    t.qualityTier === "highest" || t.qualityTier === "high" ||
-    t.costTier === "premium" || t.costTier === "high" ||
-    ["claude_code", "gemini_cli"].includes(t.toolId)
-  );
-
-  const testRunners = tools.filter((t) =>
-    t.toolId === "test_runner" || t.toolId === "git" ||
-    (t.supportedRoles || []).includes("verify")
-  );
-
-  function isAvailable(tool) {
-    return !["unavailable", "missing", "stale", "disabled_by_user"].includes(tool.workerState) &&
-      tool.installStatus !== "not_installed" &&
-      tool.workerState !== "needs_login" &&
-      tool.workerState !== "recently_limited" &&
-      tool.workerState !== "recently_failed";
-  }
-
-  function isSafeForStage(tool, stRisk) {
-    if (["critical", "high"].includes(stRisk) && !tool.safeForHighRisk) {
-      if (["free_local", "local"].includes(tool.costTier) && tool.trustTier !== "local") return false;
-    }
-    return true;
-  }
-
-  const reasonCodes = [];
-  let selected = null;
-  let role = null;
-  let fallbackAllowed = false;
-  let fallbackBlocked = null;
-
-  // Verify stage: prefer local test runner
-  if (stageId === "verify") {
-    const runner = testRunners.find((t) => isAvailable(t));
-    if (runner) {
-      selected = runner.toolId;
-      role = "local_test_runner";
-      reasonCodes.push(WORKER_REASON_CODES.LOCAL_TEST_RUNNER_FOR_VERIFICATION);
-      reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-    } else {
-      const local = localCheapTools.find((t) => isAvailable(t));
-      if (local) {
-        selected = local.toolId;
-        role = "local_or_cheap";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-        reasonCodes.push(WORKER_REASON_CODES.FALLBACK_ALLOWED);
-      } else {
-        role = "none_available";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_UNAVAILABLE);
-      }
-    }
-  }
-  // Inspect / handoff / summarize: prefer local/cheap
-  else if (["inspect", "handoff", "summarize"].includes(stageId)) {
-    const local = localCheapTools.find((t) => isAvailable(t) && isSafeForStage(t, riskLevel));
-    if (local) {
-      selected = local.toolId;
-      role = "local_or_cheap";
-      reasonCodes.push(WORKER_REASON_CODES.WORKER_LOW_COST_FOR_LOW_RISK);
-      reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-    } else {
-      const strong = strongTools.find((t) => isAvailable(t));
-      if (strong) {
-        selected = strong.toolId;
-        role = "strong_model";
-        reasonCodes.push(WORKER_REASON_CODES.FALLBACK_ALLOWED);
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-        fallbackAllowed = true;
-      } else {
-        role = "none_available";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_UNAVAILABLE);
-      }
-    }
-  }
-  // Critical/high risk implement: must use strong model
-  else if (["implement", "plan", "review"].includes(stageId) && ["critical", "high"].includes(riskLevel)) {
-    const strong = strongTools.find((t) => isAvailable(t) && t.safeForHighRisk !== false);
-    if (strong) {
-      selected = strong.toolId;
-      role = "strong_model";
-      reasonCodes.push(WORKER_REASON_CODES.STRONG_WORKER_RESERVED_FOR_CRITICAL_STAGE);
-      reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-    } else {
-      const local = localCheapTools.find((t) => isAvailable(t) && t.trustTier === "local");
-      if (local && local.trustTier === "local") {
-        selected = local.toolId;
-        role = "local_or_cheap";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-        fallbackAllowed = true;
-        reasonCodes.push(WORKER_REASON_CODES.FALLBACK_ALLOWED);
-      } else {
-        role = "none_available";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_UNAVAILABLE);
-        if (localCheapTools.length > 0) {
-          fallbackBlocked = WORKER_REASON_CODES.FALLBACK_BLOCKED_SAFETY;
-          reasonCodes.push(WORKER_REASON_CODES.FALLBACK_BLOCKED_SAFETY);
-        }
-      }
-    }
-  }
-  // Medium risk implement: prefer strong but allow local if capable
-  else {
-    const strong = strongTools.find((t) => isAvailable(t));
-    if (strong) {
-      selected = strong.toolId;
-      role = "strong_model";
-      reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-    } else {
-      const local = localCheapTools.find((t) => isAvailable(t));
-      if (local) {
-        selected = local.toolId;
-        role = "local_or_cheap";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_SUPPORTS_STAGE);
-        reasonCodes.push(WORKER_REASON_CODES.FALLBACK_ALLOWED);
-        fallbackAllowed = true;
-      } else {
-        role = "none_available";
-        reasonCodes.push(WORKER_REASON_CODES.WORKER_UNAVAILABLE);
-      }
-    }
-  }
-
-  const toolMeta = tools.find((t) => t.toolId === selected);
-
-  return {
-    selected: selected || "none",
-    role,
-    costTier: toolMeta?.costTier || "unknown",
-    qualityTier: toolMeta?.qualityTier || "unknown",
-    trustLevel: toolMeta?.trustTier || "unknown",
-    availability: toolMeta?.availability || "unknown",
-    fallbackAllowed,
-    fallbackBlocked,
-    reasonCodes,
-  };
-}
-
-// ── Phase 7: Workspace Relevance / Context Auto-Selection ─────────────────────
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function selectContextForStage(cwd, stage, workspaceHygieneReport, options = {}) {
-  const { stageId, contextNeed, riskLevel } = stage;
-  const assets = workspaceHygieneReport?.allAssets || [];
-  const reasonCodes = [];
-
-  const selectedAssetIds = [];
-  const selectedFiles = [];
-  const excludedAssetIds = [];
-
-  const budgetTokens = Math.min(
-    STAGE_TOKEN_BUDGETS[stageId] || 4000,
-    contextNeed === "small" ? LOCAL_WORKER_TOKEN_CAP : (STAGE_TOKEN_BUDGETS[stageId] || 8000)
-  );
-
-  let estimatedTokens = 0;
-  let source = "none";
-  let contextPackRef = null;
-
-  if (assets.length > 0) {
-    source = "ai_workspace_hygiene";
-    reasonCodes.push(CONTEXT_REASON_CODES.WORKSPACE_HYGIENE_USED);
-
-    for (const asset of assets) {
-      const isUnknown = asset.reviewStatus === "unknown";
-      const isHighRisk = asset.contextCost === "high" || asset.trustLevel === "low";
-      const isSkillBody = asset.assetType === "skill" && asset.fullBodyRisk;
-      const isSecretLike = (asset.findingCodes || []).includes("SECRET_LIKE_REFERENCE");
-
-      if (isUnknown) {
-        excludedAssetIds.push(asset.id || asset.name);
-        continue;
-      }
-      if (isSecretLike) {
-        excludedAssetIds.push(asset.id || asset.name);
-        reasonCodes.push(CONTEXT_REASON_CODES.SECRET_LIKE_EXCLUDED);
-        continue;
-      }
-      if (isHighRisk && stageId !== "review") {
-        excludedAssetIds.push(asset.id || asset.name);
-        reasonCodes.push(CONTEXT_REASON_CODES.HIGH_CONTEXT_COST_EXCLUDED);
-        continue;
-      }
-      if (isSkillBody) {
-        excludedAssetIds.push(asset.id || asset.name);
-        reasonCodes.push(CONTEXT_REASON_CODES.SKILL_BODY_EXCLUDED);
-        continue;
-      }
-
-      // Stage relevance filter
-      const stageHints = asset.stageHints || [];
-      if (stageHints.length > 0 && !stageHints.includes(stageId) && !stageHints.includes("all")) continue;
-
-      const tokenEstimate = asset.estimatedTokens || 100;
-      if (estimatedTokens + tokenEstimate > budgetTokens) {
-        reasonCodes.push(CONTEXT_REASON_CODES.STAGE_BUDGET_EXCEEDED);
-        continue;
-      }
-
-      estimatedTokens += tokenEstimate;
-      if (asset.id) selectedAssetIds.push(asset.id);
-      if (asset.filePath) selectedFiles.push(asset.filePath);
-    }
-
-    if (selectedAssetIds.length === 0 && stageId === "inspect") {
-      reasonCodes.push(CONTEXT_REASON_CODES.INSPECT_MAP_FIRST);
-    }
-  } else {
-    // No hygiene report — use manual fallback
-    source = assets.length === 0 && !workspaceHygieneReport ? "none" : "manual_fallback";
-    reasonCodes.push(CONTEXT_REASON_CODES.NO_HYGIENE_REPORT);
-    if (stageId === "inspect") {
-      reasonCodes.push(CONTEXT_REASON_CODES.INSPECT_MAP_FIRST);
-    }
-  }
-
-  const packPath = `${STAGES_DIR_REL}/${stageId}-context-pack.json`;
-  if (cwd) {
-    contextPackRef = path.join(cwd, packPath).replace(/\\/g, "/");
-  }
-
-  const unknownAssetsExcluded = excludedAssetIds.length;
-
-  return {
-    source,
-    selectedAssetIds,
-    selectedFiles,
-    excludedAssetIds,
-    unknownAssetsExcluded,
-    estimatedTokens,
-    budgetTokens,
-    contextPackRef,
-    reasonCodes,
-  };
-}
-
-// ── Phase 8: Stage Context Pack Writing ───────────────────────────────────────
-
-function writeStageContextPack(cwd, stageId, contextSelection, stage) {
-  const dir = path.join(cwd, STAGES_DIR_REL);
-  fs.mkdirSync(dir, { recursive: true });
-
-  const pack = {
-    stageId,
-    source: contextSelection.source,
-    selectedAssetIds: contextSelection.selectedAssetIds,
-    selectedFiles: contextSelection.selectedFiles,
-    estimatedTokens: contextSelection.estimatedTokens,
-    budgetTokens: contextSelection.budgetTokens,
-    contextPackRef: contextSelection.contextPackRef,
-    reasonCodes: contextSelection.reasonCodes,
-    constraints: {
-      noSecrets: true,
-      noRawPrompt: true,
-      noRawThirdPartySkillBodies: true,
-      noUnknownAssets: true,
-    },
-    redacted: true,
-  };
-
-  const packPath = path.join(dir, `${stageId}-context-pack.json`);
-  fs.writeFileSync(packPath, JSON.stringify(pack, null, 2), "utf8");
-  return packPath;
-}
-
-// ── Phase 9: Stage-Aware Handoff ─────────────────────────────────────────────
-
-function buildStageHandoff(cwd, orchestrationPlan, options = {}) {
-  const stages = orchestrationPlan.stages || [];
-  const handoffStage = stages.find((s) => s.stageId === "handoff");
-  const lastImplementStage = [...stages].reverse().find((s) => ["implement", "review", "verify"].includes(s.stageId));
-
-  const nextStage = handoffStage || stages[stages.length - 1];
-  const nextWorkerRole = nextStage?.workerSelection?.role || handoffStage?.recommendedWorker || "strong_model";
-
-  const doneStages = stages.filter((s) => s.stageId !== "handoff").map((s) => s.stageId);
-
-  return {
-    contract: "avorelo.stageHandoff.v1",
-    whatWasDone: doneStages,
-    doNotRedo: doneStages,
-    currentBranch: null,
-    relevantFiles: lastImplementStage?.contextSelection?.selectedFiles || [],
-    contextPackRefs: stages
-      .filter((s) => s.contextSelection?.contextPackRef)
-      .map((s) => ({ stageId: s.stageId, path: s.contextSelection.contextPackRef })),
-    riskConstraints: {
-      riskLevel: orchestrationPlan.task?.riskLevel || "medium",
-      noAutoTrustUnknownAssets: true,
-      noDestructiveActionsWithoutGuard: true,
-    },
-    selectedNextStage: nextStage?.stageId || "handoff",
-    selectedWorkerRole: nextWorkerRole,
-    verificationNextStep: lastImplementStage?.continuation?.verificationNextStep || "Run `avorelo verify` and focused tests.",
-    nextAction: orchestrationPlan.nextAction || "Continue with the next stage.",
-    proofPaths: [LATEST_PLAN_REL],
-    redacted: true,
-  };
-}
-
-// ── Phase 10: Receipts / Value Evidence ───────────────────────────────────────
-
-function buildValueEvidence(plan) {
-  const stages = plan.stages || [];
-
-  const localOrCheapStages = stages.filter((s) => s.workerSelection?.role === "local_or_cheap").length;
-  const strongWorkerStages = stages.filter((s) => s.workerSelection?.role === "strong_model").length;
-  const verificationStages = stages.filter((s) => s.stageId === "verify").length;
-  const handoffStages = stages.filter((s) => s.stageId === "handoff").length;
-
-  const allContextSelections = stages.map((s) => s.contextSelection).filter(Boolean);
-  const unknownAssetsExcluded = allContextSelections.reduce((sum, cs) => sum + (cs.unknownAssetsExcluded || 0), 0);
-  const highContextAssetsExcluded = allContextSelections.filter((cs) => cs.reasonCodes?.includes(CONTEXT_REASON_CODES.HIGH_CONTEXT_COST_EXCLUDED)).length;
-
-  const contextTokensFromReceipt = allContextSelections.reduce((sum, cs) => sum + (cs.estimatedTokens || 0), 0);
-
-  return {
-    localOrCheapStages,
-    strongWorkerStages,
-    verificationStages,
-    handoffStages,
-    premiumStagesReserved: strongWorkerStages > 0 ? `${strongWorkerStages} stage(s) reserved for strong model (evidence: critical/high risk or complexity)` : null,
-    contextTokensConsumed: contextTokensFromReceipt,
-    unknownAssetsExcluded,
-    highContextAssetsExcluded,
-    manualDecisionsAvoided: "automatic mode applied silently for low-risk stage decisions",
-    repeatedWorkAvoided: null,
-    verificationPrepared: verificationStages > 0,
-    verificationCompleted: null,
-    caveats: [
-      "Stage plan and worker selection are evidence-based estimates, not guarantees.",
-      "Actual savings depend on worker availability and task complexity at execution time.",
-      "No exact dollar or token savings claimed — counts are from the stage plan only.",
-    ],
-    redacted: true,
-  };
-}
-
-function writeWorkOrchestrationReceipt(cwd, plan) {
-  const dir = path.dirname(path.join(cwd, LATEST_PLAN_REL));
-  fs.mkdirSync(dir, { recursive: true });
-
-  const latestPath = path.join(cwd, LATEST_PLAN_REL);
-  fs.writeFileSync(latestPath, JSON.stringify(plan, null, 2), "utf8");
-
-  return latestPath;
-}
-
-// ── Orchestration plan builder ────────────────────────────────────────────────
-
-function buildWorkOrchestrationPlan(cwd, taskText, options = {}) {
-  const mode = options.mode || "automatic";
-  const task = classifyWorkTask(taskText);
-
-  // Load inventory if available
-  let inventory = options.inventory || null;
-  if (!inventory) {
-    try {
-      const { loadInventory } = require("./orchestration/inventory");
-      inventory = loadInventory(cwd, { refreshLevel: "cache" });
-    } catch {
-      inventory = { tools: [] };
-    }
-  }
-
-  // Load workspace hygiene if available
-  let hygieneReport = options.hygieneReport || null;
-  if (!hygieneReport) {
-    try {
-      const reportPath = path.join(cwd, ".claude/cco/orchestration/ai-workspace-hygiene/latest-report-debug.json");
-      hygieneReport = safeReadJson(reportPath);
-    } catch {
-      hygieneReport = null;
-    }
-  }
-
-  // Build stages
-  const rawStages = buildStagePlan(cwd, taskText, options);
-
-  // Enrich stages with worker and context selection
-  const stages = rawStages.map((stage) => {
-    const workerSelection = selectWorkerForStage(cwd, stage, inventory, options);
-    const contextSelection = selectContextForStage(cwd, stage, hygieneReport, options);
-
-    // Write stage context packs
-    try {
-      writeStageContextPack(cwd, stage.stageId, contextSelection, stage);
-    } catch {
-      // best-effort
-    }
-
-    return { ...stage, workerSelection, contextSelection };
-  });
-
-  const summary = {
-    stageCount: stages.length,
-    localOrCheapStages: stages.filter((s) => s.workerSelection?.role === "local_or_cheap").length,
-    strongWorkerStages: stages.filter((s) => s.workerSelection?.role === "strong_model").length,
-    verificationStages: stages.filter((s) => s.stageId === "verify").length,
-    handoffStages: stages.filter((s) => s.stageId === "handoff").length,
-    unknownAssetsExcluded: stages.reduce((sum, s) => sum + (s.contextSelection?.unknownAssetsExcluded || 0), 0),
-    highContextAssetsExcluded: stages.filter((s) => s.contextSelection?.reasonCodes?.includes(CONTEXT_REASON_CODES.HIGH_CONTEXT_COST_EXCLUDED)).length,
-  };
-
-  const firstPendingStage = stages.find((s) => s.stageId !== "handoff") || stages[0];
-  const nextAction = firstPendingStage
-    ? `Continue with the '${firstPendingStage.stageId}' stage using a ${firstPendingStage.workerSelection?.role || "capable"} worker.`
-    : "Review the orchestration plan and begin with the inspect stage.";
-
-  const plan = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    createdAt: new Date().toISOString(),
-    mode,
-    task,
-    stages,
-    summary,
-    valueEvidence: null,
-    nextAction,
-    receipts: [],
-    redacted: true,
-  };
-
-  // Add value evidence
-  plan.valueEvidence = buildValueEvidence(plan);
-
-  // Build handoff
-  plan.stageHandoff = buildStageHandoff(cwd, plan, options);
-
-  return plan;
-}
-
-// ── Phase 11: CLI Surfaces ────────────────────────────────────────────────────
-
-function buildWorkOrchestrationSurface(cwd) {
-  const latestPath = path.join(cwd, LATEST_PLAN_REL);
-  const plan = safeReadJson(latestPath);
-
-  if (!plan) {
-    return {
-      status: "not_run",
-      latestPlanPath: null,
-      stageCount: 0,
-      localOrCheapStages: 0,
-      strongWorkerStages: 0,
-      unknownAssetsExcluded: 0,
-      highContextAssetsExcluded: 0,
-      nextAction: "Run `avorelo orchestrate <task>` to build a work plan.",
-    };
-  }
-
-  return {
-    status: "planned",
-    latestPlanPath: LATEST_PLAN_REL,
-    stageCount: plan.summary?.stageCount || 0,
-    localOrCheapStages: plan.summary?.localOrCheapStages || 0,
-    strongWorkerStages: plan.summary?.strongWorkerStages || 0,
-    unknownAssetsExcluded: plan.summary?.unknownAssetsExcluded || 0,
-    highContextAssetsExcluded: plan.summary?.highContextAssetsExcluded || 0,
-    nextAction: plan.nextAction || null,
-  };
-}
-
-function formatWorkOrchestrationText(plan, options = {}) {
-  const isDebug = options.debug === true;
-
-  if (!plan || !plan.stages) {
-    return "No work orchestration plan available.";
-  }
-
-  const { task, stages, summary, valueEvidence, nextAction } = plan;
-
-  const lines = [
-    "Avorelo prepared the work plan.",
-    "",
-    "Done:",
-    `- Split task into ${summary.stageCount} stage(s): ${stages.map((s) => s.stageId).join(", ")}.`,
-    `- Prepared focused context for each stage.`,
-  ];
-
-  if (summary.strongWorkerStages > 0) {
-    lines.push(`- Reserved strong worker for ${summary.strongWorkerStages} critical stage(s).`);
-  }
-
-  lines.push("", "Saved:");
-  if (summary.localOrCheapStages > 0) {
-    lines.push(`- Used local/cheap worker for ${summary.localOrCheapStages} low-risk stage(s).`);
-  }
-  if (summary.unknownAssetsExcluded > 0) {
-    lines.push(`- Avoided broad workspace context (unknown assets excluded).`);
-  }
-
-  lines.push("", "Protected:");
-  if (summary.unknownAssetsExcluded > 0) {
-    lines.push(`- Excluded ${summary.unknownAssetsExcluded} unknown/high-risk workspace asset(s) from automatic context.`);
-  }
-  lines.push("- Kept destructive/deploy actions behind guard.");
-
-  lines.push("", `Next:`);
-  lines.push(`- ${nextAction}`);
-
-  if (isDebug) {
-    lines.push("", "--- Debug: Stage Plan ---");
-    for (const stage of stages) {
-      lines.push(`Stage: ${stage.stageId}`);
-      lines.push(`  Objective: ${stage.objective}`);
-      lines.push(`  Risk: ${stage.riskLevel} | Context: ${stage.contextNeed} | Quality: ${stage.qualityRequirement}`);
-      lines.push(`  Worker: ${stage.workerSelection?.selected || "none"} (role: ${stage.workerSelection?.role})`);
-      lines.push(`  Worker reason codes: ${(stage.workerSelection?.reasonCodes || []).join(", ")}`);
-      lines.push(`  Context source: ${stage.contextSelection?.source}`);
-      lines.push(`  Context assets: ${(stage.contextSelection?.selectedAssetIds || []).length} selected, ${(stage.contextSelection?.excludedAssetIds || []).length} excluded`);
-      lines.push(`  Context reason codes: ${(stage.contextSelection?.reasonCodes || []).join(", ")}`);
-      lines.push(`  Context tokens: ~${stage.contextSelection?.estimatedTokens || 0}`);
-      lines.push("");
-    }
-    lines.push("--- Debug: Value Evidence ---");
-    lines.push(`  localOrCheapStages: ${valueEvidence?.localOrCheapStages}`);
-    lines.push(`  strongWorkerStages: ${valueEvidence?.strongWorkerStages}`);
-    lines.push(`  unknownAssetsExcluded: ${valueEvidence?.unknownAssetsExcluded}`);
-    lines.push(`  highContextAssetsExcluded: ${valueEvidence?.highContextAssetsExcluded}`);
-    lines.push(`  verificationPrepared: ${valueEvidence?.verificationPrepared}`);
-    lines.push("");
-    if (valueEvidence?.caveats) {
-      lines.push("Caveats:");
-      for (const c of valueEvidence.caveats) lines.push(`  - ${c}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-// ── Product learning events ───────────────────────────────────────────────────
-
-function emitOrchestrationEvents(cwd, plan) {
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    const { stages, summary, task } = plan;
-
-    appendProductLearningEvent(cwd, {
-      eventName: "work_orchestration_plan_generated",
-      category: "work_orchestration",
-      surface: "local",
-      status: "observed",
-      payload: {
-        stageCount: summary.stageCount,
-        localOrCheapStages: summary.localOrCheapStages,
-        strongWorkerStages: summary.strongWorkerStages,
-        verificationStages: summary.verificationStages,
-        unknownAssetsExcluded: summary.unknownAssetsExcluded,
-        taskType: task.taskType,
-        riskLevel: task.riskLevel,
-        complexity: task.complexity,
-      },
-    });
-
-    for (const stage of stages) {
-      if (stage.workerSelection?.role === "local_or_cheap") {
-        appendProductLearningEvent(cwd, {
-          eventName: "local_or_cheap_stage_used",
-          category: "work_orchestration",
-          surface: "local",
-          status: "observed",
-          payload: {
-            stageId: stage.stageId,
-            workerRole: stage.workerSelection.role,
-            reasonCodes: stage.workerSelection.reasonCodes,
-          },
-        });
-      }
-      if (stage.workerSelection?.role === "strong_model") {
-        appendProductLearningEvent(cwd, {
-          eventName: "strong_worker_reserved",
-          category: "work_orchestration",
-          surface: "local",
-          status: "observed",
-          payload: {
-            stageId: stage.stageId,
-            workerRole: stage.workerSelection.role,
-            reasonCodes: stage.workerSelection.reasonCodes,
-          },
-        });
-      }
-      if ((stage.contextSelection?.unknownAssetsExcluded || 0) > 0) {
-        appendProductLearningEvent(cwd, {
-          eventName: "unknown_workspace_asset_excluded",
-          category: "work_orchestration",
-          surface: "local",
-          status: "observed",
-          payload: {
-            stageId: stage.stageId,
-            count: stage.contextSelection.unknownAssetsExcluded,
-          },
-        });
-      }
-    }
-
-    if (summary.unknownAssetsExcluded > 0) {
-      appendProductLearningEvent(cwd, {
-        eventName: "workspace_relevance_used",
-        category: "work_orchestration",
-        surface: "local",
-        status: "observed",
-        payload: {
-          unknownAssetsExcluded: summary.unknownAssetsExcluded,
-          highContextAssetsExcluded: summary.highContextAssetsExcluded,
-        },
-      });
-    }
-
-    appendProductLearningEvent(cwd, {
-      eventName: "stage_handoff_prepared",
-      category: "work_orchestration",
-      surface: "local",
-      status: "observed",
-      payload: {
-        handoffStages: summary.handoffStages,
-        stageCount: summary.stageCount,
-      },
-    });
-
-    appendProductLearningEvent(cwd, {
-      eventName: "orchestration_value_evidence_written",
-      category: "work_orchestration",
-      surface: "local",
-      status: "observed",
-      payload: {
-        localOrCheapStages: summary.localOrCheapStages,
-        strongWorkerStages: summary.strongWorkerStages,
-        unknownAssetsExcluded: summary.unknownAssetsExcluded,
-      },
-    });
-  } catch {
-    // product learning is best-effort
-  }
-}
-
-// ── Main entrypoint ───────────────────────────────────────────────────────────
-
-function runWorkOrchestration(cwd, taskText, options = {}) {
-  const plan = buildWorkOrchestrationPlan(cwd, taskText, options);
-
-  const receiptPath = writeWorkOrchestrationReceipt(cwd, plan);
-  plan.receipts = [receiptPath];
-
-  emitOrchestrationEvents(cwd, plan);
-
-  return plan;
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  LATEST_PLAN_REL,
-  TASK_TYPES,
-  WORKER_ROLES,
-  WORKER_REASON_CODES,
-  CONTEXT_REASON_CODES,
-  classifyWorkTask,
-  buildStagePlan,
-  selectWorkerForStage,
-  selectContextForStage,
-  buildStageHandoff,
-  writeWorkOrchestrationReceipt,
-  buildWorkOrchestrationSurface,
-  formatWorkOrchestrationText,
-  buildWorkOrchestrationPlan,
-  buildValueEvidence,
-  runWorkOrchestration,
-};