goalbuddy 0.3.7 → 0.3.9

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

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.7",
+  "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.7",
+  "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.7 is the Goalmaxxed release: goal oracles, largest safe useful slices, built-in local boards, receipt pressure, final-proof gates, and a smaller core without the extension catalog.
+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,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/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/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/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) => {
@@ -228,8 +229,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 +400,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 "/";
@@ -420,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/surfaces/local-goal-board/test/local-goal-board.test.mjs

@@ -558,6 +558,33 @@ test("serves multiple local boards from one shared hub URL", async () => {
   }
 });
 
+test("unregistered board paths explain hub reuse instead of stale-port cleanup", async () => {
+  const root = mkdtempSync(join(tmpdir(), "goalbuddy-local-board-unregistered-"));
+  const goalDir = join(root, "first-goal");
+  try {
+    mkdirSync(join(goalDir, "notes"), { recursive: true });
+    writeFileSync(join(goalDir, "state.yaml"), stateYaml("active", { title: "First Goal", slug: "first-goal" }));
+
+    const server = await startBoardServer({ goalDir, host: "127.0.0.1", port: 0 });
+    try {
+      const baseUrl = new URL(server.url).origin;
+      const missingResponse = await fetch(`${baseUrl}/rinova-client-revision-redesign/`);
+      assert.equal(missingResponse.status, 404);
+      const message = await missingResponse.text();
+      assert.match(message, /board path is not registered/i);
+      assert.match(message, /multi-board hub/i);
+      assert.match(message, /Do not stop it just because a \/<slug>\/ board URL returned 404/);
+      assert.match(message, /npx goalbuddy board <goal-dir>/);
+      assert.match(message, /First Goal/);
+      assert.match(message, /\/api\/boards/);
+    } finally {
+      await server.close();
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 async function readUntil(reader, pattern) {
   const decoder = new TextDecoder();
   let text = "";

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
 

package/examples/improve-goal-maker/goal.md

@@ -1,51 +0,0 @@
-# Improve Goal Maker
-
-## Objective
-
-Improve the local Goal Maker skill by discovering the highest-leverage repo-backed changes, completing the first safe implementation tranche, and leaving a reviewable handoff for anything larger.
-
-## Goal Kind
-
-`open_ended`
-
-## Current Tranche
-
-Map the current Goal Maker implementation, identify concrete improvement candidates with verification paths, select one small and reversible tranche, implement it, verify it, and finish with an audit receipt.
-
-## Non-Negotiable Constraints
-
-- Keep Goal Maker v2 control-file semantics intact: `goal.md`, `state.yaml`, and `notes/` only at each goal root.
-- Do not implement from assumptions; Scout evidence or Judge selection must precede Worker edits.
-- Preserve compatibility with Codex agent roles and the existing checker unless a Judge task explicitly chooses otherwise.
-- Keep changes small, reviewable, and backed by local verification commands.
-- Do not use destructive git operations or require credentials.
-
-## Stop Rule
-
-Stop when the tranche audit passes, all safe local work is blocked, or continuing would require owner input, credentials, destructive operations, or strategy the board cannot decide.
-
-## Canonical Board
-
-Machine truth lives at:
-
-`examples/improve-goal-maker/state.yaml`
-
-If this charter and `state.yaml` disagree, `state.yaml` wins for task status, active task, receipts, verification freshness, and completion truth.
-
-## Run Command
-
-```text
-/goal Follow examples/improve-goal-maker/goal.md
-```
-
-## PM Loop
-
-On every `/goal` continuation:
-
-1. Read this charter.
-2. Read `state.yaml`.
-3. Work only on the active board task.
-4. Assign Scout, Judge, Worker, or PM according to the task.
-5. Write a compact task receipt.
-6. Update the board.
-7. Select the next active task or finish with a Judge/PM audit receipt.

package/examples/improve-goal-maker/notes/T001-repo-map.md

@@ -1,59 +0,0 @@
-# T001: Goal Maker Repo Map
-
-Task: `T001`
-Kind: `scout`
-Status: `current`
-
-## Summary
-
-Goal Maker is a small dependency-free npm package that installs a Codex skill, three agent role definitions, templates, and a v2 board checker. The core verification path is healthy: syntax checks and all current checker tests pass, a temporary install plus doctor run succeeds, and the package dry run includes the expected runtime files. The highest-leverage next investigation is not packaging correctness; it is workflow reliability around checker blind spots, agent-installation assumptions, and template/skill contract drift.
-
-## Repo Map
-
-- `README.md` describes the package purpose, install commands, board model, repository layout, and status caveats.
-- `CONTRIBUTING.md` defines the local verification contract: `npm run check`, temporary install/doctor, and `npm pack --dry-run`.
-- `package.json` exposes the `goal-maker` bin, keeps runtime dependency-free, packages the skill runtime plus docs/assets, and defines `check`, `test`, and `pack:dry-run`.
-- `goal-maker/SKILL.md` is the installed skill contract: direct `$goal-maker` creates or repairs a v2 board, stops for user choice, and `/goal` owns the PM loop.
-- `goal-maker/bin/goal-maker.mjs` installs the skill and bundled `goal_*.toml` agents into a Codex home and supports `install`, `update`, `agents`, `doctor`, and help.
-- `goal-maker/scripts/check-goal-state.mjs` validates v2 board shape with a lightweight line-oriented parser.
-- `goal-maker/scripts/install-agents.mjs` is a secondary agent copy helper.
-- `goal-maker/templates/goal.md`, `state.yaml`, and `note.md` seed new goal control files.
-- `goal-maker/agents/goal_scout.toml`, `goal_worker.toml`, and `goal_judge.toml` define the intended role constraints.
-- `goal-maker/test/check-goal-state.test.mjs` covers key checker invariants.
-
-## Verification Commands
-
-- `npm run check` passed: Node syntax checks and 7 node:test cases passed.
-- Temporary install plus doctor passed: `skill_installed: true`; installed agents were `goal_judge.toml`, `goal_scout.toml`, and `goal_worker.toml`.
-- `npm pack --dry-run` passed and listed the expected package files, including `README.md`, `CONTRIBUTING.md`, `internal/assets/`, `package.json`, and `goal-maker/` runtime files.
-- `node goal-maker/scripts/check-goal-state.mjs examples/improve-goal-maker/state.yaml` passed with `ok: true`.
-
-## Health Signals
-
-- Current tests cover a valid Scout board, active Worker requirements, legacy v1 rejection, one-active-task enforcement, done-task receipt requirements, unexpected root entries, and final audit completion.
-- The checker intentionally avoids dependencies, but it parses YAML with regular expressions and line indentation. This is acceptable for the template subset but creates likely blind spots for richer valid YAML or misleading strings inside quoted values.
-- The package has two agent-installation paths: the CLI in `goal-maker/bin/goal-maker.mjs` and the helper in `goal-maker/scripts/install-agents.mjs`. They are similar but not identical.
-- The direct skill contract says `$goal-maker` must verify Scout, Worker, and Judge agents are installed or explain what is missing; current templates mark them `installed`, while actual verification is behavior implemented by the PM thread, not the CLI/checker.
-
-## Ranked Improvement Candidates
-
-1. Add checker tests and fixes for root-path robustness and YAML parsing edge cases, especially misleading legacy markers inside quoted values or comments.
-2. Reconcile or document the two agent-installation paths so CLI behavior, helper behavior, and README guidance cannot drift.
-3. Make agent installation status less assumption-driven in generated boards or add checker warnings when agent status values are placeholders.
-4. Add tests for the CLI install/doctor/package path so the contributor verification contract is covered by `npm run check`, not just manual commands.
-5. Tighten docs/templates around what `/goal` PM may do in Codex environments where actual subagent dispatch is unavailable and roles are simulated in-thread.
-
-## Candidate Next Tasks
-
-- Investigate checker blind spots with focused failing test candidates before choosing a fix.
-- Compare `goal-maker/bin/goal-maker.mjs` and `goal-maker/scripts/install-agents.mjs` and decide whether to consolidate, test, or document the helper.
-- Judge the first implementation tranche after the risk map, preferring a small test-backed checker or CLI reliability fix.
-
-## Board Receipt Snippet
-
-```yaml
-receipt:
-  result: done
-  note: notes/T001-repo-map.md
-  summary: "Repo map completed; verification is green, install/package checks work, and the top improvement area is Goal Maker workflow reliability around checker blind spots, agent installation assumptions, and template/skill drift."
-```

package/examples/improve-goal-maker/notes/T002-risk-map.md

@@ -1,37 +0,0 @@
-# T002: Workflow Risk Map
-
-Task: `T002`
-Kind: `scout`
-Status: `current`
-
-## Summary
-
-The highest-confidence risks are small and testable. First, `goal-maker doctor` reports success when one of the required bundled agents is missing, which weakens the "verify Scout, Worker, and Judge agents" contract. Second, the board checker accepts mismatched task `type` and `assignee` values, even though Goal Maker semantics depend on those fields agreeing. A lower-priority drift risk is that `update` does not overwrite stale existing agent definitions unless `--force` is supplied, despite README wording that says install or update the skill and bundled agents.
-
-## Evidence
-
-- `goal-maker/bin/goal-maker.mjs` `doctor()` exits based only on whether `skills/goal-maker/SKILL.md` exists. In a temp Codex home with `goal_worker.toml` removed, `doctor` exited 0 and reported only `goal_judge.toml` and `goal_scout.toml`.
-- `goal-maker/scripts/check-goal-state.mjs` independently validates `task.type` and `task.assignee`, but does not validate pairs. A temp board with `type: scout` and `assignee: Worker` passed with `ok: true`.
-- `goal-maker/scripts/check-goal-state.mjs` does not require or validate the `agents:` section. A temp board with the section omitted passed with `ok: true`.
-- `goal-maker/bin/goal-maker.mjs` `installAgents()` skips existing `goal_*.toml` files unless `--force` is present. In a temp Codex home with a stale `goal_scout.toml`, `goal-maker update` left the stale file unchanged.
-- `goal-maker/scripts/install-agents.mjs` copies any `.toml` except names containing `config-snippet`, while the CLI copies only `goal_*.toml`. Current files make this harmless, but it is a drift point.
-
-## Small Safe Implementation Candidates
-
-1. Add CLI tests for `doctor` and make `doctor` fail when any required agent file is missing. Allowed files would likely be `goal-maker/bin/goal-maker.mjs` and a new focused CLI test file.
-2. Add checker tests for task type/assignee mismatch and fix the checker to reject mismatches. Allowed files would be `goal-maker/scripts/check-goal-state.mjs` and `goal-maker/test/check-goal-state.test.mjs`.
-3. Add checker tests for missing or invalid `agents:` statuses and reject or warn. This is slightly more policy-heavy because templates currently treat agent status as PM-populated board metadata.
-4. Decide whether `update` should overwrite existing bundled agents or whether README/CLI wording should clarify that `--force` is required for agent refresh.
-
-## Recommended First Tranche
-
-Prefer the `doctor` missing-agent fix. It directly supports the `$goal-maker` requirement to verify Scout, Worker, and Judge availability, has tight behavior, and can be verified with a new CLI test plus existing checks. The checker mismatch fix is also small, but it is less directly connected to the user-visible setup flow.
-
-## Board Receipt Snippet
-
-```yaml
-receipt:
-  result: done
-  note: notes/T002-risk-map.md
-  summary: "Risk map completed; doctor exits green with missing agents, checker accepts type/assignee mismatches, and update leaves stale agents unless forced."
-```