opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.8

package/src/verification/false-completion-prevention.js

@@ -0,0 +1,100 @@
+import { detectEvidenceGaps } from "../evidence/evidence-gap.js";
+
+export const COMPLETION_KEYWORDS = [
+  "done", "fixed", "working", "solved", "completed",
+  "implemented", "resolved", "ready", "complete"
+];
+
+export function interceptCompletionClaim(agentMessage) {
+  const claims = [];
+  const lower = agentMessage.toLowerCase();
+
+  for (const keyword of COMPLETION_KEYWORDS) {
+    const regex = new RegExp(`\\b${keyword}\\b`, "gi");
+    let match;
+    while ((match = regex.exec(agentMessage)) !== null) {
+      claims.push({
+        keyword,
+        position: match.index,
+        context: agentMessage.slice(Math.max(0, match.index - 30), match.index + 30)
+      });
+    }
+  }
+
+  return claims;
+}
+
+export function classifyClaim(claim, context) {
+  const patterns = {
+    FACT: /\b(exists|present|available|installed|configured)\b/i,
+    HYPOTHESIS: /\b(think|believe|probably|might|could be)\b/i,
+    OBSERVATION: /\b(see|observe|notice|found|detected)\b/i,
+    INTENT: /\b(will|going to|plan|should|need to)\b/i,
+    CONCLUSION: /\b(therefore|so|thus|conclude)\b/i,
+    COMPLETION_CLAIM: /\b(done|fixed|working|solved|completed)\b/i
+  };
+
+  for (const [type, pattern] of Object.entries(patterns)) {
+    if (pattern.test(claim)) return type;
+  }
+
+  return "UNKNOWN";
+}
+
+export function validateCompletionClaim(claim, taskState) {
+  if (!taskState.requirements || taskState.requirements.length === 0) {
+    return { valid: false, reason: "No requirements defined" };
+  }
+
+  const gaps = detectEvidenceGaps(taskState.requirements, taskState.evidence || []);
+  const mandatoryIncomplete = taskState.requirements.filter(
+    r => !r.optional && r.status !== "VERIFIED"
+  );
+
+  return {
+    valid: mandatoryIncomplete.length === 0 && gaps.length === 0,
+    reason: gaps.length > 0 ? "Evidence gaps remain" :
+            mandatoryIncomplete.length > 0 ? "Requirements not verified" : null,
+    incompleteRequirements: mandatoryIncomplete.map(r => r.id),
+    evidenceGaps: gaps.map(g => g.requirementId)
+  };
+}
+
+export function validateContractNotReduced(originalRequirements, currentRequirements) {
+  const violations = [];
+
+  for (const orig of originalRequirements) {
+    const current = currentRequirements.find(r => r.id === orig.id);
+    if (!current) {
+      violations.push({ type: "REMOVED", requirementId: orig.id });
+      continue;
+    }
+
+    if (orig.acceptanceCriteria && current.acceptanceCriteria) {
+      const origLen = orig.acceptanceCriteria.length;
+      const currLen = current.acceptanceCriteria.length;
+      if (currLen < origLen) {
+        violations.push({
+          type: "WEAKENED",
+          requirementId: orig.id,
+          originalCount: origLen,
+          currentCount: currLen
+        });
+      }
+    }
+
+    if (orig.claim && current.claim) {
+      if (current.claim.length < orig.claim.length * 0.8) {
+        violations.push({
+          type: "WEAKENED_CLAIM",
+          requirementId: orig.id
+        });
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations
+  };
+}

package/src/verification/hook-validator.js

@@ -0,0 +1,6 @@
+export function validateHook(hook) {
+  const errors = [];
+  if (!hook || !hook.name) errors.push('Missing hook name');
+  if (!hook || !hook.callback) errors.push('Missing callback');
+  return { valid: errors.length === 0, errors };
+}

package/src/verification/requirements.js

@@ -0,0 +1,6 @@
+export function createRequirement(id, title) {
+  return { id, title, status: "pending", evidence: [] };
+}
+export function markRequirement(requirement, status, evidence) {
+  return { ...requirement, status, evidence: [...requirement.evidence, evidence] };
+}

package/src/verification/verification-context.js

@@ -0,0 +1,162 @@
+// Change 12 — context-verification
+// Change 13 — verification-context-budget
+// Change 15 — verification-invalidation
+
+export const CONTEXT_LEVELS = {
+  N0: "N0", // Task / requirements
+  N1: "N1", // Domain-specific verification knowledge
+  N2: "N2", // Current evidence / observations
+  N3: "N3"  // Opportunistic context
+};
+
+export function loadVerificationContext(level, taskData) {
+  switch (level) {
+    case CONTEXT_LEVELS.N0:
+      return { requirements: taskData.requirements };
+    case CONTEXT_LEVELS.N1:
+      return {
+        requirements: taskData.requirements,
+        verificationMethods: taskData.verificationMethods || []
+      };
+    case CONTEXT_LEVELS.N2:
+      return {
+        requirements: taskData.requirements,
+        evidence: taskData.evidence || [],
+        observations: taskData.observations || []
+      };
+    case CONTEXT_LEVELS.N3:
+      return {
+        opportunistic: true,
+        context: taskData.opportunisticContext
+      };
+    default:
+      return {};
+  }
+}
+
+// Rule: Never load N3 to substitute missing N2 evidence
+export function validateContextBudget(loadedContext, requiredLevels) {
+  const missing = requiredLevels.filter(l => !loadedContext[l]);
+  return {
+    valid: missing.length === 0,
+    missingLevels: missing,
+    warning: loadedContext[CONTEXT_LEVELS.N3] && !loadedContext[CONTEXT_LEVELS.N2]
+      ? "N3 context used to substitute missing N2"
+      : null
+  };
+}
+
+export const DEFAULT_VERIFICATION_BUDGET = {
+  maxActions: 10,
+  maxTokens: 50000,
+  maxLatencyMs: 120000,
+  maxRetries: 2
+};
+
+export function createVerificationBudget(overrides = {}) {
+  return { ...DEFAULT_VERIFICATION_BUDGET, ...overrides };
+}
+
+// Change 32 — verification-invalidation
+export function createVerificationInvalidation(requirement, reason, relatedEvidence = []) {
+  return {
+    requirementId: requirement.id,
+    previousStatus: requirement.status,
+    newStatus: "UNKNOWN",
+    reason,
+    relatedEvidence: relatedEvidence.map(e => e.id),
+    invalidatedAt: Date.now(),
+    invalidatedBy: "verificationEngine"
+  };
+}
+
+export function checkVerificationDependencies(requirement, currentContext) {
+  const dependencies = requirement.dependencies || [];
+  const changes = [];
+
+  for (const dep of dependencies) {
+    const currentValue = currentContext[dep.key];
+    const previousValue = dep.value;
+
+    if (currentValue !== previousValue) {
+      changes.push({
+        dependency: dep.key,
+        previous: previousValue,
+        current: currentValue
+      });
+    }
+  }
+
+  return {
+    stable: changes.length === 0,
+    changes
+  };
+}
+
+export function shouldInvalidate(requirement, currentContext, stalenessThreshold = 3600000) {
+  if (!requirement.verifiedAt) return false;
+
+  const age = Date.now() - requirement.verifiedAt;
+  if (age > stalenessThreshold) return true;
+
+  const deps = checkVerificationDependencies(requirement, currentContext);
+  return !deps.stable;
+}
+
+export function isBudgetExhausted(budget, usage) {
+  return (
+    usage.actions >= budget.maxActions ||
+    usage.tokens >= budget.maxTokens ||
+    usage.latencyMs >= budget.maxLatencyMs ||
+    usage.retries >= budget.maxRetries
+  );
+}
+
+export function invalidateVerification(requirement, invalidatingObservation) {
+  return {
+    ...requirement,
+    status: "UNKNOWN",
+    invalidatedAt: Date.now(),
+    invalidationReason: invalidatingObservation,
+    previousStatus: requirement.status
+  };
+}
+
+/**
+ * Before verifying a requirement, reject STALE evidence.
+ * If any linked evidence is STALE the requirement returns to PENDING
+ * and verification is skipped (caller must replan).
+ *
+ * @param {object} requirement
+ * @param {Array<{id?: string, status?: string}>} evidence
+ * @returns {{ canVerify: boolean, requirement: object, staleEvidence: Array, reason: string|null }}
+ */
+export function checkEvidenceFreshness(requirement, evidence = []) {
+  const staleEvidence = (evidence || []).filter(
+    (e) => e && (e.status === "stale" || e.status === "STALE")
+  );
+  if (staleEvidence.length === 0) {
+    return { canVerify: true, requirement, staleEvidence: [], reason: null };
+  }
+  const reverted = {
+    ...requirement,
+    status: "pending",
+    previousStatus: requirement.status,
+    replan: true,
+    staleEvidenceIds: staleEvidence.map((e) => e.id).filter(Boolean),
+  };
+  return {
+    canVerify: false,
+    requirement: reverted,
+    staleEvidence,
+    reason: "STALE evidence — requirement returned to PENDING, replan required",
+  };
+}
+
+/**
+ * Gate used immediately before verifying a requirement.
+ * Returns the requirement (possibly reset to PENDING) plus a verify flag.
+ */
+export function prepareRequirementVerification(requirement, evidence = []) {
+  return checkEvidenceFreshness(requirement, evidence);
+}

package/src/verification/verification-lifecycle.js

@@ -0,0 +1,66 @@
+/**
+ * Verification Lifecycle — requirement verification state machine.
+ * Implements spec: verification-lifecycle.
+ *
+ * States: UNVERIFIED → VERIFYING → VERIFIED (or → FAILED → new hypothesis)
+ * Evidence: method (test/lint/build/other), result (pass/fail), details
+ */
+
+const VERIFICATION_STATES = new Set(["UNVERIFIED", "VERIFYING", "VERIFIED", "FAILED", "INVALIDATED"]);
+
+const VALID_TRANSITIONS = {
+  UNVERIFIED: new Set(["VERIFYING"]),
+  VERIFYING: new Set(["VERIFIED", "FAILED"]),
+  FAILED: new Set(["VERIFYING"]),
+  VERIFIED: new Set(["INVALIDATED"]),
+  INVALIDATED: new Set(["VERIFYING"]),
+};
+
+export function isValidVerificationState(state) {
+  return VERIFICATION_STATES.has(state);
+}
+
+export function transitionVerification(from, to) {
+  if (!isValidVerificationState(from)) throw new Error(`Invalid verification state: ${from}`);
+  if (!VALID_TRANSITIONS[from].has(to)) throw new Error(`Invalid transition: ${from} → ${to}. Allowed: ${[...VALID_TRANSITIONS[from]].join(", ") || "(none)"}`);
+  return to;
+}
+
+export function createEvidence(method, result, details) {
+  if (!method || !result) throw new Error("Evidence requires method and result");
+  return { method, result, details: details || "", at: Date.now() };
+}
+
+export function isVerified(requirement) {
+  return requirement?.verificationStatus === "VERIFIED" && Array.isArray(requirement.evidence) && requirement.evidence.length > 0;
+}
+
+export function canComplete(taskState) {
+  const reqs = taskState?.requirements || [];
+  const unverified = reqs.filter((r) => !isVerified(r));
+  return { canComplete: unverified.length === 0, unverifiedCount: unverified.length, unverifiedIds: unverified.map((r) => r.id) };
+}
+
+export function hasOutstandingWork(taskState) {
+  const reqs = taskState?.requirements || [];
+  const unverified = reqs.filter((r) => !isVerified(r));
+  const backlogPending = (taskState?.backlog || []).filter((b) => b.status === "pending");
+  return unverified.length > 0 || backlogPending.length > 0;
+}
+
+export function verifyRequirement(requirement, evidenceItems = []) {
+  if (evidenceItems.length === 0) throw new Error(`Cannot verify ${requirement.id}: no evidence provided`);
+  return {
+    ...requirement,
+    verificationStatus: "VERIFIED",
+    evidence: evidenceItems,
+  };
+}
+
+export function failRequirement(requirement, reason = "") {
+  return {
+    ...requirement,
+    verificationStatus: "FAILED",
+    failureReason: reason,
+  };
+}

package/src/verification/verification-model.js

@@ -0,0 +1,89 @@
+// Requirement states
+export const REQUIREMENT_STATES = {
+  OPEN: "OPEN",
+  IN_PROGRESS: "IN_PROGRESS",
+  OBSERVED: "OBSERVED",
+  SUPPORTED: "SUPPORTED",
+  VERIFIED: "VERIFIED",
+  FAILED: "FAILED",
+  UNKNOWN: "UNKNOWN"
+};
+
+// Validation rules:
+// - OBSERVED never implies VERIFIED
+// - SUPPORTED requires relevant evidence
+// - VERIFIED requires satisfying acceptanceCriteria
+// - FAILED requires contradictory evidence
+// - UNKNOWN means insufficient evidence
+// - No VERIFIED allowed without verificationMethod
+// - No task completion while any mandatory requirement is in OPEN, UNKNOWN, OBSERVED or SUPPORTED
+
+export function createRequirement({ id, claim, intent, expectedOutcome, acceptanceCriteria = [], verificationMethod = null, optional = false }) {
+  if (!id || !claim) throw new Error("id and claim are required");
+  return {
+    id,
+    claim,
+    intent: intent || "",
+    expectedOutcome: expectedOutcome || "",
+    acceptanceCriteria,
+    verificationMethod,
+    status: REQUIREMENT_STATES.OPEN,
+    evidence: [],
+    optional,
+    createdAt: Date.now(),
+    updatedAt: Date.now()
+  };
+}
+
+export function isRequirementCompletable(requirement) {
+  const terminalStates = [REQUIREMENT_STATES.VERIFIED, REQUIREMENT_STATES.FAILED];
+  return terminalStates.includes(requirement.status);
+}
+
+export function canCompleteTask(requirements) {
+  const mandatory = requirements.filter(r => !r.optional);
+  const incomplete = mandatory.filter(r => !isRequirementCompletable(r));
+  return {
+    canComplete: incomplete.length === 0,
+    incompleteRequirements: incomplete.map(r => ({ id: r.id, status: r.status }))
+  };
+}
+
+// State transitions (per spec)
+export const VALID_TRANSITIONS = {
+  [REQUIREMENT_STATES.OPEN]: [REQUIREMENT_STATES.IN_PROGRESS],
+  [REQUIREMENT_STATES.IN_PROGRESS]: [REQUIREMENT_STATES.OBSERVED, REQUIREMENT_STATES.FAILED, REQUIREMENT_STATES.UNKNOWN],
+  [REQUIREMENT_STATES.OBSERVED]: [REQUIREMENT_STATES.SUPPORTED, REQUIREMENT_STATES.FAILED, REQUIREMENT_STATES.UNKNOWN],
+  [REQUIREMENT_STATES.SUPPORTED]: [REQUIREMENT_STATES.VERIFIED, REQUIREMENT_STATES.FAILED, REQUIREMENT_STATES.UNKNOWN],
+  [REQUIREMENT_STATES.UNKNOWN]: [REQUIREMENT_STATES.IN_PROGRESS],
+  [REQUIREMENT_STATES.VERIFIED]: [REQUIREMENT_STATES.OPEN], // only if new evidence invalidates
+  [REQUIREMENT_STATES.FAILED]: [], // terminal
+};
+
+export function canTransition(fromState, toState) {
+  const allowed = VALID_TRANSITIONS[fromState];
+  return allowed && allowed.includes(toState);
+}
+
+export function transitionRequirement(requirement, toState, evidence = null) {
+  if (!canTransition(requirement.status, toState)) {
+    throw new Error(`Invalid transition: ${requirement.status} → ${toState}. Allowed: ${VALID_TRANSITIONS[requirement.status]?.join(", ") || "none"}`);
+  }
+
+  const updated = {
+    ...requirement,
+    status: toState,
+    updatedAt: Date.now()
+  };
+
+  if (evidence) {
+    updated.evidence = [...requirement.evidence, evidence];
+  }
+
+  // If moving back to OPEN from VERIFIED, mark as stale
+  if (requirement.status === REQUIREMENT_STATES.VERIFIED && toState === REQUIREMENT_STATES.OPEN) {
+    updated.invalidatedAt = Date.now();
+  }
+
+  return updated;
+}

package/src/verification/verification-persistence.js

@@ -0,0 +1,129 @@
+/**
+ * Verification Persistence + Stale Evidence — WAM 1.1
+ *
+ * Change 16 — session-persistence:
+ *   persistVerificationState, loadVerificationState, createVerificationSnapshot
+ *
+ * Change 17 — stale-evidence:
+ *   EVIDENCE_TTL, getEvidenceTTL, isEvidenceStale
+ *
+ * Persistence root: .wam/verifications/ (mirrors PersistenceManager convention).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+let snapshotCounter = 0;
+
+// ── Stale Evidence Constants ────────────────────────────────────────────────
+
+/** Default TTL for evidence freshness: 24 hours in milliseconds. */
+export const EVIDENCE_TTL = 24 * 60 * 60 * 1000; // 86_400_000 ms
+
+/**
+ * Returns the configured TTL for evidence staleness checks (ms).
+ * Override via WAM_EVIDENCE_TTL env var for testing flexibility.
+ */
+export function getEvidenceTTL() {
+  const env = process.env.WAM_EVIDENCE_TTL;
+  if (env) {
+    const parsed = parseInt(env, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return EVIDENCE_TTL;
+}
+
+/**
+ * Determines whether evidence is stale relative to the configured TTL.
+ * Evidence is stale when (now - evidence.timestamp) > getEvidenceTTL().
+ * Accepts evidence objects with a `timestamp` (number, ms) or `at` (ISO string) field.
+ */
+export function isEvidenceStale(evidence) {
+  if (!evidence) return true;
+  const ttl = getEvidenceTTL();
+  const now = Date.now();
+
+  let evidenceTime;
+  if (typeof evidence.timestamp === "number") {
+    evidenceTime = evidence.timestamp;
+  } else if (typeof evidence.at === "string") {
+    evidenceTime = new Date(evidence.at).getTime();
+  } else {
+    return true; // no recognizable timestamp → stale
+  }
+
+  if (isNaN(evidenceTime)) return true;
+  return now - evidenceTime > ttl;
+}
+
+// ── Session Persistence ───────────────────────────────────────────────────────
+
+const VERIFICATIONS_DIR = path.join(process.cwd(), ".wam", "verifications");
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function getPath(taskId) {
+  return path.join(VERIFICATIONS_DIR, `${taskId}.json`);
+}
+
+/**
+ * Persists the verification state for a task to disk as JSON.
+ * @param {string} taskId
+ * @param {object} state — verification state object to serialize
+ * @returns {{ taskId, persistedAt, path }}
+ */
+export function persistVerificationState(taskId, state) {
+  if (!taskId) throw new Error("taskId is required");
+  ensureDir(VERIFICATIONS_DIR);
+  const filePath = getPath(taskId);
+  const record = {
+    taskId,
+    state,
+    persistedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2), "utf-8");
+  return { taskId, persistedAt: record.persistedAt, path: filePath };
+}
+
+/**
+ * Loads the verification state for a task from disk.
+ * Returns null if no file exists for the task.
+ * @param {string} taskId
+ * @returns {object|null} — { taskId, state, persistedAt } or null
+ */
+export function loadVerificationState(taskId) {
+  if (!taskId) throw new Error("taskId is required");
+  const filePath = getPath(taskId);
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, "utf-8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Creates a timestamped snapshot of the current verification state.
+ * Appends a snapshot entry to the task's existing record (or creates a new one).
+ * Snapshots are stored in `.wam/verifications/{taskId}.snapshots/` as individual files.
+ * @param {string} taskId
+ * @param {object} state — current verification state to snapshot
+ * @returns {{ taskId, snapshotId, snapshotAt, path }}
+ */
+export function createVerificationSnapshot(taskId, state) {
+  if (!taskId) throw new Error("taskId is required");
+  const snapshotsDir = path.join(VERIFICATIONS_DIR, taskId, "snapshots");
+  ensureDir(snapshotsDir);
+
+  const snapshotId = Date.now().toString(36) + "-" + (snapshotCounter++);
+  const snapshotAt = new Date().toISOString();
+  const snapshot = {
+    snapshotId,
+    taskId,
+    state,
+    snapshotAt,
+  };
+  const filePath = path.join(snapshotsDir, `${snapshotId}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2), "utf-8");
+
+  return { taskId, snapshotId, snapshotAt, path: filePath };
+}

package/src/verification/verification-policy.js

@@ -0,0 +1,127 @@
+import { detectEvidenceGaps } from "../evidence/evidence-gap.js";
+import { EVIDENCE_STRENGTH } from "../evidence/evidence.js";
+
+export const VERIFICATION_STRATEGY = {
+  EXISTING_TEST: "existing_test",
+  TARGETED_COMMAND: "targeted_command",
+  TARGETED_INSPECTION: "targeted_inspection",
+  MINIMAL_REPRODUCTION: "minimal_reproduction",
+  BROADER_TEST: "broader_test",
+  MANUAL_VALIDATION: "manual_validation"
+};
+
+export function selectMinimalVerification(gap, availableChecks = []) {
+  // Prefer existing tests
+  const existingTest = availableChecks.find(c => c.type === "test");
+  if (existingTest) return { strategy: VERIFICATION_STRATEGY.EXISTING_TEST, check: existingTest };
+
+  // Then targeted command
+  const targetedCmd = availableChecks.find(c => c.type === "command");
+  if (targetedCmd) return { strategy: VERIFICATION_STRATEGY.TARGETED_COMMAND, check: targetedCmd };
+
+  // Then targeted inspection
+  const inspection = availableChecks.find(c => c.type === "inspection");
+  if (inspection) return { strategy: VERIFICATION_STRATEGY.TARGETED_INSPECTION, check: inspection };
+
+  // Fallback to broader test
+  const broader = availableChecks.find(c => c.type === "broader_test");
+  if (broader) return { strategy: VERIFICATION_STRATEGY.BROADER_TEST, check: broader };
+
+  return { strategy: VERIFICATION_STRATEGY.MANUAL_VALIDATION, check: null };
+}
+
+// Change 28 — Verification-strategy: ordered strategy with cost estimation
+export const VERIFICATION_STRATEGY_ORDER = [
+  VERIFICATION_STRATEGY.EXISTING_TEST,
+  VERIFICATION_STRATEGY.TARGETED_COMMAND,
+  VERIFICATION_STRATEGY.TARGETED_INSPECTION,
+  VERIFICATION_STRATEGY.MINIMAL_REPRODUCTION,
+  VERIFICATION_STRATEGY.BROADER_TEST,
+  VERIFICATION_STRATEGY.MANUAL_VALIDATION
+];
+
+export function rankVerificationStrategies(strategies, context) {
+  // Always prefer cheaper strategies first
+  return strategies
+    .filter(s => VERIFICATION_STRATEGY_ORDER.includes(s))
+    .sort((a, b) => VERIFICATION_STRATEGY_ORDER.indexOf(a) - VERIFICATION_STRATEGY_ORDER.indexOf(b));
+}
+
+export function estimateStrategyCost(strategy) {
+  const costs = {
+    [VERIFICATION_STRATEGY.EXISTING_TEST]: 1,
+    [VERIFICATION_STRATEGY.TARGETED_COMMAND]: 2,
+    [VERIFICATION_STRATEGY.TARGETED_INSPECTION]: 3,
+    [VERIFICATION_STRATEGY.MINIMAL_REPRODUCTION]: 4,
+    [VERIFICATION_STRATEGY.BROADER_TEST]: 5,
+    [VERIFICATION_STRATEGY.MANUAL_VALIDATION]: 10
+  };
+  return costs[strategy] || 10;
+}
+
+// Verification-strategy coordination: validate that strategy transitions are legal.
+// NOTE: operates on VERIFICATION_STRATEGY, not policy states. Distinct from
+// policy-state-machine.js#validatePolicyFlow despite the shared name.
+export function validatePolicyFlow(currentPolicy, nextPolicy) {
+  const validTransitions = {
+    [VERIFICATION_STRATEGY.EXISTING_TEST]: [VERIFICATION_STRATEGY.TARGETED_COMMAND],
+    [VERIFICATION_STRATEGY.TARGETED_COMMAND]: [VERIFICATION_STRATEGY.TARGETED_INSPECTION],
+    [VERIFICATION_STRATEGY.TARGETED_INSPECTION]: [VERIFICATION_STRATEGY.MINIMAL_REPRODUCTION],
+    [VERIFICATION_STRATEGY.MINIMAL_REPRODUCTION]: [VERIFICATION_STRATEGY.BROADER_TEST],
+    [VERIFICATION_STRATEGY.BROADER_TEST]: [VERIFICATION_STRATEGY.MANUAL_VALIDATION],
+  };
+  if (currentPolicy === nextPolicy) return { valid: false, reason: "same-policy" };
+  const allowed = validTransitions[currentPolicy] || [];
+  if (!allowed.includes(nextPolicy)) return { valid: false, reason: "invalid-transition" };
+  return { valid: true };
+}
+
+// Verification-strategy coordination: get next strategy in escalation chain.
+// Distinct from policy-state-machine.js#getNextPolicy.
+export function getNextPolicy(currentPolicy) {
+  const chain = [
+    VERIFICATION_STRATEGY.EXISTING_TEST,
+    VERIFICATION_STRATEGY.TARGETED_COMMAND,
+    VERIFICATION_STRATEGY.TARGETED_INSPECTION,
+    VERIFICATION_STRATEGY.MINIMAL_REPRODUCTION,
+    VERIFICATION_STRATEGY.BROADER_TEST,
+    VERIFICATION_STRATEGY.MANUAL_VALIDATION,
+  ];
+  const idx = chain.indexOf(currentPolicy);
+  if (idx === -1 || idx === chain.length - 1) return null;
+  return chain[idx + 1];
+}
+
+/**
+ * Fail-closed completion gate over a task's requirements and evidence.
+ *
+ * Invariants:
+ * - A task is `blocked` unless EVERY mandatory (non-optional) requirement is
+ *   `VERIFIED` AND there are no evidence gaps.
+ * - Missing or malformed evidence never passes: absent requirements/evidence
+ *   default to empty arrays, which blocks completion.
+ * - Optional requirements do not affect `blocked`.
+ *
+ * @param {{ requirements?: Array<{id:string, optional?:boolean, status?:string}>,
+ *           evidence?: Array<object> }} task
+ * @returns {{ blocked: boolean, completedRequirements: number,
+ *            totalRequirements: number, evidenceGaps: Array<object>,
+ *            unresolvedRequirements: string[] }}
+ */
+export function evaluateCompletionGate(task) {
+  const { requirements = [], evidence = [] } = task;
+
+  const gaps = detectEvidenceGaps(requirements, evidence);
+  const mandatory = requirements.filter(r => !r.optional);
+  const verified = mandatory.filter(r => r.status === "VERIFIED");
+
+  const blocked = verified.length !== mandatory.length || gaps.length > 0;
+
+  return {
+    blocked,
+    completedRequirements: verified.length,
+    totalRequirements: mandatory.length,
+    evidenceGaps: gaps,
+    unresolvedRequirements: gaps.map(g => g.requirementId)
+  };
+}