passalong 0.3.2 → 0.6.0

package/bin/passalong

@@ -1,9 +1,18 @@
 #!/usr/bin/env node
 // Passalong CLI. Few flags on purpose: the defaults are the product.
 //
-//   passalong share [file] [--to TARGET] [--follows ID]  publish a guide → id + link
+//   passalong share [file] [--to TARGET] [--follows ID]  publish a guide → id + link; --follows adds it as context to guide ID
+//     --follows ID publishes it as a follow-up: more context for guide ID, listed under it and
+//     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 ready <id...|--all> tasks you have read are ready — an agent 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
+//   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 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"
@@ -28,16 +37,18 @@
 //   passalong team invite [email] make an invite link (mailed when an email is given)
 //   passalong team join <link|code>  accept an invite
 //   passalong team use <slug>     switch the current team
-//   passalong setup               install the Claude Code capture skill + register the MCP server
+//   passalong setup               install the Claude Code capture skill, MCP server and hooks
+//   passalong now                 what this worktree holds and what is waiting (the hooks call --hook)
 //   passalong mcp                 run the MCP server over stdio
 //   passalong version             print the installed version (also -v, --version)
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as api from "../src/api.js";
-import { scaffold } from "../src/capture.js";
+import { scaffold, taskScaffold } from "../src/capture.js";
 import { serialize } from "../src/guide.js";
 import * as passalong from "../src/passalong.js";
 import * as store from "../src/store.js";
@@ -101,24 +112,83 @@ function activityLine(n) {
   return `${dot} ${(n.guide || "").padEnd(8)}  ${relDate(n.at).padEnd(10)} ${n.text}`;
 }
 
+/**
+ * After a pulled guide, the follow-ups written for it: more context, each its own guide. Listed on
+ * stderr rather than printed in full, so stdout stays exactly the document; nothing at all when
+ * there are none or sync is off.
+ */
+async function listFollowUps(meta) {
+  const guides = await passalong.followUpGuides(meta);
+  if (!guides.length) return;
+  console.error(
+    `\n${guides.length} follow-up${guides.length === 1 ? "" : "s"} — more context for this guide:`,
+  );
+  for (const g of guides) console.error(`  ${g.id}  ${g.title || "untitled"}`);
+  console.error("Read one with: passalong pull <id>");
+}
+
 const MONTHS = "January February March April May June July August September October November December".split(" ");
 /** "September 2026" from an ISO timestamp, without pulling in a date library for one heading. */
 const monthOf = (iso) => `${MONTHS[Number(iso.slice(5, 7)) - 1]} ${iso.slice(0, 4)}`;
 
