breakaway 1.2.1-main.11 → 1.2.1-main.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.2.1-main.11",
+  "version": "1.2.1-main.13",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/scripts/tasks/cli.js

@@ -79,7 +79,7 @@ export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
 
 /**
  * The request behind `npx breakaway github fix <n>` and `github review <n>` (BRK-81): the pull request page's "Fix with an
- * agent" and "Safe to merge?" buttons (`POST github/pulls/<n>/fix` and `/review`). It names the checkout's repository
+ * agent" and "Safe to merge?" or "Review with an agent" buttons (`POST github/pulls/<n>/fix` and `/review`). It names the checkout's repository
  * like `github` does. Returns an error message instead when the number or `problem` can't be right.
  * @param {'fix' | 'review'} action
  * @param {string | number | undefined} number
@@ -96,11 +96,40 @@ export function pullAgentRequest(action, number, { repo = null, problem, note, f
     ...(repo ? { repo } : {}),
     ...(problem ? { problem } : {}),
     ...(typeof note === 'string' && note.trim() ? { note } : {}),
-    ...forceFields(force, by),
+    // Review with an agent is the owner's, so a review always says who asks (BRK-111); a fix only when forcing.
+    ...(action === 'review' ? { ...(force ? { force: true } : {}), ...(by ? { by } : {}) } : forceFields(force, by)),
   };
   return { request: ['POST', `github/pulls/${n}/${action}`, body] };
 }
 
+export const REVIEW_VERDICTS = ['ready', 'follow-up', 'changes'];
+
+/**
+ * `npx breakaway review <ID> --verdict ready|follow-up|changes "<note>"` (BRK-111): an agent's answer on the pull
+ * request that closes its task. The board adds it to the task as a comment and keeps it for the pull request page.
+ * `pr` picks the pull request when the task has several open.
+ * @param {string | undefined} ref
+ * @param {string | undefined} verdict
+ * @param {string | undefined} note
+ * @param {{ by?: string, pr?: string | number }} [options]
+ */
+export function reviewRequest(ref, verdict, note, { by, pr } = {}) {
+  if (!ref) return { error: 'say which task: npx breakaway review <task> --verdict ready "<note>"' };
+  if (!REVIEW_VERDICTS.includes(String(verdict)))
+    return { error: `say the verdict: --verdict ${REVIEW_VERDICTS.join('|')}` };
+  const text = String(note ?? '').trim();
+  if (!text) return { error: 'say what you found: the note is the review (Markdown)' };
+  const n = pr === undefined ? null : String(pr).replace(/^#/u, '');
+  if (n !== null && !/^[1-9]\d{0,8}$/u.test(n)) return { error: '--pr is a pull request number' };
+  return {
+    request: [
+      'POST',
+      `tasks/${encodeURIComponent(ref)}/review`,
+      { verdict, note: text, ...(by ? { by } : {}), ...(n ? { pr: Number(n) } : {}) },
+    ],
+  };
+}
+
 /**
  * Force start on a request that starts an agent (BRK-107): `force`, and who is asking, so the board can refuse an
  * agent's name (only the owner forces a start). Nothing when it isn't forced.
@@ -114,15 +143,17 @@ export function forceFields(force, by) {
 /**
  * `agents new`: the request that makes a task from a prompt and starts an agent on it. It's the checkout's repository
  * unless `--repo` names another. It always says who asks, so the board refuses an agent's name: only the owner starts one.
+ * With `decision` (`agents new --decision <ID> ["<note>"]`, BRK-110) the board writes the prompt from that answered
+ * decision, in the decision's repository, and the text is the owner's note under it.
  * @param {string} prompt
- * @param {{ repo?: string | null, force?: boolean, by?: string }} [options]
+ * @param {{ repo?: string | null, force?: boolean, by?: string, decision?: string | null }} [options]
  */
-export function generalAgentRequest(prompt, { repo = null, force = false, by } = {}) {
+export function generalAgentRequest(prompt, { repo = null, force = false, by, decision = null } = {}) {
   const text = String(prompt ?? '').trim();
-  if (!text)
+  if (!text && !decision)
     return { error: 'say what the agent should do: npx breakaway agents new "Tidy the docs" [--image <file>]' };
   const body = {
-    prompt: text,
+    ...(decision ? { decision, ...(text ? { note: text } : {}) } : { prompt: text }),
     ...(repo ? { repo } : {}),
     ...(force ? { force: true } : {}),
     ...(by ? { by } : {}),
@@ -132,11 +163,12 @@ export function generalAgentRequest(prompt, { repo = null, force = false, by } =
 
 /**
  * What the CLI says about a general agent's answer: the task and that it started, or why it waits (and whether Force
- * start could skip that).
- * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, waiting?: string | null, forceable?: boolean }} answer
+ * start could skip that), or, from a decision, the open one that already has it.
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, waiting?: string | null, forceable?: boolean, already?: string | null }} answer
  */
-export function generalAgentSummary({ task, run, waiting, forceable }) {
+export function generalAgentSummary({ task, run, waiting, forceable, already }) {
   const id = task.wid ?? task.short;
+  if (!run && already) return `${id} already refines from these answers: ${already}.`;
   if (run) return `Started ${run.agent ? `${run.agent} ` : 'an agent '}on ${id}${run.url ? `: ${run.url}` : ''}`;
   return `Saved ${id}, waiting to start: ${waiting ?? 'no room yet'}.${forceable ? ` Start it now past the board's limits: npx breakaway agents start ${id} --force` : ''}`;
 }
@@ -145,12 +177,13 @@ export function generalAgentSummary({ task, run, waiting, forceable }) {
  * What the CLI says about an answer to those requests: which task and agent took the pull request, or who already has it.
  * @param {'fix' | 'review'} action
  * @param {string | number} number
- * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, already?: string | null }} answer
+ * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string, kind?: string } | null, already?: string | null }} answer
  */
 export function pullAgentSummary(action, number, { task, run, already }) {
   const id = task.wid ?? task.short;
   if (!run) return `${id} already has it: ${already}.`;
-  const what = action === 'fix' ? `fixing #${number}` : `testing #${number}`;
+  const what =
+    action === 'fix' ? `fixing #${number}` : run.kind === 'pr-review' ? `reviewing #${number}` : `testing #${number}`;
   return `Started ${run.agent ? `${run.agent}, ` : 'an agent '}${what} on ${id}${run.url ? `: ${run.url}` : ''}`;
 }
 

package/scripts/tasks.mjs

@@ -51,6 +51,7 @@ import {
   ideaTask,
   pullAgentRequest,
   pullAgentSummary,
+  reviewRequest,
   staleCliWarning,
   unknownSubcommand,
 } from './tasks/cli.js';
@@ -137,6 +138,7 @@ Reading                (list, next, claim, and add work in this checkout's repos
   activity               recent changes, newest first  [--limit <n>]
   agents                 cloud agents: what's running, what's waiting to start
   agents new "<prompt>"  start an agent from a prompt: it makes its own task  [--image <file>]… [--repo <slug>] [--force] (owner)
+  agents new --decision <ref> ["<note>"]   start an agent that brings the work waiting for an answered decision in line with its answers; the board writes its prompt  [--force] (owner)
   agents start <ref>     start a Claude cloud agent on a task  [--note <text>] [--force]
   agents refine <ref>    start an agent that improves a task, not builds it  --note <what to look at or change> [--force]
   agents plan [<plan>]   your Claude plan and what it allows; pro, max5, or max20 picks one (owner) and sets the limits to its defaults
@@ -145,7 +147,9 @@ Reading                (list, next, claim, and add work in this checkout's repos
   routines run <slug>    run one now: makes a RUN task and starts an agent on it  [--note <text>] [--force]
   horizon close          close now: finished tasks go to the archive, next becomes now, later becomes next  [--dry-run]
   github fix <n>         start an agent on a pull request's conflicts, failing checks, or review comments (owner)  [--problem conflicts|failing|review] [--note <text>] [--repo <slug>] [--force]
-  github review <n>      start an agent that tests a Dependabot pull request, as Safe to merge? does (owner)  [--note <text>] [--repo <slug>] [--force]
+  github review <n>      start an agent that reviews a pull request that can merge as it stands, on the task it closes, as
+                         Review with an agent does; on a Dependabot one it tests the update, as Safe to merge? does
+                         (owner)  [--note <text>] [--repo <slug>] [--force]
   github                 the checkout's repository on GitHub: open pull requests, checks, reviews, CI, deploys, alerts  [--sync] [--repo <slug>]
   hook session|wait      the Claude Code session hooks a repository's .claude/settings.json runs (npx breakaway hook session)
   health                 the server's state
@@ -157,6 +161,8 @@ Working
                          refuses another repository's task unless --repo names it
   release <ref>          give it back  [--force]
   comment <ref> <text>   add a comment (signed with your agent name); note is the same command
+  review <ref> --verdict ready|follow-up|changes <note>   your review of the pull request that closes the task you
+                         hold: a comment on it, and the review on the pull request's page (the note is Markdown)  [--pr <n>]
   done <ref>             finish it  [--note <text>] [--pr <url>]
   add <description>      new task; gets the next work ID for its project
     --project <p> --tag <t>… --priority H|M|L --horizon now|next|later
@@ -757,8 +763,11 @@ const commands = {
       return;
     }
     if (sub === 'new') {
+      const decision = typeof opts.decision === 'string' ? opts.decision : null;
       const built = generalAgentRequest(args.slice(1).join(' '), {
-        repo: opts.repo ?? (await checkoutRepo()).slug,
+        // From a decision, the board runs it in the decision's repository unless --repo says otherwise.
+        repo: opts.repo ?? (decision ? null : (await checkoutRepo()).slug),
+        decision,
         force: Boolean(opts.force),
         by: opts.as ?? setting('AGENT'),
       });
@@ -1076,6 +1085,12 @@ const commands = {
     unmarkSession(task);
     print(task, (t) => `Released ${ref(t)}.`);
   },
+  async review() {
+    const built = reviewRequest(args[0], opts.verdict, args.slice(1).join(' '), { by: agent(), pr: opts.pr });
+    if (built.error || !built.request) fail(built.error ?? 'bad request');
+    const { review, task } = await call(...built.request);
+    print({ review, task }, (r) => `Left your review of #${r.review.pr} on ${ref(r.task)}: ${r.review.label}.`);
+  },
   // The board's `annotate` route is the comments route's alias; using it keeps this working on a board that hasn't deployed /comments yet.
   async comment() {
     const text = args.slice(1).join(' ');

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 52;
-export const CLI_FINGERPRINT = 'b1542857a107623b';
+export const CLI_VERSION = 54;
+export const CLI_FINGERPRINT = 'c5c5e4b72de52bfb';

package/src/decision.js

@@ -239,3 +239,75 @@ export function summarize(questions, answers) {
   });
   return `Decided by the owner: ${parts.join('; ')}`;
 }
+
+/** Tags that aren't a feature's (IDEA-28 section 1): the board's own, horizons, and release tags. */
+const NOT_FEATURES = new Set(['agent', 'owner', 'decide', 'idea', 'general']);
+export const featureTags = (tags) =>
+  (tags ?? []).filter((t) => !NOT_FEATURES.has(t) && !t.startsWith('horizon-') && !/^v\d/u.test(t));
+
+/** One answer as words, in full but for a long open answer. */
+function spell(q, answer) {
+  if (!answer) return 'no answer';
+  if (q.type === 'open') return clip(answer.value.trim(), 1500);
+  const label = (id) =>
+    id === 'other' ? `something else: ${answer.other}` : (q.options.find((o) => o.id === id)?.label ?? id);
+  if (q.type === 'choice') return label(answer.value);
+  if (q.type === 'multi') return answer.value.length ? answer.value.map(label).join(', ') : 'none';
+  if (q.type === 'rank') return answer.value.map((id, i) => `${i + 1}. ${label(id)}`).join(', ');
+  if (q.type === 'scale')
+    return `${answer.value} (${q.min}${q.minLabel ? ` ${q.minLabel}` : ''} to ${q.max}${q.maxLabel ? ` ${q.maxLabel}` : ''})`;
+  return String(answer.value);
+}
+
+/** The longest the prompt may be: a task's description. */
+const MAX_BRIEF = 10000;
+
+/**
+ * Refine from the answers (docs/specs/IDEA-30-new-agent.md, section 8): the prompt the board writes for a general
+ * agent that brings the work waiting for an answered decision in line with its answers. `decision` is the decision's
+ * task (its `ref` is its work ID or short ID), `waiting` the open tasks that depend on it, and `note` the owner's,
+ * which goes under the board's prompt. Returns the task's title and description.
+ * @param {{ ref: string, description: string, spec?: string | null, questions: any[], answers: Record<string, any> }} decision
+ * @param {{ ref: string, description: string, tags?: string[], spec?: string | null }[]} waiting
+ * @param {string | null} [note]
+ */
+export function refinePrompt(decision, waiting, note = null) {
+  const title = clip(`Refine from the answers to ${decision.ref}: ${decision.description}`, 200);
+  const questions = decision.questions.flatMap((q, i) => {
+    const answer = decision.answers[q.id];
+    return [
+      `${i + 1}. ${q.prompt.trim()}`,
+      `   Answer: ${spell(q, answer)}`,
+      ...(answer?.comment ? [`   The owner's note: ${answer.comment.trim()}`] : []),
+    ];
+  });
+  const specs = [...new Set([decision.spec, ...waiting.map((t) => t.spec)].filter(Boolean))];
+  const held = waiting.map((t) => {
+    const features = featureTags(t.tags);
+    return `- ${t.ref}: ${t.description}${features.length ? ` (feature: ${features.join(', ')})` : ''}`;
+  });
+  const after = [
+    '',
+    'What to do',
+    `- Change the tasks waiting for ${decision.ref}, and their dependencies, so they match the answers (the cross-task edits a general agent may make, each change noted).`,
+    `- Update ${specs.length ? 'the spec' : 'any spec the tasks link'} to match, in one pull request that closes your own task.`,
+    '- Add the tasks the answers need, filled in and depending on what they wait for.',
+    '- Ask a new decision for anything the answers leave open. Never change these answers: only the owner does.',
+    '- If nothing in the repository needs to change, comment what you changed on the board, task by task, and release your task.',
+    ...(note && String(note).trim() ? ['', 'Note from the owner:', String(note).trim().slice(0, 4000)] : []),
+  ];
+  const intro = `The owner answered the decision on ${decision.ref} (${decision.description}). Bring the work waiting for it in line with the answers.`;
+  const rest = [
+    '',
+    `Waiting for ${decision.ref}`,
+    ...(held.length ? held : ['- Nothing open waits for it: look for tasks and specs the answers change.']),
+    ...(specs.length ? ['', specs.length === 1 ? 'Spec' : 'Specs', ...specs.map((s) => `- ${s}`)] : []),
+    ...after,
+  ].join('\n');
+  // Too long for a description: the answers give way first, since they stay on the decision for the agent to read.
+  const more = `\n… (the rest is on ${decision.ref}: npx breakaway show ${decision.ref})`;
+  const answers = ['', 'Questions and answers', ...questions].join('\n');
+  const room = MAX_BRIEF - intro.length - rest.length - 1;
+  const middle = answers.length <= room ? answers : `${answers.slice(0, Math.max(0, room - more.length))}${more}`;
+  return { title, brief: `${intro}${middle}\n${rest}`.slice(0, MAX_BRIEF) };
+}