@sorenllm/opencode-forge 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,10 @@
 # opencode-forge
 
-Single general-purpose **forge** agent + a plan harness for
-[opencode](https://opencode.ai) ≥ 1.18. Plans become first-class files on
-disk with tool-enforced structure, a hard write-ban while planning, user
-confirmation gates for approve/close, and tick-as-you-go task tracking.
+Single general-purpose **forge** agent + two orthogonal harnesses for
+[opencode](https://opencode.ai) ≥ 1.18: a **plan harness** (decide first,
+execute later) and a **goal harness** (arm an objective, let the loop drive
+itself to a host-verified finish). They share nothing but a safety interop;
+OpenSpec spec workflows remain a third, separate lane.
 
 ```
 /plan fix login timeout   → read-only recon → plan_write (draft, writes denied)
@@ -16,6 +17,18 @@ confirmation gates for approve/close, and tick-as-you-go task tracking.
 /plan discard             → abandon the current plan (abandoned, writes restored)
 ```
 
+```
+/goal make the suite green --check "npm test" --contains "src/a.ts::export const A"
+                          → goal_write (arm=true; the user dialog IS the arm action)
+                          → loop: work → goal_check (advisory) → idle → continuation brief
+                          → goal_complete re-runs EVERY check itself on the host
+                            (fail-closed) + per-criterion attestations → user dialog
+                            = completion gate → completed
+/goal add ...             → queue an inert goal (no dialog, no loop)
+/goal                     → live goal + queue overview
+/goal pause | resume | discard/stop/cancel
+```
+
 - Plan files: `.opencode/plan/<date>-<slug>.md` in your project, frontmatter
   state machine `draft → approved → done` (exit: `abandoned`).
 - While a plan is in draft, `write` / `edit` / `bash` / `task` are **denied
@@ -23,9 +36,14 @@ confirmation gates for approve/close, and tick-as-you-go task tracking.
   exits are approval and discard. This is deliberate; see Design stance.
 - `plan_approve` / `plan_close` are pinned to a confirmation dialog: the
   model can never flip the state itself.
+- Goal files: `.opencode/goal/<date>-<slug>.md`, state machine
+  `queued → active ⇄ paused → completed / abandoned`, one live goal per
+  session plus a workspace queue. Completion is **verified by the plugin**,
+  not attested by the model: `goal_complete` re-executes every check itself
+  and refuses (fail-closed) on any failure.
 - The native `build` / `plan` agents are hidden while the plugin is loaded
   (runtime injection, nothing written to your config). Uninstall restores
-  them automatically; plan files are never deleted.
+  them automatically; plan and goal files are never deleted.
 
 ## Install
 
@@ -65,22 +83,22 @@ the plugin never writes them):
 }
 ```
 
-If you already have a `command.plan` of your own, it wins and the plugin's
-`/plan` is not registered.
+If you already have a `command.plan` or `command.goal` of your own, it wins
+and the plugin's command of that name is not registered.
 
 ## Uninstall (four steps, restores native opencode)
 
 1. Remove the plugin entry from the `plugin` array in
    `~/.config/opencode/opencode.json` (global installs).
 2. Delete the package store dir:
-   `~/.cache/opencode/packages/github_ChengZiiii/opencode-forge/` (github
-   installs, owner/repo layout; for npm installs it is
-   `~/.cache/opencode/packages/opencode-forge/`).
+   `~/.cache/opencode/packages/@sorenllm/opencode-forge/` (npm installs,
+   scope-dir layout; for github installs it is
+   `~/.cache/opencode/packages/github_ChengZiiii/opencode-forge/`).
 3. Delete the `agent["forge"]` block from your config if you added one
    (otherwise the name lingers in the agent list).
 4. Done — the hidden native `build`/`plan` agents come back automatically
-   (the hide was runtime-only). Your `.opencode/plan/` files are yours;
-   delete them yourself if you want.
+   (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
+   files are yours; delete them yourself if you want.
 
 ## File ledger
 
@@ -89,11 +107,84 @@ What this plugin touches, exhaustively:
 | Where | What | Lifetime |
 | --- | --- | --- |
 | `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
