passalong 0.18.0 → 0.19.0

package/README.md

@@ -28,7 +28,7 @@ codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ## Commands
 
 ```
-passalong share [file] [--to team[/handle]]  publish a guide as a draft → id + link; --to addresses it
+passalong share [file] [--to team[/handle]]  publish a guide → id + link, Ready; --to addresses it
 passalong pull <id|link>      print a guide; --save also writes ./.passalong/<id>.md (git-ignored)
 passalong inbox               guides handed to you that you have not pulled yet
 passalong board               waiting on you, in flight, landed, worth keeping
@@ -73,8 +73,8 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-Every guide, whatever its kind, moves the same way: it is a draft until a person marks it Ready
-(`passalong ready <id>`), then whoever takes it (`passalong take <id>`) holds it, hands it in with
+Every guide, whatever its kind, moves the same way: it is Ready when shared (or a draft, with
+`status: draft`, until a person runs `passalong ready <id>`), then whoever takes it (`passalong take <id>`) holds it, hands it in with
 the evidence, and a person approves it or sends it back with the reason (`passalong approve` /
 `passalong reject`).
 

package/bin/passalong

@@ -6,12 +6,11 @@
 //     handed to whoever pulls or starts that guide
 //     TARGET is a team, team/@handle for one person, or "team/#group" for the people who do a
 //     thing — quote that one, since a shell may read the # as a comment
-//   passalong task "<what needs doing>"  write a task for an agent; it waits in Draft
+//   passalong task "<what needs doing>"  write a task for an agent; Ready at once
 //   passalong ready <id...|--all> guides you have read are ready — whoever they are for may take them now
 //   passalong tasks               every task and where it is: draft, ready, claimed, stalled, review
 //   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, of any kind
-//   passalong reject <id> <why>   not done: back to Ready, and whoever takes it next reads why
+//   passalong reopen <id> <why>   finished work isn't right: back to To do, and whoever takes it next reads why
 //   passalong release <id>        take work back from whoever holds it, of any kind
 //   passalong attach <file>       upload a picture or a file and print the markdown that points at it
 //   passalong reply <id> <text>   write to whoever holds it (--file PATH to attach); or leave a note
@@ -337,9 +336,8 @@ const commands = {
     const id = guide.meta.id;
     console.log(id);
     const target = guide.meta.target_context;
-    console.error(`task "${guide.meta.title}" is in Draft${target ? ` for ${target}` : " (no repo)"}`);
+    console.error(`task "${guide.meta.title}" is Ready${target ? ` for ${target}` : " (no repo)"}`);
     if (guide.meta.team) console.error(`handed to ${guide.meta.team} (team inbox)`);
-    console.error(`when an agent may take it: passalong ready ${id}`);
   },
 
   async tasks() {
@@ -384,16 +382,25 @@ const commands = {
     if (n) console.error("review them with: passalong tasks");
   },
 
-  async approve(f) {
-    const id = f._[0] || die("usage: passalong approve <id>");
-    await passalong.approveTask(id).catch((e) => die(e.message));
-    console.error(`${id} is done`);
+  // Nothing waits for approval now (docs/REVIEW.md): finishing is final. Kept so a script that
+  // calls it is told, not refused.
+  async approve() {
+    console.error(
+      "nothing to approve: finished work is already Done. If it isn't right: passalong reopen <id> <why>",
+    );
+  },
+
+  /** Finished work back to To do, with why at its top; whoever finished it is told. */
+  async reopen(f) {
+    const id = f._[0] || die("usage: passalong reopen <id> <why>");
+    const why = f._.slice(1).join(" ");
+    if (!why) die("say why: passalong reopen <id> <what is wrong>");
+    await passalong.reopen(id, why).catch((e) => die(e.message));
+    console.error(`${id} is back in To do — whoever takes it next reads why`);
   },
 
   async reject(f) {
-    const id = f._[0] || die("usage: passalong reject <id> <why>");
-    await passalong.rejectTask(id, f._.slice(1).join(" ")).catch((e) => die(e.message));
-    console.error(`${id} is back in Ready — the next agent reads why`);
+    return commands.reopen(f);
   },
 
   async release(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [

package/skill/SKILL.md

@@ -67,8 +67,7 @@ machine, another agent session, or a teammate without your branch.
    follow-up gets the guide it came out of, and where that guide has got to — so write it as a
    note on that work rather than as a standalone brief. What you did or found while working on a
    guide belongs in its `hand_in`, not a follow-up.
-6. **Report** the id (and link) and say it is a **draft**: it reaches nobody until the person reads
-   it and marks it Ready (`passalong ready <id>`, or Ready in the hub). Then one line on how to use
+6. **Report** the id (and link). It is Ready and has reached whoever it is for. Then one line on how to use
    it on the other side: `passalong take <id>` in the target repo, or "take passalong <id>" to an
    agent with the Passalong MCP server. `take` rather than `pull` on purpose: it holds the work as
    well as fetching it, and until somebody takes it the sender cannot tell a guide nobody noticed

package/src/api.js

@@ -429,6 +429,8 @@ 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 reopen = (id, why) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/reopen`, { method: "POST", body: { why } });
 /** A handoff's or bug's approve and send-back. No `place` names the only hand-in there is. */
 export const closeGuide = (id) =>
   call(`/v1/guides/${encodeURIComponent(id)}/close`, { method: "POST", body: {} });

