goalbuddy 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.3.8 — Board Hub Guardrails (2026-05-29)
+
+- **Clarified multi-board hub recovery.** Unregistered board URLs now explain that a `/slug/` 404 does not mean the `41737` process is stale; agents should verify `/api/boards` and register the new goal on the same hub before stopping any process. Release checks now include the local board surface tests.
+- **Prefer the largest safe useful slice.** GoalBuddy now teaches Judge to pick whole useful slices, Worker to complete the assigned slice, and PM to reorient boards when tasks are safe-looking but outcome-light. `goalbuddy prompt` and the state checker emit non-fatal micro-slicing warnings without breaking old boards.
+- **Hardened Codex plugin-only installs.** Codex install/update now use the native plugin path, refresh the bundled Scout/Judge/Worker agents, and leave stale personal `~/.codex/skills/goalbuddy` / `goal-maker` folders out of the expected clean state.
+- **Fixed Codex doctor for plugin-only installs.** `goalbuddy doctor --target codex --goal-ready` now validates the plugin cache, bundled `$goal-prep` skill, enabled plugin config, and GoalBuddy agents instead of failing only because standalone personal skill folders are absent. The report also distinguishes native OpenAI-gated Codex `/goal` from GoalBuddy `$goal-prep` and local boards.
+- **Made mutating command help safe.** `goalbuddy plugin install --help` and `goalbuddy update --help` print help without installing, updating, or touching global Codex/Claude files.
+
+## 0.3.5 — Subgoals, Parallel Agents, and Dark Mode (2026-05-12)
+
+- **Subgoals for bounded branching work.** Parent tasks can link to depth-1 child `state.yaml` boards under `subgoals/`, the checker validates child shape and containment, and the local board renders the child board inside the parent task detail.
+- **Parallel-agent-ready boards.** `goalbuddy parallel-plan` reports safe read-only Scout/Judge handoffs and Worker handoffs only when write scopes are known and disjoint. It does not mutate state or spawn agents.
+- **Dark mode and a sharper live board.** The local board now has readable dark mode, global viewer settings, compact mode, completed-task collapse, a site-aligned header, GitHub stars, and active-card motion with reduced-motion handling.
+- **Multi-board local hub navigation.** Multiple local boards share one readable `goalbuddy.localhost` hub with an in-header board selector, and parent boards stream updates when linked child subgoal state changes.
+- **More durable execution plumbing.** Scout/Judge/Worker contracts are stricter, `goalbuddy prompt` emits compact task prompts, Worker write-scope checks fail closed for ambiguous overlap, and source/plugin tests cover the new branching and parallel-safety surfaces.
+
+## 0.3.2 — Harden Codex plugin cache updates (2026-05-11)
+
+- **Fixed Codex plugin updates when stale preserved-extension folders exist.** The updater now ignores non-version cache directories like `.goalbuddy-preserved-extend-*` while selecting the active plugin skill, so a leftover temporary folder cannot make `npx goalbuddy update` fail with `Unsupported version`.
+- **Stopped leaving empty preserved-extension folders during plugin reinstalls.** The updater only creates the temporary preservation directory when there is a custom extension to copy.
+
+## 0.3.1 — Fix duplicate /goal-prep slash entry (2026-05-11)
+
+- **Fixed duplicate `/goal-prep` in the Claude Code slash menu.** Previous installs shipped both a `name: goal-prep` skill and a `commands/goal-prep.md` slash command, so Claude Code listed `/goal-prep` twice with different descriptions. The skill is now the single canonical surface for `/goal-prep`. Existing installs with `~/.claude/commands/goal-prep.md` are migrated automatically: `npx goalbuddy` (and `install` / `update`) removes the legacy file. `goalbuddy doctor --target claude` reports `legacy_command_present` and fails until the legacy file is gone.
+
+## 0.3.0 — Claude Code and Codex targets
+
+GoalBuddy now installs into both **Codex** and **Claude Code** with a single `npx goalbuddy` run. The shared skill payload and `/goal` workflow are unchanged — this release adds a Claude Code target alongside the existing Codex one and reframes the project as "a /goal operating system for Codex and Claude Code."
+
+### Highlights
+
+- **One command installs both targets.** `npx goalbuddy` installs and enables the native Codex plugin in `~/.codex/`, then installs the GoalBuddy skill, three Scout/Judge/Worker subagents, and the `/goal-prep` slash command into `~/.claude/`.
+- **Target-specific installs remain available.** Use `npx goalbuddy --target codex` or `npx goalbuddy --target claude` when you only want one side.
+- **Claude Code plugin scaffold** at `plugins/goalbuddy/.claude-plugin/plugin.json` with markdown subagents (`agents/goal-scout.md`, `agents/goal-judge.md`, `agents/goal-worker.md`) and a `/goal-prep` command (`commands/goal-prep.md`).
+- **`$goal-prep` (Codex) and `/goal-prep` (Claude Code)** are documented as sibling entry points throughout the skill, README, site, and CLI.
+- **Reframed README, site, plugin docs, package.json, and SKILL.md** to position the workflow as "a /goal operating system for Codex and Claude Code."
+- **CLI is target-aware.** New flags: `--target codex|claude`, `--claude-home <path>`. Existing `--codex-home` and `CODEX_HOME` continue to work unchanged.
+- **Update supports both targets.** `goalbuddy update` refreshes the Codex plugin and Claude Code skill/agents/command together unless `--target` narrows it.
+- **Doctor checks both targets.** Default is Codex; `goalbuddy doctor --target claude` runs the Claude Code skill/agent/command check.
+
+### Compatibility
+
+- `npx goalbuddy` with no flag now prepares Codex and Claude Code together. Existing Codex-only automation can keep using `--target codex` or `--codex-home`.
+- `npx goal-maker` continues to work as a temporary alias and prints the new command.
+- The shared `goalbuddy/SKILL.md` payload is unchanged in shape; the framing is now bilingual.
+
+### Tests
+
+- All 46 tests pass.
+- Help-text and version-arithmetic tests updated for the bilingual usage and the 0.3.0 bump.
+
+### Adding Or Updating Both
+
+Install or refresh both supported agent environments:
+
+```bash
+npx goalbuddy
+npx goalbuddy update
+```

