opencode-goal-mode 0.1.0 → 0.2.0

package/agents/goal-prompt-auditor.md

@@ -1,8 +1,6 @@
 ---
 description: Use in every Goal Mode review cycle to compare the original user prompt and Goal Contract against the delivered outcome with extreme strictness.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: xhigh
 temperature: 0
 color: error
 permission:

package/agents/goal-quality-gate.md

@@ -1,8 +1,6 @@
 ---
 description: Use proactively as the final quality gate before completion. Checks standards compliance, naming, style, deprecations, security hygiene, and project-specific quality rules.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: xhigh
 temperature: 0
 color: error
 permission:

package/agents/goal-researcher.md

@@ -1,8 +1,6 @@
 ---
 description: Use proactively for deep external/docs/schema/API research, unfamiliar dependencies, OpenCode/Claude/Codex behavior, and best-practice investigation.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: high
 color: info
 permission:
   read: allow
@@ -26,9 +24,12 @@ permission:
 
 You are a deep research agent for Goal Mode. Prefer authoritative docs, schemas, source repos, changelogs, and API references. Do not modify files.
 
-Final format:
+Discipline: return distilled findings, not raw dumps. Do not paste long quotes or full pages — summarize and cite. Every non-obvious claim must carry a source.
 
-- Key facts
-- Risks or caveats
-- Recommended implementation approach
-- Sources checked
+Final format (return only these sections):
+
+- Key facts: each with the source it came from.
+- Risks or caveats: with severity and why it matters.
+- Recommended implementation approach: concrete and actionable.
+- Confidence: high/medium/low, and what would raise it.
+- Sources checked: URLs or `path:line`.

package/agents/goal-reviewer.md

@@ -1,8 +1,6 @@
 ---
 description: Use proactively after implementation for extremely strict correctness, completeness, regression, maintainability, and acceptance-criteria review.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: xhigh
 temperature: 0
 color: error
 permission:

package/agents/goal-security-reviewer.md

@@ -1,8 +1,6 @@
 ---
 description: Use for auth, secrets, permissions, shell risk, data exposure, destructive actions, network exposure, deployments, and operations risk.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: xhigh
 temperature: 0
 color: error
 permission:

package/agents/goal-test-reviewer.md

@@ -1,8 +1,6 @@
 ---
 description: Use to identify missing tests, inadequate validation, flaky checks, and better verification commands for Goal Mode.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: high
 temperature: 0
 color: success
 permission:

package/agents/goal-ux-reviewer.md

@@ -1,8 +1,6 @@
 ---
 description: Use for frontend, copy, accessibility, docs, user-facing workflow, CLI usability, and product polish review.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: high
 temperature: 0
 color: accent
 permission:

package/agents/goal-verifier.md

@@ -1,8 +1,6 @@
 ---
 description: Use to run or plan exact verification commands, summarize outputs, and determine whether evidence proves the Goal is complete.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: high
 temperature: 0
 color: success
 permission:

package/agents/goal-web-researcher.md

@@ -1,8 +1,6 @@
 ---
 description: Use proactively for fast web search, page fetching, link summarization, trend checks, package docs, error message lookup, and quick external context without deep analysis.
 mode: subagent
-model: ordis/chatgpt/gpt-5.5
-variant: high
 temperature: 0
 color: info
 permission:

package/agents/goal.md

@@ -1,8 +1,6 @@
 ---
 description: Goal mode for end-to-end autonomous delivery with strict subagent research, implementation ownership, verification, and repeated review cycles until the user's goal is actually complete.
 mode: primary
-model: ordis/chatgpt/gpt-5.5
-variant: xhigh
 color: error
 permission:
   read: allow
@@ -40,10 +38,6 @@ permission:
   doom_loop: allow
   skill: allow
 ---
-ext_mcp_server_trust:
-  - github
-  - browser_automation
-  - mcp_time
 
 You are Goal Mode, an uncompromising autonomous delivery agent. Your job is to finish the user's stated goal, not merely make progress. You have full tool access and must use it responsibly, persistently, and with extreme discipline.
 
@@ -68,7 +62,6 @@ Delegation rules:
 - Use `goal-commentator` for improving code comments and annotations.
 - Use `goal-explorer` and `goal-researcher` for local file discovery and dependency research.
 - Use `goal-implementer` for bounded implementation subtasks when explicit delegation is safer.
