@cleocode/goal 0.0.0-stage → 0.9.2

package/src/server/help.ts

@@ -0,0 +1,50 @@
+// T025 — the /goal help surface: one pure builder producing an agent-forward
+// guide (commands with arguments, the worker/owner permission split, storage
+// layout, mid-run rules). Rendered by /goal help and pinned by a unit test so
+// it cannot drift from the engine's real semantics.
+
+export type HelpFacts = { version: string }
+
+export function goalHelp({ version }: HelpFacts): string {
+  return [
+    `# opencode-goal ${version} — the goal loop, for agents and owners`,
+    "",
+    "## Commands (owner)",
+    "- `/goal new <what you want done>` — the write-goal interview (skill attached; similar-goal probe runs first)",
+    "- `/goal start <slug> [acknowledge-supersede]` — rehearse every command check, then lock and run",
+    "- `/goal status` · `/goal pause` · `/goal resume` · `/goal verify` — status costs no model turn",
+    "- `/goal abort` — end the run for good (ledger and evidence stay)",
+    "- `/goal amend [confirm]` — propose/confirm a contract re-lock after editing goal.yaml out of band",
+    "- `/goal archive` — demote a finished goal to .opencode/goals-archive/ (never deleted)",
+    "- `/goal approve <C#>` · `/goal reject <C#> <why>` — owner sign-off for human criteria",
+    "- `/goal validate <slug>` · `/goal list [all]` — validate a contract; list live (or +archived) goals",
+    "- `/goal cleo [install|init|sync]` — probe the CLEO CLI and this project's .cleo workspace (initialized / uninitialized / CLI absent); `install` and `init` run the exact documented command only on your explicit choice, never silently and never with sudo",
+    "",
+    "## Worker tools (the agent in the loop)",
+    "- `goal_progress` — record the step you are on, one line of change, the next action",
+    "- `goal_claim` — claim completion with evidence per criterion; the HOST then verifies you",
+    "- `goal_block` — stop for an owner-only blocker (missing credential, decision)",
+    "- `goal_flag` — flag a criterion that is contradictory, impossible or unsafe as written",
+    "- `goal_wait <seconds>` — pause cheaply while an external process runs",
+    "- `goal_status` / `goal_validate` — read-only checks",
+    "- `goal_verdict` — reserved for the read-only verifier child; never available to the worker",
+    "",
+    "All `goal_*` tools are called **directly by name** — they are not registered with Code Mode, so `search()`/`tools.*` inside `execute` will never find them (a routing attempt returns an unrelated Unknown-tool error).",
+    "",
+    "## Storage layout (per project)",
+    "- `.opencode/goals/<slug>/goal.yaml` — the locked contract (sha256)",
+    "- `.opencode/goals/<slug>/run.json` — live run state; `ledger.jsonl` — every event, append-only",
+    "- `.opencode/goals/<slug>/evidence/<runId>/` — locked contract copy, rehearsal baseline, verify results, verifier transcripts, amendment records",
+    "- `.opencode/goals-archive/<slug>/` — demoted goals; the machine registry still answers \"was this ever a goal here?\"",
+    "",
+    "## Mid-run rules (the contract is enforced, not advice)",
+    "- The contract is rendered into every request; compaction cannot lose it.",
+    "- Never edit `.opencode/goals/**` while a goal exists — the write guard blocks it, running or stopped.",
+    "- Completion is proven, not declared: host checks run first, then an independent verifier child whose quotes are re-read. A rejected claim returns a HOST VERDICT turn — read it, fix the work, claim again.",
+    "- Questions are deferred during a run: make the reversible choice, note it in goal_progress, or call goal_block.",
+    "- Command checks live on ONE line and are rehearsed at start; a check that cannot run refuses the lock.",
+    "- Supersession replaces a goal: `supersedes: <slug>@<lock>` in the new contract; live predecessors need your explicit acknowledgment.",
+    "- Describe changes in the Composer; goal_propose_amendment stages an exact diff, then goal_resolve_amendment binds genuine owner chat once. No sidebar Accept or manual command is required.",
+    "- Every accepted amendment is a generation-bound, audit-trailed re-lock: the prior generation is retained, changed criteria reset and re-verify, and acceptance resumes the run in the same act.",
+  ].join("\n")
+}