package/CONTRIBUTING.md

@@ -39,11 +39,11 @@ Before opening a PR, verify the npm package contents:
 npm pack --dry-run
 ```
 
-The package should include `README.md`, `internal/assets/`, `package.json`, `internal/cli/`, the canonical `goalbuddy/` skill directory, and `plugins/goalbuddy/` (with both `.codex-plugin/` and `.claude-plugin/` manifests). The temporary `$goal-maker` compatibility skill is generated by the installer; do not add a second tracked skill payload.
+The package should include `README.md`, `CHANGELOG.md`, `docs/releases/`, `internal/assets/`, `package.json`, `internal/cli/`, the canonical `goalbuddy/` skill directory, and `plugins/goalbuddy/` (with both `.codex-plugin/` and `.claude-plugin/` manifests). The temporary `$goal-maker` compatibility skill is generated by the installer; do not add a second tracked skill payload.
 
 ## Releases
 
-GoalBuddy publishes from GitHub Actions with npm trusted publishing. See [RELEASE.md](RELEASE.md) before creating a release.
+GoalBuddy publishes from GitHub Actions with npm trusted publishing. See [docs/releases](docs/releases/README.md) before creating a release.
 
 ## Contribution Guidelines
 

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <a href="https://goalbuddy.dev">
-    <img src="internal/assets/goalbuddy-v0.3.5-release.png" alt="GoalBuddy v0.3.5 release: Subgoals, parallel agents, and dark mode." width="100%">
+    <img src="internal/assets/goalbuddy-readme-hero.png" alt="GoalBuddy local board and agent workflow." width="100%">
   </a>
 </p>
 
@@ -16,9 +16,9 @@
   <a href="https://goalbuddy.dev"><img alt="goalbuddy.dev" src="https://img.shields.io/badge/site-goalbuddy.dev-684cff?style=flat-square"></a>
 </p>
 
-GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks, especially when the work branches into subgoals, parallel agents, and long-running verification.
+GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks by giving native `/goal` a finish line, a live work surface, and a proof loop.
 
-It gives `/goal` a small local workspace: a charter, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
+It gives `/goal` a small local workspace: a charter, a goal oracle, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
 
 ## Start Here
 
@@ -63,6 +63,14 @@ To verify a Codex install:
 npx goalbuddy doctor --target codex --goal-ready
 ```
 
