@tablation/crew 0.24.0 → 0.25.0

package/crew.example.yaml

@@ -100,6 +100,9 @@ routes:
     # Only needed for a self-hosted tracker.
     # baseUrl: "https://app.tablation.com"
     apiKey: "REPLACE_ME"             # or omit if `ship.apiKey` covers this workspace too
+    # With no apiKey (and no apiKeyFile/apiKeyVar) crew reads CREW_API_KEY from
+    # its process environment. Under launchd that must be set in the job's own
+    # environment, not exported from an interactive shell.
 
     # Where release state should be SHOWN is a fact about this machine and the
     # person watching it, not about the code — so unlike every other hook,

package/dist/cli.js

@@ -1065,8 +1065,10 @@ function resolveApiKey(r) {
       if (m) return (m[1] ?? "").trim().replace(/^["']|["']$/g, "");
     }
   }
+  const fromEnv = process.env.CREW_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
   throw new ConfigError(
-    `route "${r.route}": no API key (apiKey, or ${r.apiKeyVar ?? "VAR"} in ${r.apiKeyFile ?? "<unset>"})`
+    `route "${r.route}": no API key (looked for, in order: apiKey; ${r.apiKeyVar ?? "VAR"} in ${r.apiKeyFile ?? "<unset>"}; CREW_API_KEY in the environment)`
   );
 }
 var KEYCHAIN_ELIGIBLE_ROUTES = /* @__PURE__ */ new WeakSet();
