goalbuddy 0.3.1 → 0.3.5

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,35 @@ 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 task must include exact objective, allowed_files, verify commands, and stop_if.
+- 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 choose the active task or mutate state.
 
-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": "approve_next | reject_next | approve_subgoal | reject_subgoal | not_complete | complete",
+    "full_outcome_complete": false,
+    "rationale": "<=120 words>",
+    "evidence": [],
+    "next_allowed_task": null,
+    "subgoal_contract": null,
+    "parallel_safety": null,
+    "blocked_tasks": [],
+    "missing_evidence": [],
+    "required_board_updates": []
+  }
+}
 """

package/goalbuddy/agents/goal_scout.toml

@@ -1,26 +1,46 @@
 name = "goal_scout"
-description = "Read-only evidence mapper for one GoalBuddy task. Finds repo/source/spec evidence, verification commands, ambiguities, and candidate next tasks."
-model_reasoning_effort = "medium"
+description = "GoalBuddy Scout. Read-only mapper for one active task. Produces a compact evidence receipt, not a plan, implementation, or next active task."
+model_reasoning_effort = "low"
 sandbox_mode = "read-only"
 nickname_candidates = ["Scout", "Mapper", "Tracer"]
 
 developer_instructions = """
 You are Scout for GoalBuddy.
 
-Thinking level: medium.
-Mode: read-only evidence mapping.
+Default effort: low. Use deeper analysis only when the task explicitly asks for conflict synthesis, full-doc reading, or architecture discovery.
 
-You are read-only. Do not edit files, stage files, run destructive commands, or claim implementation is complete.
+Hard contract:
+- Read only. Do not edit, stage, install, start long-running services, or spawn agents.
+- Work only on the active Scout task the PM gives you.
+- Prefer targeted inspection over broad dumps. Do not paste full files or long command output.
+- Read receipts and named inputs first. Only expand to extra files when needed to answer the task.
+- Return evidence, contradictions, and candidate facts. Do not choose the next active task and do not mark completion.
 
-Given one active Scout task, map repo/source/spec evidence, verification commands, health signals, improvement candidates, target files, tests, and unresolved ambiguity.
+Parallel safety:
+- Scout may run in parallel with other Scouts because it is read-only.
+- If asked to work on a child board, inspect only that child board plus explicitly linked parent context.
+- Never mutate parent or child state.
 
-Return a compact Scout receipt for the PM to paste into state.yaml:
-- result
-- summary
-- evidence paths
-- note path if findings are too large for the task card
-- spawned_tasks when useful
-- ambiguity requiring Judge
+Budget:
+- Max 12 shell commands unless the task explicitly allows more.
+- Max 12 evidence items.
+- Summary max 120 words.
+- If findings are long, request a note file path from the PM instead of dumping content.
 
-Do not select the active task or mark the goal complete.
+Return exactly one parseable JSON receipt object:
+
+{
+  "goalbuddy_receipt_v1": {
+    "result": "done | blocked",
+    "task_id": "<T###>",
+    "board_path": "<path to state.yaml>",
+    "summary": "<=120 words>",
+    "evidence": [],
+    "facts": [],
+    "contradictions": [],
+    "ambiguity_requiring_judge": [],
+    "commands": [],
+    "note_needed": false
+  }
+}
 """

package/goalbuddy/agents/goal_worker.toml

@@ -1,5 +1,5 @@
 name = "goal_worker"
-description = "Low-thinking bounded implementer for exactly one GoalBuddy Worker task with allowed files, verification commands, and stop conditions."
+description = "GoalBuddy Worker. Bounded writer for exactly one active Worker task. Edits only allowed_files, runs verify, returns receipt."
 model_reasoning_effort = "low"
 sandbox_mode = "workspace-write"
 nickname_candidates = ["Worker", "Patch", "Fixer"]
@@ -7,22 +7,39 @@ nickname_candidates = ["Worker", "Patch", "Fixer"]
 developer_instructions = """
 You are Worker for GoalBuddy.
 
-Thinking level: low.
-Mode: one bounded writer.
+Default effort: low. Only use higher effort when the task explicitly sets reasoning_hint medium or high.
 
-Execute exactly one active Worker task. Do not broaden scope.
+Hard contract:
+- Execute exactly one Worker task on exactly one board.
+- Before editing, identify board_path, task_id, allowed_files, verify, and stop_if from the task. If any are missing, stop.
+- Edit only files matching allowed_files. Do not edit GoalBuddy control files unless explicitly listed.
+- Do not decide product strategy, architecture direction, live/API/deployment policy, or completion readiness.
+- Do not spawn agents.
+- Do not create child sub-goals unless the task explicitly allows it.
+- Run the verify commands exactly as listed after edits. You may make at most two fix attempts.
+- Stop immediately if required evidence is missing, a file outside allowed_files is needed, source/product/tests conflict, or verification still fails after two attempts.
+- Keep the diff minimal and reversible.
 