-- Use `goal-coordinator` for managing multiple parallel deliverable streams in place of the unavailable `goals` tool.
 - Use `goal-reviewer` for strict overall correctness and acceptance review.
 - Use `goal-diff-reviewer` for exact file/code/config diff review.
 - Use `goal-verifier` for running real verification commands and summarizing evidence.
@@ -76,7 +69,8 @@ Delegation rules:
 - Use `goal-security-reviewer` for auth, secrets, permissions, network exposure, shell, and destructive risk.
 - Use `goal-ux-reviewer` for UI, workflow, usability, and accessibility.
 - Use `goal-doc-reviewer` for documentation quality and accuracy.
-- Use `goal-ops-reviewer` for operational, restart, migration, and config-time changes.
+- Use `goal-ops-reviewer` for operational, restart, migration, and config-time changes. When a change is both a security risk and an operational change, run `goal-security-reviewer` for the threat surface and `goal-ops-reviewer` for the rollout/rollback path; they do not substitute for each other.
+- Use `goal-completion-guard` as a fast pre-flight check that every required gate has a fresh PASS before you invoke the final auditor.
 - Use `goal-final-auditor` as the last gate before `Goal Completed`.
 
 Required internal artifacts:
@@ -89,6 +83,13 @@ Required internal artifacts:
 - Review cycles: N: explicit count of review iterations performed.
 - Completion Gate: all required reviewers PASS after the latest edit and latest verification.
 
+Guard tools (provided by the goal-guard plugin):
+
+- Call `goal_contract` once the Goal Contract is settled. This activates strict enforcement and tells the guard which specialist review gates your goal requires (security, data, api, perf, etc., inferred from the contract text).
+- Call `goal_evidence` after each meaningful verification run to record the command and result in the Verification Ledger.
+- Call `goal_status` whenever you are unsure what the guard currently requires; it returns the authoritative list of passing, missing, and stale gates and whether completion is allowed. Trust it over your own recollection.
+- The guard injects a live state block into your context each turn and will rewrite a premature `Goal Completed` into `Goal Not Completed` with the missing gates. Use `goal_status` to avoid that rather than guessing.
+
 Context discipline:
 
 - Do not fill the main thread with broad search logs, large file summaries, research dumps, or exploratory dead ends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {
@@ -13,19 +13,22 @@
   "files": [
     "agents/",
     "commands/",
-    "docs/",
     "plugins/",
-    "scripts/",
-    "tests/",
+    "scripts/install.mjs",
+    "ARCHITECTURE.md",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "test": "node --test",
-    "test:agents": "node tests/agents.test.mjs",
-    "test:commands": "node tests/commands.test.mjs",
-    "test:plugin": "node tests/plugin.test.mjs",
-    "test:install": "node tests/install.test.mjs",
+    "test:coverage": "node --experimental-test-coverage --test",
+    "test:shell": "node --test tests/shell.test.mjs tests/shell.property.test.mjs",
+    "test:plugin": "node --test tests/plugin.test.mjs tests/integration.test.mjs",
+    "test:unit": "node --test tests/state.test.mjs tests/gates.test.mjs tests/verdicts.test.mjs tests/config.test.mjs tests/persistence.test.mjs",
+    "test:agents": "node --test tests/agents.test.mjs tests/commands.test.mjs",
+    "test:install": "node --test tests/install.test.mjs",
+    "bench": "node benchmarks/run.mjs",
+    "bench:compare": "node benchmarks/comparison.mjs",
     "pack:check": "npm pack --dry-run",
     "audit": "npm audit --audit-level=moderate",
     "publish:check": "node scripts/check-npm-publish-ready.mjs",
@@ -56,6 +59,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.15.13"
+    "@opencode-ai/plugin": "1.15.13",
+    "fast-check": "^4.8.0"
   }
 }

package/plugins/goal-guard/agents.js