+To remove GoalBuddy-owned Codex runtime surfaces:
+
+```bash
+npx goalbuddy reset --target codex
+```
+
+Native `codex plugin remove goalbuddy@goalbuddy` only removes the native plugin surface. GoalBuddy also owns the `goal_*.toml` agent files it installed, its Codex plugin cache, its marketplace entry, and old personal skill folders from earlier installs. Use `goalbuddy reset --target codex` when you want those GoalBuddy-owned files removed too.
+
 ## What It Creates
 
 ```text
@@ -70,6 +78,7 @@ docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  .goalbuddy-board/ # generated local board files
   subgoals/        # optional depth-1 child boards
 ```
 
@@ -84,16 +93,22 @@ docs/goals/<your-goal>/
 ## How It Thinks
 
 ```text
-rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
+Intent -> Oracle -> Surface -> Loop -> Proof
 ```
 
+The oracle is the observable signal that says whether the original owner outcome is actually true: a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision.
+
+No oracle, no serious goal.
+
+The local board is the default work surface. It is not an extension marketplace; it is the built-in view of the `state.yaml` truth.
+
 Scout maps the repo.
 
 Judge chooses the largest safe useful slice.
 
 Worker completes the whole assigned slice and leaves a receipt.
 
-`/goal` keeps the loop honest until the original goal is actually done.
+`/goal` keeps the loop honest until a final Judge/PM audit maps receipts and verification back to the oracle and records the full outcome complete.
 
 ## Slice Sizing
 
@@ -101,7 +116,7 @@ Safe does not mean small. Safe means bounded, explicit, verified, and reversible
 
 GoalBuddy should not optimize for tiny safe tasks. It should optimize for the largest safe useful slice: a working screen, working API path, data pipeline step, backend vertical slice, real bug fix, or milestone review. The board warns when it sees safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome.
 
-## Subgoals, Parallel Agents, and Dark Mode
+## Goalmaxxed
 
 GoalBuddy keeps the model small:
 
@@ -115,7 +130,7 @@ Use subgoals for bounded child work that belongs to a parent task. Use multiple
 
 ## Execution Quality
 
-GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
+GoalBuddy can prepare safe parallel work; it does not run a parallel org chart or install arbitrary extension packs.
 
 Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task without dumping the whole state file. The prompt includes a mandatory `required_spawn_agent_type`; Codex PMs should use that exact GoalBuddy agent (`goal_scout`, `goal_worker`, or `goal_judge`) instead of a generic role agent. Use `goalbuddy parallel-plan docs/goals/<slug>` to inspect read-only or disjoint write-scope work that can be handed to native Codex or Claude Code agent flows. The command reports recommendations only; it does not mutate state or spawn agents.
 
@@ -131,11 +146,13 @@ That updates both Codex and Claude Code.
 
 ## Live Boards
 
-GoalBuddy can open a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
+GoalBuddy opens a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
 
 Multiple local boards reuse one readable `goalbuddy.localhost` hub with an in-header board switcher. When sharing a board in chat or docs, use a real Markdown link such as `[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)` so the URL is clickable. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.
 
-See [GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode](RELEASE-0.3.5.md) for the release notes.
+Custom external integrations should be built as ordinary repo work with a concrete implementation plan, not installed from a GoalBuddy catalog.
+
+See [GoalBuddy 0.3.8: Board Hub Guardrails](docs/releases/0.3.8.md) for the latest release notes.
 
 <p align="center">
   <img src="internal/assets/goalbuddy-live-board.jpg" alt="GoalBuddy local live board open next to Codex while Scout, Judge, and Worker tasks populate." width="100%">
@@ -155,7 +172,7 @@ GoalBuddy is MIT licensed and published on npm.
 
 The implementation lives in this repo, but the happy path is intentionally tiny: install it, run Goal Prep, then let `/goal` work from the generated files.
 
-For release process details, see [RELEASE.md](RELEASE.md).
+For release process details, see [docs/releases](docs/releases/README.md).
 
 ## Star History
 

package/{RELEASE-0.3.5.md → docs/releases/0.3.5.md}

@@ -256,8 +256,8 @@ The board renderer also fails closed on invalid child paths, so a malformed subg
 Run the bundled parent/child board:
 
 ```bash
-node goalbuddy/extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal goalbuddy/extend/local-goal-board/examples/subgoal-parent
+node goalbuddy/surfaces/local-goal-board/scripts/local-goal-board.mjs \
+  --goal goalbuddy/surfaces/local-goal-board/examples/subgoal-parent
 ```
 
 Then try:
