goalbuddy 0.2.20 → 0.2.21

package/README.md

@@ -124,6 +124,12 @@ Check the local install:
 npx goalbuddy doctor
 ```
 
+Check whether a newer GoalBuddy release is available:
+
+```bash
+npx goalbuddy check-update
+```
+
 Use a non-default Codex home:
 
 ```bash
@@ -146,6 +152,14 @@ Check board health at any time:
 node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
 ```
 
+Launch the optional local board viewer for a goal:
+
+```bash
+npx goalbuddy board docs/goals/<slug>
+```
+
+`goalbuddy board` installs the `local-goal-board` extension from the catalog if needed, writes `.goalbuddy-board/` into the goal directory, and serves a local live-updating board.
+
 For a broad prompt like "Improve my project," the first active task should usually be Scout, not Worker:
 
 ```yaml
@@ -193,6 +207,7 @@ Current catalog examples include:
 
 - `github-pr-workflow`: prepares receipt-aligned commit and PR handoff text.
 - `github-projects`: mirrors GoalBuddy boards into GitHub Projects.
+- `local-goal-board`: serves a local GoalBuddy-branded board that updates live from `state.yaml` and `notes/`.
 - `ai-diff-risk-review`: summarizes risk in the current diff.
 - `ci-failure-triage`: maps failing CI back to likely causes and next tasks.
 - `docs-drift-audit`: checks whether docs still match implementation.

package/goalbuddy/SKILL.md