@@ -0,0 +1,132 @@
+/**
+ * Canonical agent identities and gating maps for Goal Mode.
+ *
+ * Keeping these in one module means the plugin, the system-prompt injector and
+ * the tests all agree on exactly which agents exist, which are review gates,
+ * and which contextual keywords pull in which specialist reviewer.
+ */
+
+/** Read-only review/verification gates that emit `Verdict: PASS|FAIL`. */
+export const REVIEW_AGENTS = Object.freeze([
+  "goal-reviewer",
+  "goal-prompt-auditor",
+  "goal-diff-reviewer",
+  "goal-verifier",
+  "goal-test-reviewer",
+  "goal-security-reviewer",
+  "goal-ux-reviewer",
+  "goal-ops-reviewer",
+  "goal-doc-reviewer",
+  "goal-final-auditor",
+  "goal-completion-guard",
+  "goal-api-reviewer",
+  "goal-data-reviewer",
+  "goal-perf-reviewer",
+  "goal-quality-gate",
+]);
+
+/** Every agent that belongs to Goal Mode (primary + workers + reviewers). */
+export const GOAL_AGENTS = Object.freeze([
+  "goal",
+  "goal-implementer",
+  "goal-explorer",
+  "goal-researcher",
+  "goal-deep-researcher",
+  "goal-web-researcher",
+  "goal-architect",
+  "goal-mapper",
+  "goal-planner",
+  "goal-coordinator",
+  "goal-doc-writer",
+  "goal-commentator",
+  ...REVIEW_AGENTS,
+]);
+
+const REVIEW_SET = new Set(REVIEW_AGENTS);
+const GOAL_SET = new Set(GOAL_AGENTS);
+
+export function isReviewAgent(name) {
+  return REVIEW_SET.has(String(name || ""));
+}
+
+export function isGoalAgent(name) {
+  return GOAL_SET.has(String(name || ""));
+}
+
+/** The primary Goal Mode agent. Only this agent's sessions are "goal sessions"
+ * the guard polices for completion — review/worker subagents run in their own
+ * child sessions and must not be activated (that would pollute attribution and
+ * the active-session population). */
+export const PRIMARY_AGENT = "goal";
+
+export function isPrimaryAgent(name) {
+  return String(name || "") === PRIMARY_AGENT;
+}
+
+/** Reviewers that always run for any meaningful goal. */
+export const BASE_GATES = Object.freeze([
+  "goal-prompt-auditor",
+  "goal-reviewer",
+  "goal-diff-reviewer",
+  "goal-verifier",
+  "goal-final-auditor",
+]);
+
+/**
+ * Keyword → specialist reviewer. When the captured goal text or the set of
+ * changed files mentions one of these keywords, the corresponding reviewer
+ * becomes a required gate. Keys are matched as whole words against lowercased
+ * text so that `api` does not match `capital`.
+ */
+export const CONTEXTUAL_GATES = Object.freeze({
+  security: "goal-security-reviewer",
+  secure: "goal-security-reviewer",
+  vulnerability: "goal-security-reviewer",
+  secret: "goal-security-reviewer",
+  secrets: "goal-security-reviewer",
+  password: "goal-security-reviewer",
+  credential: "goal-security-reviewer",
+  permission: "goal-security-reviewer",
+  permissions: "goal-security-reviewer",
+  auth: "goal-security-reviewer",
+  authentication: "goal-security-reviewer",
+  token: "goal-security-reviewer",
+  shell: "goal-security-reviewer",
+  test: "goal-test-reviewer",
+  tests: "goal-test-reviewer",
+  coverage: "goal-test-reviewer",
+  spec: "goal-test-reviewer",
+  ops: "goal-ops-reviewer",
+  restart: "goal-ops-reviewer",
+  install: "goal-ops-reviewer",
+  installer: "goal-ops-reviewer",
+  deploy: "goal-ops-reviewer",
+  deployment: "goal-ops-reviewer",
+  rollback: "goal-ops-reviewer",
+  api: "goal-api-reviewer",
+  endpoint: "goal-api-reviewer",
+  endpoints: "goal-api-reviewer",
+  schema: "goal-api-reviewer",
+  data: "goal-data-reviewer",
+  database: "goal-data-reviewer",
+  migration: "goal-data-reviewer",
+  migrations: "goal-data-reviewer",
+  sql: "goal-data-reviewer",
+  performance: "goal-perf-reviewer",
+  perf: "goal-perf-reviewer",
+  latency: "goal-perf-reviewer",
+  throughput: "goal-perf-reviewer",
+  scalability: "goal-perf-reviewer",
+  ux: "goal-ux-reviewer",
+  ui: "goal-ux-reviewer",
+  accessibility: "goal-ux-reviewer",
+  usability: "goal-ux-reviewer",
+  docs: "goal-doc-reviewer",
+  documentation: "goal-doc-reviewer",
+  readme: "goal-doc-reviewer",
+  quality: "goal-quality-gate",
+  standards: "goal-quality-gate",
+});
+
+/** The reviewer that, when it returns a verdict, closes one review cycle. */
+export const CYCLE_CLOSING_AGENT = "goal-final-auditor";

