@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/helper-orchestration-core.js

@@ -0,0 +1,307 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const helperOrchestrationSchemaVersion = "0.1.0";
+export const helperSkillNames = ["$align", "$diagnose", "$tdd", "$cleanup"];
+
+const helperContracts = [
+  {
+    skill: "$align",
+    semantic_role: "scope_alignment",
+    activates_when: [
+      "ambiguous_scope",
+      "terminology_drift",
+      "lane_handoff_needs_shared_language",
+      "docs_or_prompt_contract_needs_tightening",
+    ],
+    outputs: [
+      "current_ambiguity_or_mismatch",
+      "normalized_terminology",
+      "scope_boundary_and_exclusions",
+      "acceptance_checks_or_rewritten_prompts",
+      "exact_next_trigger",
+    ],
+    supports: ["$maestro", "$arch", "$sage", "$flow", "$vet", "$vibe", "$build"],
+    records_as: "helper_alignment_receipt",
+  },
+  {
+    skill: "$diagnose",
+    semantic_role: "blocked_lane_diagnosis",
+    activates_when: [
+      "lane_blocked",
+      "vague_symptom",
+      "runtime_artifact_invalid",
+      "missing_evidence_or_reproduction_boundary",
+    ],
+    outputs: [
+      "observed_symptom",
+      "likely_failure_slices",
+      "missing_evidence_or_repro_steps",
+      "smallest_next_probe",
+      "exact_next_trigger",
+    ],
+    supports: ["$maestro", "$flow", "$vet", "$build", "verifier_roles", "debugger_roles"],
+    records_as: "helper_diagnosis_receipt",
+  },
+  {
+    skill: "$tdd",
+    semantic_role: "regression_first_boundary",
+    activates_when: [
+      "implementation_expanding",
+      "cleanup_requires_behavior_lock",
+      "bounded_build_slice_needs_test_shape",
+      "regression_risk_before_refactor",
+    ],
+    outputs: [
+      "behavior_to_lock",
+      "minimal_regression_or_failing_test_shape",
+      "implementation_boundary",
+      "proof_test_belongs_to_change",
+      "exact_next_trigger",
+    ],
+    supports: ["$maestro", "$build", "executor_roles", "test_engineer_roles", "$cleanup"],
+    records_as: "helper_tdd_receipt",
+  },
+  {
+    skill: "$cleanup",
+    semantic_role: "contract_preserving_simplification",
+    activates_when: [
+      "artifact_is_noisy_after_decision",
+      "anti_slop_pass_needed",
+      "docs_need_product_native_wording",
+      "code_or_plan_can_be_simplified_without_behavior_change",
+    ],
+    outputs: [
+      "removable_complexity_or_noisy_wording",
+      "behavior_preserving_simplifications",
+      "residual_risks_after_cleanup",
+      "exact_next_trigger",
+    ],
+    supports: ["$maestro", "$arch", "$sage", "$flow", "$vet", "$vibe", "$build", "writer_roles"],
+    records_as: "helper_cleanup_receipt",
+  },
+];
+
+export function getHelperOrchestrationCorePath() {
+  return getRuntimeSubsystemPath("context", "helper-orchestration-core.json");
+}
+
+export function createDefaultHelperOrchestrationCore() {
+  return {
+    schemaVersion: helperOrchestrationSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Defines how $align, $diagnose, $tdd, and $cleanup work together as core non-gating helper capabilities across MA lanes, roles, workers, and exported host payloads.",
+    helper_contracts: helperContracts,
+    composition_rules: {
+      non_gating: true,
+      release_state_mutation_allowed: false,
+      may_create_parallel_release_gate: false,
+      authority_returns_to: "$maestro_or_owning_lane",
+      can_run_before_lane: true,
+      can_run_between_lanes: true,
+      can_run_after_lane: true,
+      records_as: "helper_receipt",
+      never_records_as: "gate_approval",
+    },
+    role_application: {
+      all_roles_may_consume_helper_receipts: true,
+      planner_roles: ["$align", "$diagnose"],
+      architect_roles: ["$align", "$diagnose", "$cleanup"],
+      executor_roles: ["$tdd", "$cleanup", "$diagnose"],
+      verifier_roles: ["$diagnose", "$tdd", "$cleanup"],
+      writer_roles: ["$align", "$cleanup"],
+      team_workers: ["$align", "$diagnose", "$tdd", "$cleanup"],
+      exported_host_payloads: ["$align", "$diagnose", "$tdd", "$cleanup"],
+    },
+    handoff_contract: {
+      required_fields: [
+        "skill",
+        "semantic_role",
+        "objective",
+        "observed_context",
+        "result",
+        "does_not_unlock",
+        "next_trigger",
+      ],
+      does_not_unlock: [
+        "release_state_transition",
+        "build_gate",
+        "merge_gate",
+        "production_release",
+      ],
+    },
+  };
+}
+
+export function validateHelperOrchestrationCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("helper orchestration core must be an object");
+  }
+  if (value.schemaVersion !== helperOrchestrationSchemaVersion) {
+    throw new Error(`Unsupported helper orchestration schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Array.isArray(value.helper_contracts)) {
+    throw new Error("helper orchestration core requires helper_contracts");
+  }
+  const found = value.helper_contracts.map((contract) => contract.skill).sort();
+  const expected = [...helperSkillNames].sort();
+  if (JSON.stringify(found) !== JSON.stringify(expected)) {
+    throw new Error("helper orchestration core must define all four helper skills exactly once");
+  }
+  for (const contract of value.helper_contracts) {
+    if (
+      typeof contract.semantic_role !== "string" ||
+      !Array.isArray(contract.activates_when) ||
+      !Array.isArray(contract.outputs) ||
+      !Array.isArray(contract.supports) ||
+      typeof contract.records_as !== "string"
+    ) {
+      throw new Error(
+        "helper contracts require semantic_role, activates_when, outputs, supports, records_as",
+      );
+    }
+  }
+  if (value.composition_rules?.release_state_mutation_allowed !== false) {
+    throw new Error("helper orchestration core must not allow release-state mutation");
+  }
+  if (value.composition_rules?.never_records_as !== "gate_approval") {
+    throw new Error("helper orchestration core must never record as gate approval");
+  }
+  return value;
+}
+
+export function resolveHelperContract(skill, core = createDefaultHelperOrchestrationCore()) {
+  const document = validateHelperOrchestrationCore(core);
+  const contract = document.helper_contracts.find((entry) => entry.skill === skill);
+  if (!contract) {
+    throw new Error(`Unknown helper skill: ${skill}`);
+  }
+  return contract;
+}
+
+export function chooseHelperRoute({
+  releaseState = {},
+  runtimeSummary = {},
+  taskIntent = "",
+} = {}) {
+  const intent = taskIntent.toLowerCase();
+  const helpers = [];
+  const add = (skill, reason) => {
+    if (!helpers.some((entry) => entry.skill === skill)) {
+      helpers.push({ skill, reason });
+    }
+  };
+
+  if (
+    releaseState.idea_status !== "CLEAR" ||
+    releaseState.architecture_status !== "APPROVED" ||
+    intent.includes("scope") ||
+    intent.includes("terminology") ||
+    intent.includes("prompt")
+  ) {
+    add("$align", "Normalize scope, shared language, and the next owning lane.");
+  }
+  if (
+    releaseState.logic_status === "RED" ||
+    releaseState.security_status === "RED" ||
+    runtimeSummary.pendingMailboxCount > 0 ||
+    runtimeSummary.invalidArtifacts?.length > 0 ||
+    intent.includes("blocked") ||
+    intent.includes("failure")
+  ) {
+    add("$diagnose", "Decompose blockers into reproducible slices and next probes.");
+  }
+  if (
+    ["READY", "RUNNING"].includes(releaseState.build_status) ||
+    intent.includes("test") ||
+    intent.includes("regression") ||
+    intent.includes("refactor")
+  ) {
+    add("$tdd", "Lock behavior before implementation expands or cleanup changes code.");
+  }
+  if (
+    releaseState.build_status === "DONE" ||
+    intent.includes("cleanup") ||
+    intent.includes("polish") ||
+    intent.includes("slop") ||
+    intent.includes("docs")
+  ) {
+    add("$cleanup", "Simplify artifacts without changing the owning lane decision.");
+  }
+
+  return {
+    record_type: "helper_route_recommendation",
+    helpers,
+    helper_count: helpers.length,
+    non_gating: true,
+    release_state_mutation_allowed: false,
+    next_owner:
+      helpers.length === 0
+        ? "$maestro_or_owning_lane"
+        : helpers.at(-1).skill === "$cleanup"
+          ? "$maestro_or_release_verification"
+          : "$maestro_or_owning_lane",
+  };
+}
+
+export function createHelperReceipt({
+  skill,
+  objective,
+  observedContext,
+  result,
+  nextTrigger,
+  core = createDefaultHelperOrchestrationCore(),
+}) {
+  const contract = resolveHelperContract(skill, core);
+  if (!objective || !observedContext || !result || !nextTrigger) {
+    throw new Error("helper receipt requires objective, observedContext, result, and nextTrigger");
+  }
+  return {
+    record_type: "helper_receipt",
+    skill,
+    semantic_role: contract.semantic_role,
+    objective,
+    observed_context: observedContext,
+    result,
+    records_as: contract.records_as,
+    does_not_unlock: ["release_state_transition", "build_gate", "merge_gate", "production_release"],
+    next_trigger: nextTrigger,
+    authority: "$maestro_or_owning_lane",
+    created_at: new Date().toISOString(),
+  };
+}
+
+export function evaluateHelperCoreCoverage(core = createDefaultHelperOrchestrationCore()) {
+  const document = validateHelperOrchestrationCore(core);
+  const supportedRoles = new Set();
+  for (const contract of document.helper_contracts) {
+    for (const support of contract.supports) {
+      supportedRoles.add(support);
+    }
+  }
+  return {
+    record_type: "helper_core_coverage",
+    helper_count: document.helper_contracts.length,
+    helper_skills: document.helper_contracts.map((contract) => contract.skill),
+    supported_surface_count: supportedRoles.size,
+    non_gating: document.composition_rules.non_gating === true,
+    release_state_mutation_allowed:
+      document.composition_rules.release_state_mutation_allowed === true,
+    all_helpers_defined: helperSkillNames.every((skill) =>
+      document.helper_contracts.some((contract) => contract.skill === skill),
+    ),
+  };
+}
+
+export async function seedHelperOrchestrationCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getHelperOrchestrationCorePath(),
+    `${JSON.stringify(createDefaultHelperOrchestrationCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadHelperOrchestrationCore() {
+  return validateHelperOrchestrationCore(await readJson(getHelperOrchestrationCorePath()));
+}

package/src/runtime/hook-profiles.js

@@ -0,0 +1,20 @@
+export const hookProfiles = {
+  local: { scanScope: "active-project", block: true, writeReceipts: true, readOnly: false },
+  ci: { scanScope: "active-project", block: true, writeReceipts: true, readOnly: false },
+  pr: {
+    scanScope: "active-project",
+    block: true,
+    writeReceipts: true,
+    readOnly: false,
+    requireFreshness: true,
+  },
+  audit: { scanScope: "broad", block: false, writeReceipts: false, readOnly: true },
+};
+
+export function resolveHookProfile(
+  value = process.env.MA_HOOK_PROFILE ?? process.env.MA_PROFILE ?? "local",
+) {
+  return hookProfiles[value]
+    ? { id: value, ...hookProfiles[value] }
+    : { id: "local", ...hookProfiles.local };
+}

package/src/runtime/learning-loop-core.js

@@ -0,0 +1,344 @@
+import fs from "node:fs/promises";
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+import { createFreshness } from "./context-authority.js";
+import { appendObsidianLearningRecord } from "./obsidian-integration-core.js";
+import { maskSensitiveText } from "./redaction-gateway.js";
+
+export const learningLoopCoreSchemaVersion = "0.1.0";
+
+export const learningLoopDomains = [
+  "core_orchestration",
+  "memory_knowledge",
+  "intelligence_learning",
+  "code_quality_testing",
+  "security_compliance",
+  "architecture_methodology",
+  "devops_observability",
+  "extensibility",
+  "domain_specific",
+];
+
+export function getLearningLoopCorePath() {
+  return getRuntimeSubsystemPath("context", "learning-loop-core.json");
+}
+
+export function getLearningRecordsPath() {
+  return getRuntimeSubsystemPath("learning", "records.jsonl");
+}
+
+export function createDefaultLearningLoopCore() {
+  return {
+    schemaVersion: learningLoopCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "First-party learning loop that turns verified workspace outcomes into durable, lane-aware improvements over time.",
+    loop: {
+      cadence: "every_verified_workflow_or_release_gate",
+      sequence: [
+        "observe_runtime_outcome",
+        "classify_learning_domain",
+        "record_semantic_receipt",
+        "promote_verified_learning",
+        "apply_to_next_run",
+        "verify_effectiveness_delta",
+      ],
+      fail_closed_rule:
+        "Unverified observations stay as candidate learnings and must not change gates, release state, or durable policy.",
+    },
+    domains: [
+      {
+        id: "core_orchestration",
+        label: "Core & Orchestration",
+        learns_from: ["maestro_runs", "lane_handoffs", "manager_events"],
+        writes_to: [".ma/state/manager-runs.json", ".ma/context/workspace-effectiveness.json"],
+        promotion_gate: "handoff_replay_or_release_check_passed",
+      },
+      {
+        id: "memory_knowledge",
+        label: "Memory & Knowledge",
+        learns_from: ["memory_notes", "obsidian_vault_context", "semantic_receipts"],
+        writes_to: [".ma/memory/notes.md", ".ma/memory/index.json", ".ma/context/project.md"],
+        promotion_gate: "source_provenance_and_authority_boundary_verified",
+      },
+      {
+        id: "intelligence_learning",
+        label: "Intelligence & Learning",
+        learns_from: ["prompt_strategy_results", "context_budget_outcomes", "rehearsal_traces"],
+        writes_to: [".ma/context/prompt-strategy-core.json", ".ma/context/learning-loop-core.json"],
+        promotion_gate: "strategy_result_has_verification_delta",
+      },
+      {
+        id: "code_quality_testing",
+        label: "Code Quality & Testing",
+        learns_from: ["test_failures", "lint_results", "build_results", "ralph_progress"],
+        writes_to: [".ma/specs/logic.md", ".ma/plans/build.md"],
+        promotion_gate: "fresh_test_or_build_evidence_passed",
+      },
+      {
+        id: "security_compliance",
+        label: "Security & Compliance",
+        learns_from: ["vet_findings", "exposure_catalog", "redaction_receipts"],
+        writes_to: [".ma/specs/security.md", ".ma/evidence/audits.json"],
+        promotion_gate: "security_review_passed_or_blocker_preserved",
+      },
+      {
+        id: "architecture_methodology",
+        label: "Architecture & Methodology",
+        learns_from: ["architecture_decisions", "methodology_reviews", "tradeoff_outcomes"],
+        writes_to: [".ma/specs/architecture.md", ".ma/decisions.json"],
+        promotion_gate: "architecture_review_accepts_reusable_pattern",
+      },
+      {
+        id: "devops_observability",
+        label: "DevOps & Observability",
+        learns_from: ["release_checks", "package_smokes", "runtime_traces", "hook_audits"],
+        writes_to: [".ma/runbook.md", ".ma/logs/", ".ma/hooks/audit.log"],
+        promotion_gate: "release_or_smoke_gate_passed",
+      },
+      {
+        id: "extensibility",
+        label: "Extensibility",
+        learns_from: ["skill_exports", "plugin_installs", "mcp_policy_results", "host_payloads"],
+        writes_to: [".ma/context/skills-registry-export.json", "mcp/servers.json"],
+        promotion_gate: "compatibility_matrix_verified",
+      },
+      {
+        id: "domain_specific",
+        label: "Domain-Specific",
+        learns_from: ["workspace_stack", "project_domain_notes", "trusted_sources"],
+        writes_to: [
+          ".ma/context/workspace-context-pack.json",
+          ".ma/evidence/semantic-receipts.json",
+        ],
+        promotion_gate: "domain_claim_has_source_or_user_authority",
+      },
+    ],
+    learning_record_schema: {
+      domain: "one_of_learningLoopDomains",
+      claim: "string",
+      source: "path_or_runtime_surface",
+      evidence: ["path_or_command_or_receipt"],
+      status: "candidate | verified | rejected | superseded",
+      applies_to: ["agent_or_role_or_lane"],
+      fact_ids: ["canonical_project_fact_id"],
+      cannot_mutate: ["release_state_without_owning_lane", "source_evidence", "security_boundary"],
+      next_verification: "string",
+    },
+    hard_rules: [
+      "Learning records require domain, claim, source, evidence, status, applies_to, and next_verification.",
+      "fact_ids may reference only canonical source-truth project facts.",
+      "Candidate learnings can inform context but cannot mutate gates, release state, or durable policy.",
+      "Verified learnings must preserve lane authority and semantic channel boundaries.",
+      "Obsidian and memory context can inform planning but do not become build evidence without owning-lane promotion.",
+      "Security, compliance, redaction, and irreversible-action warnings must not be compressed or auto-promoted.",
+    ],
+    records: [],
+  };
+}
+
+export function validateLearningLoopCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("learning loop core must be an object");
+  }
+  if (value.schemaVersion !== learningLoopCoreSchemaVersion) {
+    throw new Error(`Unsupported learning loop core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Array.isArray(value.domains) || value.domains.length !== learningLoopDomains.length) {
+    throw new Error("learning loop core must include every required learning domain");
+  }
+  const ids = new Set(value.domains.map((domain) => domain.id));
+  for (const required of learningLoopDomains) {
+    if (!ids.has(required)) {
+      throw new Error(`learning loop core missing domain: ${required}`);
+    }
+  }
+  for (const domain of value.domains) {
+    if (
+      typeof domain.label !== "string" ||
+      !Array.isArray(domain.learns_from) ||
+      !Array.isArray(domain.writes_to) ||
+      typeof domain.promotion_gate !== "string"
+    ) {
+      throw new Error(
+        "learning loop domains require label, learns_from, writes_to, and promotion_gate",
+      );
+    }
+  }
+  if (!Array.isArray(value.records)) {
+    throw new Error("learning loop core requires records array");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("learning loop core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export function createLearningRecord({
+  domain,
+  claim,
+  source,
+  evidence = [],
+  filesInvolved = [],
+  decisionsMade = [],
+  knownRisks = [],
+  userPreferences = {},
+  status = "candidate",
+  appliesTo = ["all_applicable_agents", "all_applicable_roles"],
+  nextVerification,
+  factIds = [],
+  failureState,
+  attemptedFixes = [],
+  resolutionStatus,
+}) {
+  if (!learningLoopDomains.includes(domain)) {
+    throw new Error(`Unsupported learning domain: ${domain}`);
+  }
+  if (!claim || !source || !nextVerification) {
+    throw new Error("Learning record requires domain, claim, source, and nextVerification");
+  }
+  if (
+    !Array.isArray(factIds) ||
+    factIds.some((entry) => typeof entry !== "string" || !/^fact-[a-f0-9]{16}$/.test(entry))
+  ) {
+    throw new Error("Learning record factIds must use canonical fact IDs");
+  }
+  const createdAt = new Date().toISOString();
+  return {
+    domain,
+    claim: sanitizeLearningText(claim),
+    source: sanitizeLearningText(source),
+    evidence: evidence
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map(sanitizeLearningText),
+    files_involved: filesInvolved
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map(sanitizeLearningText),
+    decisions_made: decisionsMade
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map(sanitizeLearningText),
+    known_risks: knownRisks
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map(sanitizeLearningText),
+    user_preferences: userPreferences && typeof userPreferences === "object" ? userPreferences : {},
+    status,
+    authority: "learning_memory",
+    freshness: createFreshness({ checkedAt: createdAt }),
+    applies_to: appliesTo.filter((entry) => typeof entry === "string" && entry.trim()),
+    fact_ids: factIds.filter((entry) => typeof entry === "string" && entry.trim()),
+    cannot_mutate: ["release_state_without_owning_lane", "source_evidence", "security_boundary"],
+    next_verification: nextVerification,
+    created_at: createdAt,
+    ...(failureState
+      ? {
+          failure_state: failureState,
+          attempted_fixes: attemptedFixes
+            .filter((entry) => typeof entry === "string")
+            .map(sanitizeLearningText),
+          resolution_status: resolutionStatus ?? "active",
+        }
+      : {}),
+  };
+}
+
+function sanitizeLearningText(value) {
+  return maskSensitiveText(String(value)).sanitizedText;
+}
+
+export function addLearningRecord(core, record) {
+  const validated = validateLearningLoopCore(core);
+  if (!learningLoopDomains.includes(record.domain)) {
+    throw new Error(`Unsupported learning domain: ${record.domain}`);
+  }
+  if (!["candidate", "verified", "rejected", "superseded"].includes(record.status)) {
+    throw new Error(`Unsupported learning record status: ${record.status}`);
+  }
+  return validateLearningLoopCore({
+    ...validated,
+    records: [...validated.records, record],
+  });
+}
+
+export function evaluateLearningLoopReadiness(core) {
+  const validated = validateLearningLoopCore(core);
+  const coveredDomains = new Set(validated.domains.map((domain) => domain.id));
+  const verifiedDomains = new Set(
+    validated.records
+      .filter((record) => record.status === "verified")
+      .map((record) => record.domain),
+  );
+
+  return {
+    record_type: "learning_loop_readiness",
+    ready: learningLoopDomains.every((domain) => coveredDomains.has(domain)),
+    domains: learningLoopDomains.length,
+    verified_domains: verifiedDomains.size,
+    candidate_records: validated.records.filter((record) => record.status === "candidate").length,
+    promotion_rule: validated.loop.fail_closed_rule,
+  };
+}
+
+export async function seedLearningLoopCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getLearningLoopCorePath(),
+    `${JSON.stringify(createDefaultLearningLoopCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadLearningLoopCore() {
+  return validateLearningLoopCore(await readJson(getLearningLoopCorePath()));
+}
+
+export async function appendLearningRecord(record) {
+  const validated = createLearningRecord(record);
+  await ensureDir(getRuntimeSubsystemPath("learning"));
+  await fs.appendFile(getLearningRecordsPath(), `${JSON.stringify(validated)}\n`, "utf8");
+  return validated;
+}
+
+export async function recordWorkLearning({ vaultPath, ...record }) {
+  const validated = await appendLearningRecord(record);
+  if (vaultPath) await appendObsidianLearningRecord({ vaultPath, record: validated });
+  return validated;
+}
+
+export async function recordFailureMemory({
+  cause,
+  source = "workflow",
+  evidence = [],
+  attemptedFixes = [],
+  resolutionStatus = "active",
+  filesInvolved = [],
+  vaultPath,
+} = {}) {
+  if (!cause) throw new Error("failure memory requires cause");
+  if (!["active", "resolved", "stale"].includes(resolutionStatus)) {
+    throw new Error(`Unsupported failure resolution status: ${resolutionStatus}`);
+  }
+  return recordWorkLearning({
+    vaultPath,
+    domain: "code_quality_testing",
+    claim: `Failure: ${cause}`,
+    source,
+    evidence,
+    filesInvolved,
+    knownRisks: [cause],
+    status: resolutionStatus === "resolved" ? "verified" : "candidate",
+    nextVerification:
+      resolutionStatus === "resolved" ? "Monitor for recurrence" : "Re-run the failing workflow",
+    failureState: resolutionStatus,
+    attemptedFixes,
+    resolutionStatus,
+  });
+}
+
+export async function loadLearningRecords({ limit = 20 } = {}) {
+  const raw = await fs.readFile(getLearningRecordsPath(), "utf8").catch(() => "");
+  return raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line))
+    .slice(-Math.max(1, Math.min(100, limit)))
+    .reverse();
+}