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

package/src/state/wam-state.js

@@ -0,0 +1,148 @@
+/**
+ * wam-state.js — Wait-a-Minute session state management.
+ *
+ * Provides CRUD for WAM (Wait-a-Minute) session state persisted to disk,
+ * session resumption, and schema migration utilities.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// ── Constants ────────────────────────────────────────────────
+export const SCHEMA_VERSION = 1;
+export const STATE_FILENAME = 'wam-state.json';
+
+/**
+ * Returns the current schema version number.
+ * @param {object} [state] — optional state object to inspect for its version
+ * @returns {number} schema version
+ */
+export function getSchemaVersion(state) {
+  if (state && typeof state === 'object' && '_schemaVersion' in state) {
+    return state._schemaVersion;
+  }
+  return SCHEMA_VERSION;
+}
+
+/**
+ * Creates a new WAM state object.
+ * @param {string} taskId
+ * @param {object} [requirements={}]
+ * @param {object} [context={}]
+ * @param {object} [evidence={}]
+ * @returns {object} the created state
+ */
+export function createWamState(taskId, requirements = {}, context = {}, evidence = {}) {
+  const now = new Date().toISOString();
+  return {
+    _schemaVersion: SCHEMA_VERSION,
+    taskId,
+    createdAt: now,
+    updatedAt: now,
+    requirements,
+    context,
+    evidence,
+    status: 'active',
+  };
+}
+
+/**
+ * Saves WAM state to disk.
+ * @param {string} taskId
+ * @param {object} state
+ * @param {string} rootDir
+ * @returns {Promise<string>} resolved file path
+ */
+export async function saveWamState(taskId, state, rootDir) {
+  const dir = path.join(rootDir, taskId);
+  await fs.mkdir(dir, { recursive: true });
+  state.updatedAt = new Date().toISOString();
+  const filePath = path.join(dir, STATE_FILENAME);
+  await fs.writeFile(filePath, JSON.stringify(state, null, 2));
+  return filePath;
+}
+
+/**
+ * Loads WAM state from disk.
+ * @param {string} taskId
+ * @param {string} rootDir
+ * @returns {Promise<object|null>} the loaded state or null if not found
+ */
+export async function loadWamState(taskId, rootDir) {
+  const filePath = path.join(rootDir, taskId, STATE_FILENAME);
+  try {
+    await fs.access(filePath);
+  } catch {
+    return null;
+  }
+  const raw = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Resumes a session from a loaded WAM state.
+ * Returns a resume descriptor with metadata about the session to continue.
+ * @param {object} wamState
+ * @returns {object} resume descriptor
+ */
+export function resumeSession(wamState) {
+  if (!wamState || typeof wamState !== 'object') {
+    return {
+      resumable: false,
+      reason: 'No valid state provided',
+      taskId: null,
+    };
+  }
+
+  if (wamState.status === 'completed') {
+    return {
+      resumable: false,
+      reason: 'Session already completed',
+      taskId: wamState.taskId ?? null,
+    };
+  }
+
+  return {
+    resumable: true,
+    taskId: wamState.taskId ?? null,
+    status: wamState.status ?? 'unknown',
+    createdAt: wamState.createdAt,
+    updatedAt: wamState.updatedAt,
+    schemaVersion: getSchemaVersion(wamState),
+    hasRequirements: Boolean(wamState.requirements && Object.keys(wamState.requirements).length > 0),
+    hasContext: Boolean(wamState.context && Object.keys(wamState.context).length > 0),
+    hasEvidence: Boolean(wamState.evidence && Object.keys(wamState.evidence).length > 0),
+  };
+}
+
+/**
+ * Migrates an old-format WAM state to the current schema version.
+ * Handles common migration scenarios: adding missing fields, renaming
+ * deprecated keys, and setting default values.
+ * @param {object} oldState
+ * @returns {object} migrated state
+ */
+export function migrateWamState(oldState) {
+  if (!oldState || typeof oldState !== 'object') {
+    return createWamState('migrated-empty');
+  }
+
+  const migrated = { ...oldState };
+
+  if (!('_schemaVersion' in migrated)) {
+    migrated._schemaVersion = 0;
+  }
+
+  // Migration from v0 → v1
+  if (migrated._schemaVersion < 1) {
+    if (!migrated.createdAt) migrated.createdAt = new Date().toISOString();
+    if (!migrated.updatedAt) migrated.updatedAt = migrated.createdAt;
+    if (!migrated.requirements) migrated.requirements = {};
+    if (!migrated.context) migrated.context = {};
+    if (!migrated.evidence) migrated.evidence = {};
+    if (!migrated.status) migrated.status = 'active';
+    migrated._schemaVersion = SCHEMA_VERSION;
+  }
+
+  return migrated;
+}

package/src/verification/completion-gate-simple.js

@@ -0,0 +1,8 @@
+export function evaluateCompletion(state) {
+  const reqs = state.requirements || [];
+  const unverified = reqs.filter(r => r.status !== "verified");
+  return {
+    blocked: unverified.length > 0,
+    unresolvedRequirements: unverified.map(r => r.id)
+  };
+}

package/src/verification/completion-gate.js

@@ -0,0 +1,183 @@
+/**
+ * Completion Gate
+ *
+ * Decides whether a task can be marked complete based on:
+ *  - every requirement being VERIFIED (via requirement-state)
+ *  - existence of at least one piece of verified evidence per requirement
+ *  - absence of contradicting evidence that would invalidate completion
+ *  - absence of inconclusive evidence that leaves the requirement unresolved
+ *
+ * API:
+ *   canComplete(taskRoot, taskId) -> {
+ *     allowed: boolean,
+ *     reason: string,
+ *     blockers: Array<{ requirementId, reason }>,
+ *     summary: { total, complete, incomplete, blocked },
+ *   }
+ *
+ * The function is read-only; it does not mutate task state. Callers may use
+ * the result to either allow completion, emit a structured failure, or block
+ * a "done" claim emitted by an agent.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getTaskState } from "../skills/engine.js";
+import {
+  isRequirementComplete,
+  summarizeRequirements,
+  REQUIREMENT_STATES,
+} from "../state/requirement-state.js";
+import {
+  getAllEvidence,
+  getEvidenceForRequirement,
+} from "../evidence/evidence-lineage.js";
+
+/**
+ * Read all evidence for a task (regardless of status). Tolerates errors.
+ */
+function readAllEvidence(taskRoot, taskId) {
+  try {
+    const ev = getAllEvidence(taskId, taskRoot);
+    return Array.isArray(ev) ? ev : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Inspect a single requirement and classify why it would block completion.
+ * Returns null if the requirement does NOT block.
+ */
+function findBlocker(requirement, allEvidence) {
+  const id = requirement.id;
+  const evidenceForReq = allEvidence.filter((e) => e && e.requirementId === id);
+
+  // 1. No evidence at all -> blocked (regardless of status).
+  if (evidenceForReq.length === 0) {
+    return {
+      requirementId: id,
+      reason: `no evidence linked (status=${requirement.status || REQUIREMENT_STATES.PENDING})`,
+    };
+  }
+
+  // 2. Evidence exists but is contradictory or invalidated -> blocked.
+  const statuses = evidenceForReq.map((e) => e.status || e.verdict);
+  if (statuses.some((s) => s === "contradictory" || s === "CONTRADICTORY" || s === "INVALIDATED" || s === "invalidated")) {
+    return {
+      requirementId: id,
+      reason: `contradictory or invalidated evidence present`,
+    };
+  }
+
+  // 3. All evidence is inconclusive -> blocked.
+  if (statuses.every((s) => s === "inconclusive" || s === "INCONCLUSIVE")) {
+    return {
+      requirementId: id,
+      reason: `only inconclusive evidence; requirement unresolved`,
+    };
+  }
+
+  // 4. Requirement is not VERIFIED but has evidence.
+  if (!isRequirementComplete(requirement)) {
+    // Has evidence but no valid piece yet -> blocked.
+    if (!statuses.some((s) => s === "valid" || s === "VERIFIED")) {
+      return {
+        requirementId: id,
+        reason: `no valid evidence for requirement`,
+      };
+    }
+    return {
+      requirementId: id,
+      reason: `requirement status is ${requirement.status || REQUIREMENT_STATES.PENDING} (not VERIFIED)`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Decide if a task can complete.
+ *
+ * @param {string} taskRoot  absolute path to the project root (where .wam/ lives)
+ * @param {string} taskId    task identifier
+ * @returns {{allowed: boolean, reason: string, blockers: Array, summary: object}}
+ */
+export function canComplete(taskRoot, taskId) {
+  if (!taskRoot || !taskId) {
+    return {
+      allowed: false,
+      reason: "taskRoot and taskId are required",
+      blockers: [],
+      summary: { total: 0, complete: 0, incomplete: 0, blocked: 0 },
+    };
+  }
+
+  const root = path.resolve(taskRoot);
+  if (!fs.existsSync(root)) {
+    return {
+      allowed: false,
+      reason: `task root does not exist: ${root}`,
+      blockers: [],
+      summary: { total: 0, complete: 0, incomplete: 0, blocked: 0 },
+    };
+  }
+
+  let taskState;
+  try {
+    taskState = getTaskState(taskId, root);
+  } catch (err) {
+    return {
+      allowed: false,
+      reason: `failed to load task state: ${err.message}`,
+      blockers: [],
+      summary: { total: 0, complete: 0, incomplete: 0, blocked: 0 },
+    };
+  }
+
+  const requirements = Array.isArray(taskState.requirements)
+    ? taskState.requirements
+    : [];
+
+  if (requirements.length === 0) {
+    return {
+      allowed: false,
+      reason: "task has no requirements",
+      blockers: [],
+      summary: { total: 0, complete: 0, incomplete: 0, blocked: 0 },
+    };
+  }
+
+  const allEvidence = readAllEvidence(root, taskId);
+
+  const blockers = [];
+  for (const req of requirements) {
+    const blocker = findBlocker(req, allEvidence);
+    if (blocker) blockers.push(blocker);
+  }
+
+  const summary = summarizeRequirements(requirements);
+
+  if (blockers.length === 0) {
+    return {
+      allowed: true,
+      reason: "all requirements verified",
+      blockers: [],
+      summary: summary.summary,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: `${blockers.length} requirement(s) blocking completion`,
+    blockers,
+    summary: summary.summary,
+  };
+}
+
+/**
+ * Convenience helper: returns true iff canComplete(...).allowed
+ */
+export function isCompletionAllowed(taskRoot, taskId) {
+  return canComplete(taskRoot, taskId).allowed;
+}

package/src/verification/contract.js

@@ -0,0 +1,9 @@
+export function createContract(requirements, verification) {
+  return { status: "PROPOSED", requirements, verification, unknowns: [], assumptions: [] };
+}
+export function approveContract(contract) {
+  return { ...contract, status: "APPROVED" };
+}
+export function rejectContract(contract) {
+  return { ...contract, status: "REJECTED" };
+}

package/src/verification/contradiction-resolution.js

@@ -0,0 +1,255 @@
+/**
+ * Context Contradiction Resolution — explicit conflict detection and resolution.
+ *
+ * Detects when two pieces of context contradict each other and determines
+ * which one governs based on authority precedence.
+ *
+ * Resolution precedence:
+ *   1. user_decided (highest authority)
+ *   2. explicit current constraint
+ *   3. verified current evidence
+ *   4. newer valid decision
+ *   5. inferred
+ *   6. unknown
+ *
+ * States: RESOLVED | UNRESOLVED | BLOCKED
+ */
+
+/**
+ * @typedef {"RESOLVED" | "UNRESOLVED" | "BLOCKED"} ConflictStatus
+ */
+
+/**
+ * @typedef {"user_decided" | "constraint" | "evidence" | "decision" | "inferred" | "unknown"} AuthorityType
+ */
+
+/**
+ * @typedef {Object} Conflict
+ * @property {string} id
+ * @property {string} nodeA - First contradicting node
+ * @property {string} nodeB - Second contradicting node
+ * @property {string} type - "contradiction" | "invalidation"
+ * @property {AuthorityType} authorityA - Authority type of node A
+ * @property {AuthorityType} authorityB - Authority type of node B
+ * @property {ConflictStatus} status
+ * @property {string} winner - Node ID that wins (if resolved)
+ * @property {string} reason - Why this resolution was chosen
+ * @property {boolean} blocking - Whether this blocks execution
+ */
+
+/** Authority precedence (lower number = higher authority) */
+const AUTHORITY_PRECEDENCE = {
+  user_decided: 1,
+  constraint: 2,
+  evidence: 3,
+  decision: 4,
+  inferred: 5,
+  unknown: 6,
+};
+
+/** Conflict types that block execution */
+const BLOCKING_TYPES = [
+  "architecture",
+  "security",
+  "compatibility",
+  "acceptance",
+  "destructive",
+];
+
+/**
+ * Determine the authority type of a node based on its content and metadata.
+ *
+ * @param {Object} node
+ * @returns {AuthorityType}
+ */
+export function getAuthorityType(node) {
+  if (!node) return "unknown";
+
+  const content = (node.content || "").toLowerCase();
+  const type = node.type || "";
+
+  // User decided
+  if (content.includes("user decided") || content.includes("user-decided")) {
+    return "user_decided";
+  }
+
+  // Constraint
+  if (
+    type === "constraint" ||
+    content.includes("must") ||
+    content.includes("shall") ||
+    content.includes("mandatory") ||
+    content.includes("required")
+  ) {
+    return "constraint";
+  }
+
+  // Evidence
+  if (
+    type === "evidence" ||
+    content.includes("evidence") ||
+    content.includes("verified") ||
+    content.includes("test passed")
+  ) {
+    return "evidence";
+  }
+
+  // Decision
+  if (
+    type === "decision" ||
+    content.includes("decision") ||
+    content.includes("decided") ||
+    content.includes("chose") ||
+    content.includes("selected")
+  ) {
+    return "decision";
+  }
+
+  // Inferred
+  if (
+    type === "inferred" ||
+    content.includes("inferred") ||
+    content.includes("assumed") ||
+    content.includes("likely")
+  ) {
+    return "inferred";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Compare two authority types and determine which wins.
+ *
+ * @param {AuthorityType} a
+ * @param {AuthorityType} b
+ * @returns {{ winner: AuthorityType, reason: string }}
+ */
+export function compareAuthority(a, b) {
+  const precA = AUTHORITY_PRECEDENCE[a] || 6;
+  const precB = AUTHORITY_PRECEDENCE[b] || 6;
+
+  if (precA < precB) {
+    return { winner: a, reason: `${a} has higher precedence than ${b}` };
+  }
+  if (precB < precA) {
+    return { winner: b, reason: `${b} has higher precedence than ${a}` };
+  }
+
+  // Same precedence - use timestamp or other tiebreaker
+  return { winner: a, reason: "same precedence, first wins" };
+}
+
+/**
+ * Create a conflict object from two contradicting nodes.
+ *
+ * @param {Object} nodeA
+ * @param {Object} nodeB
+ * @param {string} type - "contradiction" | "invalidation"
+ * @returns {Conflict}
+ */
+export function createConflict(nodeA, nodeB, type = "contradiction") {
+  const authorityA = getAuthorityType(nodeA);
+  const authorityB = getAuthorityType(nodeB);
+
+  const { winner, reason } = compareAuthority(authorityA, authorityB);
+
+  return {
+    id: `conflict-${nodeA.id}-${nodeB.id}`,
+    nodeA: nodeA.id,
+    nodeB: nodeB.id,
+    type,
+    authorityA,
+    authorityB,
+    status: "UNRESOLVED",
+    winner: null,
+    reason: "",
+    blocking: false,
+  };
+}
+
+/**
+ * Resolve a conflict based on authority precedence.
+ *
+ * @param {Conflict} conflict
+ * @param {Object} graph - Context graph for node lookup
+ * @returns {Conflict} Resolved conflict
+ */
+export function resolveConflict(conflict, graph) {
+  const nodeA = graph.getNode(conflict.nodeA);
+  const nodeB = graph.getNode(conflict.nodeB);
+
+  if (!nodeA || !nodeB) {
+    conflict.status = "UNRESOLVED";
+    conflict.reason = "One or both nodes not found in graph";
+    return conflict;
+  }
+
+  const authorityA = getAuthorityType(nodeA);
+  const authorityB = getAuthorityType(nodeB);
+
+  const { winner, reason } = compareAuthority(authorityA, authorityB);
+
+  conflict.authorityA = authorityA;
+  conflict.authorityB = authorityB;
+  conflict.winner = winner === authorityA ? conflict.nodeA : conflict.nodeB;
+  conflict.reason = reason;
+  conflict.status = "RESOLVED";
+
+  return conflict;
+}
+
+/**
+ * Check if a conflict should block execution.
+ *
+ * @param {Conflict} conflict
+ * @param {Object} taskContext - Task context for domain detection
+ * @returns {boolean}
+ */
+export function shouldBlock(conflict, taskContext = {}) {
+  if (conflict.status === "UNRESOLVED") {
+    return true;
+  }
+
+  // Check if the conflict affects critical domains
+  const content = (taskContext.content || "").toLowerCase();
+  for (const domain of BLOCKING_TYPES) {
+    if (content.includes(domain)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Generate conflict report for agent consumption.
+ *
+ * @param {Conflict[]} conflicts
+ * @returns {string} Formatted conflict report
+ */
+export function generateConflictReport(conflicts) {
+  if (conflicts.length === 0) {
+    return "";
+  }
+
+  const lines = ["[wam conflicts]"];
+
+  for (const conflict of conflicts) {
+    const status = conflict.status;
+    const winner = conflict.winner ? ` → ${conflict.winner}` : "";
+    lines.push(`  ${conflict.id}: ${conflict.nodeA} vs ${conflict.nodeB} (${status}${winner})`);
+    if (conflict.reason) {
+      lines.push(`    reason: ${conflict.reason}`);
+    }
+  }
+
+  const unresolved = conflicts.filter((c) => c.status === "UNRESOLVED");
+  if (unresolved.length > 0) {
+    lines.push(`  ⚠ ${unresolved.length} unresolved conflict(s) — do not choose silently`);
+  }
+
+  return lines.join("\n");
+}
+
+export { AUTHORITY_PRECEDENCE, BLOCKING_TYPES };