forgedock 1.35.0 → 1.37.0

package/bin/lean/lifecycle.mjs

@@ -0,0 +1,129 @@
+/**
+ * forge#4657: milestone lifecycle `building -> shipped:staging -> deployed:default -> closed`, recorded as one
+ * `<!-- FORGE:LIFECYCLE {json} -->` block in the milestone description (same register as FORGE:DRIFT, drift.mjs).
+ * Pure helpers plus `advanceMilestone`, which takes an injected `gh`/`git`. No LLM.
+ */
+import { readMilestone } from "./drift.mjs";
+
+export const LIFECYCLE_MARKER = "FORGE:LIFECYCLE";
+export const LIFECYCLE_STATES = ["building", "shipped:staging", "deployed:default", "closed"];
+export const CARRY_CLASSES = ["engineering", "external", "post-deploy", "wont-do"];
+const BLOCK_RE = new RegExp(`<!--\\s*${LIFECYCLE_MARKER}\\s+(\\{[\\s\\S]*?\\})\\s*-->`);
+const POST_DEPLOY_LABELS = ["awaiting-promotion", "awaiting-due", "awaiting-precondition", "awaiting-measurement"];
+const GATED_LABELS = ["flag-gated", "legal-gated", "legal-hold"];
+const arr = (x) => (Array.isArray(x) ? x : []);
+const names = (labels) => arr(labels).map((l) => String(l?.name ?? l));
+
+/** The FORGE:LIFECYCLE record in a milestone description ({v, state, sha?}), or null. */
+export function parseLifecycle(description) {
+  const m = BLOCK_RE.exec(String(description ?? ""));
+  if (!m) return null;
+  try { const s = JSON.parse(m[1]); return s && typeof s === "object" && !Array.isArray(s) && LIFECYCLE_STATES.includes(s.state) ? s : null; } catch { return null; }
+}
+
+/** `description` with its FORGE:LIFECYCLE block replaced (or appended); the text around it is unchanged. */
+export function renderLifecycle(description, record) {
+  const d = String(description ?? "");
+  const block = `<!-- ${LIFECYCLE_MARKER} ${JSON.stringify({ v: 1, ...record }).replace(/>/g, "\\u003e")} -->`;
+  if (BLOCK_RE.test(d)) return d.replace(BLOCK_RE, () => block);
+  return d ? `${d}\n\n${block}` : block;
+}
+
+/** `state` moves forward only: the later of `from` and `to` (a missing `from` is `building`). */
+export function advanceState(from, to) {
+  const a = Math.max(0, LIFECYCLE_STATES.indexOf(from)), b = LIFECYCLE_STATES.indexOf(to);
+  return LIFECYCLE_STATES[Math.max(a, b)];
+}
+
+/** forge.yaml `milestones.close_on`: `staging` or `default` (the default). */
+export const parseCloseOn = (v) => (String(v ?? "").trim().toLowerCase() === "staging" ? "staging" : "default");
+
+/** True when `state` has reached the point `closeOn` closes the milestone at (and it is not closed yet). */
+export function closeDue(state, closeOn = "default") {
+  if (state === "closed") return false;
+  return LIFECYCLE_STATES.indexOf(state) >= LIFECYCLE_STATES.indexOf(parseCloseOn(closeOn) === "staging" ? "shipped:staging" : "deployed:default");
+}
+
+/** Carry-over class of an open issue from its labels: external, post-deploy, wont-do, else engineering. */
+export function classifyCarryOver(issue) {
+  const l = names(issue?.labels);
+  const explicit = l.map((x) => /^carry:(.+)$/.exec(x)?.[1]).find((x) => CARRY_CLASSES.includes(x));
+  if (explicit) return explicit;
+  if (l.includes("needs-human:external")) return "external";
+  if (l.some((x) => POST_DEPLOY_LABELS.includes(x))) return "post-deploy";
+  if (l.includes("wont-do") || l.includes("wontfix")) return "wont-do";
+  return "engineering";
+}
+
+/**
+ * Ship pre-flight over the open issues of a milestone. Each item: `{number, labels, target, dependsOn?}` where `target` is the
+ * milestone it is carried to. `onBase(n)` says whether dependency `n` is on the target base (default: yes).
+ * Returns `{ok, missing:[{issue, why}], carry:[{issue, class, target, demote}], mustNotDemote:[issue]}`. An issue that is
+ * external, flag/legal-gated or depends on an issue that is not on the base is never demoted to fast lane.
+ */
+export function preflightCarryOver(openIssues, { onBase = () => true } = {}) {
+  const missing = [], carry = [], mustNotDemote = [];
+  for (const it of arr(openIssues)) {
+    const n = it?.number, cls = classifyCarryOver(it), target = String(it?.target ?? "").trim();
+    if (!target) { missing.push({ issue: n, why: "no target milestone" }); continue; }
+    const gated = names(it.labels).some((x) => GATED_LABELS.includes(x));
+    const offBase = arr(it.dependsOn).some((d) => { try { return onBase(d) === false; } catch { return false; } });
+    const blocked = cls === "external" || gated || offBase;
+    if (blocked) mustNotDemote.push(n);
+    carry.push({ issue: n, class: cls, target, demote: !blocked });
+  }
+  return { ok: missing.length === 0, missing, carry, mustNotDemote };
+}
+
+/** Open milestone `{title, state, open, closed, description}` with a shipped/deployed record and open issues left. */
+export function shippedWithOpen(ms) {
+  const s = parseLifecycle(ms?.description)?.state;
+  return ms?.state !== "closed" && ["shipped:staging", "deployed:default"].includes(s) && Number(ms?.open) > 0;
+}
+
+/** Open milestone with no open issues that is still not closed. */
+export const emptyButOpen = (ms) => ms?.state !== "closed" && Number(ms?.open) === 0;
+
+/**
+ * Advance one milestone to `to` (never backwards), recording `sha` (the merge commit) when given. Closes it when `closeOn` is
+ * reached and no open issue is left. `deployed(sha)` (optional) reports whether the shipped commit is on the default branch;
+ * it promotes `shipped:staging` to `deployed:default`. Returns `{state, closed}` or null when the milestone is not found.
+ */
+export async function advanceMilestone({ gh, repo, title, to = null, sha = null, closeOn = "default", deployed = null }) {
+  const ms = await readMilestone({ gh, repo, title });
+  if (!ms) return null;
+  const before = parseLifecycle(ms.description);
+  let state = to ? advanceState(before?.state, to) : before?.state ?? "building";
+  const rsha = sha ?? before?.sha ?? null;
+  if (state === "shipped:staging" && rsha && deployed) { try { if (await deployed(rsha)) state = "deployed:default"; } catch { /* not provably deployed */ } }
+  let closed = false;
+  if (closeDue(state, closeOn)) {
+    const open = JSON.parse(String(await gh(["issue", "list", "-R", repo, "--milestone", title, "--state", "open", "--limit", "1", "--json", "number"])) || "[]");
+    if (!arr(open).length) { state = "closed"; closed = true; }
+  }
+  const next = { state, ...(rsha ? { sha: rsha } : {}) };
+  if (!before || before.state !== next.state || before.sha !== next.sha) {
+    await gh(["api", "-X", "PATCH", `repos/${repo}/milestones/${ms.number}`, "-f", `description=${renderLifecycle(ms.description, next)}`, ...(closed ? ["-f", "state=closed"] : [])]);
+  }
+  return { state, closed };
+}
+
+/**
+ * The orchestrate `lifecycle` seam: `onBatchEnd(titles)` records `shipped:staging` for each milestone the batch merged into once it has no open issue, so an
+ * orchestrate-driven milestone closes once `close_on` is reached. Errors are the caller's to report.
+ */
+export function makeLifecycle({ gh, git = null, repo, closeOn = "default", defaultBranch = "main" }) {
+  const deployed = git ? async (sha) => { try { await git(["merge-base", "--is-ancestor", sha, `origin/${defaultBranch}`]); return true; } catch { return false; } } : null;
+  return {
+    async onBatchEnd(titles) {
+      const out = [];
+      for (const title of titles) {
+        // D3: only a milestone with no open issue left is shipped by the batch; otherwise it is re-evaluated as is.
+        const open = JSON.parse(String(await gh(["issue", "list", "-R", repo, "--milestone", title, "--state", "open", "--limit", "1", "--json", "number"])) || "[]");
+        const r = await advanceMilestone({ gh, repo, title, to: arr(open).length ? null : "shipped:staging", closeOn, deployed });
+        if (r) out.push({ title, ...r });
+      }
+      return out;
+    },
+  };
+}

