opencode-goal-mode 0.3.0 → 0.3.2

package/ARCHITECTURE.md

@@ -170,7 +170,9 @@ hooks still load.
 `{ tui }` module, mutually exclusive with `{ server }`). It registers a
 `sidebar_content` slot via `api.slots.register({ slots: { sidebar_content } })`
 and renders, in the configured colour (`#FFD700` by default), the short goal
-label plus a `passing/total gates · dirty/ready` line.
+label plus a `passing/total gates · dirty/ready` line. It renders
+unconditionally: when a task is running with no goal set, it shows a muted grey
+`No goal` (`sidebarView` returns `{ hasGoal: false }`) rather than a blank slot.
 
 It is *paired* with the server plugin only through the persisted state file:
 `sidebar-data.js` recomputes the same `stateBaseDir`/`projectKey` path the guard
@@ -182,6 +184,12 @@ error degrades to rendering nothing — it can never break the TUI. The server p
 also emits review-verdict and completion-unlock toasts (`toastOnReview`) so review
 progress is visible even without the banner.
 
+The JSX renderer is verified headlessly with `@opentui/solid`'s `testRender` in
+`tools/visual-test/sidebar-visual.jsx` (`npm run test:visual`, needs Bun + the
+OpenTUI stack): it asserts the rendered text, the exact foreground colours, and
+the bold attribute for goal / "No goal" / ready states. That tool is excluded from
+the npm package and from `node --test`/CI.
+
 ## Configuration
 
 `config.js` merges, in increasing precedence: built-in defaults, environment

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.3.2
+
+- Only the `goal` agent is user-selectable. The structural validator now requires
+  every other agent to be `mode: subagent` (no `all`/extra `primary`), so the
+  specialist reviewers can only be invoked by the Goal agent via the task tool,
+  never picked by the user.
+- Friendlier subagent names in the TUI: review-verdict toasts now read
+  "Security Reviewer → PASS" / "API Reviewer → PASS" instead of raw hyphenated ids
+  (`prettyAgentName` drops the `goal-` prefix, de-hyphenates, keeps acronyms).
+- Release pipeline: a single `vX.Y.Z` tag push now publishes to npm AND creates
+  the matching GitHub Release (versions stay in sync). `publish:check` fails the
+  release if the tag does not match `package.json` or the version already exists.
+- README: npm-first install instructions and a documented release flow.
+
+## v0.3.1
+
+- Sidebar: when a task is running but no goal is set, show a clean grey `No goal`
+  (nothing else) instead of a blank/absent banner. New `sidebarMutedColor` option
+  (`GOAL_GUARD_SIDEBAR_MUTED_COLOR`, default `#808080`).
+- `summary.sidebarView` now always returns a model (`{ hasGoal: false }` vs
+  `{ hasGoal: true, … }`) so the sidebar renders unconditionally.
+- Add a headless visual test (`npm run test:visual`, `tools/visual-test/`) that
+  renders the real component with @opentui/solid and asserts text + exact colours
+  + bold attributes across goal / no-goal / ready / custom-colour / truncation /
+  disabled / no-API / resize scenarios. Excluded from the npm package and CI.
+- Hardened the sidebar projection against malformed/partial persisted state.
+
 ## v0.3.0
 
 - Honest benchmarks: add an EXTERNAL corpus of 704 real third-party commands from

package/README.md

@@ -90,7 +90,11 @@ second) — negligible for a per-tool-call guard:
 ## What it adds
 
 - A primary `goal` agent that owns implementation but delegates research,
-  discovery, verification planning, and reviews to subagents.
+  discovery, verification planning, and reviews to subagents. **`goal` is the only
+  user-selectable agent** — every specialist (security, diff, verifier, …) is a
+  `mode: subagent` that the Goal agent invokes via the task tool; the user never
+  picks one directly. They surface with friendly names (e.g. "Security Reviewer",
+  "API Reviewer") rather than raw ids.
 - Strict review gates for prompt compliance, diff review, verification, security,
   UX, operations, data, API, performance, tests, docs, quality, and final audit.
 - Slash commands: `/goal`, `/goal-contract`, `/goal-review`,
