goalbuddy 0.3.6 → 0.3.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.6",
-  "description": "A /goal operating system for Codex and Claude Code: subgoals, parallel-agent-ready boards, dark mode, receipts, and verification.",
+  "version": "0.3.8",
+  "description": "A /goal operating loop for Codex and Claude Code: goal oracles, local boards, receipts, and verification.",
   "type": "module",
   "bin": {
     "goalbuddy": "internal/cli/goal-maker.mjs",
@@ -9,22 +9,22 @@
   },
   "files": [
     ".agents/plugins/marketplace.json",
+    "CHANGELOG.md",
     "README.md",
-    "RELEASE-0.3.5.md",
     "CONTRIBUTING.md",
-    "examples",
+    "docs/releases",
     "plugins/goalbuddy",
     "internal/assets",
     "internal/cli",
     "goalbuddy/SKILL.md",
     "goalbuddy/agents",
     "goalbuddy/scripts",
-    "goalbuddy/extend",
+    "goalbuddy/surfaces",
     "goalbuddy/templates"
   ],
   "scripts": {
-    "check": "node --check internal/cli/*.mjs goalbuddy/scripts/*.mjs && node --test internal/test/*.test.mjs",
-    "test": "node --test internal/test/*.test.mjs",
+    "check": "node --check internal/cli/*.mjs goalbuddy/scripts/*.mjs goalbuddy/surfaces/local-goal-board/scripts/*.mjs goalbuddy/surfaces/local-goal-board/scripts/lib/*.mjs && node --test internal/test/*.test.mjs goalbuddy/surfaces/local-goal-board/test/*.test.mjs",
+    "test": "node --test internal/test/*.test.mjs goalbuddy/surfaces/local-goal-board/test/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run",
     "postinstall": "node internal/cli/postinstall.mjs",
     "publish:check": "node internal/cli/check-publish-version.mjs && npm run pack:dry-run",
@@ -51,7 +51,6 @@
     "cli",
     "workflow",
     "agent",
-    "extensions",
     "verification"
   ],
   "author": "tolibear",

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

