goalbuddy 0.3.2 → 0.3.6

package/goalbuddy/scripts/render-task-prompt.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseGoalStateText } from "../extend/local-goal-board/scripts/lib/goal-board.mjs";
+
+const ROLE_DEFAULTS = {
+  scout: { agent: "goal_scout", reasoning: "low", sandbox: "read-only" },
+  judge: { agent: "goal_judge", reasoning: "high", sandbox: "read-only" },
+  worker: { agent: "goal_worker", reasoning: "medium", sandbox: "workspace-write" },
+  pm: { agent: "PM", reasoning: "medium", sandbox: "workspace-write" },
+};
+
+if (isDirectRun()) {
+  try {
+    const result = renderTaskPrompt(parseArgs(process.argv.slice(2)));
+    if (result.json) {
+      console.log(JSON.stringify(result.payload, null, 2));
+    } else {
+      console.log(formatPrompt(result.payload));
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+export function renderTaskPrompt(options) {
+  const boardPath = resolveBoardPath(options);
+  const board = loadBoard(boardPath);
+  const task = selectTask(board, options.taskId);
+  const role = normalizeRole(task.type);
+  const defaults = ROLE_DEFAULTS[role] || ROLE_DEFAULTS.pm;
+  const reasoning = normalizeReasoning(task.reasoning_hint, defaults.reasoning);
+  const warnings = promptWarnings(board, task);
+
+  return {
+    json: options.json,
+    payload: {
+      metadata: {
+        recommended_agent: defaults.agent,
+        required_spawn_agent_type: defaults.agent === "PM" ? null : defaults.agent,
+        recommended_reasoning: reasoning,
+        sandbox: defaults.sandbox,
+        fork_context_allowed: role !== "worker",
+        board_path: board.path,
+        child_board_paths: childBoardPaths(board),
+        slice_policy: board.document.rules?.slice_policy || null,
+        warnings,
+      },
+      task: {
+        id: task.id,
+        type: role,
+        assignee: task.assignee || defaults.agent,
+        status: task.status,
+        objective: task.objective || "",
+        inputs: stringList(task.inputs),
+        constraints: stringList(task.constraints),
+        allowed_files: stringList(task.allowed_files),
+        verify: stringList(task.verify),
+        stop_if: stringList(task.stop_if),
+        reasoning_hint: task.reasoning_hint || null,
+        expected_output: stringList(task.expected_output),
+      },
+      receipt_schema: receiptSchema(role),
+    },
+  };
+}
+
+export function parseArgs(args) {
+  const options = { goalRoot: "", boardPath: "", taskId: "", json: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--task") {
+      options.taskId = args[++index] || "";
+    } else if (arg.startsWith("--task=")) {
+      options.taskId = arg.slice("--task=".length);
+    } else if (arg === "--board") {
+      options.boardPath = args[++index] || "";
+    } else if (arg.startsWith("--board=")) {
+      options.boardPath = arg.slice("--board=".length);
+    } else if (arg === "--parallel-plan") {
+      options.parallelPlan = true;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    } else if (!options.goalRoot) {
+      options.goalRoot = arg;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  if (!options.goalRoot && !options.boardPath) {
+    throw new Error("Usage: goalbuddy prompt <goal-root> [--task T###] [--board path/to/state.yaml]");
+  }
+  return options;
+}
+
+export function loadBoard(boardPath) {
+  if (!existsSync(boardPath)) throw new Error(`state file not found: ${boardPath}`);
+  const document = parseGoalStateText(readFileSync(boardPath, "utf8"));
+  if (!document || Number(document.version) !== 2) {
+    throw new Error(`unsupported GoalBuddy state version in ${boardPath}`);
+  }
+  if (!Array.isArray(document.tasks)) throw new Error(`state file has no tasks: ${boardPath}`);
+  return {
+    path: boardPath,
+    root: dirname(boardPath),
+    document,
+    tasks: document.tasks,
+    goal: document.goal || {},
+    activeTask: document.active_task || "",
+  };
+}
+
+export function resolveBoardPath(options) {
+  const candidate = options.boardPath || options.goalRoot;
+  if (!candidate) throw new Error("Missing goal root or board path.");
+  const resolved = resolve(candidate);
+  if (basename(resolved) === "state.yaml") return resolved;
+  return resolve(resolved, "state.yaml");
+}
+
+export function selectTask(board, taskId = "") {
+  const id = taskId || board.activeTask;
+  if (!id) throw new Error(`No task selected and active_task is empty in ${board.path}`);
+  const task = board.tasks.find((candidate) => candidate?.id === id);
+  if (!task) throw new Error(`Task ${id} not found in ${board.path}`);
+  return task;
+}
+
+export function childBoardPaths(board) {
+  return board.tasks
+    .map((task) => task?.subgoal?.path)
+    .filter(Boolean)
+    .map((childPath) => resolve(board.root, childPath));
+}
+
+function promptWarnings(board, task) {
+  const warnings = [];
+  const role = normalizeRole(task.type);
+  if (task.id !== board.activeTask) warnings.push(`Task ${task.id} is not the active task on this board.`);
+  if (role === "worker") {
+    if (stringList(task.allowed_files).length === 0) warnings.push(`Worker task ${task.id} has no allowed_files.`);
+    if (stringList(task.verify).length === 0) warnings.push(`Worker task ${task.id} has no verify commands.`);
+    if (stringList(task.stop_if).length === 0) warnings.push(`Worker task ${task.id} has no stop_if conditions.`);
+    if (isFalse(board.goal.full_outcome_complete)) {
+      warnings.push(`full_outcome_complete is false and ${task.id} is an active Worker; do not stop after rendering or repairing the board. Execute the Worker unless a stop_if condition applies.`);
+    }
+  }
+  for (const candidate of board.tasks) {
+    if (candidate?.subgoal && Number(candidate.subgoal.depth) !== 1) {
+      warnings.push(`Task ${candidate.id} has subgoal.depth ${candidate.subgoal.depth || "<missing>"}; only depth 1 is supported.`);
+    }
+  }
+  warnings.push(...microSliceWarnings(board, task));
+  return warnings;
+}
+
+function microSliceWarnings(board, task) {
+  const warnings = [];
+  const doneTasks = board.tasks.filter((candidate) => candidate?.status === "done");
+  const recentWorkers = board.tasks
+    .filter((candidate) => normalizeRole(candidate?.type) === "worker")
+    .slice(-5);
+  const recentTinyWorkers = recentWorkers.filter((candidate) => isTinyTask(candidate));
+  const activeRole = normalizeRole(task.type);
+  const activeAllowedFiles = stringList(task.allowed_files);
+  const firstMilestoneComplete = isTrue(board.goal.first_milestone_complete);
+  const microWarning = "Board may be micro-slicing. Prefer the largest safe useful slice.";
+
+  if (recentTinyWorkers.length >= 3) warnings.push(microWarning);
+  if (doneTasks.length >= 10 && activeRole === "worker" && activeAllowedFiles.length > 0 && activeAllowedFiles.length <= 2) {
+    warnings.push(`${microWarning} Active Worker ${task.id} has only ${activeAllowedFiles.length} allowed_files after ${doneTasks.length} completed tasks.`);
+  }
+  if (firstMilestoneComplete && activeRole === "worker" && isTinyTask(task)) {
+    warnings.push(`${microWarning} The first milestone is complete, so the active Worker should move toward the next real milestone.`);
+  }
+  if (activeRole === "judge" && /pick small reviewable work|select one narrow next task/i.test(String(task.objective || "") + "\n" + stringList(task.constraints).join("\n"))) {
+    warnings.push(`${microWarning} Judge instructions still ask for small or narrow work.`);
+  }
+  return [...new Set(warnings)];
+}
+
+function isTinyTask(task) {
+  const text = [
+    task?.objective,
+    stringList(task?.constraints).join(" "),
+    task?.receipt?.summary,
+  ].join(" ").toLowerCase();
+  return /\b(tiny|narrow|single helper|one helper|projection helper|projection function|contract file|read-only proof|doc note|validator|validation wrapper|pure helper|caller-input)\b/.test(text);
+}
+
+function normalizeRole(value) {
+  const role = String(value || "pm").toLowerCase();
+  return ROLE_DEFAULTS[role] ? role : "pm";
+}
+
+function normalizeReasoning(value, fallback) {
+  const hint = String(value || "").toLowerCase();
+  if (["low", "medium", "high", "xhigh"].includes(hint)) return hint;
+  return fallback;
+}
+
+function isFalse(value) {
+  return value === false || String(value).toLowerCase() === "false";
+}
+
+function isTrue(value) {
+  return value === true || String(value).toLowerCase() === "true";
+}
+
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((item) => item !== null && item !== undefined).map(String) : [];
+}
+
+function receiptSchema(role) {
+  if (role === "worker") {
+    return {
+      result: "done | blocked",
+      changed_files: [],
+      commands: [{ cmd: "<command>", status: "pass | fail | not_run" }],
+      summary: "<=120 words",
+      remaining_blockers: [],
+    };
+  }
+  if (role === "judge") {
+    return {
+      result: "done | blocked",
+      decision: "approved | rejected | approve_subgoal | reject_subgoal | not_complete | complete",
+      full_outcome_complete: false,
+      evidence: [],
+      blocked_tasks: [],
+      required_board_updates: [],
+    };
+  }
+  return {
+    result: "done | blocked",
+    summary: "<=120 words",
+    evidence: [],
+    facts: [],
+    contradictions: [],
+    ambiguity_requiring_judge: [],
+  };
+}
+
+function formatPrompt(payload) {
+  const lines = [
+    "GoalBuddy task prompt",
+    "",
+    "Metadata:",
+    `- recommended_agent: ${payload.metadata.recommended_agent}`,
+    `- required_spawn_agent_type: ${payload.metadata.required_spawn_agent_type || "PM fallback"}`,
+    `- recommended_reasoning: ${payload.metadata.recommended_reasoning}`,
+    `- sandbox: ${payload.metadata.sandbox}`,
+    `- fork_context_allowed: ${payload.metadata.fork_context_allowed}`,
+    `- board_path: ${payload.metadata.board_path}`,
+  ];
+  if (payload.metadata.child_board_paths.length) {
+    lines.push("- child_board_paths:");
+    for (const path of payload.metadata.child_board_paths) lines.push(`  - ${path}`);
+  }
+  if (payload.metadata.slice_policy) {
+    lines.push(`- slice_policy: ${JSON.stringify(payload.metadata.slice_policy)}`);
+  }
+  if (payload.metadata.warnings.length) {
+    lines.push("- warnings:");
+    for (const warning of payload.metadata.warnings) lines.push(`  - ${warning}`);
+  }
+
+  lines.push(
+    "",
+    "Spawn contract:",
+    `- Codex spawn_agent agent_type: ${payload.metadata.required_spawn_agent_type || "do not spawn; run as PM"}`,
+    "- Do not substitute generic scout, worker, or judge agents for GoalBuddy agents.",
+    "- If the required GoalBuddy agent is unavailable, stop spawning and continue as PM fallback or install agents.",
+    "- After one wait_agent timeout with no visible allowed-file changes, stop waiting and recover deterministically.",
+    "",
+    "Task:",
+    `- id: ${payload.task.id}`,
+    `- type: ${payload.task.type}`,
+    `- assignee: ${payload.task.assignee}`,
+    `- status: ${payload.task.status}`,
+    `- objective: ${payload.task.objective}`,
+  );
+  addList(lines, "inputs", payload.task.inputs);
+  addList(lines, "constraints", payload.task.constraints);
+  addList(lines, "allowed_files", payload.task.allowed_files);
+  addList(lines, "verify", payload.task.verify);
+  addList(lines, "stop_if", payload.task.stop_if);
+  addList(lines, "expected_output", payload.task.expected_output);
+  lines.push("", "Expected receipt JSON shape:", JSON.stringify(payload.receipt_schema, null, 2));
+  return lines.join("\n");
+}
+
+function addList(lines, label, values) {
+  if (!values.length) return;
+  lines.push(`- ${label}:`);
+  for (const value of values) lines.push(`  - ${value}`);
+}
+
+function isDirectRun() {
+  return process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+}

package/goalbuddy/templates/agents.md

@@ -4,8 +4,8 @@ Use three generic agents. The main `/goal` thread remains PM and owns the board.
 
 | Agent | model_reasoning_effort | sandbox_mode | Purpose |
 |---|---:|---|---|
-| goal_scout | medium | read-only | Evidence mapping and candidate tasks |
-| goal_worker | low | workspace-write | One bounded implementation/recovery task |
+| goal_scout | low | read-only | Targeted evidence mapping and candidate facts |
+| goal_worker | medium | workspace-write | One coherent bounded implementation/recovery slice |
 | goal_judge | high | read-only | Strategic review, escalation, completion skepticism |
 
 ## PM Thinking Policy
@@ -44,5 +44,6 @@ Rules:
 
 - Only the PM loop chooses active tasks, marks tasks done, or completes the goal.
 - Keep at most one write-capable Worker active unless disjoint write scopes are explicit in `state.yaml`.
-- Scout and Judge are read-only.
-- Judge is high thinking.
+- Worker defaults to medium reasoning for implementation tasks and should complete the whole assigned slice.
+- Scout and Judge are read-only and safe to parallelize when their board inputs are clear.
+- Judge is high thinking and should choose the largest safe useful slice, not the narrowest helper.

package/goalbuddy/templates/goal.md

@@ -25,7 +25,7 @@
 
 ## Current Tranche
 
-<What is enough for the full owner outcome, and what is the current safe slice? For execution goals, the default is continuous: discover enough evidence, choose a safe implementation slice, implement it, verify it, audit it, then immediately advance to the next safe slice until the full original outcome is complete. Plan-only or one-slice-only stopping is valid only when explicitly requested.>
+<What is enough for the full owner outcome, and what is the current largest reversible local work package? For execution goals, the default is continuous: discover enough evidence, choose a coherent work package, implement it, verify it, review only at phase/risk/final boundaries, then immediately advance to the next work package until the full original outcome is complete. Plan-only or one-package-only stopping is valid only when explicitly requested.>
 
 ## Non-Negotiable Constraints
 
@@ -37,7 +37,21 @@ Stop only when a final audit proves the full original outcome is complete.
 
 Do not stop after planning, discovery, or Judge selection if the user asked for working software or automation and a safe Worker task can be activated.
 
-Do not stop after a single verified Worker slice when the broader owner outcome still has safe local follow-up slices. After each slice audit, advance the board to the next highest-leverage safe Worker task and continue.
+Do not stop after a single verified Worker package when the broader owner outcome still has safe local follow-up work. Advance the board to the next highest-leverage safe Worker package and continue unless a phase, risk, rejected-verification, ambiguity, or final-completion review is due.
+
+Do not create one Worker/Judge pair per repeated file, table, route, or helper. Put repeated same-shape work into one Worker package and review the package as a whole.
+
+## Slice Sizing
+
+Safe means bounded, explicit, verified, and reversible. It does not mean tiny.
+
+A good task is the largest safe useful slice.
+
+Small is not the goal. Useful is the goal.
+
+A Worker should finish the whole assigned slice. A Judge should judge the whole assigned slice. A PM should reorient the board when tasks are safe but not moving the outcome.
+
+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.
 
 Do not stop because a slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that exact slice blocked with a receipt, create the smallest safe follow-up or workaround task, and continue all local, non-destructive work that can still move the goal toward the full outcome.
 
@@ -67,9 +81,9 @@ On every `/goal` continuation:
 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.
+9. If safe local work remains, choose the next largest reversible Worker package 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.
+11. Review at phase, risk, rejected-verification, ambiguity, or final-completion boundaries; do not review every small Worker by habit.
 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/goalbuddy/templates/state.yaml

@@ -33,6 +33,11 @@ rules:
   missing_input_or_credentials_do_not_stop_goal: true
   preserve_and_validate_existing_plan: true
   intake_misfire_must_be_audited: true
+  slice_policy:
+    max_consecutive_tiny_tasks: 2
+    prefer_vertical_slices: true
+    judge_picks_largest_safe_slice: true
+    worker_completes_whole_slice: true
 
 agents:
   # installed | bundled_not_installed | missing | unknown
@@ -88,7 +93,7 @@ tasks:
       - "T001 receipt"
     constraints:
       - "Do not implement."
-      - "Pick small reviewable work."
+      - "Pick the largest safe useful slice with clear allowed_files, verify commands, and stop conditions."
     expected_output:
       - "Decision"
       - "Exact Worker objective"
@@ -109,6 +114,14 @@ tasks:
       - "Need files outside allowed_files."
       - "Behavior is ambiguous."
       - "Verification fails twice."
+    # Optional depth-1 child board promoted by PM when a task needs bounded branching work:
+    # subgoal:
+    #   status: active # active | blocked | done
+    #   path: subgoals/T003-child/state.yaml
+    #   owner: Worker
+    #   created_from: T003
+    #   depth: 1
+    #   rollup_receipt: null
     receipt: null
   - id: T999
     type: judge