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

package/src/cognition/cognitive-state.js

@@ -0,0 +1,126 @@
+
+import fs from "node:fs";
+import {
+  createHypothesis,
+  listHypotheses,
+  updateHypothesisStatus,
+  archiveHypothesis,
+  HYPOTHESIS_STATUS,
+} from "./cognition-store.js";
+
+/**
+ * Cognitive State facade — delegates to cognition-store.js (single source of truth).
+ *
+ * Mantiene compatibilidad con la API previa (loadCognitiveState, saveCognitiveState,
+ * addActiveHypothesis, rejectHypothesis, recordExperiment, recordObservation,
+ * compactCognitiveState) pero toda persistencia se redirige a
+ * `.wam/tasks/<taskId>/cognition/*.jsonl` vía cognition-store.
+ *
+ * Si el caller no provee taskId, se intenta derivar de la convención:
+ * taskRoot/.wam/tasks/<taskId>/  →  primer taskId encontrado.
+ */
+
+const DEFAULT_STATE = {
+  activeHypotheses: [],
+  rejectedHypotheses: [],
+  recentExperiments: [],
+  criticalObservations: [],
+  lastUpdated: null,
+};
+
+function resolveTaskId(taskRoot, explicitTaskId) {
+  if (explicitTaskId) return explicitTaskId;
+  // Convención: el primer directorio bajo .wam/tasks/
+  const tasksRoot = `${taskRoot}/.wam/tasks`;
+  try {
+    const entries = fs.readdirSync(tasksRoot, { withFileTypes: true });
+    const dir = entries.find((e) => e.isDirectory());
+    return dir ? dir.name : "default";
+  } catch {
+    return "default";
+  }
+}
+
+function buildStateFromStore(taskRoot, taskId) {
+  const all = listHypotheses(taskRoot, taskId);
+  const active = all.filter((h) =>
+    h.status === HYPOTHESIS_STATUS.PROPOSED || h.status === HYPOTHESIS_STATUS.TESTING
+  );
+  const rejected = all.filter((h) => h.status === HYPOTHESIS_STATUS.REJECTED);
+  const archived = all.filter((h) => h.status === HYPOTHESIS_STATUS.ARCHIVED);
+  const rejectedHypotheses = [...rejected, ...archived];
+  return {
+    activeHypotheses: active,
+    rejectedHypotheses,
+    recentExperiments: [],
+    criticalObservations: [],
+    lastUpdated: Date.now(),
+  };
+}
+
+export function loadCognitiveState(taskRoot, taskId) {
+  const tid = resolveTaskId(taskRoot, taskId);
+  return buildStateFromStore(taskRoot, tid);
+}
+
+/**
+ * @deprecated La persistencia ahora vive en cognition-store.js.
+ * Esta función queda como no-op para no romper callers que aún la invocan.
+ */
+export function saveCognitiveState(_taskRoot, _state) {
+  // no-op: cognition-store es la única fuente de verdad.
+}
+
+export function addActiveHypothesis(taskRoot, hypothesis, taskId) {
+  const tid = resolveTaskId(taskRoot, taskId);
+  createHypothesis(taskRoot, tid, {
+    statement: hypothesis.statement,
+    confidence: hypothesis.confidence ?? 0.5,
+  });
+}
+
+export function rejectHypothesis(taskRoot, hypothesisId, reason, taskId) {
+  const tid = resolveTaskId(taskRoot, taskId);
+  updateHypothesisStatus(taskRoot, tid, hypothesisId, HYPOTHESIS_STATUS.REJECTED);
+  // reason se preserva como entrada archivada para trazabilidad.
+  archiveHypothesis(taskRoot, tid, hypothesisId, reason || "rejected");
+}
+
+/**
+ * @deprecated Los experimentos se persisten vía cognition-store.createExperiment().
+ * Esta función queda como no-op.
+ */
+export function recordExperiment(_taskRoot, _experiment, _taskId) {
+  // no-op
+}
+
+/**
+ * @deprecated Las observaciones se persisten vía cognition-store.recordObservation().
+ * Esta función queda como no-op.
+ */
+export function recordObservation(_taskRoot, _observation, _taskId) {
+  // no-op
+}
+
+/**
+ * Compact cognitive state for context injection.
+ * Drops redundant observations, keeps actionable signal.
+ */
+export function compactCognitiveState(state, maxBytes = 1500) {
+  const compact = {
+    activeHypotheses: state.activeHypotheses.slice(0, 3),
+    rejectedHypotheses: state.rejectedHypotheses.slice(-3),
+    recentExperiments: state.recentExperiments.slice(-3),
+    criticalObservations: state.criticalObservations.slice(-3),
+  };
+  const json = JSON.stringify(compact);
+  if (json.length <= maxBytes) return compact;
+
+  // Aggressive truncation: keep only counts
+  return {
+    activeHypotheses: compact.activeHypotheses.slice(0, 1),
+    rejectedHypotheses: compact.rejectedHypotheses.length,
+    recentExperiments: compact.recentExperiments.length,
+    criticalObservations: compact.criticalObservations.length,
+  };
+}