package/src/server/index.ts

@@ -0,0 +1,23 @@
+// OpenCode 2 server entry. A plain-object default export with type-only imports,
+// so the plugin loads without @opencode/plugin installed at runtime.
+import type { Plugin } from "@opencode/plugin"
+import { GoalApp } from "./app"
+
+// S6: setup can run more than once for a location; retire the old instance first.
+const instances = new Map<string, GoalApp>()
+
+export default {
+  id: "opencode-goal",
+  async setup(ctx: Plugin.Context) {
+    const key = ctx.location.directory
+    const previous = instances.get(key)
+    if (previous) await previous.stop()
+    const app = new GoalApp(ctx)
+    instances.set(key, app)
+    await app.start()
+    return async () => {
+      await app.stop()
+      if (instances.get(key) === app) instances.delete(key)
+    }
+  },
+}

package/src/server/intent.ts

@@ -0,0 +1,22 @@
+// Recognize only the existing, explicit command shorthand. Everything
+// conversational remains the owner's text for the agent to interpret; this
+// is deliberately NOT a host-side NLP-to-shell parser.
+export function directGoalCommand(text: string, slugs: readonly string[]): boolean {
+  const [head = "", ...rest] = text.trim().split(/\s+/)
+  const sub = head.toLowerCase()
+  const arg = rest.join(" ")
+  const named = (s: string) => slugs.includes(s)
+  switch (sub) {
+    case "new": case "write": return true
+    case "status": case "help": return !arg
+    case "list": return !arg || arg === "all"
+    case "start": return !arg || named(rest[0] ?? "") && rest.slice(1).every((t) => ["fresh", "acknowledge-supersede"].includes(t))
+    case "validate": case "pause": case "resume": case "abort": case "verify": case "archive": case "attach": case "revert":
+      return !arg || rest.length === 1 && named(rest[0]!)
+    case "cleo": return true
+    case "amend": return !arg || arg === "confirm" || rest.length === 1 && named(rest[0]!)
+    case "approve": return /^C\d+(?:\s+[a-z0-9-]+)?$/i.test(arg)
+    case "reject": return /^C\d+(?:\s|$)/i.test(arg)
+    default: return false
+  }
+}

package/src/server/messages.ts