@@ -1475,6 +1477,7 @@ var State = class _State {
     const failed = `.deploy-failed-sha-${suffix}`;
     const gateFailed = `.test-gate-failed-${suffix}`;
     const gateReported = `.test-gate-reported-${suffix}`;
+    const heldReported = `.release-held-${suffix}`;
     const read = (f) => {
       try {
         return readFileSync3(this.path(f), "utf8").trim() || null;
@@ -1525,6 +1528,20 @@ var State = class _State {
         rmSync(this.path(gateFailed), { force: true });
       },
       /** Whether the board was already told about this head's red gate. */
+      heldReported: () => {
+        try {
+          return readFileSync3(this.path(heldReported), "utf8").replace(/\n$/, "") || null;
+        } catch {
+          return null;
+        }
+      },
+      noteHeldReported: (signature) => {
+        writeFileSync(this.path(heldReported), `${signature}
+`);
+      },
+      clearHeldReported: () => {
+        rmSync(this.path(heldReported), { force: true });
+      },
       testGateReported: (sha) => read(gateReported) === sha,
       noteTestGateReported: (sha) => {
         writeFileSync(this.path(gateReported), `${sha}
@@ -3934,15 +3951,18 @@ function blockerInfoMap(tickets, extra = []) {
 }
 function computeBlockedIds(tickets, info) {
   const blocked = /* @__PURE__ */ new Set();
-  for (const t of tickets) {
-    const unresolved = (t.blocked_by ?? []).some((id) => {
-      const status2 = info[id]?.status;
-      return status2 !== void 0 && !RESOLVED_STATUSES.has(status2);
-    });
-    if (unresolved) blocked.add(t.id);
-  }
+  for (const t of tickets) if (unresolvedBlockers(t, info).length > 0) blocked.add(t.id);
   return blocked;
 }
+function unresolvedBlockers(t, info) {
+  return (t.blocked_by ?? []).filter((id) => {
+    const status2 = info[id]?.status;
+    return status2 !== void 0 && !RESOLVED_STATUSES.has(status2);
+  });
+}
+function describeUnresolved(t, info) {
+  return unresolvedBlockers(t, info).map((id) => `${info[id]?.issue_tag ?? info[id]?.issue_id ?? "?"} (${info[id]?.status ?? "unknown"})`).join(", ");
+}
 function sweepDiagnostics(tickets, info) {
   const dangling = [];
   const selfBlocked = [];
@@ -4258,9 +4278,12 @@ function buildingRoleHasWork(role, i) {
   }
   return { hasWork: false, reason: "nothing startable and no new comments" };
 }
+function qaCandidates(i) {
+  return withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds) && !i.blocked.has(t.id));
+}
 function qaRoleHasWork(i) {
   if (!i.seats.qa) return { hasWork: false, reason: "this ship does not crew that role" };
-  const n = withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds)).length;
+  const n = qaCandidates(i).length;
   return n > 0 ? { hasWork: true, reason: `${n} ticket(s) awaiting or in verification` } : { hasWork: false, reason: "nothing awaiting verification" };
 }
 function triageRoleHasWork(i) {
@@ -4276,7 +4299,7 @@ function roleHasWork(role, i) {
   return buildingRoleHasWork(role, i);
 }
 function roleCandidates(role, i) {
-  if (role === "qa") return withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds));
+  if (role === "qa") return qaCandidates(i);
   if (role === "triage") return triageSlice(i.tickets, i.seats.triage, i.workModes).filter((t) => !isHeld(t, i.holds));
   if (role === "pair") return [];
   const me = i.seats[role];
@@ -4610,15 +4633,30 @@ function qaDigest(i) {
     const repo = i.dirFor ? dir ?? "**NO CHECKOUT**" : "";
     return `| ${displayKey2(t)} | ${repo} | ${modeCell(t, i)} | ${t.status} | ${builtBy(t)} | ${who(t, i)} | ${filedBy(t, i)} | ${t.severity ?? "\u2014"} | ${t.priority ?? "\u2014"} | p${effectivePriority(t)} | ${branchCell(t)} | ${worktreeCell(t)} | ${t.updated_at.slice(0, 16)}Z | ${lastComment(i, t.id)} | ${n > 0 ? `**${n} new**` : "\u2014"} |`;
   };
+  const waiting = i.tickets.filter((t) => (t.status === "qa" || t.status === "fixed") && i.blocked.has(t.id));
+  const takeable = (status2) => i.tickets.filter((t) => t.status === status2 && !i.blocked.has(t.id));
+  const waitingTable = waiting.length === 0 ? "" : `
+### Waiting on blockers \u2014 not yours to verify yet
+
+A \`fixed\` or \`qa\` ticket whose \`Blocked by\` names something not yet resolved
+(\`verified\`, \`closed_deployed\`, \`closed_wont_fix\` or \`closed_duplicate\`) is held out of
+verification: its change needs the blocker released first. It becomes yours on
+the first poll after the last blocker resolves. No one needs to change the ticket.
+
+| ticket | status | blocked by |
+|---|---|---|
+${waiting.map((t) => `| ${displayKey2(t)} | ${t.status} | ${blockers(t, i)} |`).join("\n")}
+`;
   return stream([
     "## Current queue \u2014 built for you by the poll\n",
     '\nAlready filtered to your lane: every ticket at `qa` ("Verification" \u2014\nyours, unfinished) or `fixed` (nobody has checked it yet), from both\nbuilding lanes. Ticket bodies are deliberately omitted: fetch the full\nrecord and the comments of the one ticket you actually pick up. **Do not\nre-fetch the whole tracker.** This digest comes from the same API call the\npoll just made, moments ago.\n',
     '\n"new since last poll" counts comments from someone other than you since\nthe poll watermark \u2014 the same signal that woke this run.\n',
     "\n**`repo` is the checkout the ticket's work happens in** \u2014 an area spans\nseveral repositories, so the worktree you verify in sits beside THAT\ndirectory, not beside whichever one this session started in. A ticket\nmarked **NO CHECKOUT** is not yours: this ship has no clone of its\nrepository, and another ship may serve it.\n\n**`branch` is that repository's own branch for the ticket**, found there\nrather than derived. **`<name> (on origin only)`** means another ship built it\nand pushed it: it is testable \u2014 cut a worktree from the remote branch\n(`git worktree add <worktree> <name>`). **MISSING** means the branch is gone\nlocally AND on the remote, so there is nothing left to verify \u2014 say so on the ticket. A `\u2014` means the branch\ncould not be looked for at all, because the repo has no checkout here.\n\n**`worktree` is where that branch should be checked out**, `<repo>/../<worktree>`\n\u2014 rendered the same way the dev/design digest computes it, so you land in\nthe same directory the building lane used.\n",
     "\n### Still in verification \u2014 yours, unfinished (take these first)\n",
-    table(i.tickets.filter((t) => t.status === "qa"), i, header, row),
+    table(takeable("qa"), i, header, row),
     "\n### Awaiting verification, in pick order\n",
-    table(i.tickets.filter((t) => t.status === "fixed"), i, header, row)
+    table(takeable("fixed"), i, header, row),
+    ...waitingTable ? [waitingTable] : []
   ]);
 }
 
@@ -6562,10 +6600,16 @@ function checkGuards(cwd, base = "main") {
     detail: `working tree has ${changes.length} change(s)${untrackedNote}: ${names}${more}`
   };
 }
+function heldByBlockers(tickets, verifiedStatus, info) {
+  if (!info) return [];
+  return tickets.filter((t) => t.status === verifiedStatus && unresolvedBlockers(t, info).length > 0).map((ticket) => ({ ticket, blockers: describeUnresolved(ticket, info) }));
+}
+var describeHeld = (held) => held.map((h) => `${h.ticket.issue_tag ?? h.ticket.issue_id} held: blocked by ${h.blockers}`);
 var CHANGELOG_LINE = /^Changelog:[ \t]*(.*)$/gm;
 var BUMP_LINE = /^Bump:[ \t]*(major|minor|patch)\b/gim;
-function planMerge(cwd, tickets, contract, lastReleased, branchFor = (t) => branchForIssue(cwd, t.issue_id), base = "main") {
-  const verified = tickets.filter((t) => t.status === contract.statuses.verified).sort((a, b) => Number.parseInt(a.issue_id.replace(/^\D+/, ""), 10) - Number.parseInt(b.issue_id.replace(/^\D+/, ""), 10));
+function planMerge(cwd, tickets, contract, lastReleased, branchFor = (t) => branchForIssue(cwd, t.issue_id), base = "main", blockerInfo) {
+  const held = new Set(heldByBlockers(tickets, contract.statuses.verified, blockerInfo).map((h) => h.ticket.id));
+  const verified = tickets.filter((t) => t.status === contract.statuses.verified && !held.has(t.id)).sort((a, b) => Number.parseInt(a.issue_id.replace(/^\D+/, ""), 10) - Number.parseInt(b.issue_id.replace(/^\D+/, ""), 10));
   return verified.map((ticket) => {
     const branch = branchFor(ticket);
     if (!branch) {
@@ -6683,12 +6727,13 @@ function decideRelease(cwd, tickets, contract, opts = {}) {
   const lastTag = latestReleaseTag(cwd, pattern, "HEAD");
   const lastReleased = lastTag ? tagCommit(cwd, lastTag) : null;
   const head = resolve2(cwd, "HEAD") ?? "";
-  const merges = block ? [] : planMerge(cwd, tickets, contract, lastReleased, opts.branchFor ?? ((t) => branchForIssue(cwd, t.issue_id)), base);
+  const merges = block ? [] : planMerge(cwd, tickets, contract, lastReleased, opts.branchFor ?? ((t) => branchForIssue(cwd, t.issue_id)), base, opts.blockerInfo);
   const unreleasedCommits = lastReleased ? countCommits(cwd, `${lastReleased}..HEAD`) : 0;
   const unreleasedWork = lastReleased ? (gitOk(cwd, ["log", "--format=%s", `${lastReleased}..HEAD`]) ?? "").split("\n").filter((l) => l && !RELEASE_COMMIT_SUBJECT.test(l)).length : 0;
   return {
     block,
     merges,
+    held: heldByBlockers(tickets, contract.statuses.verified, opts.blockerInfo),
     head,
     lastTag,
     lastReleased,
@@ -7293,6 +7338,17 @@ function openReleaseCheckout(o) {
   }
   return { dir, branch, close };
 }
+function reportHeld(o, held) {
+  if (held.length === 0) {
+    o.state?.clearHeldReported?.();
+    return;
+  }
+  const lines = describeHeld(held);
+  const signature = lines.join("\n");
+  if (o.dryRun || o.state?.heldReported?.() === signature) return;
+  for (const line of lines) o.emit.emit(line, { step: "release" });
+  o.state?.noteHeldReported?.(signature);
+}
 async function runRelease(o) {
   const scoped = (msg) => o.scope ? `${o.scope}: ${msg}` : msg;
   const tagPattern = o.repo.release.tagPattern ?? "v*";
@@ -7301,11 +7357,13 @@ async function runRelease(o) {
   const decision = decideRelease(o.cwd, o.tickets, o.contract, {
     tagPattern,
     base: o.repo.branch.base,
+    blockerInfo: o.blockerInfo,
     // CREW-1364: a branch another ship built and pushed at `fixed` exists
     // here only on the remote. Materialize it so the squash below has a ref.
     // A dry run only looks.
     branchFor: (t) => o.dryRun ? locateBranchForTicket(o.cwd, o.repo, t)?.branch ?? null : materializeBranchForTicket(o.cwd, o.repo, t)
   });
+  reportHeld(o, decision.held);
   if (!fresh.ok) {
     o.emit.error(scoped(`refusing to release \u2014 ${fresh.why}; a person has to reconcile the two`));
     return { merged: [], conflicts: [], deployed: false, stopped: fresh.why, decision };
@@ -11166,11 +11224,13 @@ ${changed2.map((c) => `  - ${c}
         releaseModes
       );
       reportUnplaceable(c.route, unplaceable, tracker.contract.statuses.verified, remit);
+      const blockerInfo = blockerInfoMap(all, await tracker.ticketsByIds(missingBlockerIds(all)));
       const outcome = await runRelease({
         cwd: target.dir,
         repo,
         contract: tracker.contract,
         tickets,
+        blockerInfo,
         emit: remit,
         scope,
         state: state.release(scope),
@@ -13187,6 +13247,17 @@ watermark:  ${state.watermark()}
 `);
         process.stdout.write(`releaser:   ${r.name} \u2014 ${await releaserLine(statusTracker, route.route, r.name, r.config.release)}
 `);
+      }
+      try {
+        const open = await statusTracker.openTickets();
+        const held = heldByBlockers(
+          open,
+          statusTracker.contract.statuses.verified,
+          blockerInfoMap(open, await statusTracker.ticketsByIds(missingBlockerIds(open)))
+        );
+        for (const line of describeHeld(held)) process.stdout.write(`release:    ${line}
+`);
+      } catch {
       }
       if (waiting) {
         process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",

package/prompts/default/personas/common.md

@@ -684,9 +684,42 @@ post. They record who filed the ticket and from where. The block lists a column
 only when this workspace has it, so a column it does not name is not yours to set.
 
 Name the ticket you were working when you noticed it in the new ticket's
-description. Only put it in the new ticket's `blocked by` column if your
-own ticket genuinely cannot proceed without the new one being fixed
-first — merely having noticed it nearby is not a dependency.
+description. Only add the new ticket to **your own ticket's** `blocked_by`
+(the column named `blocked by` in the Environment section) if your own
+ticket genuinely cannot proceed without the new one being fixed first —
+merely having noticed it nearby is not a dependency. The dependency always
+points from the ticket that waits to the ticket it waits on, never the
+other way round.
+
+### Work your ticket needs in another repository
+
+Out-of-scope breakage and **in-scope work that lives somewhere else** are
+different things. If your ticket's acceptance depends on a change in another
+repository (or on a change this repository cannot make), do not ship a
+stand-in for the missing piece and hand the ticket off. A stand-in whose UI,
+docs or hints promise behaviour the dependency has not delivered is a defect
+that QA passes and the release phase ships. Instead:
+
+1. File that work as its own ticket in the owning repository's project (the
+   Environment section names the projects and repos; if the owning repo is
+   not listed there, file it against the project and say which repo in the
+   description), setting `repo_id`, `project_id`, `filed_by_id` and
+   `ship_id` as in the filing block, and naming your ticket in its
+   description.
+2. Add the new ticket's id to **your own ticket's** `blocked_by`.
+3. Post a comment on your ticket naming each dependency and what it must
+   deliver.
+4. Set your ticket back to `accepted`. The poll's sweep parks it at
+   `blocked` and restores it to `accepted` once every blocker resolves.
+   In a `hybrid` project keep `assignee_id` as your own seat (an unassigned
+   hybrid ticket is off limits to every lane); in an `automatic` project
+   clear it as for any other re-queue.
+5. Leave the branch and worktree in place, committed and pushed if they hold
+   work, so the lane that resumes the ticket continues from them.
+
+Hand a ticket off as `fixed` only when the branch works against
+dependencies that are already released. A hand-off comment that says "worth
+separate tickets" for work the ticket needs is a hand-off that is not ready.
 
 ## Step 4 — you never merge, and you never deploy
 

package/prompts/default/personas/lane-design.md

@@ -82,6 +82,12 @@ stopping for this run, do the following instead:
     is actually blocked on the operator's input, not as a substitute for
     the ordinary ending above.
 
+  Before you post, check the comment: it must not name needed-but-unfiled
+  work. A design that depends on a change in another repository files that
+  ticket and links it in your ticket's `blocked_by` (see "Work your ticket
+  needs in another repository"), rather than listing it as a loose
+  follow-up.
+
   Either way, stop this ticket's work for this run once the flag is set and
   the comment posted. The operator reviews what you posted and takes it
   from there:

package/prompts/default/personas/lane-dev.md

@@ -24,4 +24,11 @@ release phase merges and ships it) or hands it back to you as `in_progress`
 with a comment saying what still fails. Take that bounce seriously — it is
 the only reading your work gets before it is deployed.
 
-**No extra steps.** Follow the shared policy as written.
+**Before you hand a ticket to QA, check the hand-off comment.** It must not
+name needed-but-unfiled work: anything the ticket's acceptance depends on in
+another repository is a filed ticket in your ticket's `blocked_by` (see "Work
+your ticket needs in another repository"), not a line saying "worth separate
+tickets". If it would name such work, the ticket goes back to `accepted`
+instead of forward to `fixed`.
+
+**No extra steps.** Otherwise follow the shared policy as written.

package/prompts/default/personas/lane-qa.md

@@ -117,6 +117,13 @@ human review, so "probably fine" is not a pass.
    Missing or stale docs are a reason to bounce the ticket back to the dev
    seat, with a comment naming the page that needs the change. If the
    repository names no such location, skip this check.
+7b. **Check the hand-off for needed-but-unfiled work.** If the dev or design
+   comment names work that is needed in another repository (or that this
+   repository cannot do) and no ticket for it exists in the ticket's
+   `blocked_by`, that is a bounce: say so in your comment and ask for the
+   ticket and the `blocked_by` link. A shipped stand-in whose UI, docs or
+   hints promise behaviour the dependency has not yet delivered is a defect
+   even if every test passes. Bounce it like any other failure (step 8).
 7a. **Ask whether the fix is covered.** A behaviour change with no test that
    would catch its regression is worth naming in your comment; whether it
    is worth bouncing the ticket over is your judgement, and depends on how

package/prompts/dev-qa/personas/common.md

@@ -666,9 +666,42 @@ post. They record who filed the ticket and from where. The block lists a column
 only when this workspace has it, so a column it does not name is not yours to set.
 
 Name the ticket you were working when you noticed it in the new ticket's
-description. Only put it in the new ticket's `blocked by` column if your
-own ticket genuinely cannot proceed without the new one being fixed
-first — merely having noticed it nearby is not a dependency.
+description. Only add the new ticket to **your own ticket's** `blocked_by`
+(the column named `blocked by` in the Environment section) if your own
+ticket genuinely cannot proceed without the new one being fixed first —
+merely having noticed it nearby is not a dependency. The dependency always
+points from the ticket that waits to the ticket it waits on, never the
+other way round.
+
+### Work your ticket needs in another repository
+
+Out-of-scope breakage and **in-scope work that lives somewhere else** are
+different things. If your ticket's acceptance depends on a change in another
+repository (or on a change this repository cannot make), do not ship a
+stand-in for the missing piece and hand the ticket off. A stand-in whose UI,
+docs or hints promise behaviour the dependency has not delivered is a defect
+that QA passes and the release phase ships. Instead:
+
+1. File that work as its own ticket in the owning repository's project (the
+   Environment section names the projects and repos; if the owning repo is
+   not listed there, file it against the project and say which repo in the
+   description), setting `repo_id`, `project_id`, `filed_by_id` and
+   `ship_id` as in the filing block, and naming your ticket in its
+   description.
+2. Add the new ticket's id to **your own ticket's** `blocked_by`.
+3. Post a comment on your ticket naming each dependency and what it must
+   deliver.
+4. Set your ticket back to `accepted`. The poll's sweep parks it at
+   `blocked` and restores it to `accepted` once every blocker resolves.
+   In a `hybrid` project keep `assignee_id` as your own seat (an unassigned
+   hybrid ticket is off limits to every lane); in an `automatic` project
+   clear it as for any other re-queue.
+5. Leave the branch and worktree in place, committed and pushed if they hold
+   work, so the lane that resumes the ticket continues from them.
+
+Hand a ticket off as `fixed` only when the branch works against
+dependencies that are already released. A hand-off comment that says "worth
+separate tickets" for work the ticket needs is a hand-off that is not ready.
 
 ## Step 4 — you never merge, and you never deploy
 

package/prompts/dev-qa/personas/lane-dev.md

@@ -23,4 +23,11 @@ release phase merges and ships it) or hands it back to you as `in_progress`
 with a comment saying what still fails. Take that bounce seriously — it is
 the only reading your work gets before it is deployed.
 
-**No extra steps.** Follow the shared policy as written.
+**Before you hand a ticket to QA, check the hand-off comment.** It must not
+name needed-but-unfiled work: anything the ticket's acceptance depends on in
+another repository is a filed ticket in your ticket's `blocked_by` (see "Work
+your ticket needs in another repository"), not a line saying "worth separate
+tickets". If it would name such work, the ticket goes back to `accepted`
+instead of forward to `fixed`.
+
+**No extra steps.** Otherwise follow the shared policy as written.

package/prompts/dev-qa/personas/lane-qa.md

@@ -104,6 +104,13 @@ human review, so "probably fine" is not a pass.
    Missing or stale docs are a reason to bounce the ticket back to the dev
    seat, with a comment naming the page that needs the change. If the
    repository names no such location, skip this check.
+7b. **Check the hand-off for needed-but-unfiled work.** If the dev or design
+   comment names work that is needed in another repository (or that this
+   repository cannot do) and no ticket for it exists in the ticket's
+   `blocked_by`, that is a bounce: say so in your comment and ask for the
+   ticket and the `blocked_by` link. A shipped stand-in whose UI, docs or
+   hints promise behaviour the dependency has not yet delivered is a defect
+   even if every test passes. Bounce it like any other failure (step 8).
 7a. **Ask whether the fix is covered.** A behaviour change with no test that
    would catch its regression is worth naming in your comment; whether it
    is worth bouncing the ticket over is your judgement, and depends on how