goalbuddy 0.3.2 → 0.3.6

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <a href="https://goalbuddy.dev">
-    <img src="internal/assets/goalbuddy-v0.3.0-release.png" alt="GoalBuddy v0.3.0 release: Claude Code support, npx goalbuddy installs into Codex and Claude Code, and npx goalbuddy update keeps both current." width="100%">
+    <img src="internal/assets/goalbuddy-v0.3.5-release.png" alt="GoalBuddy v0.3.5 release: Subgoals, parallel agents, and dark mode." width="100%">
   </a>
 </p>
 
@@ -16,7 +16,7 @@
   <a href="https://goalbuddy.dev"><img alt="goalbuddy.dev" src="https://img.shields.io/badge/site-goalbuddy.dev-684cff?style=flat-square"></a>
 </p>
 
-GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks.
+GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks, especially when the work branches into subgoals, parallel agents, and long-running verification.
 
 It gives `/goal` a small local workspace: a charter, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
 
@@ -44,6 +44,25 @@ In Claude Code, use:
 
 Goal Prep creates the board and prints the exact `/goal` command to run next. That is the whole path.
 
+## Codex Install Model
+
+For Codex, the canonical install is the native plugin plus bundled agents:
+
+```text
+~/.codex/plugins/cache/goalbuddy/goalbuddy/<version>/
+~/.codex/agents/goal_judge.toml
+~/.codex/agents/goal_scout.toml
+~/.codex/agents/goal_worker.toml
+```
+
+The Codex plugin bundles `$goal-prep`; a clean Codex install should not need personal `~/.codex/skills/goalbuddy` or `~/.codex/skills/goal-maker` folders. Native Codex `/goal` is a separate OpenAI-gated feature. GoalBuddy prepares local boards and handoff prompts for it, but it does not enable or replace native `/goal`.
+
+To verify a Codex install:
+
+```bash
+npx goalbuddy doctor --target codex --goal-ready
+```
+
 ## What It Creates
 
 ```text
@@ -51,6 +70,7 @@ docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  subgoals/        # optional depth-1 child boards
 ```
 
 `goal.md` says what you want.
@@ -59,6 +79,8 @@ docs/goals/<your-goal>/
 
 `notes/` keeps longer findings out of the main thread.
 