@@ -265,8 +265,8 @@ Then try:
 - switch to dark mode from the gear menu
 - open task `T004` to see the embedded child board
 - launch another board and use the header selector
-- run `goalbuddy parallel-plan goalbuddy/extend/local-goal-board/examples/subgoal-parent`
-- run `goalbuddy prompt goalbuddy/extend/local-goal-board/examples/subgoal-parent`
+- run `goalbuddy parallel-plan goalbuddy/surfaces/local-goal-board/examples/subgoal-parent`
+- run `goalbuddy prompt goalbuddy/surfaces/local-goal-board/examples/subgoal-parent`
 
 ## Tests
 

package/docs/releases/0.3.7.md

@@ -0,0 +1,129 @@
+# GoalBuddy 0.3.7: Goalmaxxed
+
+![GoalBuddy v0.3.7 release: Goalmaxxed.](https://raw.githubusercontent.com/tolibear/goalbuddy/v0.3.7/internal/assets/goalbuddy-v0.3.7-release.png)
+
+Release date: 2026-05-19
+
+Goalmaxxed is the release where GoalBuddy stops trying to become a workflow catalog and commits to one sharper job:
+
+```text
+Give /goal enough pressure that it keeps working until the original outcome is actually true.
+```
+
+This release is heavily inspired by the Codex maxxing playbook: keep the goal visible, preserve context in local files, use subagents deliberately, demand evidence, and resist the temptation to declare victory because a plausible slice finished.
+
+Update with:
+
+```bash
+npx goalbuddy update
+```
+
+## The Headline
+
+GoalBuddy now centers the native `/goal` loop around five small ideas:
+
+- **Intent**: capture what the owner actually wants.
+- **Oracle**: define the observable signal that proves the outcome is real.
+- **Surface**: keep one local board visible while the run moves.
+- **Loop**: Scout maps facts, Judge chooses the largest safe useful slice, Worker completes the whole slice.
+- **Proof**: final completion requires receipts mapped back to the oracle.
+
+That is the product. Everything else got judged against that loop.
+
+## Goal Pressure
+
+GoalBuddy now treats the goal oracle as first-class state. A serious goal needs an observable signal before the board can pretend it knows what done means:
+
+- a passing test suite
+- a browser walkthrough
+- a demo transcript
+- a generated artifact
+- a benchmark
+- a source-backed answer
+- a release check
+- a final human decision
+
+No oracle, no serious goal.
+
+The checker also rejects weak final completion. A goal should not be marked done just because the active task ended. Done means a final Judge or PM audit records that the receipts and verification satisfy the oracle.
+
+## Larger Useful Slices
+
+This release sharpens the slice policy:
+
+```text
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+```
+
+GoalBuddy now pushes Judge and Worker toward the largest safe useful slice: a working screen, working API path, backend vertical slice, real bug fix, data pipeline step, or milestone review.
+
+The board warns when it sees micro-slicing: helper files, contracts, proof notes, or tiny prep tasks that are safe but do not move the owner outcome.
+
+## Built-In Local Board
+
+The local board is now a core surface, not an extension.
+
+The bundled surface lives at:
+
+```text
+goalbuddy/surfaces/local-goal-board/
+```
+
+It remains the default way to watch a GoalBuddy run: active task, blocked state, receipts, verification status, subgoals, and board switching all point back to the same `state.yaml` truth.
+
+## No Extension Catalog
+
+GoalBuddy no longer ships a public extension catalog.
+
+The old catalog made the product look bigger while making the core loop blurrier. Goalmaxxed chooses the smaller invariant:
+
+```text
+GoalBuddy prepares and pressures /goal runs. Custom integrations are ordinary repo work.
+```
+
+If a team wants a GitHub, Linear, Slack, or release integration, they should prepare a concrete implementation plan in their repo and build it as normal software. GoalBuddy should not install arbitrary workflow packs as a side channel.
+
+## Simpler Public Surface
+
+The public copy now says what GoalBuddy actually does:
+
+- prepares `/goal`
+- writes `goal.md` and `state.yaml`
+- creates a goal oracle
+- opens a local board
+- keeps Scout/Judge/Worker handoffs receipt-shaped
+- prevents early completion
+- leaves custom integrations outside the core
+
+The Codex and Claude Code plugin manifests are aligned with the package description, and the test suite now checks that the Claude manifest stays in sync.
+
+## Release Boundaries
+
+This release intentionally does not add:
+
+- an extension marketplace
+- automatic parallel-agent spawning
+- hosted board state
+- automatic receipt application
+- UI controls that mutate board state
+- a replacement for native `/goal`
+
+GoalBuddy stays local, file-backed, and boring in the parts that should be boring.
+
+## Package Notes
+
+This release updates:
+
+- npm package version: `0.3.7`
+- Codex plugin version: `0.3.7`
+- Claude Code plugin version: `0.3.7`
+- package contents to include `goalbuddy/surfaces/`
+- mirrored GoalBuddy skill files under `plugins/goalbuddy/skills/goalbuddy/`
+
+Before publishing, verify:
+
+```bash
+npm run check
+npm run pack:dry-run
+node internal/cli/check-publish-version.mjs
+```

package/docs/releases/0.3.8.md

@@ -0,0 +1,40 @@
+# GoalBuddy 0.3.8: Board Hub Guardrails
+
+Release date: 2026-05-29
+
+This patch release fixes a confusing local-board failure mode.
+
+GoalBuddy already supports multiple local boards on one shared hub:
+
+```text
+http://goalbuddy.localhost:41737/<slug>/
+```
+
+The problem was the unregistered-path error. If an agent opened a new board URL before registering that goal with the hub, the server returned a bare 404. That made it too easy to infer that the process on `41737` was stale, even when it was a healthy multi-board hub for another goal.
+
+## What Changed
+
+- Unregistered board paths now return an explicit diagnostic explaining that a `/slug/` 404 does not mean the hub is stale.
+- The diagnostic points agents to `http://127.0.0.1:41737/api/boards` and tells them to rerun `npx goalbuddy board <goal-dir>` to register the goal on the same port.
+- `$goal-prep` / `/goal-prep` now says to stop a process on `41737` only when `/api/boards` proves the listener is not a current GoalBuddy multi-board hub.
+- `npm run check` now includes the local board surface tests and syntax checks.
+
+## Release Boundaries
+
+This release does not change the board state model. `state.yaml` remains the source of truth, the local board remains a viewer over repo files, and multiple boards still share the same local hub.
+
+## Package Notes
+
+This release updates:
+
+- npm package version: `0.3.8`
+- Codex plugin version: `0.3.8`
+- Claude Code plugin version: `0.3.8`
+- release checks to cover `goalbuddy/surfaces/local-goal-board/`
+
+Before publishing, verify:
+
+```bash
+npm run check
+npm run publish:check
+```

package/docs/releases/README.md

@@ -0,0 +1,83 @@
+# Release Process
+
+Historical release notes live next to this process doc:
+
+- [0.3.8: Board Hub Guardrails](0.3.8.md)
+- [0.3.7: Goalmaxxed](0.3.7.md)
+- [0.3.5: Subgoals, Parallel Agents, and Dark Mode](0.3.5.md)
+
+GoalBuddy publishes the `goalbuddy` npm package from GitHub Actions using npm trusted publishing. This avoids long-lived npm write tokens and lets npm generate provenance for future releases.
+
+## One-Time npm Setup
+
+Configure this on npmjs.com for the `goalbuddy` package:
+
+- Publisher: GitHub Actions
+- GitHub owner/user: `tolibear`
+- Repository: `goalbuddy`
+- Workflow filename: `npm-publish.yml`
+- Package: `goalbuddy`
+
+The workflow path in this repo is:
+
+```text
+.github/workflows/npm-publish.yml
+```
+
+Or configure the same trust relationship from the npm CLI:
+
+```bash
+npx --yes npm@11.13.0 trust github goalbuddy \
+  --repo tolibear/goalbuddy \
+  --file npm-publish.yml \
+  --yes
+```
+
+This command requires npm owner authentication and may print an `EOTP` browser/OTP URL. Complete that npm authentication step, then rerun the same command if needed. The `npx --yes npm@11.13.0 trust ...` form is intentional; using `npx -p npm@latest npm trust ...` can resolve to an older global npm binary that does not expose the `trust` command.
+
+After the trusted publisher works, use npm package settings to require 2FA and disallow tokens for publishing. Keep `goal-maker` published during the migration window.
+
+Starting in `0.3.0`, the installer is target-aware: `npx goalbuddy` installs into both `~/.codex/` and `~/.claude/`, and `goalbuddy update` refreshes both by default. Use `--target codex` or `--target claude` to narrow a command. Both targets share the same `goalbuddy/` skill payload and are exercised by the test suite under `internal/test/`.
+
+## Release Flow
+
+1. Update `package.json` version.
+2. Run local checks:
+
+```bash
+npm run check
+npm run pack:dry-run
+node internal/cli/check-publish-version.mjs
+```
+
+3. Commit and push the version change.
+4. Create and publish a GitHub release whose tag matches the package version, for example `v0.2.11`.
+5. Confirm the GitHub Actions workflow `Publish npm package` completed.
+6. Verify npm:
+
+```bash
+npm view goalbuddy name version dist-tags repository bin --json
+npx goalbuddy --help
+npx goalbuddy doctor --target codex
+npx goalbuddy doctor --target claude
+```
+
+## Provenance Expectations
+
+npm trusted publishing requires a GitHub-hosted runner, Node `22.14.0` or newer, npm `11.5.1` or newer, and `id-token: write` workflow permission. The release workflow uses Node 24 and grants the OIDC permission required by npm.
+
+When publishing through trusted publishing from this public repo to the public `goalbuddy` package, npm should generate provenance automatically. The workflow intentionally runs `npm publish` without `NODE_AUTH_TOKEN`; npm exchanges the GitHub OIDC identity for a short-lived publish credential.
+
+## Compatibility Package
+
+Do not unpublish `goal-maker`. During the 60-90 day compatibility window, `npx goal-maker` should continue to work and point users to:
+
+```bash
+npx goalbuddy
+```
+
+After the compatibility window:
+
+```bash
+npm deprecate goal-maker "Renamed to goalbuddy. Use: npx goalbuddy"
+```

package/goalbuddy/SKILL.md

@@ -12,9 +12,17 @@ GoalBuddy is for autonomous, long-running Codex or Claude Code work where the PM
 The loop is:
 
 ```text
-raw user intent -> intake compiler -> discovery/plan validation/execution board -> one active task -> receipt -> board update -> repeat
+raw user intent -> intake compiler -> goal oracle -> local work surface -> one active task -> receipt -> proof loop -> repeat
 ```
 
+GoalBuddy's core invariant is:
+
+```text
+Intent -> Oracle -> Surface -> Loop -> Proof
+```
+
+No oracle, no serious goal. A goal oracle is the observable signal that tells the PM whether the original owner outcome is actually true yet. It may be a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision. Weak proof creates weak goals, so record the oracle before shaping tasks and keep testing against it until final completion.
+
 ## Invocation Boundary
 
 There are two different modes:
@@ -31,7 +39,7 @@ Allowed `$goal-prep` actions:
 - run the bundled GoalBuddy update checker and mention a newer version if one is available;
 - ask diagnostic intake questions and wait when required;
 - create or repair only `docs/goals/<slug>/goal.md`, `docs/goals/<slug>/state.yaml`, `docs/goals/<slug>/notes/`, and the generated `.goalbuddy-board/` visual board artifact;
-- create and open the selected visual board surface for the goal;
+- create and open the built-in local GoalBuddy board surface for the goal unless the user opts out;
 - optionally run the GoalBuddy board checker against that `state.yaml`;
 - verify GoalBuddy agent availability, if this can be done without touching implementation work, and record `installed`, `bundled_not_installed`, `missing`, or `unknown` truthfully;
 - print exactly `/goal Follow docs/goals/<slug>/goal.md.`;
@@ -69,25 +77,27 @@ Extract:
 - authority: `requested | approved | inferred | needs_approval | blocked`;
 - proof type: `test | demo | artifact | metric | review | source_backed_answer | decision`;
 - completion proof: the observable signal for full outcome completion;
+- goal oracle: the live check, walkthrough, artifact, metric, or decision that will keep pressure on the goal and prevent early completion;
 - likely misfire: how `/goal` could succeed at the wrong thing;
 - blind spots: important risks, choices, or success dimensions the user may not have named yet;
 - existing plan facts: user-provided steps, files, constraints, or sequencing that must be preserved but still validated.
 
-Ask the visual-board question early, before detailed task shaping:
+Use the local GoalBuddy board as the default work surface for broad GoalBuddy runs. Ask only when the user has not already implied they want the default local surface, the goal is unusually quick/private, or board setup would materially distract from the requested prep:
 
 ```text
-Do you want to set up a visual board for this?
+Do you want the local GoalBuddy board for this goal?
 ```
 
 Recommended options:
 
 1. Local live board (Recommended) - starts immediately, requires no credentials, and lets the user watch tasks populate inside Codex or Claude Code.
-2. GitHub Projects - best when stakeholders need a shared external board and the user can approve GitHub credentials/project details.
-3. No visual board - best for quick or private goals where the file board is enough.
+2. No visual board - best for quick or private goals where the file board is enough.
 
 If the user chooses the local live board, create the goal directory, `notes/`, and an initial minimal `state.yaml` as soon as the slug is known, then run `npx goalbuddy board docs/goals/<slug>` and open the printed local URL in the AI coding agent's in-app browser (the Codex in-app Browser, the Claude Code preview, or the user's regular browser). The default local hub is `http://goalbuddy.localhost:41737/`, and board URLs normally look like `http://goalbuddy.localhost:41737/<slug>/`. In short: start the local board before filling the task list so the board pops up right away and cards populate live as `state.yaml` changes. Include the printed board URL in the final prep response as an actual clickable Markdown link, for example `[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)`. Do not put the board URL only in a code block, quote, HTML comment, or prose that the UI cannot click.
 
