opencode-goal-mode 0.1.0 → 0.2.1

package/plugins/goal-guard/state.js

@@ -0,0 +1,182 @@
+/**
+ * Per-session guard state and the store that owns it.
+ *
+ * Two correctness fixes versus the original design live here:
+ *
+ *  1. A monotonic `seq` counter (project-scoped) orders every state-changing
+ *     event. Staleness ("is this review newer than the latest edit?") is
+ *     decided by comparing seq numbers, not millisecond ISO strings, so two
+ *     events in the same millisecond can never tie and a review can never be
+ *     accepted as fresh against an edit it did not actually post-date.
+ *
+ *  2. The store is created PER PLUGIN INSTANCE (closure state), not as a module
+ *     global, so concurrent OpenCode projects can no longer cross-contaminate
+ *     each other's verdicts and dirty flags. Eviction is true LRU by last-touch
+ *     time and PREFERS inactive sessions: an active session is only evicted when
+ *     every tracked session is active and the cap is exceeded, in which case the
+ *     least-recently-touched active one is dropped.
+ */
+
+/** @returns a fresh per-session state record. */
+export function createState(nowIso) {
+  const at = nowIso || new Date(0).toISOString();
+  return {
+    active: false,
+    goalText: "",
+    contract: null,
+    stickyGates: [],
+    dirty: false,
+    dirtyReasons: [],
+    changedFiles: [],
+    reviewCycles: 0,
+    lastEditSeq: 0,
+    lastVerificationSeq: 0,
+    lastReviewSeq: 0,
+    lastEditAt: null,
+    lastReviewAt: null,
+    lastVerificationAt: null,
+    verdicts: [],
+    evidence: [],
+    latestVerdict: {},
+    currentAgent: undefined,
+    completedBlocked: 0,
+    completionRejections: [],
+    verificationSeen: false,
+    lastCompletionRejectAt: null,
+    createdAt: at,
+    updatedAt: at,
+    touchedAt: 0,
+  };
+}
+
+const KNOWN_FIELDS = Object.keys(createState());
+
+/** Rebuild a state object from persisted JSON, dropping unknown fields. */
+function reviveState(raw) {
+  const base = createState();
+  if (!raw || typeof raw !== "object") return base;
+  for (const field of KNOWN_FIELDS) {
+    if (raw[field] !== undefined) base[field] = raw[field];
+  }
+  // Defensive normalisation of array/object shapes.
+  for (const arrField of ["dirtyReasons", "changedFiles", "verdicts", "evidence", "completionRejections"]) {
+    if (!Array.isArray(base[arrField])) base[arrField] = [];
+  }
+  if (!base.latestVerdict || typeof base.latestVerdict !== "object") base.latestVerdict = {};
+  return base;
+}
+
+/**
+ * Create a guard store.
+ *
+ * @param {object} opts
+ * @param {number} [opts.maxSessions=200]
+ * @param {number} [opts.ttlMs=0]  Idle TTL in ms (0 disables).
+ * @param {() => number} [opts.clock]  Monotonic-ish wall clock for touch/TTL.
+ */
+export function createStore({ maxSessions = 200, ttlMs = 0, clock = () => Date.now() } = {}) {
+  const sessions = new Map();
+  let seq = 0;
+  let touchCounter = 0;
+
+  const nowIso = () => new Date(clock()).toISOString();
+  const nextSeq = () => (seq += 1);
+
+  function evictIfNeeded() {
+    // Drop TTL-expired idle sessions first.
+    if (ttlMs > 0) {
+      const cutoff = clock() - ttlMs;
+      for (const [key, st] of sessions) {
+        if (st.touchedWall !== undefined && st.touchedWall < cutoff && !st.active) {
+          sessions.delete(key);
+        }
+      }
+    }
+    while (sessions.size >= maxSessions) {
+      let oldestKey = null;
+      let oldest = Infinity;
+      for (const [key, st] of sessions) {
+        // Prefer evicting inactive sessions; only evict active ones if nothing else.
+        const rank = (st.active ? Number.MAX_SAFE_INTEGER / 2 : 0) + (st.touchedAt || 0);
+        if (rank < oldest) {
+          oldest = rank;
+          oldestKey = key;
+        }
+      }
+      if (oldestKey === null) break;
+      sessions.delete(oldestKey);
+    }
+  }
+
+  function touch(st) {
+    st.touchedAt = (touchCounter += 1);
+    st.touchedWall = clock();
+  }
+
+  function stateFor(sessionID) {
+    const key = String(sessionID || "default").trim() || "default";
+    let st = sessions.get(key);
+    if (!st) {
+      evictIfNeeded();
+      st = createState(nowIso());
+      sessions.set(key, st);
+    }
+    touch(st);
+    return st;
+  }
+
+  function snapshot() {
+    return {
+      version: 1,
+      seq,
+      touchCounter,
+      sessions: Array.from(sessions.entries()).map(([key, st]) => [key, st]),
+    };
+  }
+
+  function restore(data) {
+    if (!data || typeof data !== "object") return;
+    if (Number.isFinite(data.seq)) seq = Math.max(seq, data.seq);
+    if (Number.isFinite(data.touchCounter)) touchCounter = Math.max(touchCounter, data.touchCounter);
+    if (Array.isArray(data.sessions)) {
+      const wall = clock();
+      for (const entry of data.sessions) {
+        if (!Array.isArray(entry) || entry.length !== 2) continue;
+        const [key, raw] = entry;
+        const st = reviveState(raw);
+        // Seed a wall time so restored sessions are subject to TTL eviction
+        // (otherwise undefined touchedWall makes them immortal).
+        if (st.touchedWall === undefined) st.touchedWall = wall;
+        sessions.set(String(key), st);
+      }
+    }
+    // Restoring a snapshot must respect the configured cap, or a persisted
+    // oversized store would exceed maxSessions forever (and a later add could
+    // evict a live active session in one burst).
+    while (sessions.size > maxSessions) {
+      let oldestKey = null;
+      let oldest = Infinity;
+      for (const [key, st] of sessions) {
+        const rank = (st.active ? Number.MAX_SAFE_INTEGER / 2 : 0) + (st.touchedAt || 0);
+        if (rank < oldest) {
+          oldest = rank;
+          oldestKey = key;
+        }
+      }
+      if (oldestKey === null) break;
+      sessions.delete(oldestKey);
+    }
+  }
+
+  return {
+    sessions,
+    stateFor,
+    nowIso,
+    nextSeq,
+    seqValue: () => seq,
+    snapshot,
+    restore,
+    size: () => sessions.size,
+    clear: () => sessions.clear(),
+  };
+}

