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

package/src/context/context-classification.js

@@ -0,0 +1,199 @@
+/**
+ * Context Classification — categorize context items into semantic types.
+ *
+ * Categories: FACT, OBSERVATION, CLAIM, ASSUMPTION, DECISION,
+ * REQUIREMENT, EVIDENCE, ERROR, ACTION, RESULT.
+ *
+ * Each raw context record is classified by examining its type, content
+ * signals, and metadata flags. The classifier is rule-based and deterministic.
+ */
+
+/** @typedef {"FACT"|"OBSERVATION"|"CLAIM"|"ASSUMPTION"|"DECISION"|"REQUIREMENT"|"EVIDENCE"|"ERROR"|"ACTION"|"RESULT"} ContextCategory */
+
+/**
+ * @typedef {Object} ClassificationResult
+ * @property {ContextCategory} category
+ * @property {number} confidence 0-1
+ * @property {string[]} signals
+ */
+
+// Signal keywords mapped to categories (lowercase matching)
+const CATEGORY_SIGNALS = {
+  FACT: ["is", "are", "was", "were", "has", "have", "contains", "version", "file", "path", "directory", "exists", "size", "hash"],
+  OBSERVATION: ["observed", "noticed", "detected", "saw", "watched", "monitor", "check", "scan", "logged", "found"],
+  CLAIM: ["claim", "assert", "state", "alleged", "purported", "reported"],
+  ASSUMPTION: ["assume", "presume", "hypothesis", "suppose", "likely", "probably", "might", "may", "could"],
+  DECISION: ["decide", "decided", "decision", "chose", "choose", "selected", "approved", "rejected", "resolve", "concluded"],
+  REQUIREMENT: ["must", "should", "required", "requirement", "need to", "necessary", "mandatory", "shall", "must not"],
+  EVIDENCE: ["evidence", "proof", "data", "result", "test", "benchmark", "measure", "metric", "sample"],
+  ERROR: ["error", "fail", "exception", "throw", "crash", "fault", "exception", "bug", "broken", "stack"],
+  ACTION: ["action", "run", "execute", "perform", "task", "step", "do", "implement", "create", "delete", "update"],
+  RESULT: ["result", "outcome", "concluded", "finished", "complete", "success", "passed", "failed", "done"],
+};
+
+// Type-to-category hints (when content signals are ambiguous)
+const TYPE_HINTS = {
+  fact: "FACT",
+  observation: "OBSERVATION",
+  claim: "CLAIM",
+  assumption: "ASSUMPTION",
+  decision: "DECISION",
+  requirement: "REQUIREMENT",
+  evidence: "EVIDENCE",
+  error: "ERROR",
+  action: "ACTION",
+  result: "RESULT",
+  tool_call: "ACTION",
+  tool_result: "RESULT",
+  agent_message: "OBSERVATION",
+  system_message: "FACT",
+  file_modification: "ACTION",
+  git_change: "ACTION",
+  requirement_change: "REQUIREMENT",
+  verification_result: "RESULT",
+  clarification_request: "ACTION",
+  reasoning: "ASSUMPTION",
+  assumption: "ASSUMPTION",
+  plan: "ACTION",
+  rationale: "CLAIM",
+};
+
+/**
+ * Extract text to analyze from a context item.
+ * @param {Object} item
+ * @returns {string}
+ */
+function extractText(item) {
+  if (!item || typeof item !== "object") return "";
+  if (typeof item.content === "string") return item.content;
+  if (typeof item.summary === "string") return item.summary;
+  if (typeof item.description === "string") return item.description;
+  if (item.metadata && typeof item.metadata === "object") {
+    const parts = [
+      item.metadata.summary,
+      item.metadata.description,
+      item.metadata.content,
+    ];
+    return parts.filter(Boolean).join(" ");
+  }
+  return JSON.stringify(item.content || "");
+}
+
+/**
+ * Score a category by counting matching signals in text.
+ * Uses word boundary matching to avoid false positives from substrings.
+ * @param {string} text
+ * @param {string} category
+ * @returns {number}
+ */
+function scoreCategory(text, category) {
+  const signals = CATEGORY_SIGNALS[category] || [];
+  let score = 0;
+  for (const signal of signals) {
+    const s = typeof signal === "string" ? signal : String(signal);
+    const sl = s.toLowerCase();
+    // Word boundary match: either start of string/non-word char before, or end of string/non-word char after
+    const regex = new RegExp(`(?:^|[^a-z0-9_])(${sl.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})(?:[^a-z0-9_]|$)`, "i");
+    if (regex.test(text)) {
+      score += 1;
+    }
+  }
+  return score;
+}
+
+/**
+ * Classify a context item into a category.
+ * @param {Object} item - Context item with type, content, metadata
+ * @returns {ClassificationResult}
+ */
+export function classifyContextItem(item) {
+  if (!item || typeof item !== "object") {
+    return { category: "FACT", confidence: 0.3, signals: ["default"] };
+  }
+
+  const text = extractText(item);
+  const type = (item.type || "").toLowerCase();
+  const metadata = item.metadata || {};
+
+  // Check explicit category in metadata first
+  if (metadata.category && typeof metadata.category === "string") {
+    const cat = metadata.category.toUpperCase();
+    if (Object.keys(CATEGORY_SIGNALS).includes(cat)) {
+      return { category: cat, confidence: 0.95, signals: ["metadata_explicit"] };
+    }
+  }
+
+  // Check explicit classification field
+  if (item.classification && typeof item.classification === "string") {
+    const cat = item.classification.toUpperCase();
+    if (Object.keys(CATEGORY_SIGNALS).includes(cat)) {
+      return { category: cat, confidence: 0.9, signals: ["explicit_classification"] };
+    }
+  }
+
+  // Score by signal keywords (word-boundary matched)
+  const scores = {};
+  for (const [category, signals] of Object.entries(CATEGORY_SIGNALS)) {
+    scores[category] = scoreCategory(text, category);
+  }
+
+  // ERROR gets forced priority only when no other category has a strictly stronger signal count.
+  // A single weak error keyword (e.g. "fail" inside "should fail gracefully") must not preempt
+  // a multi-signal requirement like "must ... should ...".
+  const maxOtherScore = Math.max(
+    ...Object.entries(scores)
+      .filter(([c]) => c !== "ERROR")
+      .map(([, s]) => s),
+  );
+  if (scores.ERROR >= 1 && scores.ERROR >= maxOtherScore) {
+    return { category: "ERROR", confidence: 0.9, signals: ["error_signal"] };
+  }
+
+  // Type-based classification (primary)
+  const typeHint = TYPE_HINTS[type] || "FACT";
+
+  let bestCategory = typeHint;
+  let bestScore = scores[typeHint] || 0;
+  let bestIsTypeHint = typeHint !== "FACT";
+
+  // Override with stronger signal matches
+  for (const [category, score] of Object.entries(scores)) {
+    if (category !== "ERROR" && score > bestScore) {
+      bestScore = score;
+      bestCategory = category;
+      bestIsTypeHint = false;
+    }
+  }
+
+  // Determine confidence
+  let confidence;
+  if (bestIsTypeHint && bestScore === 0) {
+    confidence = 0.6;
+  } else if (bestScore >= 3) {
+    confidence = 0.9;
+  } else if (bestScore >= 1) {
+    confidence = 0.75;
+  } else if (typeHint) {
+    confidence = 0.65;
+  } else {
+    confidence = 0.5;
+  }
+
+  const signals = [];
+  if (metadata.category) signals.push("metadata");
+  if (item.classification) signals.push("explicit");
+  if (typeHint) signals.push(`type:${type}`);
+  if (bestScore > 0) signals.push(`${bestScore}_signals`);
+
+  return { category: bestCategory, confidence, signals };
+}
+
+/**
+ * Batch-classify multiple items.
+ * @param {Object[]} items
+ * @returns {ClassificationResult[]}
+ */
+export function classifyContextItems(items) {
+  if (!Array.isArray(items)) return [];
+  return items.map(classifyContextItem);
+}