package/src/guide.js

@@ -497,7 +497,9 @@ export function stamp(guide, defaults = {}) {
   const meta = { ...guide.meta };
   if (!meta.id) meta.id = newId();
   if (!meta.created) meta.created = new Date().toISOString();
-  if (!meta.status) meta.status = "draft";
+  // Ready unless whoever wrote it said draft: a guide sent to someone is meant to reach them, and
+  // drafts were where addressed work sat forgotten (every draft in production on 2026-10-15).
+  if (!meta.status) meta.status = "published";
   for (const [k, v] of Object.entries(defaults))
     if (meta[k] === undefined || meta[k] === "") meta[k] = v;
   return { meta, body: guide.body };
@@ -525,8 +527,7 @@ export function bugGuide({
   area = "",
   report = "",
   environment = "",
-  // A draft like every new guide: it reaches people when a person marks it Ready.
-  status = "draft",
+  status = "published",
   evidence = [],
 } = {}) {
   /**
@@ -617,7 +618,7 @@ export function template(meta = {}) {
       summary: "",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,
@@ -655,7 +656,7 @@ function bugTemplate(meta = {}) {
       kind: "bug",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       severity: "s3",
       stack_assumptions: [],
       tags: ["bug"],
@@ -697,7 +698,7 @@ function taskTemplate(meta = {}) {
       author: "",
       source_context: "",
       target_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,

package/src/mcp.js

@@ -297,15 +297,16 @@ export function buildServer() {
         "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
         "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
-        "is a spelling that is not one of the three. EVERY NEW GUIDE IS A DRAFT, whatever its kind: " +
-        "it reaches nobody until a person reads it and marks it Ready, and every kind then moves the " +
-        "same way — Ready, taken, handed in, approved. " +
+        "is a spelling that is not one of the three. A NEW GUIDE IS READY: it reaches whoever it is " +
+        "for at once. Say `status: draft` only when the person should read it first — something you " +
+        "are unsure of — and tell them; plan_tasks drafts for you. Every kind moves the same way — " +
+        "Ready, taken, handed in, approved. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
         "alone, and treat Acceptance as the definition of done. A proposal awaiting a team decision " +
-        "stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
-        "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
-        "author reviews it against Acceptance.\n" +
+        "stays Draft until a person makes it Ready. hand_in when every Acceptance line holds: it is " +
+        "final — the task goes to Done with what you showed, and nobody reviews it after you — so " +
+        "show it, and say anything you had to adapt in `writeup` (500 characters).\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
         "Follow its Steps, adapting anything marked ASSUMES to this codebase; run its " +
         "Verification, then hand_in with ok and, when it failed, a note saying what went wrong.\n" +
@@ -1084,7 +1085,7 @@ export function buildServer() {
         const ids = await passalong.planTasks(steps, { cwd: cwd || process.cwd() });
         return json({
           drafts: ids.map((id, i) => ({ id, title: steps[i].title, after: steps[i].after || [] })),
-          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
+          next: `all in Draft: ask the user to read them and mark them Ready on the board at ${api.baseUrl()}/hub/work, or run \`passalong ready --all\``,
         });
       } catch (err) {
         return fail(err);
@@ -1157,7 +1158,7 @@ export function buildServer() {
       outputSchema: handInOut,
       annotations: ADDS,
       description:
-        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "Finished here, with proof. IT IS FINAL: the work goes to Done with what you showed, and nobody reviews it after you (anyone can reopen it with a reason). So SHOW IT: a screenshot for anything with a screen — before and after, for a bug — or, for backend work, the one command and the line of its output that shows it works. 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 " +
@@ -1165,8 +1166,7 @@ export function buildServer() {
         "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 " +
+        "works. A task needs no write-up guide any more. 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 ' +
@@ -1242,10 +1242,10 @@ export function buildServer() {
           .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",
+            "what you had to adapt to make it work here — a version, a name, a step that needed " +
+              "something the guide does not mention. 500 characters at most; anything longer " +
+              "belongs in the change. Optional: leave it out when it worked as written. The next " +
+              "person to open the guide is shown it",
           ),
         risk: z
           .string()
@@ -1259,11 +1259,11 @@ export function buildServer() {
         markdown: z
           .string()
           .optional()
-          .describe("task: the write-up; start from guide_template kind transfer"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         report: z
           .string()
           .optional()
-          .describe("task, instead of markdown: id of a write-up already published"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         pr: z.string().optional().describe("task: PR or branch link, when there is one"),
         cwd: z
           .string()
@@ -1579,7 +1579,8 @@ export function buildServer() {
           ...(guide.meta.status === "draft"
             ? {
                 status: "draft",
-                next: `in Draft: ask the user to read it, then run \`passalong ready ${guide.meta.id}\``,
+                // The hub page, never the share link: the share page has no Ready button.
+                next: `in Draft: ask the user to read it and mark it Ready at ${api.baseUrl()}/hub/g/${guide.meta.id}, or run \`passalong ready ${guide.meta.id}\``,
               }
             : {}),
         });
@@ -1677,11 +1678,7 @@ export function buildServer() {
           { title: title || "", environment: environment || "", issues },
           { cwd: cwd || process.cwd(), to },
         );
-        return json({
-          ...filed,
-          // Filed is not sent: every bug is a draft until a person reads it.
-          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
-        });
+        return json(filed);
       } catch (err) {
         return fail(err);
       }

package/src/passalong.js

@@ -78,12 +78,6 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
-  // Every guide is a draft when it is first shared, whatever its kind: Draft is where it waits
-  // until a person says it is ready — `ready()` — and an agent that writes one over MCP comes
-  // through here too, so publishing on share would let it reach people with nobody reading it.
-  // Sharing *is* putting it in Draft, so a new guide that names no status says so here; one already
-  // published keeps what its document says.
-  if (!guide.meta.status) guide = { ...guide, meta: { ...guide.meta, status: "draft" } };
 
   // The server is where a guide lives; nothing is kept on this machine.
   needsSync("sharing a guide");
@@ -583,6 +577,14 @@ export async function now({ cwd = process.cwd() } = {}) {
   return { held, waiting, needs: review + handed + waiting.inbox, agent: who.agent };
 }
 
+/** Finished work back to To do, with why (docs/REVIEW.md §4). */
+export async function reopen(id, why) {
+  needsSync("reopening work");
+  if (!String(why || "").trim())
+    throw new PassalongError("say why: whoever takes it next reads it");
+  return api.reopen(await resolveId(id), why);
+}
+
 /**
  * The gate, a person's three answers to a task. Approve: the work in review is done. Reject: it
  * goes back to Ready with `why` on it for the next agent. Release: a task an agent holds, live or
@@ -1046,10 +1048,13 @@ export async function planTasks(steps, { cwd = process.cwd() } = {}) {
     ].join("\n");
     // The summary is the step's own, said by whoever planned it: it is what a person reads about the
     // task, and this builds the document without guessing one (the server refuses a task without).
+    // A plan is the case Draft is for: several tasks at once, which a person reads before any of
+    // them runs. Stated here, by the code that knows it is building one.
     const meta = {
       title: step.title,
       summary: step.summary,
       kind: "task",
+      status: "draft",
       target_context: step.target_context ?? repo,
     };
     const after = (step.after || []).map((j) => ids[j]);