@cleocode/goal 0.0.0-stage → 0.9.0

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@cleocode/goal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "CLEO Goal: persistent, host-verified goal mode for OpenCode 2 (and any harness through cleo-goal tick), with a structured goal contract and a live TUI.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.14.0",
+    "opencode": ">=2.0.22"
+  },
+  "scripts": {
+    "build": "bun run build:tui && bun run build:cli",
+    "build:tui": "bun scripts/build-tui.mjs",
+    "check:tui": "bun scripts/build-tui.mjs --check",
+    "build:cli": "bun scripts/build-cli.mjs",
+    "check:cli": "bun scripts/build-cli.mjs --check",
+    "prepublishOnly": "bun run check:tui && bun run check:cli",
+    "test": "bun test --timeout 120000",
+    "test:host": "bun test test/host --timeout 120000",
+    "typecheck": "bun run check:tui && bun run check:cli && tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opencode/client": "2.0.22",
+    "@opencode/plugin": "2.0.22",
+    "@opencode/theme": "2.0.22",
+    "@opentui/core": "0.5.14",
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "cleo-goal": "./dist/cli.js",
+    "ocg": "./dist/cli.js"
+  },
+  "exports": {
+    ".": "./server.ts",
+    "./server": "./server.ts",
+    "./tui": "./dist/tui.js",
+    "./rpc": "./rpc.ts"
+  },
+  "files": [
+    "server.ts",
+    "tui.tsx",
+    "rpc.ts",
+    "cli",
+    "dist",
+    "src",
+    "skills",
+    "!skills/*/evals",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kryptobaseddev/opencode-goal.git"
+  },
+  "homepage": "https://github.com/kryptobaseddev/opencode-goal#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "goal",
+    "goal-mode",
+    "autonomous",
+    "agent",
+    "cleo",
+    "cleo-goal",
+    "harness"
+  ],
+  "dependencies": {
+    "@opentui/solid": "0.5.14",
+    "solid-js": "1.9.15",
+    "yaml": "2.8.1"
+  },
+  "bugs": {
+    "url": "https://github.com/kryptobaseddev/opencode-goal/issues"
+  }
+}

package/rpc.ts

@@ -0,0 +1,2 @@
+// Root RPC contract entry (see server.ts).
+export * from "./src/rpc"

package/server.ts

@@ -0,0 +1,3 @@
+// Root entry: OpenCode resolves <plugin dir>/server for local plugins and the
+// "./server" export for installed packages; both land here.
+export { default } from "./src/server/index"