@@ -0,0 +1,228 @@
+// T054 — actionable message content. Owner directive: "treat users like
+// they need everything spelled out — actionable, option-based." Every
+// engine notice carries the CAUSE plus CONCRETE CHOICES: what to run, what
+// to approve, what to read. This module owns the wording of every notice
+// the engine emits; app.ts renders nothing raw. The choices render inline
+// (a plain toast stays actionable) and ride the rpc payload as structured
+// choices the T050 dialogs wire to rpc.act.
+export type Choice = {
+  /** short imperative label for a dialog button, e.g. "Resume goal" */
+  label: string
+  /** the owner command or worker action to run, e.g. "/goal resume" */
+  run: string
+  /** rpc.act action for dialog wiring (optional; commands run as commands) */
+  act?: string
+  arg?: string
+}
+
+export type EngineMessage = {
+  id: string
+  text: string
+  choices: Choice[]
+  level: "info" | "success" | "warning" | "error"
+  attention?: "done" | "question" | "error"
+}
+
+const msg = (id: string, level: EngineMessage["level"], text: string, choices: Choice[], attention?: EngineMessage["attention"]): EngineMessage => ({
+  id,
+  level,
+  text,
+  choices,
+  ...(attention ? { attention } : {}),
+})
+
+/** Inline rendering: cause + explicit choices, one line, toast-safe. */
+export function renderMessage(m: EngineMessage): string {
+  return `${m.text} — ${m.choices.map((c) => c.run).join(" · ")}`
+}
+
+const resume = { label: "Resume goal", run: "/goal resume", act: "resume" }
+const abort = { label: "Abort goal", run: "/goal abort", act: "abort" }
+const status = { label: "Show status", run: "/goal status" }
+const verify = { label: "Verify now", run: "/goal verify", act: "verify" }
+const archive = { label: "Archive goal", run: "/goal archive", act: "archive" }
+
+export const M = {
+  managerOperation: (action: string, title: string) => msg("goal.manager.operation", "warning", `${action.toUpperCase()} the selected goal "${title}"? This applies only to the reviewed run and contract. History stays intact; no operation executes until you choose.`, [
+    { label: `${action[0]!.toUpperCase()}${action.slice(1)} selected goal`, run: `answer with this option to ${action} the exact reviewed goal; preserve its history`, act: action },
+    { label: "Cancel operation", run: "keep the selected goal unchanged" },
+    { label: "Comment instead", run: "reply with commentary; no operation is authorized" },
+  ]),
+  ownerOperationFailed: (reason: string) => msg("goal.owner-operation.failed", "warning", `The selected owner operation did not succeed: ${reason}. No successful resolution was recorded.`, [{ label: "Inspect current status", run: "goal_status before requesting the exact review again" }, { label: "Restore pending review", run: "goal_review for a pending unchanged target" }]),
+  amendmentExpired: () => msg("goal.amend.expired", "warning", "The amendment review expired; the locked contract and evidence are unchanged.", [{ label: "Stage a fresh diff", run: "goal_propose_amendment with the current target lock" }]),
+  amendmentChanged: () => msg("goal.amend.changed", "warning", "The goal/run/contract changed after amendment review; no amendment was applied.", [{ label: "Read and stage again", run: "read the selected goal and stage a new reviewed diff" }]),
+  amendmentInterrupted: () => msg("goal.amend.interrupted", "error", "The amendment commit was interrupted after recorded acceptance; no further work is safe until recovery finishes.", [{ label: "Recover the accepted generation", run: "open a reloaded location to recover the host write-ahead receipt" }]),
+  launchExpired: () => msg("goal.launch.expired", "warning", "The launch review expired; nothing started. A fresh review is needed before consent can be used.", [{ label: "Review again", run: "start a new native launch review" }]),
+  launchChanged: () => msg("goal.launch.changed", "warning", "The contract changed after review; nothing started. The previous choice cannot approve different bytes.", [{ label: "Review the new contract", run: "read the revised contract and start a new native review" }]),
+  launchOutcome: (slug: string, outcome: string, result: string) =>
+    msg("goal.launch.outcome", outcome === "succeeded" ? "success" : "warning", `Launch ${slug} (${outcome}): ${result}`, [status, { label: "Inspect the exact review", run: "goal_review; no old approval is replayed" }]),
+  launchActivity: (slug: string, detail: string) =>
+    msg("goal.launch.activity", "info", `${slug}: ${detail}`, [status]),
+  launchFailed: (reason: string) => msg("goal.launch.failed", "error", `Launch failed; the decision has an explicit recoverable result: ${reason}`, [{ label: "Inspect and review again", run: "read the failed launch result and start a new native review" }]),
+  goalStarted: (title: string) =>
+    msg("goal.started", "success", `Goal started: ${title}. The contract is locked and rendered into every request.`, [status, resume]),
+  cleanStarted: (targetID: string, slug: string) =>
+    msg("goal.clean-start", "success", `Started clean: the kickoff prompt landed in the new session "${targetID}" (goal kickoff · ${slug}). This session stays untouched — nothing was cleared.`, [
+      { label: `Open the goal session`, run: `open the session "goal kickoff · ${slug}"` },
+      status,
+    ]),
+  startPicker: (goals: Array<{ slug: string; title: string; valid: boolean }>) =>
+    msg("goal.start-picker", "info", `Start which goal? ${goals.length} startable in this project:`, goals.map((g) => ({
+      label: `${g.slug} — ${g.title}`,
+      run: `/goal start ${g.slug}`,
+      act: "start",
+      arg: g.slug,
+    }))),
+  startPickerEmpty: (folders: number) =>
+    msg("goal.start-picker.empty", "warning", `No startable goal here (${folders} goal folder${folders === 1 ? "" : "s"} exist${folders ? ", none fresh" : ""}). Write one first.`, [
+      { label: "Write a goal", run: "/goal new <what you want done>" },
+    ]),
+  goalSummary: (headline: string, caveats: number, status2: string) =>
+    msg(`goal.summary.${status2}`, status2 === "complete" ? "success" : "warning", `goal.summary — ${headline}${caveats ? ` (${caveats} caveat${caveats > 1 ? "s" : ""}: provenance and unproven scope flagged in the dialog/evidence)` : ""}. The loop has stopped; follow-ups live in this dialog and the goal folder.`, [
+      { label: "Show status", run: "/goal status" },
+      ...(status2 === "complete" ? [{ label: "Archive", run: "/goal archive", act: "archive" }, { label: "Start the next goal", run: "/goal new <what you want next>" }] : [{ label: "Resolve review", run: "/goal approve <C#>" }]),
+    ]),
+  policyApplied: (kind: string, classes: string, summary: string, slug: string) =>
+    msg("goal.policy.applied", "warning", `Agent applied an in-policy ${kind} (${classes}): ${summary}. It is journalled; the owner can undo it.`, [{ label: "Undo this change", run: `/goal revert ${slug}` }, status]),
+  divergenceChanged: () => msg("goal.divergence.changed", "warning", "The divergence changed since the review; nothing applied.", [{ label: "Review again", run: "goal_recover_divergence for a fresh recovery review" }]),
+  divergenceAdopted: (slug: string) => msg("goal.divergence.adopted", "success", `Adopted the disk contract of ${slug} as a new journalled generation; the goal stays paused.`, [resume, status]),
+  divergenceRestored: (slug: string) => msg("goal.divergence.restored", "success", `Restored the locked contract of ${slug}; the divergent bytes are kept as evidence. The goal stays paused.`, [resume, status]),
+  stallReported: (turns: number) =>
+    msg("goal.stall.reported", "warning", `No visible change for ${turns} turns, but the agent kept working: the run continues under the owner-set on_stall policy and this stall is recorded.`, [status, resume]),
+  runStateRepaired: (slug: string, kept: string) =>
+    msg("goal.runstate.repaired", "warning", `run.json for ${slug} was malformed or carried duplicate keys; it was rebuilt from the run's own ledger and evidence. The raw bytes are kept at ${kept}.`, [status, resume]),
+  amended: (generation: number, summary: string) =>
+    msg("goal.amended", "success", `Goal amended (generation ${generation}): ${summary}. The contract re-locked; the next turn renders the new text.`, [verify, status]),
+  pausedAdmissionError: (reason: string) =>
+    msg("goal.paused.admission", "error", `Goal paused: the host could not send the next turn (${reason}).`, [resume, abort], "error"),
+  awaitingAnswer: (question: string) =>
+    msg("goal.awaiting-answer", "warning", `The goal is waiting for your answer: ${question}. The loop is idle until you reply.`, [
+      { label: "Answer in the session", run: "reply in the session" },
+      abort,
+    ], "question"),
+  pausedUserMessage: () =>
+    msg("goal.paused.user-message", "info", `Goal paused because you sent a message — reply to steer the run, or resume to hand control back.`, [
+      { label: "Resume goal", run: "/goal resume", act: "resume" },
+      { label: "Keep steering", run: "keep replying in the session" },
+      abort,
+    ]),
+  budgetStopped: (title: string) =>
+    msg("goal.budget.stopped", "warning", `Goal stopped at its budget: ${title}. Raise the budget to continue, or wrap up.`, [
+      { label: "Raise budget (amend)", run: "reply in the Composer with the budget change; the agent stages a reviewed amendment" },
+      abort,
+      archive,
+    ], "question"),
+  blocked: (key: string, reason: string, needs?: string) =>
+    msg("goal.blocked", "warning", `Goal blocked on ${key}: ${reason}${needs ? ` — it needs: ${needs}` : " — only the owner can resolve this"}.`, [
+      { label: "Resolve, then resume", run: "/goal resume", act: "resume" },
+      { label: "Flag the criterion (worker)", run: "goal_flag it as contradictory/impossible/unsafe" },
+      abort,
+    ], "question"),
+  pausedInterrupted: (why: string) =>
+    msg("goal.paused.interrupted", "error", `Goal paused — ${why}.`, [
+      { label: "Resume goal", run: "/goal resume", act: "resume" },
+      { label: "Keep steering", run: "keep replying in the session" },
+      abort,
+    ], "error"),
+  // T111: the stall notice names the owner-set autonomy.on_stall option and the
+  // owner's choices, so a stalled run points at /goal resume and at the policy
+  // that would have auto-continued a genuinely working run.
+  pausedStalled: (why: string, onStall: "pause" | "continue" = "pause") =>
+    msg("goal.paused.stalled", "info", `Goal paused — ${why}. Your autonomy.on_stall is "${onStall}". Choices: /goal resume to continue, /goal abort to stop, or set autonomy.on_stall: continue in goal.yaml so a stalled-but-active run keeps going with a recorded report.`, [resume, abort]),
+  verifying: () => msg("goal.verifying", "info", `Verifying the goal: host checks run first, then the independent verifier child. Nothing to do until goal.summary lands.`, [{ label: "Show status", run: "/goal status" }]),
+  complete: (title: string, caveats: number) =>
+    msg("goal.complete", "success", `Goal complete: ${title}.${caveats ? ` ${caveats} caveat${caveats > 1 ? "s" : ""} in the summary (provenance/unproven scope).` : ""} Every required criterion was verified. The loop has stopped — nothing further runs on its own; follow-ups live in the summary dialog and the goal folder.`, [
+      { label: "Archive goal", run: "/goal archive", act: "archive" },
+      { label: "Start the next goal", run: "/goal new <what you want next>" },
+    ], "done"),
+  needsSignOff: (ids: string[]) =>
+    msg("goal.needs-review.signoff", "warning", `Goal needs your sign-off on ${ids.join(", ")} — a human criterion only you can prove. Approve runs verification of everything else immediately (your approval is final and never re-checked).`, [
+      { label: `Approve ${ids[0] ?? "<id>"} (triggers verify)`, run: `/goal approve ${ids[0] ?? "<id>"}`, act: "approve", arg: ids[0] },
+      { label: "Reject with a reason", run: `/goal reject ${ids[0] ?? "<id>"} <why>`, act: "reject", arg: ids[0] },
+      status,
+    ], "question"),
+  needsReview: (reason: string, ids: string[] = []) =>
+    msg("goal.needs-review.rejected", "warning", `Goal needs review: ${reason}. A criterion failed verification repeatedly — decide it, change the work, or change the check. Approving runs verification of everything else immediately (final, never re-checked).`, [
+      ...ids.map((id) => ({ label: `Approve ${id} (final, triggers verify)`, run: `/goal approve ${id}`, act: "approve", arg: id })),
+      ...(ids.length ? [] : [{ label: "Inspect the failed criteria", run: "/goal status" }]),
+      { label: "Amend the check", run: "start a Composer interview for the check change; no contract changes before reviewed acceptance", act: "amend", arg: "interview" },
+      abort,
+    ], "question"),
+  claimRejected: (firstLine: string) =>
+    msg("goal.claim.rejected", "warning", `Claim rejected by the host — the verdict goes back to the agent: ${firstLine}`, [
+      { label: "Agent: fix and re-claim", run: "read the HOST VERDICT lines, fix the work, then goal_claim again" },
+      { label: "Owner: verify again", run: "/goal verify", act: "verify" },
+    ]),
+  attached: (title: string, status2: string) =>
+    msg("goal.attached", "success", `Goal attached here: ${title} (${status2}). Every /goal command and palette action now acts on it from this session.`, [
+      { label: "Resume goal", run: "/goal resume", act: "resume" },
+      status,
+    ]),
+  archived: (title: string, slug: string) =>
+    msg("goal.archived", "success", `Goal archived: ${title} (history intact under .opencode/goals-archive/${slug}/; the registry still answers "was this ever a goal here?").`, [
+      { label: "Start the next goal", run: "/goal new <what you want next>" },
+      { label: "List everything", run: "/goal list all" },
+    ]),
+  goalWait: (seconds: number, reason: string) =>
+    msg("goal.waiting", "info", `Goal waiting ${seconds}s: ${reason}. The loop resumes itself; the tracer counts down.`, [
+      { label: "Show status", run: "/goal status" },
+      { label: "Owner: keep steering", run: "reply in the session (it pauses the wait)" },
+    ]),
+  commandDeferred: (sub: string, held: "turn" | "form") =>
+    msg("goal.command.deferred", "info", `/goal ${sub} acknowledged — queued behind the active ${held}; it runs the moment it ends. Nothing is lost, nothing runs early.`, [
+      { label: "Show status", run: "/goal status" },
+      { label: "Act now anyway", run: "/goal pause or /goal abort run immediately" },
+    ]),
+  amendProposed: (summary: string) =>
+    msg("goal.amend.proposed", "warning", `Amendment proposed: ${summary}. Review the diff; confirming re-locks the contract with a new generation.`, [
+      { label: "Confirm re-lock", run: "/goal amend confirm", act: "amend", arg: "confirm" },
+      { label: "Revise the proposal", run: "reply in the Composer with your changes; the agent stages a revised diff" },
+    ], "question"),
+  supersedeAck: (slug: string, predecessor: string, status: string) =>
+    msg("goal.supersede.ack", "warning", `Refused to start "${slug}": predecessor "${predecessor}" is still ${status}. Superseding a live predecessor forks the audit trail.`, [
+      { label: "Acknowledge and supersede", run: `/goal start ${slug} acknowledge-supersede` },
+      { label: "Abort predecessor first", run: "/goal abort", act: "abort" },
+    ], "question"),
+  pausedAfterVerdict: (firstLine: string) =>
+    msg("goal.paused.verdict", "warning", `Verification did not pass while the goal is stopped — ${firstLine} Decide with the verdict in hand.`, [
+      resume,
+      { label: "Amend the check", run: "start a Composer interview for the check change; no contract changes before reviewed acceptance", act: "amend", arg: "interview" },
+      abort,
+    ], "question"),
+  continueWork: (title: string, slug: string, taskId: string) =>
+    msg("goal.continue-work", "success", `Goal complete: ${title}. Started the next ready CLEO item ${taskId} as "${slug}" — no owner decision was created.`, [
+      { label: "Open the new goal", run: `/goal status ${slug}` },
+      { label: "See all goals", run: "/goal list" },
+    ], "done"),
+  continueStopped: (reason: string) =>
+    msg("goal.continue.stopped", "warning", `The loop did not take more work: ${reason}. Nothing was started.`, [
+      { label: "Inspect the goal", run: "/goal status" },
+      { label: "Start a goal yourself", run: "/goal new <what you want done>" },
+    ], "question"),
+  peerAnnounced: (taskId?: string) =>
+    msg("goal.peer.announced", "info", `Goal complete. Announced availability to peers over AgentMBX${taskId ? ` (last linked task ${taskId})` : ""}; one announcement is outstanding.`, [
+      { label: "Inspect the goal", run: "/goal status" },
+    ]),
+  peerReplied: (from: string, taskId?: string) =>
+    msg("goal.peer.replied", "info", `${from} replied to the availability announcement${taskId ? ` about ${taskId}` : ""}; it is recorded as candidate work, not as consent.`, [
+      { label: "Inspect the goal", run: "/goal status" },
+    ], "question"),
+  completeDecision: (title: string, cleoPresent: boolean, unproven: number) =>
+    msg("goal.complete.decision", "success", `Goal complete: ${title}.${unproven ? ` ${unproven} discussed-but-unproven item(s) are flagged in the summary.` : ""} The loop has stopped. What next?`, [
+      { label: "Start the next goal", run: "start the write-goal interview for the next goal", act: "start-next" },
+      // T070: "Decompose with CLEO" was a dead-end guidance row — it is a
+      // real act now, dispatching the decomposition prompt into the session.
+      ...(cleoPresent
+        ? [{ label: "Decompose with CLEO", run: "file the follow-ups as CLEO tasks in this session", act: "decompose" }]
+        : []),
+      archive,
+      // guidance rows carry no act — the TUI renders them as visible rows
+      // instead of dropping them (T067: "why was I only offered Archive?");
+      // with CLEO linked, Decompose is act-able, so only the install case
+      // stays guidance
+      ...(cleoPresent ? [] : [{ label: "Install CLEO for tracking", run: "install CLEO — no .cleo workspace in this project yet" }]),
+    ], "done"),
+}
+
+/** Every engine notice comes from M — the unit suite pins none is actionless. */
+export const MESSAGE_BUILDERS = Object.keys(M)

