@feigi/fleet-ctl 3.81.6 → 3.82.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.81.6",
+  "version": "3.82.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/pull.mjs

@@ -54,9 +54,16 @@
 //   1  inflight   `inflight.sh <N>`: anything but exit 0 is taken.
 //   2  issue      `gh issue view <N> --json title,body,comments,labels,createdAt`
 //                 written to `<scratch>/impl-<N>/issue.json`. Without the
-//                 `ready-for-agent` label the ticket is gone. The distilled
-//                 brief and the paths the router's extractor finds in it are
-//                 printed.
+//                 `ready-for-agent` label the ticket is gone. A comment with a
+//                 `## Ruling` or `## Triage` heading line and no `## Agent
+//                 Brief` one, newer than the last comment that has one or on a
+//                 ticket with none, is a stranded ruling: the newest is named,
+//                 with its URL, in a comment, and the label replaces
+//                 `ready-for-agent` with `ready-for-human`, as a Q2 cause does;
+//                 a newest one `gh` printed with no URL is exit 2, nothing
+//                 posted.
+//                 Otherwise the distilled brief and the paths the router's
+//                 extractor finds in it are printed.
 //   3  Q1 staleness   `gone` / `present` (each with `--path <p>` and the string
 //                 as the text) run `staleness.mjs --path <p> --gone|--present --
 //                 <string>`; `none <why>` and `done` end the question. Exit 1
@@ -127,7 +134,7 @@ import { gitEnv } from "./git-env.mjs";
 import { isCLI } from "./is-cli.mjs";
 import { memberTokens, premisesOf, tierValues } from "./ledger-grammar.mjs";
 import { sessionFromReceipt } from "./phase0-receipt.mjs";
-import { briefPaths, briefText, outOfScope } from "./ticket-router.mjs";
+import { briefPaths, briefText, outOfScope, strandedRuling } from "./ticket-router.mjs";
 
 const NAME = "pull";
 const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -169,8 +176,18 @@ function handsParts(text) {
   return { cause: null, line: "" };
 }
 
-/** The comment, and the label that replaces `ready-for-agent`, for a Q2 answer other than `decided`. */
+/**
+ * The comment, and the label that replaces `ready-for-agent`, for a Q2 answer
+ * other than `decided` — or, for `stranded-ruling`, for a ruling or triage
+ * comment newer than the brief, `text` naming its heading line and its URL.
+ */
 export function relabel(token, text) {
+  if (token === "stranded-ruling") {
+    return {
+      label: HUMAN,
+      comment: `${RELABELLED} a ruling or triage comment is newer than the brief, and the Pull does not read it: ${text}. To make it the brief, rename its heading to \`## Agent Brief — ruling\` and drop anything that is not decided scope, or delete it; then restore \`${READY}\`.`,
+    };
+  }
   if (token === "needs-triage") {
     return {
       label: TRIAGE,
@@ -802,6 +819,11 @@ class Pull {
       return this.stop(`cannot write ${this.p.issue}: ${e.message}`);
     }
     if (!issue.labels.some((l) => l?.name === READY)) return this.leave("relabelled elsewhere");
+    const stranded = strandedRuling(issue);
+    if (stranded !== null) {
+      if (typeof stranded.url !== "string") return this.stop(`gh issue view printed a ruling comment with no url: "${stranded.heading}"`);
+      return this.relabelled("stranded-ruling", `"${stranded.heading}" ${stranded.url}`);
+    }
     this.log.push(...this.brief());
     st.stage = "staleness";
     return null;
@@ -1078,9 +1100,15 @@ class Pull {
       st.stage = "collision";
       return null;
     }
+    return this.relabelled(token, text);
+  }
+
+  // Posts the cause's comment and swaps `ready-for-agent` for its label. One
+  // comment per cause: an edit that failed after its comment landed is run
+  // again without a second comment.
+  relabelled(token, text) {
+    const { st } = this;
     const { label, comment } = relabel(token, text);
-    // One comment per cause: an edit that failed after its comment landed is
-    // answered again without a second comment.
     if (st.commented !== comment) {
       const c = this.gh("relabel", ["issue", "comment", String(st.ticket), "--body", comment]);
       if (c.status !== 0) return this.stop(withText(`gh issue comment failed (${c.how})`, c));

package/scripts/ticket-router.mjs

@@ -80,16 +80,39 @@ const DAY_MS = 86_400_000;
 // metrics — every one free, deterministic and known before dispatch
 // ---------------------------------------------------------------------------
 
+/** An `## Agent Brief` heading line: what marks the comment the brief is taken from. */
+const AGENT_BRIEF = /^## Agent Brief/m;
+
 /** The brief: the last comment carrying an `## Agent Brief` heading line, else the body. */
 export function briefText(issue) {
   const comments = Array.isArray(issue.comments) ? issue.comments : [];
   for (let i = comments.length - 1; i >= 0; i--) {
     const body = String(comments[i]?.body ?? "");
-    if (/^## Agent Brief/m.test(body)) return body;
+    if (AGENT_BRIEF.test(body)) return body;
   }
   return String(issue.body ?? "");
 }
 
+/** A ruling or triage heading line: what a decision posted outside an `## Agent Brief` comment is headed with. */
+const RULING_HEADING = /^## (?:Ruling|Triage).*$/m;
+
+/**
+ * The newest comment with a ruling or triage heading line and no `## Agent
+ * Brief` heading line that comes after the last comment `briefText` takes the
+ * brief from, or after none when there is no such comment, as its first ruling
+ * or triage heading line and its `url`; null when none is.
+ */
+export function strandedRuling(issue) {
+  const comments = Array.isArray(issue.comments) ? issue.comments : [];
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const body = String(comments[i]?.body ?? "");
+    if (AGENT_BRIEF.test(body)) return null;
+    const heading = RULING_HEADING.exec(body);
+    if (heading !== null) return { heading: heading[0], url: comments[i].url };
+  }
+  return null;
+}
+
 /** The line span `[at, end)` of `lines`' `Out of scope` section, heading to the next heading of its level or above; null when there is none. */
 function outOfScopeSpan(lines) {
   const at = lines.findIndex((l) => /^#{1,6}\s*out of scope\b/i.test(l));

package/skills/run-team/references/pull.md

@@ -52,6 +52,20 @@ terminating in exactly one dispatch or an empty shortlist:
    scope` sequencing wherever that section is found. Then judge **decided?**
    — never size.
 
+   **A ruling the brief does not carry stops the Pull first.** The brief is
+   the last `## Agent Brief` comment, else the issue body, so a decision posted
+   under another heading never reaches any question the Pull asks. A comment
+   with a `## Ruling` or `## Triage` heading line and no `## Agent Brief`
+   heading line that is newer than the last `## Agent Brief` comment, or on a
+   ticket with none, is a stranded ruling. `pull.mjs` checks for one right
+   after the `ready-for-agent` label check, before printing the brief or
+   asking anything. On a hit it posts one comment naming the newest stranded
+   comment's heading line and URL, which says to rename that heading to
+   `## Agent Brief — ruling` and drop anything that is not decided scope, or
+   to delete the comment, then restore `ready-for-agent`. It then swaps
+   `ready-for-agent` for `ready-for-human` and leaves with `LEFT #N:
+   relabelled ready-for-human: stranded-ruling`.
+
    **Still live?** A backlog ticket's claims rot. Before `decided?`, settle the
    ticket's central claim against `origin/main` — never the working tree, never
    the ticket's own line numbers, which drift. One `git show origin/main:<file>`