package/bin/lean/lifecycle.test.mjs

@@ -0,0 +1,118 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseLifecycle, renderLifecycle, advanceState, parseCloseOn, closeDue, classifyCarryOver, preflightCarryOver, shippedWithOpen, emptyButOpen, advanceMilestone, makeLifecycle } from "./lifecycle.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+import { renderSummary, parseSummary } from "./drift.mjs";
+
+const fakeGh = (ms, openIssues = []) => {
+  const calls = [];
+  const gh = async (args) => {
+    calls.push(args);
+    if (args[0] === "api" && args[1].includes("/milestones?")) return JSON.stringify([{ number: 3, title: "M", description: ms.description }]);
+    if (args[0] === "issue") return JSON.stringify(openIssues);
+    if (args[1] === "-X") { ms.description = args.find((a) => a.startsWith("description=")).slice(12); }
+    return "";
+  };
+  return { gh, calls };
+};
+
+describe("forge#4657 lifecycle block", () => {
+  it("round-trips, keeps surrounding text and the drift block", () => {
+    const d = renderSummary("intro", { v: 1, merged: [] });
+    const r = renderLifecycle(d, { state: "shipped:staging", sha: "abc" });
+    assert.equal(parseLifecycle(r).state, "shipped:staging");
+    assert.ok(r.startsWith("intro") && parseSummary(r));
+    assert.equal(parseLifecycle(renderLifecycle(r, { state: "closed" })).state, "closed");
+    assert.equal(parseLifecycle("no block"), null);
+  });
+  it("only moves forward", () => {
+    assert.equal(advanceState("deployed:default", "shipped:staging"), "deployed:default");
+    assert.equal(advanceState(undefined, "shipped:staging"), "shipped:staging");
+  });
+  it("closeDue honours close_on (default: default)", () => {
+    assert.equal(parseCloseOn(undefined), "default");
+    assert.equal(closeDue("shipped:staging", "staging"), true);
+    assert.equal(closeDue("shipped:staging"), false);
+    assert.equal(closeDue("deployed:default"), true);
+    assert.equal(closeDue("closed", "staging"), false);
+  });
+});
+
+describe("forge#4657 carry-over", () => {
+  it("classifies from labels", () => {
+    assert.equal(classifyCarryOver({ labels: ["needs-human:external"] }), "external");
+    assert.equal(classifyCarryOver({ labels: [{ name: "awaiting-promotion" }] }), "post-deploy");
+    assert.equal(classifyCarryOver({ labels: ["wont-do"] }), "wont-do");
+    assert.equal(classifyCarryOver({ labels: ["carry:post-deploy"] }), "post-deploy");
+    assert.equal(classifyCarryOver({ labels: [] }), "engineering");
+  });
+  it("requires a target milestone and never demotes external, gated or off-base-dependent issues", () => {
+    const r = preflightCarryOver([
+      { number: 1, labels: [], target: "" },
+      { number: 2, labels: ["needs-human:external"], target: "M2" },
+      { number: 3, labels: ["legal-gated"], target: "M2" },
+      { number: 4, labels: [], target: "M2", dependsOn: [9] },
+      { number: 5, labels: [], target: "M2", dependsOn: [8] },
+    ], { onBase: (n) => n !== 9 });
+    assert.equal(r.ok, false);
+    assert.deepEqual(r.missing, [{ issue: 1, why: "no target milestone" }]);
+    assert.deepEqual(r.mustNotDemote, [2, 3, 4]);
+    assert.deepEqual(r.carry.filter((c) => c.demote).map((c) => c.issue), [5]);
+    assert.equal(preflightCarryOver([]).ok, true);
+  });
+});
+
+describe("forge#4657 pipeline-status classifiers", () => {
+  it("SHIPPED_WITH_OPEN and EMPTY_BUT_OPEN", () => {
+    const d = renderLifecycle("", { state: "shipped:staging" });
+    assert.equal(shippedWithOpen({ state: "open", open: 2, description: d }), true);
+    assert.equal(shippedWithOpen({ state: "open", open: 2, description: "" }), false);
+    assert.equal(emptyButOpen({ state: "open", open: 0 }), true);
+    assert.equal(emptyButOpen({ state: "closed", open: 0 }), false);
+  });
+});
+
+describe("forge#4657 advanceMilestone", () => {
+  it("records shipped:staging and keeps the milestone open when close_on=default", async () => {
+    const ms = { description: "" }, { gh } = fakeGh(ms);
+    assert.deepEqual(await advanceMilestone({ gh, repo: "o/r", title: "M", to: "shipped:staging", sha: "abc" }), { state: "shipped:staging", closed: false });
+    assert.equal(parseLifecycle(ms.description).sha, "abc");
+  });
+  it("closes at shipped:staging when close_on=staging and no open issue is left", async () => {
+    const ms = { description: "" }, { gh, calls } = fakeGh(ms);
+    assert.equal((await advanceMilestone({ gh, repo: "o/r", title: "M", to: "shipped:staging", closeOn: "staging" })).closed, true);
+    assert.ok(calls.some((c) => c.includes("state=closed")));
+  });
+  it("does not close a milestone that still has open issues", async () => {
+    const ms = { description: "" }, { gh } = fakeGh(ms, [{ number: 1 }]);
+    assert.equal((await advanceMilestone({ gh, repo: "o/r", title: "M", to: "shipped:staging", closeOn: "staging" })).closed, false);
+  });
+  it("the orchestrate seam promotes to deployed:default once the sha is on the default branch, then closes", async () => {
+    const ms = { description: renderLifecycle("", { state: "shipped:staging", sha: "abc" }) }, { gh } = fakeGh(ms);
+    const lc = makeLifecycle({ gh, git: async () => "", repo: "o/r" });
+    assert.deepEqual(await lc.onBatchEnd(["M"]), [{ title: "M", state: "closed", closed: true }]);
+    const ms2 = { description: renderLifecycle("", { state: "shipped:staging", sha: "abc" }) }, g2 = fakeGh(ms2);
+    const lc2 = makeLifecycle({ gh: g2.gh, git: async () => { throw new Error("not ancestor"); }, repo: "o/r" });
+    assert.equal((await lc2.onBatchEnd(["M"]))[0].state, "shipped:staging");
+  });
+  it("the seam records shipped:staging for a building milestone and closes it when close_on=staging", async () => {
+    const ms = { description: "" }, { gh } = fakeGh(ms);
+    const out = await makeLifecycle({ gh, repo: "o/r", closeOn: "staging" }).onBatchEnd(["M"]);
+    assert.deepEqual(out, [{ title: "M", state: "closed", closed: true }]);
+    const ms2 = { description: "" }, g2 = fakeGh(ms2);
+    assert.deepEqual(await makeLifecycle({ gh: g2.gh, repo: "o/r" }).onBatchEnd(["M"]), [{ title: "M", state: "shipped:staging", closed: false }]);
+    assert.equal(parseLifecycle(ms2.description).state, "shipped:staging");
+  });
+  it("orchestrate calls lifecycle.onBatchEnd with the merged milestone, reports errors as a row, and is unchanged without the seam", async () => {
+    const runOne = async () => ({ terminalReason: "merged", pr: 5, milestone: "M", lane: "milestone/m" });
+    const calls = [], rows = [];
+    const res = await orchestrate({ issues: [1], parallel: 1, runOne, readBody: async () => "", onUpdate: (r) => rows.push(r), lifecycle: { onBatchEnd: async (t) => { calls.push(t); } } });
+    assert.deepEqual(calls, [["M"]]);
+    assert.equal(res[0].outcome, "merged");
+    const rows2 = [];
+    const res2 = await orchestrate({ issues: [1], parallel: 1, runOne, readBody: async () => "", onUpdate: (r) => rows2.push(r), lifecycle: { onBatchEnd: async () => { throw new Error("boom"); } } });
+    assert.equal(res2[0].outcome, "merged");
+    assert.ok(rows2.some((r) => r.outcome === "lifecycle" && /boom/.test(r.detail)));
+    assert.equal((await orchestrate({ issues: [1], parallel: 1, runOne, readBody: async () => "" }))[0].outcome, "merged");
+  });
+});

