avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/canonical-reentry.js

@@ -0,0 +1,162 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { buildBoundedStateContext, formatNextBoundedAction } = require("./proof-canonical");
+const { loadCarryForward } = require("./carry-forward-surfacing");
+const { parseContinueNote } = require("./guidance-builder");
+const { loadReentryState } = require("./reentry-state");
+
+const CONTINUE_NOTE_REL = ".claude/cco/reports/continue-from-here.md";
+const REENTRY_STATE_REL = ".claude/cco/state/reentry-state.json";
+const CARRY_FORWARD_REL = ".claude/cco/state/reentry-carry-forward.json";
+
+function loadCanonicalReentry(cwd) {
+  const context = buildBoundedStateContext(cwd);
+  if (!context) {
+    return {
+      is_canonical_truth_available: false,
+      artifact_refs: [],
+      state_source: null,
+    };
+  }
+
+  return {
+    is_canonical_truth_available: true,
+    artifact_refs: Array.isArray(context.artifact_refs) ? context.artifact_refs : [],
+    state_source: context.state_source || context.artifact_path || null,
+    where_am_i_now: context.where_am_i_now || null,
+    what_can_i_honestly_claim: context.what_can_i_honestly_claim || context.claim_boundary || null,
+    reentry_status: context.reentry_status || null,
+    latest_trustworthy_run_id: context.latest_trustworthy_run_id || null,
+    latest_trustworthy_workset_id: context.latest_trustworthy_workset_id || null,
+    next_bounded_action: context.next_bounded_action || null,
+    next_bounded_action_text: formatNextBoundedAction(context.next_bounded_action),
+    rollback_available:
+      typeof context.rollback_available === "boolean" ? context.rollback_available : null,
+    rollback_trigger: context.rollback_trigger || null,
+    readiness_state: context.readiness_status || null,
+    reason_summary: context.reentry_reason_summary || null,
+  };
+}
+
+function hasCanonicalReentryTruth(value) {
+  return Boolean(value && value.is_canonical_truth_available);
+}
+
+function readContinueNote(cwd) {
+  const absPath = path.join(cwd, CONTINUE_NOTE_REL);
+  try {
+    return parseContinueNote(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function uniqueRefs(values) {
+  return [...new Set((values || []).filter(Boolean).map((value) => String(value).trim()).filter(Boolean))];
+}
+
+function buildFallbackCurrentState(cwd) {
+  const continueNote = readContinueNote(cwd);
+  const reentryState = loadReentryState(cwd);
+  const carryForward = loadCarryForward(cwd);
+  const carryForwardNext =
+    formatNextBoundedAction(carryForward?.nextBoundedAction)
+    || formatNextBoundedAction(carryForward?.next_bounded_action);
+  const nextAction =
+    continueNote?.nextAction
+    || reentryState?.nextAction
+    || carryForwardNext
+    || null;
+  const artifactRefs = uniqueRefs([
+    continueNote ? CONTINUE_NOTE_REL : null,
+    reentryState ? REENTRY_STATE_REL : null,
+    carryForward ? CARRY_FORWARD_REL : null,
+    continueNote?.artifactPath || null,
+    reentryState?.primaryArtifactPath || null,
+  ]);
+
+  if (!continueNote && !reentryState && !carryForward) {
+    return {
+      truthSource: "none",
+      isCanonicalTruthAvailable: false,
+      whereAmINow: null,
+      whatCanIHonestlyClaim: null,
+      nextBoundedAction: null,
+      reentryStatus: null,
+      latestTrustworthyRunId: null,
+      rollbackAvailable: null,
+      readinessState: null,
+      stateSource: null,
+      artifactRefs: [],
+      limitations: [
+        "No canonical or wrapper continuity cues are available yet.",
+      ],
+    };
+  }
+
+  return {
+    truthSource: "fallback",
+    isCanonicalTruthAvailable: false,
+    whereAmINow: null,
+    whatCanIHonestlyClaim: null,
+    nextBoundedAction: nextAction,
+    reentryStatus: carryForward ? "resume_available" : null,
+    latestTrustworthyRunId: null,
+    rollbackAvailable: null,
+    readinessState: null,
+    stateSource:
+      continueNote ? CONTINUE_NOTE_REL
+        : reentryState ? REENTRY_STATE_REL
+          : carryForward ? CARRY_FORWARD_REL
+            : null,
+    artifactRefs,
+    limitations: [
+      "Canonical L8 current-state artifacts are not available; showing wrapper-derived continuity cues.",
+    ],
+  };
+}
+
+function buildCurrentStateSurface(cwd) {
+  const canonicalReentry = loadCanonicalReentry(cwd);
+  if (hasCanonicalReentryTruth(canonicalReentry)) {
+    const limitations = [];
+    if (!canonicalReentry.where_am_i_now) {
+      limitations.push("Canonical L8 artifacts do not currently describe where the session stands.");
+    }
+    if (!canonicalReentry.what_can_i_honestly_claim) {
+      limitations.push("Canonical L8 artifacts do not currently define an honest claim boundary.");
+    }
+    if (!canonicalReentry.next_bounded_action_text) {
+      limitations.push("Canonical L8 artifacts do not currently define the next bounded action.");
+    }
+
+    return {
+      truthSource: "canonical_l8",
+      isCanonicalTruthAvailable: true,
+      whereAmINow: canonicalReentry.where_am_i_now || null,
+      whatCanIHonestlyClaim: canonicalReentry.what_can_i_honestly_claim || null,
+      nextBoundedAction: canonicalReentry.next_bounded_action_text || null,
+      reentryStatus: canonicalReentry.reentry_status || null,
+      latestTrustworthyRunId: canonicalReentry.latest_trustworthy_run_id || null,
+      rollbackAvailable:
+        typeof canonicalReentry.rollback_available === "boolean"
+          ? canonicalReentry.rollback_available
+          : null,
+      readinessState: canonicalReentry.readiness_state || null,
+      stateSource: canonicalReentry.state_source || null,
+      artifactRefs: uniqueRefs(canonicalReentry.artifact_refs || []),
+      limitations,
+    };
+  }
+
+  return buildFallbackCurrentState(cwd);
+}
+
+module.exports = {
+  buildCurrentStateSurface,
+  hasCanonicalReentryTruth,
+  loadCanonicalReentry,
+};

package/scripts/lib/capability-contract-validator.js

@@ -0,0 +1,177 @@
+"use strict";
+
+/**
+ * Capability Contract Validator — avorelo.capabilityContractValidator.v1
+ *
+ * Validates each capability manifest against the v1 operating contract.
+ * Produces per-capability compliance results and an aggregate summary.
+ * This is audit-first: it does not modify capabilities, only reports.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const { validateManifest, checkClaimSafety, SCHEMA_VERSION } = require("./capability-manifest");
+
+const COMPLIANCE_READY = "ready";
+const COMPLIANCE_PARTIAL = "partial";
+const COMPLIANCE_NEEDS_ATTENTION = "needs_attention";
+
+/**
+ * Validate a single capability manifest and check file-system evidence.
+ * @param {object} manifest - The capability manifest
+ * @param {string} cwd - Repository root for file existence checks
+ * @returns {{ id, name, compliance, errors, warnings, missingFiles, claimSafetyIssues }}
+ */
+function validateCapabilityContract(manifest, cwd) {
+  const result = {
+    id: manifest.id || "(unknown)",
+    name: manifest.name || "(unknown)",
+    compliance: COMPLIANCE_READY,
+    errors: [],
+    warnings: [],
+    missingFiles: [],
+    claimSafetyIssues: [],
+    hasManifest: true,
+    hasTests: false,
+    hasDocs: false,
+    hasDogfood: false,
+    hasPolicyGate: false,
+    hasRollback: false,
+    hasBudgets: false,
+    hasEvidenceRequirements: false,
+  };
+
+  // 1. Schema validation
+  const schemaResult = validateManifest(manifest);
+  result.errors.push(...schemaResult.errors);
+  result.warnings.push(...schemaResult.warnings);
+
+  // 2. Check test files exist
+  if (manifest.tests && manifest.tests.length > 0) {
+    result.hasTests = true;
+    for (const testFile of manifest.tests) {
+      const fullPath = path.resolve(cwd, testFile);
+      if (!fs.existsSync(fullPath)) {
+        result.missingFiles.push(testFile);
+        result.warnings.push(`test file not found: ${testFile}`);
+      }
+    }
+  }
+
+  // 3. Check doc files exist
+  if (manifest.docs && manifest.docs.length > 0) {
+    result.hasDocs = true;
+    for (const docFile of manifest.docs) {
+      const fullPath = path.resolve(cwd, docFile);
+      if (!fs.existsSync(fullPath)) {
+        result.missingFiles.push(docFile);
+        result.warnings.push(`doc file not found: ${docFile}`);
+      }
+    }
+  }
+
+  // 4. Check dogfood artifact
+  if (manifest.dogfood && manifest.dogfood.artifactPath) {
+    const dogfoodPath = path.resolve(cwd, manifest.dogfood.artifactPath);
+    if (fs.existsSync(dogfoodPath)) {
+      result.hasDogfood = true;
+    } else {
+      result.missingFiles.push(manifest.dogfood.artifactPath);
+      result.warnings.push(`dogfood artifact not found: ${manifest.dogfood.artifactPath}`);
+    }
+  } else if (manifest.dogfood && manifest.dogfood.required) {
+    result.warnings.push("dogfood is required but no artifactPath is defined");
+  }
+
+  // 5. Policy gate
+  if (manifest.policy && manifest.policy.defaultDecision) {
+    result.hasPolicyGate = true;
+  }
+
+  // 6. Rollback behavior
+  if (manifest.rollback && manifest.rollback.failBehavior) {
+    result.hasRollback = true;
+  }
+
+  // 7. Budgets
+  if (manifest.budgets && typeof manifest.budgets === "object" && Object.keys(manifest.budgets).length > 0) {
+    result.hasBudgets = true;
+  }
+
+  // 8. Evidence requirements
+  if (manifest.evidenceRequirements && typeof manifest.evidenceRequirements === "object") {
+    result.hasEvidenceRequirements = true;
+  }
+
+  // 9. Claim safety: scan name and any text fields
+  const textsToCheck = [manifest.name, manifest.id, ...(manifest.allowedActions || [])];
+  for (const text of textsToCheck) {
+    const violations = checkClaimSafety(text);
+    if (violations.length > 0) {
+      result.claimSafetyIssues.push({ field: "manifest", text, violations });
+    }
+  }
+
+  // Determine compliance
+  if (result.errors.length > 0) {
+    result.compliance = COMPLIANCE_NEEDS_ATTENTION;
+  } else if (result.warnings.length > 3 || result.claimSafetyIssues.length > 0) {
+    result.compliance = COMPLIANCE_PARTIAL;
+  } else if (result.warnings.length > 0) {
+    result.compliance = COMPLIANCE_PARTIAL;
+  }
+
+  // Override: if has tests + docs + policy + rollback + no errors → ready even with minor warnings
+  if (
+    result.errors.length === 0 &&
+    result.hasTests &&
+    result.hasPolicyGate &&
+    result.hasRollback &&
+    result.claimSafetyIssues.length === 0 &&
+    result.warnings.length <= 2
+  ) {
+    result.compliance = COMPLIANCE_READY;
+  }
+
+  return result;
+}
+
+/**
+ * Validate all capabilities in a registry.
+ * @param {object[]} capabilities - Array of capability manifests
+ * @param {string} cwd - Repository root
+ * @returns {{ results, summary }}
+ */
+function validateAllContracts(capabilities, cwd) {
+  const results = capabilities.map((c) => validateCapabilityContract(c, cwd));
+
+  const summary = {
+    capabilitiesFound: results.length,
+    fullyCompliant: results.filter((r) => r.compliance === COMPLIANCE_READY).length,
+    partiallyCompliant: results.filter((r) => r.compliance === COMPLIANCE_PARTIAL).length,
+    needsAttention: results.filter((r) => r.compliance === COMPLIANCE_NEEDS_ATTENTION).length,
+    missingManifest: 0, // All have manifests in registry
+    missingProof: results.filter((r) => !r.hasEvidenceRequirements).length,
+    missingPolicyGate: results.filter((r) => !r.hasPolicyGate).length,
+    missingTests: results.filter((r) => !r.hasTests).length,
+    missingDocs: results.filter((r) => !r.hasDocs).length,
+    missingDogfood: results.filter((r) => !r.hasDogfood).length,
+    missingRollback: results.filter((r) => !r.hasRollback).length,
+    missingBudgets: results.filter((r) => !r.hasBudgets).length,
+    unsafeClaims: results.filter((r) => r.claimSafetyIssues.length > 0).length,
+    duplicateSurfaces: 0, // Checked separately
+    totalErrors: results.reduce((sum, r) => sum + r.errors.length, 0),
+    totalWarnings: results.reduce((sum, r) => sum + r.warnings.length, 0),
+  };
+
+  return { results, summary };
+}
+
+module.exports = {
+  COMPLIANCE_READY,
+  COMPLIANCE_PARTIAL,
+  COMPLIANCE_NEEDS_ATTENTION,
+  validateCapabilityContract,
+  validateAllContracts,
+};