-If the user chooses GitHub Projects, ask for approval and the required project target before any live write. Create or sync the GitHub Project at the same early point as the local board: after the goal root and skeleton `state.yaml` exist, before the detailed task list is finished, then sync again as tasks populate. Run a dry-run sync first when possible. Missing GitHub credentials or project details should not block local board creation or goal prep; record the missing requirement in `visual_board.github_projects` and seed a PM setup task.
+If `http://goalbuddy.localhost:41737/<slug>/` returns 404, do not assume the existing process is stale and do not stop it. First check `http://127.0.0.1:41737/api/boards`. If that endpoint returns board JSON, the port is the shared multi-board hub; rerun `npx goalbuddy board docs/goals/<slug>` with the absolute goal path if needed so the new goal registers on the same port. Only stop a specific process on 41737 when `/api/boards` is missing, returns 404, or otherwise proves the listener is not a current GoalBuddy multi-board hub.
+
+If the user wants an external board, GitHub sync, Slack digest, Linear handoff, or any other custom integration, do not install a GoalBuddy catalog item. Treat it as normal implementation work: create a concrete task that designs and verifies that integration inside the target repo or asks the operator for the required credentials and scope.
 
 Ask before board creation when the request is vague, strategic, improvement-oriented, or open-ended and the user has not explicitly said to use defaults. Ask one guided question at a time with 2-3 options and a recommended default, then wait. Continue the diagnostic intake until the user's answers are sufficient to choose the board shape. Do not create or repair `docs/goals/<slug>/` until the diagnostic intake is complete or the user explicitly accepts defaults.
 
