avorelo 0.1.0 → 0.3.0

package/scripts/lib/install-journey-intelligence.js

@@ -1,329 +0,0 @@
-"use strict";
-
-// ── Install Journey Intelligence ──────────────────────────────────────────────
-//
-// Contract: avorelo.installJourneyIntelligence.v1
-//
-// Computes the install/activation funnel from existing artifacts.
-// Missing optional steps → warn. Missing core steps → warn with recovery.
-// No public launch claim.
-
-const fs = require("fs");
-const path = require("path");
-const { nowIso } = require("./fsx");
-const { appendProductLearningEvent } = require("./product-learning-events");
-
-const CONTRACT = "avorelo.installJourneyIntelligence.v1";
-const SCHEMA_VERSION = 1;
-const INTELLIGENCE_DIR_REL = ".claude/cco/orchestration/prelaunch-intelligence";
-const ARTIFACT_REL = `${INTELLIGENCE_DIR_REL}/latest-install-journey.json`;
-
-const FUNNEL_STEPS = [
-  {
-    id: "install_prompt_generated",
-    label: "Install prompt generated",
-    artifactRel: ".claude/cco/orchestration/ai-install/latest-prompt.json",
-    required: true,
-    recoveryAction: "Run: node bin/avorelo install-ai --json",
-  },
-  {
-    id: "activation_checked",
-    label: "Activation checked",
-    artifactRel: ".claude/cco/orchestration/activation/latest-activation.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo activate --json",
-  },
-  {
-    id: "first_value_checked",
-    label: "First value checked",
-    artifactRel: ".claude/cco/orchestration/prelaunch-readiness/latest-activation-readiness.json",
-    required: true,
-    recoveryAction: "Run: node bin/avorelo first-value-check --json",
-  },
-  {
-    id: "hook_status_known",
-    label: "Hook status known",
-    artifactRel: ".claude/cco/orchestration/hook-apply/latest-doctor.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo hooks doctor --json",
-  },
-  {
-    id: "token_context_checked",
-    label: "Token/context checked",
-    artifactRel: ".claude/cco/orchestration/token-efficiency/latest-evidence.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo token-efficiency --json",
-  },
-  {
-    id: "mcp_governance_checked",
-    label: "MCP governance checked",
-    artifactRel: ".claude/cco/orchestration/mcp-tool-governance/latest-inventory.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo mcp doctor --json",
-  },
-  {
-    id: "launch_hardening_checked",
-    label: "Launch hardening checked",
-    artifactRel: ".claude/cco/orchestration/launch-hardening/latest-gate.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo launch-hardening --json",
-  },
-  {
-    id: "support_bundle_available",
-    label: "Support bundle available",
-    artifactRel: ".claude/cco/support/latest-support-bundle.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo support-bundle --json",
-  },
-  {
-    id: "proof_or_outcome_available",
-    label: "Proof or outcome available",
-    artifactRel: ".claude/cco/orchestration/seamless-outcome/latest-value-summary.json",
-    required: false,
-    recoveryAction: "Run: node bin/avorelo proof after completing a task.",
-  },
-];
-
-// Manual steps that Avorelo automates
-const MANUAL_STEPS_AVOIDED = [
-  {
-    id: "manual_install_prompt_research",
-    label: "Manual AI install prompt research",
-    avoidedBy: "install_prompt_generated",
-    evidenceBacked: true,
-  },
-  {
-    id: "manual_hook_config_review",
-    label: "Manual hook configuration review",
-    avoidedBy: "hook_status_known",
-    evidenceBacked: true,
-  },
-  {
-    id: "manual_mcp_risk_review",
-    label: "Manual MCP/tool risk review",
-    avoidedBy: "mcp_governance_checked",
-    evidenceBacked: true,
-  },
-  {
-    id: "manual_token_cost_estimation",
-    label: "Manual token/cost estimation",
-    avoidedBy: "token_context_checked",
-    evidenceBacked: true,
-  },
-];
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function collectInstallJourneySignals(cwd, options = {}) {
-  const stepStatuses = {};
-  for (const step of FUNNEL_STEPS) {
-    const absPath = path.join(cwd, step.artifactRel);
-    const artifact = safeReadJson(absPath);
-    stepStatuses[step.id] = {
-      present: artifact !== null,
-      artifactStatus: artifact?.status || null,
-      artifactPath: step.artifactRel,
-    };
-  }
-  return stepStatuses;
-}
-
-function buildInstallJourneyFunnel(cwd, options = {}) {
-  const signals = collectInstallJourneySignals(cwd, options);
-
-  const funnel = FUNNEL_STEPS.map((step) => {
-    const signal = signals[step.id];
-    let status;
-    if (!signal.present) {
-      status = step.required ? "missing_required" : "missing_optional";
-    } else if (signal.artifactStatus === "fail") {
-      status = "fail";
-    } else if (signal.artifactStatus === "warn") {
-      status = "warn";
-    } else {
-      status = "ready";
-    }
-    return {
-      id: step.id,
-      label: step.label,
-      status,
-      required: step.required,
-      artifactPath: step.artifactRel,
-      recoveryAction: (status === "ready" || status === "warn") ? null : step.recoveryAction,
-    };
-  });
-
-  // Drop-offs: steps that are missing or failed
-  const dropOffs = funnel.filter((s) => s.status === "missing_required" || s.status === "fail");
-  const optionalMissing = funnel.filter((s) => s.status === "missing_optional");
-
-  // Blockers: required steps missing/failed
-  const blockers = dropOffs.map((s) => ({
-    step: s.id,
-    label: s.label,
-    status: s.status,
-    recoveryAction: s.recoveryAction,
-  }));
-
-  // Warnings: optional steps missing
-  const warnings = optionalMissing.map((s) => ({
-    step: s.id,
-    label: s.label,
-    status: s.status,
-    recoveryAction: s.recoveryAction,
-  }));
-
-  // Manual steps avoided
-  const manualStepsAvoided = MANUAL_STEPS_AVOIDED.filter((m) => {
-    const avoidedSignal = signals[m.avoidedBy];
-    return avoidedSignal && avoidedSignal.present;
-  }).map((m) => ({
-    id: m.id,
-    label: m.label,
-    evidenceBacked: m.evidenceBacked,
-    evidenceRef: signals[m.avoidedBy]?.artifactPath || null,
-  }));
-
-  // Overall status
-  let journeyStatus;
-  if (blockers.length > 0) {
-    journeyStatus = "warn"; // not fail — missing optional steps don't block the journey
-  } else if (warnings.length > 3) {
-    journeyStatus = "warn";
-  } else {
-    journeyStatus = "ready";
-  }
-
-  // Next action
-  let nextAction;
-  if (blockers.length > 0) {
-    nextAction = blockers[0].recoveryAction;
-  } else if (warnings.length > 0) {
-    nextAction = warnings[0].recoveryAction || `Run: node bin/avorelo activate --json`;
-  } else {
-    nextAction = "Run node bin/avorelo proof to document value.";
-  }
-
-  return {
-    funnel,
-    dropOffs,
-    blockers,
-    warnings,
-    manualStepsAvoided,
-    journeyStatus,
-    nextAction,
-    stepsComplete: funnel.filter((s) => s.status === "ready" || s.status === "warn").length,
-    stepsTotal: funnel.length,
-  };
-}
-
-function buildInstallJourneyIntelligence(cwd, options = {}) {
-  const funnelData = buildInstallJourneyFunnel(cwd, options);
-
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    createdAt: nowIso(),
-    status: funnelData.journeyStatus,
-    funnel: funnelData.funnel,
-    dropOffs: funnelData.dropOffs,
-    blockers: funnelData.blockers,
-    warnings: funnelData.warnings,
-    manualStepsAvoided: funnelData.manualStepsAvoided,
-    stepsComplete: funnelData.stepsComplete,
-    stepsTotal: funnelData.stepsTotal,
-    nextAction: funnelData.nextAction,
-    noPublicLaunchClaim: true,
-    redacted: true,
-  };
-}
-
-function writeInstallJourneyIntelligence(cwd, intelligence) {
-  const dirAbs = path.join(cwd, INTELLIGENCE_DIR_REL);
-  fs.mkdirSync(dirAbs, { recursive: true });
-  const absPath = path.join(cwd, ARTIFACT_REL);
-  fs.writeFileSync(absPath, JSON.stringify(intelligence, null, 2), "utf8");
-  return absPath;
-}
-
-function buildInstallJourneySurface(cwd, options = {}) {
-  const absPath = path.join(cwd, ARTIFACT_REL);
-  const existing = safeReadJson(absPath);
-  if (existing) {
-    return {
-      status: existing.status,
-      stepsComplete: existing.stepsComplete,
-      stepsTotal: existing.stepsTotal,
-      blockers: existing.blockers?.length || 0,
-      manualStepsAvoided: existing.manualStepsAvoided?.length || 0,
-      artifactPath: ARTIFACT_REL,
-    };
-  }
-  const intel = buildInstallJourneyIntelligence(cwd, options);
-  writeInstallJourneyIntelligence(cwd, intel);
-  return {
-    status: intel.status,
-    stepsComplete: intel.stepsComplete,
-    stepsTotal: intel.stepsTotal,
-    blockers: intel.blockers?.length || 0,
-    manualStepsAvoided: intel.manualStepsAvoided?.length || 0,
-    artifactPath: ARTIFACT_REL,
-  };
-}
-
-function formatInstallJourneyText(intelligence, options = {}) {
-  const debug = options.debug === true;
-  const lines = [];
-
-  lines.push(`Install journey: ${intelligence.status}`);
-  lines.push(`  Steps: ${intelligence.stepsComplete}/${intelligence.stepsTotal} ready`);
-  lines.push(`  Manual steps avoided: ${intelligence.manualStepsAvoided?.length || 0}`);
-
-  if (intelligence.blockers?.length > 0) {
-    lines.push(`  Blockers: ${intelligence.blockers.length}`);
-    if (debug) {
-      for (const b of intelligence.blockers) {
-        lines.push(`    - ${b.label} [${b.status}]`);
-        if (b.recoveryAction) lines.push(`      Recovery: ${b.recoveryAction}`);
-      }
-    }
-  }
-
-  if (intelligence.warnings?.length > 0) {
-    lines.push(`  Warnings: ${intelligence.warnings.length}`);
-  }
-
-  lines.push(`  Next: ${intelligence.nextAction}`);
-
-  if (debug && intelligence.funnel) {
-    lines.push("");
-    lines.push("Funnel:");
-    for (const step of intelligence.funnel) {
-      const icon = step.status === "ready" ? "+" : step.status === "warn" ? "~" : "-";
-      lines.push(`  ${icon} [${step.status}] ${step.label}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  ARTIFACT_REL,
-  FUNNEL_STEPS,
-  MANUAL_STEPS_AVOIDED,
-  collectInstallJourneySignals,
-  buildInstallJourneyFunnel,
-  buildInstallJourneyIntelligence,
-  writeInstallJourneyIntelligence,
-  buildInstallJourneySurface,
-  formatInstallJourneyText,
-};

package/scripts/lib/intervention-guidance.js

@@ -1,57 +0,0 @@
-"use strict";
-
-const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
-
-const LATEST_INTERVENTION_PATH = ".claude/cco/state/latest-intervention.json";
-
-function ensureSentence(text, fallback) {
-  const value = String(text || "").trim();
-  const out = value || fallback;
-  return /[.!?]$/.test(out) ? out : `${out}.`;
-}
-
-function normalizePath(value) {
-  if (value === null || value === undefined || value === "") return null;
-  return String(value);
-}
-
-function buildInterventionSnapshot(input = {}) {
-  return {
-    interventionVersion: 1,
-    createdAt: nowIso(),
-    sessionId: String(input.sessionId || "unknown"),
-    eventName: String(input.eventName || "unknown"),
-    kind: String(input.kind || "intervention"),
-    whatHappened: ensureSentence(input.whatHappened, "Wuz paused the current step."),
-    nextAction: ensureSentence(input.nextAction, "Continue with the smallest safe next step."),
-    preservedState: ensureSentence(input.preservedState, "Current repo state was preserved."),
-    artifactPath: normalizePath(input.artifactPath),
-  };
-}
-
-function writeLatestIntervention(cwd, input) {
-  const snapshot = buildInterventionSnapshot(input);
-  safeWriteJson(cwd, LATEST_INTERVENTION_PATH, snapshot);
-  return { snapshot, path: LATEST_INTERVENTION_PATH };
-}
-
-function loadLatestIntervention(cwd) {
-  return safeReadJson(cwd, LATEST_INTERVENTION_PATH, null);
-}
-
-function formatInterventionMessage(input = {}) {
-  const snapshot = buildInterventionSnapshot(input);
-  const parts = [snapshot.whatHappened, `Next: ${snapshot.nextAction}`, `Preserved: ${snapshot.preservedState}`];
-  if (snapshot.artifactPath) {
-    parts.push(`Artifact: ${snapshot.artifactPath}.`);
-  }
-  return parts.join(" ");
-}
-
-module.exports = {
-  LATEST_INTERVENTION_PATH,
-  buildInterventionSnapshot,
-  writeLatestIntervention,
-  loadLatestIntervention,
-  formatInterventionMessage,
-};

package/scripts/lib/known-limitations.js

@@ -1,115 +0,0 @@
-"use strict";
-
-// ── Known Limitations Register ────────────────────────────────────────────────
-// Contract: avorelo.knownLimitations.v1
-// Documents known limitations of Avorelo for external pre-launch use.
-// Blocker limitations block candidate_ready. Accepted limitations allow warn.
-
-const fs = require("fs");
-const path = require("path");
-const { nowIso } = require("./fsx");
-const { appendProductLearningEvent } = require("./product-learning-events");
-
-const CONTRACT = "avorelo.knownLimitations.v1";
-const SCHEMA_VERSION = 1;
-const LIMITATIONS_DIR_REL = ".claude/cco/orchestration/full-readiness";
-const ARTIFACT_REL = LIMITATIONS_DIR_REL + "/latest-known-limitations.json";
-
-var LIMITATION_CATEGORIES = Object.freeze(["install_distribution", "exact_cost_unavailable", "feedback_insufficient", "browser_proof_missing", "plugin_adapter_pending", "mcp_config_preview_only", "hook_apply_requires_approval", "token_estimate_approximate", "support_scope_local_only", "external_project_coverage_unknown", "unknown"]);
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch { return null; }
-}
-
-function getBaselineLimitations() {
-  return [
-    { id: "exact_cost_unavailable", category: "exact_cost_unavailable", severity: "info", userImpact: "Token/cost savings shown as estimates only unless real usage evidence is imported.", releaseImpact: "Acceptable for pre-launch. Cannot make exact ROI claims in any launch material.", mitigation: "Import real token/cost usage samples or keep all cost outputs caveated with noExactSavingsClaim=true.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/prelaunch-intelligence/latest-token-cost-intelligence.json"], redacted: true },
-    { id: "feedback_insufficient", category: "feedback_insufficient", severity: "warn", userImpact: "Feedback intelligence stays insufficient until qualified redacted feedback evidence exists.", releaseImpact: "Cannot cluster friction patterns confidently without real local feedback evidence.", mitigation: "Add dogfood feedback via `avorelo feedback add` or import structured redacted feedback evidence.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/prelaunch-intelligence/latest-feedback-intelligence.json"], redacted: true },
-    { id: "install_distribution", category: "install_distribution", severity: "warn", userImpact: "Avorelo is not yet distributed via npm or a public install mechanism.", releaseImpact: "External users need direct repo access until a distribution-readiness slice is completed.", mitigation: "One-prompt AI install works for repo-local use. Distribution remains a separate readiness layer.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/ai-install/latest-prompt.json"], redacted: true },
-    { id: "browser_proof_missing", category: "browser_proof_missing", severity: "info", userImpact: "No visual/browser proof of UI flows. Proof is CLI-output and artifact based.", releaseImpact: "Cannot demonstrate UI flows visually. Browser Proof is a separate future PR.", mitigation: "CLI outputs are compact and verifiable. Browser proof deferred intentionally.", owner: "avorelo", status: "accepted", evidenceRefs: [], redacted: true },
-    { id: "plugin_adapter_pending", category: "plugin_adapter_pending", severity: "info", userImpact: "Plugin/adapter marketplace not implemented. Only core CLI surface is available.", releaseImpact: "Users limited to built-in capabilities. Adapter readiness is a separate future PR.", mitigation: "Core capabilities cover the primary use case. Adapters are additive.", owner: "avorelo", status: "accepted", evidenceRefs: [], redacted: true },
-    { id: "mcp_config_preview_only", category: "mcp_config_preview_only", severity: "warn", userImpact: "MCP governance is preview-only — it inventories and risk-scores but does not auto-patch config.", releaseImpact: "Users must manually apply MCP config changes. No auto-patching without approval.", mitigation: "This is by design — MCP config changes require explicit user approval.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/mcp-tool-governance/latest-policy.json"], redacted: true },
-    { id: "hook_apply_requires_approval", category: "hook_apply_requires_approval", severity: "info", userImpact: "Hooks are not auto-applied. Users must run `avorelo hooks apply --yes` to install.", releaseImpact: "First-run users may not have hooks active until they explicitly approve.", mitigation: "AI install prompt includes hook setup step. Approval boundary is a safety feature.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/ai-install/latest-prompt.json"], redacted: true },
-    { id: "token_estimate_approximate", category: "token_estimate_approximate", severity: "info", userImpact: "Token savings are estimated from receipt data, not verified against provider billing.", releaseImpact: "Cannot make exact token savings claims in any launch material.", mitigation: "All token outputs include noExactSavingsClaim=true and caveats.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/orchestration/token-efficiency/latest-evidence.json"], redacted: true },
-    { id: "support_scope_local_only", category: "support_scope_local_only", severity: "info", userImpact: "Support bundle is local-only and redacted. No cloud support backend.", releaseImpact: "Support requires user to share bundle manually. No auto-submit to support system.", mitigation: "Bundle is redacted and safe to share. Manual sharing is explicit and controlled.", owner: "avorelo", status: "accepted", evidenceRefs: [".claude/cco/support/latest-support-bundle.json"], redacted: true },
-    { id: "external_project_coverage_unknown", category: "external_project_coverage_unknown", severity: "warn", userImpact: "Avorelo has been tested primarily on itself. Coverage on external projects is unknown.", releaseImpact: "External pre-launch users may encounter edge cases not covered by internal dogfood.", mitigation: "External user simulation covers common scenarios. Alpha users provide real coverage data.", owner: "avorelo", status: "accepted", evidenceRefs: [], redacted: true },
-  ];
-}
-
-function classifyLimitation(limitation, options) {
-  options = options || {};
-  if (limitation.severity === "blocker") return "blocks_candidate_ready";
-  if (limitation.severity === "warn") return "allows_candidate_warn";
-  return "info_only";
-}
-
-function buildKnownLimitations(cwd, signals, options) {
-  options = options || {};
-  var limitations = getBaselineLimitations();
-
-  var tci = signals && signals.tokenCostIntelligence;
-  if (tci && (tci.evidenceLevel === "not_available" || tci.status === "not_available")) {
-    var ec = limitations.find(function(l) { return l.id === "exact_cost_unavailable"; });
-    if (ec) ec.severity = "warn";
-  }
-  if (tci && (tci.realUsageSamplesCount || 0) > 0) {
-    var ec2 = limitations.find(function(l) { return l.id === "exact_cost_unavailable"; });
-    if (ec2) ec2.severity = "info";
-  }
-
-  var fi = signals && signals.feedbackIntelligence;
-  if (fi && (fi.qualifiedFeedbackItemsCount || 0) > 0) {
-    var fb = limitations.find(function(l) { return l.id === "feedback_insufficient"; });
-    if (fb) {
-      fb.severity = "info";
-      fb.status = "mitigated";
-      fb.releaseImpact = "Feedback evidence exists locally, but broader external coverage may still be limited.";
-    }
-  }
-
-  var classified = limitations.map(function(l) { return Object.assign({}, l, { classification: classifyLimitation(l) }); });
-  var blockerLimitations = classified.filter(function(l) { return l.severity === "blocker" && l.status !== "accepted"; });
-  var warnLimitations = classified.filter(function(l) { return l.severity === "warn"; });
-  var infoLimitations = classified.filter(function(l) { return l.severity === "info"; });
-  var overallImpact = blockerLimitations.length > 0 ? "blocks_candidate_ready" : warnLimitations.length > 0 ? "allows_candidate_warn" : "info_only";
-
-  var result = { contract: CONTRACT, schemaVersion: SCHEMA_VERSION, createdAt: nowIso(), totalLimitations: classified.length, blockerLimitationsCount: blockerLimitations.length, warnLimitationsCount: warnLimitations.length, infoLimitationsCount: infoLimitations.length, overallImpact: overallImpact, limitations: classified, redacted: true };
-  try { appendProductLearningEvent(cwd, { eventName: "known_limitations_built", category: "full_readiness", totalLimitations: classified.length, blockerCount: blockerLimitations.length, warnCount: warnLimitations.length }); } catch (e) {}
-  return result;
-}
-
-function writeKnownLimitations(cwd, limitations) {
-  var dir = path.join(cwd, LIMITATIONS_DIR_REL);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(limitations, null, 2));
-  return limitations;
-}
-
-function buildKnownLimitationsSurface(cwd, options) {
-  options = options || {};
-  var limitations = safeReadJson(path.join(cwd, ARTIFACT_REL));
-  if (!limitations) return { status: "not_available", totalLimitations: 0 };
-  return { totalLimitations: limitations.totalLimitations, blockerLimitationsCount: limitations.blockerLimitationsCount, warnLimitationsCount: limitations.warnLimitationsCount, overallImpact: limitations.overallImpact, limitations: limitations.limitations };
-}
-
-function formatKnownLimitationsText(limitations, options) {
-  options = options || {};
-  var lines = [];
-  lines.push("Known limitations: " + limitations.totalLimitations);
-  lines.push("Impact: " + limitations.overallImpact);
-  if (limitations.blockerLimitationsCount > 0) lines.push("Blockers: " + limitations.blockerLimitationsCount);
-  lines.push("");
-  limitations.limitations.forEach(function(l) {
-    lines.push("[" + l.severity + "] " + l.id);
-    lines.push("  Impact: " + l.userImpact);
-    lines.push("  Mitigation: " + l.mitigation);
-    lines.push("  Status: " + l.status);
-    lines.push("");
-  });
-  return lines.join("\n");
-}
-
-module.exports = { CONTRACT, SCHEMA_VERSION, ARTIFACT_REL, LIMITATION_CATEGORIES, buildKnownLimitations, classifyLimitation, writeKnownLimitations, buildKnownLimitationsSurface, formatKnownLimitationsText };

package/scripts/lib/l8-path-truth.js

@@ -1,146 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { readJson } from '../ws-aif-utils.js';
-
-export function normalizeRef(inputPath) {
-  return inputPath.split(path.sep).join('/');
-}
-
-export function readJsonOrNull(filePath) {
-  if (!filePath) return null;
-  return fs.existsSync(filePath) ? readJson(filePath) : null;
-}
-
-function findRepoRoot(startCwd) {
-  let cursor = path.resolve(startCwd);
-  while (true) {
-    const required = ['artifacts', 'scripts', 'tests'];
-    if (required.every((name) => fs.existsSync(path.join(cursor, name)))) return cursor;
-    const parent = path.dirname(cursor);
-    if (parent === cursor) return null;
-    cursor = parent;
-  }
-}
-
-function resolveRepoRoot(options = {}) {
-  if (options.repoRoot) return path.resolve(options.repoRoot);
-  const currentCwd = path.resolve(options.currentCwd || process.cwd());
-  return findRepoRoot(currentCwd);
-}
-
-function resolveArtifactRoot(baseRoot, overridePath, relativePath) {
-  if (!overridePath) return baseRoot ? path.join(baseRoot, relativePath) : null;
-  return path.isAbsolute(overridePath) ? overridePath : path.resolve(baseRoot || process.cwd(), overridePath);
-}
-
-function resolveOptionalFilePath(baseRoot, currentCwd, overridePath, defaultPath) {
-  if (overridePath) {
-    return path.isAbsolute(overridePath)
-      ? overridePath
-      : path.resolve(baseRoot || currentCwd, overridePath);
-  }
-  return defaultPath || null;
-}
-
-export function latestRunIdFromRoots(l4gRoot, l5bRoot) {
-  if (!l4gRoot || !l5bRoot) return null;
-
-  const repeatedUseProof = readJsonOrNull(path.join(l5bRoot, 'repeated-use-proof.v1.json'));
-  if (typeof repeatedUseProof?.latest_run_id === 'string' && repeatedUseProof.latest_run_id) {
-    return repeatedUseProof.latest_run_id;
-  }
-
-  const runtimeSurfaceState = readJsonOrNull(path.join(l5bRoot, 'runtime-surface-state.v1.json'));
-  if (typeof runtimeSurfaceState?.last_run_id === 'string' && runtimeSurfaceState.last_run_id) {
-    return runtimeSurfaceState.last_run_id;
-  }
-
-  const ledger = readJsonOrNull(path.join(l4gRoot, 'founder-dogfood-ledger.v1.json'));
-  if (typeof ledger?.last_updated_run === 'string' && ledger.last_updated_run) {
-    return ledger.last_updated_run;
-  }
-
-  const runsRoot = path.join(l4gRoot, 'runs');
-  if (!fs.existsSync(runsRoot)) return null;
-
-  const latest = fs.readdirSync(runsRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => {
-      const fullPath = path.join(runsRoot, entry.name);
-      return {
-        fullPath,
-        name: entry.name,
-        mtimeMs: fs.statSync(fullPath).mtimeMs,
-      };
-    })
-    .sort((left, right) => right.mtimeMs - left.mtimeMs)[0];
-
-  return latest?.name || null;
-}
-
-export function buildRunArtifactPaths(l4gRoot, runId) {
-  const runDir = l4gRoot && runId ? path.join(l4gRoot, 'runs', runId) : null;
-
-  return {
-    runDir,
-    runSummary: runDir ? path.join(runDir, 'run-summary.v1.json') : null,
-    runtimeLivePacket: runDir ? path.join(runDir, 'runtime-live-packet.v1.json') : null,
-    inWorkflowInteraction: runDir ? path.join(runDir, 'in-workflow-interaction.v1.json') : null,
-    heroLoopOutput: runDir ? path.join(runDir, 'hero-loop-output.v1.json') : null,
-    explainability: runDir ? path.join(runDir, 'customer-explainability.v1.json') : null,
-    valuePack: runDir ? path.join(runDir, 'user-visible-value-pack.v1.json') : null,
-    handoff: runDir ? path.join(runDir, 'handoff-outcome.v1.json') : null,
-    readiness: runDir ? path.join(runDir, 'readiness.v1.json') : null,
-    repeatedUseProof: runDir ? path.join(runDir, 'repeated-use-proof.v1.json') : null,
-  };
-}
-
-export function relativeRefIfExists(repoRoot, currentCwd, targetPath) {
-  if (!targetPath || !fs.existsSync(targetPath)) return null;
-  return normalizeRef(path.relative(repoRoot || currentCwd, targetPath));
-}
-
-export function resolveL8Context(options = {}) {
-  const currentCwd = path.resolve(options.currentCwd || process.cwd());
-  const repoRoot = resolveRepoRoot(options);
-  const repoRootFound = Boolean(repoRoot && fs.existsSync(repoRoot));
-  const resolutionBase = repoRoot || currentCwd;
-
-  const l4gRoot = resolveArtifactRoot(
-    resolutionBase,
-    options.l4gRoot,
-    path.join('artifacts', 'ws-aif', 'l4g-session'),
-  );
-  const l5bRoot = resolveArtifactRoot(
-    resolutionBase,
-    options.l5bRoot,
-    path.join('artifacts', 'ws-aif', 'l5b'),
-  );
-  const l8Root = resolveArtifactRoot(
-    resolutionBase,
-    options.l8Root,
-    path.join('artifacts', 'ws-aif', 'l8'),
-  );
-
-  const reconciliationPath = resolveOptionalFilePath(
-    resolutionBase,
-    currentCwd,
-    options.reconciliationPath,
-    l4gRoot ? path.join(l4gRoot, 'repo-reconciliation.v1.json') : null,
-  );
-  const latestRunId = options.runId || latestRunIdFromRoots(l4gRoot, l5bRoot);
-  const runPaths = buildRunArtifactPaths(l4gRoot, latestRunId);
-
-  return {
-    currentCwd,
-    repoRoot,
-    repoRootFound,
-    l4gRoot,
-    l5bRoot,
-    l8Root,
-    reconciliationPath,
-    latestRunId,
-    runPaths,
-  };
-}