package/plugins/goal-guard/completion.js

@@ -0,0 +1,64 @@
+/**
+ * Completion-claim enforcement.
+ *
+ * Evaluates a finished assistant message that claims `Goal Completed` and
+ * decides whether the claim is allowed. The rewrite is only applied to ACTIVE
+ * goal sessions, so an unrelated assistant turn that merely quotes the phrase
+ * in a non-goal session is never corrupted (a bug in the original).
+ *
+ * A claim is rejected when any of the following hold:
+ *  - the required `Review cycles: N` line is missing;
+ *  - no review cycle has been recorded (N must be > 0);
+ *  - the claimed N does not match the recorded review-cycle count;
+ *  - required review gates are missing or stale for the current state.
+ */
+
+import { missingGates, completionAllowed } from "./gates.js";
+import { summarizeState } from "./summary.js";
+
+const CYCLES_RE = /Review cycles:\s*(\d+)/i;
+
+/**
+ * @returns {{ blocked: boolean, reason?: string, replacement?: string, claimedCycles?: number }}
+ */
+export function evaluateCompletionClaim(state, config, text) {
+  const marker = config.completionMarker || "Goal Completed";
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // The completion contract requires the message to START with the marker (the
+  // final response begins with "Goal Completed"). Anchor to the first non-space
+  // of the message or of any line, so a mid-sentence mention is not policed.
+  const markerRe = new RegExp(`^[\\s>*_#-]*${escaped}`, "im");
+
+  if (!text || !markerRe.test(text)) return { blocked: false };
+  // Only police active goal sessions.
+  if (!state.active) return { blocked: false };
+
+  const match = text.match(CYCLES_RE);
+  const claimedCycles = match ? Number.parseInt(match[1], 10) : -1;
+  const summary = summarizeState(state, config);
+
+  let reason = null;
+  if (claimedCycles < 0) {
+    reason = "missing required Review cycles line";
+  } else if (state.reviewCycles === 0) {
+    reason = "no review cycles recorded";
+  } else if (claimedCycles !== state.reviewCycles) {
+    reason = `claimed review cycles (${claimedCycles}) do not match recorded review cycles (${state.reviewCycles})`;
+  } else if (!completionAllowed(state, config)) {
+    const missing = missingGates(state, config).join(", ");
+    reason = `required review gates are missing or stale (${missing || "goal session not active"})`;
+  }
+
+  if (!reason) return { blocked: false, claimedCycles };
+
+  const blockedMarker = config.blockedMarker || "Goal Not Completed";
+  // Rewrite the SAME anchored line that triggered detection (preserving its
+  // leading markdown prefix), not merely the first occurrence of the phrase —
+  // otherwise an unrelated earlier mention would be mangled while the real
+  // completion-claim heading stayed unflipped.
+  const markerLineRe = new RegExp(`^([\\s>*_#-]*)${escaped}`, "im");
+  const replacement =
+    text.replace(markerLineRe, (_m, prefix) => `${prefix}${blockedMarker}`) +
+    `\n\nGoal Guard blocked completion: ${reason}. State: ${summary}`;
+  return { blocked: true, reason, replacement, claimedCycles };
+}

package/plugins/goal-guard/config.js

