avorelo 0.1.0

package/scripts/lib/work-ledger.js

@@ -0,0 +1,1123 @@
+"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,
+};