package/skills/write-goal/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: write-goal
+description: 'Interview the owner and write a goal contract (a goal.yaml under .opencode/goals) that an autonomous goal loop can run until the host proves it done — a "grill me" session through the ask tool that turns a rough intention into an end state, binary criteria with real checks, invariants, protected oracles, non-goals, an optional budget and stop rules, then launches it. Use when the user wants to set up, write, draft, refine or start a goal, run something "until it''s done", use goal mode or /goal, make an agent loop on a task unattended, or says "grill me on this", "turn this into a goal", "goal new", "write-goal". In OpenCode, a bare "/goal new" phrasing is command-routed: the plugin attaches this skill explicitly, so no description-based triggering is needed for that phrasing — trigger evals should measure prose phrasings only. Do NOT use for ordinary one-off requests the user did not ask to turn into a goal.'
+license: MIT
+metadata:
+  version: "0.2.0"
+  last_updated: "2026-10-10 20:10:00"
+  author: kryptobaseddev
+  tags: "opencode, goal, goal-mode, planning, interview, autonomous-agents"
+---
+
+# write-goal
+
+Turn a rough intention into a **goal contract**: a structured `goal.yaml` that says what must become true, how the host proves it, where the work may reach, and when to stop — then launch it. A goal is a completion contract, not a task description. **Proof, not effort.**
+
+## Rules (read first)
+
+1. **Ask, don't narrate.** Every choice you put to the owner goes through the ask tool — `question` in OpenCode, `AskUserQuestion` in Claude Code — with 2-4 concrete options, the recommended option **first** and labelled `(Recommended)`, each description saying what happens and the trade-off. Never list options in prose and ask for a reply. Plain text is only for open-ended input ("what would prove this is done?"), or when no ask tool exists.
+2. **Facts are your job; decisions are the owner's.** Find commands, files and current results yourself (read the repo, run the checks, use explore subagents). Ask only what the repository cannot tell you. Subagents never ask the owner.
+3. **Only when asked.** Never wrap an ordinary request in a goal. If a task would suit goal mode, say so once and let the owner choose.
+4. **The owner's words stay authoritative.** Record them verbatim in `intent.verbatim`. Write in the owner's language.
+5. **Show the exact contract before launch** and get approval. If the owner wants a looser goal than you recommend, say why once, then write theirs.
+6. **Budgets are opt-in.** Never invent a turn cap; the goal stops on its proof or an honest blocker. Offer a budget only for open-ended work, framed in tokens or cost.
+
+## Workflow
+
+### 0 · Seed
+Capture the owner's words exactly. Pick a slug (kebab-case, ≤64 chars). Everything goes in `.opencode/goals/<slug>/`.
+
+### 1 · Recon (no questions yet)
+Inspect the project: package scripts, Makefile, CI config, test/lint/typecheck/bench commands, the files the intention touches, `git status`. Run the likely checks once to capture a **baseline** (a bug-fix goal should start red). Write the facts to `.opencode/goals/<slug>/context.md` — facts only, no decisions. **If the goal ships a new version of the tooling that will verify it** (a plugin, a harness, the goal engine itself), plan the reinstall of that new version into the release step — the completing verifier round runs the *installed* engine, not the one just built.
+
+### 2 · Classify
+bugfix · feature · refactor · migration · perf · research · ops · docs. The class suggests criteria:
+- **bugfix**: the failing case captured before, the same case passing after, plus "the rest of the suite SHALL CONTINUE TO pass".
+- **perf**: metric, threshold, method and run count ("p95 < 250ms across 3 runs").
+- **refactor/migration**: behaviour unchanged (invariants), an `absent` check that the old pattern is gone, a `diff` check on what must not move.
+- **feature**: observable behaviour per scenario (EARS: "WHEN … THE system SHALL …").
+- **research/docs**: the decision or artifact it must produce, judged by a `verifier` question or `human` sign-off.
+
+### 3 · Grill in frontier rounds
+Map the decisions as a tree. Each round, ask the **frontier** — every decision whose prerequisites are already settled — in one ask call (≤4 questions), each with your recommended option derived from recon. Fold each answer into the draft before the next round. Typical: 2-3 rounds, ≤10 questions. Stop when the frontier is empty. Branches, in order:
+1. **Outcome** — the one end state that becomes true.
+2. **Done when** — which checks prove it (prefer commands that already exist).
+3. **Evidence standard** — host checks only, or also the independent verifier / owner sign-off.
+4. **Invariants and oracles** — what must keep passing; which tests/benchmarks the worker may never edit (`protect`).
+5. **Scope and non-goals** — at least one non-goal.
+6. **Risk and escalation** — irreversible or destructive actions; when to stop and ask.
+7. **Budget** (opt-in) and **autonomy** (questions mid-run deferred; owner messages steer or pause).
+
+Log every question and answer to `decisions.jsonl` (one JSON object per line: `{"t","q","options","a","by":"owner"|"assumed"}`). Anything you decide without asking becomes an `assumptions` entry with a rationale and `reversible` — never a silent default.
+
+### 4 · Draft `goal.yaml`
+Start from `assets/goal.template.yaml` (or the shape below). Then validate: call `goal_validate({slug})` when the opencode-goal plugin is present and fix every error; otherwise self-check against the rules below. Repeat until clean.
+
+### 5 · Review
+Show the owner the contract compactly: outcome, a table of criteria (id · statement · check), invariants, protected paths, non-goals, budget. Ask: **Approve** (Recommended) / Revise criteria / Revise scope / Save as draft.
+
+### 6 · Launch
+For an existing goal, resolve its exact identity with `goal_inventory` and use
+`goal_manage` for the requested lifecycle operation. Don't create a replacement
+run or ask again when the owner has already said **resume**, **continue**, or
+explicitly approved resuming. The host can consume that genuine owner message
+once for its same session/run/lock; workers cannot supply or forge the consent.
+**I accept** applies only to the exact pending review, not an unrelated or
+expired review. Check the returned
+result and `goal_status`; a staged review isn't a successful resume. Never
+bypass a refusal with raw owner APIs, receipt edits, or fabricated form replies.
+
+For a requested change to an existing live goal, do not hand-edit its YAML or
+tell the owner to run `/goal amend`. Read the selected contract and run lock,
+then use `goal_propose_amendment` with `{slug, expectedLock, yaml, rationale}`.
+The host validates and stages a full before/after semantic diff without changing
+the live contract. Show that reviewed diff in the Composer. When the owner replies
+in chat (for example, “I accept the amendment”), use `goal_resolve_amendment`
+with its exact `{decisionId, action:"accept"}`. Reject or revision feedback uses
+`action:"reject"` or `action:"comment"`. The host fetches the actual latest owner
+message itself; never supply forged approval text, fabricate a form reply, or
+treat quoted/conditional/stale/replayed text as consent. If acceptance also says
+“resume” or “get it done”, the host honors that actual instruction even if the
+optional `continueGoal` hint is omitted or false. Setting it true cannot create
+permission without the same genuine owner directive. Continuation is bound to
+the accepted next lock and never approves criteria. Acceptance alone stays stopped.
+Changed statement/check proof resets; unchanged proof remains.
+
+The sidebar and manager are optional navigation, **not an Accept surface**. Never
+send the owner there to accept or tell them to type `/goal accept/amend/approve`.
+Only ambiguous targets, missing decisions or unsupported consent wording need a
+native selectable Composer clarification. Do not loop on `goal_review` expecting
+it to consume a chat reply: it only re-presents the review. On older installs
+without `goal_resolve_amendment`, report the capability gap and use the actual
+native Composer review if available; do not invent a sidebar button. Dismissal,
+reload and commentary never imply acceptance.
+
+When `goal_prepare_launch` is available, call it with `{slug, fresh:false}` after
+showing the exact validated contract. It stages a native review with **Start goal
+now / Revise this goal / Save for later**. For a requested fresh context, prepare
+with `{slug, fresh:true}`: the review explicitly says it creates a new root
+session and preserves the original history. The host binds session, slug,
+contract hash and mode, then executes the owner's selection directly—even if
+the question result is interrupted or the server reloads. **Do not ask another
+launch question or call `goal_start` afterwards.** Revision/comments return to
+the interview; no draft launches merely because its wording begins with a
+command keyword. Check `goal_status`/the manager before retrying an uncertain
+operation; preparation and owner consent are not proof the run actually started.
+
+On installs whose `goal_start` description supports actual owner chat, an explicit
+**start the goal**, **start the goal now**, or **continue your goal** instruction
+for the already displayed, unchanged draft uses `goal_start` with that exact slug
+and reviewed mode. Don't re-ask the interview or keep replacing expired forms.
+The host reads the actual owner history, matches the last displayed contract/hash/
+session/mode, and consumes a new authorization once; the agent supplies no consent
+text. A fresh chat instruction is not replay of an expired form answer. Generic,
+quoted, conditional, ambiguous or spent replies cannot launch. A pending unrelated
+form remains a blocker; dismissing a form alone isn't approval. On older installs,
+report the capability gap rather than replaying a timed choice or fabricating an
+owner API call. Always check `goal_status`: an expired receipt isn't a running goal.
+
+If a live goal's `goal.yaml` on disk differs from its locked contract (an edit
+made outside the engine, so staging and acceptance refuse), call
+`goal_recover_divergence` with `{slug, expectedLock}` from any live session of
+that project. The host shows the owner the exact difference and last-writer
+provenance with **Adopt disk version / Restore locked version / Leave
+unchanged**. An unaccepted proposal whose text matches the disk bytes is
+evidence, never consent. Never restore or edit the YAML by hand.
+
+Ask about agent autonomy during the interview when the owner wants fewer
+interruptions: `autonomy.amend` lists change classes (`timeout`, `budget`,
+`plan`, `recover`) the agent applies itself, journalled and undoable with
+`/goal revert <slug>`. The owner sets it; the agent can never widen it. Ask
+whether the verifier must read sibling folders; list them under
+`verification.read` (read-only) instead of letting rounds time out.
+
+If `goal_manage` returns `requiredReview` for an unresolved amendment, don't request
+another resume choice: the prerequisite prevents it from executing. The author can
+restore that exact review with `goal_review`; a live session may instead stage a
+validated diff against the same current run/lock for a **new** exact owner review.
+Staging doesn't transfer or cancel another author's consent. Only an applied,
+journalled generation retires conflicting unanswered proposals. If the original
+Core session is actually unavailable, use the supported owner-confirmed `attach`
+operation for the stopped run before resuming; mailbox release alone doesn't prove
+Core-session death. No lock/status/receipt edits or forced cross-session acceptance.
+
+Older installed plugins without `goal_prepare_launch` use this compatibility flow:
+Ask with these options: **`Start goal now`** (Recommended) / Start in a fresh session / **Start clean** / Save for later. The first option's label must **start with** `Start goal now` — a `(Recommended)` suffix is expected and fine (T068: the engine matches on the prefix, never byte-exact).
+- OpenCode with the plugin: on "Start goal now", call `goal_start({slug})`. On an approved fresh mode, call `goal_start({slug, fresh:true})`; it opens a **new root session**, prompts the kickoff there and preserves the original. The approval lasts 10 minutes and survives restarts. A refusal names missing, mismatched or expired approval: inspect it and present a fresh exact Composer review if needed. Never send the owner to a sidebar or manual command as a workaround.
+- Without a supported fresh-session launch capability, report that limitation explicitly; do not claim a handoff or ask the owner to operate a missing control.
+- Claude Code (no plugin): offer a `/goal` condition rendered from the contract (≤4,000 chars: the end state, the stated check, the constraints that matter).
+- Codex: offer `/goal <end state>. Done when <check>. Scope: <in/out>. If <blocker>, stop and report.`
+
+## The contract (`goal/v1`) — essentials
+
+```yaml
+schema: goal/v1
+id: fix-login-timeout              # = directory slug
+title: Login no longer times out   # ≤80 chars, shown in the sidebar
+intent:
+  verbatim: "login keeps timing out on slow networks, fix it"
+outcome: Login completes on a 3G-throttled connection without a timeout error
+non_goals: [Redesigning the login page]
+criteria:                          # binary; each must be able to fail
+  - id: C1
+    statement: WHEN the login e2e test runs under 3G throttling THE login SHALL succeed
+    check: {kind: command, run: "npm run test:e2e -- login-slow", expect: {exit: 0}, live: true}
+  - id: C2
+    statement: 'No hard-coded 5s timeout remains in src/auth'
+    check: {kind: absent, pattern: "timeout:\\s*5000", paths: [src/auth]}
+invariants:                        # must stay true all run; host-checkable kinds only
+  - id: I1
+    statement: The unit suite SHALL CONTINUE TO pass
+    check: {kind: command, run: "npm test"}
+protect: ["test/e2e/**"]           # oracles the worker may not edit
+plan:                              # optional; becomes the sidebar checklist
+  - {id: S1, title: Reproduce under throttling, proves: []}
+  - {id: S2, title: Fix the timeout handling, proves: [C1, C2], depends_on: [S1]}
+assumptions:
+  - {id: A1, text: 3G profile = 400ms RTT / 400kbps, rationale: Chrome DevTools preset, reversible: true}
+stop:
+  escalate_when: ["The fix needs a backend API change"]
+```
+
+Check kinds: `command` (`run`, `expect: {exit | stdout_contains | stdout_regex}`, `timeout` s, `runs`, `live`) · `file` (`path`, `exists`) · `contains` (`path`, `text`|`regex`) · `absent` (`pattern`, `paths`) · `diff` (`paths` unchanged since start) · `verifier` (`ask`: judged by a read-only verifier that must quote files) · `human` (`ask`: owner sign-off).
+
+Optional blocks: `why`, `scope {in, out}`, `constraints`, `budget {turns, wall: "3h", tokens: "3M", cost_usd}`, `autonomy {questions: defer|allow, on_user_message: steer|pause, on_interrupt: pause|resume-on-message}`, `verification {mode: host|host+verifier|strict, max_rejections}` (default `host+verifier`, 3).
+
+Rules the validator enforces: `schema: goal/v1`; `id` equals the directory; `intent.verbatim`, `outcome`, ≥1 `non_goals` and ≥1 essential criterion are required; ids are `C1…`, `I1…`, `S1…`, `A1…` and unique; every criterion has a check of a known kind with its required fields; invariants are host-checkable; plan references exist and have no cycles; budgets parse. Warnings: an outcome that reads as an activity ("keep improving…"), vague words without a number ("fast", "robust", "clean"), no host-checkable essential criterion. **Quote any value containing `: `** with single quotes. Keep every `command` check on a **single line**: YAML folded scalars (`>-`) fold equally-indented lines but keep literal newlines before more-indented ones, so a loop body written on its own line becomes a separate shell command at verify time. Rehearse each command check exactly as stored (extract it from the parsed YAML, run it through the login shell) before claiming.
+
+**Version-release criteria never pin an exact version string.** A `contains`/`stdout_contains` needle like `"version": "1.2.0"` goes stale the moment a patch ships mid-run and turns a proven criterion red for no reason (contract drift — the live v0.2 case). Check the semantic prefix instead: a one-line command such as `node -e "process.exit(require('./package.json').version.startsWith('1.2.')?0:1)"`, or a `contains` regex anchored on the major.minor pair.
+
+Full field reference: `references/goal-schema.md`. Question bank and recommendation heuristics: `references/interview.md`. Four complete contracts (bugfix, perf, migration, feature): `references/examples.md`.
+
+## Weak → strong
+
+- "Find all bugs" → `outcome: Every test in test/auth passes` · C1 `npm test -- test/auth` exits 0 · protect `test/**` · non-goal: no new features · escalate: a fix needs a schema change.
+- "Make it faster" → C1 `node bench/render.mjs` prints `speedup=3` or more across 3 runs (`stdout_regex`) · I1 suite passes · non-goal: no new dependencies.
+- "Clean up the old API" → C1 `absent` pattern `legacyClient\.` in `src/` · I1 build and tests pass · C2 `verifier`: "Does MIGRATION.md list every replaced call?".
+
+## Common mistakes
+
+| Mistake | Instead |
+|---|---|
+| Asking in prose, or one question per message | One ask call per frontier round with recommended options |
+| Asking what the repo can answer | Recon first; ask only owner decisions |
+| Effort instead of proof ("keep improving X") | An end state plus a check that can fail |
+| A check the worker can edit | Put the oracle under `protect` |
+| No non-goal | At least one, so the loop does not fill the vacuum |
+| Inventing a budget or turn cap | Leave it out unless the owner wants one |
+| A `command` check spread over indented lines | One line — folded scalars keep newlines before indented lines; rehearse the stored command before claiming |
+| A multi-lookahead `regex` in a `contains` check | The engine matches without dot-all — every `(?=.*phrase)` must be satisfiable on ONE line of the file; prefer one needle per criterion, or a single alternation |
+| Pinning a release with an exact version string (`contains "version": "1.2.0"` or `stdout_contains "1.2.0"`) | A prefix or semantic check — `node -e "process.exit(require('./package.json').version.startsWith('1.2.')?0:1)"` for a command, or a `contains` regex like `"version": "1\.2\.` — patch releases must not turn a passing criterion red (contract drift; the live v0.2 case) |
+| Launching before the owner saw the exact contract | Review step, then the `Start goal now` question |