+`subgoals/` holds optional child boards when one parent task needs a bounded branch of work.
+
 ## How It Thinks
 
 ```text
@@ -67,12 +89,36 @@ rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verif
 
 Scout maps the repo.
 
-Judge chooses the next bounded slice.
+Judge chooses the largest safe useful slice.
 
-Worker changes code and leaves a receipt.
+Worker completes the whole assigned slice and leaves a receipt.
 
 `/goal` keeps the loop honest until the original goal is actually done.
 
+## Slice Sizing
+
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+
+GoalBuddy should not optimize for tiny safe tasks. It should optimize for the largest safe useful slice: a working screen, working API path, data pipeline step, backend vertical slice, real bug fix, or milestone review. The board warns when it sees safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome.
+
+## Subgoals, Parallel Agents, and Dark Mode
+
+GoalBuddy keeps the model small:
+
+- `state.yaml` is the source of truth.
+- A board is a view of one `state.yaml`.
+- The local hub is a switchboard for many boards.
+- A subgoal is one depth-1 `state.yaml` linked from a parent task.
+- Settings are viewer preferences, not workflow state.
+
+Use subgoals for bounded child work that belongs to a parent task. Use multiple local boards when parallel agents or separate goal runs are active at the same time. Keep the board open in light or dark mode while the work moves.
+
+## Execution Quality
+
+GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
+
+Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task without dumping the whole state file. The prompt includes a mandatory `required_spawn_agent_type`; Codex PMs should use that exact GoalBuddy agent (`goal_scout`, `goal_worker`, or `goal_judge`) instead of a generic role agent. Use `goalbuddy parallel-plan docs/goals/<slug>` to inspect read-only or disjoint write-scope work that can be handed to native Codex or Claude Code agent flows. The command reports recommendations only; it does not mutate state or spawn agents.
+
 ## Update
 
 When a new GoalBuddy version ships:
@@ -85,7 +131,11 @@ That updates both Codex and Claude Code.
 
 ## Live Boards
 
-GoalBuddy can open a local board while the work is running, so you can see the plan, active task, receipts, and verification status without digging through the chat.
+GoalBuddy can open a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
+
+Multiple local boards reuse one readable `goalbuddy.localhost` hub with an in-header board switcher. When sharing a board in chat or docs, use a real Markdown link such as `[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)` so the URL is clickable. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.
+
+See [GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode](RELEASE-0.3.5.md) for the release notes.
 
 <p align="center">
   <img src="internal/assets/goalbuddy-live-board.jpg" alt="GoalBuddy local live board open next to Codex while Scout, Judge, and Worker tasks populate." width="100%">

package/RELEASE-0.3.5.md

@@ -0,0 +1,324 @@
+# GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode
+
+Release date: 2026-05-12
+
+![GoalBuddy v0.3.5 release: Subgoals, parallel agents, and dark mode.](https://raw.githubusercontent.com/tolibear/goalbuddy/v0.3.5/internal/assets/goalbuddy-v0.3.5-release.png)
+
+This is the release where GoalBuddy starts feeling less like a single board and more like a calm local workspace for serious agent work.
+
+0.3.5 adds three big things:
+
+- **Subgoals**: depth-1 child boards for branching work.
+- **Parallel agents**: safe, explicit surfaces for parallel Scout, Judge, and bounded Worker handoffs.
+- **Dark mode**: a cleaner local board that can stay open all day without punishing your eyes.
+
+Under the hood, this release also hardens GoalBuddy's execution model: stricter agent contracts, deterministic task prompts, conservative parallel planning, stronger checker rules, and safer child-board rendering.
+
+Update with:
+
+```bash
+npx goalbuddy update
+```
+
+## The Headline
+
+GoalBuddy still has one simple job: keep long `/goal` runs oriented until the real outcome is done.
+
+0.3.5 makes that loop much easier to run when the work branches, when more than one agent is helping, or when you want a live board open beside Codex or Claude Code.
+
+The model stays intentionally small:
+
+- `goal.md` is the charter.
+- `state.yaml` is the ledger.
+- A board is a view of one `state.yaml`.
+- A subgoal is one depth-1 child `state.yaml` linked from a parent task.
+- The local hub is navigation, not workflow truth.
+- Viewer settings are preferences, not state.
+
+## Subgoals
+
+Subgoals give GoalBuddy a clean way to branch without turning into project-management software.
+
+A parent task can now link to a child board under `subgoals/`:
+
+```yaml
+subgoal:
+  status: active
+  path: subgoals/T004-board-view/state.yaml
+  owner: Worker
+  created_from: T004
+  depth: 1
+  rollup_receipt: null
+```
+
+The local board renders that child board inside the parent task detail, so you can open one task and see the focused child workflow underneath it.
+
+What this is good for:
+
+- a parent task that needs a focused implementation branch
+- a verification slice that deserves its own mini-board
+- a Scout/Judge/Worker path that should stay bounded
+- parallel work that needs a visible surface without losing the parent context
+
+What it is not:
+
+- recursive planning
+- nested subgoals
+- a separate project hierarchy
+- a new source of truth
+
+One parent task can have one depth-1 child board. That is the whole trick.
+
+## Parallel Agents
+
+GoalBuddy 0.3.5 is parallel-agent-ready, but deliberately not an automatic scheduler.
+
+That distinction matters.
+
+GoalBuddy now helps you prepare safe parallel work surfaces:
+
+- Scouts are read-only and safe to run in parallel by default.
+- Judges are read-only and safe on separate board decisions.
+- Workers are only safe when they are on separate boards or have provably disjoint `allowed_files`.
+- Ambiguous Worker write scopes fail closed.
+
+Use the new planner:
+
+```bash
+goalbuddy parallel-plan docs/goals/<slug>
+```
+
+It reports active tasks across the parent board and linked child boards:
+
+- board path
+- task id
+- role
+- recommended agent
+- reasoning hint
+- whether it is safe to parallelize
+- why
+- the exact prompt-render command
+
+It does not mutate state. It does not spawn agents. It does not pretend overlap is safe.
+
+That keeps GoalBuddy in the sweet spot: it makes parallel execution easier to see and safer to hand off, while native Codex or Claude Code agent flows still do the actual dispatch.
+
+## Dark Mode
+
+The local board now has real dark mode.
+
+Not "the background changed and half the text disappeared" dark mode. The board, task cards, modals, settings, detail sections, receipt text, and embedded child boards all get readable dark styling.
+
+The board also adds global viewer settings:
+
+- Theme: system, light, dark
+- Density: comfortable, compact
+- Completed column: show, collapse
+- Open boards: last viewed, newest
+- Motion: system, reduce, allow
+
+Settings are local viewer preferences and live at:
+
+```text
+~/.goalbuddy/local-board-settings.json
+```
+
+Tests can override that path with:
+
+```bash
+GOALBUDDY_LOCAL_BOARD_SETTINGS_PATH=/tmp/goalbuddy-settings.json
+```
+
+## The Local Board Got Sharper
+
+The board header now matches the GoalBuddy site style more closely:
+
+- GoalBuddy mark and wordmark
+- green live blip beside the wordmark
+- board selector only when multiple boards are running
+- GitHub stars link that opens in a new window
+- cleaner settings gear
+
+Multiple boards now share one readable local hub:
+
+```text
+http://goalbuddy.localhost:41737/
+```
+
+Each board gets its own path:
+
+```text
+http://goalbuddy.localhost:41737/subgoal-parent-board/
+http://goalbuddy.localhost:41737/local-kanban-board-extension/
+```
+
+Launch another board while the hub is already running and GoalBuddy registers it with the existing local server instead of replacing the first board.
+
+If port `41737` is occupied by something that is not GoalBuddy, the CLI says so clearly.
+
+## Active Work Is Easier To See
+
+Active cards now have a visible in-progress treatment: a subtle moving border that makes the current task obvious at a glance.
+
+The motion respects:
+
+- `prefers-reduced-motion`
+- the board Motion setting
+
+So the board can feel alive without becoming noisy.
+
+## Better Agent Contracts
+
+Scout, Judge, and Worker now have sharper contracts.
+
+Scout:
+
+- read-only
+- compact evidence
+- no edits
+- no task selection
+- receipt-shaped output
+
+Judge:
+
+- read-only
+- phase gates and risky decisions only
+- completion skepticism
+- parallel-safety decisions
+- subgoal approval boundaries
+
+Worker:
+
+- edits only `allowed_files`
+- runs listed verification
+- stops when scope expands
+- returns changed files and verification results
+- treats parallel Worker safety conservatively
+
+This is the durable GoalBuddy model:
+
+```text
+Scout maps. Judge gates. Worker patches. Receipts prove. state.yaml decides.
+```
+
+## Deterministic Prompt Rendering
+
+New command:
+
+```bash
+goalbuddy prompt docs/goals/<slug>
+goalbuddy prompt docs/goals/<slug> --task T004
+goalbuddy prompt --board docs/goals/<slug>/state.yaml --task T004
+```
+
+The renderer emits compact task-specific prompts with:
+
+- board path
+- task id
+- task type
+- objective
+- inputs
+- constraints
+- allowed files
+- verify commands
+- stop conditions
+- reasoning hint
+- recommended agent
+- expected receipt shape
+
+It avoids the bad handoff pattern where a subagent gets the entire state file, chat history assumptions, and too much inherited context.
+
+## Checker And Durability
+
+The checker now understands 0.3.5 branching.
+
+It accepts:
+
+- depth-1 subgoals under the parent goal root
+- child boards with `goal.md`, `state.yaml`, and `notes/`
+- parent tasks linked to valid child boards
+- Worker changed files that match simple `allowed_files` globs
+
+It rejects:
+
+- child paths outside the parent root
+- child paths that do not point to `state.yaml`
+- missing child state files
+- nested child subgoals
+- invalid child board state
+- done Workers with changed files outside scope
+- final completion without the expected verification and audit evidence
+
+The board renderer also fails closed on invalid child paths, so a malformed subgoal cannot make the local board read a `state.yaml` outside the parent goal root.
+
+## Demo
+
+Run the bundled parent/child board:
+
+```bash
+node goalbuddy/extend/local-goal-board/scripts/local-goal-board.mjs \
+  --goal goalbuddy/extend/local-goal-board/examples/subgoal-parent
+```
+
+Then try:
+
+- switch to dark mode from the gear menu
+- open task `T004` to see the embedded child board
+- launch another board and use the header selector
+- run `goalbuddy parallel-plan goalbuddy/extend/local-goal-board/examples/subgoal-parent`
+- run `goalbuddy prompt goalbuddy/extend/local-goal-board/examples/subgoal-parent`
+
+## Tests
+
+0.3.5 adds or expands coverage for:
+
+- parent task subgoal payloads
+- embedded child boards
+- missing child state files
+- outside-root child paths
+- live child-state updates over SSE
+- multi-board hub registration
+- settings persistence and normalization
+- dark-mode readability surfaces
+- prompt rendering
+- read-only parallel planning
+- overlapping Worker write scopes
+- overlapping Worker glob patterns
+- checker rejection for outside-root, missing, and nested subgoals
+- plugin/source mirror consistency
+
+Verified locally with:
+
+```bash
+npm run check
+git diff --check
+npm run publish:check
+```
+
+## Release Boundaries
+
+This release intentionally does not add:
+
+- automatic parallel-agent spawning
+- a parallel Worker scheduler
+- automatic receipt application
+- UI controls for creating or editing subgoals
+- recursive/nested subgoals
+- cloud-hosted board state
+
+The principle is Karpathy-level simple:
+
+```text
+One board owns one state file. A subgoal is one child state file. Parallel work is allowed only when the write boundaries are clear.
+```
+
+That gives GoalBuddy a stronger execution loop without making it heavy.
+
+## Package Notes
+
+This release updates:
+
+- npm package version: `0.3.5`
+- Codex plugin version: `0.3.5`
+- Claude Code plugin version: `0.3.5`
+- mirrored GoalBuddy skill files under `plugins/goalbuddy/skills/goalbuddy/`

package/goalbuddy/SKILL.md

@@ -85,7 +85,7 @@ Recommended options:
 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.
 
-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). 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. Keep the printed URL in the final prep response as a fallback, but do not make the URL the primary experience.
+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.
 
@@ -203,15 +203,31 @@ Planning, Scout findings, Judge decisions, and a queued Worker task are not term
 For execution goals, the default run is continuous:
 
 ```text
