@cassiomc1/forgeloop 1.1.0 → 1.2.1

package/docs/TROUBLESHOOTING.md

@@ -8,6 +8,8 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 
 - [`preflight` is `BLOCKED`](#symptom-preflight-is-blocked)
 - [`forgeloop next` returns `RESOLVE_BLOCKER`](#symptom-forgeloop-next-returns-resolve_blocker)
+- [`forgeloop next` returns `RECORD_DIAGNOSIS`](#symptom-forgeloop-next-returns-record_diagnosis)
+- [Progress is `STALLED` or `forgeloop next` returns `CHANGE_STRATEGY`](#symptom-progress-is-stalled)
 - [Protocol state or contract is `STALE`](#symptom-state-or-contract-is-stale)
 - [Execution continuity is `STALE`](#symptom-continuity-is-stale)
 - [Multiple tasks ambiguous (`E_TASK_AMBIGUOUS`)](#symptom-multiple-tasks-ambiguous)
@@ -27,26 +29,30 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 
 #### What it means
 
-Pre-implementation gates (e.g. `design`, `threat-boundary`) are unsatisfied, missing, or referencing stale files.
+Pre-implementation gates (e.g. `design`, `threat-boundary`) are unsatisfied, missing, or referencing stale files, or the contract contains unresolved blocking decisions. ForgeLoop preserves specific preflight error codes (`E_CONTRACT_UNRESOLVED_DECISION`, `E_CONTRACT_STALE`, `E_ROUTE_STALE`, `E_GATE_UNVERIFIED`) in `reasons` instead of reducing them to generic readiness errors.
 
 #### Likely causes
 
-1. A gate required by an activated guide has no corresponding `.forgeloop/task-state/<taskKey>/gates/<gate>.json` file.
-2. The gate artifact references files whose SHA-256 hashes changed after the gate was satisfied.
-3. Contract `unresolvedDecisions` contains blocking decisions.
+1. A gate required by an activated guide has no corresponding `.forgeloop/task-state/<taskKey>/gates/<gate>.json` file (`E_GATE_UNVERIFIED`).
+2. The gate artifact references files whose SHA-256 hashes changed after the gate was satisfied (`E_GATE_STALE`).
+3. Contract `unresolvedDecisions` contains blocking decisions (`E_CONTRACT_UNRESOLVED_DECISION`).
 
 #### Inspect
 
 ```bash
 forgeloop task-show --task <id> --json
 forgeloop preflight --task <id> --json
+forgeloop next --task <id> --json
 ```
 
 #### Safe recovery
 
 1. If a gate is missing, satisfy required gates or create the gate artifact with status `"satisfied"`.
 2. If an artifact hash changed, update the artifact SHA-256 in the gate file.
-3. Re-run `forgeloop preflight --task <id> --json`.
+3. If `unresolvedDecisions` contains blocking items:
+   - Record settlement guidance with `forgeloop record-decision-criterion --decision="..." --settled-by="..."` to provide context.
+   - Resolve or remove the blocking decision in `contract.json`.
+4. Re-run `forgeloop preflight --task <id> --json`.
 
 #### Do not
 
@@ -77,7 +83,75 @@ forgeloop next --task <id> --json
 
 1. Check the `reasons` field in the `forgeloop next --json` output.
 2. Follow the suggested command in `commands` or `commandSpecs`.
-3. If in `VERIFYING` after a failure, record a hypothesis, apply the fix, and re-run `run-check`.
+3. If in `VERIFYING` after a failure, advance to `DIAGNOSING`, record a diagnosis with `forgeloop record-diagnosis`, and advance to `CORRECTING`.
+
+---
+
+### Symptom: `forgeloop next` returns `RECORD_DIAGNOSIS`
+
+#### What it means
+
+The task is in `DIAGNOSING` phase following a verification failure, but no append-only diagnosis event (`DIAGNOSIS_RECORDED`) has been recorded for the active verification cycle (`E_DIAGNOSIS_REQUIRED`).
+
+#### Likely causes
+
+1. A check failed in `VERIFYING` and the phase was advanced to `DIAGNOSING` without calling `record-diagnosis`.
+2. An attempt was made to advance directly to `CORRECTING` without recording an evidence-backed root cause hypothesis.
+
+#### Inspect
+
+```bash
+forgeloop status --task <id> --json
+forgeloop next --task <id> --json
+```
+
+#### Safe recovery
+
+Record an append-only diagnosis referencing at least one failed or blocked check from the current verification cycle:
+
+```bash
+forgeloop record-diagnosis --task <id> \
+  --hypothesis="Root cause explanation" \
+  --failure-class="VERIFICATION_FAILURE" \
+  --evidence-ref="failed-check-id" \
+  --settled-by="Observable condition that settles the hypothesis" \
+  --next-safe-action="Smallest safe action to address the hypothesis"
+```
+
+Then advance to `CORRECTING`:
+
+```bash
+forgeloop advance --task <id> --to CORRECTING
+```
+
+---
+
+### Symptom: Progress is `STALLED`
+
+#### What it means
+
+Deterministic progress evaluation detected that iterative correction cycles are not advancing (`E_PROGRESS_STALLED`). The latest diagnosis produced `informationGain: NONE` (signal `NO_DIAGNOSTIC_INFORMATION_GAIN`), or a specific contract requirement failed across 3+ verification cycles with an identical diagnosis (`REPEATED_FAILURE_WITH_SAME_DIAGNOSIS`).
+
+#### Likely causes
+
+1. A recorded diagnosis in a new cycle repeated the previous hypothesis with the exact same evidence references (`informationGain: NONE`). Note: technical retries within the *same* cycle are idempotent and do not cause stalls, but repeating in a *new* cycle does.
+2. The same requirement has repeatedly failed across 3 or more verification cycles with unchanged diagnostic hypotheses.
+3. Minor cosmetic changes were made to `settledBy` or `nextSafeAction` without changing the root hypothesis or evidence references.
+
+#### Inspect
+
+```bash
+forgeloop progress --task <id> --json
+forgeloop next --task <id> --json
+```
+
+#### Safe recovery
+
+1. When stalled, `forgeloop next` returns `nextAction: "CHANGE_STRATEGY"` with error code `E_PROGRESS_STALLED`.
+2. Do not repeat the same retry or correction action.
+3. Re-examine the failure evidence from a new angle or gather fresh diagnostic evidence.
+4. Formulate a genuinely new root-cause hypothesis with new evidence references and record it with `forgeloop record-diagnosis`.
+5. Once a diagnosis with positive information gain (`NEW_HYPOTHESIS`, `NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`) is recorded, `forgeloop next` returns `CORRECT` and status returns to `ADVANCING`.
 
 ---
 
@@ -341,5 +415,13 @@ forgeloop next --task <id> --json
 | `E_TASK_SCOPE_CONFLICT` | Task write claims overlap with another non-complete task in the same checkout. | Adjust write claims to non-overlapping paths or run tasks in separate worktrees. |
 | `E_TASK_SCOPE_DIRTY` | Claimed paths contain pre-existing uncommitted changes. | Commit or stash changes in claimed paths before defining or adopting the scope. |
 | `E_TASK_CHANGE_OUTSIDE_SCOPE` | Modified paths in repository exceed the declared task write claims. | Update write claims with forgeloop task-scope or revert out-of-scope modifications. |
+| `E_DIAGNOSIS_REQUIRED` | Current correction cycle has no append-only diagnosis record. | Run forgeloop record-diagnosis with current failed evidence before correcting. |
+| `E_DIAGNOSIS_INVALID` | Diagnosis record details or parameters are malformed. | Provide valid failureClass, hypothesis, evidenceRefs, settledBy, and nextSafeAction. |
+| `E_DIAGNOSIS_EVIDENCE_INVALID` | Referenced diagnosis evidence is missing or has no failed checks in the current cycle. | Reference at least one failed or blocked check ID from the active verification cycle. |
+| `E_DIAGNOSIS_CYCLE_MISMATCH` | Diagnosis verification cycle does not match the active work state verification cycle. | Record diagnosis for the current active verification cycle. |
+| `E_DIAGNOSIS_NO_NEW_INFORMATION` | The proposed retry repeats the previous hypothesis with the same evidence. | Change the hypothesis, collect independent evidence, or change strategy. |
+| `E_PROGRESS_STALLED` | Persisted correction history shows no new diagnostic information. | Use an independent check, revisit assumptions, or record a materially different diagnosis. |
+| `E_DECISION_CRITERION_INVALID` | Decision settlement criterion details or parameters are malformed. | Provide non-empty decision text and settledBy criterion. |
+| `E_DECISION_NOT_UNRESOLVED` | A settlement criterion referenced a decision not present in current unresolvedDecisions. | Use the exact current unresolved decision text or update the contract first. |
 
 <!-- END FORGELOOP GENERATED: public-error-codes -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -26,6 +26,9 @@ import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/
 import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
 import { formatRunCheckResult, runCheck } from "./commands/run-check.js";
 import { formatRecordTerminalResult, runRecordTerminalResult } from "./commands/record-terminal-result.js";
+import { formatRecordDiagnosisResult, runRecordDiagnosis } from "./commands/record-diagnosis.js";
+import { formatProgressResult, runProgress } from "./commands/progress.js";
+import { formatRecordDecisionCriterionResult, runRecordDecisionCriterion } from "./commands/record-decision-criterion.js";
 import { formatNextActionResult, runNext } from "./commands/next.js";
 import { formatContinuityResult, runContinuity } from "./commands/continuity.js";
 import { formatRecordContinuityResult, runRecordContinuity } from "./commands/record-continuity.js";
@@ -500,6 +503,36 @@ export const COMMAND_HANDLERS = Object.freeze({
     console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordTerminalResult(result));
     return 0;
   },
+  "record-diagnosis": async ({ target, packageRoot, options }) => {
+    const result = await runRecordDiagnosis({
+      target,
+      packageRoot,
+      hypothesis: options.hypothesis,
+      failureClass: options.failureClass,
+      evidenceRefs: options.evidenceRefs,
+      settledBy: options.settledBy,
+      nextSafeAction: options.nextSafeAction,
+      taskId: options.task,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordDiagnosisResult(result));
+    return 0;
+  },
+  progress: async ({ target, packageRoot, options }) => {
+    const result = await runProgress({ target, packageRoot, taskId: options.task });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatProgressResult(result));
+    return result.status === "STALLED" ? 1 : 0;
+  },
+  "record-decision-criterion": async ({ target, packageRoot, options }) => {
+    const result = await runRecordDecisionCriterion({
+      target,
+      packageRoot,
+      decision: options.decision,
+      settledBy: options.settledBy,
+      taskId: options.task,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordDecisionCriterionResult(result));
+    return 0;
+  },
   complete: async ({ target, packageRoot, options }) => {
     const result = await runComplete({ target, packageRoot, strict: options.strict, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));

package/src/commands/next.js

@@ -14,7 +14,21 @@ export function formatNextActionResult(result) {
   ];
   if (result.reasons.length > 0) {
     lines.push("REASONS:");
-    lines.push(...result.reasons.map((reason) => `- ${reason.code}: ${reason.message}`));
+    for (const reason of result.reasons) {
+      lines.push(`- ${reason.code}: ${reason.message}`);
+      if (reason.resolution?.kind === "SETTLEMENT_CRITERION" && reason.resolution.settledBy) {
+        lines.push(`  SETTLED BY: ${reason.resolution.settledBy}`);
+      } else if (reason.resolution?.kind === "SETTLEMENT_CRITERIA" && Array.isArray(reason.resolution.items)) {
+        lines.push("  SETTLEMENT CRITERIA:");
+        for (const item of reason.resolution.items) {
+          lines.push(`  - ${item.decision}`);
+          lines.push(`    SETTLED BY: ${item.settledBy}`);
+        }
+      }
+    }
+  }
+  if (result.progress) {
+    lines.push(`PROGRESS: ${result.progress.status}`);
   }
   if (result.commands.length > 0) {
     lines.push("COMMANDS (SAFE SYNOPSIS ONLY):");

package/src/commands/progress.js

@@ -0,0 +1,51 @@
+import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
+import { readEvents } from "../core/events.js";
+import { readWorkState } from "../core/work-state.js";
+import { resolveTaskContext } from "../core/task-context.js";
+
+export { evaluateProgress };
+
+export async function runProgress({ target, packageRoot, taskId, task }) {
+  const resolved = await resolveTaskContext(target, { packageRoot, explicitTaskId: taskId ?? task });
+  const activeTaskId = resolved.taskId;
+
+  const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
+  const events = await readEvents(target, packageRoot, { taskId: activeTaskId });
+
+  const progress = evaluateProgress({ state, events });
+  return {
+    taskId: activeTaskId ?? state?.taskId ?? "unknown",
+    phase: state?.phase ?? "UNKNOWN",
+    verificationCycle: state?.verificationCycle ?? 1,
+    ...progress,
+  };
+}
+
+export function formatProgressResult(result) {
+  const lines = [
+    `FORGELOOP PROGRESS: ${result.status}`,
+    `PHASE: ${result.phase}`,
+    `CYCLE: ${result.verificationCycle}`,
+  ];
+
+  if (result.signals && result.signals.length > 0) {
+    lines.push("SIGNALS:");
+    for (const signal of result.signals) {
+      lines.push(`- ${signal.code}: ${signal.message}`);
+    }
+  } else {
+    lines.push("SIGNALS: none");
+  }
+
+  let recommended = "NONE";
+  if (result.status === PROGRESS_STATUS.STALLED) {
+    recommended = "CHANGE_STRATEGY";
+  } else if (result.status === PROGRESS_STATUS.WATCH) {
+    recommended = "REVIEW_CHECKS";
+  } else {
+    recommended = "ADVANCE";
+  }
+  lines.push(`RECOMMENDED: ${recommended}`);
+
+  return lines.join("\n") + "\n";
+}

package/src/commands/record-decision-criterion.js

@@ -0,0 +1,34 @@
+import { recordDecisionCriterion } from "../core/settlement.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordDecisionCriterion };
+
+export async function runRecordDecisionCriterion({
+  target,
+  packageRoot,
+  decision,
+  settledBy,
+  taskId,
+  task,
+}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-decision-criterion", async (ctx) => {
+    return recordDecisionCriterion({
+      target,
+      packageRoot,
+      decision,
+      settledBy,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordDecisionCriterionResult(result) {
+  const c = result.criterion ?? result.event?.details ?? {};
+  return [
+    `FORGELOOP DECISION CRITERION RECORDED`,
+    `DECISION: ${c.decision}`,
+    `DECISION ID: ${c.decisionId}`,
+    `SETTLED BY: ${c.settledBy}`,
+    `CONTRACT FINGERPRINT: ${c.contractFingerprint}`,
+  ].join("\n") + "\n";
+}

package/src/commands/record-diagnosis.js

@@ -0,0 +1,49 @@
+import { recordDiagnosis } from "../core/diagnosis.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordDiagnosis };
+
+export async function runRecordDiagnosis({
+  target,
+  packageRoot,
+  hypothesis,
+  failureClass,
+  evidenceRefs = [],
+  evidenceRef = null,
+  settledBy,
+  nextSafeAction,
+  taskId,
+  task,
+}) {
+  const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
+    ? evidenceRefs
+    : (evidenceRef ? [evidenceRef] : []);
+
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-diagnosis", async (ctx) => {
+    return recordDiagnosis({
+      target,
+      packageRoot,
+      hypothesis,
+      failureClass,
+      evidenceRefs: refs,
+      settledBy,
+      nextSafeAction,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordDiagnosisResult(result) {
+  const d = result.diagnosis ?? result.event?.details ?? {};
+  return [
+    `FORGELOOP DIAGNOSIS RECORDED`,
+    `CYCLE: ${d.verificationCycle}`,
+    `FAILURE CLASS: ${d.failureClass}`,
+    `HYPOTHESIS: ${d.hypothesis}`,
+    `INFORMATION GAIN: ${d.informationGain}`,
+    `EVIDENCE: ${(d.evidenceRefs ?? []).join(", ")}`,
+    `SETTLED BY: ${d.settledBy}`,
+    `NEXT SAFE ACTION: ${d.nextSafeAction}`,
+    `FINGERPRINT: ${d.diagnosisFingerprint}`,
+  ].join("\n") + "\n";
+}

package/src/core/cli-command-definitions.js

@@ -1,5 +1,5 @@
 /**
- * Canonical, declarative definition of all 33 ForgeLoop CLI commands.
+ * Canonical, declarative definition of all 36 ForgeLoop CLI commands.
  * This is the machine source of truth for CLI option parsing, help text,
  * metadata, documentation generation, and conformance validation.
  *
@@ -317,6 +317,55 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Records external terminal result evidence (PUBLICATION or PRODUCTION_READINESS) into receipt.",
   }),
+  "record-diagnosis": Object.freeze({
+    name: "record-diagnosis",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--hypothesis": Object.freeze({ targetKey: "hypothesis", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--hypothesis requires text", description: "specific root-cause hypothesis explaining the verification failure" }),
+      "--failure-class": Object.freeze({ targetKey: "failureClass", parseType: "string", takesValue: true, valueName: "class", missingValueMessage: "--failure-class requires a class", description: "canonical failure class taxonomy" }),
+      "--evidence-ref": Object.freeze({ targetKey: "evidenceRefs", parseType: "string", takesValue: true, valueName: "check-id", repeatable: true, missingValueMessage: "--evidence-ref requires a check ID", description: "reference to failed/blocked check from current cycle" }),
+      "--settled-by": Object.freeze({ targetKey: "settledBy", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--settled-by requires text", description: "falsification or settlement criteria for the hypothesis" }),
+      "--next-safe-action": Object.freeze({ targetKey: "nextSafeAction", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--next-safe-action requires text", description: "smallest safe action to address the hypothesis" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson", ".forgeloop/task-state/<taskKey>/work-state.json"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an append-only diagnosis event in the lifecycle event ledger for the active cycle.",
+  }),
+  progress: Object.freeze({
+    name: "progress",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit progress evaluation as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Evaluates task progress across verification cycles and detects stalls deterministically.",
+  }),
+  "record-decision-criterion": Object.freeze({
+    name: "record-decision-criterion",
+    category: "lifecycle",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--decision": Object.freeze({ targetKey: "decision", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--decision requires text", description: "unresolved decision text matching current contract" }),
+      "--settled-by": Object.freeze({ targetKey: "settledBy", parseType: "string", takesValue: true, valueName: "text", missingValueMessage: "--settled-by requires text", description: "criteria or guidance that settles the decision" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Records an append-only decision settlement criterion bound to the active contract fingerprint.",
+  }),
   complete: Object.freeze({
     name: "complete",
     category: "lifecycle",

package/src/core/diagnosis-model.js

@@ -0,0 +1,214 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { assertFailureClass } from "./protocol.js";
+
+export const DIAGNOSIS_INFORMATION_GAIN = Object.freeze([
+  "FIRST_DIAGNOSIS",
+  "NEW_HYPOTHESIS",
+  "NEW_EVIDENCE",
+  "NEW_HYPOTHESIS_AND_EVIDENCE",
+  "NONE",
+]);
+
+export function normalizeDiagnosisText(value, label = "value") {
+  if (typeof value !== "string" || !value.trim()) {
+    const error = new Error(`${label} must be a non-empty string`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+
+export function diagnosisFingerprint({ failureClass, hypothesis, evidenceRefs }) {
+  assertFailureClass(failureClass);
+  const normalizedHypothesis = normalizeDiagnosisText(hypothesis, "hypothesis");
+  if (!Array.isArray(evidenceRefs) || evidenceRefs.length === 0) {
+    const error = new Error("evidenceRefs must be a non-empty array of strings");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const cleanRefs = evidenceRefs.map((ref) => {
+    if (typeof ref !== "string" || !ref.trim()) {
+      const error = new Error("evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+    return ref.trim();
+  });
+  const normalizedRefs = [...new Set(cleanRefs)].sort();
+  return canonicalFingerprint({
+    failureClass,
+    hypothesis: normalizedHypothesis,
+    evidenceRefs: normalizedRefs,
+  });
+}
+
+export function classifyDiagnosisInformationGain(current, previous) {
+  if (!previous) return "FIRST_DIAGNOSIS";
+
+  const currentHypothesis = normalizeDiagnosisText(current.hypothesis, "current hypothesis");
+  const prevHypothesis = normalizeDiagnosisText(previous.hypothesis, "previous hypothesis");
+  const sameHypothesis = currentHypothesis === prevHypothesis;
+
+  const currentEvidence = [...new Set((current.evidenceRefs ?? []).map((r) => String(r).trim()))].sort();
+  const prevEvidence = [...new Set((previous.evidenceRefs ?? []).map((r) => String(r).trim()))].sort();
+  const sameEvidence = JSON.stringify(currentEvidence) === JSON.stringify(prevEvidence);
+
+  if (sameHypothesis && sameEvidence) return "NONE";
+  if (!sameHypothesis && !sameEvidence) return "NEW_HYPOTHESIS_AND_EVIDENCE";
+  if (!sameHypothesis) return "NEW_HYPOTHESIS";
+  return "NEW_EVIDENCE";
+}
+
+export function createDiagnosisDetails(input, previous = null) {
+  if (typeof input?.verificationCycle !== "number" || !Number.isInteger(input.verificationCycle) || input.verificationCycle < 1) {
+    const error = new Error("verificationCycle must be an integer >= 1");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  try {
+    assertFailureClass(input.failureClass);
+  } catch {
+    const error = new Error(`Invalid failureClass: ${input.failureClass}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof input.hypothesis !== "string" || !input.hypothesis.trim()) {
+    const error = new Error("hypothesis must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!Array.isArray(input.evidenceRefs) || input.evidenceRefs.length === 0) {
+    const error = new Error("evidenceRefs must be a non-empty array");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const cleanRefs = input.evidenceRefs.map((r) => {
+    if (typeof r !== "string" || !r.trim()) {
+      const error = new Error("each evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+    return r.trim();
+  });
+  const uniqueRefs = [...new Set(cleanRefs)].sort();
+  if (typeof input.settledBy !== "string" || !input.settledBy.trim()) {
+    const error = new Error("settledBy must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof input.nextSafeAction !== "string" || !input.nextSafeAction.trim()) {
+    const error = new Error("nextSafeAction must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+
+  const fingerprint = diagnosisFingerprint({
+    failureClass: input.failureClass,
+    hypothesis: input.hypothesis,
+    evidenceRefs: uniqueRefs,
+  });
+  const infoGain = classifyDiagnosisInformationGain(
+    { hypothesis: input.hypothesis, evidenceRefs: uniqueRefs },
+    previous ? { hypothesis: previous.hypothesis, evidenceRefs: previous.evidenceRefs } : null,
+  );
+
+  return {
+    verificationCycle: input.verificationCycle,
+    failureClass: input.failureClass,
+    hypothesis: input.hypothesis.trim(),
+    evidenceRefs: uniqueRefs,
+    settledBy: input.settledBy.trim(),
+    nextSafeAction: input.nextSafeAction.trim(),
+    diagnosisFingerprint: fingerprint,
+    informationGain: infoGain,
+    previousDiagnosisFingerprint: previous?.diagnosisFingerprint ?? null,
+  };
+}
+
+export function assertDiagnosisDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    const error = new Error("Diagnosis details must be an object");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.verificationCycle !== "number" || !Number.isInteger(details.verificationCycle) || details.verificationCycle < 1) {
+    const error = new Error("Diagnosis verificationCycle must be an integer >= 1");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  try {
+    assertFailureClass(details.failureClass);
+  } catch {
+    const error = new Error(`Invalid diagnosis failureClass: ${details.failureClass}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.hypothesis !== "string" || !details.hypothesis.trim()) {
+    const error = new Error("Diagnosis hypothesis must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!Array.isArray(details.evidenceRefs) || details.evidenceRefs.length === 0) {
+    const error = new Error("Diagnosis evidenceRefs must be a non-empty array");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  for (const ref of details.evidenceRefs) {
+    if (typeof ref !== "string" || !ref.trim()) {
+      const error = new Error("Diagnosis evidenceRef must be a non-empty string");
+      error.code = "E_DIAGNOSIS_INVALID";
+      throw error;
+    }
+  }
+  if (typeof details.settledBy !== "string" || !details.settledBy.trim()) {
+    const error = new Error("Diagnosis settledBy must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.nextSafeAction !== "string" || !details.nextSafeAction.trim()) {
+    const error = new Error("Diagnosis nextSafeAction must be a non-empty string");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (!DIAGNOSIS_INFORMATION_GAIN.includes(details.informationGain)) {
+    const error = new Error(`Invalid diagnosis informationGain: ${details.informationGain}`);
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (typeof details.diagnosisFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.diagnosisFingerprint)) {
+    const error = new Error("Invalid diagnosisFingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  const computed = diagnosisFingerprint({
+    failureClass: details.failureClass,
+    hypothesis: details.hypothesis,
+    evidenceRefs: details.evidenceRefs,
+  });
+  if (computed !== details.diagnosisFingerprint) {
+    const error = new Error("Diagnosis fingerprint does not match computed fingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  if (details.previousDiagnosisFingerprint !== null && (typeof details.previousDiagnosisFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.previousDiagnosisFingerprint))) {
+    const error = new Error("Invalid previousDiagnosisFingerprint");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function diagnosisEventsForTask(events, taskId) {
+  if (!Array.isArray(events)) return [];
+  return events.filter((e) => e.event === "DIAGNOSIS_RECORDED" && (!taskId || e.taskId === taskId));
+}
+
+export function currentCycleDiagnosis(events, taskId, verificationCycle) {
+  const taskEvents = diagnosisEventsForTask(events, taskId);
+  for (let i = taskEvents.length - 1; i >= 0; i--) {
+    if (taskEvents[i].details?.verificationCycle === verificationCycle) {
+      return taskEvents[i];
+    }
+  }
+  return null;
+}