package/bin/lean/light.mjs

@@ -54,7 +54,7 @@ const REPRO_RE = /steps to reproduce|\brepro(duction|duce)?\b|\bexpected[ _-]+(b
 const FENCE_RE = /^\s*(```|~~~)/m;
 const DECISION_LABEL_RE = /^(type[:/]\s*)?(decision|needs-decision|product-decision|rfc|adr)$/i;
 const DECISION_TITLE_RE = /^\s*(decision|rfc|adr)[(:]/i;
-const POST_DEPLOY_LABELS = new Set(["post-deploy", "awaiting-promotion"]);
+const POST_DEPLOY_LABELS = new Set(["post-deploy", "awaiting-promotion", "awaiting-due"]);
 
 /** Risk details for `files`: a built-in risk word or a declared review.risk_paths glob. */
 function riskDetails(files, riskPaths) {

package/bin/lean/milestonesync.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Milestone branch sync (#4663). No LLM. `syncMilestone` merges a base into `milestone/{slug}` on demand:
+ *   - a milestone whose lifecycle is past `building` (shipped:*, deployed:default, closed) is never synced (`isSyncable`);
+ *   - a base already merged in is `up-to-date`; the caller names why it syncs (`reason`), never "every base move";
+ *   - conflicts go through the lane base-merge resolver (conflictres.mjs `resolveBaseConflicts`, forge.yaml `lean.base_merge_*`);
+ *   - an unprotected branch gets a plain push; a protected one (branch protection or a ruleset, or a push rejected by one)
+ *     gets ONE long-lived sync PR (`sync/milestone-{slug}`) whose head is force-pushed in place (with lease) while the
+ *     FORGE:MILESTONE-SYNC marker in its body (base sha + time) debounces: same base => `unchanged`, inside the window =>
+ *     `debounced` (a `ship` sync is never debounced). Auto-merge is armed; a CLEAN PR (auto-merge refused) is merged directly.
+ * Never throws; resolves {status, ...}.
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseForgeYaml } from "../forge-utils.mjs";
+import { resolveBaseConflicts } from "./conflictres.mjs";
+import { parseLifecycle } from "./lifecycle.mjs";
+import { parseMinAge } from "./prefilter.mjs";
+import { DEFAULT_FEATURE_PATTERN, milestoneSlug, readBranches } from "./lane.mjs";
+
+export const SYNC_REASONS = ["ship", "batch", "conflict-risk", "manual"];
+export const DEFAULT_DEBOUNCE_MS = 10 * 60 * 1000;
+export const SYNC_MARKER = "FORGE:MILESTONE-SYNC";
+const MARKER_RE = new RegExp(`<!--\\s*${SYNC_MARKER}\\s+(\\{[\\s\\S]*?\\})\\s*-->`);
+const REJECTED_RE = /GH006|GH013|protected branch|repository rule|rule violations/i;
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+
+/** Only a milestone that is open and still `building` (or has no lifecycle record) may be synced or picked active. */
+export function isSyncable(ms) {
+  const state = parseLifecycle(ms?.description)?.state;
+  return String(ms?.state ?? "open") !== "closed" && (!state || state === "building");
+}
+
+/** forge.yaml `milestones.sync_debounce` ("10m", "1h"; default 10m) in ms. */
+export function readSyncDebounce(cwd = process.cwd()) {
+  try { return parseMinAge(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.milestones?.sync_debounce) ?? DEFAULT_DEBOUNCE_MS; } catch { return DEFAULT_DEBOUNCE_MS; }
+}
+
+/** True when branch protection or a repository ruleset applies to `branch`; each source fails independently to false. */
+export async function isProtectedBranch({ gh, repo, branch }) {
+  const safe = async (f) => { try { return await f(); } catch { return false; } };
+  return (await safe(async () => String(await gh(["api", `repos/${repo}/branches/${branch}`, "--jq", ".protected"])).trim() === "true"))
+    || (await safe(async () => Number(String(await gh(["api", `repos/${repo}/rules/branches/${branch}`, "--jq", "length"])).trim()) > 0));
+}
+
+const syncMarker = (rec) => `<!-- ${SYNC_MARKER} ${JSON.stringify(rec)} -->`;
+const readMarker = (body) => { try { return JSON.parse(MARKER_RE.exec(String(body ?? ""))?.[1]); } catch { return null; } };
+
+/**
+ * @param {{gh:Function, git:(args:string[], o?:{cwd?:string})=>Promise<string>, repo:string, slug:string, base:string,
+ *   branch?:string, cfg?:object, reason:string, now?:number, debounceMs?:number, tmp?:string}} p
+ * @returns {Promise<{status:"synced"|"pr-created"|"pr-updated"|"up-to-date"|"unchanged"|"debounced"|"shipped"|"conflict"|"refused"|"error", pr?:number, base?:string, paths?:string[], detail?:string}>}
+ */
+export async function syncMilestone({ gh, git, repo, slug, base, branch = `milestone/${slug}`, cfg = {}, reason, now = Date.now(), debounceMs = DEFAULT_DEBOUNCE_MS, tmp = tmpdir() }) {
+  let wt = null, baseSha;
+  try {
+    if (!SYNC_REASONS.includes(reason)) return { status: "refused", detail: `sync is on demand: reason must be one of ${SYNC_REASONS.join("|")}` };
+    const list = JSON.parse(String(await gh(["api", `repos/${repo}/milestones?state=all&per_page=100`])) || "[]");
+    const ms = (Array.isArray(list) ? list : []).find((m) => milestoneSlug(m?.title) === slug);
+    if (!ms) return { status: "refused", detail: `no milestone with slug ${slug}` };
+    if (!isSyncable(ms)) return { status: "shipped", detail: `milestone is ${parseLifecycle(ms.description)?.state ?? ms.state}: never synced` };
+    await git(["fetch", "origin", base, branch]);
+    baseSha = String(await git(["rev-parse", `origin/${base}`])).trim();
+    try { await git(["merge-base", "--is-ancestor", `origin/${base}`, `origin/${branch}`]); return { status: "up-to-date", base: baseSha }; } catch { /* behind */ }
+
+    const syncBranch = `sync/milestone-${slug}`;
+    const protectedBranch = await isProtectedBranch({ gh, repo, branch });
+    let pr = null;
+    if (protectedBranch) {
+      pr = JSON.parse(String(await gh(["pr", "list", "-R", repo, "--head", syncBranch, "--base", branch, "--state", "open", "--json", "number,body"])) || "[]")[0] ?? null;
+      const rec = readMarker(pr?.body);
+      if (rec?.base === baseSha) return { status: "unchanged", pr: pr.number, base: baseSha };
+      if (rec && reason !== "ship" && now - Number(rec.at) < debounceMs) return { status: "debounced", pr: pr.number, base: baseSha };
+    }
+
+    wt = mkdtempSync(join(tmp, "milestonesync-"));
+    await git(["worktree", "add", "--detach", wt, `origin/${branch}`]);
+    const g = (a) => git(a, { cwd: wt });
+    const ident = String(await g(["config", "user.email"]).catch(() => "")).trim() ? [] : ["-c", "user.name=ForgeDock", "-c", "user.email=forgedock@users.noreply.github.com"];
+    try { await g([...ident, "merge", "--no-edit", `origin/${base}`]); } catch {
+      const files = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=U"]).catch(() => ""));
+      const r = files.length ? await resolveBaseConflicts({ git: g, cwd: wt, files, cfg }) : { remaining: ["(unknown files)"] };
+      if (r.remaining.length) { await g(["merge", "--abort"]).catch(() => {}); return { status: "conflict", base: baseSha, paths: r.remaining }; }
+      await g([...ident, "commit", "--no-edit"]);
+    }
+    const head = String(await g(["rev-parse", "HEAD"])).trim();
+
+    if (!protectedBranch) {
+      try { await git(["push", "origin", `${head}:refs/heads/${branch}`]); return { status: "synced", base: baseSha }; } catch (e) {
+        if (!REJECTED_RE.test(String(e?.stderr ?? e?.message ?? e))) throw e; // a rule the probe could not see: take the PR path
+      }
+    }
+    const old = lines(await git(["ls-remote", "origin", `refs/heads/${syncBranch}`]).catch(() => ""))[0]?.split(/\s+/)[0] ?? "";
+    await git(["push", `--force-with-lease=refs/heads/${syncBranch}:${old}`, "origin", `${head}:refs/heads/${syncBranch}`]);
+    const body = `Sync of \`${branch}\` with \`${base}\` (${reason}). One PR per milestone: its head is updated in place when the base moves.\n\n${syncMarker({ v: 1, base: baseSha, at: now })}`;
+    let status = "pr-updated";
+    if (pr) await gh(["pr", "edit", String(pr.number), "-R", repo, "--body", body]);
+    else {
+      const url = String(await gh(["pr", "create", "-R", repo, "--base", branch, "--head", syncBranch, "--title", `chore(milestone): sync ${branch} with ${base}`, "--body", body])).trim();
+      pr = { number: Number(/(\d+)\s*$/.exec(url)?.[1]) || 0 }; status = "pr-created";
+    }
+    try { await gh(["pr", "merge", String(pr.number), "-R", repo, "--auto", "--merge"]); } catch {
+      await gh(["pr", "merge", String(pr.number), "-R", repo, "--merge"]).catch(() => {}); // CLEAN: auto-merge is refused, merge now; a blocked one stays open for its checks
+    }
+    return { status, pr: pr.number, base: baseSha };
+  } catch (e) {
+    return { status: "error", ...(baseSha ? { base: baseSha } : {}), detail: String(e?.message ?? e).split("\n")[0].slice(0, 200) };
+  } finally {
+    if (wt) { await git(["worktree", "remove", "--force", wt]).catch(() => {}); try { rmSync(wt, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+}
+
+/** `forgedock milestone-sync <slug> --reason ship|batch|conflict-risk|manual [--base BRANCH] [--repo owner/repo]`; resolves the exit code. */
+export async function runMilestoneSyncCli(argv, deps = {}) {
+  const val = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : null; };
+  const slug = argv[0] && !argv[0].startsWith("--") ? argv[0] : null;
+  const cwd = deps.cwd ?? process.cwd();
+  const repo = val("--repo") ?? deps.repo;
+  const br = readBranches(cwd);
+  const base = val("--base") ?? br.staging ?? br.default;
+  if (!slug || !repo || !base) throw new Error("usage: forgedock milestone-sync <slug> --reason ship|batch|conflict-risk|manual --repo owner/repo [--base BRANCH]");
+  const io = deps.io ?? (await import("./effects.mjs")).makeLeanIo({ repo });
+  const { readBaseMerge } = await import("../engine-cli.mjs");
+  const res = await syncMilestone({ gh: io.gh, git: (a, o = {}) => io.git(a, { cwd: o.cwd ?? cwd }), repo, slug, base,
+    branch: String(br.featurePattern || DEFAULT_FEATURE_PATTERN).replace("{slug}", slug), cfg: deps.cfg ?? readBaseMerge(cwd) ?? {}, reason: val("--reason") ?? "", debounceMs: readSyncDebounce(cwd), ...(deps.now ? { now: deps.now } : {}) });
+  (deps.print ?? ((t) => console.log(t)))(`milestone-sync: milestone/${slug} <- ${base}: ${res.status}${res.pr ? ` (#${res.pr})` : ""}${res.paths ? ` conflicts: ${res.paths.join(", ")}` : ""}${res.detail ? ` (${res.detail})` : ""}`);
+  return ["conflict", "error", "refused"].includes(res.status) ? 1 : 0;
+}

package/bin/lean/milestonesync.test.mjs

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4663: milestone sync. Real git (bare origin + clone), stub gh with a PR table; no network.
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { isSyncable, syncMilestone } from "./milestonesync.mjs";
+
+const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: ENV });
+const put = (root, files) => { for (const [p, t] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), t); } };
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+const MIN = 60000;
+
+let origin, work, calls, prs, opts;
+const gh = async (args) => {
+  calls.push(args.join(" "));
+  const a = args.join(" ");
+  if (args[0] === "api" && args[1].includes("/milestones")) return JSON.stringify([{ title: "Alpha", state: opts.msState ?? "open", description: opts.desc ?? "" }]);
+  if (args[0] === "api" && args[1].endsWith("/branches/milestone/alpha")) return opts.protected ? "true" : "false";
+  if (args[0] === "api" && args[1].includes("/rules/branches/")) return "0";
+  if (args[0] === "pr" && args[1] === "list") return JSON.stringify(prs.filter((p) => p.open));
+  if (args[0] === "pr" && args[1] === "create") { prs.push({ number: prs.length + 1, open: true, body: args[args.indexOf("--body") + 1] }); return `https://github.com/o/r/pull/${prs.length}\n`; }
+  if (args[0] === "pr" && args[1] === "edit") { prs.find((p) => p.number === Number(args[2])).body = args[args.indexOf("--body") + 1]; return ""; }
+  if (args[0] === "pr" && args[1] === "merge") { if (a.includes("--auto") && opts.clean) throw new Error("auto-merge not allowed: clean status"); return ""; }
+  throw new Error(`unexpected gh ${a}`);
+};
+const git = async (args, o = {}) => execFileSync("git", args, { cwd: o.cwd ?? work, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: ENV });
+const run = (extra = {}) => syncMilestone({ gh, git, repo: "o/r", slug: "alpha", base: "staging", reason: "batch", cfg: {}, tmp: tmpDir("msync-tmp-"), ...extra });
+const moveBase = (n) => { sh(work, "checkout", "-q", "staging"); put(work, { [`f${n}.txt`]: `${n}\n` }); commit(work, `base ${n}`); sh(work, "push", "-q", "origin", "staging"); };
+const remote = (...a) => sh(origin, ...a).trim();
+
+beforeEach(() => {
+  const root = tmpDir("msync-");
+  origin = join(root, "origin.git"); work = join(root, "work");
+  execFileSync("git", ["init", "-q", "--bare", "-b", "staging", origin]);
+  execFileSync("git", ["clone", "-q", origin, work], { env: ENV, stdio: "ignore" });
+  sh(work, "checkout", "-q", "-b", "staging");
+  put(work, { "registry.txt": "a\nb\n", "other.txt": "x\n" }); commit(work, "init"); sh(work, "push", "-q", "origin", "staging");
+  sh(work, "checkout", "-q", "-b", "milestone/alpha"); put(work, { "m.txt": "m\n" }); commit(work, "m"); sh(work, "push", "-q", "origin", "milestone/alpha");
+  calls = []; prs = []; opts = {};
+});
+
+describe("syncMilestone (#4663)", () => {
+  it("protected branch: one sync PR with auto-merge, the milestone branch is not pushed", async () => {
+    opts.protected = true; moveBase(1);
+    const before = remote("rev-parse", "milestone/alpha");
+    const r = await run();
+    assert.equal(r.status, "pr-created");
+    assert.equal(remote("rev-parse", "milestone/alpha"), before);
+    assert.match(remote("log", "--format=%s", "sync/milestone-alpha"), /base 1/);
+    assert.ok(calls.some((c) => c.startsWith("pr create") && c.includes("--head sync/milestone-alpha") && c.includes("--base milestone/alpha")));
+    assert.ok(calls.some((c) => c.startsWith("pr merge 1") && c.includes("--auto")));
+  });
+
+  it("protected CLEAN PR: falls back to a direct merge when auto-merge is refused", async () => {
+    opts.protected = true; opts.clean = true; moveBase(1);
+    assert.equal((await run()).status, "pr-created");
+    assert.ok(calls.some((c) => c.startsWith("pr merge 1") && !c.includes("--auto")));
+  });
+
+  it("a fast-moving base produces one sync PR, never closed or reopened", async () => {
+    opts.protected = true;
+    moveBase(1); assert.equal((await run({ now: 0 })).status, "pr-created");
+    const outcomes = [];
+    for (let i = 2; i <= 5; i++) { moveBase(i); outcomes.push((await run({ now: i * MIN })).status); }
+    assert.deepEqual(outcomes, ["debounced", "debounced", "debounced", "debounced"]);
+    assert.equal((await run({ now: 5 * MIN })).status, "debounced");
+    const r = await run({ now: 11 * MIN });
+    assert.equal(r.status, "pr-updated");
+    assert.equal(r.pr, 1);
+    assert.match(remote("log", "--format=%s", "sync/milestone-alpha"), /base 5/);
+    assert.equal(calls.filter((c) => c.startsWith("pr create")).length, 1);
+    assert.equal(calls.filter((c) => /^pr (close|reopen)/.test(c)).length, 0);
+    assert.equal(prs.length, 1);
+    assert.equal((await run({ now: 30 * MIN })).status, "unchanged");
+  });
+
+  it("a ship sync is not debounced", async () => {
+    opts.protected = true;
+    moveBase(1); await run({ now: 0 }); moveBase(2);
+    assert.equal((await run({ now: MIN, reason: "ship" })).status, "pr-updated");
+  });
+
+  it("refuses an unstated or unknown reason", async () => {
+    moveBase(1);
+    assert.equal((await run({ reason: "base-moved" })).status, "refused");
+  });
+
+  it("never syncs a shipped, deployed or closed milestone", async () => {
+    moveBase(1);
+    for (const o of [{ desc: '<!-- FORGE:LIFECYCLE {"v":1,"state":"shipped:staging"} -->' }, { desc: '<!-- FORGE:LIFECYCLE {"v":1,"state":"deployed:default"} -->' }, { msState: "closed" }]) {
+      opts = o; calls = [];
+      assert.equal((await run()).status, "shipped");
+      assert.ok(!calls.some((c) => c.startsWith("pr ")));
+    }
+    assert.equal(isSyncable({ state: "open", description: '<!-- FORGE:LIFECYCLE {"v":1,"state":"building"} -->' }), true);
+    assert.equal(isSyncable({ state: "open", description: '<!-- FORGE:LIFECYCLE {"v":1,"state":"shipped:staging"} -->' }), false);
+  });
+
+  it("unprotected branch: a plain push to the milestone branch, no PR", async () => {
+    moveBase(1);
+    assert.equal((await run()).status, "synced");
+    assert.match(remote("log", "--format=%s", "milestone/alpha"), /base 1/);
+    assert.ok(!calls.some((c) => c.startsWith("pr ")));
+  });
+
+  it("up to date: nothing to do", async () => {
+    assert.equal((await run()).status, "up-to-date");
+  });
+
+  it("append-only registry conflicts are resolved with the base-merge resolver", async () => {
+    sh(work, "checkout", "-q", "milestone/alpha"); put(work, { "registry.txt": "a\nb\nmilestone-row\n" }); commit(work, "reg m"); sh(work, "push", "-q", "origin", "milestone/alpha");
+    sh(work, "checkout", "-q", "staging"); put(work, { "registry.txt": "a\nb\nbase-row\n" }); commit(work, "reg base"); sh(work, "push", "-q", "origin", "staging");
+    const r = await run({ cfg: { unionGlobs: ["registry.txt"] } });
+    assert.equal(r.status, "synced");
+    const text = remote("show", "milestone/alpha:registry.txt");
+    assert.ok(text.includes("milestone-row") && text.includes("base-row"));
+  });
+
+  it("a conflict outside the resolver globs leaves the branch untouched", async () => {
+    sh(work, "checkout", "-q", "milestone/alpha"); put(work, { "other.txt": "m\n" }); commit(work, "o m"); sh(work, "push", "-q", "origin", "milestone/alpha");
+    sh(work, "checkout", "-q", "staging"); put(work, { "other.txt": "b\n" }); commit(work, "o b"); sh(work, "push", "-q", "origin", "staging");
+    const before = remote("rev-parse", "milestone/alpha");
+    const r = await run({ cfg: { unionGlobs: ["registry.txt"] } });
+    assert.equal(r.status, "conflict");
+    assert.deepEqual(r.paths, ["other.txt"]);
+    assert.equal(remote("rev-parse", "milestone/alpha"), before);
+  });
+});