-| merged config object (RAM only) | forge agent, native build/plan `disable`, `skills.paths` entry, `command.plan` | vanishes when the plugin is removed; nothing is written to disk |
+| `<project>/.opencode/goal/*.md` | goal files (contract, Check Log, Turn Ledger) | user data — kept forever, uninstall never deletes |
+| merged config object (RAM only) | forge agent, native build/plan `disable`, `skills.paths` entry, `command.plan`, `command.goal`, goal permission keys | vanishes when the plugin is removed; nothing is written to disk |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
-The plugin writes no temp files, no logs, nothing outside the table.
+The plugin writes no temp files, no logs, nothing outside the table (a
+`FORGE_GOAL_PROBE=1` env opt-in appends continuation diagnostics to the OS
+temp dir for debugging).
+
+## Goal mode (autonomous, host-verified objectives)
+
+Three orthogonal workflows — pick per task, they never bind to each other:
+
+| Workflow | decides | use when |
+| --- | --- | --- |
+| OpenSpec change | spec deltas, review gates | multi-session features with spec impact |
+| `/plan` | approach + task order, you approve then it executes | single-task execution you want to review first |
+| `/goal` | arm an objective + verification contract, the loop executes | well-defined objective with machine-checkable success |
+
+`/goal <objective>` drafts a **contract**: goal, success criteria,
+verification checks, constraints, non-goals, budgets. Contract markers in the
+objective map to structured fields:
+
+```
+/goal make the release green --check "npm test" --check "npm run lint"
+      --contains "CHANGELOG.md::## Unreleased"
+      --success "zero failing tests" --constraint "no dependency bumps"
+      --non-goal "refactoring" --max-turns 15 --max-minutes 30
+```
+
+Two check types, both **executed by the plugin on the host** (the model never
+grades its own homework):
+
+- `--check "cmd"` — shell command in the workspace; passes on exit 0,
+  timeout-configurable (default 120 s, max 600 s).
+- `--contains "file::text"` — file contract: the literal text must be present
+  in that workspace file.
+
+**Arming and the loop.** `goal_write` with `arm=true` pops one confirmation
+dialog — your Allow IS the arm action; nothing autonomous runs before it.
+From then on, whenever the session goes idle, the plugin re-prompts the agent
+with a `[forge:goal-continue]` brief (with debounce, owner-checked, and
+compaction-aware: autocontinue is suppressed for active-goal sessions so a
+context compaction can never silently re-trigger the loop). Each continuation
+turn is counted and recorded in the goal's Turn Ledger.
+
+**Budgets and auto-pause.** `--max-turns` (default 25, hard ceiling 200) and
+`--max-minutes` (default 60, hard ceiling 480). The loop pauses itself — with
+a `stop_reason` in the frontmatter — on: budget exhaustion, two consecutive
+no-progress continuation turns, three consecutive transport failures, or a
+live draft plan appearing in the session (the only plan/goal interop: a draft
+plan's write ban would wall the loop off, so the goal pauses instead of
+burning turns against it). `/goal pause` (or `goal_pause` with a blocker
+description) pauses by hand; `/goal resume` re-arms through another
+confirmation dialog.
+
+**Completion is fail-closed.** `goal_complete` re-executes every check itself
+at the gate — results recorded in the Check Log never substitute for the
+re-run — and requires one attestation per success criterion. Only then does
+the user dialog appear. Revising the contract (`goal_write` with
+`revise=true`) bumps the revision: earlier evidence no longer counts, but the
+Check Log and Turn Ledger survive as an audit trail.
+
+**Queueing.** One live goal per session; `/goal add ...` queues additional
+goals (inert, no dialog). When the live goal reaches a terminal state,
+`/goal resume` promotes the oldest queued goal into the now-free session.
+
+**Run-mode limitation.** `opencode run` exits before the idle continuation
+debounce fires, so the autonomous loop effectively requires a TUI/serve
+session. Arming, checks, completion, pause/resume, and queueing all work in
+run mode; `--auto` approves the gates, without it they auto-reject
+(headless cannot silently pass a gate).
+
+**Security boundary.** Verification shell commands run on your host, in the
+workspace, via the plugin — that is the point (host-verified completion).
+They are drafted by the model from your objective. Read them in the dialog
+before allowing the arm; `--contains` contracts are strictly
+workspace-relative (path escape is refused).
 
 ## Design stance (read before filing "bash is blocked" issues)
 
@@ -117,9 +208,11 @@ bun run bundle        # rebuild self-contained dist/index.js (committed)
 ```
 
 Architecture: `plugin.ts` (dual entry — v1 `server` full-featured + v2
-`setup` defensive forward-compat) + `src/plan-file.ts` (pure plan document
-core, unit-tested, no opencode imports) + `SKILL.md` (planning discipline,
-discovered via `config.skills.paths`). Behavioral changes go through the
+`setup` defensive forward-compat) + `src/plan-file.ts` / `src/goal-file.ts`
+(pure document cores, unit-tested, no opencode imports) + `src/run-check.ts`
+(shell/file-contract runner with tree-kill timeouts and a workspace path
+guard) + `SKILL.md` (planning discipline, discovered via
+`config.skills.paths`). Behavioral changes go through the
 OpenSpec workflow in `openspec/` — see AGENTS.md. Common pitfalls live in
 `../opencode-plugin-dev-pitfalls.md`.