@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/semantic-planning/projection.js

@@ -0,0 +1,94 @@
+import { FAILURE_CLASSES, DIAGNOSIS_STRATEGIES, REVIEW_FOCUSES } from "./constants.js";
+
+function strings(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()) : [];
+}
+
+function text(input) {
+  return [input?.message, input?.error, input?.failure, input?.objective, ...(input?.paths ?? []), ...(input?.risks ?? [])]
+    .filter((value) => typeof value === "string").join(" ").toLowerCase();
+}
+
+function unique(values) { return [...new Set(values)]; }
+
+function validateRecommendation(recommendation, allowed, label) {
+  if (recommendation === undefined || recommendation === null) return null;
+  const values = typeof recommendation === "string" ? [recommendation]
+    : recommendation && typeof recommendation === "object" && !Array.isArray(recommendation)
+      ? Object.entries(recommendation).filter(([, value]) => value === true).map(([key]) => key)
+      : strings(recommendation);
+  const unknown = values.filter((value) => !allowed.includes(value));
+  if (unknown.length > 0) {
+    const error = new Error(`${label} contains unknown semantic values: ${unknown.join(", ")}`);
+    error.code = "E_DECISION_RESULT_INVALID";
+    throw error;
+  }
+  return unique(values);
+}
+
+export function projectFailureTriage({ input = {}, semanticRecommendation = null } = {}) {
+  const candidate = semanticRecommendation?.failureClass ?? semanticRecommendation;
+  const value = validateRecommendation(candidate, FAILURE_CLASSES, "failure recommendation");
+  const inferred = /timeout|timed out/.test(text(input)) ? "timeout"
+    : /network|dns|connection|environment/.test(text(input)) ? "network/environment"
+      : /ownership|protocol|ledger|phase/.test(text(input)) ? "ownership/protocol mismatch"
+        : "unknown";
+  return {
+    decisionKind: "FAILURE_TRIAGE",
+    questionSetId: "failure-v1",
+    candidates: [...FAILURE_CLASSES],
+    ranked: unique([...(value ?? []), inferred]),
+    semanticRequired: true,
+    unknownEscalates: !value,
+    authority: "SEMANTIC_DECISION",
+    evidenceAuthority: "NONE",
+  };
+}
+
+export function projectDiagnosisPriority({ input = {}, semanticRecommendation = null } = {}) {
+  const candidate = semanticRecommendation?.priority ?? semanticRecommendation;
+  const value = validateRecommendation(candidate, DIAGNOSIS_STRATEGIES, "diagnosis recommendation");
+  const inferred = /race|concurr|lock/.test(text(input)) ? "inspect concurrency path"
+    : /state|ledger|phase|fingerprint/.test(text(input)) ? "inspect state transition"
+      : /depend|package|module/.test(text(input)) ? "inspect dependency behavior"
+        : "run narrower experiment";
+  return {
+    decisionKind: "DIAGNOSIS_PRIORITY",
+    questionSetId: "diagnosis-v1",
+    candidates: [...DIAGNOSIS_STRATEGIES],
+    ranked: unique([...(value ?? []), inferred]),
+    previouslyFailed: strings(input.previouslyFailed),
+    semanticRequired: true,
+    unknownEscalates: !value,
+    authority: "SEMANTIC_DECISION",
+    evidenceAuthority: "NONE",
+  };
+}
+
+export function projectReviewPlan({ input = {}, semanticRecommendation = null } = {}) {
+  const candidate = semanticRecommendation?.reviewFocus ?? semanticRecommendation;
+  const value = validateRecommendation(candidate, REVIEW_FOCUSES, "review recommendation");
+  const body = text(input);
+  const mandatory = ["needs_full_diff_context"];
+  if (/security|secret|credential|auth|permission/.test(body)) mandatory.push("needs_security_review");
+  if (/api|public|compatib/.test(body)) mandatory.push("needs_api_compatibility_review");
+  if (/race|concurr|lock/.test(body)) mandatory.push("needs_concurrency_review");
+  if (/package|release|dependency/.test(body)) mandatory.push("needs_package_review", "needs_dependency_review");
+  if (/doc|readme|guide/.test(body)) mandatory.push("needs_docs_review");
+  if (/migration|schema|database/.test(body)) mandatory.push("needs_migration_review");
+  if (/performance|timeout|latency/.test(body)) mandatory.push("needs_performance_review");
+  if (input.fullDiff === true || body.includes("full diff")) mandatory.push("needs_full_diff_context");
+  const ranked = unique([...mandatory, ...(value ?? [])]);
+  if (ranked.length === 0) ranked.push("needs_full_diff_context");
+  if (input.primaryModel === true || input.ambiguity === true) ranked.push("needs_primary_model");
+  return {
+    decisionKind: "REVIEW_PLAN",
+    questionSetId: "review-v1",
+    mandatory: unique(mandatory),
+    ranked: unique(ranked),
+    semanticRequired: true,
+    unknownEscalates: !value,
+    authority: "SEMANTIC_DECISION",
+    evidenceAuthority: "NONE",
+  };
+}

