avorelo 0.3.1 → 0.3.2

package/README.md

@@ -1,8 +1,10 @@
 # Avorelo
 
-**AI Work Control.** Avorelo runs *around* your AI coding tool. It does not generate code — it keeps the
-work focused, keeps secrets out of the model and out of cloud, and saves proof of what actually happened,
-locally.
+**AI Work Control.** Keep using your AI coding tool. Avorelo runs *around* it to keep the work focused,
+keep secrets out of the model and out of cloud, and save proof of what actually happened, locally.
+
+Avorelo is not an agent framework, agent runtime, or replacement for Claude Code, Codex, Cursor, or your
+existing workflow. It adds control, receipts, approvals, and proof around the work.
 
 > Status: **private alpha** (`0.2.0`). Local-first and deterministic. See the limitations below.
 
@@ -56,8 +58,11 @@ avorelo control-center --target .
 | Command | What it does |
 |---|---|
 | `avorelo run "<task>"` | The runtime product flow above |
-| `avorelo control-center` | Read-only local view of all session/proof/value state |
-| `avorelo open` | Local receipts dashboard (HTML/text/json) |
+| `avorelo control-center` | Read-only local view of all session/proof/value state |
+| `avorelo controls list` · `avorelo controls explain <control>` | Inspect built-in Work Controls and where they fire |
+| `avorelo receipt latest` | Show the latest local receipt |
+| `avorelo proof check` | Validate the latest proof status |
+| `avorelo open` | Local receipts dashboard (HTML/text/json) |
 | `avorelo readiness` | Canonical readiness gate for this workspace |
 | `avorelo secret-boundary scan` | Detect + redact secrets in content (local, no network) |
 | `avorelo context compile "<task>"` | Show the bounded context packet |

package/dist/avorelo.mjs

@@ -362,6 +362,16 @@ function listReceipts(dir) {
   }
   return out;
 }