package/src/summary/audit.ts

@@ -0,0 +1,76 @@
+// T046 — the completion scope audit. The owner's 2026-10-04 gap: a contract's
+// criteria can all pass while a plan step that proves nothing (proves:[])
+// never happened and a scope.in line maps to no criterion at all — the run
+// "completed" a smaller goal than the one discussed. Per the council
+// decision this ships as a FLAGGED CAVEAT in the post-goal summary: items
+// are surfaced as discussed-but-unproven, completion is never blocked by
+// them (deliberately loose plans must not deadlock).
+import type { Contract, Criterion } from "../contract/types"
+import type { RunState } from "../engine/state"
+import type { ScopeAuditFlag } from "./build"
+
+const STOP = new Set(["the", "and", "for", "with", "this", "that", "from", "into", "when", "must", "shall", "your", "you", "are", "was", "were", "has", "have", "its", "their", "than", "then", "over", "under", "before", "after", "every", "each", "which", "what", "also", "onto", "any", "all", "not", "but", "out", "off", "via", "per", "new", "next", "them", "they", "some", "more", "most", "less", "least", "very", "just", "only", "done", "work", "owner", "agent"])
+
+/** Lowercase meaningful tokens (≥4 chars, naive plural/past stripping). */
+export function tokens(text: string): string[] {
+  return [
+    ...new Set(
+      text
+        .toLowerCase()
+        .replace(/[^a-z0-9+#./-]+/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 4 && !STOP.has(t))
+        .map((t) => (t.length > 4 && t.endsWith("s") ? t.slice(0, -1) : t.length > 4 && t.endsWith("ed") ? t.slice(0, -2) : t)),
+    ),
+  ]
+}
+
+/** The searchable text of a criterion: statement plus its check body. */
+function criterionText(c: Criterion): string {
+  const check = c.check as Record<string, unknown>
+  return `${c.statement} ${Object.values(check).filter((v) => typeof v === "string").join(" ")}`
+}
+
+/** A scope.in line maps to a criterion when one mentions the other, or they
+ *  share ≥2 meaningful tokens. Deterministic and explainable — the audit
+ *  says WHY an item was flagged, never just that it was. */
+export function scopeItemMaps(item: string, criteria: Criterion[]): boolean {
+  const itemNorm = item.toLowerCase().trim()
+  const itemTokens = tokens(item)
+  for (const c of criteria) {
+    const text = criterionText(c)
+    const textNorm = text.toLowerCase()
+    // a direct mention either way (guarded against tiny substrings)
+    if (itemNorm.length >= 8 && (textNorm.includes(itemNorm) || itemNorm.includes(textNorm))) return true
+    if (tokens(text).filter((t) => itemTokens.includes(t)).length >= 2) return true
+  }
+  return false
+}
+
+/**
+ * Flag discussed-but-unproven items:
+ * - plan steps with proves:[] and no sibling evidence of work (the step was
+ *   never recorded done or active in the run's progress state), and
+ * - scope.in lines mapping to no criterion.
+ * Returns the flags; the caller surfaces them as caveats. Never blocks.
+ */
+export function completionAudit(contract: Contract, state: RunState): ScopeAuditFlag[] {
+  const flags: ScopeAuditFlag[] = []
+  const all = [...contract.criteria, ...contract.invariants]
+  for (const step of contract.plan) {
+    if (step.proves.length) continue // proves criteria — those outcomes speak
+    const sibling = state.steps[step.id]
+    if (sibling === "done" || sibling === "active") continue // recorded work exists
+    flags.push({
+      kind: "step",
+      id: step.id,
+      title: step.title,
+      why: `proves no criterion and was never recorded done or active (${sibling ?? "pending"}) — discussed but unproven`,
+    })
+  }
+  for (const item of contract.scope.in) {
+    if (scopeItemMaps(item, all)) continue
+    flags.push({ kind: "scope", id: item, title: item, why: "no criterion statement or check maps to it — discussed but unproven" })
+  }
+  return flags
+}