package/src/context/context-compaction.js

@@ -0,0 +1,179 @@
+/**
+ * Context Compression — Functions for compacting, deltas, pruning,
+ * and reconstructing context state.
+ *
+ * OpenSpec changes: context-compaction, context-delta, context-pruning,
+ * context-reconstruction (Changes 44-47).
+ */
+
+/**
+ * Change 44 — compactContext
+ * Compresses a full taskState into a minimal context object.
+ *
+ * Change 73 update: Preserves mandatory fields and provenance
+ * metadata explicitly so compacted context retains traceability.
+ */
+export function compactContext(taskState) {
+  const mandatory = (taskState.requirements || []).filter((r) => !r.optional);
+
+  return {
+    // Core mandatory fields (always preserved)
+    currentGoal: taskState.currentGoal || null,
+    mandatoryRequirements: mandatory.map((r) => ({
+      id: r.id,
+      status: r.status,
+      provenance: r.provenance || null,
+      mandatory: true,
+    })),
+    currentState: taskState.phase,
+    // Evidence
+    verifiedFacts: (taskState.requirements || []).filter((r) => r.status === "VERIFIED").map((r) => ({
+      id: r.id,
+      provenance: r.provenance || null,
+    })),
+    openQuestions: (taskState.questions || []).filter((q) => q.status === "OPEN").map((q) => q.id),
+    evidenceGaps: taskState.evidenceGaps || [],
+    contextGaps: taskState.contextGaps || [],
+    recentActions: (taskState.actions || []).slice(-5),
+    nextConstraint: taskState.nextConstraint || null,
+    // Provenance tracking (Change 73)
+    _provenance: {
+      source: taskState.source || "task_state",
+      mandatoryCount: mandatory.length,
+      compressedAt: taskState.compressedAt || Date.now(),
+      retainedFields: [
+        "currentGoal",
+        "mandatoryRequirements",
+        "currentState",
+        "verifiedFacts",
+        "openQuestions",
+        "evidenceGaps",
+        "contextGaps",
+        "recentActions",
+        "nextConstraint",
+      ],
+    },
+  };
+}
+
+/**
+ * Change 73 — preserveMandatoryProvenance
+ * Explicitly marks which fields in a compacted context are
+ * mandatory and must never be stripped by downstream processors.
+ */
+export function preserveMandatoryProvenance(compacted) {
+  return {
+    ...compacted,
+    _mandatoryFields: [
+      "currentGoal",
+      "mandatoryRequirements",
+      "currentState",
+      "verifiedFacts",
+    ],
+    _provenance: {
+      ...(compacted._provenance || {}),
+      preservationGuaranteed: true,
+    },
+  };
+}
+
+/**
+ * Change 45 — computeContextDelta
+ * Computes the delta between two context snapshots.
+ */
+export function computeContextDelta(previousContext, currentContext) {
+  const delta = {
+    unchanged: [],
+    new: [],
+    invalidated: [],
+    modified: [],
+  };
+
+  const prevKeys = new Set(Object.keys(previousContext));
+  const currKeys = new Set(Object.keys(currentContext));
+
+  // New keys
+  for (const key of currKeys) {
+    if (!prevKeys.has(key)) {
+      delta.new.push(key);
+    }
+  }
+
+  // Removed/invalidated
+  for (const key of prevKeys) {
+    if (!currKeys.has(key)) {
+      delta.invalidated.push(key);
+    }
+  }
+
+  // Modified
+  for (const key of currKeys) {
+    if (prevKeys.has(key) && JSON.stringify(previousContext[key]) !== JSON.stringify(currentContext[key])) {
+      delta.modified.push(key);
+    }
+  }
+
+  // Unchanged
+  for (const key of currKeys) {
+    if (prevKeys.has(key) && !delta.modified.includes(key) && !delta.new.includes(key)) {
+      delta.unchanged.push(key);
+    }
+  }
+
+  return delta;
+}
+
+/**
+ * Change 46 — pruneContext
+ * Prunes context based on configurable rules.
+ */
+export function pruneContext(context, rules = {}) {
+  const {
+    removeIrrelevant = true,
+    removeDuplicate = true,
+    removeStale = true,
+    removeInvalidated = true,
+    keepHistory = true,
+  } = rules;
+
+  let pruned = { ...context };
+
+  if (removeStale && pruned.staleItems) {
+    pruned.activeItems = (pruned.activeItems || []).filter(i => !pruned.staleItems.includes(i.id));
+  }
+
+  if (removeInvalidated && pruned.invalidatedItems) {
+    pruned.activeItems = (pruned.activeItems || []).filter(i => !pruned.invalidatedItems.includes(i.id));
+  }
+
+  if (removeDuplicate && pruned.activeItems) {
+    const seen = new Set();
+    pruned.activeItems = (pruned.activeItems || []).filter(i => {
+      if (seen.has(i.id)) return false;
+      seen.add(i.id);
+      return true;
+    });
+  }
+
+  return pruned;
+}
+
+/**
+ * Change 47 — reconstructContext
+ * Reconstructs a condensed context from WAM state.
+ */
+export function reconstructContext(wamState) {
+  const { requirements = [], evidence = [], gaps = [], tasks = [] } = wamState;
+
+  return {
+    requirements: requirements.map(r => ({
+      id: r.id,
+      status: r.status,
+      claim: r.claim,
+    })),
+    verifiedFacts: requirements.filter(r => r.status === "VERIFIED").map(r => r.id),
+    invalidFacts: requirements.filter(r => r.status === "INVALIDATED").map(r => r.id),
+    openGaps: gaps.filter(g => g.status === "OPEN"),
+    recentTasks: tasks.slice(-3),
+  };
+}