+// ---- the status line cache --------------------------------------------------------------------------
+
+/** One small file per working directory, so two sessions in two repos each see their own. */
+const statusPath = (cwd) =>
+  join(store.HOME, "statusline", `${createHash("sha1").update(cwd).digest("hex").slice(0, 16)}.json`);
+
+function writeStatus(cwd, text) {
+  const p = statusPath(cwd);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify({ at: Date.now(), text }));
+}
+
+/** How old a cached line may be before a refresh is started behind it. */
+const STATUS_TTL_MS = 30_000;
+
+/**
+ * Print the cached line for this directory at once, and when it is stale start a detached refresh
+ * that writes the next one. The first run in a directory prints a placeholder; the refresh lands
+ * within a second or two, and the next update shows it. Offline or signed out, it says nothing.
+ */
+async function statusLine() {
+  let input = {};
+  if (!process.stdin.isTTY) {
+    let raw = "";
+    for await (const chunk of process.stdin) raw += chunk;
+    try {
+      input = JSON.parse(raw || "{}");
+    } catch {}
+  }
+  if (!api.loggedIn()) return;
+  const cwd = input.workspace?.current_dir || input.cwd || process.cwd();
+  let cached = null;
+  try {
+    cached = JSON.parse(readFileSync(statusPath(cwd), "utf8"));
+  } catch {}
+  process.stdout.write(cached?.text ?? "passalong");
+  if (!cached || Date.now() - cached.at > STATUS_TTL_MS) {
+    // Marked fresh before the refresh starts, so a burst of updates starts one refresh, not ten.
+    writeStatus(cwd, cached?.text ?? "passalong");
+    spawn(process.execPath, [fileURLToPath(import.meta.url), "now", "--statusline-refresh", cwd], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    }).unref();
+  }
+}
+
 const commands = {
   async share(f) {
     let path = f._[0];
-    let fromDrafts = false;
     if (!path) {
       const [latest] = store.drafts();
       if (latest) {
         path = latest;
-        fromDrafts = true;
         console.error(`using draft ${path}`);
       } else {
         path = store.draftPath(new Date().toISOString().replace(/[:.]/g, "-"));
         writeFileSync(path, scaffold());
-        fromDrafts = true;
         if (!tty)
           die(`no draft to share; scaffolded ${path} — fill it in and run \`passalong share ${path}\``);
       }
@@ -130,7 +200,10 @@ const commands = {
     const { guide, url, synced, notified, path: saved } = await passalong
       .share(readFileSync(path, "utf8"), { to, follows })
       .catch((e) => die(e.message));
-    if (fromDrafts) store.removeDraft(path);
+    // Any draft that went out is spent, however it was named — a task that failed validation is
+    // re-shared by its path, and leaving it would have the next bare `share` publish it again.
+    // removeDraft() touches nothing outside the drafts directory.
+    store.removeDraft(resolve(path));
     console.log(guide.meta.id);
     console.error(`shared "${guide.meta.title}" → ${saved}`);
     if (guide.meta.parent) console.error(`follows ${guide.meta.parent}`);
@@ -142,11 +215,107 @@ const commands = {
     else console.error("not synced (run `passalong login` to sync across machines)");
   },
 
+  /**
+   * Write a task. It lands in Draft and stays there until `passalong ready`: the gap between the
+   * two is the one moment a person reads what an agent is about to be asked to do.
+   */
+  async task(f) {
+    const sentence = f._.join(" ").trim() || die('usage: passalong task "<what needs doing>"');
+    const path = store.draftPath(`task-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+    writeFileSync(path, taskScaffold(sentence));
+    if (tty && !f["no-edit"]) edit(path);
+    const { guide, synced } = await passalong
+      .share(readFileSync(path, "utf8"))
+      .catch((e) => die(`${e.message}\ndraft kept at ${path} — fix it and run \`passalong share ${path}\``));
+    store.removeDraft(path);
+    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(`when an agent may take it: passalong ready ${id}`);
+    if (!synced) console.error("not synced (run `passalong login` — agents elsewhere cannot see it)");
+  },
+
+  async tasks() {
+    const rows = await passalong.tasks().catch((e) => die(e.message));
+    if (!rows.length) return console.error('no tasks yet — write one with: passalong task "<what needs doing>"');
+    for (const t of rows) {
+      const c = t.claim;
+      const who = c ? `  ${c.host || "?"}:${c.worktree.split("/").pop() || "?"}` : "";
+      const said = c?.note ? `  "${c.note}"` : "";
+      console.log(`${t.id}  ${t.state.padEnd(8)} ${t.title}${t.target ? `  [${t.target}]` : ""}${who}${said}`);
+      // What came back, under the task it answers: the thing a reviewer reads before deciding.
+      if (t.state === "review" && c?.report)
+        console.log(`          → ${c.report}  ${c.report_title || "(untitled)"}${c.pr ? `  ${c.pr}` : ""}`);
+    }
+    if (rows.some((t) => t.state === "review"))
+      console.error("\nread a write-up with: passalong open <id> — then approve or reject the task");
+  },
+
+  /**
+   * Work the queue from this worktree until it is empty. The agent is `claude -p` unless --agent or
+   * PASSALONG_AGENT says otherwise, e.g. "claude -p --permission-mode acceptEdits" so it can edit
+   * files without asking — which is yours to decide, not this command's.
+   */
+  async work(f) {
+    const run = await passalong
+      .work({
+        agent: typeof f.agent === "string" ? f.agent : undefined,
+        once: Boolean(f.once),
+        any: Boolean(f.any),
+        onTask: (t) => console.error(`\n→ ${t.id}  ${t.title}${t.resumed ? "  (resuming)" : ""}`),
+      })
+      .catch((e) => die(e.message));
+    for (const id of run.finished) console.log(id);
+    const n = run.finished.length;
+    const done = `${n} task${n === 1 ? "" : "s"} finished and waiting for review`;
+    if (run.stopped === "unfinished")
+      die(
+        `${done}. Stopped: the agent exited with ${run.task} still ${run.state || "open"} — ` +
+          `run again to resume it, or \`passalong release ${run.task}\``,
+      );
+    console.error(`${done}${run.stopped === "empty" ? " — nothing left for this repo" : ""}`);
+    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`);
+  },
+
+  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`);
+  },
+
+  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`);
+  },
+
+  async ready(f) {
+    if (f.all) {
+      const ids = await passalong.readyDrafts().catch((e) => die(e.message));
+      if (!ids.length) return console.error("no drafts of yours to make ready");
+      for (const id of ids) console.log(id);
+      return console.error(`${ids.length} task${ids.length === 1 ? "" : "s"} Ready — agents may take them`);
+    }
+    if (!f._.length) die("usage: passalong ready <id...> | --all");
+    for (const id of f._) {
+      const g = await passalong.ready(id).catch((e) => die(e.message));
+      console.error(`${g.meta.id} is Ready — an agent may take it`);
+    }
+  },
+
   async pull(f) {
     const ref = f._[0] || die("usage: passalong pull <id|link>");
-    const { markdown, path, from } = await passalong.pull(ref).catch((e) => die(e.message));
+    const { guide, markdown, path, from } = await passalong.pull(ref).catch((e) => die(e.message));
     process.stdout.write(markdown);
     console.error(`\npulled from ${from} → ${path}`);
+    await listFollowUps(guide.meta);
   },
 
   /**
@@ -165,6 +334,7 @@ const commands = {
     // Saying nothing here would be the silence the whole hop exists to end: you would have the
     // guide, believe you had answered for it, and the sender would still be waiting.
     else console.error("not taken — sync is off, so nobody was told (run `passalong login`)");
+    await listFollowUps(r.guide.meta);
   },
 
   /**
@@ -471,11 +641,82 @@ const commands = {
           `could not register MCP server automatically (${msg.trim()}).\n  run: claude mcp add passalong -- passalong mcp`,
         );
     }
+    // The two hooks that keep an agent on what it holds: told at session start, and stopped once
+    // before ending with work nobody has handed in. Merged into the user's settings, not written
+    // over them, and a no-op when they are already there.
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    try {
+      const { withHooks, withStatusLine } = await import("../src/hooks.js");
+      const before = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
+      const after = withStatusLine(withHooks(before));
+      if (before.statusLine && before.statusLine.command !== "passalong now --statusline")
+        console.error(
+          "you already have a status line, so it was left alone. To show Passalong in it, call `passalong now --statusline` from your script",
+        );
+      if (JSON.stringify(after) === JSON.stringify(before)) console.error("Claude Code hooks already installed");
+      else {
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, `${JSON.stringify(after, null, 2)}\n`);
+        console.error(`installed Claude Code hooks (session start, stop) and status line → ${settingsPath}`);
+      }
+    } catch (err) {
+      console.error(`could not install Claude Code hooks (${err.message}); ${settingsPath} left as it was`);
+    }
     if (!api.loggedIn())
       console.error("sync is off; run `passalong login` when you want guides to follow you across machines");
     console.error('done. In Claude Code, say "pass this along" at the end of a task, or run /passalong-capture.');
   },
 
+  /**
+   * What this worktree holds and what is waiting. `--hook session|stop` is the form the Claude
+   * Code hooks from `setup` call (src/hooks.js): it prints only what the hook protocol reads, and
+   * nothing at all when anything goes wrong — a hook must never get in the way of a session.
+   */
+  async now(f) {
+    const { nowText, statusText, stopVerdict } = await import("../src/hooks.js");
+    // The status line: printed from a cache, refreshed behind it. Claude Code cancels a status
+    // line still running when the next update comes, so this never waits on the network.
+    if (f.statusline) return statusLine(f);
+    if (f["statusline-refresh"]) {
+      const cwd = typeof f["statusline-refresh"] === "string" ? f["statusline-refresh"] : process.cwd();
+      try {
+        const r = await passalong.now({ cwd });
+        writeStatus(cwd, statusText({ held: r.held, needs: r.needs, ready: r.waiting.ready }));
+      } catch {}
+      return;
+    }
+    if (!f.hook) {
+      const r = await passalong.now();
+      console.log(nowText(r) || "Nothing held here, and nothing waiting.");
+      return;
+    }
+    try {
+      let input = {};
+      if (f.hook === "stop" && !process.stdin.isTTY) {
+        let raw = "";
+        for await (const chunk of process.stdin) raw += chunk;
+        input = JSON.parse(raw || "{}");
+      }
+      if (!api.loggedIn()) return;
+      const r = await Promise.race([
+        passalong.now(),
+        new Promise((_, no) => setTimeout(() => no(new Error("timeout")), 5000)),
+      ]);
+      if (f.hook === "session") {
+        const text = nowText(r);
+        if (text)
+          console.log(
+            JSON.stringify({
+              hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: text },
+            }),
+          );
+      } else if (f.hook === "stop") {
+        const v = stopVerdict({ held: r.held, input });
+        if (v) console.log(JSON.stringify(v));
+      }
+    } catch {}
+  },
+
   async mcp() {
     const { serve } = await import("../src/mcp.js");
     await serve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.3.2",
+  "version": "0.6.0",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",
@@ -35,7 +35,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:e2e": "PASSALONG_E2E_API=${PASSALONG_E2E_API:-http://localhost:3001} node --test test/task-flow.e2e.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/skill/SKILL.md

@@ -34,12 +34,13 @@ session's history. Write for execution, not for permanence.
    team's members and their handles. It prints the guide id on stdout and the share link (and
    who it was handed to) on stderr.
 
-   **If this session started from a passalong guide** — you ran `passalong start` or `pull` on an
-   id, or an agent opened one — and what you are capturing is what doing it taught you, add
-   `--follows <that id>`. The original then lists this one as a follow-up. That is the case when
-   you departed from it: changed or skipped a Step, adapted an `ASSUMES` for this stack, found the
-   fix a failing guide did not have, or hit a Gotcha it does not list. If it worked exactly as
-   written there is nothing to capture — say so with `passalong works <id>` instead.
+   **If what you are capturing is more context for an existing guide** — a missing detail, a step
+   that needed explaining, what changed since, what you found doing it — add `--follows <that id>`.
+   That publishes it as a follow-up: its own guide, listed under the original, and handed to
+   whoever opens the original, person or agent. 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
+   `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
    Passalong MCP server. `start` rather than `pull` on purpose: it takes the handoff as well as
@@ -56,7 +57,7 @@ each. Absent means `transfer`, which is what every guide written before bug repo
 
 | kind | what it is | what the receiver does |
 | --- | --- | --- |
-| `transfer` (default) | finished work to repeat somewhere else | follows the **Steps** |
+| `transfer` (or no `kind:` line) | finished work to repeat somewhere else | follows the **Steps** |
 | `bug` | a defect to fix where it is | fixes it — **Reproduce** shows the problem, it is not a procedure to apply |
 
 To file bugs you found but are not fixing, call `file_bugs` with all of them in one call — it

package/src/api.js

@@ -46,10 +46,14 @@ async function call(path, { method = "GET", body, auth = true, raw = false } = {
   if (!res.ok) {
     const text = await res.text();
     let message = text;
+    let parsed = {};
     try {
-      message = JSON.parse(text).message || text;
+      parsed = JSON.parse(text);
+      message = parsed.message || text;
     } catch {}
-    throw new ApiError(res.status, message || res.statusText);
+    // The whole answer rides along: a refusal can carry `next`, `say` or `holder`, which is what
+    // an agent needs to decide what to do instead.
+    throw Object.assign(new ApiError(res.status, message || res.statusText), { body: parsed });
   }
   return raw ? res.text() : res.json();
 }
@@ -91,6 +95,12 @@ export const createReport = (body) => call("/v1/reports", { method: "POST", body
 /** One report and the issues filed under it, grouped by product area. */
 export const report = (id) => call(`/v1/reports/${encodeURIComponent(id)}`);
 export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
+/**
+ * A guide's follow-ups, one level down. `markdown` adds each one's content, oldest first and
+ * capped server-side; neither form counts as opening them.
+ */
+export const children = (id, { markdown = false } = {}) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/children${q({ markdown: markdown ? "1" : "" })}`);
 export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
 export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
@@ -98,6 +108,28 @@ export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
 export const verdict = (id, ok, note = "") =>
   call(`/v1/guides/${id}/verdict`, { method: "PUT", body: { ok, note } });
 
+export const tasks = () => call("/v1/tasks");
+export const nextTask = (body) => call("/v1/tasks/next", { method: "POST", body });
+export const taskProgress = (id, body) =>
+  call(`/v1/tasks/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
+export const finishTask = (id, body) =>
+  call(`/v1/tasks/${encodeURIComponent(id)}/finish`, { method: "POST", body });
+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: {} });
+/** 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");
+export const take = (body) => call("/v1/take", { method: "POST", body });
+export const progress = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
+export const handIn = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/hand_in`, { method: "POST", body });
+export const pass = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/pass`, { method: "POST", body });
 export const ack = (id, taken, note = "") =>
   call(`/v1/guides/${id}/ack`, { method: "PUT", body: { taken, note } });
 

package/src/capture.js

@@ -17,6 +17,23 @@ function git(cwd, ...args) {
   }
 }
 
+/**
+ * One repo, written one way, so a task and the agent asking for work agree on what it is called.
+ * A remote URL becomes `owner/repo` whichever form it came in; anything else is kept, lowercase.
+ * Mirrors `repoKey()` in apps/api/src/claims.ts, which normalises what it stores the same way.
+ */
+export function repoKey(raw) {
+  let s = String(raw ?? "")
+    .trim()
+    .toLowerCase();
+  s = s.replace(/\/+$/, "").replace(/\.git$/, "");
+  const url = /^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?[^:/]+[:/](.+\/[^/]+)$/.exec(s);
+  if (url && (s.includes("://") || s.includes("@"))) {
+    return url[1].split("/").filter(Boolean).slice(-2).join("/");
+  }
+  return s;
+}
+
 /** What we can infer about the current context without reading any session. */
 export function context(cwd = process.cwd()) {
   const root = git(cwd, "rev-parse", "--show-toplevel");
@@ -30,13 +47,36 @@ export function context(cwd = process.cwd()) {
   const files = root
     ? git(cwd, "diff", "--name-only", "HEAD~5..HEAD").split("\n").filter(Boolean)
     : [];
-  return { root, name, branch, author, commits, changed, files };
+  // The repo as the task queue names it: its remote when it has one, because two worktrees of one
+  // repo have two folder names and one remote. The folder name when there is no remote.
+  const repo = root ? repoKey(git(cwd, "remote", "get-url", "origin") || name) : "";
+  return { root, name, repo, branch, author, commits, changed, files };
+}
+
+/**
+ * A task draft from one sentence: the sentence as the title and the Goal, the rest left to fill.
+ *
+ * `target_context` defaults to the repo this runs in, because that is the likeliest repo a task
+ * written from inside one is for — and it is in the editor, in the frontmatter, for the author
+ * to change before it goes anywhere. Outside a repo it stays empty, which is a task for no repo.
+ */
+export function taskScaffold(sentence, cwd = process.cwd()) {
+  const c = context(cwd);
+  const md = template({
+    kind: "task",
+    title: sentence,
+    author: c.author,
+    source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
+    target_context: c.repo,
+  });
+  return md.replace(/^## Goal\n/m, `## Goal\n${sentence}\n`);
 }
 
 /** A draft pre-filled with repo facts. Recent activity is appended as a comment for reference. */
 export function scaffold(cwd = process.cwd()) {
   const c = context(cwd);
   let md = template({
+    kind: "transfer",
     title: "",
     author: c.author,
     source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,

package/src/guide.js

@@ -35,11 +35,12 @@ export const SETTABLE = ["draft", "published", "consumed"];
  *
  *   transfer  work that is finished here and should be repeated there — follow the Steps
  *   bug       something broken there — do NOT follow anything; fix it
+ *   task      work nobody has done yet — do what Goal asks, done when Acceptance holds
  *
  * A guide with no `kind` is a transfer guide: every guide written before this existed is one,
  * and defaulting the other way would turn them all into bug reports.
  */
-export const KINDS = ["transfer", "bug"];
+export const KINDS = ["transfer", "bug", "task"];
 
 // Body sections in the order a guide should present them. The heading text is what the
 // receiving agent keys on, so keep these stable.
@@ -98,13 +99,29 @@ export const BUG_LEAD =
   "> **Bug report.** The steps under Reproduce show the problem \u2014 they are not a fix to " +
   "apply. Fix what Problem describes, then check Verification.";
 
+/**
+ * A task's sections: a brief for work nobody has done yet, written before it starts.
+ *
+ * `Acceptance` is the section that matters. It is what a person checks the finished work against
+ * before approving it, so a task without one has no way to be done — which is why it is required.
+ * There is no `Steps`: the agent that takes a task works out how, and what it did comes back as a
+ * transfer guide, which is where Steps belong.
+ */
+export const TASK_SECTIONS = ["Goal", "Context", "Constraints", "Acceptance", "Out of scope"];
+
 /** The sections a guide of this kind presents, in order. */
 export function sectionsFor(kind) {
-  return kind === "bug" ? BUG_SECTIONS : SECTIONS;
+  if (kind === "bug") return BUG_SECTIONS;
+  if (kind === "task") return TASK_SECTIONS;
+  return SECTIONS;
 }
 
 /** The sections it cannot be published without. */
-const REQUIRED = { transfer: ["Problem", "Steps"], bug: ["Problem", "Reproduce"] };
+const REQUIRED = {
+  transfer: ["Problem", "Steps"],
+  bug: ["Problem", "Reproduce"],
+  task: ["Goal", "Acceptance"],
+};
 
 // Fields that hold a list of strings. Everything else is a plain string.
 /**
@@ -132,7 +149,7 @@ export function tagList(raw) {
   return [...new Set(list.map(tag).filter(Boolean))];
 }
 
-const LIST_FIELDS = new Set(["stack_assumptions", "tags"]);
+const LIST_FIELDS = new Set(["stack_assumptions", "tags", "blocked_by"]);
 
 // IDs are short enough to type and say out loud. 8 chars from a 31-letter alphabet with the
 // look-alikes removed (0/o, 1/l/i) is ~40 bits: plenty for addressing, not a secret.
@@ -225,7 +242,9 @@ export function parseFrontmatter(text) {
       listKey = null;
     }
   }
-  for (const k of LIST_FIELDS) if (meta[k] === undefined) meta[k] = [];
+  // 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] = [];
   // 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);
@@ -245,6 +264,11 @@ const META_ORDER = [
   "created",
   "author",
   "source_context",
+  // Tasks only: the repo the work is for. Optional — a task without one is not tied to a repo.
+  "target_context",
+  // Tasks only: the tasks this one waits for, by id. It is not handed to an agent until a person
+  // has approved each of them. See migrations/0022_blocks.sql.
+  "blocked_by",
   // Where it came from, in the two senses a guide has one: `source_context` is the repo and branch
   // it was written in, `parent` is the guide it was written *out of*.
   "parent",
@@ -451,7 +475,10 @@ 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.
   if (meta.kind === "bug") return bugTemplate(meta);
+  if (meta.kind !== "transfer") return taskTemplate(meta);
   const body = [
     "## Problem",
     "<!-- passalong: What was broken or needed, in two or three sentences. -->",
@@ -480,6 +507,7 @@ export function template(meta = {}) {
       stack_assumptions: [],
       tags: [],
       ...meta,
+      kind: "transfer",
     },
     body,
   });
@@ -522,6 +550,46 @@ function bugTemplate(meta = {}) {
   });
 }
 
+/**
+ * One task, as a guide: the brief an agent takes before any work exists.
+ *
+ * `target_context` is the repo the work is for, and it is left empty rather than defaulted to the
+ * repo the task was written in: a task written in one repo is often for another, and one aimed at
+ * the wrong repo is picked up by the wrong agent.
+ */
+function taskTemplate(meta = {}) {
+  const body = [
+    "## Goal",
+    "<!-- passalong: What should be true when this is done, in two or three sentences. -->",
+    "",
+    "## Context",
+    "<!-- passalong: What the agent needs to know first: where the code lives, what exists already, links. -->",
+    "",
+    "## Constraints",
+    "<!-- passalong: What must not change, what to use or avoid, limits on scope or approach. -->",
+    "",
+    "## Acceptance",
+    "<!-- passalong: How a person checks it is done: commands, expected output, behaviour to see. -->",
+    "",
+    "## Out of scope",
+    "<!-- passalong: What looks related but is not part of this task. -->",
+  ].join("\n");
+  return serialize({
+    meta: {
+      title: "",
+      kind: "task",
+      author: "",
+      source_context: "",
+      target_context: "",
+      status: "draft",
+      stack_assumptions: [],
+      tags: [],
+      ...meta,
+    },
+    body,
+  });
+}
+
 /** Strip the template comments so an untouched section reads as empty rather than as a prompt. */
 export function stripPlaceholders(body) {
   return body.replace(/^<!-- passalong:.*?-->\n?/gm, "").trim();