@mmerterden/multi-agent-pipeline 17.4.0 → 17.5.1

package/pipeline/scripts/base-branch-candidates.mjs

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+/**
+ * base-branch-candidates.mjs  -  collect every plausible base branch WITH the
+ * evidence behind it, rank them, and hand the picker a list it can show.
+ *
+ * Two failures this replaces, both reported from real runs.
+ *
+ * 1. The fetch can fail and the answer degrades silently. Step 3 ran
+ *    `git fetch origin` and then `git branch -r`. On a restricted network the
+ *    fetch fails and `git branch -r` still prints a full, confident list - the
+ *    remote-tracking cache, which may be weeks old or empty. Nothing in the
+ *    output said so, so a stale local guess was presented as the remote's
+ *    answer. Here the provenance is a required input, it rides on every
+ *    candidate, and the picker question has to say it.
+ *
+ * 2. The right base branch is usually derivable from the issue, and nothing
+ *    derived it. An issue that carries a target version, or that links a
+ *    separate issue representing the release, already names the branch on a
+ *    repo whose release branches encode the version. That is evidence, not a
+ *    rule: this module collects it, scores it, and stops. A human (or, in
+ *    autopilot, a recorded resolution) still chooses.
+ *
+ * WHY THE CONVENTION IS LEARNED RATHER THAN TABLED. Every repo spells its
+ * release branches differently and the spellings change. A table of prefixes
+ * would be wrong for most repos on the day it was written, and silently wrong
+ * afterwards. So the template is inferred from the branch names actually on the
+ * remote: find the branches that contain a version token, replace the token
+ * with a hole, and the most common resulting shape is this repo's convention.
+ * The inference is reported with its member count so a reader can see how much
+ * evidence it rests on.
+ *
+ * A PREDICTED BRANCH IS NEVER A CANDIDATE. If the learned template predicts a
+ * name that is not on the ref list, that fact is a note, never an option. An
+ * option the user picks has to be checkoutable; offering a name that does not
+ * exist moves the failure to Step 8 where it reads as a git error instead of a
+ * wrong answer here.
+ *
+ * Usage:
+ *   node base-branch-candidates.mjs --input <file.json> [--json]
+ *
+ * Exit codes: 0 = candidates produced, 1 = bad input, 2 = usage
+ *
+ * @module pipeline/scripts/base-branch-candidates
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { pathToFileURL } from "url";
+
+/**
+ * A version token in a branch name or a field value. Two, three or four
+ * numeric segments, separated by `.`, `_` or `-`, with an optional trailing
+ * qualifier that is NOT captured (a `-rc1` suffix still identifies the release).
+ */
+const VERSION_TOKEN = /(\d+)[._-](\d+)(?:[._-](\d+))?(?:[._-](\d+))?/;
+
+/** Weights. Kept as one table so the ranking is readable rather than derived. */
+export const WEIGHTS = {
+  issueVersionExact: 100,
+  linkedReleaseExact: 90,
+  linkedReleaseAuthoritative: 110,
+  versionPartial: 60,
+  recent: 40,
+  recentRecencyMax: 10,
+  repoDefault: 12,
+  sortDevelop: 30,
+  sortRelease: 20,
+  sortMain: 10,
+};
+
+/**
+ * Branch families the legacy sort order knew about - the floor, below every piece of
+ * real evidence. The three stay ABOVE `repoDefault` on purpose: Step 3 has always led
+ * with `develop` on a repo that has one, and a weights table that quietly reordered
+ * that would change the recommended row on every repo whose default is `main`.
+ */
+const SORT_FAMILIES = [
+  [/(^|\/)develop/i, WEIGHTS.sortDevelop, "sorts under the develop family"],
+  [/(^|\/)releases?([./_-]|$)/i, WEIGHTS.sortRelease, "sorts under the release family"],
+  [/(^|\/)(main|master)$/i, WEIGHTS.sortMain, "sorts under the main/master family"],
+];
+
+/**
+ * Strip a `refs/remotes/<remote>/` or `<remote>/` prefix so remote and local
+ * names compare as the same branch.
+ *
+ * @param {string} ref
+ * @param {string} remote
+ * @returns {string}
+ */
+export function shortName(ref, remote = "origin") {
+  let s = String(ref || "").trim();
+  s = s.replace(/^refs\/(remotes|heads)\//, "");
+  if (s.startsWith(`${remote}/`)) s = s.slice(remote.length + 1);
+  return s;
+}
+
+/**
+ * Normalise a version string to its numeric segments. `v1.51.0`, `1_51_0` and
+ * `Release 1.51` all reduce to the same segment list, which is what lets a
+ * field value match a branch name spelled with a different separator.
+ *
+ * @param {string} raw
+ * @returns {string[]} numeric segments, empty when nothing version-shaped is present
+ */
+export function versionSegments(raw) {
+  const m = String(raw || "").match(VERSION_TOKEN);
+  if (!m) return [];
+  return m.slice(1).filter((x) => x !== undefined);
+}
+
+/**
+ * Every spelling of a version that could appear inside a branch name.
+ *
+ * @param {string[]} segments
+ * @returns {string[]}
+ */
+export function versionSpellings(segments) {
+  if (segments.length < 2) return [];
+  const out = new Set();
+  for (const sep of [".", "_", "-"]) {
+    out.add(segments.join(sep));
+    if (segments.length > 2) out.add(segments.slice(0, 2).join(sep));
+  }
+  return [...out];
+}
+
+/**
+ * Does this branch name carry this version?
+ *
+ * @param {string} branch
+ * @param {string[]} segments
+ * @returns {"exact"|"partial"|null}
+ */
+export function versionMatch(branch, segments) {
+  if (segments.length < 2) return null;
+  const found = versionSegments(branch);
+  if (found.length < 2) return null;
+  const sameHead = found[0] === segments[0] && found[1] === segments[1];
+  if (!sameHead) return null;
+  // Both sides carry a patch segment and they differ -> a different release.
+  if (found.length > 2 && segments.length > 2 && found[2] !== segments[2]) return null;
+  // Exact means the two version strings name the same release, segment for segment.
+  // A field value of `1.51` against a branch `...1.51.0` is the release LINE, which is
+  // real evidence and a weaker claim - so it is partial, not exact.
+  return found.join(".") === segments.join(".") ? "exact" : "partial";
+}
+
+/**
+ * Infer this repo's release-branch template from the refs that exist.
+ *
+ * Every branch carrying a version token is reduced to its shape by replacing
+ * the token with `<version>`; the most common shape wins. Ties break on the
+ * longer template, because a longer shape is the more specific claim and a
+ * shorter one is usually its prefix.
+ *
+ * @param {string[]} branches - short names
+ * @returns {{template: string, members: string[], separator: string}|null}
+ */
+export function learnVersionConvention(branches) {
+  /** @type {Map<string, {members: string[], separator: string}>} */
+  const shapes = new Map();
+  for (const b of branches) {
+    const m = b.match(VERSION_TOKEN);
+    if (!m) continue;
+    const separator = m[0].includes("_") ? "_" : m[0].includes("-") ? "-" : ".";
+    const template = b.slice(0, m.index) + "<version>" + b.slice(m.index + m[0].length);
+    if (!shapes.has(template)) shapes.set(template, { members: [], separator });
+    shapes.get(template).members.push(b);
+  }
+  if (shapes.size === 0) return null;
+  let best = null;
+  for (const [template, info] of shapes) {
+    if (
+      best === null ||
+      info.members.length > best.members.length ||
+      (info.members.length === best.members.length && template.length > best.template.length)
+    ) {
+      best = { template, members: info.members, separator: info.separator };
+    }
+  }
+  return best;
+}
+
+/**
+ * Render a version into a learned template.
+ *
+ * @param {{template: string, separator: string}} convention
+ * @param {string[]} segments
+ * @returns {string}
+ */
+export function applyConvention(convention, segments) {
+  return convention.template.replace("<version>", segments.join(convention.separator));
+}
+
+/**
+ * Pull version and release-link evidence out of an already-fetched issue.
+ *
+ * NOTHING HERE IS HARDCODED TO A FIELD ID. Jira's only system version fields
+ * are `fixVersions` and `versions`; a board's own "target version" is a custom
+ * field whose id differs per instance, so it is discovered by its declared
+ * schema type instead. `fieldMeta` is the `GET /rest/api/2/field` response
+ * (or the `names`/`schema` maps from `GET /rest/api/2/issue/<key>?expand=names`);
+ * any field whose schema resolves to a version - directly or as array items -
+ * is read, whatever it is called and whatever its id.
+ *
+ * GitHub's analogue is the milestone, which is a plain title string.
+ *
+ * @param {object} issue - `{fields: {...}}` (Jira) or `{milestone, ...}` (GitHub)
+ * @param {Array<object>} fieldMeta - `[{id, name, schema: {type, items}}]`
+ * @returns {{versions: Array<object>, releaseLinks: Array<object>}}
+ */
+export function extractIssueEvidence(issue, fieldMeta = []) {
+  const versions = [];
+  const releaseLinks = [];
+  if (!issue || typeof issue !== "object") return { versions, releaseLinks };
+
+  const isVersionSchema = (schema) =>
+    !!schema &&
+    (schema.type === "version" ||
+      (schema.type === "array" && schema.items === "version") ||
+      schema.custom === "version" ||
+      schema.items === "version");
+
+  const metaById = new Map();
+  for (const f of Array.isArray(fieldMeta) ? fieldMeta : []) {
+    if (f && typeof f.id === "string") metaById.set(f.id, f);
+  }
+
+  const pushVersion = (fieldId, fieldName, value, weightHint) => {
+    const raw =
+      value && typeof value === "object" ? value.name || value.value || value.id : String(value);
+    const segments = versionSegments(raw);
+    if (segments.length < 2) return;
+    versions.push({
+      field: fieldId,
+      fieldName: fieldName || fieldId,
+      raw: String(raw),
+      segments,
+      weightHint,
+    });
+  };
+
+  const fields = issue.fields && typeof issue.fields === "object" ? issue.fields : {};
+
+  for (const [id, value] of Object.entries(fields)) {
+    if (value === null || value === undefined) continue;
+    const meta = metaById.get(id);
+    const name = meta ? meta.name : id;
+    const schemaSaysVersion = meta ? isVersionSchema(meta.schema) : false;
+    const isSystemFix = id === "fixVersions";
+    const isSystemAffects = id === "versions";
+    if (!schemaSaysVersion && !isSystemFix && !isSystemAffects) continue;
+    const hint = isSystemAffects ? "affects" : "fix";
+    if (Array.isArray(value)) for (const v of value) pushVersion(id, name, v, hint);
+    else pushVersion(id, name, value, hint);
+  }
+
+  const linkFrom = (other, relation) => {
+    if (!other || typeof other !== "object") return;
+    const of = other.fields && typeof other.fields === "object" ? other.fields : {};
+    const segments = [];
+    for (const v of Array.isArray(of.fixVersions) ? of.fixVersions : []) {
+      const s = versionSegments(v && v.name);
+      if (s.length >= 2) segments.push(s);
+    }
+    if (segments.length === 0) {
+      const s = versionSegments(of.summary || "");
+      if (s.length >= 2) segments.push(s);
+    }
+    if (segments.length === 0) return;
+    releaseLinks.push({
+      key: other.key || null,
+      summary: of.summary || null,
+      relation,
+      segments: segments[0],
+    });
+  };
+
+  for (const link of Array.isArray(fields.issuelinks) ? fields.issuelinks : []) {
+    const type = link && link.type ? link.type : {};
+    if (link && link.inwardIssue) linkFrom(link.inwardIssue, type.inward || "links to");
+    if (link && link.outwardIssue) linkFrom(link.outwardIssue, type.outward || "links to");
+  }
+  if (fields.parent) linkFrom(fields.parent, "parent of this sub-task");
+
+  // GitHub: the milestone is the version field, and a title is all there is.
+  if (issue.milestone && issue.milestone.title) {
+    const segments = versionSegments(issue.milestone.title);
+    if (segments.length >= 2) {
+      versions.push({
+        field: "milestone",
+        fieldName: "milestone",
+        raw: String(issue.milestone.title),
+        segments,
+        weightHint: "fix",
+      });
+    }
+  }
+
+  return { versions, releaseLinks };
+}
+
+/**
+ * Collect and rank candidates.
+ *
+ * @param {object} input
+ * @param {string[]} input.remoteBranches - refs as git printed them
+ * @param {string[]} [input.localBranches]
+ * @param {"remote"|"local"} input.refProvenance - where the list above came from
+ * @param {string} [input.fetchStatus] - `fresh` | `cached-stale` | `local-branch` | `aborted`
+ * @param {string|null} [input.defaultBranch]
+ * @param {Array<object>} [input.recentBranches] - `[{branch, lastUsed, count}]`
+ * @param {number} [input.branchTtlDays]
+ * @param {string} [input.now] - ISO timestamp, for the TTL filter
+ * @param {{versions?: Array<object>, releaseLinks?: Array<object>}} [input.issue]
+ * @param {boolean} [input.preferLinkedRelease]
+ * @returns {object}
+ */
+export function collect(input) {
+  const remote = String(input.remote || "origin");
+  const provenance = input.refProvenance === "local" ? "local" : "remote";
+  const degraded = provenance === "local";
+  const notes = [];
+
+  const seen = new Map();
+  const addRef = (ref, where) => {
+    const name = shortName(ref, remote);
+    if (!name || name === "HEAD" || name.includes("->")) return;
+    if (!seen.has(name)) seen.set(name, new Set());
+    seen.get(name).add(where);
+  };
+  for (const r of input.remoteBranches || [])
+    addRef(r, provenance === "local" ? "local-cache" : "remote");
+  for (const r of input.localBranches || []) addRef(r, "local");
+
+  const names = [...seen.keys()];
+  const convention = learnVersionConvention(names);
+
+  /** @type {Map<string, {branch: string, score: number, evidence: Array<object>, refs: string[]}>} */
+  const cands = new Map();
+  const candidate = (branch) => {
+    if (!seen.has(branch)) return null;
+    if (!cands.has(branch))
+      cands.set(branch, { branch, score: 0, evidence: [], refs: [...seen.get(branch)] });
+    return cands.get(branch);
+  };
+  const award = (branch, points, kind, detail) => {
+    const c = candidate(branch);
+    if (!c) return false;
+    c.score += points;
+    c.evidence.push({ kind, detail });
+    return true;
+  };
+
+  // --- issue version fields -------------------------------------------------
+  const issue = input.issue || {};
+  for (const v of issue.versions || []) {
+    const hits = names.filter((n) => versionMatch(n, v.segments));
+    for (const n of hits) {
+      const kind = versionMatch(n, v.segments);
+      const points = kind === "exact" ? WEIGHTS.issueVersionExact : WEIGHTS.versionPartial;
+      const weight = v.weightHint === "affects" ? Math.round(points * 0.6) : points;
+      award(
+        n,
+        weight,
+        "issue-version",
+        `matches ${kind === "exact" ? "" : "the line of "}version ${v.raw} from the issue field "${v.fieldName}"`,
+      );
+    }
+    if (hits.length === 0 && convention) {
+      const predicted = applyConvention(convention, v.segments);
+      notes.push(
+        `version ${v.raw} (field "${v.fieldName}") has no branch on the ${provenance === "local" ? "local refs" : "remote"}; ` +
+          `the convention ${convention.template} learned from ${convention.members.length} branch(es) would spell it ${predicted}`,
+      );
+    } else if (hits.length === 0) {
+      notes.push(
+        `version ${v.raw} (field "${v.fieldName}") matched no branch and no version convention could be learned`,
+      );
+    }
+  }
+
+  // --- linked release issues ------------------------------------------------
+  const authoritative = input.preferLinkedRelease === true;
+  for (const link of issue.releaseLinks || []) {
+    const hits = names.filter((n) => versionMatch(n, link.segments));
+    for (const n of hits) {
+      const kind = versionMatch(n, link.segments);
+      const base = authoritative ? WEIGHTS.linkedReleaseAuthoritative : WEIGHTS.linkedReleaseExact;
+      const points = kind === "exact" ? base : WEIGHTS.versionPartial;
+      award(
+        n,
+        points,
+        "linked-release",
+        `the linked release issue ${link.key || "(no key)"} (${link.relation}) names version ` +
+          `${link.segments.join(".")}${authoritative ? "; this board treats the release link as authoritative" : ""}`,
+      );
+    }
+    if (hits.length === 0) {
+      notes.push(
+        `linked release issue ${link.key || "(no key)"} names version ${link.segments.join(".")}, which matched no branch`,
+      );
+    }
+  }
+
+  // --- the learned convention itself ---------------------------------------
+  if (convention) {
+    for (const m of convention.members) {
+      const c = cands.get(m);
+      if (c)
+        c.evidence.push({
+          kind: "version-convention",
+          detail: `this remote spells release branches ${convention.template} (learned from ${convention.members.length} branch(es), no built-in table)`,
+        });
+    }
+  }
+
+  // --- recently used for this repo -----------------------------------------
+  const ttlDays = Number.isFinite(input.branchTtlDays) ? input.branchTtlDays : 15;
+  const now = input.now ? Date.parse(input.now) : Date.now();
+  for (const entry of input.recentBranches || []) {
+    if (!entry || typeof entry.branch !== "string") continue;
+    const used = entry.lastUsed ? Date.parse(entry.lastUsed) : NaN;
+    const ageDays = Number.isFinite(used) ? (now - used) / 86400000 : Infinity;
+    if (Number.isFinite(ageDays) && ageDays > ttlDays) continue;
+    const recency = Number.isFinite(ageDays)
+      ? Math.max(0, Math.round(WEIGHTS.recentRecencyMax * (1 - ageDays / Math.max(ttlDays, 1))))
+      : 0;
+    award(
+      entry.branch,
+      WEIGHTS.recent + recency,
+      "recent",
+      Number.isFinite(ageDays)
+        ? `used as the base for this repo ${Math.max(0, Math.round(ageDays))} day(s) ago`
+        : "used as the base for this repo before",
+    );
+  }
+
+  // --- repo default ---------------------------------------------------------
+  if (input.defaultBranch) {
+    award(
+      shortName(input.defaultBranch, remote),
+      WEIGHTS.repoDefault,
+      "repo-default",
+      "the repository's default branch",
+    );
+  }
+
+  // --- the legacy sort order, as the floor ---------------------------------
+  for (const n of names) {
+    for (const [re, points, detail] of SORT_FAMILIES) {
+      if (re.test(n)) {
+        award(n, points, "sort-order", detail);
+        break;
+      }
+    }
+  }
+
+  // --- provenance rides on every candidate ---------------------------------
+  const provenanceDetail = degraded
+    ? "listed from local refs because the fetch failed; this may be stale or incomplete"
+    : "listed from the remote after a successful fetch";
+  for (const c of cands.values())
+    c.evidence.push({ kind: "ref-provenance", detail: provenanceDetail });
+
+  const candidates = [...cands.values()].sort(
+    (a, b) => b.score - a.score || a.branch.localeCompare(b.branch),
+  );
+  const top = candidates[0];
+  const ambiguous = candidates.length > 1 && top !== undefined && candidates[1].score === top.score;
+
+  const issueDerived = new Set(["issue-version", "linked-release"]);
+  const derivedTop =
+    top !== undefined && top.evidence.some((e) => issueDerived.has(e.kind)) && !ambiguous;
+
+  return {
+    refProvenance: provenance,
+    fetchStatus: input.fetchStatus || (degraded ? "cached-stale" : "fresh"),
+    degraded,
+    convention: convention
+      ? { template: convention.template, members: convention.members.length }
+      : null,
+    candidates,
+    ambiguous,
+    derivable: derivedTop,
+    notes,
+  };
+}
+
+/**
+ * Turn the ranked list into picker rows.
+ *
+ * THE TWO-OPTION FLOOR IS ENFORCED HERE, not left to the caller. Claude Code's
+ * `AskUserQuestion` refuses a question with fewer than two declared options and
+ * discards every question batched with it, and the host's injected "Other" row
+ * does not count towards the schema's minimum. A filtered list that leaves one
+ * row has narrowed the world, not decided anything - so the escape row that
+ * re-opens the unfiltered list is what turns it back into a question. This
+ * function never returns fewer than two rows.
+ *
+ * @param {object} result - the return value of `collect`
+ * @param {number} [visible] - how many ranked rows to show
+ * @returns {{question: string, options: Array<object>}}
+ */
+export function toPickerOptions(result, visible = 4) {
+  const options = result.candidates.slice(0, Math.max(1, visible)).map((c, i) => ({
+    branch: c.branch,
+    label: c.branch,
+    recommended: i === 0,
+    // The evidence IS the description: "matches the target version on the
+    // remote" and "repo default" are different answers to the same question,
+    // and a row that hides which one it is cannot be chosen on its merits.
+    description: c.evidence.map((e) => e.detail).join("; "),
+    kind: "candidate",
+  }));
+
+  options.push({
+    branch: null,
+    label: "Show all branches",
+    recommended: false,
+    description: result.degraded
+      ? "re-open with every ref in the local cache, unfiltered"
+      : "re-open with every remote branch, unfiltered",
+    kind: "escape",
+  });
+
+  if (result.degraded) {
+    options.push({
+      branch: null,
+      label: "Retry the fetch",
+      recommended: false,
+      description: "re-run git fetch and rebuild this list from the remote",
+      kind: "retry",
+    });
+  }
+
+  // The floor is enforced here rather than left to the caller, and the empty
+  // case is the one that breaks it: no candidate leaves only "Show all
+  // branches", and a one-option AskUserQuestion is refused by the host along
+  // with every question batched with it. Abort is the honest second row when
+  // there is nothing to recommend - the run cannot pick a base it could not
+  // find, and "OK" would manufacture consent to a list with nothing in it.
+  if (options.length < 2) {
+    options.push({
+      branch: null,
+      label: "Abort",
+      recommended: false,
+      description: "no branch could be found to base this work on; stop before a worktree exists",
+      kind: "abort",
+    });
+  }
+
+  const question = result.degraded
+    ? "The fetch failed, so these branches come from local refs and may be stale. Which base branch?"
+    : "Which base branch should this work target?";
+
+  return { question, options };
+}
+
+/** @param {string[]} argv */
+function main(argv) {
+  const args = argv.slice(2);
+  const idx = args.indexOf("--input");
+  if (idx < 0 || !args[idx + 1]) {
+    console.error("usage: base-branch-candidates.mjs --input <file.json> [--json]");
+    return 2;
+  }
+  const path = args[idx + 1];
+  if (!existsSync(path)) {
+    console.error(`base-branch-candidates: no such input file: ${path}`);
+    return 1;
+  }
+  let input;
+  try {
+    input = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (e) {
+    console.error(`base-branch-candidates: ${path} is not valid JSON: ${e.message}`);
+    return 1;
+  }
+  const result = collect(input);
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ...result, picker: toPickerOptions(result) }, null, 2));
+  } else {
+    console.log(
+      `base-branch-candidates: ${result.candidates.length} candidate(s), refs from ${result.refProvenance}` +
+        `${result.degraded ? " (DEGRADED - fetch failed)" : ""}`,
+    );
+    for (const c of result.candidates) {
+      console.log(`  ${c.score.toString().padStart(4)}  ${c.branch}`);
+      for (const e of c.evidence) console.log(`        - ${e.kind}: ${e.detail}`);
+    }
+    for (const n of result.notes) console.log(`  note: ${n}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(main(process.argv));
+}

package/pipeline/scripts/gc-abandoned.sh

@@ -18,9 +18,11 @@
 #      This is not theoretical: four state files on that machine record
 #      `worktreePath` as the REPO ROOT, so a sweep that trusted the field would
 #      have deleted the checkout.
-#   3. Uncommitted work is never destroyed. The branch is stashed to
-#      `autopilot/abandoned/<task-id>` and the directory is left in place, which
-#      costs disk and keeps the work. Losing a day of edits is worse than 750 MB.
+#   3. Uncommitted work is never destroyed. It goes into a STASH ENTRY labelled
+#      `autopilot/abandoned/<task-id>` - `git stash list` finds it - and the
+#      directory is left in place, which costs disk and keeps the work. Losing a
+#      day of edits is worse than 750 MB. No branch is created: a branch made
+#      after `stash push` points at HEAD and holds none of the stashed work.
 #
 # TWO PASSES, because the state files are not where the disk is. Measured across
 # 28 worktrees holding 23 GB: only 5 of them (1.5 GB) belong to a run that still