avorelo 0.1.0

package/scripts/lib/alpha-feedback.js

@@ -0,0 +1,263 @@
+"use strict";
+
+// ── Alpha Feedback ────────────────────────────────────────────────────────────
+//
+// Contract: avorelo.alphaFeedback.v1
+//
+// Local-only feedback capture for dogfood and alpha users.
+// No PII, no raw customer data, no secrets. Summaries only.
+// Feeds company-loop and ledger.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const { redactPayload } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.alphaFeedback.v1";
+const SCHEMA_VERSION = 1;
+const FEEDBACK_DIR_REL = ".claude/cco/feedback";
+
+const VALID_SOURCES = new Set(["dogfood", "design_partner", "manual_customer", "session_review", "support_note"]);
+const VALID_PERSONAS = new Set(["developer", "pm", "security", "qa", "unknown"]);
+const VALID_FRICTION_TYPES = new Set([
+  "first_run_unclear",
+  "hook_apply_friction",
+  "output_too_noisy",
+  "output_too_sparse",
+  "command_not_found",
+  "proof_missing",
+  "value_unclear",
+  "safe_run_unclear",
+  "ledger_incomplete",
+  "doctor_confusing",
+  "support_bundle_missing",
+  "feedback_path_missing",
+  "other",
+]);
+const VALID_SEVERITIES = new Set(["low", "medium", "high", "blocker"]);
+const VALID_ACTIVATION_STAGES = new Set(["unknown", "first_run", "activation", "first_value", "repeat_use", "handoff", "support"]);
+const MAX_SUMMARY_LENGTH = 500;
+const MAX_DESIRED_BEHAVIOR_LENGTH = 500;
+const MAX_FIELD_LENGTH = 64;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeId() {
+  return `fb-${Date.now()}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function sanitizeText(text, maxLen) {
+  if (!text || typeof text !== "string") return "";
+  return text.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "").slice(0, maxLen).trim();
+}
+
+function redactFeedbackText(text) {
+  return text
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/\b[\w.-]+@[\w.-]+\.\w{2,}\b/g, "[redacted-email]")
+    .replace(/(password|secret|token|apikey|api_key)\s*[:=]\s*\S+/gi, "$1=[redacted]");
+}
+
+function sanitizeBool(value) {
+  return value === true;
+}
+
+function redactEvidencePath(value) {
+  if (!value) return null;
+  const payload = redactPayload({ filePath: String(value) });
+  return payload.filePath || "[redacted-path]";
+}
+
+function ensureFeedbackDir(cwd) {
+  const dirAbs = path.join(cwd, FEEDBACK_DIR_REL);
+  if (!fs.existsSync(dirAbs)) fs.mkdirSync(dirAbs, { recursive: true });
+  return dirAbs;
+}
+
+// ── Add feedback ──────────────────────────────────────────────────────────────
+
+function addFeedback(cwd, input = {}) {
+  const {
+    source = "dogfood",
+    persona = "unknown",
+    runId = null,
+    frictionType = "other",
+    severity = "medium",
+    summary = "",
+    desiredBehavior = "",
+    segment = "unknown",
+    theme = null,
+    issueCategory = null,
+    activationStage = "unknown",
+    trustConcern = false,
+    pricingConcern = false,
+    simulated = false,
+    evidencePath = null,
+  } = input;
+
+  // Validate
+  const errors = [];
+  if (!VALID_SOURCES.has(source)) errors.push(`source must be one of: ${[...VALID_SOURCES].join(", ")}`);
+  if (!VALID_PERSONAS.has(persona)) errors.push(`persona must be one of: ${[...VALID_PERSONAS].join(", ")}`);
+  if (!VALID_FRICTION_TYPES.has(frictionType)) errors.push(`frictionType must be one of: ${[...VALID_FRICTION_TYPES].join(", ")}`);
+  if (!VALID_SEVERITIES.has(severity)) errors.push(`severity must be one of: ${[...VALID_SEVERITIES].join(", ")}`);
+  if (!VALID_ACTIVATION_STAGES.has(activationStage)) errors.push(`activationStage must be one of: ${[...VALID_ACTIVATION_STAGES].join(", ")}`);
+  if (!summary || summary.trim().length === 0) errors.push("summary is required");
+  if (errors.length > 0) return { ok: false, errors };
+
+  // Sanitize and redact
+  const cleanSummary = redactFeedbackText(sanitizeText(summary, MAX_SUMMARY_LENGTH));
+  const cleanDesiredBehavior = desiredBehavior
+    ? redactFeedbackText(sanitizeText(desiredBehavior, MAX_DESIRED_BEHAVIOR_LENGTH))
+    : "";
+
+  const feedback = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    id: makeId(),
+    source,
+    persona,
+    runId: runId ? String(runId).slice(0, 64) : null,
+    frictionType,
+    severity,
+    segment: sanitizeText(segment, MAX_FIELD_LENGTH) || "unknown",
+    theme: sanitizeText(theme || frictionType, MAX_FIELD_LENGTH) || frictionType,
+    issueCategory: sanitizeText(issueCategory || theme || frictionType || "other", MAX_FIELD_LENGTH) || "other",
+    activationStage,
+    trustConcern: sanitizeBool(trustConcern),
+    pricingConcern: sanitizeBool(pricingConcern),
+    simulated: sanitizeBool(simulated),
+    summary: cleanSummary,
+    desiredBehavior: cleanDesiredBehavior,
+    evidencePath: redactEvidencePath(evidencePath),
+    createdAt: nowIso(),
+    redacted: true,
+  };
+
+  try {
+    ensureCcoDirs(cwd);
+    const dirAbs = ensureFeedbackDir(cwd);
+    const filePath = path.join(dirAbs, `${feedback.id}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(feedback, null, 2), "utf8");
+
+    appendProductLearningEvent(cwd, {
+      eventName: "alpha_feedback_added",
+      source,
+      persona,
+      frictionType,
+      severity,
+    });
+
+    return { ok: true, feedback, path: `${FEEDBACK_DIR_REL}/${feedback.id}.json` };
+  } catch (err) {
+    return { ok: false, errors: [`Failed to write feedback: ${err.message}`] };
+  }
+}
+
+// ── List feedback ─────────────────────────────────────────────────────────────
+
+function listFeedback(cwd, options = {}) {
+  const { source = null, limit = 50 } = options;
+  const dirAbs = path.join(cwd, FEEDBACK_DIR_REL);
+
+  if (!fs.existsSync(dirAbs)) {
+    return { contract: CONTRACT, schemaVersion: SCHEMA_VERSION, items: [], total: 0, redacted: true };
+  }
+
+  let files;
+  try {
+    files = fs.readdirSync(dirAbs).filter((f) => f.endsWith(".json")).sort().reverse();
+  } catch {
+    return { contract: CONTRACT, schemaVersion: SCHEMA_VERSION, items: [], total: 0, error: "Cannot read feedback directory", redacted: true };
+  }
+
+  const items = [];
+  for (const file of files) {
+    if (items.length >= limit) break;
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(dirAbs, file), "utf8"));
+      if (source && data.source !== source) continue;
+      items.push(data);
+    } catch {}
+  }
+
+  // Summary counts
+  const bySource = {};
+  const bySeverity = {};
+  for (const item of items) {
+    bySource[item.source] = (bySource[item.source] || 0) + 1;
+    bySeverity[item.severity] = (bySeverity[item.severity] || 0) + 1;
+  }
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    total: files.length,
+    showing: items.length,
+    bySource,
+    bySeverity,
+    items,
+    feedbackDir: FEEDBACK_DIR_REL,
+    redacted: true,
+  };
+}
+
+// ── Read feedback summary for ledger/company-loop ─────────────────────────────
+
+function readFeedbackSummary(cwd) {
+  const list = listFeedback(cwd, { limit: 200 });
+  if (list.total === 0) return null;
+
+  const topFriction = {};
+  for (const item of list.items) {
+    topFriction[item.frictionType] = (topFriction[item.frictionType] || 0) + 1;
+  }
+  const topFrictionType = Object.entries(topFriction).sort((a, b) => b[1] - a[1])[0];
+
+  return {
+    total: list.total,
+    bySource: list.bySource,
+    bySeverity: list.bySeverity,
+    topFrictionType: topFrictionType ? topFrictionType[0] : null,
+    topFrictionCount: topFrictionType ? topFrictionType[1] : 0,
+    feedbackDir: FEEDBACK_DIR_REL,
+  };
+}
+
+// ── Format text ───────────────────────────────────────────────────────────────
+
+function formatFeedbackListText(list) {
+  const lines = [];
+  lines.push(`Alpha Feedback (${list.total} total, showing ${list.showing})`);
+  if (list.total === 0) {
+    lines.push("  No feedback captured yet.");
+    lines.push("  Run: avorelo feedback add --source dogfood --summary \"...\"");
+    return lines.join("\n");
+  }
+  lines.push(`  Sources: ${JSON.stringify(list.bySource)}`);
+  lines.push(`  Severity: ${JSON.stringify(list.bySeverity)}`);
+  lines.push("");
+  list.items.slice(0, 10).forEach((item) => {
+    lines.push(`  [${item.severity}] ${item.frictionType} (${item.source}): ${item.summary}`);
+  });
+  if (list.total > 10) lines.push(`  ... and ${list.total - 10} more.`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  FEEDBACK_DIR_REL,
+  VALID_SOURCES,
+  VALID_PERSONAS,
+  VALID_FRICTION_TYPES,
+  VALID_SEVERITIES,
+  addFeedback,
+  listFeedback,
+  readFeedbackSummary,
+  formatFeedbackListText,
+};

package/scripts/lib/alpha-readiness-gate.js

@@ -0,0 +1,332 @@
+"use strict";
+
+// ── Alpha Readiness Gate ──────────────────────────────────────────────────────
+//
+// Contract: avorelo.alphaReadinessGate.v1
+//
+// Deterministic gate that checks whether Avorelo is ready for alpha use.
+// This is NOT public launch readiness — it is alpha-readiness only.
+//
+// Checks pass/warn/fail against existing artifacts. Does not modify any files.
+
+const fs = require("fs");
+const path = require("path");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.alphaReadinessGate.v1";
+const SCHEMA_VERSION = 1;
+const GATE_REL = ".claude/cco/orchestration/alpha-readiness/latest-gate.json";
+const GATE_DIR_REL = ".claude/cco/orchestration/alpha-readiness";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function moduleExists(cwd, rel) {
+  return fs.existsSync(path.join(cwd, rel));
+}
+
+function artifactExists(cwd, rel) {
+  return fs.existsSync(path.join(cwd, rel));
+}
+
+function checkPass(id, summary) { return { id, status: "pass", summary }; }
+function checkWarn(id, summary, nextAction) { return { id, status: "warn", summary, nextAction: nextAction || null }; }
+function checkFail(id, summary, nextAction) { return { id, status: "fail", summary, nextAction: nextAction || null }; }
+
+// ── Individual checks ─────────────────────────────────────────────────────────
+
+function checkInstallOrRepoEntry(cwd) {
+  const hasBin = fs.existsSync(path.join(cwd, "bin", "avorelo"));
+  const hasPkg = fs.existsSync(path.join(cwd, "package.json"));
+  if (!hasBin) return checkFail("install_or_repo_entry_clear", "bin/avorelo not found.", "Run: npm install");
+  if (!hasPkg) return checkWarn("install_or_repo_entry_clear", "package.json not found.", "Check repo root.");
+  return checkPass("install_or_repo_entry_clear", "Repo entry clear — bin/avorelo and package.json present.");
+}
+
+function checkProjectProfileAvailable(cwd) {
+  const modPath = path.join(cwd, "scripts/lib/project-profile.js");
+  if (!moduleExists(cwd, "scripts/lib/project-profile.js")) {
+    return checkFail("project_profile_available", "project-profile.js not found.");
+  }
+  return checkPass("project_profile_available", "Project profile module available.");
+}
+
+function checkSafeRunAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/safe-run-controller.js")) {
+    return checkFail("safe_run_available", "safe-run-controller.js not found.");
+  }
+  return checkPass("safe_run_available", "Safe run controller available.");
+}
+
+function checkSmartRouteAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/smart-work-routing.js")) {
+    return checkFail("smart_route_available", "smart-work-routing.js not found.");
+  }
+  return checkPass("smart_route_available", "Smart work routing available.");
+}
+
+function checkExecutionPacketAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/execution-packet.js")) {
+    return checkFail("execution_packet_available", "execution-packet.js not found.");
+  }
+  return checkPass("execution_packet_available", "Execution packet available.");
+}
+
+function checkHookPreviewAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/hook-config-preview.js")) {
+    return checkFail("hook_preview_available", "hook-config-preview.js not found.");
+  }
+  return checkPass("hook_preview_available", "Hook config preview available.");
+}
+
+function checkHookApplyStatusKnown(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/hook-apply.js")) {
+    return checkFail("hook_apply_status_known", "hook-apply.js not found.");
+  }
+  const applyArtifact = safeReadJson(path.join(cwd, ".claude/cco/orchestration/hook-apply/latest-apply.json"));
+  if (!applyArtifact) {
+    return checkWarn("hook_apply_status_known", "Hook apply status unknown — no apply artifact yet.", "Run: avorelo hooks --json");
+  }
+  return checkPass("hook_apply_status_known", `Hook apply status known (applied: ${applyArtifact.hooksApplied || false}).`);
+}
+
+function checkHookDoctorPassOrClear(cwd) {
+  const doctorArtifact = safeReadJson(path.join(cwd, ".claude/cco/orchestration/hook-apply/latest-doctor.json"));
+  if (!doctorArtifact) {
+    return checkWarn("hook_doctor_pass_or_clear_next_action", "No hook doctor artifact. Run `avorelo hooks doctor` to check.", "Run: avorelo hooks doctor --json");
+  }
+  const failCount = doctorArtifact.summary?.fail || 0;
+  if (failCount > 0) {
+    return checkWarn("hook_doctor_pass_or_clear_next_action", `Hook doctor has ${failCount} failure(s).`, doctorArtifact.nextAction || "Run: avorelo hooks doctor --json");
+  }
+  return checkPass("hook_doctor_pass_or_clear_next_action", "Hook doctor pass or clear next action.");
+}
+
+function checkProofAvailableOrClear(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/seamless-reality-gate.js")) {
+    return checkFail("proof_available_or_clear_next_action", "seamless-reality-gate.js not found.");
+  }
+  const proofArtifact = safeReadJson(path.join(cwd, ".claude/cco/orchestration/seamless-outcome/latest-reality-gate.json"));
+  if (!proofArtifact) {
+    return checkWarn("proof_available_or_clear_next_action", "No proof artifact. Run `avorelo proof` to generate.", "Run: avorelo proof");
+  }
+  return checkPass("proof_available_or_clear_next_action", "Proof artifact available.");
+}
+
+function checkLedgerAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/work-ledger.js")) {
+    return checkFail("ledger_available", "work-ledger.js not found.");
+  }
+  return checkPass("ledger_available", "Work ledger available.");
+}
+
+function checkOutcomeAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/seamless-outcome.js")) {
+    return checkFail("outcome_available", "seamless-outcome.js not found.");
+  }
+  return checkPass("outcome_available", "Seamless outcome available.");
+}
+
+function checkCompanyLoopAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/company-loop.js")) {
+    return checkFail("company_loop_available", "company-loop.js not found.");
+  }
+  return checkPass("company_loop_available", "Company loop available.");
+}
+
+function checkFeedbackCaptureAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/alpha-feedback.js")) {
+    return checkWarn("feedback_capture_available", "alpha-feedback.js not found.", "Build alpha-feedback.js");
+  }
+  return checkPass("feedback_capture_available", "Feedback capture available (local only).");
+}
+
+function checkSupportBundleAvailable(cwd) {
+  if (!moduleExists(cwd, "scripts/lib/support-bundle.js")) {
+    return checkWarn("support_bundle_available", "support-bundle.js not found.", "Build support-bundle.js");
+  }
+  return checkPass("support_bundle_available", "Support bundle available (redacted).");
+}
+
+function checkDefaultOutputCompact(cwd) {
+  // Check that proof command output is within size bounds (32KB limit from reality gate)
+  const proofArtifact = safeReadJson(path.join(cwd, ".claude/cco/orchestration/seamless-outcome/latest-reality-gate.json"));
+  if (!proofArtifact) {
+    return checkWarn("default_output_compact", "Cannot verify compact output — no proof artifact.", "Run: avorelo proof");
+  }
+  // Check activation receipt size if present
+  const activationArtifact = safeReadJson(path.join(cwd, ".claude/cco/orchestration/activation/latest-activation.json"));
+  if (activationArtifact) {
+    const bytes = Buffer.byteLength(JSON.stringify(activationArtifact));
+    if (bytes > 32 * 1024) {
+      return checkWarn("default_output_compact", `Activation receipt is large (${bytes} bytes). Default output should be compact.`);
+    }
+  }
+  return checkPass("default_output_compact", "Default output appears compact.");
+}
+
+function checkTokenEfficiencyHardeningPresent(cwd) {
+  const hasModule = moduleExists(cwd, "scripts/lib/token-efficiency-evidence.js");
+  if (!hasModule) {
+    return checkWarn("token_efficiency_hardening_present", "token-efficiency-evidence.js not found. Token efficiency hardening is recommended for alpha.", "Add token-efficiency-evidence.js");
+  }
+  const hasSandbox = moduleExists(cwd, "scripts/lib/tool-output-sandbox.js");
+  const hasRepoMap = moduleExists(cwd, "scripts/lib/repo-map.js");
+  const hasQualityGate = moduleExists(cwd, "scripts/lib/token-context-quality-gate.js");
+  if (!hasSandbox || !hasRepoMap || !hasQualityGate) {
+    const missing = [!hasSandbox && "tool-output-sandbox", !hasRepoMap && "repo-map", !hasQualityGate && "token-context-quality-gate"].filter(Boolean);
+    return checkWarn("token_efficiency_hardening_present", `Token efficiency hardening partial. Missing: ${missing.join(", ")}.`, "Add missing token efficiency modules.");
+  }
+  return checkPass("token_efficiency_hardening_present", "Token efficiency hardening modules present.");
+}
+
+function checkNoLaunchClaimBeforeGate(cwd) {
+  // Check docs and README for premature launch claims
+  const filesToCheck = [
+    "README.md",
+    "docs/Avorelo-Operating-Layer.md",
+  ];
+  const launchPhrases = [
+    "production ready",
+    "launch ready",
+    "publicly available",
+    "GA release",
+    "generally available",
+  ];
+  for (const rel of filesToCheck) {
+    const absPath = path.join(cwd, rel);
+    if (!fs.existsSync(absPath)) continue;
+    const content = fs.readFileSync(absPath, "utf8").toLowerCase();
+    for (const phrase of launchPhrases) {
+      if (content.includes(phrase)) {
+        return checkWarn("no_launch_claim_before_gate", `"${phrase}" found in ${rel}. Alpha-readiness is not public launch.`);
+      }
+    }
+  }
+  return checkPass("no_launch_claim_before_gate", "No premature launch claims found.");
+}
+
+// ── Build gate ────────────────────────────────────────────────────────────────
+
+function buildAlphaReadinessGate(cwd, options = {}) {
+  const checks = [
+    checkInstallOrRepoEntry(cwd),
+    checkProjectProfileAvailable(cwd),
+    checkSafeRunAvailable(cwd),
+    checkSmartRouteAvailable(cwd),
+    checkExecutionPacketAvailable(cwd),
+    checkHookPreviewAvailable(cwd),
+    checkHookApplyStatusKnown(cwd),
+    checkHookDoctorPassOrClear(cwd),
+    checkProofAvailableOrClear(cwd),
+    checkLedgerAvailable(cwd),
+    checkOutcomeAvailable(cwd),
+    checkCompanyLoopAvailable(cwd),
+    checkFeedbackCaptureAvailable(cwd),
+    checkSupportBundleAvailable(cwd),
+    checkDefaultOutputCompact(cwd),
+    checkNoLaunchClaimBeforeGate(cwd),
+    checkTokenEfficiencyHardeningPresent(cwd),
+  ];
+
+  const failCount = checks.filter((c) => c.status === "fail").length;
+  const warnCount = checks.filter((c) => c.status === "warn").length;
+  const passCount = checks.filter((c) => c.status === "pass").length;
+
+  let gateStatus;
+  if (failCount > 0) gateStatus = "fail";
+  else if (warnCount > 0) gateStatus = "warn";
+  else gateStatus = "pass";
+
+  const score = Math.round((passCount / checks.length) * 100);
+
+  const report = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: gateStatus,
+    score,
+    summary: { pass: passCount, warn: warnCount, fail: failCount },
+    checks,
+    note: "Alpha-readiness is not public launch readiness. This gate confirms Avorelo foundations are in place for internal testing.",
+    redacted: true,
+  };
+
+  return report;
+}
+
+// ── Write gate artifact ───────────────────────────────────────────────────────
+
+function writeAlphaReadinessGate(cwd, report) {
+  try {
+    ensureCcoDirs(cwd);
+    const dirAbs = path.join(cwd, GATE_DIR_REL);
+    if (!fs.existsSync(dirAbs)) fs.mkdirSync(dirAbs, { recursive: true });
+    const gateAbs = path.join(cwd, GATE_REL);
+    fs.writeFileSync(gateAbs, JSON.stringify(report, null, 2), "utf8");
+    return gateAbs;
+  } catch {
+    return null;
+  }
+}
+
+// ── Run gate ──────────────────────────────────────────────────────────────────
+
+function runAlphaReadinessGate(cwd, options = {}) {
+  const report = buildAlphaReadinessGate(cwd, options);
+  const written = writeAlphaReadinessGate(cwd, report);
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "alpha_readiness_gate_run",
+      status: report.status,
+      score: report.score,
+      passCount: report.summary.pass,
+      warnCount: report.summary.warn,
+      failCount: report.summary.fail,
+    });
+  } catch {}
+
+  return { ...report, artifactPath: written ? GATE_REL : null };
+}
+
+// ── Format text ───────────────────────────────────────────────────────────────
+
+function formatAlphaReadinessGateText(report, options = {}) {
+  const lines = [];
+  lines.push(`Alpha Readiness Gate: ${report.status} (score: ${report.score}/100)`);
+  lines.push(`  pass: ${report.summary.pass}  warn: ${report.summary.warn}  fail: ${report.summary.fail}`);
+  lines.push("");
+  lines.push("Note: Alpha-readiness is NOT public launch readiness.");
+  if (report.checks) {
+    const issues = report.checks.filter((c) => c.status !== "pass");
+    if (issues.length > 0) {
+      lines.push("");
+      lines.push("Issues:");
+      issues.forEach((c) => {
+        lines.push(`  [${c.status}] ${c.id}: ${c.summary}`);
+        if (c.nextAction) lines.push(`         → ${c.nextAction}`);
+      });
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  GATE_REL,
+  buildAlphaReadinessGate,
+  writeAlphaReadinessGate,
+  runAlphaReadinessGate,
+  formatAlphaReadinessGateText,
+};