package/plugins/goal-guard/summary.js

@@ -0,0 +1,46 @@
+/**
+ * Human-readable summaries of guard state, used in compaction context, block
+ * messages, and the `goal_status` tool. Kept pure and dependency-light.
+ */
+
+import { requiredGates, missingGates } from "./gates.js";
+
+export function summarizeState(state, config) {
+  const verdictSummary =
+    state.verdicts
+      .slice(-8)
+      .map((v) => `${v.agent}:${v.verdict}`)
+      .join(", ") || "none";
+  return [
+    `active=${Boolean(state.active)}`,
+    `dirty=${Boolean(state.dirty)}`,
+    `reviewCycles=${state.reviewCycles}`,
+    `lastEditSeq=${state.lastEditSeq || 0}`,
+    `lastReviewSeq=${state.lastReviewSeq || 0}`,
+    `recentVerdicts=${verdictSummary}`,
+    `missingGates=${missingGates(state, config).join(" ") || "none"}`,
+    `dirtyReasons=${state.dirtyReasons.slice(-5).join(" | ") || "none"}`,
+  ].join("; ");
+}
+
+/** Structured status object for the goal_status tool / diagnostics. */
+export function statusReport(state, config) {
+  const required = requiredGates(state, config);
+  const missing = missingGates(state, config);
+  return {
+    active: Boolean(state.active),
+    dirty: Boolean(state.dirty),
+    reviewCycles: state.reviewCycles,
+    requiredGates: required,
+    passingGates: required.filter((g) => !missing.includes(g)),
+    missingGates: missing,
+    verificationSeen: Boolean(state.verificationSeen),
+    lastEditAt: state.lastEditAt,
+    lastReviewAt: state.lastReviewAt,
+    lastVerificationAt: state.lastVerificationAt,
+    evidenceCount: state.evidence.length,
+    changedFiles: state.changedFiles.slice(-50),
+    contract: state.contract,
+    completionAllowed: Boolean(state.active) && missing.length === 0,
+  };
+}