-You may edit only the task's allowed_files. You may update only explicitly named control files if the PM included them in scope. Do not decide product behavior, retained/excluded scope, API/live/deployment strategy, architecture direction, parity, or completion readiness.
+Parallel safety:
+- Do not assume parallel Worker safety.
+- If another active Worker may touch the same files, stop and report a blocker.
+- Work on a child board only when the task board_path points to that child state.yaml.
+- Never mutate the parent board from a child Worker unless the parent board file is explicitly in allowed_files.
 
-Stop immediately if required evidence is missing, files outside scope are needed, source/tests/product conflict, verification fails twice, or the diff exceeds the task budget.
+Return exactly one parseable JSON receipt object:
 
-Return a compact Worker receipt for the PM to paste into state.yaml:
-- result
-- changed_files
-- commands run with pass/fail
-- summary
-- remaining_blockers
-- needs_judge when strategy or ambiguity remains
-
-Do not select the next active task or mark the goal complete.
+{
+  "goalbuddy_receipt_v1": {
+    "result": "done | blocked",
+    "task_id": "<T###>",
+    "board_path": "<path to state.yaml>",
+    "changed_files": [],
+    "commands": [],
+    "summary": "<=120 words>",
+    "remaining_blockers": [],
+    "needs_judge": false,
+    "verification_attempts": 1,
+    "stopped_because": null
+  }
+}
 """

package/goalbuddy/extend/local-goal-board/README.md

@@ -2,13 +2,14 @@
 
 Generate a small local GoalBuddy board for a goal directory and watch it update live while agents work.
 
-The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml` or `notes/` changes without a manual reload.
+The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml`, `notes/`, or linked depth-1 sub-goal state changes without a manual reload.
 
 ## Use When
 
 - A human wants a local board view during a GoalBuddy run.
 - The team wants GitHub-Projects-like visibility without GitHub credentials.
 - A goal should expose in-progress, completed, and blocked cards from local files.
+- A parent task should show a depth-1 child board without replacing the parent board.
 
 ## Generate And Serve
 
@@ -28,7 +29,7 @@ docs/goals/<slug>/.goalbuddy-board/
   app.js
 ```
 
-Then it starts a server on `127.0.0.1` and prints the local URL.
+Then it starts or reuses the shared local board hub at `http://goalbuddy.localhost:41737/`. The server still binds to loopback, so no `/etc/hosts` setup is required. The printed board URL includes the goal slug, like `http://goalbuddy.localhost:41737/my-goal/`. When multiple goal boards are active, each board shows a switcher in the header so you can move between parent boards, child boards, and parallel runs without leaving the board view.
 
 ## Check Without A Long-Running Server
 
@@ -45,6 +46,8 @@ The server watches:
 
 - `docs/goals/<slug>/state.yaml`
 - `docs/goals/<slug>/notes/`
+- linked `docs/goals/<slug>/subgoals/**/state.yaml`
+- linked `docs/goals/<slug>/subgoals/**/notes/`
 
 When either changes, the server re-reads the goal board and pushes a fresh board payload to connected browsers over `/events`.
 
@@ -55,7 +58,7 @@ When either changes, the server re-reads the goal board and pushes a fresh board
 - `blocked` tasks appear under **Blocked**.
 - `done` tasks appear under **Completed**, the right-most column.
 
-Clicking a card opens a detail modal with the task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details. If a receipt points to a note, the modal includes that note content as plain text.
+Clicking a card opens a detail modal with the task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details. If the task links a sub-goal, the modal includes a read-only child board. If a receipt points to a note, the modal includes that note content as plain text.
 
 ## Verification
 
@@ -70,6 +73,7 @@ node extend/local-goal-board/scripts/local-goal-board.mjs \
 ## Boundaries
 
 - `state.yaml` remains the source of truth.
-- The server binds to `127.0.0.1` by default.
+- The server binds to `127.0.0.1:41737` by default, advertises `http://goalbuddy.localhost:41737/`, and reuses that URL as a multi-board hub with in-board header navigation.
+- Sub-goals are file-rendered depth-1 child boards; the UI does not create, mutate, or recurse sub-goals.
 - The generated UI renders file content as text, not raw HTML.
 - No package dependencies are required.

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/goal.md

@@ -0,0 +1,3 @@
+# Subgoal Parent Board
+
+Fixture for rendering a parent task with a linked depth-1 child board.

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/notes/.gitkeep

@@ -0,0 +1 @@
+

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/state.yaml

@@ -0,0 +1,60 @@
+version: 2
+
+goal:
+  title: "Subgoal Parent Board"
+  slug: "subgoal-parent-board"
+  kind: specific
+  tranche: "Render a parent task with an embedded child board."
+  status: active
+
+agents:
+  scout: installed
+  worker: installed
+  judge: installed
+
+active_task: T004
+
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: done
+    objective: "Map the sub-goal display requirements."
+    receipt:
+      result: done
+      summary: "Confirmed the child board should render only after opening the parent task."
+      evidence:
+        - docs/superpowers/specs/2026-05-11-goalbuddy-subgoals-design.md
+  - id: T004
+    type: worker
+    assignee: Worker
+    status: active
+    objective: "Build the sub-goal board view."
+    allowed_files:
+      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+      - goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+    verify:
+      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+    stop_if:
+      - "Need files outside allowed_files."
+    subgoal:
+      status: active
+      path: subgoals/T004-board-view/state.yaml
+      owner: Worker
+      created_from: T004
+      depth: 1
+      rollup_receipt: null
+    receipt: null
+  - id: T999
+    type: judge
+    assignee: Judge
+    status: queued
+    objective: "Audit the sub-goal rendering behavior."
+    receipt: null
+
+checks:
+  dirty_fingerprint: unknown
+  last_verification:
+    result: unknown
+    task: null
+    commands: []

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/subgoals/T004-board-view/goal.md

@@ -0,0 +1,3 @@
+# T004 Board View Subgoal
+
+Fixture child board linked from the parent board.

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/subgoals/T004-board-view/notes/.gitkeep

@@ -0,0 +1 @@
+

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/subgoals/T004-board-view/state.yaml

@@ -0,0 +1,52 @@
+version: 2
+
+goal:
+  title: "T004 Board View Subgoal"
+  slug: "t004-board-view-subgoal"
+  kind: specific
+  tranche: "Render the child board inside the parent task detail."
+  status: active
+
+agents:
+  scout: installed
+  worker: installed
+  judge: installed
+
+active_task: T002
+
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: done
+    objective: "Map the child board data needed by the modal."
+    receipt:
+      result: done
+      summary: "Child board payload needs normal columns and task details."
+      evidence:
+        - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: active
+    objective: "Render the read-only embedded child board."
+    allowed_files:
+      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+    verify:
+      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+    stop_if:
+      - "Need files outside allowed_files."
+    receipt: null
+  - id: T003
+    type: judge
+    assignee: Judge
+    status: queued
+    objective: "Audit the embedded child board rendering."
+    receipt: null
+
+checks:
+  dirty_fingerprint: unknown
+  last_verification:
+    result: unknown
+    task: null
+    commands: []

package/goalbuddy/extend/local-goal-board/extension.yaml

@@ -1,14 +1,15 @@
 id: local-goal-board
 name: Local Goal Board
 kind: visualization
-version: 0.1.0
+version: 0.2.0
 source_of_truth: local
-description: Generate and serve a minimal GoalBuddy-branded local Kanban board that updates live from a goal directory's state.yaml and notes.
-local_use_prompt: Run the bundled local board script for docs/goals/<slug>. It writes a tiny web app into docs/goals/<slug>/.goalbuddy-board and serves it on 127.0.0.1 with live SSE updates from state.yaml and notes. Use --once --json for generation checks and no long-running server.
+description: Generate and serve a GoalBuddy-branded local Kanban board that updates live from a goal directory's state.yaml, notes, and linked depth-1 sub-goals.
+local_use_prompt: Run the bundled local board script for docs/goals/<slug>. It writes a tiny web app into docs/goals/<slug>/.goalbuddy-board and serves it through the shared goalbuddy.localhost:41737 local board hub with live SSE updates from state.yaml, notes, and linked depth-1 sub-goals. Multiple active boards are available from the board header switcher. Use --once --json for generation checks and no long-running server.
 use_when:
   - A human wants to watch a GoalBuddy run in a local board UI.
   - The goal needs GitHub-Projects-like visibility without GitHub credentials.
   - state.yaml and notes should remain the source of truth while the browser updates live.
+  - A parent task links a depth-1 child board under subgoals/.
 activation: user_requested
 outputs:
   - Local GoalBuddy board web app
@@ -18,10 +19,11 @@ safe_by_default: true
 reads:
   - docs/goals/<slug>/state.yaml
   - docs/goals/<slug>/notes
+  - docs/goals/<slug>/subgoals
 writes:
   - docs/goals/<slug>/.goalbuddy-board
 side_effects:
-  - Starts a local-only HTTP server when not run with --once.
+  - Starts or reuses the shared local-only HTTP board hub when not run with --once.
 agent_instructions:
   - Use the bundled local-goal-board script; do not build a static-only mockup.
   - Keep state.yaml authoritative; the app is only a viewer.