-Discover enough evidence, choose a safe implementation slice, implement it, verify it, audit it, then immediately choose and execute the next safe slice until the full original outcome is complete.
+Discover enough evidence, choose the largest reversible local work package, implement it, verify it, review only at risk or phase boundaries, then immediately choose and execute the next work package until the full original outcome is complete.
 ```
 
 If the first `/goal` run reaches a Judge decision that names a safe Worker task with `allowed_files`, `verify`, and `stop_if`, the PM should activate that Worker and continue in the same run unless a stop condition applies.
 
-After a verified Worker slice and audit, do not mark the thread goal complete merely because that slice passed. A slice audit is a checkpoint. For broad automation or product goals, continue by reopening or advancing the board to the next safe Worker task until the full owner outcome is complete.
+After a verified Worker package, do not mark the thread goal complete merely because that package passed. For broad automation or product goals, continue by reopening or advancing the board to the next safe Worker package until the full owner outcome is complete.
 
 Missing owner input, credentials, production access, destructive-operation permission, or policy decisions are blockers for specific tasks, not stopping conditions for the whole goal. When a slice hits one of those blockers, mark that exact task blocked with a receipt, create a safe follow-up or workaround task, and keep doing local, non-destructive work that advances the full outcome.
 
+## Slice Sizing Policy
+
+A good task is the largest safe useful slice.
+
+Small is not the goal. Useful is the goal.
+
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+
+A good Worker task usually produces a working screen, a working API path, a working data pipeline step, a working backend vertical slice, a real bug fix, or a milestone review. A bad Worker task is one more tiny helper, projection function, contract file, read-only proof, or doc note unless that tiny task is truly blocking progress.
+
+Judge picks the largest safe useful next slice. Worker completes the whole assigned slice. Judge reviews the whole slice.
+
+After two tiny tasks in a row, PM or Judge should reorient the board. If a demo milestone is complete, the next task should move toward the next real milestone.
+
+Tiny tasks are allowed when the failure is isolated, the risk is high, the scope is unknown, or the tiny task unlocks a larger slice. Tiny tasks are bad when they keep happening, do not change behavior, only add wrappers/contracts/proof files, or avoid the real milestone.
+
 ## When To Use
 
 Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, already planned, already stale, already red, or likely to need Scout/Judge/Worker delegation.
@@ -267,7 +283,7 @@ What counts as enough for the current tranche?
 Avoid forever goals. A broad goal should define an execution tranche, for example:
 
 ```text