package/plugins/goal-guard/system.js

@@ -0,0 +1,43 @@
+/**
+ * Builds the live Goal Guard state block injected into the system prompt via
+ * `experimental.chat.system.transform`. This makes the guard's enforcement
+ * legible to the model on every turn — it always knows the recorded review
+ * cycle count, which gates are missing, and whether completion is currently
+ * allowed — turning the guard from a silent blocker into an active steering
+ * signal. Only emitted for active goal sessions.
+ */
+
+import { statusReport } from "./summary.js";
+
+function bullet(list) {
+  return list.length ? list.join(", ") : "none";
+}
+
+export function buildSystemInjection(state, config) {
+  if (!state || !state.active) return null;
+  const r = statusReport(state, config);
+  const lines = [];
+  lines.push("## Goal Guard — live enforcement state");
+  lines.push(
+    "This block is injected by the goal-guard plugin and reflects authoritative, " +
+      "tracked state. Treat it as ground truth over your own recollection.",
+  );
+
+  if (r.contract && r.contract.acceptanceCriteria && r.contract.acceptanceCriteria.length) {
+    lines.push(`- Goal Contract: ${r.contract.acceptanceCriteria.length} acceptance criteria recorded.`);
+  } else {
+    lines.push("- Goal Contract: not yet recorded. Call `goal_contract` to establish acceptance criteria.");
+  }
+  lines.push(`- Review cycles recorded: ${r.reviewCycles}.`);
+  lines.push(`- Working tree dirty since last clean review: ${r.dirty ? "yes" : "no"}.`);
+  lines.push(`- Verification observed: ${r.verificationSeen ? "yes" : "no"}.`);
+  lines.push(`- Required review gates: ${bullet(r.requiredGates)}.`);
+  lines.push(`- Gates still missing or stale: ${bullet(r.missingGates)}.`);
+  lines.push(
+    `- Completion is currently ${r.completionAllowed ? "ALLOWED" : "BLOCKED"}. ` +
+      (r.completionAllowed
+        ? `You may answer with "${config.completionMarker}" and an accurate "Review cycles: ${r.reviewCycles}" line.`
+        : `Do NOT claim "${config.completionMarker}" yet; resolve the missing gates and re-run review first.`),
+  );
+  return lines.join("\n");
+}

package/plugins/goal-guard/tools.js

