goalbuddy 0.3.8 → 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

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

package/README.md

@@ -152,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.8: Board Hub Guardrails](docs/releases/0.3.8.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%">

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

@@ -2,6 +2,7 @@
 
 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)

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,9 +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 `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 `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.
 
@@ -474,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.
@@ -528,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.
 
@@ -570,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/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,
@@ -148,7 +145,7 @@ export function buildColumns(tasks) {
 
   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") },
   ];

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

@@ -33,6 +33,7 @@ const SETTINGS_OPTIONS = {
 const DEFAULT_BIND_HOST = "127.0.0.1";
 const DEFAULT_PUBLIC_HOST = "goalbuddy.localhost";
 const DEFAULT_PORT = 41737;
+const STATE_CHANGE_SETTLE_MS = 300;
 
 if (isDirectRun()) {
   main().catch((error) => {
@@ -441,7 +442,7 @@ async function readJsonRequest(request) {
 
 function watchGoal(goalDir, onChange) {
   const watchers = [];
-  const schedule = debounce(onChange, 80);
+  const schedule = debounce(onChange, STATE_CHANGE_SETTLE_MS);
   let watchedDirs = new Set();
 
   const rebuild = () => {

package/goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs

@@ -35,6 +35,59 @@ test("orders completed cards newest first while preserving queued order", () =>
   assert.deepEqual(columns.find((column) => column.id === "completed").tasks.map((task) => task.id), ["T003", "T001"]);
 });
 
+test("renders multiple active tasks in the in-progress column", () => {
+  const root = mkdtempSync(join(tmpdir(), "goalbuddy-multiple-active-"));
+  try {
+    const goalDir = join(root, "parallel-workers");
+    mkdirSync(join(goalDir, "notes"), { recursive: true });
+    writeFileSync(join(goalDir, "state.yaml"), `version: 2
+goal:
+  title: "Parallel workers"
+  slug: "parallel-workers"
+  kind: specific
+  tranche: "Render disjoint active workers."
+  status: active
+active_task: T001
+tasks:
+  - id: T001
+    type: worker
+    assignee: Worker A
+    status: active
+    objective: "Patch the board parser."
+    allowed_files:
+      - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
+    verify:
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
+    stop_if:
+      - "Need files outside allowed_files."
+    receipt: null
+  - id: T002
+    type: worker
+    assignee: Worker B
+    status: active
+    objective: "Patch the board tests."
+    allowed_files:
+      - goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
+    verify:
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
+    stop_if:
+      - "Need files outside allowed_files."
+    receipt: null
+`);
+
+    const payload = createBoardPayload(goalDir);
+    assert.equal(payload.goal.activeTask, "T001");
+    assert.equal(payload.counts.inProgress, 2);
+    assert.deepEqual(
+      payload.columns.find((column) => column.id === "in-progress").tasks.map((task) => task.id),
+      ["T001", "T002"],
+    );
+    assert.deepEqual(payload.tasks.filter((task) => task.active).map((task) => task.id), ["T001", "T002"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("loads depth-1 subgoal boards into parent task payloads", () => {
   const payload = createBoardPayload(resolve("goalbuddy/surfaces/local-goal-board/examples/subgoal-parent"));
   const parentTask = payload.tasks.find((task) => task.id === "T004");
@@ -472,6 +525,50 @@ test("serves board JSON and streams live state changes over SSE", async () => {
   }
 });
 
+test("coalesces transient active-task violations during multi-write transitions", async () => {
+  const root = mkdtempSync(join(tmpdir(), "goalbuddy-local-board-transition-"));
+  const goalDir = join(root, "transition-goal");
+  try {
+    mkdirSync(join(goalDir, "notes"), { recursive: true });
+    writeFileSync(join(goalDir, "state.yaml"), transitionStateYaml({
+      activeTask: "T001",
+      firstStatus: "active",
+      secondStatus: "queued",
+    }));
+
+    const server = await startBoardServer({ goalDir, host: "127.0.0.1", port: 0 });
+    try {
+      const controller = new AbortController();
+      const events = await fetch(`${server.url}events`, { signal: controller.signal });
+      assert.equal(events.status, 200);
+      const reader = events.body.getReader();
+
+      await readUntil(reader, /"activeTask":"T001"/);
+      writeFileSync(join(goalDir, "state.yaml"), transitionStateYaml({
+        activeTask: "T002",
+        firstStatus: "active",
+        secondStatus: "active",
+      }));
+      await delay(120);
+      writeFileSync(join(goalDir, "state.yaml"), transitionStateYaml({
+        activeTask: "T002",
+        firstStatus: "done",
+        secondStatus: "active",
+      }));
+
+      const update = await readUntil(reader, /"activeTask":"T002"/);
+      assert.doesNotMatch(update, /more than one active task/i);
+
+      controller.abort();
+      await reader.cancel().catch(() => {});
+    } finally {
+      await server.close();
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("streams parent board updates when linked child subgoal state changes", async () => {
   const root = mkdtempSync(join(tmpdir(), "goalbuddy-local-board-subgoal-live-"));
   const goalDir = join(root, "parent-goal");
@@ -624,6 +721,10 @@ async function readUntil(reader, pattern) {
   assert.fail(`Timed out waiting for ${pattern}. Received:\n${text}`);
 }
 
+function delay(ms) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
 function parentWithSubgoalYaml() {
   return `version: 2
 goal:
@@ -648,6 +749,39 @@ tasks:
 `;
 }
 
+function transitionStateYaml({ activeTask, firstStatus, secondStatus }) {
+  return `version: 2
+goal:
+  title: "Transition Goal"
+  slug: "transition-goal"
+  kind: specific
+  tranche: "Verify multi-write task transition."
+  status: active
+active_task: ${activeTask}
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: ${firstStatus}
+    objective: "Map transition."
+    receipt:
+      result: done
+      summary: "Mapped transition."
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: ${secondStatus}
+    objective: "Implement transition."
+    allowed_files:
+      - goalbuddy/surfaces/local-goal-board/**
+    verify:
+      - npm run check
+    stop_if:
+      - "Need files outside allowed_files."
+    receipt: null
+`;
+}
+
 function stateYaml(status, { title = "Live board", slug = "live-board" } = {}) {
   return `version: 2
 goal:

package/goalbuddy/templates/goal.md

@@ -64,6 +64,18 @@ Tiny tasks are allowed when the failure is isolated, the risk is high, the scope
 
 Do not stop because a slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that exact slice blocked with a receipt, create the smallest safe follow-up or workaround task, and continue all local, non-destructive work that can still move the goal toward the full outcome.
 
+If an exact human approval phrase is the only remaining blocker and no safe local work remains, ask once and stop. Preserve the exact phrase in the blocked receipt as `required_reply`, set `waiting_for_user_approval: true`, set `goal.status: blocked`, and set `active_task: null`. Do not keep posting approval prompts until the user replies.
+
+## Board Health
+
+The PM owns board health. If the board looks stale, misleading, offline, or inconsistent, run the bundled checker:
+
+```bash
+node <skill-path>/scripts/check-goal-state.mjs docs/goals/<slug>
+```
+
+If the local board is running, compare `state.yaml` to the live board API. Repair only GoalBuddy control files unless an active Worker or PM task explicitly allows product-file edits.
+
 ## Canonical Board
 
 Machine truth lives at:

package/goalbuddy/templates/state.yaml

@@ -35,6 +35,7 @@ rules:
   queued_required_worker_blocks_completion: true
   continuous_until_full_outcome: true
   missing_input_or_credentials_do_not_stop_goal: true
+  exact_human_approval_can_terminal_wait: true
   preserve_and_validate_existing_plan: true
   intake_misfire_must_be_audited: true
   goal_pressure_requires_oracle: true
@@ -58,7 +59,7 @@ visual_board:
   local:
     status: not_requested # not_requested | starting | live | generated | blocked
     url: null
-    command: "npx goalbuddy board docs/goals/<goal-slug>"
+    command: "node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<goal-slug>"
 
 active_task: T001
 

package/internal/cli/goal-maker.mjs

@@ -735,7 +735,7 @@ function updateReport() {
     latest_version: null,
     update_available: false,
     check_status: "unknown",
-    update_command: `npx ${canonicalCliName}`,
+    update_command: detectUpdateCommand(),
   };
 
   try {
@@ -750,6 +750,23 @@ function updateReport() {
   return report;
 }
 
+function detectUpdateCommand() {
+  if (process.env.GOALBUDDY_TEST_UPDATE_COMMAND) return process.env.GOALBUDDY_TEST_UPDATE_COMMAND;
+  if (process.env.CLAUDE_PLUGIN_ROOT || normalizedPath(__dirname).includes("/.claude/")) return `/plugin update ${pluginName}@${pluginName}`;
+
+  const userAgent = process.env.npm_config_user_agent || "";
+  if (/^pnpm\//.test(userAgent)) return `pnpm update -g ${canonicalCliName}`;
+  if (/^bun\//.test(userAgent)) return `bun update -g ${canonicalCliName}`;
+  if (process.env.MISE_EXE || process.env.MISE_SHELL || process.env.MISE_PROJECT_ROOT) return `mise upgrade npm:${canonicalCliName}`;
+  if (/^npm\//.test(userAgent)) return `npx ${canonicalCliName}@latest`;
+
+  return `use the install channel that installed ${canonicalProductName}`;
+}
+
+function normalizedPath(path) {
+  return String(path).replace(/\\/g, "/");
+}
+
 function plugin() {
   const subcommand = positional(1) || "";
   if (wantsHelp()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "A /goal operating loop for Codex and Claude Code: goal oracles, local boards, receipts, and verification.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     ".agents/plugins/marketplace.json",
+    ".claude-plugin/marketplace.json",
     "CHANGELOG.md",
     "README.md",
     "CONTRIBUTING.md",

package/plugins/goalbuddy/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Turn broad Codex and Claude Code work into pressured /goal runs with oracles, local boards, receipts, and verification.",
   "author": {
     "name": "tolibear",

package/plugins/goalbuddy/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Turn broad Codex and Claude Code work into pressured /goal runs with oracles, local boards, receipts, and verification.",
   "author": {
     "name": "tolibear",

package/plugins/goalbuddy/README.md

@@ -2,7 +2,7 @@
 
 GoalBuddy packages the canonical `goal-prep` skill as a plugin so teams can install the reusable workflow in **Codex** and **Claude Code**, while keeping the npm CLI for local setup, doctor checks, and the built-in local board surface.
 
-Version 0.3.8 keeps the Goalmaxxed core and adds board-hub guardrails so agents reuse the shared local board hub instead of stopping it after an unregistered board URL returns 404.
+Version 0.3.9 keeps the Goalmaxxed core and hardens marketplace installs, local board rendering, and PM runtime guidance for approval waits and board-health checks.
 
 ## What It Contains
 

package/plugins/goalbuddy/skills/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,9 +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 `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 `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.
 
@@ -474,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.
@@ -528,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.
 
@@ -570,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/plugins/goalbuddy/skills/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/plugins/goalbuddy/skills/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/plugins/goalbuddy/skills/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,
@@ -148,7 +145,7 @@ export function buildColumns(tasks) {
 
   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") },
   ];

package/plugins/goalbuddy/skills/goalbuddy/surfaces/local-goal-board/scripts/local-goal-board.mjs

@@ -33,6 +33,7 @@ const SETTINGS_OPTIONS = {
 const DEFAULT_BIND_HOST = "127.0.0.1";
 const DEFAULT_PUBLIC_HOST = "goalbuddy.localhost";
 const DEFAULT_PORT = 41737;
+const STATE_CHANGE_SETTLE_MS = 300;
 
 if (isDirectRun()) {
   main().catch((error) => {
@@ -441,7 +442,7 @@ async function readJsonRequest(request) {
 
 function watchGoal(goalDir, onChange) {
   const watchers = [];
-  const schedule = debounce(onChange, 80);
+  const schedule = debounce(onChange, STATE_CHANGE_SETTLE_MS);
   let watchedDirs = new Set();
 
   const rebuild = () => {

package/plugins/goalbuddy/skills/goalbuddy/templates/goal.md

@@ -64,6 +64,18 @@ Tiny tasks are allowed when the failure is isolated, the risk is high, the scope
 
 Do not stop because a slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that exact slice blocked with a receipt, create the smallest safe follow-up or workaround task, and continue all local, non-destructive work that can still move the goal toward the full outcome.
 
+If an exact human approval phrase is the only remaining blocker and no safe local work remains, ask once and stop. Preserve the exact phrase in the blocked receipt as `required_reply`, set `waiting_for_user_approval: true`, set `goal.status: blocked`, and set `active_task: null`. Do not keep posting approval prompts until the user replies.
+
+## Board Health
+
+The PM owns board health. If the board looks stale, misleading, offline, or inconsistent, run the bundled checker:
+
+```bash
+node <skill-path>/scripts/check-goal-state.mjs docs/goals/<slug>
+```
+
+If the local board is running, compare `state.yaml` to the live board API. Repair only GoalBuddy control files unless an active Worker or PM task explicitly allows product-file edits.
+
 ## Canonical Board
 
 Machine truth lives at:

package/plugins/goalbuddy/skills/goalbuddy/templates/state.yaml

@@ -35,6 +35,7 @@ rules:
   queued_required_worker_blocks_completion: true
   continuous_until_full_outcome: true
   missing_input_or_credentials_do_not_stop_goal: true
+  exact_human_approval_can_terminal_wait: true
   preserve_and_validate_existing_plan: true
   intake_misfire_must_be_audited: true
   goal_pressure_requires_oracle: true
@@ -58,7 +59,7 @@ visual_board:
   local:
     status: not_requested # not_requested | starting | live | generated | blocked
     url: null
-    command: "npx goalbuddy board docs/goals/<goal-slug>"
+    command: "node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<goal-slug>"
 
 active_task: T001