avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/ai-efficiency-guard-contract.js

@@ -0,0 +1,209 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { safeReadJson } = require("./fsx");
+
+const GUARD_DESCRIPTORS = [
+  {
+    guardId: "data-guard",
+    commandName: "data-guard",
+    schemaVersion: null,
+    surfaces: ["cli", "hook", "agent"],
+    taskTypes: ["data-access", "data-mutation", "migration"],
+    routeHints: ["proof-required", "block-on-fail"],
+    proofExpectationLabel: "Data permissions verified before access",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "data-permissions-guard.js",
+    reportPath: ".claude/cco/reports/data-permissions-guard/latest-report.json",
+  },
+  {
+    guardId: "permissions-guard",
+    commandName: "permissions-guard",
+    schemaVersion: null,
+    surfaces: ["cli", "hook"],
+    taskTypes: ["permission-check", "access-control"],
+    routeHints: ["proof-required"],
+    proofExpectationLabel: "Permission boundaries enforced",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "data-permissions-guard.js",
+    reportPath: ".claude/cco/reports/data-permissions-guard/latest-report.json",
+  },
+  {
+    guardId: "deployment-guard",
+    commandName: "deployment-guard",
+    schemaVersion: null,
+    surfaces: ["cli", "hook", "agent"],
+    taskTypes: ["deploy", "release", "environment-check"],
+    routeHints: ["proof-required", "block-on-fail"],
+    proofExpectationLabel: "Deployment environment validated",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "deployment-environment-guard.js",
+    reportPath: ".claude/cco/reports/deployment-environment-guard/latest-report.json",
+  },
+  {
+    guardId: "supply-chain-guard",
+    commandName: "supply-chain-guard",
+    schemaVersion: "avorelo.supplyChainDependencyGuard.v1",
+    surfaces: ["cli", "hook"],
+    taskTypes: ["dependency-audit", "package-integrity"],
+    routeHints: ["proof-required"],
+    proofExpectationLabel: "Supply chain integrity verified",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "log-and-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "supply-chain-dependency-guard.js",
+    reportPath: ".claude/cco/reports/supply-chain-dependency-guard/latest-report.json",
+  },
+  {
+    guardId: "observability-recovery-guard",
+    commandName: "observability-recovery-guard",
+    schemaVersion: "avorelo.observabilityRecoveryGuard.v1",
+    surfaces: ["cli", "hook", "agent"],
+    taskTypes: ["observability", "recovery", "production_confidence"],
+    routeHints: ["proof-required", "block-on-fail"],
+    proofExpectationLabel: "Observability and recovery paths verified",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "observability-recovery-guard.js",
+    reportPath: ".claude/cco/reports/observability-recovery-guard/latest-report.json",
+  },
+  {
+    guardId: "cost-abuse-guard",
+    commandName: "cost-abuse-guard",
+    schemaVersion: "avorelo.costAbuseGuard.v1",
+    surfaces: ["cli", "hook", "agent"],
+    taskTypes: ["cost-control", "abuse-detection", "production_confidence"],
+    routeHints: ["proof-required", "block-on-fail"],
+    proofExpectationLabel: "Cost and abuse thresholds enforced",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "cost-abuse-guard.js",
+    reportPath: ".claude/cco/reports/cost-abuse-guard/latest-report.json",
+  },
+  {
+    guardId: "webhook-idempotency-guard",
+    commandName: "webhook-idempotency-guard",
+    schemaVersion: "avorelo.webhookIdempotencyGuard.v1",
+    surfaces: ["cli", "hook", "agent"],
+    taskTypes: ["webhook", "idempotency", "production_confidence"],
+    routeHints: ["proof-required", "block-on-fail"],
+    proofExpectationLabel: "Webhook idempotency contracts enforced",
+    statusSource: "report",
+    blockedBehavior: "halt-task",
+    warnBehavior: "surface-warning-continue",
+    evidenceRefSelector: "latestReport.evidence",
+    guardFile: "webhook-idempotency-guard.js",
+    reportPath: ".claude/cco/reports/webhook-idempotency-guard/latest-report.json",
+  },
+];
+
+const FUTURE_REASON_CODES = {};
+
+function resolveGuardState(descriptor, cwd) {
+  const libDir = path.resolve(__dirname);
+  const fileExists =
+    descriptor.guardFile &&
+    fs.existsSync(path.resolve(libDir, descriptor.guardFile));
+
+  let reportData = null;
+  if (descriptor.reportPath && cwd) {
+    reportData = safeReadJson(cwd, descriptor.reportPath);
+  }
+
+  const present = !!fileExists;
+  const runtimeVerified = present && reportData !== null;
+
+  return { present, runtimeVerified, reportData };
+}
+
+function buildGuardIntegrationContract(cwd) {
+  const reasonCodes = [];
+  let hasPresent = false;
+  let hasBlocked = false;
+  let hasContractOnly = false;
+
+  const guards = GUARD_DESCRIPTORS.map((descriptor) => {
+    const { present, runtimeVerified } = resolveGuardState(descriptor, cwd);
+
+    const entry = {
+      guardId: descriptor.guardId,
+      commandName: descriptor.commandName,
+      schemaVersion: descriptor.schemaVersion,
+      surfaces: descriptor.surfaces,
+      taskTypes: descriptor.taskTypes,
+      routeHints: descriptor.routeHints,
+      proofExpectationLabel: descriptor.proofExpectationLabel,
+      statusSource: descriptor.statusSource,
+      blockedBehavior: descriptor.blockedBehavior,
+      warnBehavior: descriptor.warnBehavior,
+      evidenceRefSelector: descriptor.evidenceRefSelector,
+      present,
+      runtimeVerified,
+      contractReady: true,
+    };
+
+    if (present && runtimeVerified) {
+      hasPresent = true;
+      reasonCodes.push("GUARD_PRESENT_RUNTIME_VERIFIED");
+    } else if (present && !runtimeVerified) {
+      hasPresent = true;
+      hasContractOnly = true;
+      reasonCodes.push("GUARD_CONTRACT_ONLY");
+    } else {
+      // Not present — contract placeholder
+      const futureCode = FUTURE_REASON_CODES[descriptor.guardId];
+      if (futureCode) {
+        reasonCodes.push(futureCode);
+      }
+    }
+
+    if (descriptor.blockedBehavior === "halt-task" && present) {
+      reasonCodes.push("GUARD_BLOCKED_PRESERVED");
+    }
+    if (
+      descriptor.warnBehavior === "surface-warning-continue" &&
+      present
+    ) {
+      reasonCodes.push("GUARD_WARN_PRESERVED");
+    }
+
+    return entry;
+  });
+
+  const presentGuards = guards.filter((g) => g.present);
+  let status;
+  if (presentGuards.length === 0) {
+    status = "no_data";
+  } else if (hasBlocked) {
+    status = "blocked";
+  } else if (hasContractOnly) {
+    status = "partial";
+  } else {
+    status = "ready";
+  }
+
+  reasonCodes.unshift("GUARD_CONTRACT_READY");
+
+  return {
+    status,
+    guards,
+    reasonCodes: [...new Set(reasonCodes)],
+  };
+}
+
+module.exports = { buildGuardIntegrationContract, GUARD_DESCRIPTORS };