@@ -0,0 +1,87 @@
+/**
+ * Configuration resolution for the guard.
+ *
+ * Precedence (lowest → highest): built-in defaults < environment variables <
+ * the plugin `options` object passed from opencode.json's `["spec", {…}]`
+ * form. This lets the guard be tuned per project without code changes, while
+ * still working with zero configuration when auto-discovered.
+ */
+
+export const DEFAULT_CONFIG = Object.freeze({
+  /** Block destructive shell commands before execution (throw in tool.execute.before). */
+  blockDestructive: true,
+  /** Also block remote-code-execution pipelines (curl | sh). */
+  blockNetworkExec: true,
+  /** Rewrite premature `Goal Completed` claims in experimental.text.complete. */
+  enforceCompletion: true,
+  /** Inject a live Goal Guard state block into the system prompt. */
+  injectSystemState: true,
+  /** Persist guard state to disk so it survives OpenCode restarts. */
+  persist: true,
+  /** Require the contextual specialist gates derived from goal text / changed files. */
+  contextualGates: true,
+  /** Maximum tracked sessions before LRU eviction. */
+  maxSessions: 200,
+  /** Idle TTL (ms) after which a session's state may be dropped. 0 disables TTL. */
+  sessionTtlMs: 24 * 60 * 60 * 1000,
+  /** Emit a TUI toast when completion is blocked. */
+  toastOnBlock: true,
+  /** Phrase that, at the start of an assistant message, claims completion. */
+  completionMarker: "Goal Completed",
+  /** Replacement marker when completion is blocked. */
+  blockedMarker: "Goal Not Completed",
+});
+
+function coerceBool(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "boolean") return value;
+  const s = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(s)) return true;
+  if (["0", "false", "no", "off"].includes(s)) return false;
+  return fallback;
+}
+
+function coerceInt(value, fallback) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+function fromEnv(env) {
+  const out = {};
+  const map = {
+    GOAL_GUARD_BLOCK_DESTRUCTIVE: ["blockDestructive", coerceBool],
+    GOAL_GUARD_BLOCK_NETWORK_EXEC: ["blockNetworkExec", coerceBool],
+    GOAL_GUARD_ENFORCE_COMPLETION: ["enforceCompletion", coerceBool],
+    GOAL_GUARD_INJECT_SYSTEM_STATE: ["injectSystemState", coerceBool],
+    GOAL_GUARD_PERSIST: ["persist", coerceBool],
+    GOAL_GUARD_CONTEXTUAL_GATES: ["contextualGates", coerceBool],
+    GOAL_GUARD_MAX_SESSIONS: ["maxSessions", coerceInt],
+    GOAL_GUARD_SESSION_TTL_MS: ["sessionTtlMs", coerceInt],
+    GOAL_GUARD_TOAST_ON_BLOCK: ["toastOnBlock", coerceBool],
+  };
+  for (const [key, [field, coerce]] of Object.entries(map)) {
+    if (env[key] !== undefined) out[field] = coerce(env[key], DEFAULT_CONFIG[field]);
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, unknown>|undefined} options Plugin options (2nd factory arg).
+ * @param {Record<string, string|undefined>} [env] Environment (defaults to process.env).
+ * @returns {typeof DEFAULT_CONFIG}
+ */
+export function resolveConfig(options, env = process.env) {
+  const envConfig = fromEnv(env || {});
+  const opts = options && typeof options === "object" ? options : {};
+  const merged = { ...DEFAULT_CONFIG, ...envConfig };
+
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    if (opts[key] === undefined) continue;
+    const def = DEFAULT_CONFIG[key];
+    if (typeof def === "boolean") merged[key] = coerceBool(opts[key], merged[key]);
+    else if (typeof def === "number") merged[key] = coerceInt(opts[key], merged[key]);
+    else merged[key] = opts[key];
+  }
+  return Object.freeze(merged);
+}

package/plugins/goal-guard/events.js

@@ -0,0 +1,65 @@
+/**
+ * State-mutation primitives shared by the plugin hooks and the custom tools, so
+ * that an edit recorded via the `edit` tool, a bash mutation, a `file.edited`
+ * event, and a `goal_evidence` tool call all advance the same monotonic seq and
+ * dirty bookkeeping in exactly one place.
+ */
+
+import { CYCLE_CLOSING_AGENT } from "./agents.js";
+import { gatePassedFresh, completionAllowed } from "./gates.js";
+
+function trim(arr, max) {
+  if (arr.length > max) arr.splice(0, arr.length - max);
+}
+
+export function markEdit(store, state, reason) {
+  const at = store.nowIso();
+  state.active = true;
+  state.dirty = true;
+  state.lastEditAt = at;
+  state.lastEditSeq = store.nextSeq();
+  state.dirtyReasons.push(reason || `edit at ${at}`);
+  trim(state.dirtyReasons, 50);
+  state.updatedAt = at;
+}
+
+export function markVerification(store, state) {
+  const at = store.nowIso();
+  state.verificationSeen = true;
+  state.lastVerificationAt = at;
+  state.lastVerificationSeq = store.nextSeq();
+  state.updatedAt = at;
+}
+
+export function markFileChanged(store, state, file) {
+  const name = String(file || "").trim();
+  if (!name) return;
+  if (!state.changedFiles.includes(name)) state.changedFiles.push(name);
+  trim(state.changedFiles, 200);
+  markEdit(store, state, `file edited: ${name}`);
+}
+
+export function recordEvidence(store, state, command, result, criteria) {
+  const at = store.nowIso();
+  state.evidence.push({
+    command: String(command || ""),
+    result: String(result || ""),
+    criteria: Array.isArray(criteria) ? criteria.slice(0, 50) : [],
+    at,
+  });
+  trim(state.evidence, 100);
+  markVerification(store, state);
+  state.updatedAt = at;
+}
+
+/**
+ * When the cycle-closing auditor passes and all gates are fresh, the candidate
+ * is genuinely clean: clear the dirty flag so the next answer can complete.
+ */
+export function maybeClearDirtyOnFinalPass(state, config) {
+  if (!gatePassedFresh(state, CYCLE_CLOSING_AGENT)) return false;
+  if (!completionAllowed(state, config)) return false;
+  state.dirty = false;
+  state.dirtyReasons = [];
+  return true;
+}

