avorelo 0.1.0 → 0.3.0

package/scripts/lib/work-ledger.js

@@ -1,1123 +0,0 @@
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-const crypto = require("node:crypto");
-
-const CONTRACT = "avorelo.workLedger.v1";
-const SCHEMA_VERSION = 1;
-
-const LEDGER_DIR_REL = ".claude/cco/orchestration/work-ledger";
-const LATEST_LEDGER_REL = `${LEDGER_DIR_REL}/latest-ledger.json`;
-
-const ENTRY_TYPES = Object.freeze([
-  "route",
-  "context",
-  "guard",
-  "safe_path",
-  "intake",
-  "workspace_hygiene",
-  "orchestration",
-  "smart_route",
-  "safe_run",
-  "proof",
-  "outcome",
-  "reality_gate",
-  "product_learning",
-  "dogfood",
-  "feedback",
-  // PR #140 — Hook Baseline + Lifecycle Automation Preview
-  "hook_baseline",
-  "adapter_readiness",
-  "hook_config_preview",
-  "lifecycle_hook",
-  // PR #141 — Explicit Hook Apply + Lifecycle Live
-  "hook_apply",
-  "hook_doctor",
-  "hook_rollback",
-  "hook_uninstall",
-  // PR #142 — Activation Alpha Readiness + First Value
-  "alpha_activation",
-  "alpha_readiness_gate",
-  "alpha_feedback",
-  "support_bundle",
-  // PR #143 — Token Efficiency + Context Quality Hardening
-  "token_efficiency_evidence",
-  "tool_output_sandbox",
-  "repo_map",
-  "context_acquisition_plan",
-  "cache_readiness",
-  "token_context_quality_gate",
-  // PR #144 — Launch Hardening + Failure Recovery v1
-  "failure_recovery",
-  "launch_hardening_gate",
-  "artifact_health",
-  "artifact_cleanup",
-  "doctor_hardening",
-  // PR #145 — MCP Least-Privilege Tool Governance v1
-  "mcp_tool_inventory",
-  "mcp_tool_risk",
-  "mcp_policy_preview",
-  "mcp_pre_tool_use_decision",
-  // PR #146 � One-Prompt AI Install + Pre-Launch Activation Readiness
-  "ai_install_prompt",
-  "prelaunch_activation_readiness",
-  "install_journey_intelligence",
-  // PR #147 � Pre-Launch Intelligence Layer
-  "prelaunch_intelligence",
-  "feedback_intelligence",
-  "token_cost_intelligence",
-  "token_cost_capture_checked",
-  "feedback_evidence_imported",
-  "token_cost_evidence_imported",
-  "token_cost_summary_generated",
-  "proof_outcome_evidence_checked",
-  "failure_recovery_checked",
-  "hook_safety_boundary_checked",
-  "readiness_evidence_gap_closed",
-  // PR #148 � Full Readiness / Release Candidate Gate
-  "full_readiness_gate",
-  "readiness_evidence_closure",
-  "known_limitations",
-  "external_user_simulation",
-  "release_candidate_bundle",
-  "activation_distribution_readiness",
-  "activation_distribution_check",
-  "activation_distribution_evidence",
-  "design_partner_feedback_session",
-  "design_partner_feedback_summary",
-  "readiness_delta",
-  // PR #161 — Public Activation Distribution Truth v1
-  "public_distribution_truth",
-  "package_content_audit",
-  "local_package_smoke",
-  "public_install_claim_check",
-  "publish_provenance_readiness",
-  "public_activation_distribution_gate",
-  "unknown",
-]);
-
-// Artifact source paths (relative to cwd)
-const ARTIFACT_PATHS = Object.freeze({
-  orchestration_plan:
-    ".claude/cco/orchestration/work-aware-orchestration/latest-plan.json",
-  context_pack:
-    ".claude/cco/orchestration/context-optimizer/latest-pack.json",
-  context_receipt:
-    ".claude/cco/orchestration/context-optimizer/latest-receipt.json",
-  workspace_hygiene:
-    ".claude/cco/orchestration/ai-workspace-hygiene/latest-report.json",
-  outcome:
-    ".claude/cco/orchestration/seamless-outcome/latest-outcome.json",
-  value_summary:
-    ".claude/cco/orchestration/seamless-outcome/latest-value-summary.json",
-  reality_gate:
-    ".claude/cco/orchestration/seamless-outcome/latest-reality-gate.json",
-  safe_path:
-    ".claude/cco/security/safe-path/latest-receipt.json",
-  agent_access_governance:
-    ".claude/cco/security/agent-access-governance/latest-receipt.json",
-  product_learning:
-    ".claude/cco/events/product-learning.jsonl",
-  feedback_dir: ".claude/cco/feedback",
-  smart_route:
-    ".claude/cco/orchestration/smart-work-routing/latest-route.json",
-  safe_run:
-    ".claude/cco/orchestration/safe-run/latest-run.json",
-  // PR #140 — Hook Baseline + Lifecycle Automation Preview
-  hook_baseline:
-    ".claude/cco/orchestration/hook-baseline/latest-baseline.json",
-  adapter_readiness:
-    ".claude/cco/orchestration/adapter-readiness/latest-readiness.json",
-  hook_config_preview:
-    ".claude/cco/orchestration/hook-baseline/latest-preview.json",
-  lifecycle_hook_session_start:
-    ".claude/cco/orchestration/lifecycle-hooks/latest-sessionstart.json",
-  lifecycle_hook_pre_tool_use:
-    ".claude/cco/orchestration/lifecycle-hooks/latest-pretooluse.json",
-  lifecycle_hook_stop:
-    ".claude/cco/orchestration/lifecycle-hooks/latest-stop.json",
-  lifecycle_hook_session_end:
-    ".claude/cco/orchestration/lifecycle-hooks/latest-sessionend.json",
-  // PR #141 — Explicit Hook Apply + Lifecycle Live
-  hook_apply:
-    ".claude/cco/orchestration/hook-apply/latest-apply.json",
-  hook_doctor:
-    ".claude/cco/orchestration/hook-apply/latest-doctor.json",
-  hook_rollback:
-    ".claude/cco/orchestration/hook-apply/latest-rollback.json",
-  // PR #142 — Activation Alpha Readiness + First Value
-  alpha_activation:
-    ".claude/cco/orchestration/activation/latest-activation.json",
-  alpha_readiness_gate:
-    ".claude/cco/orchestration/alpha-readiness/latest-gate.json",
-  support_bundle:
-    ".claude/cco/support/latest-support-bundle.json",
-  // PR #143 — Token Efficiency + Context Quality Hardening
-  token_efficiency_evidence:
-    ".claude/cco/orchestration/token-efficiency/latest-evidence.json",
-  tool_output_sandbox:
-    ".claude/cco/orchestration/tool-output/latest-summary.json",
-  repo_map:
-    ".claude/cco/orchestration/repo-map/latest-map.json",
-  context_acquisition_plan:
-    ".claude/cco/orchestration/context-acquisition/latest-plan.json",
-  cache_readiness:
-    ".claude/cco/orchestration/cache-readiness/latest-readiness.json",
-  token_context_quality_gate:
-    ".claude/cco/orchestration/token-efficiency/latest-quality-gate.json",
-  // PR #144
-  failure_recovery: ".claude/cco/orchestration/failure-recovery/latest-recovery.json",
-  launch_hardening_gate: ".claude/cco/orchestration/launch-hardening/latest-gate.json",
-  artifact_health: ".claude/cco/orchestration/artifact-health/latest-health.json",
-  artifact_cleanup: ".claude/cco/orchestration/artifact-health/latest-cleanup.json",
-  // PR #145 — MCP Least-Privilege Tool Governance v1
-  mcp_tool_inventory: ".claude/cco/orchestration/mcp-tool-governance/latest-inventory.json",
-  mcp_tool_risk: ".claude/cco/orchestration/mcp-tool-governance/latest-risk.json",
-  mcp_policy_preview: ".claude/cco/orchestration/mcp-tool-governance/latest-policy-preview.json",
-  mcp_pre_tool_use_decision: ".claude/cco/orchestration/mcp-tool-governance/latest-pretooluse-decision.json",
-  // PR #161 — Public Activation Distribution Truth v1
-  public_distribution_truth: ".claude/cco/orchestration/public-distribution/latest-truth.json",
-  package_content_audit: ".claude/cco/orchestration/public-distribution/latest-package-content-audit.json",
-  local_package_smoke: ".claude/cco/orchestration/public-distribution/latest-local-package-smoke.json",
-  public_install_claim_check: ".claude/cco/orchestration/public-distribution/latest-install-claim-check.json",
-  publish_provenance_readiness: ".claude/cco/orchestration/public-distribution/latest-publish-provenance-readiness.json",
-  public_activation_distribution_gate: ".claude/cco/orchestration/public-distribution/latest-gate.json",
-});
-
-function createRunId(input) {
-  const base = input
-    ? `${input.slice(0, 40)}-${Date.now()}`
-    : `ledger-${Date.now()}`;
-  return `ledger-${crypto
-    .createHash("sha1")
-    .update(base)
-    .digest("hex")
-    .slice(0, 12)}`;
-}
-
-function safeReadJson(filePath) {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    const raw = fs.readFileSync(filePath, "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-function safeReadJsonl(filePath, limit = 200) {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    const raw = fs.readFileSync(filePath, "utf8");
-    const lines = raw
-      .split("\n")
-      .filter((l) => l.trim())
-      .slice(-limit);
-    const events = [];
-    for (const line of lines) {
-      try {
-        events.push(JSON.parse(line));
-      } catch {
-        // skip malformed line
-      }
-    }
-    return events;
-  } catch {
-    return null;
-  }
-}
-
-function readAvailableWorkArtifacts(cwd) {
-  const artifacts = {};
-  for (const [key, rel] of Object.entries(ARTIFACT_PATHS)) {
-    const full = path.join(cwd, rel);
-    if (key === "product_learning") {
-      artifacts[key] = { path: full, rel, exists: fs.existsSync(full) };
-    } else if (key === "feedback_dir") {
-      artifacts[key] = { path: full, rel, exists: fs.existsSync(full) };
-    } else {
-      artifacts[key] = { path: full, rel, exists: fs.existsSync(full) };
-    }
-  }
-  return artifacts;
-}
-
-function normalizeLedgerEntry(type, source, artifactData, options = {}) {
-  const { evidencePath, evidenceKind = "receipt" } = options;
-  const entry = {
-    entryId: `entry-${crypto.randomBytes(4).toString("hex")}`,
-    type,
-    source,
-    stageId: options.stageId || null,
-    status: options.status || "unknown",
-    summary: options.summary || "not_available",
-    evidencePath: evidencePath || null,
-    evidenceKind,
-    valueSignals: options.valueSignals || [],
-    riskSignals: options.riskSignals || [],
-    qualitySignals: options.qualitySignals || [],
-    frictionSignals: options.frictionSignals || [],
-    nextAction: options.nextAction || null,
-    reasonCodes: options.reasonCodes || [],
-    timestamp: options.timestamp || new Date().toISOString(),
-    redacted: true,
-  };
-  return entry;
-}
-
-function readOrchestrationEntry(cwd, artifacts) {
-  const art = artifacts.orchestration_plan;
-  if (!art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) {
-    return normalizeLedgerEntry("orchestration", "work_aware_orchestration", null, {
-      status: "warn",
-      summary: "Orchestration plan file exists but could not be parsed.",
-      evidencePath: art.rel,
-      evidenceKind: "receipt",
-      frictionSignals: ["corrupted_receipt"],
-    });
-  }
-
-  const stageCount = Array.isArray(data.stages) ? data.stages.length : 0;
-  const taskType = data.task?.taskType || "unknown";
-  const riskLevel = data.task?.riskLevel || "unknown";
-  const localStages = Array.isArray(data.stages)
-    ? data.stages.filter((s) => s.workerSelection?.costTier === "free_local").length
-    : 0;
-  const handoffReady = data.stageHandoff?.ready === true;
-  const valueEvidence = data.valueEvidence || {};
-
-  const valueSignals = [];
-  if (localStages > 0) valueSignals.push(`${localStages} local/cheap stage(s)`);
-  if (handoffReady) valueSignals.push("handoff_prepared");
-  if (valueEvidence.manualDecisionsAvoided > 0)
-    valueSignals.push("manual_decisions_avoided");
-  if (valueEvidence.unknownAssetsExcluded > 0)
-    valueSignals.push("unknown_assets_excluded");
-
-  const riskSignals = [];
-  if (riskLevel === "high" || riskLevel === "critical") riskSignals.push(`task_risk_${riskLevel}`);
-
-  const frictionSignals = [];
-  const contextReasonCodes = Array.isArray(data.stages)
-    ? data.stages.flatMap((s) => s.contextSelection?.reasonCodes || [])
-    : [];
-  if (contextReasonCodes.includes("NO_HYGIENE_REPORT"))
-    frictionSignals.push("no_hygiene_report_for_context");
-  if (contextReasonCodes.includes("INSPECT_MAP_FIRST"))
-    frictionSignals.push("inspect_before_context_selection");
-
-  return normalizeLedgerEntry("orchestration", "work_aware_orchestration", data, {
-    status: data.status || "pass",
-    summary: `Orchestration plan: ${stageCount} stage(s), task type ${taskType}, risk ${riskLevel}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    stageId: "orchestration",
-    valueSignals,
-    riskSignals,
-    frictionSignals,
-    reasonCodes: [],
-    nextAction: data.nextAction || null,
-  });
-}
-
-function readContextEntry(cwd, artifacts) {
-  const art = artifacts.context_receipt;
-  if (!art.exists) {
-    const packArt = artifacts.context_pack;
-    if (!packArt.exists) return null;
-  }
-
-  const source = art.exists ? art : artifacts.context_pack;
-  const data = safeReadJson(source.path);
-  if (!data) return null;
-
-  const tokensSaved = data.tokensSaved || data.estimatedTokensAvoided || 0;
-  const filesSelected = data.filesSelected || data.selectedFiles?.length || 0;
-  const filesExcluded = data.filesExcluded || data.excludedFiles?.length || 0;
-  const broadScansAvoided = data.broadScansAvoided || 0;
-
-  const valueSignals = [];
-  if (tokensSaved > 0) valueSignals.push(`~${tokensSaved} context tokens saved (estimate)`);
-  if (broadScansAvoided > 0) valueSignals.push(`${broadScansAvoided} broad scan(s) avoided`);
-  if (filesExcluded > 0) valueSignals.push(`${filesExcluded} file(s) excluded`);
-
-  return normalizeLedgerEntry("context", "context_optimizer", data, {
-    status: data.status || "pass",
-    summary: `Context: ${filesSelected} file(s) selected, ${filesExcluded} excluded, ~${tokensSaved} tokens saved (estimate).`,
-    evidencePath: source.rel,
-    evidenceKind: "receipt",
-    valueSignals,
-    riskSignals: [],
-    frictionSignals: [],
-    reasonCodes: data.reasonCodes || [],
-  });
-}
-
-function readWorkspaceHygieneEntry(cwd, artifacts) {
-  const art = artifacts.workspace_hygiene;
-  if (!art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) {
-    return normalizeLedgerEntry("workspace_hygiene", "ai_workspace_hygiene", null, {
-      status: "warn",
-      summary: "Workspace hygiene report exists but could not be parsed.",
-      evidencePath: art.rel,
-      frictionSignals: ["corrupted_receipt"],
-    });
-  }
-
-  const score = data.score || 0;
-  const totalAssets = data.summary?.totalAssets || 0;
-  const highRisk = data.summary?.highRiskAssets || 0;
-  const needsReview = data.summary?.needsReviewAssets || 0;
-  const status = data.status || (score >= 80 ? "pass" : score >= 60 ? "warn" : "fail");
-
-  const valueSignals = [];
-  if (highRisk > 0) valueSignals.push(`${highRisk} high-risk asset(s) detected`);
-  if (needsReview > 0) valueSignals.push(`${needsReview} asset(s) need review`);
-
-  const riskSignals = [];
-  if (highRisk > 0) riskSignals.push(`high_risk_assets:${highRisk}`);
-
-  return normalizeLedgerEntry("workspace_hygiene", "ai_workspace_hygiene", data, {
-    status,
-    summary: `Workspace hygiene: score ${score}/100, ${totalAssets} asset(s), ${highRisk} high-risk.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals,
-    riskSignals,
-    reasonCodes: data.topReasonCodes || [],
-    nextAction: data.nextAction || null,
-  });
-}
-
-function readOutcomeEntry(cwd, artifacts) {
-  const vsArt = artifacts.value_summary;
-  const outArt = artifacts.outcome;
-
-  const art = vsArt.exists ? vsArt : outArt.exists ? outArt : null;
-  if (!art) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const completed = data.completed || {};
-  const saved = data.saved || {};
-  const protected_ = data.protected || {};
-  const verified = data.verified || {};
-  const quality = data.quality || {};
-  const evidenceBacked = data.evidenceBacked !== false;
-
-  const valueSignals = [];
-  if (completed.completedItems > 0)
-    valueSignals.push(`${completed.completedItems} completed`);
-  if (completed.preparedItems > 0)
-    valueSignals.push(`${completed.preparedItems} prepared`);
-  if (saved.localStagesUsed > 0)
-    valueSignals.push(`${saved.localStagesUsed} local stage(s) used`);
-  if (protected_.unsafeActionsBlocked > 0)
-    valueSignals.push(`${protected_.unsafeActionsBlocked} unsafe action(s) blocked`);
-  if (verified.testsRun > 0)
-    valueSignals.push(`${verified.testsRun} test(s) run`);
-
-  const frictionSignals = [];
-  if (!evidenceBacked) frictionSignals.push("value_summary_not_evidence_backed");
-  if (completed.status === "unknown") frictionSignals.push("completion_status_unknown");
-
-  return normalizeLedgerEntry("outcome", "seamless_outcome", data, {
-    status: data.status || "pass",
-    summary: `Outcome: ${completed.completedItems || 0} completed, ${saved.localStagesUsed || 0} local stages, ${protected_.unsafeActionsBlocked || 0} blocked.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals,
-    frictionSignals,
-    reasonCodes: data.caveats || [],
-  });
-}
-
-function readRealityGateEntry(cwd, artifacts) {
-  const art = artifacts.reality_gate;
-  if (!art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const score = data.score || 0;
-  const summary = data.summary || {};
-  const status = data.status || "unknown";
-
-  const qualitySignals = [];
-  if (summary.pass > 0) qualitySignals.push(`${summary.pass} check(s) passed`);
-  if (summary.warn > 0) qualitySignals.push(`${summary.warn} warning(s)`);
-  if (summary.fail > 0) qualitySignals.push(`${summary.fail} failure(s)`);
-
-  const frictionSignals = [];
-  if (summary.fail > 0) frictionSignals.push(`reality_gate_failures:${summary.fail}`);
-  if (summary.warn > 0) frictionSignals.push(`reality_gate_warnings:${summary.warn}`);
-
-  return normalizeLedgerEntry("reality_gate", "seamless_reality_gate", data, {
-    status,
-    summary: `Reality Gate: ${score}/100 — ${summary.pass || 0} pass, ${summary.warn || 0} warn, ${summary.fail || 0} fail.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    qualitySignals,
-    frictionSignals,
-    nextAction: data.gaps?.[0]?.nextAction || null,
-    reasonCodes: (data.gaps || []).map((g) => g.id).slice(0, 5),
-  });
-}
-
-function readGuardEntry(cwd, artifacts) {
-  const art = artifacts.safe_path;
-  if (!art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const decision = data.lastDecision || data.decision || "unknown";
-  const blocked = decision === "block" ? 1 : 0;
-  const reductions = data.reductionsApplied || data.reductionsRecommended || 0;
-
-  const riskSignals = [];
-  if (blocked > 0) riskSignals.push("unsafe_action_blocked");
-  if ((data.topReasonCodes || []).includes("DESTRUCTIVE_COMMAND"))
-    riskSignals.push("destructive_command_detected");
-  if ((data.topReasonCodes || []).includes("DEPLOYMENT_CONFIG"))
-    riskSignals.push("deployment_config_access_guarded");
-
-  const valueSignals = [];
-  if (reductions > 0) valueSignals.push(`${reductions} reduction(s) applied`);
-  if (blocked > 0) valueSignals.push("unsafe_action_blocked");
-
-  return normalizeLedgerEntry("guard", "safe_path", data, {
-    status: "pass",
-    summary: `Safe Path: last decision ${decision}, ${reductions} reduction(s).`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    riskSignals,
-    valueSignals,
-    reasonCodes: data.topReasonCodes || [],
-  });
-}
-
-function readAgentAccessEntry(cwd, artifacts) {
-  const art = artifacts.agent_access_governance;
-  if (!art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const unknownSubjects = data.unknownSubjects || 0;
-  const status = data.status || "foundation";
-
-  const riskSignals = [];
-  if (unknownSubjects > 0) riskSignals.push(`unknown_subjects:${unknownSubjects}`);
-
-  return normalizeLedgerEntry("guard", "agent_access_governance", data, {
-    status: status === "pass" ? "pass" : "warn",
-    summary: `Agent Access Governance: status ${status}, ${unknownSubjects} unknown subject(s).`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    riskSignals,
-    reasonCodes: data.topReasonCodes || [],
-  });
-}
-
-function readProductLearningEntry(cwd, artifacts) {
-  const art = artifacts.product_learning;
-  if (!art.exists) return null;
-
-  const events = safeReadJsonl(art.path, 500);
-  if (!events || events.length === 0) return null;
-
-  const eventCounts = {};
-  const categories = {};
-  for (const ev of events) {
-    const name = ev.eventName || "unknown";
-    eventCounts[name] = (eventCounts[name] || 0) + 1;
-    const cat = ev.category || "unknown";
-    categories[cat] = (categories[cat] || 0) + 1;
-  }
-
-  const topEvents = Object.entries(eventCounts)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 5)
-    .map(([n, c]) => `${n}:${c}`);
-
-  return normalizeLedgerEntry("product_learning", "product_learning_events", null, {
-    status: "pass",
-    summary: `Product Learning: ${events.length} event(s). Top: ${topEvents.slice(0, 3).join(", ")}.`,
-    evidencePath: art.rel,
-    evidenceKind: "jsonl",
-    valueSignals: [`${events.length} events recorded`],
-    frictionSignals: [],
-    reasonCodes: [],
-  });
-}
-
-function readSmartRouteEntry(cwd, artifacts) {
-  const art = artifacts.smart_route;
-  if (!art || !art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const decision = data.decision || "unknown";
-  const pathType = (data.executionPath && data.executionPath.pathType) || "unknown";
-  const reasonCodes = (data.executionPath && data.executionPath.reasonCodes) || [];
-  const proofRequired = (data.executionPath && data.executionPath.proofRequired) || false;
-  const sameSurfacePreferred = (data.executionPath && data.executionPath.sameSurfacePreferred) !== false;
-
-  const valueSignals = [];
-  if (pathType === "local_or_cheap" || pathType === "local_deterministic") {
-    valueSignals.push("local_or_cheap_path_selected");
-  }
-  if (sameSurfacePreferred) valueSignals.push("same_surface_preferred");
-
-  const riskSignals = [];
-  if (reasonCodes.includes("DESTRUCTIVE_ACTION_BLOCKED")) riskSignals.push("destructive_action_blocked");
-  if (reasonCodes.includes("SECRETS_EXCLUDED_FROM_CONTEXT")) riskSignals.push("secrets_excluded");
-  if (reasonCodes.includes("DEPLOY_REQUIRES_APPROVAL")) riskSignals.push("deploy_approval_required");
-  if (reasonCodes.includes("EXTERNAL_AGENT_REQUIRES_APPROVAL")) riskSignals.push("remote_agent_blocked");
-
-  return normalizeLedgerEntry("smart_route", "smart_work_routing", data, {
-    status: decision === "blocked" ? "warn" : "pass",
-    summary: `Smart route: decision=${decision}, path=${pathType}, proof=${proofRequired ? "required" : "optional"}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals,
-    riskSignals,
-    reasonCodes: reasonCodes.slice(0, 5),
-  });
-}
-
-function readSafeRunEntry(cwd, artifacts) {
-  const art = artifacts.safe_run;
-  if (!art || !art.exists) return null;
-
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-
-  const decision = data.decision || "prepared";
-  const localStepsRun = (data.executionSummary && data.executionSummary.localStepsRun) || 0;
-  const localStepsPassed = (data.executionSummary && data.executionSummary.localStepsPassed) || 0;
-
-  const valueSignals = [];
-  if (localStepsPassed > 0) valueSignals.push(`${localStepsPassed} local proof step(s) passed`);
-  if (data.safety && data.safety.deployBlocked) valueSignals.push("deploy_blocked");
-  if (data.safety && data.safety.secretsExcluded) valueSignals.push("secrets_excluded");
-  if (data.safety && data.safety.remoteAgentExecutionBlocked) valueSignals.push("remote_agent_execution_blocked");
-
-  const frictionSignals = [];
-  if (decision === "approval_required") frictionSignals.push("approval_required");
-  if (decision === "blocked") frictionSignals.push("task_blocked");
-  const failed = (data.executionSummary && data.executionSummary.localStepsFailed) || 0;
-  if (failed > 0) frictionSignals.push(`local_steps_failed:${failed}`);
-
-  return normalizeLedgerEntry("safe_run", "safe_run_controller", data, {
-    // blocked/approval_required = safety working correctly (warn), not a failure
-    status: decision === "verified" ? "pass" : "warn",
-    summary: `Safe run: decision=${decision}, localStepsRun=${localStepsRun}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals,
-    frictionSignals,
-    reasonCodes: [],
-  });
-}
-
-function readFeedbackEntries(cwd, artifacts) {
-  const art = artifacts.feedback_dir;
-  if (!art.exists) return [];
-
-  const entries = [];
-  try {
-    const files = fs.readdirSync(art.path).filter((f) => f.endsWith(".json"));
-    for (const f of files.slice(0, 20)) {
-      const filePath = path.join(art.path, f);
-      const data = safeReadJson(filePath);
-      if (!data) continue;
-      entries.push(
-        normalizeLedgerEntry("feedback", data.source || "manual", data, {
-          status: "pass",
-          summary: data.summary
-            ? data.summary.slice(0, 120)
-            : "Feedback signal loaded.",
-          evidencePath: path.join(art.rel, f),
-          evidenceKind: "feedback",
-          frictionSignals: data.frictionType ? [data.frictionType] : [],
-          reasonCodes: data.frictionType ? [data.frictionType] : [],
-        })
-      );
-    }
-  } catch {
-    // skip feedback dir read errors
-  }
-  return entries;
-}
-
-function readHookBaselineEntry(cwd, artifacts) {
-  const art = artifacts.hook_baseline;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  return normalizeLedgerEntry("hook_baseline", "hook_baseline", data, {
-    status: "pass",
-    summary: `Hook baseline: ${data.hookCount || 0} events registered. Install status: ${data.installStatus || "preview_only"}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: ["hook_baseline_ready", "lifecycle_automation_prepared"],
-    frictionSignals: data.installStatus === "preview_only" ? ["hooks_not_yet_installed"] : [],
-    reasonCodes: ["HOOK_BASELINE_BUILT"],
-  });
-}
-
-function readAdapterReadinessEntry(cwd, artifacts) {
-  const art = artifacts.adapter_readiness;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  const detectedCount = (data.hosts || []).filter((h) => h.detected && !h.fallback).length;
-  return normalizeLedgerEntry("adapter_readiness", "adapter_readiness", data, {
-    status: data.status === "needs_review" ? "warn" : "pass",
-    summary: `Adapter readiness: ${data.status}. ${detectedCount} host(s) detected.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: detectedCount > 0 ? ["host_adapter_detected"] : ["generic_cli_fallback_available"],
-    frictionSignals: data.status === "needs_review" ? ["adapter_config_needs_review"] : [],
-    reasonCodes: ["ADAPTER_READINESS_DETECTED"],
-  });
-}
-
-function readHookConfigPreviewEntry(cwd, artifacts) {
-  const art = artifacts.hook_config_preview;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  return normalizeLedgerEntry("hook_config_preview", "hook_config_preview", data, {
-    status: "pass",
-    summary: `Hook config preview: mode=${data.mode || "preview_only"}. No user config modified. Approval required.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: ["hook_config_preview_ready"],
-    frictionSignals: ["hooks_not_yet_applied"],
-    reasonCodes: ["HOOK_CONFIG_PREVIEW_GENERATED"],
-  });
-}
-
-function readHookApplyEntry(cwd, artifacts) {
-  const art = artifacts.hook_apply;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  const isApplied = data.applied === true;
-  const isRolledBack = data.status === "rolled_back";
-  const isUninstalled = data.status === "uninstalled";
-  const isDryRun = data.status === "dry_run";
-  return normalizeLedgerEntry("hook_apply", "hook_apply", data, {
-    status: isApplied ? "pass" : isDryRun ? "pass" : "warn",
-    summary: `Hook apply: status=${data.status}. Hosts applied: ${(data.hostsApplied || []).map((h) => h.host).join(", ") || "none"}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: isApplied ? ["hooks_applied", "lifecycle_live"] : isDryRun ? ["hook_apply_dry_run_ready"] : [],
-    frictionSignals: !isApplied && !isDryRun && !isRolledBack && !isUninstalled
-      ? ["hooks_not_yet_applied"]
-      : [],
-    reasonCodes: isApplied ? ["HOOKS_APPLIED", "LIFECYCLE_LIVE"]
-      : isRolledBack ? ["HOOKS_ROLLED_BACK"]
-      : isUninstalled ? ["HOOKS_UNINSTALLED"]
-      : isDryRun ? ["DRY_RUN_ONLY"]
-      : ["APPROVAL_REQUIRED"],
-  });
-}
-
-function readHookDoctorEntry(cwd, artifacts) {
-  const art = artifacts.hook_doctor;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  return normalizeLedgerEntry("hook_doctor", "hook_doctor", data, {
-    status: data.status === "pass" ? "pass" : data.status === "warn" ? "warn" : "warn",
-    summary: `Hook doctor: ${data.status}. pass=${data.summary?.pass || 0} warn=${data.summary?.warn || 0} fail=${data.summary?.fail || 0}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: data.status === "pass" ? ["lifecycle_live_smoke_passed"] : [],
-    frictionSignals: data.status !== "pass" ? ["hook_doctor_needs_attention"] : [],
-    reasonCodes: ["HOOK_DOCTOR_RUN"],
-  });
-}
-
-// PR #142 — Activation Alpha Readiness + First Value
-function readAlphaActivationEntry(cwd, artifacts) {
-  const art = artifacts.alpha_activation;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  const checksPass = (data.checks || []).filter((c) => c.status === "pass").length;
-  const checksWarn = (data.checks || []).filter((c) => c.status === "warn").length;
-  const checksFail = (data.checks || []).filter((c) => c.status === "fail").length;
-  return normalizeLedgerEntry("alpha_activation", "alpha_activation", data, {
-    status: data.status === "ready" ? "pass" : data.status === "blocked" ? "fail" : "warn",
-    summary: `Alpha activation: ${data.status}. Stage: ${data.activationStage || "unknown"}. Checks: ${checksPass} pass, ${checksWarn} warn, ${checksFail} fail.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: data.status === "ready" ? ["activation_ready"] : [],
-    frictionSignals: data.status !== "ready" ? [`activation_${data.status}`] : [],
-    reasonCodes: ["ALPHA_ACTIVATION_CHECKED"],
-  });
-}
-
-function readAlphaReadinessGateEntry(cwd, artifacts) {
-  const art = artifacts.alpha_readiness_gate;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  return normalizeLedgerEntry("alpha_readiness_gate", "alpha_readiness_gate", data, {
-    status: data.status === "pass" ? "pass" : data.status === "fail" ? "fail" : "warn",
-    summary: `Alpha readiness gate: ${data.status} (score: ${data.score || 0}/100). pass=${data.summary?.pass || 0} warn=${data.summary?.warn || 0} fail=${data.summary?.fail || 0}.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: data.status === "pass" ? ["alpha_readiness_confirmed"] : [],
-    frictionSignals: data.status !== "pass" ? ["alpha_readiness_incomplete"] : [],
-    reasonCodes: ["ALPHA_READINESS_GATE_RUN"],
-  });
-}
-
-function readSupportBundleEntry(cwd, artifacts) {
-  const art = artifacts.support_bundle;
-  if (!art || !art.exists) return null;
-  const data = safeReadJson(art.path);
-  if (!data) return null;
-  return normalizeLedgerEntry("support_bundle", "support_bundle", data, {
-    status: data.status === "ready" ? "pass" : "warn",
-    summary: `Support bundle: ${data.status}. ${data.summary?.artifactsAvailable || 0} artifacts, ${data.summary?.feedbackItems || 0} feedback items.`,
-    evidencePath: art.rel,
-    evidenceKind: "receipt",
-    valueSignals: ["support_bundle_available"],
-    frictionSignals: [],
-    reasonCodes: ["SUPPORT_BUNDLE_GENERATED"],
-  });
-}
-
-function buildWorkLedger(cwd, options = {}) {
-  const runId = createRunId(options.runIdInput || cwd);
-  const artifacts = readAvailableWorkArtifacts(cwd);
-  const entries = [];
-  const warnings = [];
-
-  const readers = [
-    () => readOrchestrationEntry(cwd, artifacts),
-    () => readContextEntry(cwd, artifacts),
-    () => readWorkspaceHygieneEntry(cwd, artifacts),
-    () => readGuardEntry(cwd, artifacts),
-    () => readAgentAccessEntry(cwd, artifacts),
-    () => readSmartRouteEntry(cwd, artifacts),
-    () => readSafeRunEntry(cwd, artifacts),
-    () => readOutcomeEntry(cwd, artifacts),
-    () => readRealityGateEntry(cwd, artifacts),
-    () => readProductLearningEntry(cwd, artifacts),
-    // PR #140 — Hook Baseline + Lifecycle Automation Preview
-    () => readHookBaselineEntry(cwd, artifacts),
-    () => readAdapterReadinessEntry(cwd, artifacts),
-    () => readHookConfigPreviewEntry(cwd, artifacts),
-    // PR #141 — Explicit Hook Apply + Lifecycle Live
-    () => readHookApplyEntry(cwd, artifacts),
-    () => readHookDoctorEntry(cwd, artifacts),
-    // PR #142 — Activation Alpha Readiness + First Value
-    () => readAlphaActivationEntry(cwd, artifacts),
-    () => readAlphaReadinessGateEntry(cwd, artifacts),
-    () => readSupportBundleEntry(cwd, artifacts),
-  ];
-
-  for (const reader of readers) {
-    try {
-      const entry = reader();
-      if (entry) entries.push(entry);
-    } catch (err) {
-      warnings.push(`Reader error: ${err.message}`);
-    }
-  }
-
-  const feedbackEntries = readFeedbackEntries(cwd, artifacts);
-  entries.push(...feedbackEntries);
-
-  // Rollup
-  const completed = [];
-  const saved = [];
-  const protected_ = [];
-  const verified = [];
-  const quality = [];
-  const friction = [];
-  const feedbackSummary = [];
-
-  for (const e of entries) {
-    if ((e.type === "orchestration" || e.type === "smart_route" || e.type === "safe_run") && e.status !== "warn" && e.status !== "fail") {
-      completed.push(e.summary);
-    }
-    for (const v of e.valueSignals || []) {
-      if (
-        v.includes("token") ||
-        v.includes("local") ||
-        v.includes("avoided") ||
-        v.includes("excluded")
-      ) {
-        saved.push(v);
-      }
-    }
-    for (const r of e.riskSignals || []) {
-      protected_.push(r);
-    }
-    if (e.type === "reality_gate") {
-      for (const q of e.qualitySignals || []) {
-        verified.push(q);
-      }
-    }
-    if (e.type === "outcome") {
-      for (const v of e.valueSignals || []) {
-        if (v.includes("test")) verified.push(v);
-      }
-    }
-    if (e.type === "workspace_hygiene" || e.type === "orchestration") {
-      for (const q of e.qualitySignals || []) quality.push(q);
-    }
-    for (const f of e.frictionSignals || []) {
-      friction.push(f);
-    }
-    if (e.type === "feedback") {
-      feedbackSummary.push(e.summary);
-    }
-  }
-
-  const gateEntry = entries.find((e) => e.type === "reality_gate");
-  const nextAction =
-    gateEntry?.nextAction ||
-    entries.find((e) => e.nextAction)?.nextAction ||
-    "Run node bin/avorelo outcome to see current state.";
-
-  const rollup = {
-    completed: completed.length > 0 ? completed : ["not_available"],
-    saved: [...new Set(saved)].slice(0, 8),
-    protected: [...new Set(protected_)].slice(0, 8),
-    verified: [...new Set(verified)].slice(0, 8),
-    quality: [...new Set(quality)].slice(0, 8),
-    friction: [...new Set(friction)].slice(0, 10),
-    feedback: feedbackSummary.slice(0, 5),
-    nextAction,
-  };
-
-  const existingPaths = Object.values(artifacts)
-    .filter((a) => a.exists && a.rel && !a.rel.endsWith("/"))
-    .map((a) => a.rel);
-
-  const plEventArt = artifacts.product_learning;
-  const plEvents = plEventArt.exists ? safeReadJsonl(plEventArt.path, 500) : null;
-  const eventCounts = {};
-  if (plEvents) {
-    for (const ev of plEvents) {
-      const name = ev.eventName || "unknown";
-      eventCounts[name] = (eventCounts[name] || 0) + 1;
-    }
-  }
-
-  const feedbackArt = artifacts.feedback_dir;
-  const feedbackPaths = [];
-  if (feedbackArt.exists) {
-    try {
-      const files = fs.readdirSync(feedbackArt.path).filter((f) => f.endsWith(".json"));
-      feedbackPaths.push(...files.map((f) => path.join(feedbackArt.rel, f)));
-    } catch {
-      // ignore
-    }
-  }
-
-  const overallStatus =
-    entries.some((e) => e.status === "fail")
-      ? "fail"
-      : entries.some((e) => e.status === "warn")
-      ? "warn"
-      : entries.length === 0
-      ? "empty"
-      : "pass";
-
-  const ledger = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    runId,
-    status: overallStatus,
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    entries,
-    rollup,
-    evidence: {
-      receiptPaths: existingPaths,
-      eventCounts,
-      dogfoodPaths: [],
-      feedbackPaths,
-    },
-    caveats: [
-      "Savings and token estimates are approximations based on receipt data.",
-      "Absent receipts produce not_available entries.",
-      warnings.length > 0 ? `Reader warnings: ${warnings.join("; ")}` : null,
-    ].filter(Boolean),
-    warnings: warnings.length > 0 ? warnings : undefined,
-    redacted: true,
-  };
-
-  return ledger;
-}
-
-function writeWorkLedger(cwd, ledger) {
-  const dir = path.join(cwd, LEDGER_DIR_REL);
-  fs.mkdirSync(dir, { recursive: true });
-  const filePath = path.join(cwd, LATEST_LEDGER_REL);
-  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), "utf8");
-  return filePath;
-}
-
-function buildWorkLedgerSurface(cwd) {
-  const ledgerPath = path.join(cwd, LATEST_LEDGER_REL);
-  if (!fs.existsSync(ledgerPath)) {
-    return {
-      status: "not_available",
-      latestLedgerPath: LATEST_LEDGER_REL,
-      entryCount: 0,
-      completedCount: 0,
-      frictionCount: 0,
-      nextAction: "Run node bin/avorelo ledger to generate.",
-    };
-  }
-  const data = safeReadJson(ledgerPath);
-  if (!data) {
-    return {
-      status: "warn",
-      latestLedgerPath: LATEST_LEDGER_REL,
-      entryCount: 0,
-      completedCount: 0,
-      frictionCount: 0,
-      nextAction: "Ledger file corrupt. Re-run node bin/avorelo ledger.",
-    };
-  }
-  const completedCount = (data.rollup?.completed || []).filter(
-    (c) => c !== "not_available"
-  ).length;
-  const frictionCount = (data.rollup?.friction || []).length;
-  return {
-    status: data.status || "unknown",
-    latestLedgerPath: LATEST_LEDGER_REL,
-    entryCount: (data.entries || []).length,
-    completedCount,
-    frictionCount,
-    nextAction: data.rollup?.nextAction || null,
-  };
-}
-
-function formatWorkLedgerText(ledger, options = {}) {
-  const debug = options.debug === true;
-  const lines = [];
-
-  const statusLabel =
-    ledger.status === "pass"
-      ? "pass"
-      : ledger.status === "warn"
-      ? "warn"
-      : ledger.status === "fail"
-      ? "fail"
-      : ledger.status;
-
-  lines.push(`Avorelo Work Ledger: ${statusLabel}`);
-  lines.push(`Run: ${ledger.runId}`);
-  lines.push("");
-
-  const { rollup } = ledger;
-
-  if (rollup.completed.some((c) => c !== "not_available")) {
-    lines.push("Completed:");
-    for (const c of rollup.completed) {
-      if (c !== "not_available") lines.push(`  - ${c}`);
-    }
-    lines.push("");
-  }
-
-  if (rollup.saved.length > 0) {
-    lines.push("Saved:");
-    for (const s of rollup.saved) lines.push(`  - ${s}`);
-    lines.push("");
-  }
-
-  if (rollup.protected.length > 0) {
-    lines.push("Protected:");
-    for (const p of rollup.protected) lines.push(`  - ${p}`);
-    lines.push("");
-  }
-
-  if (rollup.verified.length > 0) {
-    lines.push("Verified:");
-    for (const v of rollup.verified) lines.push(`  - ${v}`);
-    lines.push("");
-  }
-
-  if (rollup.friction.length > 0) {
-    lines.push("Friction:");
-    for (const f of rollup.friction) lines.push(`  - ${f}`);
-    lines.push("");
-  }
-
-  if (rollup.feedback.length > 0) {
-    lines.push("Feedback:");
-    for (const fb of rollup.feedback) lines.push(`  - ${fb}`);
-    lines.push("");
-  }
-
-  if (rollup.nextAction) {
-    lines.push(`Next:`);
-    lines.push(`  ${rollup.nextAction}`);
-    lines.push("");
-  }
-
-  if (debug) {
-    lines.push("--- Debug: Ledger Entries ---");
-    for (const entry of ledger.entries) {
-      lines.push(`[${entry.type}] ${entry.source}: ${entry.status}`);
-      lines.push(`  Summary: ${entry.summary}`);
-      if (entry.evidencePath) lines.push(`  Evidence: ${entry.evidencePath}`);
-      if (entry.reasonCodes?.length > 0)
-        lines.push(`  Codes: ${entry.reasonCodes.join(", ")}`);
-      if (entry.frictionSignals?.length > 0)
-        lines.push(`  Friction: ${entry.frictionSignals.join(", ")}`);
-    }
-    lines.push("");
-
-    lines.push("--- Debug: Evidence Paths ---");
-    for (const p of ledger.evidence.receiptPaths) {
-      lines.push(`  ${p}`);
-    }
-    lines.push("");
-
-    if (ledger.caveats?.length > 0) {
-      lines.push("--- Debug: Caveats ---");
-      for (const c of ledger.caveats) lines.push(`  ${c}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  ENTRY_TYPES,
-  LATEST_LEDGER_REL,
-  ARTIFACT_PATHS,
-  createRunId,
-  readAvailableWorkArtifacts,
-  normalizeLedgerEntry,
-  buildWorkLedger,
-  writeWorkLedger,
-  buildWorkLedgerSurface,
-  formatWorkLedgerText,
-};