package/src/context/context-decision-audit.js

@@ -0,0 +1,267 @@
+
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../integration/logger.js";
+
+/**
+ * ContextDecisionTracer
+ *
+ * Handles audit logging for context decision processes.
+ * Ensures persistence to .wam/traces/<trace_id>.json with fail-safe behavior.
+ */
+export class ContextDecisionTracer {
+  constructor(traceId, projectRoot, mode = "standard") {
+    this.traceId = traceId;
+    this.projectRoot = projectRoot || process.cwd();
+    this.mode = mode; // minimal, standard, debug
+    this.ledger = {
+      traceId,
+      timestamp: new Date().toISOString(),
+      entries: [],
+    };
+  }
+
+  _getTraceFile() {
+    let current = this.projectRoot;
+    
+    while (current !== path.parse(current).root) {
+      if (fs.existsSync(path.join(current, ".wam"))) {
+        // Verify this is a project root to avoid accidental jumps
+        const isProjectRoot = fs.existsSync(path.join(current, "package.json")) || 
+                             fs.existsSync(path.join(current, ".opencode.jsonc"));
+        
+        if (isProjectRoot) {
+          const traceDir = path.join(current, ".wam", "traces");
+          if (!fs.existsSync(traceDir)) {
+            fs.mkdirSync(traceDir, { recursive: true });
+          }
+          return path.join(traceDir, `${this.traceId}.json`);
+        }
+      }
+      current = path.dirname(current);
+    }
+
+    // Fallback to original behavior if no qualified root found
+    const traceDir = path.join(this.projectRoot, ".wam", "traces");
+    if (!fs.existsSync(traceDir)) {
+      fs.mkdirSync(traceDir, { recursive: true });
+    }
+    return path.join(traceDir, `${this.traceId}.json`);
+  }
+
+  _persist() {
+    let tracePath;
+    try {
+      tracePath = this._getTraceFile();
+      logger.info("AuditPersist", `traceId: ${this.traceId}, entries: ${this.ledger.entries.length}, path: ${tracePath}`);
+      if (this.ledger.entries.length === 0) {
+        logger.warn("AuditEmpty", `Attempting to persist empty ledger for trace ${this.traceId}`);
+      }
+      fs.writeFileSync(tracePath, JSON.stringify(this.ledger, null, 2));
+      logger.info("AuditSuccess", `Persisted trace to: ${tracePath}`);
+    } catch (err) {
+      logger.error("AuditFail", `Path: ${tracePath ?? "<unresolved>"} | Error: ${err?.message ?? err}`);
+    }
+  }
+
+  _addEntry(type, data) {
+    // _persist() already swallows persistence failures; ledger update is in-memory only.
+    this.ledger.entries.push({
+      type,
+      timestamp: new Date().toISOString(),
+      ...data,
+    });
+    this._persist();
+  }
+
+  logConceptExtraction(concept, metadata = {}) {
+    this._addEntry("CONCEPT_EXTRACTION", { concept, metadata });
+  }
+
+  logDictionaryResolution(term, resolution, metadata = {}) {
+    this._addEntry("DICTIONARY_RESOLUTION", { term, resolution, metadata });
+  }
+
+  logCandidateRetrieval(query, candidatesCount, metadata = {}) {
+    this._addEntry("CANDIDATE_RETRIEVAL", { query, candidatesCount, metadata });
+  }
+
+  logSelectionDecision(candidateId, evidenceClassification, reason, metadata = {}) {
+    this._addEntry("SELECTION_DECISION", {
+      candidateId,
+      evidenceClassification, // e.g., 'direct', 'inferred', 'probabilistic'
+      reason,
+      metadata,
+    });
+  }
+
+  /**
+   * Registra una decisión técnica con punto de bifurcación, racional, alternativas
+   * evaluadas, evidencia y métricas técnicas opcionales. Usado por el Decision Gate
+   * para forzar documentación de elecciones arquitectónicas o de modelo de datos.
+   *
+   * @param {string} decisionPoint  - Qué se decidió (ej: "nuevo servicio X", "cambio de schema Y").
+   * @param {string} rationale      - Por qué se eligió esta ruta.
+   * @param {Array}  alternatives   - Alternativas descartadas [{name, pros, cons, whyRejected}].
+   * @param {Array}  evidence       - Evidencia técnica (benchmarks, docs, RFCs, links, file:line).
+   * @param {Object} [technicalMetrics] - Métricas técnicas (latencia, costo, complejidad, etc.).
+   */
+  logTechnicalDecision(decisionPoint, rationale, alternatives, evidence, technicalMetrics = {}) {
+    this._addEntry("TECHNICAL_DECISION", {
+      decisionPoint,
+      rationale,
+      alternatives: Array.isArray(alternatives) ? alternatives : [],
+      evidence: Array.isArray(evidence) ? evidence : [],
+      technicalMetrics: technicalMetrics || {},
+    });
+  }
+}
+
+/**
+ * Valid sources per spec: N0_POLICY, N1_PROJECT, N2_TASK, OBSERVED
+ */
+const VALID_SOURCES = new Set(["N0_POLICY", "N1_PROJECT", "N2_TASK", "OBSERVED"]);
+const VALID_CONFIDENCE = new Set(["high", "medium", "low"]);
+const VALID_STATUS = new Set(["accepted", "rejected", "provisional"]);
+
+/**
+ * Audit a single context-influenced decision and append to contract.contextDecisions.
+ * Per spec: { id, date, source, statement, reason, confidence, status }
+ *
+ * @param {Object} contract     - The task contract (must have contextDecisions array, or one is created)
+ * @param {Object} decision     - { statement, reason, source, confidence, status }
+ * @returns {Object} the recorded decision entry
+ */
+export function auditDecision(contract, decision) {
+  if (!contract || typeof contract !== "object") {
+    throw new Error("auditDecision: contract must be an object");
+  }
+  if (!decision || typeof decision !== "object") {
+    throw new Error("auditDecision: decision must be an object");
+  }
+
+  const { statement, reason, source, confidence, status } = decision;
+
+  if (typeof statement !== "string" || statement.length === 0) {
+    throw new Error("auditDecision: statement is required");
+  }
+  if (typeof reason !== "string" || reason.length === 0) {
+    throw new Error("auditDecision: reason is required");
+  }
+  if (!VALID_SOURCES.has(source)) {
+    throw new Error(
+      `auditDecision: source must be one of N0_POLICY|N1_PROJECT|N2_TASK|OBSERVED (got: ${source})`,
+    );
+  }
+  if (!VALID_CONFIDENCE.has(confidence)) {
+    throw new Error(
+      `auditDecision: confidence must be high|medium|low (got: ${confidence})`,
+    );
+  }
+  if (!VALID_STATUS.has(status)) {
+    throw new Error(
+      `auditDecision: status must be accepted|rejected|provisional (got: ${status})`,
+    );
+  }
+
+  if (!Array.isArray(contract.contextDecisions)) {
+    contract.contextDecisions = [];
+  }
+
+  const id = `CD${contract.contextDecisions.length + 1}`;
+  const entry = {
+    id,
+    date: new Date().toISOString(),
+    source,
+    statement,
+    reason,
+    confidence,
+    status,
+  };
+  contract.contextDecisions.push(entry);
+  return entry;
+}
+
+/**
+ * Inspect the audit trail: returns the contract.contextDecisions array
+ * (or an empty list if none).
+ */
+export function inspectAudit(contract) {
+  if (!contract || typeof contract !== "object") return [];
+  return Array.isArray(contract.contextDecisions) ? contract.contextDecisions : [];
+}
+
+/**
+ * Audit gate. Returns { allowed, reason } indicating whether completion /
+ * approval is permitted.
+ *
+ * Rule: any decision that is (status === "provisional") OR (status ===
+ * "accepted" AND confidence === "low") is treated as a CRITICAL unverified
+ * context decision and blocks completion until resolved (accepted with
+ * medium/high, or rejected).
+ */
+export function auditGate(contract) {
+  const decisions = inspectAudit(contract);
+  const blocking = decisions.filter(
+    (d) =>
+      d.status === "provisional" ||
+      (d.status === "accepted" && d.confidence === "low"),
+  );
+  if (blocking.length === 0) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: `Blocked by ${blocking.length} unverified context decision(s): ${blocking
+      .map((d) => d.id)
+      .join(", ")}`,
+    blocking,
+  };
+}
+
+/**
+ * Resolve a decision by id (used by /wam resolve-decision CLI).
+ * Updates status/confidence on the matching entry.
+ */
+export function resolveDecision(contract, id, updates) {
+  if (!contract || typeof contract !== "object") {
+    throw new Error("resolveDecision: contract must be an object");
+  }
+  const decisions = inspectAudit(contract);
+  const idx = decisions.findIndex((d) => d.id === id);
+  if (idx === -1) {
+    throw new Error(`resolveDecision: decision ${id} not found`);
+  }
+  if (!updates || typeof updates !== "object") {
+    throw new Error("resolveDecision: updates must be an object");
+  }
+  const current = decisions[idx];
+  if (updates.status !== undefined) {
+    if (!VALID_STATUS.has(updates.status)) {
+      throw new Error(
+        `resolveDecision: status must be accepted|rejected|provisional`,
+      );
+    }
+    current.status = updates.status;
+  }
+  if (updates.confidence !== undefined) {
+    if (!VALID_CONFIDENCE.has(updates.confidence)) {
+      throw new Error(`resolveDecision: confidence must be high|medium|low`);
+    }
+    current.confidence = updates.confidence;
+  }
+  if (updates.statement !== undefined) {
+    if (typeof updates.statement !== "string" || updates.statement.length === 0) {
+      throw new Error("resolveDecision: statement must be a non-empty string");
+    }
+    current.statement = updates.statement;
+  }
+  if (updates.reason !== undefined) {
+    if (typeof updates.reason !== "string" || updates.reason.length === 0) {
+      throw new Error("resolveDecision: reason must be a non-empty string");
+    }
+    current.reason = updates.reason;
+  }
+  decisions[idx] = current;
+  return current;
+}