@cleocode/goal 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,53 @@
+# goal/v1 field reference
+
+The plugin's parser (`src/contract/parse.ts` in opencode-goal) is the source of truth; this mirrors it.
+
+## Top level
+
+| Field | Required | Notes |
+|---|---|---|
+| `schema` | yes | exactly `goal/v1` |
+| `id` | yes | kebab-case slug, ≤64 chars, equals the directory name |
+| `title` | yes | ≤80 chars recommended (sidebar) |
+| `intent.verbatim` | yes | the owner's words, never rewritten |
+| `outcome` | yes | one end state; warned if it reads as an activity or uses vague words without a number |
+| `why` | no | |
+| `scope.in` / `scope.out` | no | globs or plain descriptions |
+| `non_goals` | yes (≥1) | |
+| `constraints` | no | |
+| `criteria` | yes (≥1 essential) | ids `C1…` |
+| `invariants` | no | ids `I1…`, host-checkable kinds only, always essential |
+| `protect` | no | globs the worker may not edit; enforced before edits and re-checked at verification |
+| `assumptions` | no | ids `A1…`; `status` assumed (default) / confirmed / vetoed |
+| `plan` | no | ids `S1…`; `proves` must reference criteria; `depends_on` must reference steps; no cycles |
+| `budget` | no | `turns` (int), `wall` ("90m", "3h", "1h30m"), `tokens` (400k, "3M"; spend across the run), `cost_usd` |
+| `stop.when`, `stop.escalate_when` | no | shown to the worker; escalation means `goal_block` |
+| `autonomy` | no | `questions` defer (default) / allow · `on_user_message` steer (default) / pause · `on_interrupt` pause (default) / resume-on-message · `amend`: owner-set policy, a list of change classes the agent may apply to its own contract without asking — `timeout` (a check's timeout only), `budget`, `plan` (plan steps and assumptions), `recover` (adopt an in-policy out-of-band disk edit). Default `[]` = owner reviews every change. Criteria statements/checks, protect, scope, verification, stop rules and the policy itself are never agent-applicable. |
+| `verification` | no | `mode` host / host+verifier (default) / strict · `max_rejections` 1-10 (default 3) · `read`: extra folders or files outside the project the verifier may READ (plain paths, relative to the project root; never writable; everything else outside the project stays denied) |
+| `execution.agent` | no | informational in v0.1 |
+| `meta` | no | free-form |
+
+## Criterion
+
+```yaml
+- id: C1
+  statement: WHEN … THE … SHALL …        # binary, specific
+  essential: true                         # default true; optional criteria never block completion
+  check: { kind: …, … }
+```
+
+| `check.kind` | Fields | Passes when |
+|---|---|---|
+| `command` | `run` (required), `expect.exit` (default 0), `expect.stdout_contains`, `expect.stdout_regex`, `timeout` seconds (default 300), `runs` (1-10, all must pass), `live` (re-run by the host after turns that changed files) | every run meets every expectation; runs in the owner's login shell at the project root |
+| `file` | `path`, `exists` (default true) | the path exists (or not) |
+| `contains` | `path`, `text` or `regex` | the file contains it |
+| `absent` | `pattern` (extended regex), `paths` | `git grep` finds no match (goal state excluded) |
+| `diff` | `paths` (globs) | none changed since the run started |
+| `verifier` | `ask` | the read-only verifier answers proven with quotes the host finds verbatim in the files |
+| `human` | `ask` | the owner approves it (`/goal approve C3`) |
+
+## Validator messages
+
+Errors: wrong schema · bad or mismatched id · missing title / intent.verbatim / outcome · no non-goals · no criteria · no essential criterion · criterion id not `C<n>` · missing statement · missing or unknown check kind · missing kind fields (run, path, pattern, paths, ask, text|regex) · invalid regex · non-positive timeout · invariant with a non-host kind · duplicate ids · plan id not `S<n>` · unknown `proves`/`depends_on` · dependency cycle · bad budget values · bad autonomy / verification values · invalid YAML (with a hint for unquoted `: `).
+
+Warnings: title over 80 chars · outcome reads as an activity · vague words without a number (outcome and statements) · no host-checkable essential criterion.

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

@@ -0,0 +1,36 @@
+# Interview: frontier rounds
+
+## Protocol
+1. After recon, write every open decision as a node; note which decisions depend on which.
+2. A round asks the **frontier**: the decisions whose prerequisites are settled. One ask call, ≤4 questions, 2-4 options each, recommended option first with "(Recommended)", every option describing what happens and its trade-off.
+3. After the answers, update the draft contract and `decisions.jsonl`, then compute the next frontier.
+4. Stop when the frontier is empty: an implementer agent could run the contract without asking a single question.
+5. Anything not worth the owner's time becomes an assumption: `{id, text, rationale, reversible}`.
+
+`decisions.jsonl` line: `{"t":"2026-10-02T23:00:00Z","q":"What proves it is done?","options":["npm test exits 0","…"],"a":"npm test exits 0","by":"owner"}`
+
+## Question bank (recommendation heuristics in brackets)
+
+**Outcome** — "Which end state should be true when this goal finishes?" [the narrowest state that satisfies the owner's words; offer one broader and one narrower alternative]
+
+**Done when** — "What proves it?" [existing commands from recon first: the failing test, the suite, the build, a bench; a new check only if none exists]
+
+**Evidence standard** — "How strict is completion?" [host checks + independent verifier (Recommended) · host checks only (cheapest; semantic criteria need owner sign-off) · strict (verifier re-confirms host checks)]
+
+**Oracles** — "Which files must the worker never change?" [the tests and benchmarks named in Done-when]
+
+**Invariants** — "What must keep working the whole time?" [the full test suite, the build, typecheck]
+
+**Scope / non-goals** — "Where may the work reach, and what is explicitly out?" [the module recon found; non-goal = the most tempting adjacent change]
+
+**Escalation** — "When should it stop and ask instead of pushing on?" [irreversible data changes, public API changes, new dependencies, credentials]
+
+**Budget** (only for open-ended goals) — "Cap the spend?" [no cap (Recommended for well-proven goals) · a token cap sized to the work · a wall-clock cap]
+
+**Autonomy** — "If you type while it runs?" [steer: your message guides the next turn (Recommended) · pause]
+
+**Priority** (ask only when the project already has a live goal — check the registry or `.opencode/goals/*/run.json` for a non-terminal run; a first goal needs no ordering) — "Where does this goal rank against the live one if you must choose where work goes first?" [medium (Recommended: the default lane) · high (first in /goal list, the palette and the start picker; taken ahead of the live goal) · low (lists last; the live goal keeps the attention) · skip (no field — sorts last by recency)]
+
+## Launch question
+
+Options, in this order: `Start goal now` (Recommended; the label must start with the exact text `goal_start` checks) · Start in a fresh session · Start clean (the engine opens a new session owned by the goal) · Save for later.

package/src/cli/install.ts

@@ -0,0 +1,125 @@
+// `cleo-goal install --project`: register this plugin in the PROJECT's OpenCode
+// v2 config (`.opencode/opencode.json`, key `plugins`). Idempotent. Never the
+// user-global config: `opencode plugin add` only writes the global file, which is
+// why this exists.
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeSync } from "node:fs"
+import { homedir } from "node:os"
+import { isAbsolute, join, relative, resolve, sep } from "node:path"
+
+export const INSTALL_SCHEMA_VERSION = 1
+export const PACKAGE_NAME = "@cleocode/goal"
+/** Specs that name this plugin, whatever the version: the npm package and the git repo it was installed from before npm. */
+const IDENTITIES = [PACKAGE_NAME, "github:kryptobaseddev/opencode-goal", "opencode-goal"]
+export const PROJECT_CONFIG = join(".opencode", "opencode.json")
+
+type Options = Record<string, unknown>
+export type PluginEntry = string | [string, Options] | { package: string; options?: Options }
+
+export type InstallResult = {
+  schemaVersion: typeof INSTALL_SCHEMA_VERSION
+  action: "installed" | "already-present" | "updated" | "dry-run"
+  file: string
+  spec: string
+  plugins: PluginEntry[]
+}
+
+export class InstallError extends Error {}
+
+const specOf = (entry: PluginEntry): string => (typeof entry === "string" ? entry : Array.isArray(entry) ? entry[0] : entry.package)
+
+/** The spec without its version, tag or ref: `@cleocode/goal@0.8.1` → `@cleocode/goal`. */
+export function identity(spec: string): string {
+  const hash = spec.indexOf("#")
+  const bare = hash === -1 ? spec : spec.slice(0, hash)
+  const at = bare.lastIndexOf("@")
+  return at > 0 ? bare.slice(0, at) : bare
+}
+
+const isOurs = (entry: PluginEntry) => IDENTITIES.includes(identity(specOf(entry)))
+
+const withSpec = (entry: PluginEntry, spec: string): PluginEntry =>
+  typeof entry === "string" ? spec : Array.isArray(entry) ? [spec, entry[1]] : { ...entry, package: spec }
+
+const canonical = (path: string) => {
+  try {
+    return realpathSync(path)
+  } catch {
+    return resolve(path)
+  }
+}
+
+const inside = (child: string, parent: string) => {
+  const rel = relative(parent, child)
+  return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+}
+
+/**
+ * Refuse anything that is user-global OpenCode config: the home directory as a
+ * project, a project under the config dirs, and (T13871) a `.opencode` dir or
+ * `opencode.json` that resolves, through a symlink, into a config dir or
+ * anywhere outside the project.
+ */
+function assertProjectScoped(root: string, home: string) {
+  const r = canonical(root)
+  const h = canonical(home)
+  if (r === h) throw new InstallError(`refusing to install into the home directory (${h}): its .opencode/ is user-global; run from a project`)
+  const globals = [...new Set([canonical(process.env.XDG_CONFIG_HOME || join(h, ".config")), canonical(join(h, ".config")), canonical(join(h, ".opencode"))])]
+  const underGlobal = (path: string) => globals.find((g) => inside(path, g))
+  const g = underGlobal(r)
+  if (g) throw new InstallError(`refusing to install under ${g}: that is user-global config; run from a project`)
+  for (const target of [join(root, ".opencode"), join(root, PROJECT_CONFIG)]) {
+    if (!existsSync(target)) continue
+    const real = canonical(target)
+    const global = underGlobal(real)
+    if (global) throw new InstallError(`refusing to write ${target}: it resolves to ${real}, inside user-global ${global}`)
+    if (!inside(real, r)) throw new InstallError(`refusing to write ${target}: it resolves to ${real}, outside the project ${r}`)
+  }
+}
+
+function readPlugins(path: string): { config: Record<string, unknown>; plugins: PluginEntry[] } {
+  if (!existsSync(path)) return { config: {}, plugins: [] }
+  let config: unknown
+  try {
+    config = JSON.parse(readFileSync(path, "utf8"))
+  } catch (error) {
+    throw new InstallError(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); left untouched`)
+  }
+  if (!config || typeof config !== "object" || Array.isArray(config)) throw new InstallError(`${path} is not a JSON object; left untouched`)
+  const record = config as Record<string, unknown>
+  const plugins = record.plugins ?? []
+  if (!Array.isArray(plugins)) throw new InstallError(`${path}: "plugins" is not an array; left untouched`)
+  return { config: record, plugins: plugins as PluginEntry[] }
+}
+
+function writeAtomic(path: string, text: string) {
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+  const fd = openSync(tmp, "wx", 0o644)
+  try {
+    writeSync(fd, text)
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  renameSync(tmp, path)
+}
+
+/** Add (or move to `spec`) this plugin in `<root>/.opencode/opencode.json`. */
+export function installProject(root: string, spec: string, options: { dryRun?: boolean; home?: string } = {}): InstallResult {
+  assertProjectScoped(root, options.home ?? homedir())
+  const path = join(root, PROJECT_CONFIG)
+  if (!existsSync(path) && existsSync(`${path}c`)) {
+    throw new InstallError(`${PROJECT_CONFIG}c exists; add "${spec}" to its "plugins" by hand (JSONC is not rewritten, to keep its comments)`)
+  }
+  const { config, plugins } = readPlugins(path)
+  const ours = plugins.findIndex(isOurs)
+  const next = ours === -1 ? [...plugins, spec] : plugins.map((entry, i) => (i === ours ? withSpec(entry, spec) : entry)).filter((entry, i) => i <= ours || !isOurs(entry))
+  const action = ours === -1 ? "installed" : specOf(plugins[ours]!) === spec && plugins.filter(isOurs).length === 1 ? "already-present" : "updated"
+  const result = { schemaVersion: INSTALL_SCHEMA_VERSION, file: PROJECT_CONFIG, spec, plugins: action === "already-present" ? plugins : next } as const
+  if (options.dryRun) return { ...result, action: "dry-run" }
+  if (action !== "already-present") {
+    mkdirSync(join(root, ".opencode"), { recursive: true })
+    // A symlinked opencode.json inside the project is written through, never replaced by a file.
+    writeAtomic(existsSync(path) ? canonical(path) : path, `${JSON.stringify({ ...config, plugins: next }, null, 2)}\n`)
+  }
+  return { ...result, action }
+}

package/src/cli/status.ts

@@ -0,0 +1,116 @@
+// `cleo-goal status --json`: the read contract CLEO parses (schemaVersion 1).
+// CLEO never reads run.json directly; this is the only shape it relies on, so
+// a field change here is a schemaVersion bump.
+import { parseContract } from "../contract/parse"
+import type { Contract } from "../contract/types"
+import { budgetUse, isTerminal, type RunState, type Status } from "../engine/state"
+import type { Store } from "../engine/store"
+
+export const STATUS_SCHEMA_VERSION = 1
+
+export type StatusCriterion = {
+  id: string
+  statement: string
+  status: "unknown" | "pass" | "fail" | "claimed"
+  essential: boolean
+  invariant: boolean
+  by: string | null
+  detail: string | null
+}
+
+export type GoalStatusJson = {
+  schemaVersion: typeof STATUS_SCHEMA_VERSION
+  goal: string | null
+  runId: string | null
+  title: string
+  status: Status | "none"
+  priority?: "low" | "medium" | "high"
+  turn: number
+  reason: string | null
+  criteria: StatusCriterion[]
+  proven: number
+  total: number
+  budget: { ratio: number; parts: Array<{ name: string; used: number; limit: number }> }
+  verdict: { passed: boolean; lines: string[]; turn: number } | null
+  blocker: { key: string; count: number; reason: string } | null
+  updatedAt: number
+}
+
+const NONE: GoalStatusJson = {
+  schemaVersion: STATUS_SCHEMA_VERSION,
+  goal: null,
+  runId: null,
+  title: "",
+  status: "none",
+  turn: 0,
+  reason: null,
+  criteria: [],
+  proven: 0,
+  total: 0,
+  budget: { ratio: 0, parts: [] },
+  verdict: null,
+  blocker: null,
+  updatedAt: 0,
+}
+
+/** The run to report: the newest live run, else the newest finished one. */
+export function selectRun(store: Store): RunState | undefined {
+  const runs = store
+    .slugs()
+    .map((slug) => store.readRun(slug))
+    .filter((run): run is RunState => Boolean(run))
+    .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+  return runs.find((run) => !isTerminal(run.status)) ?? runs[0]
+}
+
+/** The contract generation the run locked (the disk copy may have moved on). */
+function lockedContract(store: Store, run: RunState): Contract | undefined {
+  const disk = store.readContract(run.slug)
+  if (disk?.contract && disk.lock === run.lock) return disk.contract
+  try {
+    return parseContract(store.lockedText(run.slug, run.runId, run.lock), { slug: run.slug }).contract ?? disk?.contract
+  } catch {
+    return disk?.contract
+  }
+}
+
+/** Build the status reply for the project the store belongs to. */
+export function goalStatus(store: Store, now = Date.now()): GoalStatusJson {
+  const run = selectRun(store)
+  if (!run) return NONE
+  const contract = lockedContract(store, run)
+  const declared = contract
+    ? [...contract.criteria.map((c) => ({ c, invariant: false })), ...contract.invariants.map((c) => ({ c, invariant: true }))]
+    : []
+  const criteria: StatusCriterion[] = declared.map(({ c, invariant }) => {
+    const state = run.criteria[c.id]
+    return {
+      id: c.id,
+      statement: c.statement,
+      status: state?.status ?? "unknown",
+      essential: c.essential,
+      invariant,
+      by: state?.by ?? null,
+      detail: state?.detail ?? null,
+    }
+  })
+  const states = Object.values(run.criteria).filter((c) => c && typeof c === "object")
+  const budget = contract ? budgetUse(run, contract, now) : { ratio: 0, parts: [] }
+  return {
+    schemaVersion: STATUS_SCHEMA_VERSION,
+    goal: run.slug,
+    runId: run.runId,
+    title: run.title,
+    status: run.status,
+    ...(run.priority ? { priority: run.priority } : {}),
+    turn: run.turn,
+    reason: run.reason ?? null,
+    criteria,
+    proven: states.filter((c) => c.status === "pass").length,
+    total: states.length,
+    budget: { ratio: budget.ratio, parts: budget.parts.map((p) => ({ name: p.name, used: p.used, limit: p.limit })) },
+    verdict: run.verdict ? { passed: run.verdict.passed, lines: run.verdict.lines, turn: run.verdict.turn } : null,
+    blocker: run.blocker ? { key: run.blocker.key, count: run.blocker.count, reason: run.blocker.reason } : null,
+    updatedAt: run.updatedAt,
+  }
+}