-Discover the highest-leverage local improvements, complete successive safe verified implementation slices, audit each slice against the original user outcome, and keep advancing until the full outcome is complete.
+Discover the highest-leverage local improvements, complete successive safe verified work packages, review only at risk or phase boundaries, and keep advancing until the full outcome is complete.
 ```
 
 ## Board
@@ -390,8 +406,9 @@ Judge receipt:
 ```yaml
 receipt:
   result: done
-  decision: "Do router coverage first; defer auth flake because it is not reproducible locally."
-  next_allowed_task: T004
+  decision: "approved"
+  full_outcome_complete: false
+  rationale: "Router coverage is verified; continue with the next PM-selected work package."
   blocked_tasks:
     - T005
 ```
@@ -440,7 +457,7 @@ Blocked tasks do not necessarily block the goal. The PM should keep doing safe l
 
 - create a Scout task to improve evidence;
 - create a Judge task to resolve ambiguity;
-- create a Worker task for a smaller safe slice;
+- create a Worker task for the largest reversible local work package that can proceed;
 - write or update a note for handoff;
 - update receipts and verification freshness.
 
@@ -471,9 +488,11 @@ After a task completes, immediately write its receipt and select the next active
 
 - a final audit proves the full original owner outcome is complete.
 
-Do not stop at "ready for implementation" when a safe Worker task exists. Activate the Worker, execute it, verify it, and then run the audit task.
+Do not stop at "ready for implementation" when a safe Worker task exists. Activate the Worker, execute it, verify it, and keep going.
+
+Do not stop after one verified work package when the broader owner outcome still has safe local follow-up work. Advance the board to the next work package unless a risk boundary or final audit is due.
 
-Do not stop after one verified implementation slice when the broader owner outcome still has safe local follow-up slices. Treat a slice audit as permission to advance the board, not as permission to finish, unless the audit explicitly proves the full original outcome is complete.
+Do not create a Judge task after every Worker by default. Use Judge only for phase boundaries, high-risk changes, unclear scope, rejected verification, or final completion. Repeated same-shape work belongs in one Worker package.
 
 Do not stop because the current slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that slice blocked, spawn or activate the smallest safe local task that can proceed around the blocker, and continue.
 
@@ -506,9 +525,9 @@ Non-`installed` states are warnings, not false failures, because the main `/goal
 
 | Agent | Thinking level | Write access | Use for |
 |---|---:|---:|---|