+function readReceipt(dir, receiptId) {
+  const path = join(localReceiptDir(dir), `${receiptId}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    const r2 = JSON.parse(readFileSync(path, "utf8"));
+    return r2 && typeof r2.receiptId === "string" ? r2 : null;
+  } catch {
+    return null;
+  }
+}
 var init_receipts = __esm({
   "src/avorelo/kernel/receipts/index.ts"() {
     init_redaction();
@@ -5659,9 +5669,9 @@ function executeMultiAgentReview(reviewPlan, executorResult, plan, ctx) {
       break;
     }
   }
-  const finalVerdict = determineFinalVerdict(rounds, stopCondition);
+  const finalVerdict2 = determineFinalVerdict(rounds, stopCondition);
   const routedToManualGate = stopCondition === "REVIEWER_DISAGREEMENT" || stopCondition === "MAX_REVIEW_ROUNDS_REACHED" || stopCondition === "VERIFIER_OVERRIDE";
-  const modelConsensusOnly = finalVerdict === "approved" && rounds.every((r2) => r2.verifierPassed === null);
+  const modelConsensusOnly = finalVerdict2 === "approved" && rounds.every((r2) => r2.verifierPassed === null);
   const reasonCodes = [
     ...reviewPlan.triggerReasonCodes,
     `REVIEW_ROUNDS:${rounds.length}`,
@@ -5673,7 +5683,7 @@ function executeMultiAgentReview(reviewPlan, executorResult, plan, ctx) {
     attempted: true,
     roundsCompleted: rounds.length,
     maxRoundsReached: stopCondition === "MAX_REVIEW_ROUNDS_REACHED",
-    finalVerdict,
+    finalVerdict: finalVerdict2,
     rounds,
     totalDurationMs: Date.now() - start,
     reasonCodes,
@@ -6642,10 +6652,22 @@ function runPreflight(targetDir) {
       cacheOk = true;
       checks.push({ id: "npm_cache_writable", label: "npm cache directory accessible", passed: true, details: "cache directory exists" });
     } else {
-      checks.push({ id: "npm_cache_writable", label: "npm cache directory accessible", passed: false, details: "cache path does not exist", recovery: isWindows ? "Use a temporary cache: set npm_config_cache=%TEMP%\\npm-cache-avorelo && npx -y avorelo@latest activate" : "Use a temporary cache: npm_config_cache=$(mktemp -d) npx -y avorelo@latest activate" });
+      checks.push({
+        id: "npm_cache_writable",
+        label: "npm cache directory accessible",
+        passed: false,
+        details: "cache path does not exist",
+        recovery: isWindows ? 'Use a temporary cache. PowerShell: $env:npm_config_cache="$env:TEMP\\npm-cache-avorelo"; npx -y avorelo@latest activate. cmd.exe: cmd /c "set npm_config_cache=%TEMP%\\npm-cache-avorelo && npx -y avorelo@latest activate"' : "Use a temporary cache: npm_config_cache=$(mktemp -d) npx -y avorelo@latest activate"
+      });
     }
   } catch {
-    checks.push({ id: "npm_cache_writable", label: "npm cache directory accessible", passed: false, details: "could not read npm cache config", recovery: isWindows ? "Use a temporary cache: set npm_config_cache=%TEMP%\\npm-cache-avorelo && npx -y avorelo@latest activate" : "Use a temporary cache: npm_config_cache=$(mktemp -d) npx -y avorelo@latest activate" });
+    checks.push({
+      id: "npm_cache_writable",
+      label: "npm cache directory accessible",
+      passed: false,
+      details: "could not read npm cache config",
+      recovery: isWindows ? 'Use a temporary cache. PowerShell: $env:npm_config_cache="$env:TEMP\\npm-cache-avorelo"; npx -y avorelo@latest activate. cmd.exe: cmd /c "set npm_config_cache=%TEMP%\\npm-cache-avorelo && npx -y avorelo@latest activate"' : "Use a temporary cache: npm_config_cache=$(mktemp -d) npx -y avorelo@latest activate"
+    });
   }
   let tempOk = false;
   try {
@@ -11120,6 +11142,477 @@ function buildSummary(status, sourceCount, findingCount) {
 
 // src/avorelo/capabilities/runtime-flow/index.ts
 init_redaction();
+
+// src/avorelo/kernel/work-controls/index.ts
+var BUILTIN_CONTROLS = [
+  {
+    controlId: "secrets_guard",
+    title: "Secrets Guard",
+    purpose: "Block tasks, commands, syncs, and receipts that would leak secrets or env values.",
+    enforcementPoints: ["before_task_start", "before_shell_command", "before_secret_or_env_access", "before_cloud_sync", "before_receipt_finalize"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Detects secret and env exposure locally, returns coded findings only, never persists raw values.",
+    cloudBehavior: "Never allows raw secret or env material into sync payloads.",
+    dataPersisted: ["reason codes", "redaction classes", "safe next actions"],
+    testsRequired: ["no raw env persistence", "no secret printing", "DENY short-circuit"],
+    uiCopy: "Block secret or env leakage."
+  },
+  {
+    controlId: "scope_drift_guard",
+    title: "Scope Drift Guard",
+    purpose: "Stop broad or out-of-scope work before it silently expands.",
+    enforcementPoints: ["before_task_start", "before_file_write"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Uses route and write-scope metadata only.",
+    cloudBehavior: "Only safe scope codes may be synced.",
+    dataPersisted: ["reason codes", "triggered control id"],
+    testsRequired: ["ASK for broad scope", "DENY for out-of-scope writes"],
+    uiCopy: "Stop scope drift before it spreads."
+  },
+  {
+    controlId: "risky_action_approval",
+    title: "Risky Action Approval",
+    purpose: "Ask before risky work starts when the routed task already requires confirmation or manual review.",
+    enforcementPoints: ["before_task_start"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Maps current route/risk/proof metadata to a clear ASK verdict.",
+    cloudBehavior: "Only approval-required state may be synced, never task content.",
+    dataPersisted: ["verdict", "reason codes", "approval-required flag"],
+    testsRequired: ["ASK requires explicit approval", "approval clears ASK but not DENY"],
+    uiCopy: "Ask before risky actions."
+  },
+  {
+    controlId: "shell_command_approval",
+    title: "Shell Command Approval",
+    purpose: "Ask before risky shell commands and deny obviously destructive ones.",
+    enforcementPoints: ["before_shell_command"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Evaluates the command string locally and never stores terminal output.",
+    cloudBehavior: "Only coded gate outcomes may sync.",
+    dataPersisted: ["reason codes", "verdict"],
+    testsRequired: ["ASK for risky commands", "DENY for destructive commands"],
+    uiCopy: "Ask before risky shell commands."
+  },
+  {
+    controlId: "file_write_approval",
+    title: "File Write Approval",
+    purpose: "Require confirmation before sensitive file writes.",
+    enforcementPoints: ["before_file_write"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Uses path classification only, not file contents.",
+    cloudBehavior: "Only write gate metadata may sync.",
+    dataPersisted: ["reason codes", "verdict"],
+    testsRequired: ["ASK for sensitive writes"],
+    uiCopy: "Ask before sensitive file writes."
+  },
+  {
+    controlId: "dependency_install_approval",
+    title: "Dependency Install Approval",
+    purpose: "Pause before package installs or dependency changes.",
+    enforcementPoints: ["before_dependency_install", "before_shell_command"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Uses command metadata only.",
+    cloudBehavior: "Only approval-required metadata may sync.",
+    dataPersisted: ["reason codes", "verdict"],
+    testsRequired: ["ASK for dependency install"],
+    uiCopy: "Ask before dependency installs."
+  },
+  {
+    controlId: "release_guard",
+    title: "Release Guard",
+    purpose: "Require explicit approval before package publish or release tagging.",
+    enforcementPoints: ["before_package_publish", "before_release_tag", "before_task_start"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Evaluates release intent locally and records approval state.",
+    cloudBehavior: "Only release gate receipts may sync.",
+    dataPersisted: ["verdict", "reason codes", "approval-required flag"],
+    testsRequired: ["ASK for publish", "ASK for release tag"],
+    uiCopy: "Prevent publish or release without approval."
+  },
+  {
+    controlId: "production_deploy_guard",
+    title: "Production Deploy Guard",
+    purpose: "Escalate production-impacting work beyond a normal ASK.",
+    enforcementPoints: ["before_production_deploy", "before_task_start"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Records the stronger approval requirement locally.",
+    cloudBehavior: "Only coded escalation metadata may sync.",
+    dataPersisted: ["verdict", "reason codes", "approval-required flag"],
+    testsRequired: ["ESCALATE for production deploy without stronger approval"],
+    uiCopy: "Require stronger approval for production deploys."
+  },
+  {
+    controlId: "proof_required_before_done",
+    title: "Proof Required Before Done",
+    purpose: "Block done claims until outcome and post-action proof exist.",
+    enforcementPoints: ["after_agent_claims_done", "before_receipt_finalize", "before_test_claim"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Checks proof metadata only; never stores raw test logs or diffs.",
+    cloudBehavior: "Only proof status may sync.",
+    dataPersisted: ["proof-required flag", "reason codes", "safe next actions"],
+    testsRequired: ["REQUIRE_PROOF without evidence", "proof gate deterministic"],
+    uiCopy: "Require proof before done."
+  },
+  {
+    controlId: "raw_payload_upload_guard",
+    title: "Raw Prompt/Source/Diff Upload Guard",
+    purpose: "Deny cloud sync when raw prompt, source, diff, env, terminal, or secret payloads are present.",
+    enforcementPoints: ["before_cloud_sync"],
+    defaultState: "enabled",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Evaluates payload safety flags locally before any sync attempt.",
+    cloudBehavior: "Hard-denies unsafe sync.",
+    dataPersisted: ["reason codes", "verdict"],
+    testsRequired: ["no raw prompt upload", "no raw source upload", "no raw diff upload"],
+    uiCopy: "Receipts, not raw source."
+  },
+  {
+    controlId: "model_worthiness_guard",
+    title: "Model Worthiness Guard",
+    purpose: "Warn when a trivial task is not worth an expensive or deep review path.",
+    enforcementPoints: ["before_task_start"],
+    defaultState: "warn_only",
+    packaging: { free: true, pro: true, teams: true },
+    localOnlyBehavior: "Uses routing/task metadata only.",
+    cloudBehavior: "Only safe warning metadata may sync.",
+    dataPersisted: ["warning reason codes"],
+    testsRequired: ["WARN for trivial task with expensive model request"],
+    uiCopy: "Warn when deep review is not worth it."
+  }
+];
+var CONTROL_BY_ID = new Map(BUILTIN_CONTROLS.map((control) => [control.controlId, control]));
+var VERDICT_PRECEDENCE = [
+  "DENY",
+  "ESCALATE",
+  "ASK",
+  "REQUIRE_PROOF",
+  "WARN",
+  "ALLOW",
+  "NOOP"
+];
+var DESTRUCTIVE_SHELL_RE = /\b(rm\s+-rf|del\s+\/s|drop\s+table|git\s+push\s+--force|mkfs|dd\s+if=)\b/i;
+var RISKY_SHELL_RE = /\b(npm\s+publish|git\s+tag|railway|netlify|vercel|docker\s+push|kubectl|terraform\s+apply)\b/i;
+var DEPENDENCY_INSTALL_RE = /\b(npm|pnpm|yarn|bun)\s+(install|add)\b/i;
+function hasRawPayload(ctx) {
+  return !!(ctx.containsRawPrompt || ctx.containsRawSource || ctx.containsRawSecret || ctx.containsEnvValue || ctx.containsGitDiff || ctx.containsTerminalLog);
+}
+function hasProof(ctx) {
+  const levels = ctx.evidenceLevels ?? [];
+  return levels.includes("OUTCOME") && levels.includes("POST_ACTION");
+}
+function buildTrigger(controlId, enforcementPoint, verdict, reason, reasonCodes, nextAction) {
+  const def = CONTROL_BY_ID.get(controlId);
+  return {
+    controlId,
+    title: def.title,
+    verdict,
+    enforcementPoint,
+    reason,
+    reasonCodes,
+    nextAction
+  };
+}
+function evaluateSecretsGuard(point, ctx) {
+  if (point === "before_cloud_sync" && hasRawPayload(ctx)) {
+    return buildTrigger(
+      "raw_payload_upload_guard",
+      point,
+      "DENY",
+      "Cloud sync is blocked because the payload still contains raw prompt, source, diff, secret, env, or terminal data.",
+      ["RAW_PAYLOAD_BLOCKED"],
+      "Redact the payload and sync metadata only."
+    );
+  }
+  if (ctx.safeRunDecision === "block" || ctx.containsRawSecret || ctx.containsEnvValue) {
+    return buildTrigger(
+      "secrets_guard",
+      point,
+      "DENY",
+      "This action would expose secret or env material beyond Avorelo's trust boundary.",
+      ["SECRET_OR_ENV_EXPOSURE"],
+      "Remove the secret/env access, rotate if needed, and retry with safe references only."
+    );
+  }
+  return null;
+}
+function evaluateScopeGuard(point, ctx) {
+  if (point === "before_file_write" && ctx.outOfScopeWrite) {
+    return buildTrigger(
+      "scope_drift_guard",
+      point,
+      "DENY",
+      "The requested write is outside the approved work scope.",
+      ["OUT_OF_SCOPE_WRITE"],
+      "Narrow the task or explicitly approve the additional scope before writing."
+    );
+  }
+  if (point === "before_task_start" && ctx.route === "needs_decision") {
+    return buildTrigger(
+      "scope_drift_guard",
+      point,
+      "ASK",
+      "The task scope is too broad or ambiguous to start safely without a confirmation step.",
+      ["SCOPE_CONFIRMATION_REQUIRED"],
+      "Clarify the scope, target files, or success criteria before continuing."
+    );
+  }
+  return null;
+}
+function evaluateRiskyActionApproval(point, ctx) {
+  if (point !== "before_task_start") return null;
+  if (ctx.approvalPolicy === "require_confirmation" || ctx.approvalPolicy === "require_manual_review") {
+    if (ctx.userApproved) {
+      return buildTrigger(
+        "risky_action_approval",
+        point,
+        "ALLOW",
+        "The risky action had an explicit approval, so Avorelo can proceed without weakening safety.",
+        ["RISKY_ACTION_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "risky_action_approval",
+      point,
+      "ASK",
+      "This task has enough risk that it needs an explicit approval before work starts.",
+      ["RISKY_ACTION_APPROVAL_REQUIRED"],
+      "Confirm the risky action before continuing."
+    );
+  }
+  return null;
+}
+function evaluateShellCommand(point, ctx) {
+  if (point !== "before_shell_command" || !ctx.command) return null;
+  if (DESTRUCTIVE_SHELL_RE.test(ctx.command)) {
+    return buildTrigger(
+      "shell_command_approval",
+      point,
+      "DENY",
+      "The shell command is destructive enough that Avorelo blocks it by default.",
+      ["DESTRUCTIVE_SHELL_COMMAND"],
+      "Use a safer command or get the destructive step handled outside the automated flow."
+    );
+  }
+  if (ctx.dependencyInstallRequested || DEPENDENCY_INSTALL_RE.test(ctx.command)) {
+    if (ctx.userApproved) {
+      return buildTrigger(
+        "dependency_install_approval",
+        point,
+        "ALLOW",
+        "The dependency install had explicit approval.",
+        ["DEPENDENCY_INSTALL_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "dependency_install_approval",
+      point,
+      "ASK",
+      "Dependency installation is paused until the user explicitly approves it.",
+      ["DEPENDENCY_INSTALL_APPROVAL_REQUIRED"],
+      "Approve the dependency install, or use the existing lockfile and local dependencies only."
+    );
+  }
+  if (RISKY_SHELL_RE.test(ctx.command)) {
+    if (ctx.userApproved) {
+      return buildTrigger(
+        "shell_command_approval",
+        point,
+        "ALLOW",
+        "The risky shell command had explicit approval.",
+        ["SHELL_COMMAND_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "shell_command_approval",
+      point,
+      "ASK",
+      "This shell command can change external or release state and needs explicit approval.",
+      ["SHELL_COMMAND_APPROVAL_REQUIRED"],
+      "Approve the shell command before continuing."
+    );
+  }
+  return null;
+}
+function evaluateFileWrite(point, ctx) {
+  if (point !== "before_file_write" || !ctx.sensitiveFilePath) return null;
+  if (ctx.userApproved) {
+    return buildTrigger(
+      "file_write_approval",
+      point,
+      "ALLOW",
+      "The sensitive file write had explicit approval.",
+      ["FILE_WRITE_APPROVED"],
+      null
+    );
+  }
+  return buildTrigger(
+    "file_write_approval",
+    point,
+    "ASK",
+    "This write touches a sensitive surface and needs confirmation first.",
+    ["SENSITIVE_FILE_WRITE_APPROVAL_REQUIRED"],
+    "Approve the write or narrow the task to a non-sensitive path."
+  );
+}
+function evaluateRelease(point, ctx) {
+  if (point === "before_task_start" && ctx.productionImpact) {
+    if (ctx.adminApproved || ctx.teamApproved) {
+      return buildTrigger(
+        "production_deploy_guard",
+        point,
+        "ALLOW",
+        "The production-impacting task has stronger approval coverage.",
+        ["PRODUCTION_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "production_deploy_guard",
+      point,
+      "ESCALATE",
+      "Production-impacting work needs stronger approval than a normal ASK.",
+      ["PRODUCTION_ESCALATION_REQUIRED"],
+      "Get stronger approval before changing production-facing state."
+    );
+  }
+  if (point === "before_package_publish" || point === "before_release_tag") {
+    if (ctx.userApproved) {
+      return buildTrigger(
+        "release_guard",
+        point,
+        "ALLOW",
+        "The release step has explicit approval.",
+        ["RELEASE_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "release_guard",
+      point,
+      "ASK",
+      "Package publish and release tagging stay paused until explicitly approved.",
+      ["RELEASE_APPROVAL_REQUIRED"],
+      "Approve the release step before continuing."
+    );
+  }
+  if (point === "before_production_deploy") {
+    if (ctx.adminApproved || ctx.teamApproved) {
+      return buildTrigger(
+        "production_deploy_guard",
+        point,
+        "ALLOW",
+        "The production deploy has stronger approval coverage.",
+        ["PRODUCTION_APPROVED"],
+        null
+      );
+    }
+    return buildTrigger(
+      "production_deploy_guard",
+      point,
+      "ESCALATE",
+      "Production deploys need stronger approval than a normal ASK.",
+      ["PRODUCTION_ESCALATION_REQUIRED"],
+      "Get the stronger production approval before deploying."
+    );
+  }
+  return null;
+}
+function evaluateProof(point, ctx) {
+  if (point !== "after_agent_claims_done" && point !== "before_receipt_finalize" && point !== "before_test_claim") return null;
+  if (!ctx.agentClaimsDone) return null;
+  if (hasProof(ctx)) {
+    return buildTrigger(
+      "proof_required_before_done",
+      point,
+      "ALLOW",
+      "Outcome and post-action evidence are present, so the done claim can stand.",
+      ["PROOF_PRESENT"],
+      null
+    );
+  }
+  return buildTrigger(
+    "proof_required_before_done",
+    point,
+    "REQUIRE_PROOF",
+    "The agent claimed done before outcome and post-action proof existed.",
+    ["PROOF_REQUIRED_BEFORE_DONE"],
+    "Run the missing verification and attach outcome plus post-action evidence before marking done."
+  );
+}
+function evaluateModelWorthiness(point, ctx) {
+  if (point !== "before_task_start") return null;
+  if (!ctx.expensiveModelRequested || !ctx.taskSeemsTrivial) return null;
+  return buildTrigger(
+    "model_worthiness_guard",
+    point,
+    "WARN",
+    "This task looks trivial relative to the requested review depth.",
+    ["MODEL_WORTHINESS_WARN"],
+    "Use a lighter-weight path unless deeper review is actually needed."
+  );
+}
+function finalVerdict(triggers) {
+  if (triggers.length === 0) return "NOOP";
+  for (const verdict of VERDICT_PRECEDENCE) {
+    if (triggers.some((trigger) => trigger.verdict === verdict)) return verdict;
+  }
+  return "NOOP";
+}
+function listWorkControls() {
+  return BUILTIN_CONTROLS.map((control) => ({ ...control, enforcementPoints: [...control.enforcementPoints], packaging: { ...control.packaging }, dataPersisted: [...control.dataPersisted], testsRequired: [...control.testsRequired] }));
+}
+function getWorkControl(controlId) {
+  const found = CONTROL_BY_ID.get(controlId);
+  if (!found) return null;
+  return {
+    ...found,
+    enforcementPoints: [...found.enforcementPoints],
+    packaging: { ...found.packaging },
+    dataPersisted: [...found.dataPersisted],
+    testsRequired: [...found.testsRequired]
+  };
+}
+function evaluateWorkControls(enforcementPoint, ctx) {
+  const triggers = [
+    evaluateSecretsGuard(enforcementPoint, ctx),
+    evaluateScopeGuard(enforcementPoint, ctx),
+    evaluateRiskyActionApproval(enforcementPoint, ctx),
+    evaluateShellCommand(enforcementPoint, ctx),
+    evaluateFileWrite(enforcementPoint, ctx),
+    evaluateRelease(enforcementPoint, ctx),
+    evaluateProof(enforcementPoint, ctx),
+    evaluateModelWorthiness(enforcementPoint, ctx)
+  ].filter((trigger) => trigger !== null);
+  const verdict = finalVerdict(triggers);
+  const reasonCodes = Array.from(new Set(triggers.flatMap((trigger) => trigger.reasonCodes)));
+  const safeNextActions = Array.from(new Set(triggers.map((trigger) => trigger.nextAction).filter((value) => typeof value === "string" && value.length > 0)));
+  const blockingTrigger = triggers.find((trigger) => trigger.verdict === verdict) ?? null;
+  return {
+    enforcementPoint,
+    finalVerdict: verdict,
+    finalReason: blockingTrigger?.reason ?? "No relevant work control fired.",
+    reasonCodes,
+    approvalRequired: triggers.some((trigger) => trigger.verdict === "ASK" || trigger.verdict === "ESCALATE"),
+    proofRequired: triggers.some((trigger) => trigger.verdict === "REQUIRE_PROOF"),
+    triggers,
+    safeNextActions,
+    deterministic: true
+  };
+}
+
+// src/avorelo/capabilities/runtime-flow/index.ts
 function runtimeDir(dir) {
   return join39(dir, ".avorelo", "runtime");
 }
@@ -11154,6 +11647,22 @@ function safeFallbackProjection(reasonCodes, extraVerifierPlan = []) {
     containsRawSecret: false
   };
 }
+function toRuntimeWorkControls(evaluation) {
+  return {
+    enforcementPoint: evaluation.enforcementPoint,
+    finalVerdict: evaluation.finalVerdict,
+    finalReason: evaluation.finalReason,
+    reasonCodes: evaluation.reasonCodes,
+    approvalRequired: evaluation.approvalRequired,
+    proofRequired: evaluation.proofRequired,
+    triggeredControls: evaluation.triggers.map((trigger) => ({
+      controlId: trigger.controlId,
+      verdict: trigger.verdict,
+      reasonCodes: trigger.reasonCodes
+    })),
+    safeNextActions: evaluation.safeNextActions
+  };
+}
 function freshRuntimeId(seed) {
   return "rts_" + createHash12("sha256").update(seed).digest("hex").slice(0, 12);
 }
@@ -11218,6 +11727,20 @@ function runRuntimeSession(input) {
   const routing = decideRouting({ task, dir, planTier });
   const c = routing.contract;
   const displayTask = routing.displayTask;
+  const taskStartControls = evaluateWorkControls("before_task_start", {
+    task: displayTask,
+    planTier,
+    route: c.route,
+    riskClass: c.riskClass,
+    proofTier: c.proofTier,
+    approvalPolicy: c.approvalPolicy,
+    safeRunDecision: c.safetyBoundary.safeRunDecision,
+    secretRiskCodes: c.safetyBoundary.secretRiskCodes,
+    userApproved: routing.gate === "allow",
+    productionImpact: /deploy|release|publish|production|prod/i.test(displayTask),
+    taskSeemsTrivial: c.route === "deterministic_only" && c.riskClass === "low",
+    expensiveModelRequested: c.route === "deep_reasoning_required"
+  });
   const layers = [{
     order: 1,
     layer: "safety_and_routing",
@@ -11245,6 +11768,7 @@ function runRuntimeSession(input) {
       safeRunDecision: c.safetyBoundary.safeRunDecision,
       secretRiskCodes: c.safetyBoundary.secretRiskCodes ?? []
     },
+    workControls: toRuntimeWorkControls(taskStartControls),
     layers,
     redacted: true,
     containsRawSecret: false,
@@ -11809,6 +12333,8 @@ function buildRuntimeSessionSyncMetadata(record) {
     riskClass: record.riskClass,
     proofTier: record.proofTier,
     approvalPolicy: record.approvalPolicy,
+    workControlVerdict: record.workControls.finalVerdict,
+    workControlTriggerCount: record.workControls.triggeredControls.length,
     layerStatuses,
     secretRiskCodes: record.safetyBoundary.secretRiskCodes,
     canShowSavings: record.proof?.canShowSavings ?? false,
@@ -11824,6 +12350,8 @@ function validateRuntimeSession(record) {
   if (record.containsRawSecret !== false) reasons.push("contains_raw_secret");
   if (record.containsRawPrompt !== false) reasons.push("contains_raw_prompt");
   if (record.containsRawSourceDump !== false) reasons.push("contains_raw_source_dump");
+  if (!record.workControls) reasons.push("work_controls_missing");
+  else if (record.workControls.finalVerdict === "REQUIRE_PROOF" && record.gate === "allow") reasons.push("proof_required_task_started");
   if (record.gate === "blocked" && (record.session || record.context || record.continuity || record.tokenCost || record.proof || record.value || record.efficiencySync)) {
     reasons.push("blocked_gate_ran_downstream");
   }
@@ -11914,6 +12442,18 @@ function buildControlCenter(dir, opts) {
   } : { status: "unavailable" };
   if (runtime) sources.push(avoreloPath(dir, "runtime", "session.latest.json"));
   else notes.push('No runtime session yet \u2014 run `avorelo run "<task>"` to create one.');
+  const workControlsSection = runtime?.workControls ? {
+    status: "available",
+    enforcementPoint: runtime.workControls.enforcementPoint,
+    finalVerdict: runtime.workControls.finalVerdict,
+    approvalRequired: runtime.workControls.approvalRequired,
+    proofRequired: runtime.workControls.proofRequired,
+    triggeredCount: runtime.workControls.triggeredControls.length,
+    controls: runtime.workControls.triggeredControls.map((control) => ({
+      controlId: control.controlId,
+      verdict: control.verdict
+    }))
+  } : { status: "unavailable" };
   const contextPackSection = runtime?.contextPack ? {
     status: "available",
     contextPackId: runtime.contextPack.contextPackId,
@@ -12081,6 +12621,7 @@ function buildControlCenter(dir, opts) {
     workspace: dir,
     sections: {
       runtimeSession: runtimeSection,
+      workControls: workControlsSection,
       contextPack: contextPackSection,
       proof: proofSection,
       value: valueSection,
@@ -12115,6 +12656,7 @@ function renderText2(m) {
   } else {
     lines.push("  Runtime:   none yet");
   }
+  lines.push(`  Controls:  ${s.workControls.status === "available" ? `${s.workControls.finalVerdict} at ${s.workControls.enforcementPoint} \xB7 approval=${s.workControls.approvalRequired} \xB7 proof=${s.workControls.proofRequired} \xB7 triggers=${s.workControls.triggeredCount}` : "none"}`);
   lines.push(`  Ctx pack:  ${s.contextPack.status === "available" ? `${s.contextPack.contextPackId} \xB7 consumer=${s.contextPack.consumer} adapter=${s.contextPack.selectedAdapter} \xB7 refs=${s.contextPack.allowedCount}/${s.contextPack.forbiddenCount} blocked \xB7 budget=${s.contextPack.budget} used=${s.contextPack.contextBudgetUsed} \xB7 tags=${s.contextPack.provenanceTagCount}` : "none"}`);
   lines.push(`  Proof:     ${s.proof.status === "available" ? `${s.proof.reportId} \xB7 savings ${s.proof.canShowSavings ? "shown" : `not claimed (${s.proof.savingsRefusalReason ?? "no_comparative_evidence"})`}` : "none"}`);
   lines.push(`  Token/cost:${s.costEvidence.status === "available" ? ` ${s.costEvidence.confidence} \xB7 costSummary=${s.costEvidence.canShowCostSummary} \xB7 ${s.costEvidence.evidenceCount} item(s)` : " none"}`);
@@ -12182,6 +12724,7 @@ function renderHtml2(m) {
 <h1>Avorelo \u2014 Local Control Center</h1>
 <table>
 ${row("Runtime", s.runtimeSession.status === "available" ? `${esc2(s.runtimeSession.sessionStatus)} \xB7 gate=${esc2(s.runtimeSession.gate)} route=${esc2(s.runtimeSession.route)} risk=${esc2(s.runtimeSession.riskClass)} proof=${esc2(s.runtimeSession.proofTier)}<div>${layers}</div>` : '<span class="muted">none yet</span>')}
+${row("Controls", s.workControls.status === "available" ? `${esc2(s.workControls.finalVerdict)} \xB7 point=${esc2(s.workControls.enforcementPoint)} \xB7 approval=${esc2(s.workControls.approvalRequired)} \xB7 proof=${esc2(s.workControls.proofRequired)} \xB7 triggers=${esc2(s.workControls.triggeredCount)}${(s.workControls.controls ?? []).length ? `<div class="muted">${(s.workControls.controls ?? []).map((c) => `${esc2(c.controlId)}=${esc2(c.verdict)}`).join(" \xB7 ")}</div>` : ""}` : '<span class="muted">none</span>')}
 ${row("Ctx pack", s.contextPack.status === "available" ? `${esc2(s.contextPack.contextPackId)} \xB7 consumer=${esc2(s.contextPack.consumer)} adapter=${esc2(s.contextPack.selectedAdapter)} \xB7 refs=${esc2(s.contextPack.allowedCount)}/${esc2(s.contextPack.forbiddenCount)} blocked \xB7 budget=${esc2(s.contextPack.budget)} used=${esc2(s.contextPack.contextBudgetUsed)} \xB7 tags=${esc2(s.contextPack.provenanceTagCount)}` : '<span class="muted">none</span>')}
 ${row("Proof", s.proof.status === "available" ? `${esc2(s.proof.reportId)} \xB7 savings ${s.proof.canShowSavings ? "shown" : `<b>not claimed</b> (${esc2(s.proof.savingsRefusalReason ?? "no_comparative_evidence")})`}` : '<span class="muted">none</span>')}
 ${row("Token/cost", s.costEvidence.status === "available" ? `${esc2(s.costEvidence.confidence)} \xB7 costSummary=${esc2(s.costEvidence.canShowCostSummary)} \xB7 ${esc2(s.costEvidence.evidenceCount)} item(s)` : '<span class="muted">none</span>')}
@@ -13013,7 +13556,7 @@ function checkEnvironmentIntegrity(dir, signals) {
   if (signals?.staleProcess) reasonCodes.push("STALE_PROCESS");
   return { compromised: reasonCodes.length > 0, reasonCodes };
 }
-function evaluateProof(input) {
+function evaluateProof2(input) {
   const declared = input.artifacts ?? [];
   const readbacks = (input.readbacks ?? []).map((c) => readBack(input.dir, c));
   const readbackArtifacts = readbacks.map((r2) => r2.artifact).filter((a) => a !== null);
@@ -16088,6 +16631,9 @@ var RUNTIME_ACTIONS = [
   { action: "cli.status", capabilityKey: "session_value_visible", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Show activation status", freeFallbackExists: true },
   { action: "cli.open", capabilityKey: "session_value_visible", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Local receipts dashboard", freeFallbackExists: true },
   { action: "cli.control_center", capabilityKey: "session_value_visible", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Local Control Center", freeFallbackExists: true },
+  { action: "cli.controls", capabilityKey: "session_value_visible", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Inspect built-in Work Controls", freeFallbackExists: true },
+  { action: "cli.receipt", capabilityKey: "session_proof_summary", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Inspect latest local receipt", freeFallbackExists: true },
+  { action: "cli.proof", capabilityKey: "session_proof_summary", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Validate latest proof status", freeFallbackExists: true },
   { action: "cli.doctor", capabilityKey: "scope_safety_check_basic", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Health check", freeFallbackExists: true },
   { action: "cli.verify", capabilityKey: "session_proof_summary", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Validate activation state", freeFallbackExists: true },
   { action: "cli.billing", capabilityKey: "session_value_visible", minimumTier: "free", surface: "cli", fallback: "allow", reason: "Billing readiness (read-only)", freeFallbackExists: true },
@@ -16126,6 +16672,9 @@ var FREE_COMMANDS = /* @__PURE__ */ new Set([
   "status",
   "open",
   "control-center",
+  "controls",
+  "receipt",
+  "proof",
   "doctor",
   "verify",
   "billing",
@@ -17241,6 +17790,10 @@ function help() {
     "  status [--target <dir>]                                           Show activation and session status",
     "  open [--target <dir>] [--format html|json|text]                   Local receipts dashboard",
     "  control-center [--target <dir>] [--format html|json|text]         Local Control Center (read-only, all local state)",
+    "  controls list [--json]                                            List built-in Work Controls",
+    "  controls explain <control> [--json]                               Explain one built-in Work Control",
+    "  receipt latest [--target <dir>] [--json]                          Show the latest local receipt",
+    "  proof check [--target <dir>] [--json]                             Validate the latest proof status",
     "  doctor [--target <dir>]                                           Health check (adapters, hooks, session)",
     "  verify [--target <dir>]                                           Validate activation state invariants",
     "  uninstall [--target <dir>]                                        Remove all Avorelo-managed content",
@@ -17721,6 +18274,140 @@ function cmdControlCenter(args) {
   process.stdout.write(JSON.stringify({ ok: true, htmlPath, runtime: model.sections.runtimeSession.status, sources: model.sources.length }, null, 2) + "\n");
   return 0;
 }
+function cmdControls(args) {
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "list";
+  const asJson = args.includes("--json");
+  if (sub === "list") {
+    const controls = listWorkControls();
+    if (asJson) {
+      process.stdout.write(JSON.stringify(controls, null, 2) + "\n");
+      return 0;
+    }
+    process.stdout.write([
+      "",
+      "Avorelo Work Controls",
+      ...controls.map((control) => `  ${control.controlId}: ${control.uiCopy} [${control.defaultState}]`),
+      ""
+    ].join("\n"));
+    return 0;
+  }
+  if (sub === "explain") {
+    const controlId = args.find((value, index) => index > 0 && !value.startsWith("--"));
+    if (!controlId) {
+      process.stderr.write("Usage: avorelo controls explain <control> [--json]\n");
+      return 2;
+    }
+    const control = getWorkControl(controlId);
+    if (!control) {
+      process.stderr.write(`Unknown Work Control: ${controlId}
+`);
+      return 1;
+    }
+    if (asJson) {
+      process.stdout.write(JSON.stringify(control, null, 2) + "\n");
+      return 0;
+    }
+    process.stdout.write([
+      "",
+      `${control.title} (${control.controlId})`,
+      `  Purpose:    ${control.purpose}`,
+      `  Points:     ${control.enforcementPoints.join(", ")}`,
+      `  Default:    ${control.defaultState}`,
+      `  Packaging:  Free=${control.packaging.free} Pro=${control.packaging.pro} Teams=${control.packaging.teams}`,
+      `  Local:      ${control.localOnlyBehavior}`,
+      `  Cloud:      ${control.cloudBehavior}`,
+      `  Persisted:  ${control.dataPersisted.join(", ")}`,
+      `  Tests:      ${control.testsRequired.join(", ")}`,
+      `  UI copy:    ${control.uiCopy}`,
+      ""
+    ].join("\n"));
+    return 0;
+  }
+  process.stderr.write("Usage: avorelo controls <list|explain> [<control>] [--json]\n");
+  return 2;
+}
+function latestReceiptFor(dir) {
+  return listReceipts(dir).sort((a, b) => {
+    const aw = typeof a.writtenAt === "number" ? a.writtenAt : -1;
+    const bw = typeof b.writtenAt === "number" ? b.writtenAt : -1;
+    if (aw !== bw) return bw - aw;
+    return b.receiptId.localeCompare(a.receiptId);
+  })[0] ?? null;
+}
+function cmdReceipt(args) {
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "latest";
+  const target = arg(args, "--target", process.cwd());
+  const asJson = args.includes("--json");
+  if (sub !== "latest") {
+    process.stderr.write("Usage: avorelo receipt latest [--target <dir>] [--json]\n");
+    return 2;
+  }
+  const latest = latestReceiptFor(target);
+  if (!latest) {
+    if (asJson) {
+      process.stdout.write(JSON.stringify({ status: "none", message: "no receipts found" }, null, 2) + "\n");
+      return 0;
+    }
+    process.stdout.write("\nNo receipts found yet. Run a controlled session first.\n\n");
+    return 0;
+  }
+  const full = readReceipt(target, latest.receiptId) ?? latest;
+  if (asJson) {
+    process.stdout.write(JSON.stringify(full, null, 2) + "\n");
+    return 0;
+  }
+  process.stdout.write([
+    "",
+    `Latest receipt: ${full.receiptId}`,
+    `  Contract:    ${full.contractId}`,
+    `  Decision:    ${full.decision}`,
+    `  Evidence:    ${full.evidenceLevels.join(", ") || "none"}`,
+    `  Reasons:     ${full.decisionBasis.reasonCodes.join(", ") || "none"}`,
+    `  Next:        ${full.safeNextActions.join("; ") || "none"}`,
+    ""
+  ].join("\n"));
+  return 0;
+}
+function cmdProof(args) {
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "check";
+  const target = arg(args, "--target", process.cwd());
+  const asJson = args.includes("--json");
+  if (sub !== "check") {
+    process.stderr.write("Usage: avorelo proof check [--target <dir>] [--json]\n");
+    return 2;
+  }
+  const report = loadLatestProofReport(target) ?? buildProofReportFromLocalEvidence(target);
+  const summary = summarizeProofReport(report);
+  const validation = validateProofReport(report);
+  const payload = {
+    reportId: report.reportId,
+    valid: validation.valid,
+    reasons: validation.reasons,
+    canShowCostSummary: summary.canShowCostSummary,
+    canShowSavings: summary.canShowSavings,
+    savingsRefusalReason: summary.savingsRefusalReason,
+    sections: summary.sections
+  };
+  if (asJson) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    return validation.valid ? 0 : 1;
+  }
+  process.stdout.write([
+    "",
+    `Proof check: ${report.reportId}`,
+    `  Valid:      ${validation.valid}`,
+    `  Found:      ${summary.sections.found}`,
+    `  Protected:  ${summary.sections.protected}`,
+    `  Verified:   ${summary.sections.verified}`,
+    `  Attention:  ${summary.sections.needsAttention}`,
+    `  Next:       ${summary.sections.next}`,
+    `  Cost:       ${summary.canShowCostSummary ? "available" : "unavailable"}`,
+    `  Savings:    ${summary.canShowSavings ? "shown" : "not claimed"}${summary.savingsRefusalReason ? ` (${summary.savingsRefusalReason})` : ""}`,
+    validation.reasons.length ? `  Issues:      ${validation.reasons.join(", ")}` : "  Issues:      none",
+    ""
+  ].join("\n"));
+  return validation.valid ? 0 : 1;
+}
 function cmdVerify(args) {
   const target = arg(args, "--target", process.cwd());
   const stateVerify = verifyActivationState(target);
@@ -17734,7 +18421,7 @@ function cmdVerify(args) {
   const input = loadProofInput(target);
   if (input) {
     const contract = createWorkContract({ contractId: "verify", objective: input.objective ?? "verify real-workflow proof", allowedPaths: [join61(target, "src")], planTier: "Free" });
-    const r2 = evaluateProof({ contract, artifacts: input.artifacts, readbacks: input.readbacks, dir: target, sampleSize: input.sampleSize, receiptId: "rcpt_verify" });
+    const r2 = evaluateProof2({ contract, artifacts: input.artifacts, readbacks: input.readbacks, dir: target, sampleSize: input.sampleSize, receiptId: "rcpt_verify" });
     process.stdout.write(JSON.stringify({ scope: "full", activationState: { valid: true }, proof: { decision: r2.decision, confidence: r2.confidence } }, null, 2) + "\n");
     return r2.decision === "STOP_DONE" ? 0 : 1;
   }
@@ -19722,6 +20409,12 @@ function main(argv) {
       return cmdOpen(rest);
     case "control-center":
       return cmdControlCenter(rest);
+    case "controls":
+      return cmdControls(rest);
+    case "receipt":
+      return cmdReceipt(rest);
+    case "proof":
+      return cmdProof(rest);
     case "verify":
       return cmdVerify(rest);
     case "site":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avorelo",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "license": "UNLICENSED",
   "description": "Avorelo — AI Work Control. One command. Keep using your AI coding tool. Avorelo quietly keeps the work focused and saves proof.",