avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/run-action-policy.js

@@ -0,0 +1,104 @@
+"use strict";
+
+const CONTRACT = "avorelo.runActionPolicy.v1";
+
+const ALLOWED_BY_DEFAULT = Object.freeze([
+  "local_read",
+  "deterministic_analysis",
+  "source_refs",
+  "tests",
+  "validators",
+  "docs_edits",
+  "local_reports",
+  "local_artifacts",
+]);
+
+const ALLOWED_WITH_CONTRACT = Object.freeze([
+  "local_writes",
+  "source_changes",
+  "compact_dashboard_surface",
+  "dogfood_artifact_updates",
+]);
+
+const NEEDS_DECISION = Object.freeze([
+  "dependency_changes",
+  "package_json_scripts",
+  "public_website_claims",
+  "ci_config_changes",
+  "github_mutations",
+  "browser_automation",
+  "external_api_writes",
+]);
+
+const BLOCKED_BY_DEFAULT = Object.freeze([
+  "deploy",
+  "publish",
+  "billing_changes",
+  "entitlement_changes",
+  "secrets_access",
+  "destructive_delete",
+  "mass_rewrite",
+  "raw_prompt_storage",
+  "raw_code_storage",
+  "raw_log_storage",
+  "external_data_upload",
+  "broad_refactor_without_scope",
+]);
+
+function buildActionPolicy(taskClassification, riskClassification, routeDecision, plan) {
+  const riskLevel = riskClassification.level;
+  const sideEffectLevel = riskClassification.sideEffectLevel;
+  const taskType = taskClassification.taskType;
+
+  const allowedActions = [...ALLOWED_BY_DEFAULT];
+  const blockedActions = [...BLOCKED_BY_DEFAULT];
+  const needsDecisionActions = [...NEEDS_DECISION];
+  const approvalReasonCodes = [];
+
+  // Promote actions based on task and risk
+  if (riskLevel !== "blocked" && sideEffectLevel !== "destructive") {
+    if (["capability-development", "bugfix", "guard-policy-change", "ui-compact-surface", "dashboard-change"].includes(taskType)) {
+      allowedActions.push(...ALLOWED_WITH_CONTRACT);
+    }
+  }
+
+  // Block everything for blocked tasks
+  if (riskLevel === "blocked") {
+    allowedActions.length = 0;
+    allowedActions.push("local_read", "deterministic_analysis");
+    approvalReasonCodes.push("risk_blocked_all_writes");
+  }
+
+  // Dashboard rewrite blocked unless explicitly approved
+  if (taskType === "dashboard-change" && plan && plan.antiGoals && plan.antiGoals.includes("dashboard_rewrite_without_approval")) {
+    blockedActions.push("dashboard_rewrite");
+    approvalReasonCodes.push("dashboard_rewrite_blocked");
+  }
+
+  // Deploy/publish/billing always blocked
+  if (["deploy-request", "publish-request", "billing-entitlement-change"].includes(taskType)) {
+    approvalReasonCodes.push(`${taskType}_requires_explicit_approval`);
+  }
+
+  // Route-based tool restrictions
+  if (routeDecision.blockedTools && routeDecision.blockedTools.length > 0) {
+    blockedActions.push(...routeDecision.blockedTools);
+  }
+
+  return {
+    schemaVersion: CONTRACT,
+    allowedActions: [...new Set(allowedActions)],
+    blockedActions: [...new Set(blockedActions)],
+    needsDecisionActions: [...new Set(needsDecisionActions)],
+    approvalReasonCodes: [...new Set(approvalReasonCodes)],
+  };
+}
+
+module.exports = {
+  buildActionPolicy,
+  ALLOWED_BY_DEFAULT,
+  ALLOWED_WITH_CONTRACT,
+  NEEDS_DECISION,
+  BLOCKED_BY_DEFAULT,
+  CONTRACT,
+};

package/scripts/lib/run-contract-receipt.js