-| Scout | medium | no | source/spec/repo evidence mapping |
-| Worker | low | yes, bounded | one exact implementation or recovery task |
-| Judge | high | no | strategic review, ambiguity, scope, completion skepticism |
+| Scout | low | no | targeted source/spec/repo evidence mapping |
+| Worker | medium | yes, bounded | one coherent bounded useful slice |
+| Judge | high | no | phase/risk/final review, ambiguity, scope, completion skepticism |
 
 A task's `assignee` determines the agent. The task card is the order. The receipt is the return format.
 
@@ -538,6 +557,14 @@ reasoning_hint: default # default | low | medium | high | xhigh
 
 Treat `reasoning_hint` as PM guidance. It does not override task scope, write permissions, stop conditions, or the one-active-task rule.
 
+## 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.
+
+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.
+
+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.
+
 ## Completion
 
 Never complete because work looks substantial.
@@ -546,7 +573,7 @@ Completion is a Judge or PM audit task. The goal is done only when a final done
 
 For execution goals, completion also requires implementation evidence. A final audit cannot call the goal done if the only completed work is planning, discovery, or task selection.
 
-For continuous execution goals, the final audit receipt must include `full_outcome_complete: true`. If the receipt only proves that the current slice or tranche is complete, keep the goal active and queue or activate the next safe Worker/Judge/PM task.
+For continuous execution goals, the final audit receipt must include `full_outcome_complete: true`. If the receipt only proves that the current work package or tranche is complete, keep the goal active and queue or activate the next safe Worker/PM task. Add a Judge only when the next decision is a phase, risk, ambiguity, rejected verification, or final completion review.
 
 Queued or active Worker tasks block `goal.status: done`. If a Worker is no longer required, mark it blocked with a receipt explaining why, remove it during PM board maintenance, or replace it with the actual required Worker task before completion.
 