package/src/cognition/hypothesis-manager.js

@@ -0,0 +1,113 @@
+/**
+ * Hypothesis contradiction tracking.
+ * Called when an observation contradicts the active hypothesis.
+ * Triggers strategy replanning (INVESTIGATING → new hypothesis).
+ *
+ * Signature (backward compatible):
+ *   noteContradiction(hypothesisId, observation, assessment)
+ *   noteContradiction(taskId, hypothesisId, observation, assessment, root)
+ *
+ * When a hypothesis is rejected, dependent evidence is marked STALE
+ * so the linked requirement returns to PENDING and must be replanned.
+ */
+
+import { invalidateDependentEvidence, getAllEvidence } from "../evidence/evidence-lineage.js";
+import { persistTaskState, getTaskState } from "../skills/engine.js";
+
+function isAssessment(value) {
+  return value && typeof value === "object" && Array.isArray(value.comparisons);
+}
+
+/**
+ * Reject a hypothesis after a contradicting observation and stale any
+ * evidence that was produced under that hypothesis.
+ *
+ * @returns {{ type: string, hypothesisId: string, detail: string, staleEvidence: Array, pendingRequirements: string[] }}
+ */
+export function noteContradiction(hypothesisIdOrTaskId, observationOrHypothesisId, assessmentOrObservation, maybeAssessment, maybeRoot) {
+  let taskId = null;
+  let hypothesisId;
+  let observation;
+  let assessment;
+  let root;
+
+  if (isAssessment(assessmentOrObservation) && maybeAssessment === undefined) {
+    // noteContradiction(hypothesisId, observation, assessment)
+    hypothesisId = hypothesisIdOrTaskId;
+    observation = observationOrHypothesisId;
+    assessment = assessmentOrObservation;
+  } else {
+    // noteContradiction(taskId, hypothesisId, observation, assessment, root)
+    taskId = hypothesisIdOrTaskId;
+    hypothesisId = observationOrHypothesisId;
+    observation = assessmentOrObservation;
+    assessment = maybeAssessment;
+    root = maybeRoot;
+  }
+
+  const comparisons = assessment?.comparisons || [];
+  const conflictFields = comparisons
+    .filter((c) => c.status === "CONTRADICTED")
+    .map((c) => `${c.field}: expected ${JSON.stringify(c.expected)}, got ${JSON.stringify(c.actual)}`);
+
+  const detail = conflictFields.length > 0
+    ? `Contradicted fields: ${conflictFields.join("; ")}.`
+    : `Observation contradicted hypothesis "${hypothesisId}".`;
+
+  let staleEvidence = [];
+  const pendingRequirements = [];
+
+  if (taskId) {
+    staleEvidence = invalidateDependentEvidence(taskId, hypothesisId, detail, root) || [];
+    const requirementIds = [...new Set(staleEvidence.map((e) => e.requirementId).filter(Boolean))];
+    if (requirementIds.length > 0) {
+      const state = getTaskState(taskId, root);
+      if (state?.requirements) {
+        for (const req of state.requirements) {
+          if (requirementIds.includes(req.id)) {
+            req.status = "pending";
+            req.replan = true;
+            pendingRequirements.push(req.id);
+          }
+        }
+        persistTaskState(taskId, state, root);
+      }
+    }
+  } else {
+    // In-memory form used by unit tests / execution-engine (no persistence).
+    staleEvidence = [];
+  }
+
+  return {
+    type: "CONTRADICTION",
+    hypothesisId,
+    assessmentResult: assessment?.result,
+    reasoning: assessment?.reasoning,
+    detail,
+    observed: observation,
+    timestamp: Date.now(),
+    hypothesisStatus: "rejected",
+    staleEvidence,
+    pendingRequirements,
+    replan: true,
+  };
+}
+
+/**
+ * After a contradiction, mark every requirement that depended on the
+ * rejected hypothesis as PENDING so the planner must replan.
+ */
+export function revertRequirementsToPending(taskId, hypothesisId, root) {
+  const evidence = getAllEvidence(taskId, root).filter((e) => e.hypothesisId === hypothesisId);
+  const requirementIds = [...new Set(evidence.map((e) => e.requirementId).filter(Boolean))];
+  const state = getTaskState(taskId, root);
+  if (!state?.requirements) return requirementIds;
+  for (const req of state.requirements) {
+    if (requirementIds.includes(req.id)) {
+      req.status = "pending";
+      req.replan = true;
+    }
+  }
+  persistTaskState(taskId, state, root);
+  return requirementIds;
+}

