passalong 0.11.0 → 0.13.0

package/README.md

@@ -33,7 +33,7 @@ passalong activity [--all]    what happened while you were away; clears unless -
 passalong list [query]        your guides and your teams', local and synced
 passalong open <id> [--print] view a guide in the browser (or the terminal)
 passalong hub                 open your synced guides in the browser
-passalong works <id>          you tried it and it holds up
+passalong works <id> <shot>   you tried it and it holds up, with a screenshot of it working
 passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 passalong archive <id>        off your board and out of the free tier's count (was `done`)
 passalong promote <id>        deprecated: mark promoted
@@ -67,9 +67,11 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-A receiver who tries the work reports back with `passalong works <id>` or `passalong broken <id> <why>`.
-That is separate from `done`, which means *implemented*: a verdict means it actually runs, a failing
-one has to say why, and the author sees it on their board and in their inbox.
+A receiver who tries the work reports back with `passalong works <id> <screenshot.png>` or
+`passalong broken <id> <why>`. That is separate from `done`, which means *implemented*: a verdict
+means it actually runs. A passing one has to show it — at least one screenshot of it working, kept
+until 5 days after the guide is closed — a failing one has to say why, and the author sees it on
+their board and in their inbox.
 
 Sign in at [the hub](https://passalong.dev/hub) with an email and password, and mint
 an API token there for the CLI and MCP servers — named, revocable, and shown once. Your password

package/bin/passalong

@@ -33,7 +33,7 @@
 //                                 give Solo to @handle, or Team to team/slug, until a date (operator only)
 //   passalong gifts               what has been given away, and what is still running
 //   passalong ungift <gift id>    take one back now
-//   passalong works <id>          you tried it and it holds up
+//   passalong works <id> <shot.png...>  you tried it and it holds up — with a screenshot of it working
 //   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   passalong archive <id>        off your board and out of the free tier's count (was `done`)
 //   passalong rm <id>             delete a guide locally and from sync
@@ -603,9 +603,12 @@ const commands = {
   },
 
   async works(f) {
-    const id = f._[0] || die("usage: passalong works <id>");
-    const r = await passalong.verdict(id, true, f._.slice(1).join(" ")).catch((e) => die(e.message));
-    console.error(`${r.id} verified — the author has been told`);
+    const id = f._[0] || die("usage: passalong works <id> <screenshot.png...> [what you checked]");
+    const { images, note } = passalong.proofArgs(f._.slice(1));
+    const r = await passalong.verdict(id, true, note, { images }).catch((e) => die(e.message));
+    console.error(
+      `${r.id} verified with ${images.length || "your"} screenshot${images.length === 1 ? "" : "s"} — the author has been told`,
+    );
   },
 
   async broken(f) {

package/package.json

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

package/skill/SKILL.md

@@ -66,7 +66,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. A session that started from a passalong guide
    (`passalong start` or `pull` on an id, or an agent opened one) usually has context worth adding
-   this way. Whether the guide worked is still its own answer: `passalong works <id>` or
+   this way. Whether the guide worked is still its own answer: `passalong works <id> <screenshot>` or
    `passalong broken <id> <why>`.
 6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the

package/src/api.js

@@ -1,7 +1,18 @@
 // Client for the hosted sync API (apps/api). Everything here is optional: with no token the
 // CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
+import { readFileSync } from "node:fs";
 import { readConfig } from "./store.js";
 
+/**
+ * This build's version, sent on every authenticated call as `x-passalong-version`. The server
+ * refuses a CLI below its floor (apps/api/src/clients.ts), because the rules it enforces deploy on
+ * merge and the text telling an agent how to follow them only arrives with a reinstall.
+ */
+export const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+const CLIENT = { "x-passalong-version": VERSION };
+
 export const DEFAULT_API = "https://passalong.dev";
 
 export class ApiError extends Error {
@@ -24,7 +35,7 @@ export function loggedIn() {
 }
 
 async function call(path, { method = "GET", body, auth = true, raw = false } = {}) {
-  const headers = {};
+  const headers = { ...CLIENT };
   if (auth) {
     const t = token();
     if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
@@ -220,7 +231,7 @@ export const ack = (id, taken, note = "") =>
 export async function uploadShot(bytes, type, name = "") {
   const t = token();
   if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
-  const headers = { authorization: `Bearer ${t}`, "content-type": type };
+  const headers = { ...CLIENT, authorization: `Bearer ${t}`, "content-type": type };
   // A header is latin-1: a filename with an accent in it throws on the way out rather than at the
   // server, and the label is not worth failing an upload over.
   if (name) headers["x-shot-name"] = String(name).replace(/[^\x20-\x7e]/g, "");

package/src/checks.js

@@ -22,6 +22,26 @@
  * exit code is the whole verdict here, which is also how a CI step decides.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * The shell a check runs in: bash with `pipefail` wherever there is one.
+ *
+ * A plain shell reports a pipeline's last command. `npx jest 2>&1 | grep Tests:` then passes when
+ * jest fails, because grep found the summary line, and `git log main..HEAD | head -60` passes when
+ * git dies with "fatal: ambiguous argument", because head exited 0 — which is exactly how a hand-in
+ * came back marked "ran, it worked here" with the fatal error sitting in its own output. With
+ * pipefail, any failing step fails the check.
+ */
+const BASH =
+  process.platform === "win32" ? "" : ["/bin/bash", "/usr/bin/bash"].find(existsSync) || "";
+
+/**
+ * 141 is 128 + SIGPIPE: the command was still writing when a later step stopped reading, which is
+ * what `| head` does on purpose. Under pipefail that is the pipeline's status, and it is not a
+ * failure — git printed what head wanted and was told to stop.
+ */
+const SIGPIPE = 141;
 
 /** How long a check may run before it is killed. Long enough for a real suite, short of a lease. */
 export const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
@@ -58,13 +78,15 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
   const cmd = String(check?.cmd ?? "").trim();
   if (!cmd) return { check: check.check, ran: check.ran };
 
-  const r = spawnSync(cmd, {
-    shell: true,
+  const opts = {
     cwd,
     timeout: timeoutMs,
     encoding: "utf8",
     maxBuffer: 64 * 1024 * 1024,
-  });
+  };
+  const r = BASH
+    ? spawnSync(BASH, ["-o", "pipefail", "-c", cmd], opts)
+    : spawnSync(cmd, { ...opts, shell: true });
 
   const out = tail(`${r.stdout ?? ""}${r.stderr ?? ""}`);
   // `status` is null when the child was killed rather than exited: a timeout, or a signal.
@@ -84,15 +106,20 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
     };
   }
 
+  const cutShort = Boolean(BASH) && r.status === SIGPIPE;
   return {
     check: check.check,
     cmd,
     exit: r.status,
-    ok: r.status === 0,
+    ok: r.status === 0 || cutShort,
     // The recorded evidence is what the process printed, not what the agent said about it. An
     // empty run is written out rather than left blank: the exit code is what decided it, and a
     // blank `ran` reads like evidence nobody supplied.
-    ran: out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`,
+    ran:
+      (out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`) +
+      (cutShort
+        ? "\n(exit 141: a later step stopped reading early, as `head` does; not a failure)"
+        : ""),
   };
 }
 

package/src/guide.js

@@ -127,8 +127,22 @@ export function sectionsFor(kind) {
 }
 
 /** The sections it cannot be published without. */
+/**
+ * The sections a kind cannot do without, and the one that has none.
+ *
+ * A transfer is context exchange. Context is whatever the next agent needs to not start cold —
+ * a decision and why, a constraint, where the bodies are — and none of that arrives in six fixed
+ * headings. Requiring `## Problem` and `## Steps` made every short note into a document: of 56
+ * follow-ups in real use, the ones that fill this template average 599 words and ten of sixteen
+ * were never opened by anyone, while the ones that ignored it average 137 words and every single
+ * one was opened. The template was not raising the floor, it was padding to reach it.
+ *
+ * A task and a bug keep theirs, because theirs are not prose. `## Acceptance` is the list a
+ * hand-in answers line by line, and `## Reproduce` is how a reader sees the defect. Those earn
+ * their requirement by being read mechanically; `## Steps` on a piece of context does not.
+ */
 const REQUIRED = {
-  transfer: ["Problem", "Steps"],
+  transfer: [],
   bug: ["Problem", "Reproduce"],
   task: ["Goal", "Acceptance"],
 };
@@ -255,16 +269,58 @@ export function parseFrontmatter(text) {
   // Only the lists every guide has. `blocked_by` is a task's, and defaulting it would write an
   // empty one into every guide anybody re-shares.
   for (const k of ["stack_assumptions", "tags"]) if (meta[k] === undefined) meta[k] = [];
-  // What it is, said rather than inferred. An unknown spelling is left alone for `validate()` to
-  // refuse by name: quietly turning `kind: buggy` into a transfer guide is the same guess this is
-  // here to remove.
-  if (!String(meta.kind ?? "").trim()) meta.kind = "transfer";
+  // Absent is absent. It is NOT a transfer guide.
+  //
+  // This line, and the sentence publish_guide tells every agent — "kind: task (the default)" —
+  // disagreed for thirteen days. An agent that left `kind:` off, believing what it had been told,
+  // got a transfer guide. 162 of 200 guides in real use are labelled transfer; their titles are
+  // tasks and bug reports. Everything downstream followed from that: a transfer has no states, so
+  // nothing could show as in progress; it demands Problem and Steps, so a two-line correction was
+  // padded to six sections; and there is nowhere to report into one, so agents published a second
+  // guide to carry what they had found.
+  //
+  // So it stays empty and `validate()` refuses it by name. The back-compat this default protected
+  // is a guide written before kinds existed being re-shared; that guide is re-shared once with an
+  // explicit `kind: transfer`, which is a sentence its author can write, unlike thirteen days of
+  // mislabelled work nobody could see.
+  meta.kind = String(meta.kind ?? "").trim();
   // Both ends of this module: what it reads and what it writes are in one style, so a guide
   // written before there was a rule comes back normalised and goes out normalised.
   meta.tags = tagList(meta.tags);
   return meta;
 }
 
+/**
+ * Frontmatter fields holding more than this format can: a nested map, a block scalar (`|`), a
+ * sequence under a field that is not a list. `parseFrontmatter` keeps only the key's own line, so
+ * each of these would come back as `""` with its content gone — a design.md's `colors:` block did
+ * exactly that, and a publish would have stored the document with every token wiped. The format
+ * does not grow to hold them (strings and string lists only); the publish refuses them by name
+ * instead, so nothing is lost without its author being told. Mirrors `unheldFields` in
+ * apps/api/src/guide.ts, which is the refusal every client meets.
+ */
+export function unheldFields(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!m) return [];
+  const out = new Set();
+  let key = null;
+  let listKey = null;
+  for (const line of m[1].split(/\r?\n/)) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    if (listKey && /^\s*-\s*/.test(line)) continue;
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
+    if (kv) {
+      key = kv[1];
+      listKey = kv[2].trim() === "" && LIST_FIELDS.has(key) ? key : null;
+      continue;
+    }
+    // Anything else is a line the parser skips: an indented child, or an item under a field
+    // that is not a list. It belongs to the key above it, and that is the key to name.
+    out.add(key ?? line.trim());
+  }
+  return [...out];
+}
+
 function quote(v) {
   const s = String(v ?? "");
   // Quote anything YAML would misread: colons, leading symbols, or empty.
@@ -305,6 +361,10 @@ export function serializeFrontmatter(meta) {
   ];
   const out = [];
   for (const key of keys) {
+    // A kind nobody stated is left unstated. Writing `kind: ""` would put an answer in the
+    // document that its author never gave, and the next parse would read it back as a stated
+    // empty rather than an absent one — which is the whole distinction validate() turns on.
+    if (key === "kind" && !String(meta[key] ?? "").trim()) continue;
     const v = key === "tags" ? tagList(meta[key]) : meta[key];
     if (Array.isArray(v)) {
       out.push(v.length ? `${key}: [${v.map(quote).join(", ")}]` : `${key}: []`);
@@ -497,8 +557,9 @@ export function bugGuide({
 
 /** A draft with the section skeleton. Placeholders are HTML comments so they vanish when rendered. */
 export function template(meta = {}) {
-  // A task unless asked otherwise: most guides assign work. The transfer skeleton writes its kind
-  // out, since an absent kind: still means transfer to every client already installed.
+  // A task unless asked otherwise: most guides assign work. Every skeleton writes its kind out —
+  // absent is now refused rather than read as transfer, so a template that left it off would
+  // produce a document its own author could not publish.
   if (meta.kind === "bug") return bugTemplate(meta);
   if (meta.kind !== "transfer") return taskTemplate(meta);
   const body = [

package/src/mcp.js

@@ -261,7 +261,9 @@ export function buildServer() {
         "Collect it as you work rather than writing it from memory at the end. hand_in without " +
         "it is refused, because the write-up and the verdict are both your word for your own " +
         "work and evidence is the part the person reviewing it can check.\n" +
-        `kind: task (the default) is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
+        "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. " +
+        `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. hand_in with `markdown`: a " +
         "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
@@ -381,7 +383,19 @@ export function buildServer() {
     }
   }
 
-  async function doHandIn({ id, ok, note, evidence, checks, writeup, markdown, report, pr, cwd }) {
+  async function doHandIn({
+    id,
+    ok,
+    note,
+    evidence,
+    checks,
+    writeup,
+    risk,
+    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
@@ -402,6 +416,7 @@ export function buildServer() {
         evidence: evidence || "",
         checks: done.checks,
         writeup: writeup || "",
+        risk: risk || "",
         markdown,
         report,
         pr: pr || "",
@@ -763,6 +778,15 @@ export function buildServer() {
               "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",
           ),
+        risk: z
+          .string()
+          .optional()
+          .describe(
+            "what this could break, in one line — the part of a PR template's Risk that is " +
+              "worth reading: a shared helper changed, a migration that cannot be undone, a " +
+              "route other clients call. Optional; leave it out when there is nothing specific, " +
+              'rather than writing "low risk". Its author reads it before accepting the work',
+          ),
         markdown: z
           .string()
           .optional()

package/src/passalong.js

@@ -16,6 +16,7 @@ import {
   serialize,
   stamp,
   stripPlaceholders,
+  unheldFields,
   validate,
 } from "./guide.js";
 import * as store from "./store.js";
@@ -60,7 +61,13 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   if (follows) guide.meta.parent = await resolveId(String(follows).trim());
   if (guide.meta.to && !guide.meta.team)
     throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
-  const errors = validate(guide);
+  const errors = [
+    ...unheldFields(markdown).map(
+      (k) =>
+        `frontmatter "${k}" holds more than a string or a list of strings, and it would be dropped — move it into the body (a fenced yaml block keeps it as written)`,
+    ),
+    ...validate(guide),
+  ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
   // A task stays a draft when it is shared. Draft is the column a task waits in until a person
@@ -358,8 +365,16 @@ export async function finishTask(
   requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
-    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
-      .guide.meta.id;
+    // A task's report is a transfer guide, and this code is what is making one — so it says so
+    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
+    // agent's hand-in because its write-up left a line off would be this function's omission
+    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
+    // author's to leave open, because the caller already knows the answer.
+    report = (
+      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
+        cwd,
+      })
+    ).guide.meta.id;
   }
   if (!report)
     throw new PassalongError(
@@ -414,6 +429,7 @@ export async function handIn(
     evidence = "",
     checks = [],
     writeup = "",
+    risk = "",
     markdown,
     report,
     pr = "",
@@ -443,8 +459,16 @@ export async function handIn(
   else requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
-    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
-      .guide.meta.id;
+    // A task's report is a transfer guide, and this code is what is making one — so it says so
+    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
+    // agent's hand-in because its write-up left a line off would be this function's omission
+    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
+    // author's to leave open, because the caller already knows the answer.
+    report = (
+      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
+        cwd,
+      })
+    ).guide.meta.id;
   }
   const fence = fenceFor(id, cwd);
   return api.handIn(id, {
@@ -466,6 +490,8 @@ export async function handIn(
     // 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 } : {}),
+    // What it could break, for the reviewer. Left out when empty, like the write-up.
+    ...(risk ? { risk } : {}),
     ...(typeof ok === "boolean" ? { ok } : {}),
   });
 }
@@ -713,6 +739,11 @@ export async function attach(file, { name = "" } = {}) {
  * found doing it. Whoever opens the original, person or agent, gets its follow-ups with it, which
  * is why context belongs there rather than in a one-line verdict note.
  *
+ * What an agent did and found working on the guide is not context for it: that is the hand-in,
+ * and the note says so. It used to list "what you found doing it" among the things to publish, on
+ * every `take`, while hand_in said a follow-up was not for answering — the agent followed the one
+ * it read last, and the author got a second guide to review with the evidence inside it.
+ *
  * Trailing, like the handoff nudge, so it never sits in front of the frontmatter. It is here and
  * not only in the server's instructions because an agent reads the payload it is working from and
  * skims everything else — the same reason the bug lead is inside the document. For a bug, the
@@ -729,9 +760,10 @@ export function followUpNote(meta = {}) {
     );
   return (
     "<!-- passalong: a follow-up is more context for this guide, written as its own guide. If " +
-    "this guide needs more — a missing detail, a step that needed explaining, what changed since, " +
-    `what you found doing it — publish that with publish_guide parent=${meta.id}, and whoever ` +
-    "opens this guide gets it too. -->"
+    "this guide needs more — a missing detail, a step that needed explaining, what changed since " +
+    `— publish that with publish_guide parent=${meta.id}, and whoever opens this guide gets it ` +
+    "too. What you did and found working on it is not a follow-up: it goes on hand_in, in " +
+    "`checks` and `writeup`. -->"
   );
 }
 
@@ -883,13 +915,40 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * "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 = "") {
+export async function verdict(id, ok, note = "", { images = [] } = {}) {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
   const said = note.trim();
   if (!ok && !said)
     throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  // "It works" is shown, not said: the server refuses one with no screenshot of it working, so
+  // the refusal is said here before anything is uploaded, in the words of the command that fixes it.
+  if (ok && !images.length && !/\/v1\/shots\/[a-z0-9]{6,16}/.test(said))
+    throw new PassalongError(
+      "show it working: passalong works <id> <screenshot.png> [what you checked]",
+    );
+  const guide = await resolveId(id);
+  const shots = [];
+  for (const file of images) shots.push((await attach(file)).markdown);
   const line = said.split("\n")[0].slice(0, 280);
-  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
+  const detail = [said.length > line.length || shots.length ? said : "", ...shots]
+    .filter(Boolean)
+    .join("\n");
+  return api.verdict(guide, ok, line, detail);
+}
+
+/**
+ * The words after `passalong works <id>`, split into the screenshots and the note: an argument is a
+ * screenshot when it names an image file that exists, and everything else is what was checked.
+ */
+export function proofArgs(args) {
+  const images = [];
+  const words = [];
+  for (const a of args) {
+    const ext = a.slice(a.lastIndexOf(".")).toLowerCase();
+    if (SHOT_TYPES[ext] && existsSync(a)) images.push(a);
+    else words.push(a);
+  }
+  return { images, note: words.join(" ") };
 }
 
 /**