@@ -0,0 +1,48 @@
+"use strict";
+
+// Run Contract Receipt — packet-compatible adapter only.
+// This module extracts contract fields into a compact receipt format.
+// It does NOT replace or duplicate:
+//   - efficiency-receipt.js (owner of per-run efficiency receipt composition)
+//   - next-run-continuity.js (owner of next-run route synthesis)
+//   - dashboard.js (owner of system-wide status aggregation)
+// See docs/internal/capability-ownership-registry.md
+
+const RECEIPT_SCHEMA = "avorelo.runContractReceipt.v1";
+
+function buildReceipt(contract) {
+  if (!contract) return null;
+
+  return {
+    schemaVersion: RECEIPT_SCHEMA,
+    contractId: contract.id,
+    taskType: contract.taskType,
+    status: contract.status,
+    route: contract.route.decision,
+    scopeTier: contract.scope.scopeTier,
+    riskLevel: contract.risk.level,
+    proofRequired: contract.proof.required,
+    proofTier: contract.proof.proofTier,
+    claimSafetyRequired: contract.proof.claimSafetyRequired,
+    valueConfidence: contract.value.confidence,
+    verifiedOutcomeRequired: contract.value.verifiedOutcomeRequired,
+    unsafeActionsBlocked: contract.policy.blockedActions.length,
+    humanApprovalRequired: contract.route.requiresHumanApproval,
+    safeNextAction: contract.safeNextAction,
+    metrics: {
+      routeDecision: contract.route.decision,
+      modelClass: contract.route.modelClass,
+      scopeTier: contract.scope.scopeTier,
+      proofTier: contract.proof.proofTier,
+      confidence: contract.value.confidence,
+      blockedActionsCount: contract.policy.blockedActions.length,
+      needsDecisionActionsCount: contract.policy.needsDecisionActions.length,
+      learningSignalsCount: contract.learning ? contract.learning.signalsToRecord.length : 0,
+    },
+  };
+}
+
+module.exports = {
+  buildReceipt,
+  RECEIPT_SCHEMA,
+};

package/scripts/lib/run-contract.js