package/src/cognition/observation-engine.js

@@ -0,0 +1,112 @@
+/**
+ * Observation Engine — records raw observations for the hypothesis→experiment loop.
+ *
+ * Pure extraction of observation persistence from execution-engine.js.
+ * Owns: the contract of what an observation IS and how it gets persisted.
+ * Does NOT own: assessment, evidence creation, or hypothesis status transitions
+ * (those live in evidence-engine.js and state-machine.js).
+ *
+ * A raw observation captures: what actually happened (actual), anything that
+ * diverged from the plan (unexpected), provenance (which experiment), and
+ * the assessment result + facts that led to recording it.
+ *
+ * Source of truth for the observation record shape and JSONL append path.
+ */
+
+import {
+  recordObservation,
+  getExperiment,
+} from "./cognition-store.js";
+import { AssessmentResult } from "../policy/assessment-engine.js";
+
+/**
+ * Build a raw observation payload from inputs (pure, no I/O).
+ * @param {object} args
+ * @param {string|null} args.experimentId
+ * @param {string} args.hypothesisId
+ * @param {string} args.result - AssessmentResult enum value
+ * @param {string[]} args.facts - List of fact strings (e.g. evidence ids, error messages)
+ * @param {*} [args.actual]
+ * @param {string[]} [args.unexpected]
+ * @param {object} [args.provenance]
+ * @returns {object} observation payload
+ */
+export function buildObservationPayload({
+  experimentId,
+  hypothesisId,
+  result,
+  facts,
+  actual,
+  unexpected,
+  provenance,
+}) {
+  return {
+    experimentId: experimentId ?? null,
+    hypothesisId,
+    result,
+    facts: Array.isArray(facts) ? facts : [],
+    actual: actual ?? null,
+    unexpected: Array.isArray(unexpected) ? unexpected : [],
+    provenance: provenance ?? null,
+  };
+}
+
+/**
+ * Resolve the experiment record (if known) for the observation context.
+ * Returns null when no experimentId is provided or the experiment cannot be found.
+ *
+ * @param {string} taskRoot
+ * @param {string} taskId
+ * @param {object} args
+ * @param {string|null} args.experimentId
+ * @param {string} args.hypothesisId
+ * @returns {object|null}
+ */
+export function resolveExperimentContext(taskRoot, taskId, { experimentId, hypothesisId }) {
+  if (!experimentId) return null;
+  const stored = getExperiment(taskRoot, taskId, experimentId);
+  return stored ?? { id: experimentId, hypothesisId };
+}
+
+/**
+ * Default fact-derivation strategy used by noteFailure / noteSuccess.
+ * Pure: given inputs, returns facts list. Centralized here so observation
+ * contracts stay consistent across callers.
+ *
+ * @param {object} args
+ * @param {string} args.outcome - "success" | "failure"
+ * @param {string} [args.reason]
+ * @param {*} [args.result]
+ * @param {string[]} [args.facts] - pre-built facts (e.g. [evidenceId]); wins if present
+ * @returns {string[]}
+ */
+export function deriveDefaultFacts({ outcome, reason, result, facts }) {
+  if (Array.isArray(facts) && facts.length > 0) return facts;
+  if (outcome === "failure") return reason ? [reason] : ["failure"];
+  if (typeof result === "string") return [result];
+  if (result === undefined || result === null) return ["ok"];
+  return [JSON.stringify(result)];
+}
+
+/**
+ * Record a raw observation. Wraps the cognition-store append with the
+ * observation-engine contract: payload shape, fact derivation, and
+ * experiment-context resolution.
+ *
+ * @param {string} taskRoot
+ * @param {string} taskId
+ * @param {object} args - see buildObservationPayload + deriveDefaultFacts
+ * @returns {object} persisted observation record
+ */
+export function recordRawObservation(taskRoot, taskId, args) {
+  const experiment = resolveExperimentContext(taskRoot, taskId, args);
+  const facts = deriveDefaultFacts(args);
+  const payload = buildObservationPayload({ ...args, facts });
+  const persisted = recordObservation(taskRoot, taskId, {
+    ...payload,
+    experimentId: experiment?.id ?? payload.experimentId,
+  });
+  return { observation: persisted, experiment };
+}
+
+export { AssessmentResult };