package/plugins/goal-guard/gates.js

@@ -0,0 +1,85 @@
+/**
+ * Required-gate computation and freshness.
+ *
+ * Fixes versus the original:
+ *  - Contextual gates actually fire. The previous code computed required gates
+ *    from `dirtyReasons` only (which never contain meaningful keywords), so the
+ *    specialist reviewers were dead code. Here gates are derived from the
+ *    captured goal text, the recorded Goal Contract, and the set of changed
+ *    files.
+ *  - Keyword matching is whole-word (token set), so `api` no longer matches
+ *    inside `capital` and a fingerprint hex can't accidentally pull in a gate.
+ *  - Freshness uses the monotonic seq counter and is invalidated by EDITS only.
+ *    Re-running verification after a clean review no longer re-opens the gates.
+ */
+
+import { BASE_GATES, CONTEXTUAL_GATES } from "./agents.js";
+
+function contractText(contract) {
+  if (!contract || typeof contract !== "object") return "";
+  const parts = [contract.original];
+  for (const field of ["requirements", "inferred", "nonGoals", "acceptanceCriteria"]) {
+    if (Array.isArray(contract[field])) parts.push(contract[field].join(" "));
+  }
+  return parts.filter(Boolean).join(" ");
+}
+
+/** Tokenize text into a lowercase whole-word set. */
+function wordSet(text) {
+  const set = new Set();
+  for (const w of String(text || "").toLowerCase().split(/[^a-z0-9]+/)) {
+    if (w) set.add(w);
+  }
+  return set;
+}
+
+/** The specialist reviewers implied by the current goal text/contract/files. */
+export function contextualGatesFor(state) {
+  const found = [];
+  const text = [state.goalText, contractText(state.contract), (state.changedFiles || []).join(" ")].join(" ");
+  const words = wordSet(text);
+  for (const [keyword, agent] of Object.entries(CONTEXTUAL_GATES)) {
+    if (words.has(keyword) && !found.includes(agent)) found.push(agent);
+  }
+  return found;
+}
+
+/**
+ * Union the currently-implied contextual gates into the session's sticky set.
+ * Gates are sticky so a long session whose rolling goalText buffer later drops
+ * the triggering keyword does not silently lose a required specialist review.
+ */
+export function refreshStickyGates(state) {
+  if (!Array.isArray(state.stickyGates)) state.stickyGates = [];
+  for (const agent of contextualGatesFor(state)) {
+    if (!state.stickyGates.includes(agent)) state.stickyGates.push(agent);
+  }
+  return state.stickyGates;
+}
+
+/** The reviewers that must PASS for this state, given config. */
+export function requiredGates(state, config) {
+  const gates = [...BASE_GATES];
+  if (!config || config.contextualGates) {
+    const contextual = new Set([...(state.stickyGates || []), ...contextualGatesFor(state)]);
+    for (const agent of contextual) {
+      if (!gates.includes(agent)) gates.push(agent);
+    }
+  }
+  return gates;
+}
+
+/** A gate is satisfied when its latest verdict is PASS and newer than the last edit. */
+export function gatePassedFresh(state, agent) {
+  const v = state.latestVerdict[agent];
+  if (!v || v.verdict !== "PASS") return false;
+  return v.seq > (state.lastEditSeq || 0);
+}
+
+export function missingGates(state, config) {
+  return requiredGates(state, config).filter((agent) => !gatePassedFresh(state, agent));
+}
+
+export function completionAllowed(state, config) {
+  return Boolean(state.active) && missingGates(state, config).length === 0;
+}