avorelo 0.3.8 → 0.4.0-rc.2

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

@@ -0,0 +1,976 @@
+"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 verify`." : 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,
+};