@@ -0,0 +1,288 @@
+"use strict";
+
+const crypto = require("crypto");
+const { classifyTask } = require("./run-task-classifier");
+const { classifyRisk } = require("./run-risk-classifier");
+const { selectRoute } = require("./execution-route-governor");
+const { generatePlan } = require("./smallest-safe-plan");
+const { generateProofContract } = require("./run-proof-contract");
+const { buildCostToVerifiedOutcome } = require("./run-cost-to-verified-outcome");
+const { buildActionPolicy } = require("./run-action-policy");
+
+const SCHEMA_VERSION = "avorelo.runContract.v1";
+
+function compileRunContract(options = {}) {
+  const {
+    taskDescription,
+    taskType: taskTypeOverride,
+    contextPacket,
+    capabilityContract,
+    changedFiles,
+    repoRoot,
+  } = options;
+
+  // Step 1: Classify task
+  const taskClassification = classifyTask(taskDescription, { taskType: taskTypeOverride });
+
+  // Step 2: Classify risk
+  const riskClassification = classifyRisk(taskClassification, {
+    description: taskDescription,
+    changedFiles,
+    contextPacket,
+  });
+
+  // Step 3: Select route
+  const routeDecision = selectRoute(taskClassification, riskClassification, {
+    contextPacket,
+    capabilityContract,
+  });
+
+  // Step 4: Generate smallest safe plan
+  const plan = generatePlan(taskClassification, riskClassification, routeDecision, {
+    contextPacket,
+  });
+
+  // Step 5: Generate proof contract
+  const proofContract = generateProofContract(taskClassification, riskClassification, plan, {
+    contextPacket,
+  });
+
+  // Step 6: Build cost-to-verified-outcome
+  const value = buildCostToVerifiedOutcome(taskClassification, proofContract, {
+    contextPacket,
+  });
+
+  // Step 7: Build action policy
+  const actionPolicy = buildActionPolicy(taskClassification, riskClassification, routeDecision, plan);
+
+  // Step 8: Determine overall status
+  const status = determineStatus(riskClassification, routeDecision, actionPolicy);
+
+  // Step 9: Build safe next action
+  const safeNextAction = buildSafeNextAction(taskClassification, routeDecision, plan);
+
+  // Step 10: Build learning signals
+  const learning = {
+    observationOnly: true,
+    signalsToRecord: buildLearningSignals(taskClassification, riskClassification, routeDecision),
+    noSelfModification: true,
+  };
+
+  const contractId = `run_contract_${crypto.randomBytes(8).toString("hex")}`;
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: contractId,
+    taskProfile: taskClassification.taskType,
+    taskType: taskClassification.taskType,
+    contextPacketRef: contextPacket ? contextPacket.id || "" : "",
+    status,
+    route: {
+      decision: routeDecision.decision,
+      reasonCodes: routeDecision.reasonCodes,
+      allowedTools: routeDecision.allowedTools,
+      blockedTools: routeDecision.blockedTools,
+      modelClass: routeDecision.modelClass,
+      requiresHumanApproval: routeDecision.requiresHumanApproval,
+    },
+    scope: {
+      scopeTier: plan.scopeTier,
+      allowedFilesMax: plan.allowedFilesMax,
+      expectedDiffSize: plan.expectedDiffSize,
+      allowedAreas: plan.allowedAreas,
+      blockedAreas: plan.blockedAreas,
+      antiGoals: plan.antiGoals,
+      refactorAllowed: plan.refactorAllowed,
+      newAbstractionAllowed: plan.newAbstractionAllowed,
+    },
+    risk: {
+      level: riskClassification.level,
+      reasonCodes: riskClassification.reasonCodes,
+      sensitiveAreas: riskClassification.sensitiveAreas,
+      sideEffectLevel: riskClassification.sideEffectLevel,
+    },
+    proof: {
+      required: proofContract.required,
+      proofTier: proofContract.proofTier,
+      commands: proofContract.commands,
+      artifactRequired: proofContract.artifactRequired,
+      artifactPath: proofContract.artifactPath,
+      postMergeSmokeRequired: proofContract.postMergeSmokeRequired,
+      claimSafetyRequired: proofContract.claimSafetyRequired,
+    },
+    value: {
+      verifiedOutcomeRequired: value.verifiedOutcomeRequired,
+      costPerVerifiedOutcomeTracked: value.costPerVerifiedOutcomeTracked,
+      outputCanCountAsValueWithoutProof: value.outputCanCountAsValueWithoutProof,
+      confidence: value.confidence,
+      grossValueSignals: value.grossValueSignals,
+      kernelCostSignals: value.kernelCostSignals,
+      netValueSignals: value.netValueSignals,
+    },
+    policy: {
+      allowedActions: actionPolicy.allowedActions,
+      blockedActions: actionPolicy.blockedActions,
+      needsDecisionActions: actionPolicy.needsDecisionActions,
+      approvalReasonCodes: actionPolicy.approvalReasonCodes,
+    },
+    learning,
+    safeNextAction,
+  };
+}
+
+function determineStatus(riskClassification, routeDecision, actionPolicy) {
+  if (riskClassification.level === "blocked" || routeDecision.decision === "blocked") {
+    return "blocked";
+  }
+  if (routeDecision.decision === "needs_decision" || routeDecision.requiresHumanApproval) {
+    return "needs_decision";
+  }
+  if (actionPolicy.approvalReasonCodes.length > 0 && riskClassification.level === "high") {
+    return "needs_decision";
+  }
+  return "ready";
+}
+
+function buildSafeNextAction(taskClassification, routeDecision, plan) {
+  if (routeDecision.decision === "blocked") {
+    return "This task is blocked. Requires explicit human approval before proceeding.";
+  }
+  if (routeDecision.decision === "needs_decision") {
+    return "This task requires a human decision before proceeding. Review scope and risk.";
+  }
+
+  const taskType = taskClassification.taskType;
+  switch (taskType) {
+    case "docs-only":
+    case "release-doc-update":
+      return "Make the documentation change and validate.";
+    case "public-copy":
+    case "article-writing":
+      return "Draft content, run claim-safety checks, then validate.";
+    case "capability-development":
+      return "Implement the smallest safe change and prove it with targeted tests.";
+    case "bugfix":
+      return "Fix the bug with a targeted change and prove it with tests.";
+    case "dashboard-change":
+    case "ui-compact-surface":
+      return "Make the compact surface change and run status-dashboard tests.";
+    case "guard-policy-change":
+    case "production-readiness-review":
+      return "Make the guard/policy change with full proof coverage.";
+    case "browser-proof-qa":
+      return "Run browser proof workflow and capture evidence.";
+    default:
+      return "Implement the smallest safe change and prove it with targeted tests.";
+  }
+}
+
+function buildLearningSignals(taskClassification, riskClassification, routeDecision) {
+  const signals = [];
+  signals.push(`task_classified:${taskClassification.taskType}`);
+  signals.push(`risk_level:${riskClassification.level}`);
+  signals.push(`route_selected:${routeDecision.decision}`);
+  signals.push(`model_class:${routeDecision.modelClass}`);
+  if (routeDecision.requiresHumanApproval) signals.push("human_approval_required");
+  return signals;
+}
+
+// Packet-compatible helper — provides run contract metadata for next-run consumers.
+// Does NOT replace next-run-continuity.js (owner of route synthesis/carry-forward).
+// See docs/internal/capability-ownership-registry.md
+function buildNextRunMetadata(contract) {
+  if (!contract) return null;
+  return {
+    runContract: {
+      status: contract.status,
+      route: contract.route.decision,
+      scope: contract.scope.scopeTier,
+      proofRequired: contract.proof.required,
+      unsafeActionsBlocked: contract.policy.blockedActions.length,
+      safeNextAction: contract.safeNextAction,
+    },
+  };
+}
+
+// Packet-compatible helper — provides run contract surface for dashboard consumers.
+// Does NOT replace dashboard.js (owner of system-wide status aggregation).
+// See docs/internal/capability-ownership-registry.md
+function buildDashboardSurface(contract) {
+  if (!contract) return null;
+  const unsafeBlocked = contract.policy.blockedActions.length;
+  const statusLine = `Run: ${contract.status}; route: ${contract.route.decision}; proof ${contract.proof.required ? "required" : "not required"}; ${unsafeBlocked} unsafe actions blocked.`;
+  return {
+    runContract: {
+      status: contract.status,
+      statusLine,
+      route: contract.route.decision,
+      scopeTier: contract.scope.scopeTier,
+      proofRequired: contract.proof.required,
+      unsafeActionsBlocked: unsafeBlocked,
+      safeNextAction: contract.safeNextAction,
+    },
+  };
+}
+
+function formatTextOutput(contract) {
+  if (!contract) return "No run contract available.";
+  const parts = [];
+  parts.push(`Run: ${contract.route.decision}; ${contract.scope.scopeTier} scope; proof ${contract.proof.required ? "required" : "not required"}; ${contract.policy.blockedActions.length} unsafe actions blocked.`);
+  parts.push(`Next: ${contract.safeNextAction}`);
+  return parts.join(" ");
+}
+
+function validateContract(contract) {
+  const errors = [];
+  const warnings = [];
+
+  if (!contract) {
+    errors.push("No contract provided");
+    return { valid: false, errors, warnings };
+  }
+
+  if (contract.schemaVersion !== SCHEMA_VERSION) {
+    errors.push(`Invalid schema version: ${contract.schemaVersion}`);
+  }
+
+  if (!contract.id || !contract.id.startsWith("run_contract_")) {
+    errors.push("Missing or invalid contract id");
+  }
+
+  if (!contract.taskType) errors.push("Missing taskType");
+  if (!contract.status) errors.push("Missing status");
+  if (!contract.route || !contract.route.decision) errors.push("Missing route decision");
+  if (!contract.scope || !contract.scope.scopeTier) errors.push("Missing scope tier");
+  if (!contract.risk || !contract.risk.level) errors.push("Missing risk level");
+  if (!contract.proof) errors.push("Missing proof contract");
+  if (!contract.value) errors.push("Missing value fields");
+  if (!contract.policy) errors.push("Missing action policy");
+  if (!contract.safeNextAction) errors.push("Missing safeNextAction");
+
+  // Safety checks
+  const json = JSON.stringify(contract);
+  if (/[A-Za-z]:\\/.test(json) || /\/home\//.test(json) || /\/Users\//.test(json)) {
+    errors.push("Contract contains absolute path");
+  }
+  if (/sk-[A-Za-z0-9_-]{16,}/.test(json) || /gh[ps]_[A-Za-z0-9]{12,}/.test(json)) {
+    errors.push("Contract contains potential secret");
+  }
+
+  if (contract.learning && !contract.learning.observationOnly) {
+    warnings.push("Learning is not observation-only");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+module.exports = {
+  compileRunContract,
+  validateContract,
+  buildNextRunMetadata,
+  buildDashboardSurface,
+  formatTextOutput,
+  SCHEMA_VERSION,
+};

package/scripts/lib/run-cost-to-verified-outcome.js

@@ -0,0 +1,87 @@
+"use strict";
+
+// Run Contract cost-to-verified-outcome — adapter/consumer of the AI Work Efficiency
+// value layer. This module maps proof tiers to confidence levels for run contract use.
+// It does NOT replace or redefine:
+//   - cost-to-outcome-signals.js (owner of waste signal detection and aggregation)
+//   - value-ledger.js (owner of per-run value event logging)
+//   - efficiency-receipt.js (owner of per-run efficiency receipt composition)
+// Confidence labels here align with the efficiency layer taxonomy:
+//   measured = full proof, inferred = targeted proof, estimated = smoke only, unverified = none
+// See docs/internal/capability-ownership-registry.md
+
+const CONTRACT = "avorelo.runCostToVerifiedOutcome.v1";
+
+// Aligned with AI Work Efficiency Control Layer confidence taxonomy.
+// Source-of-truth for confidence definitions: cost-to-outcome-signals.js
+const CONFIDENCE_LEVELS = Object.freeze(["measured", "inferred", "estimated", "unverified"]);
+
+function buildCostToVerifiedOutcome(taskClassification, proofContract, options = {}) {
+  const contextPacket = options.contextPacket || null;
+
+  const verifiedOutcomeRequired = proofContract.required;
+  const outputCanCountAsValueWithoutProof = false;
+  const costPerVerifiedOutcomeTracked = true;
+
+  let confidence = "estimated";
+  const grossValueSignals = [];
+  const kernelCostSignals = [];
+  const netValueSignals = [];
+
+  // Derive confidence from proof tier
+  if (proofContract.proofTier === "full_ci" || proofContract.proofTier === "browser_proof") {
+    confidence = "measured";
+    grossValueSignals.push("full_proof_coverage");
+  } else if (proofContract.proofTier === "targeted_tests" || proofContract.proofTier === "validation_script") {
+    confidence = "inferred";
+    grossValueSignals.push("targeted_proof_coverage");
+  } else if (proofContract.proofTier === "smoke") {
+    confidence = "estimated";
+    grossValueSignals.push("smoke_only");
+  } else if (proofContract.proofTier === "none") {
+    confidence = "unverified";
+    grossValueSignals.push("no_proof");
+  } else if (proofContract.proofTier === "manual_review_required") {
+    confidence = "unverified";
+    grossValueSignals.push("blocked_pending_review");
+  }
+
+  // Context packet signals
+  if (contextPacket && contextPacket.metrics) {
+    if (contextPacket.metrics.proofBackedRefsRatio >= 0.8) {
+      grossValueSignals.push("high_proof_backed_context");
+    } else if (contextPacket.metrics.proofBackedRefsRatio >= 0.5) {
+      grossValueSignals.push("moderate_proof_backed_context");
+    }
+
+    if (contextPacket.metrics.totalEstimatedTokens > 0) {
+      kernelCostSignals.push(`context_tokens:${contextPacket.metrics.totalEstimatedTokens}`);
+    }
+  }
+
+  // Net value = gross minus cost signals
+  if (verifiedOutcomeRequired && confidence !== "unverified") {
+    netValueSignals.push("verified_outcome_tracked");
+  }
+
+  if (taskClassification.artifactRequired) {
+    netValueSignals.push("artifact_evidence_required");
+  }
+
+  return {
+    schemaVersion: CONTRACT,
+    verifiedOutcomeRequired,
+    costPerVerifiedOutcomeTracked,
+    outputCanCountAsValueWithoutProof,
+    confidence,
+    grossValueSignals,
+    kernelCostSignals,
+    netValueSignals,
+  };
+}
+
+module.exports = {
+  buildCostToVerifiedOutcome,
+  CONFIDENCE_LEVELS,
+  CONTRACT,
+};