@@ -0,0 +1,129 @@
+/**
+ * First-class `goal_*` custom tools.
+ *
+ * These give the model a structured, machine-checked way to interact with the
+ * guard instead of relying on free-text parsing: it can record a Goal Contract,
+ * log verification evidence, and read back authoritative gate status. They are
+ * registered via the plugin `tool` hook (object key == tool name, verbatim).
+ *
+ * The `@opencode-ai/plugin` import is isolated to this module so that, if the
+ * host cannot resolve it, the entry can skip tool registration while the core
+ * guard hooks still load.
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { statusReport } from "./summary.js";
+import { recordEvidence } from "./events.js";
+import { refreshStickyGates } from "./gates.js";
+import { createState } from "./state.js";
+
+const s = tool.schema;
+
+/**
+ * @param {object} deps
+ * @param {ReturnType<import("./state.js").createStore>} deps.store
+ * @param {object} deps.config
+ * @param {() => void} deps.persist  Debounced persistence trigger.
+ */
+export function createGoalTools({ store, config, persist }) {
+  const save = typeof persist === "function" ? persist : () => {};
+
+  return {
+    goal_status: tool({
+      description:
+        "Return the authoritative Goal Guard state for this session: recorded review " +
+        "cycles, required vs. passing vs. missing review gates, dirty/verification status, " +
+        "and whether completion is currently allowed. Read-only.",
+      args: {},
+      async execute(_args, ctx) {
+        const state = store.stateFor(ctx.sessionID);
+        const report = statusReport(state, config);
+        return {
+          title: `Goal status: completion ${report.completionAllowed ? "allowed" : "blocked"}`,
+          output: JSON.stringify(report, null, 2),
+          metadata: { completionAllowed: report.completionAllowed, reviewCycles: report.reviewCycles },
+        };
+      },
+    }),
+
+    goal_contract: tool({
+      description:
+        "Record or update the Goal Contract for this session (the explicit requirements, " +
+        "inferred requirements, non-goals, and acceptance criteria). Establishing a contract " +
+        "activates strict goal enforcement and drives which specialist review gates are required.",
+      args: {
+        original: s.string().describe("The original user request, verbatim or faithfully summarized."),
+        requirements: s.array(s.string()).optional().describe("Explicit requirements stated by the user."),
+        inferred: s.array(s.string()).optional().describe("Reasonable inferred requirements."),
+        nonGoals: s.array(s.string()).optional().describe("Things explicitly out of scope."),
+        acceptanceCriteria: s
+          .array(s.string())
+          .describe("Concrete, checkable acceptance criteria that define done."),
+      },
+      async execute(args, ctx) {
+        const state = store.stateFor(ctx.sessionID);
+        state.active = true;
+        state.contract = {
+          original: String(args.original || ""),
+          requirements: args.requirements || [],
+          inferred: args.inferred || [],
+          nonGoals: args.nonGoals || [],
+          acceptanceCriteria: args.acceptanceCriteria || [],
+          at: store.nowIso(),
+        };
+        state.goalText = [state.goalText, state.contract.original].filter(Boolean).join(" ");
+        refreshStickyGates(state);
+        state.updatedAt = store.nowIso();
+        save();
+        const report = statusReport(state, config);
+        return {
+          title: `Goal Contract recorded (${state.contract.acceptanceCriteria.length} acceptance criteria)`,
+          output:
+            `Goal Contract stored. Required review gates for this goal: ` +
+            `${report.requiredGates.join(", ")}.`,
+          metadata: { requiredGates: report.requiredGates },
+        };
+      },
+    }),
+
+    goal_evidence: tool({
+      description:
+        "Record a piece of verification evidence (a command that was run and its result, " +
+        "optionally the acceptance criteria it covers). Counts as observed verification.",
+      args: {
+        command: s.string().describe("The verification command that was executed."),
+        result: s.string().describe("Pass/fail summary and any salient output."),
+        criteria: s.array(s.string()).optional().describe("Acceptance criteria this evidence covers."),
+      },
+      async execute(args, ctx) {
+        const state = store.stateFor(ctx.sessionID);
+        state.active = true;
+        recordEvidence(store, state, args.command, args.result, args.criteria);
+        save();
+        return {
+          title: "Verification evidence recorded",
+          output: `Recorded evidence for: ${args.command}. Total evidence entries: ${state.evidence.length}.`,
+          metadata: { evidenceCount: state.evidence.length },
+        };
+      },
+    }),
+
+    goal_reset: tool({
+      description:
+        "Clear all Goal Guard state for this session (contract, dirty flags, verdicts, review " +
+        "cycles). Requires confirm=true. Use only when abandoning or restarting a goal.",
+      args: {
+        confirm: s.boolean().describe("Must be true to actually reset."),
+      },
+      async execute(args, ctx) {
+        if (!args.confirm) {
+          return { title: "Reset not confirmed", output: "Pass confirm=true to reset Goal Guard state." };
+        }
+        const fresh = createState(store.nowIso());
+        store.sessions.set(String(ctx.sessionID || "default"), fresh);
+        save();
+        return { title: "Goal Guard state reset", output: "All goal state cleared for this session." };
+      },
+    }),
+  };
+}

package/plugins/goal-guard/verdicts.js