package/scripts/lib/ai-efficiency-measured-value.js

@@ -0,0 +1,106 @@
+'use strict';
+
+function safeLen(arr) {
+  return Array.isArray(arr) ? arr.length : 0;
+}
+
+function safeNum(v, fallback) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+
+const AVG_SUPPRESSED_BYTES = 500; // estimated per-ref average
+
+function computeMeasuredLocalValue(contextBudget, governedExposure, tokenEfficiency, promptCompilerPlan) {
+  const cb = contextBudget || {};
+  const ge = governedExposure || {};
+  const pcp = promptCompilerPlan || {};
+
+  const availableContextRefsBefore = safeNum(cb.estimatedContextItems, 0);
+
+  const selectedContextRefsAfter = safeLen(ge.includeContextRefs);
+  const suppressedContextRefs = Math.max(0, availableContextRefsBefore - selectedContextRefsAfter);
+
+  const includedBytes = safeNum(cb.estimatedInputBytes, null);
+  const suppressedBytes = suppressedContextRefs > 0
+    ? { value: suppressedContextRefs * AVG_SUPPRESSED_BYTES, estimated: true }
+    : { value: 0, estimated: true };
+
+  const staleRefsSuppressed = safeNum(cb.staleContextCount, 0);
+  const duplicateRefsSuppressed = safeNum(cb.duplicateContextCount, 0);
+  const noisyRefsSuppressed = safeNum(cb.suppressedContextCount, 0);
+
+  const capabilityRefsExposed = safeLen(ge.exposedCapabilityRefs);
+  const capabilityRefsSuppressed = safeLen(ge.suppressedCapabilityRefs);
+  const capabilityRefsAvailable = capabilityRefsExposed + capabilityRefsSuppressed;
+
+  const toolRefsExposed = safeLen(ge.exposedToolRefs);
+  const toolRefsSuppressed = safeLen(ge.suppressedToolRefs);
+  const toolRefsAvailable = toolRefsExposed + toolRefsSuppressed;
+
+  const proofExpectationsAdded = safeLen(ge.proofExpectations);
+  const guardEvidenceRefsIncluded = safeLen(ge.guardEvidenceRefs);
+
+  const hasMeasuredRefs = availableContextRefsBefore > 0 || selectedContextRefsAfter > 0;
+  const hasMeasuredCaps = capabilityRefsAvailable > 0;
+  const hasMeasuredTools = toolRefsAvailable > 0;
+  const hasAnything = hasMeasuredRefs || hasMeasuredCaps || hasMeasuredTools || includedBytes !== null;
+
+  const status = hasAnything
+    ? (hasMeasuredRefs && hasMeasuredCaps ? 'measured' : 'partial')
+    : 'unavailable';
+
+  const measurementType = 'measured';
+
+  const publicClaimAllowed = status !== 'unavailable';
+
+  const caveat = status === 'unavailable'
+    ? 'No measured local data available. Token savings are heuristic estimates only.'
+    : 'Measured local context reduction in refs and capabilities. Token savings are heuristic estimates only.';
+
+  const reasonCodes = [];
+  if (status !== 'unavailable') {
+    reasonCodes.push('MEASURED_LOCAL_VALUE_AVAILABLE');
+  }
+  if (hasMeasuredRefs) {
+    reasonCodes.push('MEASURED_CONTEXT_REDUCTION');
+  }
+  if (suppressedContextRefs > 0) {
+    reasonCodes.push('MEASURED_REFS_SUPPRESSED');
+  }
+  if (suppressedBytes.value > 0) {
+    reasonCodes.push('MEASURED_BYTES_SUPPRESSED');
+  }
+  reasonCodes.push('HEURISTIC_TOKEN_VALUE_ONLY');
+  reasonCodes.push('DOLLAR_SAVINGS_UNAVAILABLE');
+  if (publicClaimAllowed) {
+    reasonCodes.push('PUBLIC_CLAIM_ALLOWED_MEASURED_LOCAL');
+  } else {
+    reasonCodes.push('PUBLIC_CLAIM_BLOCKED_HEURISTIC_ONLY');
+  }
+
+  return {
+    status,
+    availableContextRefsBefore,
+    selectedContextRefsAfter,
+    suppressedContextRefs,
+    includedBytes,
+    suppressedBytes,
+    staleRefsSuppressed,
+    duplicateRefsSuppressed,
+    noisyRefsSuppressed,
+    capabilityRefsAvailable,
+    capabilityRefsExposed,
+    capabilityRefsSuppressed,
+    toolRefsAvailable,
+    toolRefsExposed,
+    toolRefsSuppressed,
+    proofExpectationsAdded,
+    guardEvidenceRefsIncluded,
+    measurementType,
+    publicClaimAllowed,
+    caveat,
+    reasonCodes
+  };
+}
+
+module.exports = { computeMeasuredLocalValue };