@@ -28,6 +28,7 @@ During a `$goal-prep` turn, do not perform the user's requested work, even if th
 
 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`, and `docs/goals/<slug>/notes/`;
 - optionally run the GoalBuddy board checker against that `state.yaml`;
@@ -37,6 +38,22 @@ Allowed `$goal-prep` actions:
 
 If the prompt names another skill or tool, such as "use the taste skill", "refresh the taste skill", "look at this repo", "use browser", or "generate assets", record that requirement in the charter and seed tasks. Do not load that skill, browse that repo, or generate those assets during `$goal-prep`.
 
+## Update Check
+
+At the start of a `$goal-prep` turn, check whether GoalBuddy itself is stale. Run the bundled checker from the installed skill directory when available:
+
+```bash
+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
+```
+
+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.
+
 ## Intake Compiler
 
 Before creating, repairing, or running a board, privately translate the user's input into a Goal Intake. The input may be vague, specific, or detailed with an existing plan. Do not dump the intake to the user unless they ask for it.
@@ -131,6 +148,7 @@ When invoked directly, run intake first. For vague, strategic, improvement-orien
 
 Do:
 
+- check for a newer GoalBuddy version once at the start and mention it without blocking;
 - clarify or infer the goal title and slug;
 - run the Intake Compiler;
 - ask diagnostic intake questions when clarity would materially improve the board;
@@ -409,6 +427,25 @@ 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.
 
+## 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.
+
+The PM may create a board task to prepare a repo-native follow-up. If the user has already approved publishing and the repo/auth state supports it, the PM may create an issue or PR directly and record the link in the receipt. Otherwise, ask the operator one concise question before creating the external artifact:
+
+```markdown
+I found [problem or suggestion].
+
+Should I:
+1. Create an issue in this repo for it? (Recommended) - [why]
+2. Prepare a PR for the fix/suggestion - [when this is better]
+3. Keep it only in the GoalBuddy board for now - [tradeoff]
+```
+
+Use an issue for follow-up work, unclear scope, missing approval, or suggestions that need discussion. Use a PR when the fix is already implemented or safely implementable within the current approved scope. If neither is appropriate, propose a different path and record the decision in `state.yaml`.
+
+External issues and PRs are supporting artifacts, not board truth. `state.yaml` remains authoritative, and every issue/PR creation or decision must be reflected in a PM, Worker, or Judge receipt.
+
 ## Continuation Rule
 
 After a task completes, immediately write its receipt and select the next active task unless:

package/goalbuddy/scripts/check-update.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageName = "goalbuddy";
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+
+const report = {
+  package: packageName,
+  current_version: findCurrentVersion(),
+  latest_version: null,
+  update_available: false,
+  check_status: "unknown",
+  update_command: "npx goalbuddy",
+};
+
+try {
+  report.latest_version = latestPublishedVersion();
+  report.update_available = compareVersions(report.current_version, report.latest_version) < 0;
+  report.check_status = "ok";
+} catch (error) {
+  report.check_status = "unavailable";
+  report.error = error.message;
+}
+
+if (args.includes("--json")) {
+  console.log(JSON.stringify(report, null, 2));
+} else if (report.check_status !== "ok") {
+  console.log(`GoalBuddy update check unavailable: ${report.error}`);
+} else if (report.update_available) {
+  console.log(`GoalBuddy ${report.latest_version} is available; installed version is ${report.current_version}.`);
+  console.log(`Update with: ${report.update_command}`);
+} else {
+  console.log(`GoalBuddy is up to date (${report.current_version}).`);
+}
+
+function findCurrentVersion() {
+  const candidates = [
+    join(scriptDir, "..", ".goalbuddy-install.json"),
+    join(scriptDir, "..", "..", "..", ".codex-plugin", "plugin.json"),
+    join(scriptDir, "..", "..", "package.json"),
+  ];
+
+  for (const path of candidates) {
+    const data = readJson(path);
+    const version = data?.package_version || data?.version;
+    if (version) return normalizeVersion(version);
+  }
+
+  return "0.0.0";
+}
+
+function latestPublishedVersion() {
+  if (process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION) {
+    return normalizeVersion(process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION);
+  }
+
+  const result = spawnSync("npm", ["view", packageName, "version"], {
+    cwd: resolve(scriptDir, ".."),
+    encoding: "utf8",
+    timeout: 5000,
+    env: {
+      ...process.env,
+      npm_config_update_notifier: "false",
+    },
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    throw new Error(output || `npm view exited with status ${result.status}`);
+  }
+
+  return normalizeVersion(result.stdout);
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeVersion(value) {
+  const match = String(value).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) throw new Error(`Unsupported version: ${value}`);
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+function compareVersions(left, right) {
+  const leftParts = normalizeVersion(left).split(".").map(Number);
+  const rightParts = normalizeVersion(right).split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}

package/goalbuddy/templates/goal.md

@@ -61,11 +61,15 @@ On every `/goal` continuation:
 
 1. Read this charter.
 2. Read `state.yaml`.
-3. Re-check the intake: original request, input shape, authority, proof, blind spots, existing plan facts, and likely misfire.
-4. Work only on the active board task.
-5. Assign Scout, Judge, Worker, or PM according to the task.
-6. Write a compact task receipt.
-7. Update the board.
-8. If Judge selected a safe Worker task with `allowed_files`, `verify`, and `stop_if`, activate it and continue unless blocked.
-9. Treat a slice audit as a checkpoint, not completion, unless it explicitly proves the full original outcome is complete.
-10. Finish only with a Judge/PM audit receipt that maps receipts and verification back to the original user outcome and records `full_outcome_complete: true`.
+3. Run the bundled GoalBuddy update checker when available and mention a newer version without blocking.
+4. Re-check the intake: original request, input shape, authority, proof, blind spots, existing plan facts, and likely misfire.
+5. Work only on the active board task.
+6. Assign Scout, Judge, Worker, or PM according to the task.
+7. Write a compact task receipt.
+8. Update the board.
+9. If Judge selected a safe Worker task with `allowed_files`, `verify`, and `stop_if`, activate it and continue unless blocked.
+10. If a problem, suggestion, or follow-up should become a repo artifact, create an approved issue/PR or ask the operator whether to create one.
+11. Treat a slice audit as a checkpoint, not completion, unless it explicitly proves the full original outcome is complete.
+12. Finish only with a Judge/PM audit receipt that maps receipts and verification back to the original user outcome and records `full_outcome_complete: true`.
+
+Issue and PR handoffs are supporting artifacts. `state.yaml` remains authoritative, and every external artifact decision must be recorded in a task receipt.

package/internal/cli/goal-maker.mjs

@@ -37,7 +37,10 @@ const optionsWithValues = new Set([
   "--catalog",
   "--catalog-url",
   "--codex-home",
+  "--goal",
+  "--host",
   "--kind",
+  "--port",
   "--source",
 ]);
 
@@ -70,12 +73,19 @@ async function main() {
     case "doctor":
       doctor();
       break;
+    case "check-update":
+    case "update-check":
+      checkUpdate();
+      break;
     case "plugin":
       plugin();
       break;
     case "extend":
       await extend();
       break;
+    case "board":
+      await board();
+      break;
     case "help":
     case "--help":
     case "-h":
@@ -144,11 +154,13 @@ Usage:
   ${canonicalCliName} update [--codex-home <path>] [--json]
   ${canonicalCliName} agents [--codex-home <path>] [--force]
   ${canonicalCliName} doctor [--codex-home <path>] [--goal-ready]
+  ${canonicalCliName} check-update [--json]
   ${canonicalCliName} extend [--catalog-url <url-or-path>] [--kind <kind>] [--json]
   ${canonicalCliName} extend <id> [--catalog-url <url-or-path>] [--json]
   ${canonicalCliName} extend install <id> [--catalog-url <url-or-path>] [--dry-run] [--force] [--json]
   ${canonicalCliName} extend install --all [--catalog-url <url-or-path>] [--dry-run] [--force] [--json]
   ${canonicalCliName} extend doctor [<id>] [--codex-home <path>] [--json]
+  ${canonicalCliName} board <docs/goals/slug> [--catalog-url <url-or-path>] [--host <host>] [--port <port>] [--once] [--json]
 
 Default:
   ${canonicalCliName}  Installs and enables the native Codex plugin.
@@ -335,6 +347,46 @@ function doctor() {
   process.exit(installOk && goalReadyOk ? 0 : 1);
 }
 
+function checkUpdate() {
+  const report = updateReport();
+
+  if (hasFlag("--json")) {
+    printJson(report);
+    return;
+  }
+
+  if (report.check_status !== "ok") {
+    console.log(`GoalBuddy update check unavailable: ${report.error}`);
+  } else if (report.update_available) {
+    console.log(`GoalBuddy ${report.latest_version} is available; installed version is ${report.current_version}.`);
+    console.log(`Update with: ${report.update_command}`);
+  } else {
+    console.log(`GoalBuddy is up to date (${report.current_version}).`);
+  }
+}
+
+function updateReport() {
+  const report = {
+    package: packageInfo.name,
+    current_version: normalizeVersion(packageInfo.version),
+    latest_version: null,
+    update_available: false,
+    check_status: "unknown",
+    update_command: `npx ${canonicalCliName}`,
+  };
+
+  try {
+    report.latest_version = latestPublishedVersion();
+    report.update_available = compareVersions(report.current_version, report.latest_version) < 0;
+    report.check_status = "ok";
+  } catch (error) {
+    report.check_status = "unavailable";
+    report.error = error.message;
+  }
+
+  return report;
+}
+
 function plugin() {
   const subcommand = positional(1) || "";
   switch (subcommand) {
@@ -528,6 +580,56 @@ async function extend() {
   }
 }
 
+async function board() {
+  const goal = optionValue("--goal") || positional(1);
+  if (!goal) {
+    console.error(`Missing goal directory. Usage: ${canonicalCliName} board docs/goals/<slug>`);
+    process.exit(2);
+  }
+
+  const script = await ensureLocalBoardExtension();
+  const scriptArgs = [script, "--goal", goal];
+  for (const option of ["--host", "--port"]) {
+    const value = optionValue(option);
+    if (value) scriptArgs.push(option, value);
+  }
+  if (hasFlag("--once")) scriptArgs.push("--once");
+  if (hasFlag("--json")) scriptArgs.push("--json");
+
+  const capture = hasFlag("--once") || hasFlag("--json");
+  const result = spawnSync(process.execPath, scriptArgs, {
+    cwd: packageRoot,
+    encoding: "utf8",
+    env: process.env,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+
+  if (capture) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+async function ensureLocalBoardExtension() {
+  const id = "local-goal-board";
+  const script = join(extensionTarget(id), "scripts", "local-goal-board.mjs");
+  if (existsSync(script)) return script;
+
+  const catalog = await loadCatalog();
+  const extension = catalog.extensions.find((candidate) => candidate.id === id);
+  if (!extension) {
+    throw new Error(`Extension ${id} is not available in ${catalog.url}.`);
+  }
+
+  await installCatalogExtension(catalog, extension);
+  if (!existsSync(script)) {
+    throw new Error(`Extension ${id} installed, but script is missing: ${script}`);
+  }
+  return script;
+}
+
 function extendUsage() {
   console.log(`${canonicalProductName} Extend
 
