@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/src/core/reconcile-closure.js

@@ -1,6 +1,7 @@
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { appendProtocolEvent, validateEventLedger, readEvents, validateCompletionRecoveryAuthorization } from "./events.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebind.js";
 import { runCommandExecution } from "./execution.js";
 import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
@@ -68,7 +69,7 @@ export async function runReconcileClosure({
   const eventsRel = taskArtifactPath(taskId, "events");
   const receiptRel = taskArtifactPath(taskId, "receipt");
 
-  const state = await readWorkState(target, { packageRoot, taskId });
+  let state = await readWorkState(target, { packageRoot, taskId });
   if (!state) {
     throw reconcileError("E_RECONCILE_PHASE_INVALID", "Cannot reconcile without work state", [stateRel]);
   }
@@ -80,22 +81,24 @@ export async function runReconcileClosure({
     );
   }
   if (state.phase === "REVIEWING") {
-    let receipt = null;
-    try {
-      receipt = (await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot))?.value ?? null;
-    } catch {
-      receipt = null;
-    }
-    const events = await readEvents(target, packageRoot, { taskId });
-    const recoveryAuth = validateCompletionRecoveryAuthorization({ state, receipt, events });
-    if (!recoveryAuth.authorized) {
-      const first = recoveryAuth.errors?.[0] ?? {};
+    const recovery = await authorizeCompletionRecoveryOrRebind({
+      target,
+      packageRoot,
+      taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    if (!recovery.recoveryAuth.authorized) {
+      const first = recovery.recoveryAuth.errors?.[0] ?? {};
       throw reconcileError(
         first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
         `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
         [stateRel, receiptRel],
       );
     }
+    if (recovery.rebound) {
+      state = recovery.state;
+    }
   }
 
   const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });

package/src/core/reflection.js

@@ -0,0 +1,305 @@
+import { buildTaskTrace } from "./trace.js";
+import { readEvents } from "./events.js";
+import { findTaskById } from "./task-discovery.js";
+import { projectHypothesisStates } from "./hypothesis-projection.js";
+import {
+  buildInformationGainProjection,
+  evaluateStructuredDiagnosticStall,
+} from "./information-gain-projection.js";
+import { computeFailureSignature } from "./failure-signature.js";
+import {
+  computeStrategyFingerprints as computeStrategyFingerprintsImpl,
+  detectOscillation as detectOscillationImpl,
+  evaluateInterventionEffectiveness as evaluateInterventionEffectivenessImpl,
+} from "./strategy-analysis.js";
+
+export const REFLECTION_STATUS = Object.freeze({
+  ADVANCING: "ADVANCING",
+  WATCH: "WATCH",
+  STALLED: "STALLED",
+});
+
+
+export function summarizeHypotheses(trace) {
+  const summary = { created: 0, supported: 0, weakened: 0, falsified: 0, superseded: 0, unresolved: 0, open: 0 };
+
+  const pseudoEvents = [
+    ...trace.diagnostics.cases.map((diagnosticCase) => ({
+      seq: diagnosticCase.sequence,
+      event: "DIAGNOSTIC_CASE_RECORDED",
+      details: diagnosticCase,
+    })),
+    ...trace.diagnostics.legacyDiagnoses.map((legacy) => ({
+      seq: legacy.sequence,
+      event: "DIAGNOSIS_RECORDED",
+      details: legacy,
+    })),
+    ...trace.diagnostics.dispositions.map((disposition) => ({
+      seq: disposition.sequence,
+      event: "HYPOTHESIS_DISPOSITION_RECORDED",
+      details: disposition,
+    })),
+  ];
+  const projection = projectHypothesisStates(pseudoEvents);
+
+  for (const hypothesis of projection.hypotheses) {
+    if (hypothesis.id === "h-legacy" && hypothesis.sourceEventSeq !== null) {
+      summary.created += 1;
+    } else if (hypothesis.id !== "h-legacy") {
+      summary.created += 1;
+    }
+    const status = hypothesis.currentStatus.toLowerCase();
+    if (summary[status] !== undefined) summary[status] += 1;
+  }
+  summary.open = projection.openHypotheses.length;
+  return summary;
+}
+
+export function detectOscillation(strategies) {
+  return detectOscillationImpl(strategies);
+}
+
+export function evaluateInterventionEffectiveness(trace, surfacesByCycle) {
+  return evaluateInterventionEffectivenessImpl(trace, surfacesByCycle);
+}
+
+function failedRequirementSurfacesFromEvents(events = [], state = null) {
+  const byCycle = new Map();
+  const record = (cycle, requirement) => {
+    if (!requirement) return;
+    if (!byCycle.has(cycle)) byCycle.set(cycle, new Set());
+    byCycle.get(cycle).add(requirement);
+  };
+  for (const event of events) {
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    const d = event.details ?? {};
+    if (d.status === "failed" || d.status === "blocked") {
+      record(d.verificationCycle ?? 1, d.requirement ?? d.id ?? d.checkId);
+    }
+  }
+  for (const check of state?.checks ?? []) {
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check.requirement ?? check.id ?? check.checkId);
+  }
+  return byCycle;
+}
+
+function signatureSetsByCycle(trace) {
+  const byCycle = new Map();
+  for (const entry of trace.failureSignatures) {
+    for (const cycle of entry.cycles ?? []) {
+      if (!byCycle.has(cycle)) byCycle.set(cycle, new Set());
+      byCycle.get(cycle).add(entry.signature);
+    }
+  }
+  return byCycle;
+}
+
+export function deriveDiagnosticContext(events = [], state = null) {
+  const cycle = state?.verificationCycle ?? null;
+  const taskEvents = events.filter((event) => !state?.taskId || event.taskId === state.taskId);
+
+  // Canonical failure-signature hashes for the active verification cycle.
+  const activeFailureSignatures = [...new Set(
+    taskEvents
+      .filter((event) => event.event === "VERIFICATION_RECORDED"
+        && ["failed", "blocked"].includes(event.details?.status)
+        && (cycle === null || event.details?.verificationCycle === cycle))
+      .map((event) => {
+        const d = event.details;
+        return computeFailureSignature({
+          requirement: d.requirement ?? d.id ?? d.checkId,
+          status: d.status,
+          exitCode: Number.isInteger(d.exitCode) ? d.exitCode : null,
+          failureToken: typeof d.failureToken === "string" && d.failureToken
+            ? d.failureToken
+            : (typeof d.details?.failureToken === "string" ? d.details.failureToken : null),
+        });
+      }),
+  )].sort();
+
+  const activeFailedRequirements = [...new Set(
+    [
+      ...taskEvents
+        .filter((event) => event.event === "VERIFICATION_RECORDED"
+          && ["failed", "blocked"].includes(event.details?.status)
+          && (cycle === null || event.details?.verificationCycle === cycle))
+        .map((event) => event.details?.requirement ?? event.details?.id ?? event.details?.checkId),
+      ...((state?.checks ?? []))
+        .filter((check) => ["failed", "blocked"].includes(check.status)
+          && (cycle === null || check.details?.verificationCycle === cycle))
+        .map((check) => check.requirement ?? check.id ?? check.checkId),
+    ].filter(Boolean),
+  )].sort();
+
+  const projection = projectHypothesisStates(taskEvents);
+  const openHypotheses = [...projection.openHypotheses].sort();
+
+  const interventions = taskEvents.filter((event) => event.event === "INTERVENTION_RECORDED");
+  const latestIntervention = interventions.at(-1)?.details?.intervention?.id ?? null;
+
+  // doNotRepeat requires semantic repetition AND at least two completed
+  // post-intervention verification cycles AND unchanged failure surface.
+  const surfacesByCycle = failedRequirementSurfacesFromEvents(taskEvents, state);
+  const completedCycles = [...new Set(
+    taskEvents.filter((event) => event.event === "VERIFICATION_STARTED")
+      .map((event) => event.details?.verificationCycle)
+      .filter(Number.isInteger),
+  )].sort((a, b) => a - b);
+
+  const fingerprintGroups = new Map();
+  for (const event of interventions) {
+    const fingerprint = event.details?.interventionSemanticFingerprint;
+    if (!fingerprint) continue;
+    if (!fingerprintGroups.has(fingerprint)) fingerprintGroups.set(fingerprint, []);
+    fingerprintGroups.get(fingerprint).push(event);
+  }
+
+  const doNotRepeat = [];
+  for (const [fingerprint, group] of fingerprintGroups.entries()) {
+    if (group.length < 2) continue;
+    const lastInterventionCycle = Math.max(...group.map((event) => event.details?.verificationCycle ?? 1));
+    const postCycles = completedCycles.filter((completed) => completed > lastInterventionCycle);
+    if (postCycles.length < 2) continue;
+    const firstSurface = [...(surfacesByCycle.get(lastInterventionCycle) ?? [])].sort();
+    const latestSurface = [...(surfacesByCycle.get(postCycles.at(-1)) ?? [])].sort();
+    if (JSON.stringify(firstSurface) === JSON.stringify(latestSurface)) {
+      doNotRepeat.push(fingerprint);
+    }
+  }
+  doNotRepeat.sort();
+
+  return {
+    activeFailureSignatures,
+    activeFailedRequirements,
+    openHypotheses,
+    latestIntervention,
+    nextExperiment: null,
+    doNotRepeat,
+  };
+}
+
+export async function buildTaskReflection({ target, packageRoot, taskId = null } = {}) {
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  // Modern tasks own a scoped ledger; legacy singleton callers still pass a
+  // taskId that must be used only as a filter over the canonical ledger.
+  const task = taskId ? await findTaskById(target, taskId, packageRoot) : null;
+  const rawEvents = await readEvents(target, packageRoot, task ? { taskId } : {});
+
+  // Authoritative surfaces come from the canonical trace projection.
+  const surfaceEntries = {};
+  for (const entry of trace.failureSurfaces) {
+    surfaceEntries[entry.verificationCycle] = { surface: entry.surface, signatures: [] };
+  }
+  const signatureSets = signatureSetsByCycle(trace);
+  for (const [cycle, signatures] of signatureSets.entries()) {
+    if (!surfaceEntries[cycle]) surfaceEntries[cycle] = { surface: [], signatures: [] };
+    surfaceEntries[cycle].signatures = [...signatures].sort();
+  }
+
+  const cycles = [...new Set([
+    ...trace.failureSurfaces.map((entry) => entry.verificationCycle),
+    ...trace.diagnostics.cases.map((diagnosticCase) => diagnosticCase.verificationCycle),
+  ])].sort((a, b) => a - b);
+
+  const strategies = computeStrategyFingerprintsImpl(trace);
+  const oscillation = detectOscillation(strategies);
+
+  const signals = [];
+  let status = REFLECTION_STATUS.ADVANCING;
+
+  const evaluatedInterventions = evaluateInterventionEffectiveness(trace, surfaceEntries);
+  const repeatedNonInformative = evaluatedInterventions
+    .filter((intervention) => intervention.effectiveness === "NON_INFORMATIVE");
+  if (oscillation.detected) {
+    signals.push("OSCILLATING_STRATEGY");
+    status = REFLECTION_STATUS.WATCH;
+  }
+  if (repeatedNonInformative.length >= 2) {
+    signals.push("REPEATED_INTERVENTION");
+    status = REFLECTION_STATUS.WATCH;
+  }
+
+  const lastTwoSameStrategy = strategies.length >= 2
+    && strategies.at(-1).strategyFingerprint === strategies.at(-2).strategyFingerprint
+    && JSON.stringify(surfaceEntries[strategies.at(-1)?.verificationCycle]?.signatures ?? [])
+      === JSON.stringify(surfaceEntries[strategies.at(-2)?.verificationCycle]?.signatures ?? []);
+  if (lastTwoSameStrategy && !signals.includes("OSCILLATING_STRATEGY")) {
+    status = status === REFLECTION_STATUS.ADVANCING ? REFLECTION_STATUS.WATCH : status;
+  }
+
+  // Information Gain v2 truth comes fully from the authoritative cycle
+  // analysis projection. Consumers must not redefine gain semantics.
+  const gainProjection = buildInformationGainProjection(rawEvents, taskId ?? null);
+  const cyclesWithoutEffectiveGain = gainProjection
+    .filter((entry) => !entry.effectiveGain)
+    .map((entry) => entry.verificationCycle);
+
+  // One canonical structured-stall truth shared with phase and progress.
+  const stallAnalysis = evaluateStructuredDiagnosticStall(gainProjection);
+  const latestNoGain = Boolean(stallAnalysis.stalled);
+  let consecutiveNoGainCycles = 0;
+  for (let i = gainProjection.length - 1; i >= 0 && gainProjection[i].effectiveGain === false; i--) {
+    consecutiveNoGainCycles += 1;
+  }
+  const previousEntry = gainProjection.length >= 2 ? gainProjection.at(-2) : null;
+  const currentEntry = gainProjection.at(-1) ?? null;
+  if (latestNoGain) {
+    status = REFLECTION_STATUS.STALLED;
+    if (!signals.includes("NO_EFFECTIVE_INFORMATION_GAIN")) signals.push("NO_EFFECTIVE_INFORMATION_GAIN");
+  }
+  if ((trace.actions?.ambiguous ?? 0) > 0) {
+    signals.push("EXTERNAL_ACTION_RECONCILIATION_REQUIRED");
+    status = status === REFLECTION_STATUS.ADVANCING ? REFLECTION_STATUS.WATCH : status;
+  }
+
+  const recommendedProtocolAction = (trace.actions?.ambiguous ?? 0) > 0
+    ? "RECONCILE_EXTERNAL_ACTION"
+    : oscillation.detected
+    ? "INTRODUCE_NEW_OBSERVATION"
+    : (status === REFLECTION_STATUS.STALLED ? "REQUIRE_NEW_DIAGNOSTIC_INFORMATION" : "CONTINUE");
+
+  return {
+    schemaVersion: 1,
+    command: "reflect",
+    taskId: trace.task.id,
+    taskPhase: trace.task.phase,
+    integrityValid: trace.integrity.valid,
+    snapshotConsistent: trace.snapshot.consistent,
+    status,
+    verificationCycles: cycles.length,
+    failureSurfaces: trace.failureSurfaces,
+    hypotheses: summarizeHypotheses(trace),
+    interventions: (() => {
+      const evaluated = evaluatedInterventions;
+      return {
+        count: evaluated.length,
+        informative: evaluated.filter((intervention) => ["INFORMATIVE", "IMPROVED"].includes(intervention.effectiveness)).length,
+        nonInformative: evaluated.filter((intervention) => intervention.effectiveness === "NON_INFORMATIVE").length,
+        details: evaluated,
+      };
+    })(),
+    informationGain: {
+      cyclesWithCases: trace.diagnostics.cases.map((diagnosticCase) => diagnosticCase.verificationCycle),
+      cyclesWithoutEffectiveGain,
+      cycles: gainProjection.map(({ dimensions, ...rest }) => ({ ...rest, dimensions })),
+    },
+    strategies,
+    oscillation,
+    signals,
+    stallAnalysis: {
+      latestNoGain,
+      consecutiveNoGainCycles,
+      sameStrategyAsPrevious: Boolean(previousEntry && currentEntry
+        && previousEntry.evidence.strategyFingerprint === currentEntry.evidence.strategyFingerprint),
+      sameFailureSurfaceAsPrevious: Boolean(previousEntry && currentEntry
+        && JSON.stringify(previousEntry.evidence.failureSurface) === JSON.stringify(currentEntry.evidence.failureSurface)),
+      sameFailureSignaturesAsPrevious: Boolean(previousEntry && currentEntry
+        && JSON.stringify(previousEntry.evidence.failureSignatures) === JSON.stringify(currentEntry.evidence.failureSignatures)),
+    },
+    recommendedProtocolAction,
+    actions: trace.actions,
+  };
+}
+
+export { computeStrategyFingerprintsImpl as computeStrategyFingerprints };

package/src/core/resumability.js

@@ -1,22 +1,76 @@
 import { currentRepositoryFingerprint } from "./repository.js";
+import { validateEventLedger } from "./events.js";
 import { createWorkState, initializeWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
+/**
+ * Resume phase derived from the highest lifecycle milestone already recorded in
+ * a validated ledger. Recreating a checkpoint at ROUTED for a task whose ledger
+ * already passed EXECUTION_STARTED would make every subsequent advance append a
+ * duplicate non-repeatable milestone and invalidate the ledger, so restoration
+ * must resume at the phase the recorded chronology supports.
+ */
+const RESUME_PHASE_BY_MILESTONE = Object.freeze({
+  PLAN_RECORDED: "PLANNED",
+  EXECUTION_STARTED: "EXECUTING",
+  VERIFICATION_STARTED: "VERIFYING",
+  VERIFICATION_RECORDED: "VERIFYING",
+});
+
+async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
+  let ledger;
+  try {
+    ledger = await validateEventLedger(target, packageRoot, { taskId });
+  } catch {
+    return null;
+  }
+  if (!ledger?.valid) return null;
+  const scoped = (ledger.events ?? []).filter((event) => event.taskId === taskId);
+  if (scoped.some((event) => event.event === "COMPLETION_VALIDATED")) return null;
+  const positions = RESUME_PHASE_BY_MILESTONE;
+  let derived = null;
+  for (const event of scoped) {
+    const phase = positions[event.event];
+    if (!phase) continue;
+    if (!derived) {
+      derived = phase;
+      continue;
+    }
+    if (phase === "VERIFYING") derived = "VERIFYING";
+  }
+  return derived;
+}
+
+function resumeSteps(phase) {
+  if (phase === "EXECUTING" || phase === "VERIFYING") {
+    return {
+      completedSteps: ["contract", "route", "planning", "implementation"],
+      pendingSteps: ["verification"],
+    };
+  }
+  return {
+    completedSteps: ["contract", "route"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS],
+  };
+}
+
 export async function ensureResumableState({ target, packageRoot, contract, route, taskId, statePath }) {
   if (!contract || !route) return null;
   const existing = await readWorkState(target, { packageRoot, taskId, statePath });
   if (existing) return existing;
 
+  const resumedPhase = await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED";
+  const steps = resumeSteps(resumedPhase);
   const state = createWorkState({
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     repositoryFingerprint: await currentRepositoryFingerprint(target),
-    phase: "ROUTED",
+    phase: resumedPhase,
     selectedGuides: route.value.guides,
-    completedSteps: ["contract", "route"],
-    pendingSteps: DEFAULT_PENDING_STEPS,
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
     checks: [],
     failures: [],
     blockers: [],

package/src/core/schema-validation.js

@@ -34,6 +34,14 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "authority",
   "task-descriptor",
   "task-recovery",
+  "diagnostic-case",
+  "intervention",
+  "hypothesis-disposition",
+  "action",
+  "approval",
+  "capability-policy",
+  "trajectory-evaluation",
+  "trajectory-scenario",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/strategy-analysis.js

@@ -0,0 +1,97 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { compareFailureSurface } from "./failure-surface.js";
+
+export function computeStrategyFingerprints(trace) {
+  const byCycle = new Map();
+  const add = (cycle, component, fingerprint) => {
+    if (!byCycle.has(cycle)) byCycle.set(cycle, { hypotheses: new Set(), contributors: new Set(), interventions: new Set() });
+    byCycle.get(cycle)[component].add(fingerprint);
+  };
+  for (const diagnosticCase of trace.diagnostics.cases) {
+    for (const hypothesis of diagnosticCase.hypotheses ?? []) {
+      add(diagnosticCase.verificationCycle, "hypotheses", `${hypothesis.statement}`.trim().toLowerCase());
+    }
+    for (const contributor of diagnosticCase.contributors ?? []) {
+      add(diagnosticCase.verificationCycle, "contributors", `${contributor.statement}`.trim().toLowerCase());
+    }
+  }
+  for (const legacy of trace.diagnostics.legacyDiagnoses) {
+    add(legacy.verificationCycle, "hypotheses", `${legacy.hypothesis}`.trim().toLowerCase());
+  }
+  for (const intervention of trace.diagnostics.interventions) {
+    add(intervention.verificationCycle, "interventions", intervention.interventionSemanticFingerprint ?? `${intervention.intervention?.statement ?? ""}`.trim().toLowerCase());
+  }
+
+  return [...byCycle.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([cycle, components]) => ({
+      verificationCycle: cycle,
+      strategyFingerprint: JSON.stringify([
+        [...components.hypotheses].sort(),
+        [...components.contributors].sort(),
+        [...components.interventions].sort(),
+      ]),
+      components: {
+        hypotheses: [...components.hypotheses].sort(),
+        contributors: [...components.contributors].sort(),
+        interventions: [...components.interventions].sort(),
+      },
+    }));
+}
+
+export function detectOscillation(strategies) {
+  const fingerprints = strategies.map((strategy) => strategy.strategyFingerprint);
+  const patterns = [];
+  for (let i = 2; i < fingerprints.length; i++) {
+    if (fingerprints[i] === fingerprints[i - 2] && fingerprints[i] !== fingerprints[i - 1]) {
+      patterns.push({ kind: "A_B_A", cycles: [strategies[i - 2].verificationCycle, strategies[i - 1].verificationCycle, strategies[i].verificationCycle] });
+    }
+  }
+  for (let i = 3; i < fingerprints.length; i++) {
+    if (fingerprints[i] === fingerprints[i - 2]
+      && fingerprints[i - 1] === fingerprints[i - 3]
+      && fingerprints[i] !== fingerprints[i - 1]) {
+      patterns.push({ kind: "A_B_A_B", cycles: [strategies[i - 3].verificationCycle, strategies[i - 2].verificationCycle, strategies[i - 1].verificationCycle, strategies[i].verificationCycle] });
+    }
+  }
+  const detected = patterns.length > 0;
+  return { detected, patterns };
+}
+
+export function evaluateInterventionEffectiveness(trace, surfacesByCycle) {
+  const interventions = [];
+  const list = trace.diagnostics.interventions;
+  for (const entry of list) {
+    const cycle = entry.verificationCycle;
+    const laterVerificationCycles = Object.keys(surfacesByCycle).map(Number).filter((value) => value > cycle);
+    const nextCycle = laterVerificationCycles.length > 0 ? Math.min(...laterVerificationCycles) : null;
+
+    let effectiveness = "PENDING";
+    if (nextCycle !== null) {
+      const previousSurface = surfacesByCycle[cycle]?.surface ?? [];
+      const currentSurface = surfacesByCycle[nextCycle]?.surface ?? [];
+      const comparison = compareFailureSurface(previousSurface, currentSurface);
+      const signatureChanged = JSON.stringify(surfacesByCycle[cycle]?.signatures ?? []) !== JSON.stringify(surfacesByCycle[nextCycle]?.signatures ?? []);
+      if (comparison.direction === "REDUCED") effectiveness = "IMPROVED";
+      else if (comparison.direction === "EXPANDED") effectiveness = "REGRESSED";
+      else if (signatureChanged || comparison.changed) effectiveness = "INFORMATIVE";
+      else effectiveness = "NON_INFORMATIVE";
+    }
+    interventions.push({
+      id: entry.intervention?.id ?? null,
+      sequence: entry.sequence,
+      verificationCycle: cycle,
+      kind: entry.intervention?.kind ?? null,
+      reversible: entry.intervention?.reversible ?? null,
+      semanticFingerprint: entry.interventionSemanticFingerprint ?? null,
+      effectiveness,
+    });
+  }
+  return interventions;
+}
+
+
+export function interventionSemanticFingerprintOf(entry) {
+  return entry?.interventionSemanticFingerprint
+    ?? (entry?.intervention ? canonicalFingerprint(entry.intervention) : null);
+}

package/src/core/task-paths.js

@@ -15,6 +15,9 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   events: "events.ndjson",
   gates: "gates",
   executions: "executions",
+  actions: "actions",
+  approvals: "approvals",
+  evaluations: "evaluations",
   policySnapshot: "policy-snapshot.json",
   recovery: "recovery.json",
 });
@@ -32,6 +35,7 @@ export const PROJECT_ARTIFACT_PATHS = Object.freeze({
   policyBaseline: ".forgeloop/policy/baseline.json",
   policyLock: ".forgeloop/policy/policy.lock",
   policyDiscovery: ".forgeloop/policy/discovery.json",
+  capabilityPolicy: ".forgeloop/policy/capabilities.json",
 });
 
 export const LEGACY_TASK_ARTIFACT_PATHS = Object.freeze({
@@ -74,6 +78,27 @@ export function taskExecutionPath(taskId, executionId) {
   return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.executions}/${executionId}.json`;
 }
 
+export function taskActionPath(taskId, actionId) {
+  if (typeof actionId !== "string" || !/^action-[A-Za-z0-9_-]+$/.test(actionId)) {
+    throw new Error(`Invalid action ID: ${actionId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.actions}/${actionId}.json`;
+}
+
+export function taskApprovalPath(taskId, approvalId) {
+  if (typeof approvalId !== "string" || !/^approval-[A-Za-z0-9_-]+$/.test(approvalId)) {
+    throw new Error(`Invalid approval ID: ${approvalId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.approvals}/${approvalId}.json`;
+}
+
+export function taskEvaluationPath(taskId, evaluationId) {
+  if (typeof evaluationId !== "string" || !/^eval-[A-Za-z0-9_-]+$/.test(evaluationId)) {
+    throw new Error(`Invalid evaluation ID: ${evaluationId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.evaluations}/${evaluationId}.json`;
+}
+
 export function taskLockPath(taskId) {
   assertTaskId(taskId);
   return `${TASK_LOCK_ROOT}/${taskStorageKey(taskId)}.lock`;
@@ -101,6 +126,9 @@ export function buildTaskArtifactPaths(taskId) {
     events: `${dir}/${TASK_ARTIFACT_FILES.events}`,
     gates: `${dir}/${TASK_ARTIFACT_FILES.gates}`,
     executions: `${dir}/${TASK_ARTIFACT_FILES.executions}`,
+    actions: `${dir}/${TASK_ARTIFACT_FILES.actions}`,
+    approvals: `${dir}/${TASK_ARTIFACT_FILES.approvals}`,
+    evaluations: `${dir}/${TASK_ARTIFACT_FILES.evaluations}`,
     lock: taskLockPath(taskId),
     policySnapshot: `${dir}/${TASK_ARTIFACT_FILES.policySnapshot}`,
     recovery: `${dir}/${TASK_ARTIFACT_FILES.recovery}`,

package/src/core/task-snapshot.js

@@ -0,0 +1,53 @@
+import { readEvents, validateEventLedger } from "./events.js";
+import { readWorkState } from "./work-state.js";
+import { canonicalFingerprint } from "./artifacts.js";
+
+function ledgerTail(events) {
+  const last = events.at(-1) ?? null;
+  return {
+    sequence: last?.seq ?? 0,
+    hash: last?.hash ?? null,
+  };
+}
+
+export async function buildTaskSnapshot({
+  target,
+  packageRoot,
+  taskId = null,
+  eventsPath = null,
+  stateFile = null,
+} = {}) {
+  const options = { packageRoot, taskId, ...(eventsPath ? { eventsPath } : {}) };
+  const state = await readWorkState(target, { ...options, ...(stateFile ? { statePath: stateFile } : {}) });
+  const events = await readEvents(target, packageRoot, options);
+  const before = {
+    stateRevision: state?.revision ?? null,
+    ...ledgerTail(events),
+  };
+
+  const validation = await validateEventLedger(target, packageRoot, options);
+
+  const rereadState = await readWorkState(target, { ...options, ...(stateFile ? { statePath: stateFile } : {}) });
+  const rereadEvents = await readEvents(target, packageRoot, options);
+  const after = {
+    stateRevision: rereadState?.revision ?? null,
+    ...ledgerTail(rereadEvents),
+  };
+
+  const consistent = JSON.stringify(before) === JSON.stringify(after);
+
+  return {
+    consistent,
+    taskId: taskId ?? state?.taskId ?? rereadState?.taskId ?? null,
+    anchors: before,
+    capturedAt: new Date().toISOString(),
+    integrity: {
+      valid: validation.valid,
+      errors: validation.errors,
+      eventCount: validation.events.length,
+      fingerprint: canonicalFingerprint(validation.events.map(({ seq, event, at }) => ({ seq, event, at }))),
+    },
+    state: rereadState,
+    events: validation.events,
+  };
+}

package/src/core/templates.js

@@ -67,6 +67,14 @@ export const TEMPLATE_PATHS = [
   "schemas/authority.schema.json",
   "schemas/task-descriptor.schema.json",
   "schemas/task-recovery.schema.json",
+  "schemas/diagnostic-case.schema.json",
+  "schemas/intervention.schema.json",
+  "schemas/hypothesis-disposition.schema.json",
+  "schemas/action.schema.json",
+  "schemas/approval.schema.json",
+  "schemas/capability-policy.schema.json",
+  "schemas/trajectory-evaluation.schema.json",
+  "schemas/trajectory-scenario.schema.json",
 ];
 
 export function getPackageRoot() {