passalong 0.8.0 → 0.9.0

package/bin/passalong

@@ -12,7 +12,7 @@
 //   passalong work [--once] [--agent CMD]  run an agent on each ready task here, one after another
 //   passalong approve <id>        the work in review is done
 //   passalong reject <id> <why>   not done: back to Ready, and the next agent reads why
-//   passalong release <id>        take a task back from the agent holding it, stalled or not
+//   passalong release <id>        take work back from whoever holds it, of any kind
 //   passalong attach <image>      upload evidence and print the markdown that points at it
 //   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
 //   passalong start <id|link>     pull it and take it — one command for "I am doing this"
@@ -332,8 +332,12 @@ const commands = {
 
   async release(f) {
     const id = f._[0] || die("usage: passalong release <id>");
-    await passalong.releaseTask(id).catch((e) => die(e.message));
-    console.error(`${id} is back in Ready — it says where the last agent left it`);
+    const r = await passalong.release(id).catch((e) => die(e.message));
+    const from = Number(r?.from) || 1;
+    console.error(
+      `${id} is back in Ready${from > 1 ? `, taken back from ${from} places` : ""}` +
+        " — whoever had it has been told",
+    );
   },
 
   async ready(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",

package/src/api.js

@@ -176,8 +176,11 @@ export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
 export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
 /** Does it actually work? `note` is required when it does not. */
-export const verdict = (id, ok, note = "") =>
-  call(`/v1/guides/${id}/verdict`, { method: "PUT", body: { ok, note } });
+export const verdict = (id, ok, note = "", detail = "") =>
+  call(`/v1/guides/${id}/verdict`, {
+    method: "PUT",
+    body: { ok, note, ...(detail ? { detail } : {}) },
+  });
 
 export const tasks = () => call("/v1/tasks");
 export const nextTask = (body) => call("/v1/tasks/next", { method: "POST", body });
@@ -189,8 +192,9 @@ export const approveTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/approve`, { method: "POST", body: {} });
 export const rejectTask = (id, why) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/reject`, { method: "POST", body: { why } });
-export const releaseTask = (id) =>
-  call(`/v1/tasks/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
+/** Take work back from whoever holds it, of any kind. `/v1/tasks/…/release` is the old path. */
+export const release = (id) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
 /** The four verbs every guide answers to. See docs/V2.md §11. */
 export const working = () => call("/v1/working");
 export const handedIn = () => call("/v1/handed_in");

package/src/mcp.js

@@ -326,7 +326,7 @@ export function buildServer() {
     }
   }
 
-  async function doHandIn({ id, ok, note, evidence, checks, markdown, report, pr, cwd }) {
+  async function doHandIn({ id, ok, note, evidence, checks, writeup, markdown, report, pr, cwd }) {
     try {
       // A check that names a command is run here, before anything is recorded, and its exit code
       // decides it rather than the agent's account of it. A failure is refused with the command's
@@ -346,6 +346,7 @@ export function buildServer() {
         note: note || "",
         evidence: evidence || "",
         checks: done.checks,
+        writeup: writeup || "",
         markdown,
         report,
         pr: pr || "",
@@ -640,18 +641,22 @@ export function buildServer() {
       outputSchema: handInOut,
       annotations: ADDS,
       description:
-        "Done here, with proof. Every hand-in carries what you ran and what came back. On a TASK " +
-        "send `checks`: one entry per Acceptance line, each with that line and the evidence for " +
-        "it — that is what its author reads, line against line, instead of hunting through a wall " +
-        "of output for the part that answers each one. Give a check `cmd` when a command proves " +
-        "it: the command is run here before the hand-in lands, a non-zero exit refuses it, and " +
-        "what it printed is recorded instead of your account of it. Use `ran` for a check no " +
-        "command can settle. `evidence` is the same thing as one block, " +
-        "for a handoff or a bug, which have no Acceptance lines. A task also takes `markdown`, a " +
-        "transfer guide about what you did and decided — this publishes it and attaches it. A " +
-        "handoff or a bug takes `ok`, whether its Verification held here, and `note` saying what " +
-        "went wrong when it did not. More context than a note holds goes in a follow-up: " +
-        "publish_guide with `parent` set to this id.",
+        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a " +
+        "bug — each with that line and the evidence for it. That is what its author reads, line " +
+        "against line, instead of hunting through a wall of output for the part that answers each " +
+        "one, AND IT IS HOW YOU KNOW YOU ARE DONE: every line has one. Give a check `cmd` when a " +
+        "command proves it: the command is run here before the hand-in lands, a non-zero exit " +
+        "refuses it, and what it printed is recorded instead of your account of it. Use `ran` for " +
+        "a check no command can settle. `evidence` as one block is the older shape and still " +
+        "works. A task also takes `markdown`, a transfer guide about what you did and decided — " +
+        "this publishes it and attaches it. A handoff or a bug takes `ok`, whether its " +
+        "Verification held here, and `note` saying what went wrong when it did not. DO NOT " +
+        "publish a guide to carry your evidence: it belongs on this call, and a second document " +
+        'titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you ' +
+        "had to adapt something, that goes in `writeup` and the next reader of the guide is shown " +
+        "it — that is its home. A follow-up guide is for work somebody else should now do, not " +
+        "for answering.",
       inputSchema: {
         id: z.string().describe("passalong id"),
         evidence: z
@@ -664,7 +669,12 @@ export function buildServer() {
         checks: z
           .array(
             z.object({
-              check: z.string().describe("the Acceptance line this answers, in the task's words"),
+              check: z
+                .string()
+                .describe(
+                  "the line this answers, in the guide's own words: an Acceptance line on a task, " +
+                    "a Verification line on a handoff or a bug",
+                ),
               ran: z
                 .string()
                 .optional()
@@ -681,9 +691,21 @@ export function buildServer() {
             }),
           )
           .optional()
-          .describe("task: one entry per Acceptance line, in the order you worked them"),
+          .describe(
+            "one entry per line the guide asks for — Acceptance on a task, Verification on a " +
+              "handoff or a bug — in the order you worked them",
+          ),
         ok: z.boolean().optional().describe("handoff or bug: did its Verification hold"),
         note: z.string().optional().describe("one line; required when ok is false"),
+        writeup: z
+          .string()
+          .optional()
+          .describe(
+            "handoff or bug: what you had to adapt to make it work here — a version, a name, a " +
+              "step that needed something the guide does not mention. Prose, and optional: leave " +
+              "it out when it worked as written. The next person to open the guide is shown it, " +
+              "which is why it does not need to be a guide of its own",
+          ),
         markdown: z
           .string()
           .optional()

package/src/passalong.js

@@ -412,6 +412,7 @@ export async function handIn(
     note = "",
     evidence = "",
     checks = [],
+    writeup = "",
     markdown,
     report,
     pr = "",
@@ -446,6 +447,9 @@ export async function handIn(
         }
       : {}),
     ...(report ? { report, pr } : {}),
+    // Left out when there is nothing to say, rather than sent as "": most hand-ins have nothing
+    // to adapt, and the field is for the ones that do.
+    ...(writeup ? { writeup } : {}),
     ...(typeof ok === "boolean" ? { ok } : {}),
   });
 }
@@ -539,9 +543,16 @@ export async function rejectTask(id, why) {
   return r;
 }
 
-export async function releaseTask(id) {
-  needsSync("releasing a task");
-  const r = await api.releaseTask(id);
+/**
+ * Take it back from whoever is holding it — a task, a handoff or a bug, and from all of them at
+ * once when several people hold the same handoff in different repos.
+ *
+ * It was tasks only, which left an asymmetry nobody chose: the author of a handoff could mark it
+ * done or give it to somebody else, and had no way to simply have it back.
+ */
+export async function release(id) {
+  needsSync("taking work back");
+  const r = await api.release(id);
   store.remove(id);
   return r;
 }
@@ -808,11 +819,21 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
  * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
  */
+/**
+ * Say whether a guide held, and why at the length that takes.
+ *
+ * The reason used to be one field, capped at 280 characters by the row it was written for — so an
+ * agent that had run the Verification and found it did not hold published a guide called
+ * "Correction: …" instead, because measurements, commands and commit ids do not fit in a tweet.
+ * The first line is the summary a row shows; the whole thing is what the guide shows.
+ */
 export async function verdict(id, ok, note = "") {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
-  if (!ok && !note.trim())
-    throw new PassalongError("say what went wrong: passalong failed <id> <what happened>");
-  return api.verdict(await resolveId(id), ok, note.trim());
+  const said = note.trim();
+  if (!ok && !said)
+    throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  const line = said.split("\n")[0].slice(0, 280);
+  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
 }
 
 /**