package/scripts/lib/ai-install-prompt.js

@@ -0,0 +1,293 @@
+"use strict";
+
+// ── AI Install Prompt ─────────────────────────────────────────────────────────
+//
+// Contract: avorelo.aiInstallPrompt.v1
+//
+// Generates a safe, copy-pasteable one-prompt AI install experience.
+// Inspired by PostHog install-with-AI pattern, adapted for Avorelo's
+// approval-boundary requirements (hooks/MCP/tool governance require
+// explicit user approval — never auto-applied).
+//
+// Rules:
+// - Prompt never includes raw secrets, repo-specific sensitive data, or PII
+// - Hook apply always requires explicit --yes approval from user
+// - MCP config is never auto-modified
+// - Global config is never modified
+// - AI must stop on blockers and request explicit approval for config changes
+// - Default output is compact; debug exposes internals
+
+const fs = require("fs");
+const path = require("path");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.aiInstallPrompt.v1";
+const SCHEMA_VERSION = 1;
+
+const PROMPT_DIR_REL = ".claude/cco/orchestration/ai-install";
+const LATEST_PROMPT_REL = `${PROMPT_DIR_REL}/latest-prompt.json`;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const AVORELO_ROOT = path.resolve(__dirname, "../../");
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJsonRel(cwd, rel) {
+  return safeReadJson(path.join(cwd, rel));
+}
+
+// ── Command sequence ──────────────────────────────────────────────────────────
+
+// All commands are external-user commands (npx avorelo@latest ...), never
+// repo-internal `node bin/avorelo ...`. Step 1 actually activates Avorelo and
+// writes the canonical local state; the remaining steps verify and report.
+function buildCommandSequence() {
+  return [
+    { step: 1, cmd: "npx avorelo@latest activate", purpose: "Activate Avorelo: safe local detection + self-healing setup, writes canonical state" },
+    { step: 2, cmd: "npx avorelo@latest status", purpose: "Verify activation is 'ready' (must not say 'not activated')" },
+    { step: 3, cmd: "npx avorelo@latest open", purpose: "Open local receipts and proof - confirm activation receipt exists" },
+    { step: 4, cmd: "npx avorelo@latest verify", purpose: "Validate activation state invariants" },
+  ];
+}
+
+// ── Approval boundaries ───────────────────────────────────────────────────────
+
+function buildApprovalBoundaries() {
+  return [
+    {
+      surface: "hooks",
+      rule: "NEVER run `avorelo hooks apply --yes` without explicit user approval. Always show dry-run preview first.",
+      command: "npx avorelo@latest hooks apply --dry-run",
+      approvalCommand: "npx avorelo@latest hooks apply --yes",
+    },
+    {
+      surface: "mcp_config",
+      rule: "NEVER modify MCP config automatically. MCP governance is preview-only in this flow.",
+      command: null,
+      approvalCommand: null,
+    },
+    {
+      surface: "global_config",
+      rule: "NEVER modify global config files (e.g., ~/.claude/settings.json) without explicit user instruction.",
+      command: null,
+      approvalCommand: null,
+    },
+    {
+      surface: "destructive_commands",
+      rule: "NEVER run deploy, publish, rm -rf, database migrations, or production commands.",
+      command: null,
+      approvalCommand: null,
+    },
+  ];
+}
+
+// ── Safety rules ──────────────────────────────────────────────────────────────
+
+function buildSafetyRules() {
+  return [
+    "Do not write product code before activation readiness checks complete.",
+    "Stop immediately if any command returns status: fail — show the safeNextAction and wait.",
+    "Do not bypass, skip, or override any approval boundary.",
+    "Do not expose, log, or include secrets, API keys, tokens, or PII in any output.",
+    "Do not run --yes on hook apply without the user reading the dry-run preview.",
+    "Do not modify global config or MCP server config.",
+    "Keep all output compact. Use --debug only if the user requests diagnostics.",
+    "The value summary must be evidence-backed — no exact cost savings claims.",
+  ];
+}
+
+// ── Prompt text ───────────────────────────────────────────────────────────────
+
+function buildPromptText(commandSequence, approvalBoundaries, safetyRules) {
+  const steps = commandSequence.map((s) => `  ${s.step}. ${s.cmd}\n     # ${s.purpose}`).join("\n");
+  const boundaries = approvalBoundaries.map((b) => `  - ${b.surface}: ${b.rule}`).join("\n");
+  const rules = safetyRules.map((r) => `  - ${r}`).join("\n");
+
+  return `You are activating Avorelo in this repo for me.
+
+Run these exact commands in order, from the project root. Use the commands as
+written (npx avorelo@latest ...). Do NOT invent setup steps, do NOT install
+anything else, and do NOT use internal commands like \`node bin/avorelo\`.
+Stop immediately if a step fails and report the reason plus one next action.
+
+Steps:
+${steps}
+
+Verify before reporting success:
+- Step 1 output says activation is "ready" or "already active".
+- Step 2 (status) does NOT say "not activated".
+- Step 3 (open) shows at least one activation receipt.
+- The activation state file exists under .avorelo/ in your project.
+If any of these is not true, STOP and report what failed — do not claim success.
+
+Approval boundaries (NEVER bypass these):
+${boundaries}
+
+Safety rules:
+${rules}
+
+Local-first: activation must not require signup. Do not create an account or ask
+me to sign up to reach first value — everything runs locally with no account
+required. Do not touch unrelated app code, do not deploy, do not publish.
+
+After the steps complete, return a compact summary:
+- Activation status (ready / already active / needs attention)
+- What Avorelo set up automatically
+- Where the status/state/receipts live
+- One clear next action
+
+Do not claim public launch readiness. Do not claim exact/guaranteed savings.
+Keep output compact.`;
+}
+
+// ── Expected outputs ──────────────────────────────────────────────────────────
+
+function buildExpectedOutputs() {
+  return [
+    { step: "activate", shape: "avorelo.activation.canonical.v1", keyField: "activated" },
+    { step: "status", shape: "avorelo status (activation: ready)", keyField: "activation.status" },
+    { step: "open", shape: "avorelo open (receipts and proof)", keyField: "activation.status" },
+    { step: "verify", shape: "avorelo verify (invariants pass)", keyField: "summary" },
+  ];
+}
+
+// ── Build prompt receipt ──────────────────────────────────────────────────────
+
+function buildAiInstallPrompt(cwd, options = {}) {
+  const commandSequence = buildCommandSequence();
+  const approvalBoundaries = buildApprovalBoundaries();
+  const safetyRules = buildSafetyRules();
+  const promptText = buildPromptText(commandSequence, approvalBoundaries, safetyRules);
+  const expectedOutputs = buildExpectedOutputs();
+
+  // Check if activation module is available
+  let activationAvailable = false;
+  try {
+    require("./alpha-activation");
+    activationAvailable = true;
+  } catch {}
+
+  // Check if prelaunch readiness module is available
+  let prelaunchAvailable = false;
+  try {
+    require("./prelaunch-activation-readiness");
+    prelaunchAvailable = true;
+  } catch {}
+
+  const status = activationAvailable ? "ready" : "partial";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    promptText,
+    commandSequence,
+    approvalBoundaries,
+    safetyRules,
+    expectedOutputs,
+    nextAction: "Copy the promptText and paste it into Claude Code, Codex, Cursor, VS Code, or your AI coding agent.",
+    activationAvailable,
+    prelaunchAvailable,
+    redacted: true,
+  };
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "ai_install_prompt_generated",
+      status: receipt.status,
+      activationAvailable,
+      prelaunchAvailable,
+    });
+  } catch {}
+
+  return receipt;
+}
+
+// ── Build install plan (metadata without full prompt text) ────────────────────
+
+function buildAiInstallPlan(cwd, options = {}) {
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    stepCount: buildCommandSequence().length,
+    approvalBoundaryCount: buildApprovalBoundaries().length,
+    safetyRuleCount: buildSafetyRules().length,
+    summary: "One-prompt AI install: activate → readiness → launch-hardening → token/context → mcp → hooks → first-value → support → prelaunch-readiness → proof",
+    safeForAutoRun: false,
+    requiresExplicitApproval: ["hooks apply", "mcp config changes", "global config changes"],
+    redacted: true,
+  };
+}
+
+// ── Artifact I/O ──────────────────────────────────────────────────────────────
+
+function writeAiInstallPromptReceipt(cwd, receipt) {
+  const dir = path.join(cwd, PROMPT_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const latest = path.join(cwd, LATEST_PROMPT_REL);
+  // Never write raw secrets. Receipt has redacted:true.
+  // Strip promptText from the stored artifact (keep it in-memory only) to avoid
+  // accidentally committing repo-sensitive context.
+  const stored = Object.assign({}, receipt, { promptText: "[see formatAiInstallPromptText]" });
+  fs.writeFileSync(latest, JSON.stringify(stored, null, 2), "utf8");
+  return latest;
+}
+
+// ── Surface / format ──────────────────────────────────────────────────────────
+
+function buildAiInstallPromptSurface(cwd, options = {}) {
+  const receipt = buildAiInstallPrompt(cwd, options);
+  return { receipt };
+}
+
+function formatAiInstallPromptText(receipt, options = {}) {
+  const lines = [
+    `Install Avorelo with AI`,
+    ``,
+    `Copy this prompt into Claude Code, Codex, Cursor, VS Code, or your AI coding agent:`,
+    ``,
+    `─────────────────────────────────────────────────────────────`,
+    receipt.promptText,
+    `─────────────────────────────────────────────────────────────`,
+    ``,
+    `What it will do:`,
+    `  - Check project readiness.`,
+    `  - Run safe activation.`,
+    `  - Verify hooks and MCP/tool governance.`,
+    `  - Request approval before config changes.`,
+    `  - Run first-value verification.`,
+    `  - Produce a compact value summary.`,
+    ``,
+    `Next:`,
+    `  - Paste the prompt into your AI coding session.`,
+    ``,
+    `Note: Hook apply requires explicit approval. MCP config is not modified automatically.`,
+  ];
+  return lines.join("\n");
+}
+
+module.exports = {
+  buildAiInstallPrompt,
+  buildAiInstallPlan,
+  writeAiInstallPromptReceipt,
+  buildAiInstallPromptSurface,
+  formatAiInstallPromptText,
+  // exposed for testing
+  buildCommandSequence,
+  buildApprovalBoundaries,
+  buildSafetyRules,
+  buildPromptText,
+  CONTRACT,
+  LATEST_PROMPT_REL,
+};