@@ -0,0 +1,87 @@
+/**
+ * Verdict extraction and recording.
+ *
+ * Fixes versus the original:
+ *  - Last-verdict-wins. A reviewer transcript that says
+ *    "previously Verdict: FAIL, after fixes Verdict: PASS" records PASS, not
+ *    FAIL. The reviewer's FINAL line is its conclusion.
+ *  - Line-anchored matching is preferred, so a `Verdict: PASS` buried in quoted
+ *    context or tool metadata does not register a gate the reviewer never
+ *    actually rendered.
+ *  - The `<task><task_result>…</task_result></task>` wrapper that the task tool
+ *    puts around a subagent's output is unwrapped before scanning.
+ */
+
+import { CYCLE_CLOSING_AGENT } from "./agents.js";
+
+const TASK_RESULT_RE = /<task_result>([\s\S]*?)<\/task_result>/i;
+const ANCHORED_RE = /^[ \t>*_-]*\*{0,2}Verdict:?\*{0,2}[\s*_]*(PASS|FAIL)\b/gim;
+const LOOSE_RE = /Verdict:?\*{0,2}[\s*_]*(PASS|FAIL)\b/gi;
+
+/** Pull the human-readable text out of a tool/subagent output object. */
+export function textOf(output) {
+  if (output == null) return "";
+  if (typeof output === "string") return output;
+  const raw = output.output ?? output.text ?? output.message ?? output.title ?? "";
+  let text;
+  if (typeof raw === "string") text = raw;
+  else if (raw && typeof raw === "object") text = raw.output ?? raw.text ?? JSON.stringify(raw);
+  else text = String(raw ?? "");
+  const m = TASK_RESULT_RE.exec(text);
+  return m ? m[1] : text;
+}
+
+/**
+ * Extract the final verdict from a body of text.
+ *
+ * True textual last-wins: a reviewer's FINAL `Verdict: …` line is its
+ * conclusion. We scan ALL matches (loose) and take the one with the greatest
+ * position, using line-anchored matches only as a tiebreak when an anchored and
+ * a loose match share the same end position. The earlier "prefer the anchored
+ * set whenever any anchored match exists" logic was a critical bug: a transcript
+ * like "Verdict: PASS (happy path)\nHowever, Verdict: FAIL — blocking" has only
+ * the early PASS anchored (the FAIL line starts with "However,"), so it wrongly
+ * returned PASS and let a failing final review complete the goal.
+ *
+ * @returns {"PASS"|"FAIL"|null}
+ */
+export function parseVerdict(text) {
+  if (typeof text !== "string" || !text) return null;
+  const loose = [...text.matchAll(LOOSE_RE)];
+  if (!loose.length) return null;
+  const lastLoose = loose[loose.length - 1];
+  const anchored = [...text.matchAll(ANCHORED_RE)];
+  const lastAnchored = anchored.length ? anchored[anchored.length - 1] : null;
+  // Prefer whichever genuinely occurs last in the text; on a tie, the anchored
+  // (conclusion-formatted) one wins.
+  const lastAnchoredEnd = lastAnchored ? lastAnchored.index + lastAnchored[0].length : -1;
+  const lastLooseEnd = lastLoose.index + lastLoose[0].length;
+  const chosen = lastAnchoredEnd >= lastLooseEnd && lastAnchored ? lastAnchored : lastLoose;
+  return chosen[1].toUpperCase();
+}
+
+export function hasVerdict(text) {
+  return parseVerdict(text) !== null;
+}
+
+export function latestVerdictFor(state, agent) {
+  return state.latestVerdict[agent] || null;
+}
+
+/**
+ * Record a review verdict for `agent`, stamping it with the next monotonic seq.
+ * Increments the review-cycle count when the cycle-closing agent reports.
+ */
+export function recordVerdict(store, state, agent, verdict) {
+  const at = store.nowIso();
+  const seq = store.nextSeq();
+  const entry = { agent, verdict, at, seq };
+  state.verdicts.push(entry);
+  if (state.verdicts.length > 200) state.verdicts.splice(0, state.verdicts.length - 200);
+  state.latestVerdict[agent] = { verdict, at, seq };
+  state.lastReviewAt = at;
+  state.lastReviewSeq = seq;
+  state.updatedAt = at;
+  if (agent === CYCLE_CLOSING_AGENT) state.reviewCycles += 1;
+  return entry;
+}