package/skills/write-goal/assets/goal.template.yaml

@@ -0,0 +1,38 @@
+# goal/v1 contract — fill every field marked REQUIRED; delete optional blocks you do not need.
+# Values that contain ": " must be wrapped in single quotes.
+schema: goal/v1
+id: my-goal                     # REQUIRED: equals the directory name .opencode/goals/my-goal/
+title: One line the owner will recognise   # REQUIRED, ≤80 chars
+intent:
+  verbatim: "the owner's own words, unedited"   # REQUIRED
+outcome: The single end state that is true when this is done   # REQUIRED: not an activity
+why: Why it matters (optional)
+scope:
+  in: [src/area/**]
+  out: [anything outside src/area]
+non_goals:                      # REQUIRED: at least one
+  - Something the loop must not wander into
+constraints:
+  - A non-negotiable that rules options out
+criteria:                       # REQUIRED: at least one essential criterion
+  - id: C1
+    statement: WHEN the target check runs THE result SHALL pass
+    essential: true
+    check: {kind: command, run: "npm test", expect: {exit: 0}, timeout: 600, live: true}
+invariants:
+  - id: I1
+    statement: The existing build SHALL CONTINUE TO succeed
+    check: {kind: command, run: "npm run build"}
+protect:                        # oracles the worker may never edit
+  - "test/**"
+assumptions:
+  - {id: A1, text: A default chosen without asking, rationale: why it is reasonable, reversible: true}
+plan:
+  - {id: S1, title: First concrete step, proves: []}
+  - {id: S2, title: Step that makes C1 true, proves: [C1], depends_on: [S1]}
+stop:
+  when: Every essential criterion is host-verified and invariants hold
+  escalate_when:
+    - The change needs an irreversible or destructive action
+autonomy: {questions: defer, on_user_message: steer, on_interrupt: pause}
+verification: {mode: host+verifier, max_rejections: 3}

package/skills/write-goal/references/examples.md

@@ -0,0 +1,283 @@
+# Worked examples
+
+Four complete `goal/v1` contracts, one per common class (bugfix, perf, migration,
+feature). Copy one into `.opencode/goals/<slug>/goal.yaml`, replace the placeholders
+with facts from your recon, and validate (`goal_validate({slug})` or the parser).
+
+Every example here parses with the plugin's own `parseContract` — treat them as
+templates that must stay valid, not as prose.
+
+---
+
+## 1 · Bugfix — a timeout that only happens on slow networks
+
+```yaml
+schema: goal/v1
+id: fix-login-timeout
+title: Login no longer times out on 3G
+intent:
+  verbatim: 'login keeps timing out on slow networks, fix it'
+outcome: Login completes on a 3G-throttled connection without a timeout error
+non_goals:
+  - Redesigning the login page
+  - Touching the session refresh flow
+criteria:
+  - id: C1
+    statement: WHEN the login e2e test runs under 3G throttling THE login SHALL succeed
+    check:
+      kind: command
+      run: npm run test:e2e -- login-slow
+      expect: { exit: 0 }
+      live: true
+      timeout: 300
+  - id: C2
+    statement: 'No hard-coded 5s timeout remains in src/auth'
+    check:
+      kind: absent
+      pattern: 'timeout:\s*5000'
+      paths: [src/auth]
+invariants:
+  - id: I1
+    statement: The full unit suite SHALL CONTINUE TO pass
+    check:
+      kind: command
+      run: npm test
+      expect: { exit: 0 }
+protect: ['test/e2e/**']
+plan:
+  - id: S1
+    title: Reproduce under throttling
+    proves: []
+  - id: S2
+    title: Fix the timeout handling
+    proves: [C1, C2]
+    depends_on: [S1]
+assumptions:
+  - id: A1
+    text: 3G profile is 400ms RTT / 400kbps
+    rationale: Chrome DevTools preset
+    reversible: true
+stop:
+  escalate_when:
+    - 'The fix needs a backend API change'
+```
+
+---
+
+## 2 · Perf — a render pass that must get measurably faster
+
+```yaml
+schema: goal/v1
+id: speed-up-render
+title: Board render is at least 3x faster on 10k rows
+intent:
+  verbatim: 'the board takes forever to render with 10k rows, make it at least 3 times faster'
+outcome: The render benchmark reports speedup of 3 or more versus the baseline, with no visual regressions
+non_goals:
+  - Rewriting the board in a different framework
+  - Changing the rendered markup or styling
+criteria:
+  - id: C1
+    statement: THE render benchmark SHALL report speedup of 3 or more across 3 runs
+    check:
+      kind: command
+      run: node bench/render.mjs --runs 3
+      expect: { stdout_regex: 'speedup=([3-9]|\d{2,})' }
+      runs: 3
+  - id: C2
+    statement: THE board snapshot SHALL be unchanged
+    check:
+      kind: command
+      run: npm test -- board.snapshot
+      expect: { exit: 0 }
+invariants:
+  - id: I1
+    statement: The full test suite SHALL CONTINUE TO pass
+    check:
+      kind: command
+      run: npm test
+      expect: { exit: 0 }
+  - id: I2
+    statement: 'The baseline bench result (bench/baseline.json) SHALL NOT change'
+    check:
+      kind: diff
+      paths: [bench/baseline.json]
+protect: ['bench/**']
+scope:
+  in:
+    - 'src/board render path only'
+  out:
+    - 'The data-loading pipeline'
+stop:
+  escalate_when:
+    - 'Speedup 2x is reachable but 3x needs a data-model change'
+```
+
+---
+
+## 3 · Migration — retire an old client without behaviour change
+
+```yaml
+schema: goal/v1
+id: drop-legacy-client
+title: Every call site uses the new API client
+intent:
+  verbatim: 'remove every legacyClient call and move to the new api client, nothing should behave differently'
+outcome: 'No legacyClient import or call remains in src/, the suite and typecheck pass, and MIGRATION.md documents the replacement for every removed call'
+non_goals:
+  - Changing request payloads or endpoints
+  - Deleting the legacy client package from package.json
+criteria:
+  - id: C1
+    statement: 'No legacyClient reference remains in src/'
+    check:
+      kind: absent
+      pattern: 'legacyClient\.'
+      paths: [src]
+  - id: C2
+    statement: The typecheck and full suite pass after the migration
+    check:
+      kind: command
+      run: npm run typecheck && npm test
+      expect: { exit: 0 }
+      timeout: 600
+  - id: C3
+    statement: MIGRATION.md lists a replacement for every removed call
+    check:
+      kind: verifier
+      ask: >-
+        Read MIGRATION.md and git log for this run. For every legacyClient call site
+        removed, does MIGRATION.md name the new-api replacement? Quote one line per
+        gap you find.
+invariants:
+  - id: I1
+    statement: 'The public API surface (api/public.d.ts) SHALL NOT change'
+    check:
+      kind: diff
+      paths: [api/public.d.ts]
+protect: ['api/public.d.ts']
+plan:
+  - id: S1
+    title: Map every legacyClient call site
+    proves: []
+  - id: S2
+    title: Replace call sites in dependency order
+    proves: [C1]
+  - id: S3
+    title: Document replacements in MIGRATION.md
+    proves: [C3]
+    depends_on: [S2]
+```
+
+---
+
+## 4 · Feature — an export button with observable behaviour per scenario
+
+```yaml
+schema: goal/v1
+id: csv-export
+title: Users can export the orders table as CSV
+intent:
+  verbatim: 'add an export button to the orders table that downloads a csv'
+outcome: The orders table has an Export CSV button that downloads the currently filtered rows as valid CSV
+non_goals:
+  - XLSX or PDF export
+  - Server-side async export jobs
+criteria:
+  - id: C1
+    statement: WHEN the user clicks Export CSV with filters applied THE download SHALL contain exactly the filtered rows in display order
+    check:
+      kind: command
+      run: npm run test:e2e -- orders-export
+      expect: { exit: 0 }
+      live: true
+  - id: C2
+    statement: THE csv writer SHALL escape quotes, commas and newlines
+    check:
+      kind: command
+      run: npm test -- csvWriter
+      expect: { exit: 0 }
+  - id: C3
+    statement: The export button is approved design-wise by the owner
+    check:
+      kind: human
+      ask: 'Open the orders page and confirm the Export CSV button matches the design mock'
+invariants:
+  - id: I1
+    statement: The full test suite SHALL CONTINUE TO pass
+    check:
+      kind: command
+      run: npm test
+      expect: { exit: 0 }
+  - id: I2
+    statement: No new runtime dependency SHALL be added
+    check:
+      kind: contains
+      path: package.json
+      text: '"dependencies": {'
+scope:
+  in:
+    - 'src/orders table, src/lib/csv writer, e2e coverage'
+  out:
+    - 'Other tables and pages'
+stop:
+  escalate_when:
+    - 'Exports above 50k rows would need a streaming format change'
+```
+
+---
+
+## 5 · Release — ship v1.2 and keep the check true across patch releases
+
+The trap this example exists for: pinning the release with an exact version
+string. `contains "version": "1.2.0"` passes on release day and then fails
+the moment 1.2.1 ships mid-run — contract drift, red criterion, an owner
+amendment that changes nothing real (this exact case closed the v0.2 dogfood
+run). Check the semantic prefix instead.
+
+```yaml
+schema: goal/v1
+id: ship-v1-2
+title: v1.2 released from a clean tree
+intent:
+  verbatim: "cut the 1.2 release"
+outcome: v1.2.x is tagged, the changelog carries it, and a clean checkout of the tag passes its own suite
+non_goals:
+  - Rewriting release automation
+  - Backporting to 1.1
+criteria:
+  - id: C1
+    statement: package.json is semantically bumped for the 1.2 line
+    check: {kind: command, run: 'node -e "process.exit(require(\"./package.json\").version.startsWith(\"1.2.\")?0:1)"'}
+  - id: C2
+    statement: CHANGELOG.md carries the 1.2 entry
+    check: {kind: contains, path: CHANGELOG.md, regex: "## \\[?1\\.2\\."}
+  - id: C3
+    statement: the pushed tag installs from git in an isolated environment
+    check: {kind: command, run: 'INSTALL_TEST=1 TAG=v1.2.0 bun test test/release/git-install.test.ts', timeout: 600}
+invariants:
+  - id: I1
+    statement: the suite still passes on the release commit
+    check: {kind: command, run: "bun test"}
+protect: ["docs/baselines/**"]
+plan:
+  - {id: S1, title: Bump + changelog, proves: [C1, C2]}
+  - {id: S2, title: Tag, push, git-install proof, proves: [C3, I1], depends_on: [S1]}
+```
+
+Why each check holds across patch releases: C1 reads the version and asserts
+the `1.2.` prefix — 1.2.0, 1.2.1, 1.2.9 all pass, 1.3.0 fails (the line
+moved on, which SHOULD be red); C2 anchors the changelog heading on the
+major.minor pair; only C3 names an exact tag, because a specific tag is
+genuinely what it verifies.
+
+---
+
+## What makes these pass
+
+- Every criterion is **binary and able to fail**: a command that can exit non-zero, a
+  pattern that can still be present, a question a verifier can answer "no" to.
+- Invariants pin what must not regress; `protect` pins the files the worker may never
+  edit (oracles, baselines, public API surfaces).
+- Each has at least one **non-goal**, so the loop cannot invent scope when it stalls.
+- Budgets are absent on purpose — the goals stop on proof or an honest blocker.