@@ -134,7 +144,7 @@ Stop after each question. Do not create files, repair an existing board, run che
 
 Minimum diagnostic ladder for vague, strategic, or improvement-oriented goals:
 
-1. Visual board: ask "Do you want to set up a visual board for this?"
+1. Goal surface: use the local live board by default, or ask "Do you want the local GoalBuddy board for this goal?" when board handling is unresolved.
 2. Intent target: what kind of improvement or outcome matters most?
 3. Success proof: what evidence would convince the user this worked?
 4. Scope and non-goals: what should remain untouched or explicitly out of scope?
@@ -173,7 +183,7 @@ Do:
 - classify the goal as `specific`, `open_ended`, `existing_plan`, `recovery`, or `audit`;
 - create or repair `docs/goals/<slug>/`;
 - create `goal.md`, `state.yaml`, and `notes/`;
-- if requested, start the local visual board immediately and open it in the AI coding agent's in-app browser (Codex in-app Browser, Claude Code preview, or the user's regular browser) before filling the task list;
+- start the local board immediately and open it in the AI coding agent's in-app browser (Codex in-app Browser, Claude Code preview, or the user's regular browser) before filling the task list, unless the user opts out;
 - seed a role-tagged task board that matches the input shape;
 - make the first active task safe;
 - verify Scout, Worker, and Judge agent availability or record an explicit truthful state;