@@ -1,7 +1,7 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.6",
-  "description": "Turn broad Claude Code work into verified GoalBuddy boards with subgoals, parallel-agent-ready handoffs, dark mode, and receipts.",
+  "version": "0.3.8",
+  "description": "Turn broad Codex and Claude Code work into pressured /goal runs with oracles, local boards, receipts, and verification.",
   "author": {
     "name": "tolibear",
     "email": "support@tolibear.com",
@@ -18,7 +18,6 @@
     "goal",
     "task-board",
     "receipts",
-    "workflow",
-    "extensions"
+    "workflow"
   ]
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.6",
-  "description": "Turn broad Codex and Claude Code work into verified GoalBuddy boards with subgoals, parallel-agent-ready handoffs, dark mode, and receipts.",
+  "version": "0.3.8",
+  "description": "Turn broad Codex and Claude Code work into pressured /goal runs with oracles, local boards, receipts, and verification.",
   "author": {
     "name": "tolibear",
     "email": "support@tolibear.com",
@@ -18,14 +18,13 @@
     "goal",
     "task-board",
     "receipts",
-    "workflow",
-    "extensions"
+    "workflow"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "GoalBuddy",
-    "shortDescription": "Verified goal boards with subgoals, parallel-agent-ready handoffs, and dark mode",
-    "longDescription": "GoalBuddy packages a structured goal workflow for broad, long-running, or ambiguous engineering work in Codex or Claude Code. It creates durable goal charters, task boards, optional depth-1 subgoals, visual board surfaces, parallel-agent-ready handoffs, receipts, verification gates, extension handoffs, and compatibility guidance for teams moving from goal-maker.",
+    "shortDescription": "Goal oracles, local boards, receipts, and proof loops for /goal",
+    "longDescription": "GoalBuddy packages a structured goal workflow for broad, long-running, or ambiguous engineering work in Codex or Claude Code. It creates durable goal charters, goal oracles, task boards, optional depth-1 subgoals, local board surfaces, parallel-agent-ready handoffs, receipts, verification gates, and compatibility guidance for teams moving from goal-maker.",
     "developerName": "tolibear",
     "category": "Coding",
     "capabilities": [

package/plugins/goalbuddy/README.md

@@ -1,8 +1,8 @@
 # GoalBuddy Plugin (Codex + Claude Code)
 
-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 extension management.
+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.5 is the Subgoals, Parallel Agents, and Dark Mode release: depth-1 child boards, a shared multi-board local hub, readable dark-mode boards, stricter agent contracts, deterministic prompt rendering, and conservative parallel planning for long-running work.
+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.
 
 ## What It Contains
 
@@ -56,8 +56,9 @@ goalbuddy --target claude  # installs for Claude Code only
 For local CLI testing before npm publish:
 
 ```bash
-node internal/cli/goal-maker.mjs --catalog-url extend/catalog.json
+node internal/cli/goal-maker.mjs
 node internal/cli/goal-maker.mjs doctor
+node internal/cli/goal-maker.mjs board docs/goals/<slug> --once --json
 ```
 
 ## Release Notes

package/plugins/goalbuddy/skills/goalbuddy/SKILL.md

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

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

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

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

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseGoalStateText } from "../extend/local-goal-board/scripts/lib/goal-board.mjs";
+import { parseGoalStateText } from "../surfaces/local-goal-board/scripts/lib/goal-board.mjs";
 
 const ROLE_DEFAULTS = {
   scout: { agent: "goal_scout", reasoning: "low", sandbox: "read-only" },
@@ -45,6 +45,7 @@ export function renderTaskPrompt(options) {
         fork_context_allowed: role !== "worker",
         board_path: board.path,
         child_board_paths: childBoardPaths(board),
+        goal_oracle: board.goal.oracle || null,
         slice_policy: board.document.rules?.slice_policy || null,
         warnings,
       },
@@ -141,6 +142,12 @@ function promptWarnings(board, task) {
   const warnings = [];
   const role = normalizeRole(task.type);
   if (task.id !== board.activeTask) warnings.push(`Task ${task.id} is not the active task on this board.`);
+  if (isWeakProof(board.goal.oracle?.signal)) {
+    warnings.push("goal.oracle.signal is missing or placeholder-like; keep the goal pressured by a concrete completion oracle.");
+  }
+  if (isWeakProof(board.goal.oracle?.final_proof)) {
+    warnings.push("goal.oracle.final_proof is missing or placeholder-like; do not mark the goal complete without receipt-backed proof.");
+  }
   if (role === "worker") {
     if (stringList(task.allowed_files).length === 0) warnings.push(`Worker task ${task.id} has no allowed_files.`);
     if (stringList(task.verify).length === 0) warnings.push(`Worker task ${task.id} has no verify commands.`);
@@ -211,6 +218,17 @@ function isTrue(value) {
   return value === true || String(value).toLowerCase() === "true";
 }
 
+function isWeakProof(value) {
+  if (value === null || value === undefined) return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === ""
+    || normalized === "unknown"
+    || normalized === "tbd"
+    || normalized === "todo"
+    || normalized === "none"
+    || /^<.*>$/.test(normalized);
+}
+
 function stringList(value) {
   return Array.isArray(value) ? value.filter((item) => item !== null && item !== undefined).map(String) : [];
 }
@@ -219,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,
   };
 }
 
@@ -261,6 +293,9 @@ function formatPrompt(payload) {
     lines.push("- child_board_paths:");
     for (const path of payload.metadata.child_board_paths) lines.push(`  - ${path}`);
   }
+  if (payload.metadata.goal_oracle) {
+    lines.push(`- goal_oracle: ${JSON.stringify(payload.metadata.goal_oracle)}`);
+  }
   if (payload.metadata.slice_policy) {
     lines.push(`- slice_policy: ${JSON.stringify(payload.metadata.slice_policy)}`);
   }

package/{goalbuddy/extend → plugins/goalbuddy/skills/goalbuddy/surfaces}/local-goal-board/README.md

@@ -2,7 +2,7 @@
 
 Generate a small local GoalBuddy board for a goal directory and watch it update live while agents work.
 
-The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml`, `notes/`, or linked depth-1 sub-goal state changes without a manual reload.
+The surface keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml`, `notes/`, or linked depth-1 sub-goal state changes without a manual reload.
 
 ## Use When
 
@@ -14,11 +14,10 @@ The extension keeps `state.yaml` authoritative. It writes static web app files i
 ## Generate And Serve
 
 ```bash
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal docs/goals/<slug>
+npx goalbuddy board docs/goals/<slug>
 ```
 
-The generated app includes the bundled `assets/goalbuddy-mark.png`, so the board keeps the GoalBuddy mark after the extension is installed or copied elsewhere.
+The generated app includes the bundled `assets/goalbuddy-mark.png`, so the board keeps the GoalBuddy mark anywhere the package is installed.
 
 The command writes:
 
@@ -34,8 +33,7 @@ Then it starts or reuses the shared local board hub at `http://goalbuddy.localho
 ## Check Without A Long-Running Server
 
 ```bash
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal docs/goals/<slug> \
+npx goalbuddy board docs/goals/<slug> \
   --once \
   --json
 ```
@@ -63,9 +61,9 @@ Clicking a card opens a detail modal with the task objective, status, assignee,
 ## Verification
 
 ```bash
-node --test extend/local-goal-board/test/*.test.mjs
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal extend/local-goal-board/examples/sample-goal \
+node --test goalbuddy/surfaces/local-goal-board/test/*.test.mjs
+node goalbuddy/surfaces/local-goal-board/scripts/local-goal-board.mjs \
+  --goal goalbuddy/surfaces/local-goal-board/examples/sample-goal \
   --once \
   --json
 ```

package/plugins/goalbuddy/skills/goalbuddy/{extend → surfaces}/local-goal-board/examples/sample-goal/state.yaml

@@ -1,8 +1,8 @@
 version: 2
 
 goal:
-  title: "Local Kanban Board Extension"
-  slug: "local-kanban-board-extension"
+  title: "Local Goal Board Surface"
+  slug: "local-goal-board-surface"
   kind: specific
   tranche: "Demonstrate local GoalBuddy board rendering."
   status: active
@@ -30,7 +30,7 @@ tasks:
     type: worker
     assignee: Worker
     status: blocked
-    objective: "Catalog and document the local board extension."
+    objective: "Catalog and document the local board surface."
     receipt:
       result: blocked
       summary: "T003 is blocked during the progressive board motion demo."
@@ -78,7 +78,7 @@ tasks:
     type: scout
     assignee: Scout
     status: done
-    objective: "List the extension launch paths."
+    objective: "List the board launch paths."
     receipt:
       result: done
       summary: "T009 completed during the progressive board motion demo."
@@ -118,7 +118,7 @@ tasks:
     type: worker
     assignee: Worker
     status: done
-    objective: "Prepare final extension packaging check."
+    objective: "Prepare final board packaging check."
     receipt:
       result: done
       summary: "T014 completed during the progressive board motion demo."

package/{goalbuddy/extend → plugins/goalbuddy/skills/goalbuddy/surfaces}/local-goal-board/examples/subgoal-parent/state.yaml

@@ -31,10 +31,10 @@ tasks:
     status: active
     objective: "Build the sub-goal board view."
     allowed_files:
-      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
-      - goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
+      - goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     verify:
-      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     stop_if:
       - "Need files outside allowed_files."
     subgoal:

package/plugins/goalbuddy/skills/goalbuddy/{extend → surfaces}/local-goal-board/examples/subgoal-parent/subgoals/T004-board-view/state.yaml

@@ -24,16 +24,16 @@ tasks:
       result: done
       summary: "Child board payload needs normal columns and task details."
       evidence:
-        - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+        - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
   - id: T002
     type: worker
     assignee: Worker
     status: active
     objective: "Render the read-only embedded child board."
     allowed_files:
-      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+      - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
     verify:
-      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     stop_if:
       - "Need files outside allowed_files."
     receipt: null

package/{goalbuddy/extend → plugins/goalbuddy/skills/goalbuddy/surfaces}/local-goal-board/scripts/lib/goal-board.mjs

@@ -6,8 +6,8 @@ import { fileURLToPath } from "node:url";
 const VALID_STATUSES = new Set(["queued", "active", "blocked", "done"]);
 const COLUMN_ORDER = ["todo", "in-progress", "blocked", "completed"];
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const extensionRoot = resolve(__dirname, "../..");
-const logoAssetPath = join(extensionRoot, "assets", "goalbuddy-mark.png");
+const surfaceRoot = resolve(__dirname, "../..");
+const logoAssetPath = join(surfaceRoot, "assets", "goalbuddy-mark.png");
 
 export class GoalBoardError extends Error {
   constructor(message) {

package/plugins/goalbuddy/skills/goalbuddy/{extend → surfaces}/local-goal-board/scripts/local-goal-board.mjs

@@ -228,8 +228,7 @@ export async function startBoardServer(options = {}) {
 
       const route = routeBoardRequest(url.pathname, boards, initialBoard);
       if (!route.board) {
-        response.writeHead(404);
-        response.end("Not found");
+        sendUnregisteredBoardPath(response, url.pathname, boards, baseUrl);
         return;
       }
       if (route.pathname === "/api/board") {
@@ -400,6 +399,28 @@ function routeBoardRequest(pathname, boards, initialBoard) {
   return matches[0] || { board: null, pathname };
 }
 
+function sendUnregisteredBoardPath(response, pathname, boards, baseUrl) {
+  response.writeHead(404, {
+    "Content-Type": "text/plain; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  const registeredBoards = [...boards.values()].map((board) => {
+    const summary = boardSummary(board, baseUrl);
+    return `- ${summary.title}: ${summary.url}`;
+  });
+  response.end([
+    `GoalBuddy board path is not registered in this local hub: ${pathname}`,
+    "",
+    "This server is the GoalBuddy multi-board hub. Do not stop it just because a /<slug>/ board URL returned 404.",
+    "Start or rerun `npx goalbuddy board <goal-dir>` to register that goal on this same port, then open the printed /<slug>/ URL.",
+    "",
+    "Registered boards:",
+    registeredBoards.length ? registeredBoards.join("\n") : "- none",
+    "",
+    `Hub API: ${baseUrl}/api/boards`,
+  ].join("\n"));
+}
+
 function stripBoardPathPrefix(pathname, boardPath) {
   const prefix = boardPath.endsWith("/") ? boardPath.slice(0, -1) : boardPath;
   if (pathname === prefix) return "/";
@@ -527,9 +548,9 @@ function serveStatic(appDir, pathname, response) {
     return;
   }
 
-  const extension = cleanPath.match(/\.[^.]+$/)?.[0] || "";
+  const fileExtension = cleanPath.match(/\.[^.]+$/)?.[0] || "";
   response.writeHead(200, {
-    "Content-Type": textTypes[extension] || "application/octet-stream",
+    "Content-Type": textTypes[fileExtension] || "application/octet-stream",
     "Cache-Control": "no-store",
   });
   response.end(readFileSync(file));
@@ -580,8 +601,8 @@ function usage() {
   console.log(`GoalBuddy Local Goal Board
 
 Usage:
-  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug>
-  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug> --once --json
+  npx goalbuddy board docs/goals/<slug>
+  npx goalbuddy board docs/goals/<slug> --once --json
 
 Options:
   --goal <path>   Goal directory containing state.yaml.