goalbuddy 0.3.7 → 0.3.9

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "goalbuddy",
+  "owner": {
+    "name": "tolibear",
+    "email": "support@tolibear.com"
+  },
+  "description": "GoalBuddy /goal-prep skill plus Scout/Judge/Worker subagents for pressured /goal runs.",
+  "plugins": [
+    {
+      "name": "goalbuddy",
+      "source": "./plugins/goalbuddy",
+      "description": "GoalBuddy: turn broad work into pressured /goal runs with oracles, local boards, receipts, and verification."
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## 0.3.9 — Marketplace and Board Runtime Polish (2026-06-23)
+
+- **Made Claude marketplace install discoverable.** The repo now ships a root `.claude-plugin/marketplace.json`, keeps it in the npm package allowlist, and validates marketplace install flow alongside the existing plugin manifest checks.
+- **Made `/goal-prep` install-channel agnostic.** Model-invoked board, prompt, and parallel-plan commands now use bundled skill scripts instead of assuming a global `goalbuddy` or `npx goalbuddy` binary. Update and agent guidance now points users back to their actual install channel.
+- **Stopped local-board flicker during task transitions.** The board watcher now coalesces rapid `state.yaml` writes before streaming updates, avoiding transient “more than one active task” errors during normal multi-step transitions.
+- **Let the board render valid parallel work.** The local board now renders multiple active tasks in the In Progress column instead of refusing to parse the whole board, while the stricter `check-goal-state` invariant remains available for board validation.
+- **Added exact-approval wait guidance.** GoalBuddy now has a terminal waiting shape for exact human approval gates: ask once, preserve the required reply, set `waiting_for_user_approval: true`, and stop until the user replies.
+- **Added PM-owned board health stewardship.** Goal Prep now explains the safe steward model: use the bundled checker and live board API to repair GoalBuddy control files only, without introducing an always-on implementation actor.
+
+## 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>
 
@@ -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
@@ -144,7 +152,7 @@ Multiple local boards reuse one readable `goalbuddy.localhost` hub with an in-he
 
 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.7: Goalmaxxed](RELEASE-0.3.7.md) for the latest release notes.
+See [GoalBuddy 0.3.9: Marketplace and Board Runtime Polish](docs/releases/0.3.9.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%">
@@ -164,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.7.md → docs/releases/0.3.7.md}

@@ -1,5 +1,7 @@
 # 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:

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/0.3.9.md

@@ -0,0 +1,46 @@
+# GoalBuddy 0.3.9: Marketplace and Board Runtime Polish
+
+GoalBuddy 0.3.9 prepares the package for cleaner Claude marketplace installs and tightens the runtime behavior around local boards, approval gates, and board-health stewardship.
+
+## Highlights
+
+- **Claude marketplace wrapper.** The repo now includes a root `.claude-plugin/marketplace.json` so Claude Code can discover the existing `plugins/goalbuddy` plugin through marketplace install flow.
+- **Install-channel agnostic Goal Prep.** `/goal-prep` no longer assumes a global `goalbuddy` or `npx goalbuddy` binary for model-invoked board, prompt, and parallel-plan commands. It uses bundled skill scripts from `<skill-path>` instead.
+- **Better update and agent advice.** `check-update` detects common install channels and falls back to “use the install channel that installed GoalBuddy” instead of guessing wrong. Agent availability warnings now use the same channel-neutral language.
+- **Less board flicker.** Local board file watching now waits for rapid `state.yaml` transition writes to settle before rebuilding the streamed payload.
+- **Parallel active tasks render.** The local board can display multiple active tasks in the In Progress column, which keeps parallel/disjoint work visible instead of failing the entire board render.
+- **Exact approval wait state.** When the only remaining action is an exact human approval phrase, GoalBuddy now has an explicit terminal wait shape: ask once, preserve `required_reply`, set `waiting_for_user_approval: true`, and stop until the user replies.
+- **Board health stewardship.** The PM-owned stewardship contract is now documented: run the bundled state checker, compare the live board API when available, and repair only GoalBuddy control files unless an active task explicitly allows product-file edits.
+
+## Why This Release Matters
+
+The Claude marketplace wrapper from 0.3.9 makes marketplace installs viable, but marketplace installs do not guarantee a shell-level `goalbuddy` binary. This release closes that gap by moving model-run commands onto the bundled scripts that ship inside the installed skill.
+
+The board changes also make GoalBuddy more honest during real runs: transient task switches do not flash false errors, and valid parallel work stays visible.
+
+## Verification
+
+- `npm run check`
+- `git diff --check`
+- `node --check plugins/goalbuddy/skills/goalbuddy/scripts/check-update.mjs plugins/goalbuddy/skills/goalbuddy/scripts/check-goal-state.mjs`
+- `GOALBUDDY_TEST_NPM_LATEST_VERSION=99.0.0 GOALBUDDY_TEST_UPDATE_COMMAND='/plugin update goalbuddy@goalbuddy' node plugins/goalbuddy/skills/goalbuddy/scripts/check-update.mjs --json`
+- `npm pack --dry-run --json`
+
+## Package Metadata
+
+- npm package version: `0.3.9`
+- Codex plugin version: `0.3.9`
+- Claude Code plugin version: `0.3.9`
+
+## Install
+
+```bash
+npx goalbuddy
+```
+
+For Claude Code marketplace installs:
+
+```text
+/plugin marketplace add tolibear/goalbuddy
+/plugin install goalbuddy@goalbuddy
+```

package/docs/releases/README.md

@@ -0,0 +1,84 @@
+# Release Process
+
+Historical release notes live next to this process doc:
+
+- [0.3.9: Marketplace and Board Runtime Polish](0.3.9.md)
+- [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

@@ -58,7 +58,7 @@ node <skill-path>/scripts/check-update.mjs --json
 If the checker reports `update_available: true`, tell the user once before continuing:
 
 ```text
-GoalBuddy <latest_version> is available. After this turn, update with: npx goalbuddy
+GoalBuddy <latest_version> is available. After this turn, update through the channel that installed GoalBuddy: `/plugin update goalbuddy@goalbuddy`, `npx goalbuddy@latest`, `npm i -g goalbuddy`, `pnpm update -g goalbuddy`, `bun update -g goalbuddy`, or `mise upgrade npm:goalbuddy`.
 ```
 
 Do not block intake or board creation on update checking. If the checker is missing, cannot find npm, or network access fails, continue silently unless the user asked about updates.
@@ -93,7 +93,9 @@ 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. 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 the local live board, create the goal directory, `notes/`, and an initial minimal `state.yaml` as soon as the slug is known, then run `node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal 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 `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 `node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal <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.
 
@@ -472,6 +474,22 @@ Blocked tasks do not necessarily block the goal. The PM should keep doing safe l
 
 Avoid setting `goal.status: blocked` for missing input, credentials, production access, destructive-operation permission, or policy decisions. Block the specific task instead, record the missing requirement, and continue with every safe local workaround or adjacent slice.
 
+Exception: if an exact human approval phrase is the only remaining blocker and no safe local work remains, ask once, preserve the exact phrase, and stop. Set `goal.status: blocked`, set `active_task: null`, mark every unfinished task `blocked`, and write a receipt with `result: blocked`, `waiting_for_user_approval: true`, and `required_reply: "<exact phrase>"`. Do not rephrase, retry, spawn follow-up work, or post another approval prompt until the user replies.
+
+## Board Health Stewardship
+
+The PM owns board health. Do not auto-spawn a separate always-on steward by default.
+
+When the board looks stale, misleading, offline, Not Found, or inconsistent, run the bundled checker:
+
+```bash
+node <skill-path>/scripts/check-goal-state.mjs docs/goals/<slug>
+```
+
+If a local board server is running, compare `state.yaml` with `http://127.0.0.1:41737/<slug>/api/board` or `http://127.0.0.1:41737/api/boards`. Repair only GoalBuddy control files: `goal.md`, `state.yaml`, `notes/`, depth-1 `subgoals/`, and `.goalbuddy-board/`. Never edit product implementation files during board-health work unless there is an active Worker or PM task with explicit `allowed_files`.
+
+Board-health work should verify these truths: `active_task` matches live task status, done and blocked tasks have receipts, human-blocked work is in the blocked column, future work stays queued, and the live board/API reflects `state.yaml`.
+
 ## Operator Escalation
 
 When Scout, Judge, Worker, or PM discovers a problem, improvement opportunity, product suggestion, follow-up repair, or tool limitation that should not be fixed inside the current active task, do not let it disappear in chat.
@@ -526,9 +544,9 @@ Use these `state.yaml` values:
 | State | Meaning | Next action |
 |---|---|---|
 | `installed` | Matching Scout/Worker/Judge agent configs were found in the expected user or project agent location. | Continue. |
-| `bundled_not_installed` | The bundled `goal_*.toml` template exists with the skill, but no matching installed agent config was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run `npx goalbuddy agents`. |
-| `missing` | Neither an installed config nor the bundled template was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run `npx goalbuddy install`. |
-| `unknown` | Agent availability could not be checked. | `/goal` can proceed through PM fallback. To check before `/goal`, run `npx goalbuddy doctor`. |
+| `bundled_not_installed` | The bundled `goal_*.toml` template exists with the skill, but no matching installed agent config was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run the GoalBuddy CLI through the user's install channel with `agents`. |
+| `missing` | Neither an installed config nor the bundled template was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run the GoalBuddy CLI through the user's install channel with `install`. |
+| `unknown` | Agent availability could not be checked. | `/goal` can proceed through PM fallback. To check before `/goal`, run the GoalBuddy CLI through the user's install channel with `doctor`. |
 
 Non-`installed` states are warnings, not false failures, because the main `/goal` PM can perform Scout/Judge/Worker-shaped tasks directly when dedicated agents are unavailable.
 
@@ -568,11 +586,11 @@ Treat `reasoning_hint` as PM guidance. It does not override task scope, write pe
 
 ## Execution Quality Commands
 
-Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task. The prompt includes only task-specific material, safe agent metadata, continuation warnings, and the expected receipt shape. It should not include broad chat history or dump the whole state file.
+Use `node <skill-path>/scripts/render-task-prompt.mjs docs/goals/<slug>` to render a compact prompt for the active task. The prompt includes only task-specific material, safe agent metadata, continuation warnings, and the expected receipt shape. It should not include broad chat history or dump the whole state file.
 
-When dispatching Codex subagents from a GoalBuddy prompt, the `required_spawn_agent_type` is mandatory. Use that exact `spawn_agent` `agent_type` (`goal_scout`, `goal_worker`, or `goal_judge`). Do not substitute generic `scout`, `worker`, or `judge` agents; if the required GoalBuddy agent is unavailable, stop spawning and continue as PM fallback or run `npx goalbuddy agents`/`npx goalbuddy install`. After one `wait_agent` timeout with no visible allowed-file changes, stop waiting, record the timeout, and recover deterministically instead of waiting forever.
+When dispatching Codex subagents from a GoalBuddy prompt, the `required_spawn_agent_type` is mandatory. Use that exact `spawn_agent` `agent_type` (`goal_scout`, `goal_worker`, or `goal_judge`). Do not substitute generic `scout`, `worker`, or `judge` agents; if the required GoalBuddy agent is unavailable, stop spawning and continue as PM fallback or ask the operator to run the GoalBuddy CLI through their install channel with `agents` or `install`. After one `wait_agent` timeout with no visible allowed-file changes, stop waiting, record the timeout, and recover deterministically instead of waiting forever.
 
-Use `goalbuddy parallel-plan docs/goals/<slug>` when the user explicitly asks for parallel agent work. It is read-only: it recommends safe Scout/Judge handoffs and Worker handoffs only when write scopes are known and disjoint. It does not mutate `state.yaml`, create sub-goals, apply receipts, or spawn agents.
+Use `node <skill-path>/scripts/parallel-plan.mjs docs/goals/<slug>` when the user explicitly asks for parallel agent work. It is read-only: it recommends safe Scout/Judge handoffs and Worker handoffs only when write scopes are known and disjoint. It does not mutate `state.yaml`, create sub-goals, apply receipts, or spawn agents.
 
 ## Completion
 

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

@@ -297,12 +297,12 @@ if (isWeakProof(completionProof)) {
 function agentStatusWarning(agent, status) {
   const agentLabel = agent[0].toUpperCase() + agent.slice(1);
   if (status === "bundled_not_installed") {
-    return `agents.${agent} is bundled_not_installed; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable until installed. If dedicated agents are required before /goal, run: npx goalbuddy agents`;
+    return `agents.${agent} is bundled_not_installed; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable until installed. If dedicated agents are required before /goal, run the GoalBuddy CLI through the user's install channel with: agents`;
   }
   if (status === "missing") {
-    return `agents.${agent} is missing; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable. If dedicated agents are required before /goal, run: npx goalbuddy install`;
+    return `agents.${agent} is missing; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable. If dedicated agents are required before /goal, run the GoalBuddy CLI through the user's install channel with: install`;
   }
-  return `agents.${agent} is unknown; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation was not verified. To check before /goal, run: npx goalbuddy doctor`;
+  return `agents.${agent} is unknown; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation was not verified. To check before /goal, run the GoalBuddy CLI through the user's install channel with: doctor`;
 }
 
 for (const { agent, status } of agentStatuses) {
@@ -353,6 +353,7 @@ for (const task of tasks) {
 if (tasks.length === 0) errors.push("tasks must contain at least one task");
 
 const activeTasks = tasks.filter((task) => task.status === "active");
+const terminalApprovalWait = isTerminalApprovalWait(tasks, activeTasks, activeTask);
 if (goalStatus === "done") {
   if (activeTasks.length !== 0) errors.push("done goals must not have an active task");
   if (activeTask !== null) errors.push("done goals must set active_task: null");
@@ -364,7 +365,7 @@ if (goalStatus === "done") {
   }
 } else if (goalStatus === "blocked") {
   if (activeTasks.length > 1) errors.push("blocked goals may have at most one active task");
-  if (continuousUntilFullOutcome && missingInputOrCredentialsDoNotStopGoal) {
+  if (continuousUntilFullOutcome && missingInputOrCredentialsDoNotStopGoal && !terminalApprovalWait) {
     errors.push("continuous goals must keep goal.status active; missing input or credentials should block specific tasks, not the whole goal");
   }
 } else if (activeTasks.length !== 1) {
@@ -436,6 +437,23 @@ for (const task of tasks) {
 
 warnings.push(...microSliceWarnings(tasks, activeTask, goalStatus));
 
+function isTerminalApprovalWait(tasks, activeTasks, activeTask) {
+  if (goalStatus !== "blocked") return false;
+  if (activeTask !== null) return false;
+  if (activeTasks.length !== 0) return false;
+
+  const unfinishedTasks = tasks.filter((task) => task.status !== "done");
+  if (unfinishedTasks.length === 0) return false;
+  if (unfinishedTasks.some((task) => task.status !== "blocked")) return false;
+
+  return unfinishedTasks.some((task) => {
+    if (!task.receipt.present || task.receipt.value === null) return false;
+    return task.receipt.scalar("result") === "blocked"
+      && task.receipt.scalar("waiting_for_user_approval") === true
+      && Boolean(task.receipt.scalar("required_reply"));
+  });
+}
+
 function validateSubgoal(task) {
   if (isChildCheck) {
     errors.push(`child task ${task.id} must not contain a nested subgoal`);

package/goalbuddy/scripts/check-update.mjs

@@ -14,7 +14,7 @@ const report = {
   latest_version: null,
   update_available: false,
   check_status: "unknown",
-  update_command: "npx goalbuddy",
+  update_command: detectUpdateCommand(),
 };
 
 try {
@@ -77,6 +77,23 @@ function latestPublishedVersion() {
   return normalizeVersion(result.stdout);
 }
 
+function detectUpdateCommand() {
+  if (process.env.GOALBUDDY_TEST_UPDATE_COMMAND) return process.env.GOALBUDDY_TEST_UPDATE_COMMAND;
+  if (process.env.CLAUDE_PLUGIN_ROOT || normalizedPath(scriptDir).includes("/.claude/")) return "/plugin update goalbuddy@goalbuddy";
+
+  const userAgent = process.env.npm_config_user_agent || "";
+  if (/^pnpm\//.test(userAgent)) return "pnpm update -g goalbuddy";
+  if (/^bun\//.test(userAgent)) return "bun update -g goalbuddy";
+  if (process.env.MISE_EXE || process.env.MISE_SHELL || process.env.MISE_PROJECT_ROOT) return "mise upgrade npm:goalbuddy";
+  if (/^npm\//.test(userAgent)) return "npx goalbuddy@latest";
+
+  return "use the install channel that installed GoalBuddy";
+}
+
+function normalizedPath(path) {
+  return String(path).replace(/\\/g, "/");
+}
+
 function readJson(path) {
   if (!existsSync(path)) return null;
   try {

package/goalbuddy/scripts/render-task-prompt.mjs

@@ -237,29 +237,43 @@ function receiptSchema(role) {
   if (role === "worker") {
     return {
       result: "done | blocked",
+      task_id: "<T###>",
+      board_path: "<path to state.yaml>",
       changed_files: [],
-      commands: [{ cmd: "<command>", status: "pass | fail | not_run" }],
-      summary: "<=120 words",
+      commands: [],
+      summary: "<=120 words>",
       remaining_blockers: [],
+      verification_attempts: 1,
+      stopped_because: null,
     };
   }
   if (role === "judge") {
     return {
       result: "done | blocked",
+      task_id: "<T###>",
+      board_path: "<path to state.yaml>",
       decision: "approved | rejected | approve_subgoal | reject_subgoal | not_complete | complete",
       full_outcome_complete: false,
+      rationale: "<=120 words>",
       evidence: [],
+      subgoal_contract: null,
+      parallel_safety: null,
       blocked_tasks: [],
+      missing_evidence: [],
       required_board_updates: [],
     };
   }
   return {
     result: "done | blocked",
-    summary: "<=120 words",
+    task_id: "<T###>",
+    board_path: "<path to state.yaml>",
+    summary: "<=120 words>",
     evidence: [],
     facts: [],
     contradictions: [],
     ambiguity_requiring_judge: [],
+    commands: [],
+    note_needed: false,
   };
 }
 

package/goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs

@@ -88,9 +88,6 @@ export function normalizeGoalBoard(document, goalDir = "<memory>") {
 
   const tasks = document.tasks.map((task, index) => normalizeTask(task, index));
   const activeTasks = tasks.filter((task) => task.status === "active");
-  if (activeTasks.length > 1) {
-    throw new GoalBoardError("Goal state has more than one active task.");
-  }
 
   return {
     goalDir,
@@ -142,13 +139,13 @@ export function buildColumns(tasks) {
     byColumn.get(task.column).push(task);
   }
 
-  for (const columnTasks of byColumn.values()) {
-    columnTasks.sort((left, right) => taskSortKey(left).localeCompare(taskSortKey(right)));
+  for (const [columnId, columnTasks] of byColumn.entries()) {
+    columnTasks.sort((left, right) => compareColumnTasks(columnId, left, right));
   }
 
   return [
     { id: "todo", title: "Todo", description: "Queued work ready to pull", tasks: byColumn.get("todo") },
-    { id: "in-progress", title: "In Progress", description: "The active task", tasks: byColumn.get("in-progress") },
+    { id: "in-progress", title: "In Progress", description: "Active task work", tasks: byColumn.get("in-progress") },
     { id: "blocked", title: "Blocked", description: "Needs unblock or a smaller slice", tasks: byColumn.get("blocked") },
     { id: "completed", title: "Completed", description: "Receipted work", tasks: byColumn.get("completed") },
   ];
@@ -289,7 +286,7 @@ function titleForTask(task) {
 function compactTaskTitle(value) {
   const text = cleanText(value).replace(/\.$/, "");
   const routeMatch = text.match(/^Implement\b.*?\s(\/[A-Za-z0-9_./:-]+)\s+(route|queue slice|slice)\b/i);
-  if (routeMatch) return truncateTitle(`Implement ${routeMatch[1]} ${routeMatch[2]}`);
+  if (routeMatch) return `Implement ${routeMatch[1]} ${routeMatch[2]}`;
 
   const firstClause = text
     .split(/(?<=[.!?])\s+|\s+(?:Use only|Add|Match|Render|Clearly label|Do not)\b/i)[0]
@@ -300,14 +297,7 @@ function compactTaskTitle(value) {
     .replace(/[.;:,]\s*$/, "")
     .trim();
 
-  return truncateTitle(firstClause || text);
-}
-
-function truncateTitle(value, maxLength = 82) {
-  const text = cleanText(value).replace(/\.$/, "");
-  if (text.length <= maxLength) return text;
-  const shortened = text.slice(0, maxLength + 1).replace(/\s+\S*$/, "").trim();
-  return `${shortened || text.slice(0, maxLength).trim()}...`;
+  return firstClause || text;
 }
 
 function columnForStatus(status) {
@@ -322,6 +312,12 @@ function taskSortKey(task) {
   return `${rank}:${task.id}`;
 }
 
+function compareColumnTasks(columnId, left, right) {
+  const order = taskSortKey(left).localeCompare(taskSortKey(right));
+  if (columnId === "completed") return -order;
+  return order;
+}
+
 function normalizeStringList(value) {
   if (!value) return [];
   if (Array.isArray(value)) return value.map(cleanText).filter(Boolean);
@@ -1503,8 +1499,13 @@ h1 {
 .task-title {
   margin: 0;
   color: #2f3437;
+  display: -webkit-box;
   font-size: 15px;
   line-height: 1.35;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 5;
 }
 
 .card-footer {