@@ -111,8 +115,9 @@ second) — negligible for a per-tool-call guard:
     `goal_reviewer_memory`, `goal_status`, `goal_reset`.
   - **Live state injection** into the system prompt so the model always knows
     what the guard requires.
-  - **TUI toasts**: a toast on each review verdict (PASS/FAIL) and a single
-    "completion unlocked" toast the moment the last required gate clears.
+  - **TUI toasts**: a toast on each review verdict (PASS/FAIL), with the
+    reviewer's friendly name, and a single "completion unlocked" toast the moment
+    the last required gate clears.
 - An **experimental** companion TUI plugin (`plugins/goal-sidebar.js`) that shows
   the active goal as a shining-yellow banner in the sidebar with a compact gate
   status line. See [TUI integration](#tui-integration).
@@ -127,38 +132,53 @@ enforcement and writes its state to disk, and an experimental TUI plugin
 
 - **Sidebar goal banner (experimental).** The current goal renders in shining
   yellow in the sidebar (`sidebar_content` slot), with a `passing/total gates ·
-  dirty/ready` status line, and updates as reviews land. It requires a
-  TUI-plugin-capable OpenCode (one exposing `api.slots.register`); on any older
-  runtime it silently no-ops, so it can never break your TUI. Set
-  `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable, or
-  `sidebarColor` to recolour it. Because no local environment can run OpenCode's
-  TUI runtime, this banner is shipped best-effort and should be verified in your
-  own TUI.
+  dirty/ready` status line, and updates as reviews land. When a task is running
+  but **no goal is set**, it shows a clean grey `No goal` and nothing else. It
+  requires a TUI-plugin-capable OpenCode (one exposing `api.slots.register`); on
+  any older runtime it silently no-ops, so it can never break your TUI. Set
+  `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable,
+  `sidebarColor` to recolour the goal, or `sidebarMutedColor` for the "No goal"
+  line. It is rendered-and-asserted headlessly by the
+  [visual test](tools/visual-test/README.md) (`npm run test:visual`); still worth
+  a glance in your own TUI.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).
 
-## Install globally
+## Install
+
+### From npm (recommended)
 
 ```bash
-npm ci
-npm run validate
-npm run install:global
+npm install -g opencode-goal-mode
+opencode-goal-mode-install --global    # installs into ~/.config/opencode
 ```
 
-Restart OpenCode after installation. OpenCode loads agents, commands, and
-plugins at startup.
+Then restart OpenCode (it loads agents, commands, and plugins at startup). In the
+agent picker you will see **only the `goal` agent** — the specialist reviewers are
+subagents the Goal agent drives for you; they are never selectable by the user.
 
-## Install into one project
+Install into a single project instead of globally:
 
 ```bash
+npm install -D opencode-goal-mode
+npx opencode-goal-mode-install         # writes to ./.opencode
+```
+
+Upgrade later by re-running the same install command after `npm install -g
+opencode-goal-mode@latest`; the installer replaces only the files it owns and
+leaves your local edits alone (see [Installer options](#installer-options)).
+
+### From source
+
+```bash
+git clone https://github.com/devinoldenburg/opencode-goal-mode
+cd opencode-goal-mode
 npm ci
 npm run validate
-npm run install:local
+npm run install:global                 # or: npm run install:local
 ```
 
-This writes to `./.opencode` in the current project.
-
 ## Installer options
 
 ```bash
@@ -202,6 +222,7 @@ Or via environment variables (`GOAL_GUARD_*`):
 | `toastOnReview` / `GOAL_GUARD_TOAST_ON_REVIEW` | `true` | Toast on each review verdict and when completion unlocks. |
 | `sidebarBanner` / `GOAL_GUARD_SIDEBAR_BANNER` | `true` | Show the experimental yellow goal banner in the TUI sidebar. |
 | `sidebarColor` / `GOAL_GUARD_SIDEBAR_COLOR` | `#FFD700` | Foreground colour of the sidebar goal banner. |
+| `sidebarMutedColor` / `GOAL_GUARD_SIDEBAR_MUTED_COLOR` | `#808080` | Colour of the muted "No goal" line when no goal is set. |
 
 ## Custom tools
 
@@ -250,32 +271,34 @@ keeps read-only inspection from dirtying the session, preserves goal state durin
 compaction and across restarts, and blocks premature `Goal Completed` responses
 when review gates are missing or stale.
 
-## npm publishing
+## Releasing
 
-Install from npm after the first publish:
+Releases are fully automated and **version-synced**: one pushed tag publishes to
+npm *and* creates the matching GitHub Release. The pipeline lives in
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) (Node 24).
 
 ```bash
-npm install -g opencode-goal-mode
-opencode-goal-mode-install --global
+npm version patch        # bumps package.json + package-lock.json and creates the vX.Y.Z tag
+git push --follow-tags   # pushes main + the tag → the Release workflow runs
 ```
 