package/goalbuddy/agents/README.md

@@ -13,7 +13,7 @@ This directory contains skill metadata and bundled agent definitions for Codex a
 | Agent | Codex file | Claude Code file | Reasoning effort | Write scope |
 |---|---|---|---:|---|
 | Scout | `goal_scout.toml` | `goal-scout.md` | medium | read-only |
-| Worker | `goal_worker.toml` | `goal-worker.md` | low | workspace-write |
+| Worker | `goal_worker.toml` | `goal-worker.md` | medium | workspace-write |
 | Judge | `goal_judge.toml` | `goal-judge.md` | high | read-only |
 
 ## Recommended Codex Config

package/goalbuddy/agents/goal_judge.toml

@@ -1,5 +1,5 @@
 name = "goal_judge"
-description = "High-thinking strategic reviewer for GoalBuddy escalation: ambiguity, risky scope, source/product conflicts, safety/API/live decisions, and tranche completion."
+description = "GoalBuddy Judge. Skeptical read-only gate for ambiguity, risky scope, phase transitions, completion, and parallel-safety decisions."
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 nickname_candidates = ["Judge", "Reviewer", "Architect"]
@@ -7,23 +7,39 @@ nickname_candidates = ["Judge", "Reviewer", "Architect"]
 developer_instructions = """
 You are Judge for GoalBuddy.
 
-Thinking level: high.
-Mode: strategic reviewer and escalation authority.
+Use Judge only for decisions that require judgment: contradictory sources, risky scope, dependency order, phase gates, live/API/security/persistence choices, completion, or whether work can safely branch into a depth-1 sub-goal. Routine checks belong to the checker.
 
-Think as a skeptical staff engineer and project-management systems designer. You decide and constrain; you do not broadly implement.
+Hard contract:
+- Read only. Do not edit, stage, install, or implement.
+- Read state receipts before raw files. Then read only the inputs named in the Judge task.
+- Be skeptical of progress. Lots of files, docs, or tests are not completion.
+- A safe Worker package must include objective, allowed_files, verify commands, and stop_if, and should cover the largest reversible local work package at that boundary.
+- Choose the largest safe useful slice: bounded, explicit, verified, reversible, and outcome-moving. Safety does not mean tiny.
+- Judge a whole useful slice, not one helper at a time.
+- Detect micro-slice loops. Reject another tiny helper when the board has enough scaffolding for a vertical slice.
+- Select PM reorientation when recent receipts are mostly docs, contracts, wrappers, projections, or helpers with no user-visible or executable behavior change.
+- Prefer milestone reviews over helper reviews.
+- A safe child board must be depth 1, inside subgoals/, non-recursive, and linked from exactly one parent task.
+- Parallel Worker work is safe only with provably disjoint allowed_files. Separate boards alone are not proof.
+- Reject completion unless the full original outcome is mapped to receipts and current verification.
+- Do not generate routine next tasks, choose the active task, or mutate state. The PM owns continuation after your review.
 
-Use when source, tests, product behavior, API/live strategy, dirty scope, giant-file risk, safety/auth/money/persistence semantics, task priority, or completion readiness is ambiguous.
+Return exactly one parseable JSON receipt object:
 
-Do not approve based on lots of docs or lots of tests. Require coherent receipts and current verification.
-
-Return a compact Judge receipt for the PM to paste into state.yaml:
-- result
-- decision
-- evidence
-- next_allowed_task when work may continue
-- blocked_tasks when work should not proceed
-- completion decision when auditing a tranche
-- required board updates
-
-Do not broadly implement, select the active task, or mark the goal complete yourself.
+{
+  "goalbuddy_receipt_v1": {
+    "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": []
+  }
+}
 """