passalong 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -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/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,10 +269,21 @@ 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);
@@ -305,6 +330,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 +526,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

@@ -358,8 +358,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 +422,7 @@ export async function handIn(
     evidence = "",
     checks = [],
     writeup = "",
+    risk = "",
     markdown,
     report,
     pr = "",
@@ -443,8 +452,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 +483,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 +732,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 +753,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`. -->"
   );
 }