-Publishing is handled by `.github/workflows/publish.yml`, which runs on Node 24
-and publishes with the `NPM_TOKEN` repository secret. The workflow validates the
-package, checks the tag matches `package.json`, verifies the version is not
-already on npm, then publishes. Manual workflow dispatch defaults to
-`npm publish --dry-run`.
+On a `vX.Y.Z` tag push the workflow:
 
-Release flow for a new version:
+1. installs and runs the full CI gate (`npm run ci` — tests, audit, structural
+   validation, `npm pack --dry-run`);
+2. runs `npm run publish:check`, which **fails if the tag does not match
+   `package.json`** or if that version already exists on npm;
+3. publishes with `npm publish --access public` using the `NPM_TOKEN` repository
+   secret;
+4. creates the GitHub Release for the tag with auto-generated notes.
 
-```bash
-npm version patch
-git push --follow-tags
-```
+So the git tag, the `package.json` version, the npm version, and the GitHub
+Release version are always identical. A manual `workflow_dispatch` is available
+and defaults to a safe `npm publish --dry-run`.
 
-For a version that is already bumped and reviewed, commit the current tree, tag
-the reviewed version (for example `v0.2.4`), push the branch and tag, then create
-the GitHub Release. Ensure `NPM_TOKEN` has npm publish rights before publishing
-the release.
+**One-time setup:** add a publish-scoped npm token as the `NPM_TOKEN` repository
+secret (`gh secret set NPM_TOKEN`). Treat that token as sensitive — never commit
+it.
 
 ## Goal Completion Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {
@@ -31,6 +31,7 @@
     "test:unit": "node --test tests/state.test.mjs tests/gates.test.mjs tests/verdicts.test.mjs tests/config.test.mjs tests/persistence.test.mjs",
     "test:agents": "node --test tests/agents.test.mjs tests/commands.test.mjs",
     "test:install": "node --test tests/install.test.mjs",
+    "test:visual": "bun tools/visual-test/sidebar-visual.jsx",
     "bench": "node benchmarks/run.mjs",
     "bench:external": "node benchmarks/external.mjs",
     "bench:corpus": "node benchmarks/build-external-corpus.mjs",

package/plugins/goal-guard/agents.js