@@ -1129,9 +1231,39 @@ function assertSkillInstalledForExtensionInstall() {
   }
 }
 
+function latestPublishedVersion() {
+  if (process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION) {
+    return normalizeVersion(process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION);
+  }
+
+  const result = spawnSync("npm", ["view", packageInfo.name, "version"], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    timeout: 5000,
+    env: {
+      ...process.env,
+      npm_config_update_notifier: "false",
+    },
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    throw new Error(output || `npm view exited with status ${result.status}`);
+  }
+
+  return normalizeVersion(result.stdout);
+}
+
+function normalizeVersion(value) {
+  const match = String(value).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) throw new Error(`Unsupported version: ${value}`);
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
 function compareVersions(left, right) {
-  const leftParts = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const rightParts = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const leftParts = normalizeVersion(left).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = normalizeVersion(right).split(".").map((part) => Number.parseInt(part, 10) || 0);
   const length = Math.max(leftParts.length, rightParts.length);
   for (let index = 0; index < length; index += 1) {
     const diff = (leftParts[index] || 0) - (rightParts[index] || 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Turn open-ended Codex goals into a GoalBuddy Scout/Judge/Worker board with receipts, verification, and optional extensions.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Turn broad Codex work into verified GoalBuddy boards with Scout, Judge, Worker, receipts, and optional extensions.",
   "author": {
     "name": "tolibear",

package/plugins/goalbuddy/README.md

@@ -15,6 +15,7 @@ From the repo root:
 ```bash
 npm run check
 npx goalbuddy doctor
+npx goalbuddy check-update
 ```
 
 ## Native Codex Install

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

@@ -28,6 +28,7 @@ During a `$goal-prep` turn, do not perform the user's requested work, even if th
 
 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`, and `docs/goals/<slug>/notes/`;
 - optionally run the GoalBuddy board checker against that `state.yaml`;
@@ -37,6 +38,22 @@ Allowed `$goal-prep` actions:
 
 If the prompt names another skill or tool, such as "use the taste skill", "refresh the taste skill", "look at this repo", "use browser", or "generate assets", record that requirement in the charter and seed tasks. Do not load that skill, browse that repo, or generate those assets during `$goal-prep`.
 
+## Update Check
+
+At the start of a `$goal-prep` turn, check whether GoalBuddy itself is stale. Run the bundled checker from the installed skill directory when available:
+
+```bash
+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
+```
+
+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.
+
 ## Intake Compiler
 
 Before creating, repairing, or running a board, privately translate the user's input into a Goal Intake. The input may be vague, specific, or detailed with an existing plan. Do not dump the intake to the user unless they ask for it.
@@ -131,6 +148,7 @@ When invoked directly, run intake first. For vague, strategic, improvement-orien
 
 Do:
 
+- check for a newer GoalBuddy version once at the start and mention it without blocking;
 - clarify or infer the goal title and slug;
 - run the Intake Compiler;
 - ask diagnostic intake questions when clarity would materially improve the board;
@@ -409,6 +427,25 @@ 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.
 
+## 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.
+
+The PM may create a board task to prepare a repo-native follow-up. If the user has already approved publishing and the repo/auth state supports it, the PM may create an issue or PR directly and record the link in the receipt. Otherwise, ask the operator one concise question before creating the external artifact:
+
+```markdown
+I found [problem or suggestion].
+
+Should I:
+1. Create an issue in this repo for it? (Recommended) - [why]
+2. Prepare a PR for the fix/suggestion - [when this is better]
+3. Keep it only in the GoalBuddy board for now - [tradeoff]
+```
+
+Use an issue for follow-up work, unclear scope, missing approval, or suggestions that need discussion. Use a PR when the fix is already implemented or safely implementable within the current approved scope. If neither is appropriate, propose a different path and record the decision in `state.yaml`.
+
+External issues and PRs are supporting artifacts, not board truth. `state.yaml` remains authoritative, and every issue/PR creation or decision must be reflected in a PM, Worker, or Judge receipt.
+
 ## Continuation Rule
 
 After a task completes, immediately write its receipt and select the next active task unless:

package/plugins/goalbuddy/skills/goalbuddy/scripts/check-update.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageName = "goalbuddy";
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+
+const report = {
+  package: packageName,
+  current_version: findCurrentVersion(),
+  latest_version: null,
+  update_available: false,
+  check_status: "unknown",
+  update_command: "npx goalbuddy",
+};
+
+try {
+  report.latest_version = latestPublishedVersion();
+  report.update_available = compareVersions(report.current_version, report.latest_version) < 0;
+  report.check_status = "ok";
+} catch (error) {
+  report.check_status = "unavailable";
+  report.error = error.message;
+}
+
+if (args.includes("--json")) {
+  console.log(JSON.stringify(report, null, 2));
+} else if (report.check_status !== "ok") {
+  console.log(`GoalBuddy update check unavailable: ${report.error}`);
+} else if (report.update_available) {
+  console.log(`GoalBuddy ${report.latest_version} is available; installed version is ${report.current_version}.`);
+  console.log(`Update with: ${report.update_command}`);
+} else {
+  console.log(`GoalBuddy is up to date (${report.current_version}).`);
+}
+
+function findCurrentVersion() {
+  const candidates = [
+    join(scriptDir, "..", ".goalbuddy-install.json"),
+    join(scriptDir, "..", "..", "..", ".codex-plugin", "plugin.json"),
+    join(scriptDir, "..", "..", "package.json"),
+  ];
+
+  for (const path of candidates) {
+    const data = readJson(path);
+    const version = data?.package_version || data?.version;
+    if (version) return normalizeVersion(version);
+  }
+
+  return "0.0.0";
+}
+
+function latestPublishedVersion() {
+  if (process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION) {
+    return normalizeVersion(process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION);
+  }
+
+  const result = spawnSync("npm", ["view", packageName, "version"], {
+    cwd: resolve(scriptDir, ".."),
+    encoding: "utf8",
+    timeout: 5000,
+    env: {
+      ...process.env,
+      npm_config_update_notifier: "false",
+    },
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    throw new Error(output || `npm view exited with status ${result.status}`);
+  }
+
+  return normalizeVersion(result.stdout);
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeVersion(value) {
+  const match = String(value).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) throw new Error(`Unsupported version: ${value}`);
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+function compareVersions(left, right) {
+  const leftParts = normalizeVersion(left).split(".").map(Number);
+  const rightParts = normalizeVersion(right).split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}

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

@@ -61,11 +61,15 @@ On every `/goal` continuation:
 
 1. Read this charter.
 2. Read `state.yaml`.
-3. Re-check the intake: original request, input shape, authority, proof, blind spots, existing plan facts, and likely misfire.
-4. Work only on the active board task.
-5. Assign Scout, Judge, Worker, or PM according to the task.
-6. Write a compact task receipt.
-7. Update the board.
-8. If Judge selected a safe Worker task with `allowed_files`, `verify`, and `stop_if`, activate it and continue unless blocked.
-9. Treat a slice audit as a checkpoint, not completion, unless it explicitly proves the full original outcome is complete.
-10. Finish only with a Judge/PM audit receipt that maps receipts and verification back to the original user outcome and records `full_outcome_complete: true`.
+3. Run the bundled GoalBuddy update checker when available and mention a newer version without blocking.
+4. Re-check the intake: original request, input shape, authority, proof, blind spots, existing plan facts, and likely misfire.
+5. Work only on the active board task.
+6. Assign Scout, Judge, Worker, or PM according to the task.
+7. Write a compact task receipt.
+8. Update the board.
+9. If Judge selected a safe Worker task with `allowed_files`, `verify`, and `stop_if`, activate it and continue unless blocked.
+10. If a problem, suggestion, or follow-up should become a repo artifact, create an approved issue/PR or ask the operator whether to create one.
+11. Treat a slice audit as a checkpoint, not completion, unless it explicitly proves the full original outcome is complete.
+12. Finish only with a Judge/PM audit receipt that maps receipts and verification back to the original user outcome and records `full_outcome_complete: true`.
+
+Issue and PR handoffs are supporting artifacts. `state.yaml` remains authoritative, and every external artifact decision must be recorded in a task receipt.