package/src/core/semantic-planning/service.js

@@ -0,0 +1,15 @@
+import { DECISION_ERROR_CODES, decisionError } from "../decision/errors.js";
+import { projectDiagnosisPriority, projectFailureTriage, projectReviewPlan } from "./projection.js";
+
+const PROJECTORS = Object.freeze({
+  failure: projectFailureTriage,
+  diagnosis: projectDiagnosisPriority,
+  review: projectReviewPlan,
+});
+
+export function runSemanticPlan({ kind, input = {}, semanticRecommendation = null } = {}) {
+  const projector = PROJECTORS[kind];
+  if (!projector) throw decisionError(DECISION_ERROR_CODES.QUESTION_SET_UNKNOWN, `Unknown semantic plan kind: ${kind}`);
+  return projector({ input, semanticRecommendation });
+}
+

package/src/core/sources.js

@@ -1,5 +1,19 @@
+import { CONTRACT_PRESET_IDS } from "./contract-presets.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 
+const CONTRACT_PRESET_PREFIX = "contract-preset:";
+const BUILTIN_CONTRACT_PRESET_REFS = new Set(
+  CONTRACT_PRESET_IDS.map((presetId) => `${CONTRACT_PRESET_PREFIX}${presetId}`),
+);
+
+export function isBuiltinContractPresetRef(ref) {
+  return typeof ref === "string" && BUILTIN_CONTRACT_PRESET_REFS.has(ref);
+}
+
+export function externalContractSourceRefs(refs = []) {
+  return refs.filter((ref) => !isBuiltinContractPresetRef(ref));
+}
+
 export const SOURCE_REGISTRY_SCHEMA_VERSION = 1;
 export const SOURCE_KINDS = Object.freeze([
   "user-request",
@@ -84,3 +98,26 @@ export function assertSourceProvenance(registry, refs = [], { expectedKind } = {
   }
   return true;
 }
+
+export function assertContractPresetRefs(refs = []) {
+  for (const ref of refs) {
+    if (typeof ref === "string" && ref.startsWith(CONTRACT_PRESET_PREFIX) && !isBuiltinContractPresetRef(ref)) {
+      const error = new Error(`Unknown built-in contract preset source: ${ref}`);
+      error.code = "E_PROFILE_SOURCE_UNKNOWN";
+      throw error;
+    }
+  }
+  return true;
+}
+
+export function assertContractSourceProvenance(registry, refs = []) {
+  assertContractPresetRefs(refs);
+  const externalRefs = externalContractSourceRefs(refs);
+  if (externalRefs.length === 0) return true;
+  if (!registry) {
+    const error = new Error("External contract source references require a source registry");
+    error.code = "E_PROFILE_SOURCE_MISSING";
+    throw error;
+  }
+  return assertSourceProvenance(registry, externalRefs);
+}

package/src/core/task-claim-state.js

@@ -6,7 +6,7 @@ import {
   E_TASK_RECOVERY_INCONSISTENT,
 } from "./error-codes.js";
 import { validateCompletionOwnershipProof } from "./completion-ownership.js";
-import { validateEventLedger } from "./events.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { classifyRecoveryHistory } from "./recovery-history.js";
 import { readTaskDescriptor } from "./task-descriptor.js";
 import { normalizeWriteClaims } from "./task-scope.js";
@@ -15,6 +15,35 @@ import {
   validateTaskRecoveryConsistency,
 } from "./task-recovery.js";
 import { readWorkState } from "./work-state.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  resolveEffectiveContractBootstrapRepairAnchor,
+  resolveCanonicalPostRepairCheckpointBinding,
+  resolveCanonicalPostRepairRouteBinding,
+  sameCanonicalGuideList,
+} from "./contract-bootstrap-recovery.js";
+import { canonicalFingerprint } from "./artifacts.js";
+import { stateIdentityErrors } from "./completion-relationships.js";
+import { routeCheckpointMustMatchCurrentRoute } from "./resumability.js";
+
+const REPAIR_PHASE_EVENTS = Object.freeze({
+  CONTRACT_READY: "CONTRACT_VALIDATED",
+  ROUTED: "ROUTE_VALIDATED",
+  DESIGNING: "DESIGN_GATE_STARTED",
+  PLANNED: "PLAN_RECORDED",
+  EXECUTING: "EXECUTION_STARTED",
+  VERIFYING: "VERIFICATION_STARTED",
+  DIAGNOSING: "VERIFICATION_STARTED",
+  CORRECTING: "VERIFICATION_STARTED",
+  REVIEWING: "REVIEW_STARTED",
+  COMPLETE: "COMPLETION_VALIDATED",
+});
+
+const REPAIR_ROUTE_PHASES = new Set([
+  "ROUTED", "DESIGNING", "PLANNED", "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING", "COMPLETE",
+]);
 
 function ownershipError(message, cause = null) {
   return {
@@ -24,6 +53,164 @@ function ownershipError(message, cause = null) {
   };
 }
 
+function repairInvalid(message) {
+  return ownershipError(message, { code: "E_CONTRACT_BOOTSTRAP_REPAIR_INVALID" });
+}
+
+function lateRouteCheckpointErrors(events, state, marker) {
+  if (routeCheckpointMustMatchCurrentRoute(state.phase) || !REPAIR_PHASE_EVENTS[state.phase]) return [];
+  const checkpoint = resolveCanonicalPostRepairCheckpointBinding(events, marker);
+  if (!checkpoint) {
+    return [repairInvalid("Repaired late-phase state lacks an immutable route checkpoint binding")];
+  }
+  if (state.routeFingerprint !== checkpoint.routeFingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, checkpoint.selectedGuides)) {
+    return [repairInvalid("Late-phase checkpoint route identity was rewritten after the canonical checkpoint binding")];
+  }
+  return [];
+}
+
+function repairArtifactErrors(artifacts) {
+  return [
+    ...(artifacts?.contractError
+      ? [repairInvalid(`Current contract artifact is invalid after a recorded repair: ${artifacts.contractError}`)]
+      : []),
+    ...(artifacts?.routeError
+      ? [repairInvalid(`Current route artifact is invalid after a recorded repair: ${artifacts.routeError}`)]
+      : []),
+  ];
+}
+
+function repairAnchorErrors(details, state, artifacts) {
+  const errors = [];
+  if (state.phase !== details.reconstructedPhase) {
+    errors.push(repairInvalid(
+      `Work-state phase ${state.phase} does not match repair anchor phase ${details.reconstructedPhase}`,
+    ));
+  }
+  if (canonicalFingerprint(state) !== details.reconstructedStateFingerprint) {
+    errors.push(repairInvalid("Work-state fingerprint does not match the repair anchor"));
+  }
+  const stateRouteFingerprint = state.routeFingerprint ?? null;
+  const currentRouteFingerprint = artifacts?.route?.fingerprint ?? null;
+  if (stateRouteFingerprint !== details.routeFingerprint
+    || currentRouteFingerprint !== details.routeFingerprint) {
+    errors.push(repairInvalid("Current route identity does not match the repair anchor"));
+  }
+  return errors;
+}
+
+function evolvedRepairErrors(anchor, events, state, artifacts) {
+  const errors = [];
+  const contract = artifacts?.contract ?? null;
+  const route = artifacts?.route ?? null;
+  if (!contract) errors.push(repairInvalid("Current contract is unavailable after a recorded repair"));
+  const routeRequired = REPAIR_ROUTE_PHASES.has(state.phase) || state.routeFingerprint !== undefined;
+  if (routeRequired && !route) {
+    errors.push(repairInvalid("Current route is required by the evolved task state but is unavailable"));
+  }
+  if (contract) {
+    const routeErrors = stateIdentityErrors({ contract, route, state });
+    const checkpointMustMatch = routeCheckpointMustMatchCurrentRoute(state.phase);
+    errors.push(...routeErrors
+      .filter((error) => checkpointMustMatch || error.code !== "E_ROUTE_GUIDE_MISMATCH")
+      .map((error) => repairInvalid(error.message)));
+  }
+  const currentRouteFingerprint = route?.fingerprint ?? null;
+  const binding = currentRouteFingerprint !== anchor.details.routeFingerprint
+    ? resolveCanonicalPostRepairRouteBinding(events, anchor.sourceMarker, currentRouteFingerprint)
+    : null;
+  if (currentRouteFingerprint !== anchor.details.routeFingerprint && !binding) {
+    errors.push(repairInvalid("Changed route identity lacks a canonical post-repair route binding"));
+  }
+  errors.push(...lateRouteCheckpointErrors(events, state, anchor.sourceMarker));
+  errors.push(...validateStateLedgerCoherence(state, events).map((error) => repairInvalid(error.message)));
+  const requiredEvent = REPAIR_PHASE_EVENTS[state.phase];
+  if (requiredEvent && !events.some((event) => event.event === requiredEvent)) {
+    errors.push(repairInvalid(`Current work-state phase ${state.phase} is not supported by the repair ledger history`));
+  }
+  return errors;
+}
+
+function validateContractBootstrapRepairConsistency(taskId, events, state, artifacts) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (!anchor) {
+    if (!events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) return [];
+    return [repairInvalid("Contract bootstrap repair marker is invalid")];
+  }
+  if (!state) return [repairInvalid("Work-state is missing after a recorded contract bootstrap repair")];
+  const details = anchor.details;
+  const errors = [];
+  if (state.taskId !== taskId) errors.push(repairInvalid("Work-state taskId does not match the repaired task"));
+  if (!Number.isInteger(state.revision) || state.revision < 0) {
+    return [...errors, repairInvalid("Work-state revision is missing or invalid after a recorded repair")];
+  }
+  const anchorRevision = details.reconstructedStateRevision;
+  if (state.revision < anchorRevision) {
+    return [...errors, repairInvalid("Work-state revision rolled back behind the repair anchor")];
+  }
+  if (state.contractFingerprint !== details.contractFingerprint) {
+    errors.push(repairInvalid("Work-state contract fingerprint does not match repair-time contract identity"));
+  }
+  errors.push(...repairArtifactErrors(artifacts));
+  return state.revision === anchorRevision
+    ? [...errors, ...repairAnchorErrors(details, state, artifacts)]
+    : [...errors, ...evolvedRepairErrors(anchor, events, state, artifacts)];
+}
+
+/**
+ * Async cross-artifact consistency collector for a recorded contract bootstrap
+ * repair. The pure classifier stays filesystem-free; this reads the current
+ * task-scoped contract and route artifacts through their canonical readers so
+ * schema validation, artifact bounds, task-scoped paths, and fingerprint
+ * semantics stay consistent with the rest of the protocol.
+ *
+ * With no repair marker this performs no extra work.
+ */
+async function collectContractBootstrapRepairConsistency(target, packageRoot, taskId, events, state) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (!anchor) return null;
+  const details = anchor.details;
+  const artifacts = { contract: null, route: null, contractError: null, routeError: null };
+
+  // Contract binding: the current contract must exist, validate, and bind to
+  // the marker and work state.
+  try {
+    const contract = await readContract(target, packageRoot, { taskId });
+    artifacts.contract = contract;
+    if (contract.fingerprint !== details.contractFingerprint) {
+      artifacts.contractError = `contract fingerprint ${contract.fingerprint} does not match marker contract fingerprint ${details.contractFingerprint}`;
+    } else if (state && state.contractFingerprint !== details.contractFingerprint) {
+      artifacts.contractError = "work-state contract fingerprint does not match marker contract fingerprint";
+    }
+  } catch (error) {
+    artifacts.contractError = error.code === "ARTIFACT_MISSING"
+      ? "contract artifact is missing after a recorded repair"
+      : `contract artifact is invalid after a recorded repair: ${error.message}`;
+  }
+
+  // Route binding is anchored exactly at repair time, then follows the
+  // current state/route identity after the checkpoint advances.
+  const routeRequired = state && (REPAIR_ROUTE_PHASES.has(state.phase)
+    || state.routeFingerprint !== undefined);
+  if (routeRequired || details.routeFingerprint !== null) {
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId });
+      artifacts.route = route;
+      if (route.value?.contractFingerprint !== undefined
+        && route.value.contractFingerprint !== details.contractFingerprint) {
+        artifacts.routeError = "route artifact contract binding does not match repair anchor contract fingerprint";
+      }
+    } catch (error) {
+      artifacts.routeError = error.code === "ARTIFACT_MISSING"
+        ? "route artifact is missing after a routed repair"
+        : `route artifact is invalid after a routed repair: ${error.message}`;
+    }
+  }
+
+  return artifacts;
+}
+
 function appendClaims(target, claims, errors, source) {
   if (claims === undefined || claims === null) return;
   try {
@@ -85,6 +272,19 @@ export async function collectTaskClaimEvidence(target, {
   if (ledger.events.some((event) => event.taskId !== taskId)) {
     errors.push(ownershipError(`Task event ledger contains an event for a different task`));
   }
+  if (state) {
+    for (const error of validateStateLedgerCoherence(state, ledger.events)) {
+      if (![
+        "E_CHECKPOINT_REVALIDATION_UNSAFE",
+        "E_CONTRACT_REVISION_UNSAFE",
+      ].includes(error.code)) continue;
+      errors.push(ownershipError(`Task state and event ledger are incoherent: ${error.message}`, error));
+    }
+  }
+
+  const repairArtifacts = await collectContractBootstrapRepairConsistency(target, packageRoot, taskId, ledger.events, state);
+  const repairConsistencyErrors = validateContractBootstrapRepairConsistency(taskId, ledger.events, state, repairArtifacts);
+  errors.push(...repairConsistencyErrors);
 
   const history = classifyRecoveryHistory(ledger.events);
   const descriptorClaims = [];

package/src/core/task-conflict-inspection.js

@@ -64,6 +64,27 @@ function lastMeaningfulActivity(state, events) {
   return candidates.sort((left, right) => Date.parse(right.at) - Date.parse(left.at))[0] ?? null;
 }
 
+function isInitialTaskLedger(events, taskId) {
+  return events.length >= 2
+    && events[0]?.taskId === taskId
+    && events[0]?.event === "TASK_RECEIVED"
+    && events[1]?.taskId === taskId
+    && events[1]?.event === "TRANSACTION_COMMITTED"
+    && events[1]?.details?.operation === "task-create"
+    && !events.slice(2).some((event) => [
+      "CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY", "EXECUTION_STARTED",
+      "VERIFICATION_STARTED", "VERIFICATION_RECORDED", "REVIEW_STARTED", "COMPLETION_VALIDATED",
+      "TASK_RECOVERY_RECORDED", "OPERATOR_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED",
+    ].includes(event.event));
+}
+
+function deriveEarlyPhase(events, taskId) {
+  if (!isInitialTaskLedger(events, taskId)) return null;
+  return events.some((event) => event.event === "DISCOVERY_STARTED")
+    ? "DISCOVERING"
+    : "RECEIVED";
+}
+
 /**
  * Deterministic classification of a potentially conflicting task from
  * machine-readable state only. REVIEWING plus an old timestamp alone is never
@@ -97,6 +118,7 @@ export function classifyConflictEvidence(evidence, {
     totalChecks,
     verificationEvidenceCount,
     recoveryStatus,
+    earlyPhase,
   } = evidence;
 
   if (!ledgerValid) {
@@ -110,7 +132,8 @@ export function classifyConflictEvidence(evidence, {
     "RECEIVED", "DISCOVERING", "CONTRACT_READY", "ROUTED", "DESIGNING", "PLANNED",
     ...POST_EXECUTION_PHASES,
   ]);
-  if (!phase || !KNOWN_PHASES.has(phase)) {
+  const effectivePhase = phase ?? earlyPhase;
+  if (!effectivePhase || !KNOWN_PHASES.has(effectivePhase)) {
     return {
       classification: "INCONSISTENT",
       reasonCodes: ["E_PHASE_UNKNOWN"],
@@ -151,7 +174,7 @@ export function classifyConflictEvidence(evidence, {
     };
   }
 
-  if (phase === "COMPLETE") {
+  if (effectivePhase === "COMPLETE") {
     return {
       classification: "COMPLETE",
       reasonCodes: ["TASK_COMPLETE"],
@@ -175,7 +198,7 @@ export function classifyConflictEvidence(evidence, {
     };
   }
 
-  if (POST_EXECUTION_PHASES.has(phase)) {
+  if (POST_EXECUTION_PHASES.has(effectivePhase)) {
     if (staleOnlyRepositoryDrift) {
       return {
         classification: "RECOVERABLE",
@@ -262,6 +285,9 @@ export async function inspectTaskConflictState(target, {
   const ledgerErrors = [...ownershipEvidence.ledger.errors, ...coherenceErrors];
 
   const repository = await currentRepositoryFingerprint(target);
+  const initialTask = !state && ledgerValid && ownershipEvidence.descriptor
+    && isInitialTaskLedger(ledgerEvents, taskId)
+    && !ownershipEvidence.recovery;
   const meaningfulActivity = lastMeaningfulActivity(state, ledgerEvents);
   const recoveryConsistencyErrors = claimProjection.ownershipErrors ?? claimProjection.errors ?? [];
   const healthReasonCodes = [
@@ -275,7 +301,7 @@ export async function inspectTaskConflictState(target, {
     healthy: healthReasonCodes.length === 0,
     healthReasonCodes,
     descriptorHealthy: true,
-    phase: state?.phase ?? null,
+    phase: state?.phase ?? (initialTask ? deriveEarlyPhase(ledgerEvents, taskId) : null),
     lastUpdated: state?.lastUpdated ?? null,
     lastMeaningfulActivityAt: meaningfulActivity?.at ?? null,
     lastMeaningfulEventType: meaningfulActivity?.type ?? null,
@@ -283,7 +309,7 @@ export async function inspectTaskConflictState(target, {
     lockStatus: lockClassification.status,
     lockId: lockInfo?.lockId ?? null,
     lockExpiresAt: lockClassification.expiresAt ?? null,
-    freshnessStatus: freshness?.status ?? "UNKNOWN",
+    freshnessStatus: freshness?.status ?? (initialTask ? "FRESH" : "UNKNOWN"),
     freshnessReasons: freshness?.reasons ?? [],
     ledgerValid,
     ledgerLastSeq: ledgerEvents.at(-1)?.seq ?? 0,

package/src/core/task-paths.js

@@ -27,6 +27,8 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   verificationScope: "verification-scope.json",
   attestations: "attestations",
   structuralQuality: "structural-quality",
+  decisions: "decisions",
+  testUtility: "test-utility.json",
 });
 
 export const POLICY_ROOT = ".forgeloop/policy";
@@ -106,6 +108,15 @@ export function taskEvaluationPath(taskId, evaluationId) {
   return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.evaluations}/${evaluationId}.json`;
 }
 
+export function taskDecisionDirectory(taskId) {
+  return taskArtifactPath(taskId, "decisions");
+}
+
+export function taskDecisionPath(taskId, decisionId) {
+  assertArtifactId(decisionId, /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/, "decision ID");
+  return `${taskDecisionDirectory(taskId)}/${decisionId}.json`;
+}
+
 function assertArtifactId(value, pattern, label) {
   if (typeof value !== "string" || !pattern.test(value)) {
     throw new Error(`Invalid ${label}: ${value}`);
@@ -217,6 +228,8 @@ export function buildTaskArtifactPaths(taskId) {
     actions: `${dir}/${TASK_ARTIFACT_FILES.actions}`,
     approvals: `${dir}/${TASK_ARTIFACT_FILES.approvals}`,
     evaluations: `${dir}/${TASK_ARTIFACT_FILES.evaluations}`,
+    decisions: `${dir}/${TASK_ARTIFACT_FILES.decisions}`,
+    testUtility: `${dir}/${TASK_ARTIFACT_FILES.testUtility}`,
     usage: `${dir}/${TASK_ARTIFACT_FILES.usage}`,
     lock: taskLockPath(taskId),
     policySnapshot: `${dir}/${TASK_ARTIFACT_FILES.policySnapshot}`,

package/src/core/task-recovery.js

@@ -12,6 +12,7 @@ export const TASK_RECOVERY_SCHEMA_VERSION = 1;
 export const TASK_RECOVERY_EVENT_TYPES = Object.freeze(new Set([
   "TASK_RECOVERY_RECORDED",
   "OPERATOR_RECOVERY_RECORDED",
+  "TASK_ABANDONED",
   LEGACY_RECOVERY_MIGRATION_EVENT,
 ]));
 

package/src/core/templates.js

@@ -88,6 +88,9 @@ export const TEMPLATE_PATHS = [
   "schemas/execution-profile-benchmark-run.schema.json",
   "schemas/execution-profile-benchmark-aggregate.schema.json",
   "schemas/structural-quality.schema.json",
+  "schemas/semantic-decision.schema.json",
+  "schemas/context-plan.schema.json",
+  "schemas/test-utility.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/test-intelligence/benchmarks.js

@@ -0,0 +1,68 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { buildTestUtilityArtifact } from "./utility.js";
+
+const FIXTURE_TESTS = Object.freeze([
+  { testId: "protected-security", file: "tests/security.test.js", framework: "node:test", suite: "", name: "security", line: 1, signals: { security: true } },
+  { testId: "protected-public-api", file: "tests/api.test.js", framework: "node:test", suite: "", name: "api", line: 1, signals: { publicApi: true } },
+  { testId: "semantic-duplicate", file: "tests/duplicate.test.js", framework: "node:test", suite: "", name: "duplicate", line: 1, signals: {} },
+  { testId: "unique-branch", file: "tests/required.test.js", framework: "node:test", suite: "", name: "required", line: 1, signals: { requiredBehavior: true } },
+  { testId: "obsolete-test", file: "tests/obsolete.test.js", framework: "node:test", suite: "", name: "obsolete", line: 1, signals: {} },
+  { testId: "slow-required", file: "tests/critical.test.js", framework: "node:test", suite: "", name: "critical", line: 1, signals: { criticalPath: true } },
+  { testId: "flaky-low-signal", file: "tests/flaky.test.js", framework: "node:test", suite: "", name: "flaky", line: 1, signals: {} },
+]);
+
+const CASES = Object.freeze([
+  { id: "protected-security", expected: "KEEP_RISK_GUARD", protected: true },
+  { id: "protected-public-api", expected: "KEEP_UNIQUE", protected: true },
+  { id: "semantic-duplicate", expected: "REDUNDANT_CANDIDATE", protected: false },
+  { id: "unique-branch", expected: "KEEP_REQUIRED", protected: true },
+  { id: "obsolete-test", expected: "OBSOLETE_CANDIDATE", protected: false },
+  { id: "slow-required", expected: "KEEP_RECOVERY_INVARIANT", protected: true },
+  { id: "flaky-low-signal", expected: "FLAKY_LOW_SIGNAL", protected: false },
+]);
+
+function precision(cases, label) {
+  const predicted = cases.filter((item) => item.observed === label);
+  if (predicted.length === 0) return null;
+  return predicted.filter((item) => item.expected === label).length / predicted.length;
+}
+
+function recall(cases, label) {
+  const expected = cases.filter((item) => item.expected === label);
+  if (expected.length === 0) return null;
+  return expected.filter((item) => item.observed === label).length / expected.length;
+}
+
+export function runTestIntelligenceBenchmark() {
+  const candidateIds = ["semantic-duplicate", "obsolete-test", "flaky-low-signal"];
+  const decisions = { candidateIds, tests: {
+    "semantic-duplicate": { semantic_duplicate: true },
+    "obsolete-test": { likely_obsolete: true },
+    "flaky-low-signal": { likely_flaky_low_signal: true },
+  } };
+  const confidence = Object.fromEntries(
+    candidateIds.flatMap((id, index) => (
+      Object.keys(decisions.tests[id]).map((dimension) => [`test_${index}_${dimension}`, 0.95])
+    )),
+  );
+  const observedTests = buildTestUtilityArtifact({ taskId: "benchmark", inventory: { schemaVersion: 1, source: "FIXTURE", tests: FIXTURE_TESTS }, semanticDecision: { decisionId: "benchmark-decision", decision: decisions, confidence } }).tests;
+  const cases = CASES.map((item) => ({ ...item, observed: observedTests.find((test) => test.testId === item.id)?.classification ?? "UNKNOWN" }));
+  const protectedFalsePositives = cases.filter((item) => item.protected && ["REDUNDANT_CANDIDATE", "OBSOLETE_CANDIDATE", "SAFE_TO_REMOVE"].includes(item.observed)).length;
+  const summary = {
+    schemaVersion: 1,
+    status: "OFFLINE_DETERMINISTIC_FIXTURE",
+    caseCount: CASES.length,
+    metrics: {
+      redundantCandidatePrecision: precision(cases, "REDUNDANT_CANDIDATE"),
+      redundantCandidateRecall: recall(cases, "REDUNDANT_CANDIDATE"),
+      obsoleteCandidatePrecision: precision(cases, "OBSOLETE_CANDIDATE"),
+      obsoleteCandidateRecall: recall(cases, "OBSOLETE_CANDIDATE"),
+      protectedTestFalsePositiveRate: protectedFalsePositives / CASES.filter((item) => item.protected).length,
+      safeToRemoveFalsePositiveRate: precision(cases, "SAFE_TO_REMOVE") === null ? null : 1 - precision(cases, "SAFE_TO_REMOVE"),
+      rewriteRecommendationPrecision: null,
+    },
+    deletionAuthority: false,
+    cases,
+  };
+  return { ...summary, fingerprint: canonicalFingerprint(summary) };
+}