@@ -234,7 +244,7 @@ Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, alrea
 
 For a one-change task, do not create a GoalBuddy board.
 
-Scout and Judge tasks may identify optional extension, plugin, publishing, reporting, or channel opportunities as improvement candidates. Treat those as normal board tasks. Extensions are supporting surfaces; `state.yaml` remains board truth.
+Scout and Judge tasks may identify optional publishing, reporting, integration, plugin, or channel opportunities as improvement candidates. Treat those as normal board tasks with concrete implementation plans. `state.yaml` remains board truth.
 
 ## The Four Primitives
 
@@ -274,6 +284,7 @@ The charter answers:
 What did the user originally ask for?
 What are we trying to improve?
 What input shape did the intake identify?
+What is the goal oracle?
 What constraints are non-negotiable?
 Is this goal specific, open-ended, existing-plan, recovery, or audit?
 What likely misfire must the PM avoid?

package/goalbuddy/scripts/check-goal-state.mjs

@@ -53,6 +53,38 @@ function nestedScalar(section, key) {
   return null;
 }
 
+function pathScalar(path, key) {
+  const lines = text.split(/\r?\n/);
+  let depth = 0;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent < depth * 2) depth = Math.floor(indent / 2);
+
+    if (depth < path.length && indent === depth * 2 && new RegExp(`^\\s{${indent}}${path[depth]}:\\s*$`).test(line)) {
+      depth += 1;
+      continue;
+    }
+
+    if (depth === path.length && indent === depth * 2) {
+      const match = line.match(new RegExp(`^\\s{${indent}}${key}:\\s*(.*?)\\s*$`));
+      if (match) return clean(match[1]);
+    }
+  }
+  return null;
+}
+
+function isWeakProof(value) {
+  if (value === null || value === undefined) return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === ""
+    || normalized === "unknown"
+    || normalized === "tbd"
+    || normalized === "todo"
+    || normalized === "none"
+    || /^<.*>$/.test(normalized);
+}
+
 function sectionText(section) {
   const lines = text.split(/\r?\n/);
   const start = lines.findIndex((line) => new RegExp(`^${section}:\\s*$`).test(line));
@@ -225,6 +257,11 @@ const allowedAgentStatuses = new Set(["installed", "bundled_not_installed", "mis
 const continuousUntilFullOutcome = nestedScalar("rules", "continuous_until_full_outcome") === true;
 const missingInputOrCredentialsDoNotStopGoal =
   nestedScalar("rules", "missing_input_or_credentials_do_not_stop_goal") === true;
+const goalPressureRequiresOracle = nestedScalar("rules", "goal_pressure_requires_oracle") !== false;
+const noCompletionOnWeakProof = nestedScalar("rules", "no_completion_on_weak_proof") !== false;
+const completionProof = pathScalar(["goal", "intake"], "completion_proof");
+const oracleSignal = pathScalar(["goal", "oracle"], "signal");
+const oracleFinalProof = pathScalar(["goal", "oracle"], "final_proof");
 const legacySignals = [
   /^gate:\s*$/m,
   /^artifact_policy:\s*$/m,
@@ -244,6 +281,19 @@ if (!["active", "blocked", "done"].includes(goalStatus)) {
   errors.push(`goal.status must be active, blocked, or done; got ${goalStatus || "<missing>"}`);
 }
 
+if (goalPressureRequiresOracle) {
+  if (isWeakProof(oracleSignal)) {
+    warnings.push("goal.oracle.signal is missing or placeholder-like; weak oracles make /goal finish too early.");
+  }
+  if (isWeakProof(oracleFinalProof)) {
+    warnings.push("goal.oracle.final_proof is missing or placeholder-like; final completion needs receipt-backed proof.");
+  }
+}
+
+if (isWeakProof(completionProof)) {
+  warnings.push("goal.intake.completion_proof is missing or placeholder-like; record the observable signal that proves the full original outcome.");
+}
+
 function agentStatusWarning(agent, status) {
   const agentLabel = agent[0].toUpperCase() + agent.slice(1);
   if (status === "bundled_not_installed") {
@@ -532,6 +582,9 @@ function escapeRegExp(value) {
 }
 
 if (goalStatus === "done") {
+  if (noCompletionOnWeakProof && (isWeakProof(completionProof) || isWeakProof(oracleSignal) || isWeakProof(oracleFinalProof))) {
+    errors.push("done goals require concrete completion proof, goal.oracle.signal, and goal.oracle.final_proof; weak proof cannot close a goal");
+  }
   const finalAudit = tasks.some((task) => {
     if (!["judge", "pm"].includes(task.type) || task.status !== "done") return false;
     if (!task.receipt.present || task.receipt.value === null) return false;