package/src/cognition/observation-provenance.js

@@ -0,0 +1,268 @@
+/**
+ * Observation Provenance — unified observation format with provenance tracking.
+ *
+ * Unifies observation format across task-runs, cognitive-state, and cognition-store.
+ * Adds provenance tracking with source, confidence, and session binding.
+ *
+ * Provenance types:
+ *   - user_decided: explicitly decided by user (highest confidence)
+ *   - observed: directly observed from execution (medium confidence)
+ *   - inferred: inferred from other observations (lower confidence)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {"user_decided" | "observed" | "inferred"} ProvenanceType
+ */
+
+/**
+ * @typedef {Object} Provenance
+ * @property {ProvenanceType} source - How this observation was obtained
+ * @property {number} confidence - 0-1 confidence level
+ * @property {string} sessionId - Session that created this observation
+ * @property {string} taskId - Task this observation belongs to
+ * @property {string} parentId - Parent observation (for inferred chains)
+ */
+
+/**
+ * @typedef {Object} Observation
+ * @property {string} id
+ * @property {string} text
+ * @property {number} timestamp
+ * @property {Provenance} provenance
+ */
+
+/** Default confidence by provenance type */
+const DEFAULT_CONFIDENCE = {
+  user_decided: 1.0,
+  observed: 0.8,
+  inferred: 0.5,
+};
+
+/** Valid provenance types */
+const VALID_PROVENANCE = new Set(["user_decided", "observed", "inferred"]);
+
+/**
+ * Create a new observation with provenance.
+ *
+ * @param {string} text - Observation text
+ * @param {ProvenanceType} source - Provenance type
+ * @param {Object} options - Additional options
+ * @returns {Observation}
+ */
+export function createObservation(text, source = "observed", options = {}) {
+  const provenanceType = VALID_PROVENANCE.has(source) ? source : "observed";
+
+  return {
+    id: options.id || `obs-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    text,
+    timestamp: options.timestamp || Date.now(),
+    provenance: {
+      source: provenanceType,
+      confidence: options.confidence ?? DEFAULT_CONFIDENCE[provenanceType],
+      sessionId: options.sessionId || null,
+      taskId: options.taskId || null,
+      parentId: options.parentId || null,
+    },
+  };
+}
+
+/**
+ * Validate observation provenance.
+ *
+ * @param {Observation} observation
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateObservation(observation) {
+  const errors = [];
+
+  if (!observation.id) {
+    errors.push("Missing observation id");
+  }
+
+  if (!observation.text || typeof observation.text !== "string") {
+    errors.push("Missing or invalid observation text");
+  }
+
+  if (typeof observation.timestamp !== "number") {
+    errors.push("Missing or invalid timestamp");
+  }
+
+  if (!observation.provenance) {
+    errors.push("Missing provenance");
+  } else {
+    if (!VALID_PROVENANCE.has(observation.provenance.source)) {
+      errors.push(`Invalid provenance source: ${observation.provenance.source}`);
+    }
+
+    if (
+      typeof observation.provenance.confidence !== "number" ||
+      observation.provenance.confidence < 0 ||
+      observation.provenance.confidence > 1
+    ) {
+      errors.push(`Invalid confidence: ${observation.provenance.confidence}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Check if an observation can be promoted to a higher level.
+ *
+ * @param {Observation} observation
+ * @param {string} targetLevel - Target level (L1, L2, L3, L4)
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function canPromoteObservation(observation, targetLevel) {
+  if (!observation.provenance) {
+    return { allowed: false, reason: "Missing provenance" };
+  }
+
+  const { source, confidence } = observation.provenance;
+
+  // Inferred observations cannot promote to L1
+  if (source === "inferred" && targetLevel === "L1") {
+    return {
+      allowed: false,
+      reason: "Inferred observations cannot promote to L1 (user_decided required)",
+    };
+  }
+
+  // Low confidence observations cannot promote to L1
+  if (confidence < 0.6 && targetLevel === "L1") {
+    return {
+      allowed: false,
+      reason: `Confidence ${confidence} too low for L1 promotion (requires >= 0.6)`,
+    };
+  }
+
+  // Observed observations can promote to L2-L4
+  if (source === "observed" && confidence >= 0.6) {
+    return { allowed: true, reason: "Observed with sufficient confidence" };
+  }
+
+  // User decided can promote anywhere
+  if (source === "user_decided") {
+    return { allowed: true, reason: "User decided observations can promote anywhere" };
+  }
+
+  return { allowed: false, reason: "Insufficient provenance for promotion" };
+}
+
+/**
+ * Create a derived observation from an existing one.
+ * Preserves the observation chain for auditability.
+ *
+ * @param {Observation} parent - Parent observation
+ * @param {string} text - Derived observation text
+ * @param {ProvenanceType} source - How this was derived
+ * @returns {Observation}
+ */
+export function deriveObservation(parent, text, source = "inferred") {
+  return createObservation(text, source, {
+    sessionId: parent.provenance.sessionId,
+    taskId: parent.provenance.taskId,
+    parentId: parent.id,
+    confidence: Math.min(parent.provenance.confidence, DEFAULT_CONFIDENCE[source]),
+  });
+}
+
+/**
+ * Load observations from a JSONL file.
+ *
+ * @param {string} filePath
+ * @returns {Observation[]}
+ */
+export function loadObservations(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    const observations = [];
+
+    for (const line of lines) {
+      try {
+        const obs = JSON.parse(line);
+        if (obs.provenance) {
+          observations.push(obs);
+        }
+      } catch {}
+    }
+
+    return observations;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save observations to a JSONL file.
+ *
+ * @param {string} filePath
+ * @param {Observation[]} observations
+ */
+export function saveObservations(filePath, observations) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const content = observations.map((obs) => JSON.stringify(obs)).join("\n") + "\n";
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * Append an observation to a JSONL file.
+ *
+ * @param {string} filePath
+ * @param {Observation} observation
+ */
+export function appendObservation(filePath, observation) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  fs.appendFileSync(filePath, JSON.stringify(observation) + "\n", "utf-8");
+}
+
+/**
+ * Get provenance summary for a set of observations.
+ *
+ * @param {Observation[]} observations
+ * @returns {Object} Summary statistics
+ */
+export function getProvenanceSummary(observations) {
+  const bySource = {
+    user_decided: 0,
+    observed: 0,
+    inferred: 0,
+  };
+
+  let totalConfidence = 0;
+
+  for (const obs of observations) {
+    if (obs.provenance) {
+      bySource[obs.provenance.source] = (bySource[obs.provenance.source] || 0) + 1;
+      totalConfidence += obs.provenance.confidence;
+    }
+  }
+
+  const total = observations.length;
+  const avgConfidence = total > 0 ? totalConfidence / total : 0;
+
+  return {
+    total,
+    bySource,
+    avgConfidence,
+    highConfidence: observations.filter((o) => o.provenance?.confidence >= 0.8).length,
+    lowConfidence: observations.filter((o) => o.provenance?.confidence < 0.5).length,
+  };
+}
+
+export { VALID_PROVENANCE, DEFAULT_CONFIDENCE };

package/src/context/active-context-boundary.js

@@ -0,0 +1,68 @@
+import { LIFECYCLE_STATES, TERMINAL_STATES } from "./context-lifecycle.js";
+import { CONTEXT_EVENT_TYPES } from "./context-event-ingress.js";
+
+export const ACTIVE_LIFECYCLES = new Set(["CREATED", "ACTIVE"]);
+export const SUPPORTING_LIFECYCLES = new Set(["COMPRESSED", "STALE"]);
+export const EXCLUDED_LIFECYCLES = new Set(["INVALIDATED", "ARCHIVED"]);
+
+export const PURPOSE_MODES = Object.freeze({
+  PLANNING: "PLANNING",
+  IMPLEMENTATION: "IMPLEMENTATION",
+  INVESTIGATION: "INVESTIGATION",
+  DEBUGGING: "DEBUGGING",
+  VALIDATION: "VALIDATION",
+  REVIEW: "REVIEW",
+  RESUME: "RESUME",
+});
+
+export function retrieveActiveContext(items, purpose = PURPOSE_MODES.PLANNING) {
+  const isDebugOrResume = [PURPOSE_MODES.DEBUGGING, PURPOSE_MODES.RESUME].includes(purpose);
+  const includeInvalidated = isDebugOrResume || purpose === PURPOSE_MODES.REPLAN || purpose === PURPOSE_MODES.AUDIT;
+
+  return items.filter((item) => {
+    const lc = item.lifecycle;
+    if (ACTIVE_LIFECYCLES.has(lc)) return true;
+    if (SUPPORTING_LIFECYCLES.has(lc)) return true;
+    if (EXCLUDED_LIFECYCLES.has(lc)) return includeInvalidated;
+    return true;
+  });
+}
+
+export function isContextSufficient(items, purpose = PURPOSE_MODES.PLANNING) {
+  const active = retrieveActiveContext(items, purpose);
+  const activeCount = active.length;
+  const hasCriticalMissing = active.some((item) => {
+    return item.unresolvedCriticalUnknowns?.length > 0;
+  });
+  return {
+    sufficient: activeCount > 0 && !hasCriticalMissing,
+    missing: hasCriticalMissing ? active.flatMap((item) => item.unresolvedCriticalUnknowns || []) : [],
+    activeCount,
+    mandatoryIncluded: active.some((item) => item.mandatoryIncluded === true),
+    unresolvedCriticalUnknowns: hasCriticalMissing ? active.flatMap((item) => item.unresolvedCriticalUnknowns || []) : [],
+  };
+}
+
+export function invalidateContextItems(items, event) {
+  const { reason, invalidatedIds, scope } = event.payload || {};
+  const affected = [];
+
+  for (const item of items) {
+    if (invalidatedIds?.includes(item.id)) {
+      affected.push({ ...item, lifecycle: LIFECYCLE_STATES.INVALIDATED, invalidatedAt: Date.now(), invalidationReason: reason });
+    } else if (EXCLUDED_LIFECYCLES.has(item.lifecycle) && !invalidatedIds?.includes(item.id)) {
+      continue;
+    } else {
+      affected.push(item);
+    }
+  }
+
+  return affected;
+}
+
+export function markItemsStale(items, triggerEvent) {
+  return items.map((item) => {
+    if (EXCLUDED_LIFECYCLES.has(item.lifecycle)) return item;
+    return { ...item, lifecycle: LIFECYCLE_STATES.STALE, staleReason: triggerEvent?.payload?.reason || "context-stale" };
+  });
+}