@@ -130,3 +130,23 @@ export const CONTEXTUAL_GATES = Object.freeze({
 
 /** The reviewer that, when it returns a verdict, closes one review cycle. */
 export const CYCLE_CLOSING_AGENT = "goal-final-auditor";
+
+/** Acronyms that should stay upper-case in display names. */
+const ACRONYMS = new Set(["api", "ux", "ui", "sql", "ops", "qa"]);
+
+/**
+ * Human-friendly display name for an agent id: drops the `goal-` namespace
+ * prefix, turns hyphens into spaces, Title-Cases words, and keeps known acronyms
+ * upper-case. e.g. "goal-security-reviewer" → "Security Reviewer",
+ * "goal-api-reviewer" → "API Reviewer", "goal-final-auditor" → "Final Auditor".
+ */
+export function prettyAgentName(id) {
+  const raw = String(id || "").trim();
+  if (!raw) return "";
+  return raw
+    .replace(/^goal-/, "")
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+}

package/plugins/goal-guard/config.js

@@ -32,6 +32,8 @@ export const DEFAULT_CONFIG = Object.freeze({
   sidebarBanner: true,
   /** Foreground colour (hex) for the sidebar goal banner. */
   sidebarColor: "#FFD700",
+  /** Foreground colour (hex) for the muted "No goal" sidebar line. */
+  sidebarMutedColor: "#808080",
   /** Phrase that, at the start of an assistant message, claims completion. */
   completionMarker: "Goal Completed",
   /** Replacement marker when completion is blocked. */
@@ -68,6 +70,7 @@ function fromEnv(env) {
     GOAL_GUARD_TOAST_ON_REVIEW: ["toastOnReview", coerceBool],
     GOAL_GUARD_SIDEBAR_BANNER: ["sidebarBanner", coerceBool],
     GOAL_GUARD_SIDEBAR_COLOR: ["sidebarColor", (v) => (v == null ? undefined : String(v))],
+    GOAL_GUARD_SIDEBAR_MUTED_COLOR: ["sidebarMutedColor", (v) => (v == null ? undefined : String(v))],
   };
   for (const [key, [field, coerce]] of Object.entries(map)) {
     if (env[key] !== undefined) out[field] = coerce(env[key], DEFAULT_CONFIG[field]);

package/plugins/goal-guard/sidebar-data.js

@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stateBaseDir, projectKey } from "./persistence.js";
 import { DEFAULT_CONFIG } from "./config.js";
-import { sidebarView } from "./summary.js";
+import { sidebarView, NO_GOAL } from "./summary.js";
 
 /** Absolute path of the guard's state file for a given worktree. */
 export function sidebarStateFile(worktree, env = process.env) {
@@ -49,8 +49,10 @@ export function pickSession(snapshot, sessionId) {
 }
 
 /**
- * Build the sidebar banner model for a worktree, or null if there is nothing to
- * show. Returns { goal, status, allowed, … } (see summary.sidebarView).
+ * Build the sidebar banner model for a worktree. ALWAYS returns an object so the
+ * sidebar renders unconditionally: `{ hasGoal: false }` when there is no state,
+ * no active session, or no goal (render a muted "No goal"); otherwise
+ * `{ hasGoal: true, goal, status, … }` (see summary.sidebarView).
  *
  * @param {object} opts
  * @param {string} opts.worktree   Project worktree root (same key the guard uses).
@@ -63,9 +65,9 @@ export function readSidebarModel({ worktree, sessionId, config = DEFAULT_CONFIG,
   try {
     snapshot = JSON.parse(readFileSync(sidebarStateFile(worktree, env), "utf8"));
   } catch {
-    return null; // no state yet, or unreadable — show nothing.
+    return NO_GOAL; // no state yet, or unreadable.
   }
   const record = pickSession(snapshot, sessionId);
-  if (!record) return null;
+  if (!record) return NO_GOAL;
   return sidebarView(record, config);
 }

package/plugins/goal-guard/summary.js

@@ -21,21 +21,25 @@ export function shortGoalLabel(state, max = 80) {
   return `${base.slice(0, max - 1).trimEnd()}…`;
 }
 
+/** Sentinel for "a task is running but no goal is set" — the sidebar shows a muted "No goal". */
+export const NO_GOAL = Object.freeze({ hasGoal: false });
+
 /**
- * Compact projection for the TUI sidebar banner: the short goal label, a
- * one-line gate/dirty status, and whether completion is currently allowed.
- * Returns null when there is no active goal worth showing.
+ * Compact projection for the TUI sidebar banner. ALWAYS returns an object so the
+ * sidebar can render unconditionally:
+ *   - `{ hasGoal: false }` when no active goal is set (render a muted "No goal").
+ *   - `{ hasGoal: true, goal, status, … }` when a goal is active (render in colour).
  */
 export function sidebarView(state, config) {
-  if (!state || !state.active) return null;
+  if (!state || !state.active) return NO_GOAL;
   const goal = shortGoalLabel(state);
-  if (!goal) return null;
+  if (!goal) return NO_GOAL;
   const required = requiredGates(state, config);
   const missing = missingGates(state, config);
   const passing = required.length - missing.length;
   const allowed = required.length > 0 && missing.length === 0 && !state.dirty;
   const status = `${passing}/${required.length} gates` + (state.dirty ? " · dirty" : "") + (allowed ? " · ready" : "");
-  return { goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
+  return { hasGoal: true, goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
 }
 
 export function summarizeState(state, config) {

package/plugins/goal-guard.js

@@ -23,7 +23,7 @@ import { createStore, createState } from "./goal-guard/state.js";
 import { createPersistence } from "./goal-guard/persistence.js";
 import { createLogger } from "./goal-guard/logger.js";
 import { analyzeCommand, looksLikeDestructiveBash, looksLikeMutatingBash, isVerification } from "./goal-guard/shell.js";
-import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT } from "./goal-guard/agents.js";
+import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT, prettyAgentName } from "./goal-guard/agents.js";
 import { textOf, parseVerdict, recordVerdict } from "./goal-guard/verdicts.js";
 import { completionAllowed, missingGates, refreshStickyGates } from "./goal-guard/gates.js";
 import { evaluateCompletionClaim } from "./goal-guard/completion.js";
@@ -210,9 +210,9 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
         // Surface review progress in the TUI: a toast per recorded verdict, and a
         // single celebratory toast the moment the last required gate clears.
         if (recordedAgent && recordedVerdict && config.toastOnReview) {
-          logger.toast(`Goal Guard: ${recordedAgent} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
+          logger.toast(`${prettyAgentName(recordedAgent)} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
           if (!wasAllowed && completionAllowed(state, config)) {
-            logger.toast("Goal Guard: all required gates passed — completion unlocked", "success");
+            logger.toast("All required gates passed — completion unlocked", "success");
           }
         }
         persist();

package/plugins/goal-sidebar.js

@@ -28,10 +28,11 @@
  */
 
 import { createSignal, onCleanup, Show } from "solid-js";
-import { sidebarView } from "./goal-guard/summary.js";
+import { sidebarView, NO_GOAL } from "./goal-guard/summary.js";
 import { DEFAULT_CONFIG } from "./goal-guard/config.js";
 
 const DEFAULT_COLOR = "#FFD700"; // shining yellow
+const DEFAULT_MUTED = "#808080"; // clean grey for "No goal"
 const POLL_MS = 1500;
 
 function resolveOptions(options, env) {
@@ -41,7 +42,8 @@ function resolveOptions(options, env) {
   const disabled =
     enabledOpt === false || enabledEnv === "0" || enabledEnv === "false" || enabledEnv === "off";
   const color = options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR;
-  return { enabled: !disabled, color };
+  const muted = options?.sidebarMutedColor || e.GOAL_GUARD_SIDEBAR_MUTED_COLOR || DEFAULT_MUTED;
+  return { enabled: !disabled, color, muted };
 }
 
 /**
@@ -82,14 +84,14 @@ function pickSession(snapshot, sessionId) {
 }
 
 function readModel(worktree, sessionId) {
-  const snapshot = readSnapshot(worktree);
-  if (!snapshot) return null;
-  const record = pickSession(snapshot, sessionId);
-  if (!record) return null;
   try {
+    const snapshot = readSnapshot(worktree);
+    if (!snapshot) return NO_GOAL;
+    const record = pickSession(snapshot, sessionId);
+    if (!record) return NO_GOAL;
     return sidebarView(record, DEFAULT_CONFIG);
   } catch {
-    return null;
+    return NO_GOAL;
   }
 }
 
@@ -98,7 +100,7 @@ export const id = "goal-mode-sidebar";
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
 export const tui = async (api, options) => {
   try {
-    const { enabled, color } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    const { enabled, color, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
     if (!enabled) return;
     if (!api?.slots?.register) return; // runtime without the slot API → no-op.
 
@@ -110,25 +112,26 @@ export const tui = async (api, options) => {
         sidebar_content(_ctx, props) {
           const read = () => {
             try {
-              return readModel(worktree, props?.session_id);
+              return readModel(worktree, props?.session_id) || NO_GOAL;
             } catch {
-              return null;
+              return NO_GOAL;
             }
           };
           const [model, setModel] = createSignal(read());
           const timer = setInterval(() => setModel(read()), POLL_MS);
           onCleanup(() => clearInterval(timer));
+          // Always render: a muted "No goal" when none is set, the goal in colour otherwise.
           return (
-            <Show when={model()}>
-              <box flexDirection="column">
+            <box flexDirection="column">
+              <Show when={model().hasGoal} fallback={<text fg={muted}>No goal</text>}>
                 <text fg={color}>
                   {"◆ "}
                   <b>GOAL</b>
                   {`  ${model().goal}`}
                 </text>
                 <text fg={color}>{model().status}</text>
-              </box>
-            </Show>
+              </Show>
+            </box>
           );
         },
       },