forgedock 1.36.0 → 1.37.0

package/scripts/file-deferred-followups.test.sh

@@ -16,7 +16,8 @@ echo "$*" >> "$GH_LOG"
 case "$1 $2" in
   "api -X") [ -n "${LOOKUP_FAIL:-}" ] && exit 1; cat "$SEARCH_JSON"; exit 0 ;;
   "api --paginate") [ -n "${CLAIM_FAIL:-}" ] && exit 1; cat "$COMMENTS_JSON"; exit 0 ;;
-  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; echo "https://github.com/o/r/issues/901"; exit 0 ;;
+  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; N=$(( $(cat "$T_DIR/create.n" 2>/dev/null || echo 900) + 1 )); echo "$N" > "$T_DIR/create.n"; while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$T_DIR/created.$N.body"; shift; done; echo "https://github.com/o/r/issues/$N"; exit 0 ;;
+  "label create") exit 0 ;;
   "issue comment") [ -n "${COMMENT_FAIL:-}" ] && exit 1; exit 0 ;;
   "issue reopen") [ -n "${REOPEN_FAIL:-}" ] && exit 1; exit 0 ;;
   "issue close") [ -n "${CLOSE_FAIL:-}" ] && exit 1; exit 0 ;;
@@ -25,6 +26,8 @@ case "$1 $2" in
     while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$ISSUE_BODY.edited"; shift; done; exit 0 ;;
 esac
 if [ "$1" = api ]; then
+  case "$*" in "api repos/o/r/milestones"*) cat "$T_DIR/milestones.json"; exit 0 ;; esac
+  case "$*" in "api repos/o/r/issues/10 --jq"*) cat "$T_DIR/parent.milestone"; exit 0 ;; esac
   case "$*" in *--jq*) cat "$ISSUE_BODY"; exit 0 ;; esac
   n="${2##*/}"; [ -f "$T_DIR/issue.$n.json" ] && { cat "$T_DIR/issue.$n.json"; exit 0; }
   echo "HTTP 404: Not Found" >&2; exit 1
@@ -37,7 +40,8 @@ PASS=0; FAIL=0
 ok() { PASS=$((PASS+1)); echo "PASS: $1"; }
 bad() { FAIL=$((FAIL+1)); echo "FAIL: $1"; }
 check() { if eval "$2"; then ok "$1"; else bad "$1"; fi; }
-reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN
+reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json "$T/create.n"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN FORGE_FOLLOWUP_MILESTONE FORGE_FOLLOWUPS_DEFAULT_MILESTONE FORGE_EXTERNAL_PREREQ
+  echo '[]' > "$T/milestones.json"; : > "$T/parent.milestone"
   echo '{"items":[]}' > "$SEARCH_JSON"; echo '[]' > "$COMMENTS_JSON"; }
 # issue_json NUMBER STATE ASSOCIATION [PARENT]: REST view of a follow-up carrying the DEFERRED_FROM marker
 issue_json() { printf '{"number":%s,"state":"%s","author_association":"%s","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #%s -->"}\n' "$1" "$2" "$3" "${4:-10}" > "$T/issue.$1.json"; }
@@ -198,10 +202,113 @@ check "dry-run: no comment/reopen/close/edit" "! grep -qE '^issue (comment|reope
 # 18. #4626: a post-deploy why's [check:<id>] token is kept verbatim in the checklist line
 reset
 printf 'x\n' > "$ISSUE_BODY"
-echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"; issue_json 77 open OWNER
-printf 'R3: soak\tpost-deploy: [check:login-smoke] after a day\t\n' > "$T/check.tsv"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+printf '{"number":77,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->\\n<!-- FORGE:DEFERRED_FROM: #10 -->\\n### #10\\n<!-- FORGE:DEFERRED_CLASS: post-deploy -->"}\n' > "$T/issue.77.json"
+printf -- '-\tpost-deploy: [check:login-smoke] after a day\t\t\tR3: soak\n' > "$T/check.tsv"
 bash "$S" --parent 10 --repo o/r --items "$T/check.tsv" >/dev/null 2>&1
 check "check token kept in the checklist line" "grep -q 'post-deploy: \[check:login-smoke\] after a day' '$ISSUE_BODY.edited'"
 
+# 19. #4664: milestone inheritance
+MS='[{"title":"M1","state":"open","due_on":"2026-01-01T00:00:00Z"},{"title":"M0","state":"closed","due_on":"2025-06-01T00:00:00Z"},{"title":"M2","state":"open","due_on":"2026-06-01T00:00:00Z"},{"title":"Dflt","state":"open","due_on":null}]'
+reset; echo "$MS" > "$T/milestones.json"; export FORGE_FOLLOWUP_MILESTONE=M1
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: open parent milestone inherited" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo "$MS" > "$T/milestones.json"; echo M1 > "$T/parent.milestone"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: read from the parent when not passed" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo "$MS" > "$T/milestones.json"; export FORGE_FOLLOWUP_MILESTONE=M0
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: shipped (closed) one -> next open by due date" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo '[{"title":"M0","state":"closed","due_on":"2025-06-01T00:00:00Z"},{"title":"Dflt","state":"open","due_on":null}]' > "$T/milestones.json"
+export FORGE_FOLLOWUP_MILESTONE=M0 FORGE_FOLLOWUPS_DEFAULT_MILESTONE=Dflt
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: shipped, no next -> followups.default_milestone" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone Dflt'"
+reset; echo '[]' > "$T/milestones.json"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: parent without one -> none passed" "grep -q '^issue create' '$GH_LOG' && ! grep '^issue create' '$GH_LOG' | grep -q -- '--milestone'"
+
+# 20. #4664: one issue per class, class labels
+printf 'a/x.sh\twhy a\t\nb/y.sh\tpost-deploy: [check:smoke] later\t\t\nc/z.sh\texternal: needs a real credential\t\t\nd/w.sh\tops drill\t\tops\n-\tdefer: plain\t\t\tR9: plain item\n' > "$T/classes.tsv"
+reset
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/classes.tsv"); RC=$?
+check "classes: rc 0, one create per class (4)" "[ $RC -eq 0 ] && [ \$(grep -c '^issue create' '$GH_LOG') -eq 4 ]"
+for c in engineering post-deploy external ops; do check "classes: label followup:$c applied" "grep '^issue create' '$GH_LOG' | grep -q -- '--label followup:$c'"; done
+check "classes: external also labelled external-prerequisite" "grep '^issue create' '$GH_LOG' | grep -- 'followup:external' | grep -q -- '--label external-prerequisite'"
+check "classes: engineering has the old title, others carry the class" "grep '^issue create' '$GH_LOG' | grep -q 'follow-up (ops): 1 deferred' && grep '^issue create' '$GH_LOG' | grep -q 'follow-up: 2 deferred'"
+check "classes: telemetry lists every issue and class" "printf '%s' \"\$OUT\" | grep -q 'batched_into=#901,#902,#903,#904 filed=4 classes=engineering,external,ops,post-deploy'"
+check "classes: rows point at their class issue (a/x.sh and the R9 item share one)" "printf '%s\n' \"\$OUT\" | grep -q '^c/z.sh	90[0-9]\$' && [ \$(printf '%s\n' \"\$OUT\" | grep -E '^(a/x.sh|R9: plain item)	' | cut -f2 | sort -u | wc -l) -eq 1 ]"
+check "classes: claim markers carry the class" "grep '^issue comment 10' '$GH_LOG' | grep -q 'class=external'"
+# an existing engineering follow-up is not reused for another class
+reset
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 open OWNER; claim_json OWNER 77
+printf 'c/z.sh\texternal: needs a credential\t\n' > "$T/ext.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ext.tsv"); RC=$?
+check "classes: engineering follow-up #77 not reused for an external item" "[ $RC -eq 0 ] && grep -q '^issue create' '$GH_LOG' && ! grep -q '^issue edit 77' '$GH_LOG'"
+# a labelled-class follow-up is reused for its class
+reset
+printf 'x\n' > "$ISSUE_BODY"
+printf '{"number":78,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->\\n<!-- FORGE:DEFERRED_CLASS: external -->"}\n' > "$T/issue.78.json"; claim_json OWNER 78
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ext.tsv"); RC=$?
+check "classes: external follow-up #78 reused for external items" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG' && grep -q '^issue edit 78' '$GH_LOG'"
+
+# 21. #4664: requirement-text rows are rejected, nothing filed
+for row in 'R1: a saved mapping per entity\twhy\t' 'R1: R2: a saved mapping\twhy\t' 'add a saved mapping\twhy\t' 'a/x.sh\twhy\t\tbogus'; do
+  reset; printf "$row\n" > "$T/bad.tsv"
+  OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/bad.tsv" 2>/dev/null); RC=$?
+  check "rejected row ($(printf "$row" | cut -c1-24)): rc 2, DEFERRED_TSV=INVALID, no gh call" "[ $RC -eq 2 ] && printf '%s' \"\$OUT\" | grep -q DEFERRED_TSV=INVALID && [ ! -s '$GH_LOG' ]"
+done
+reset; printf 'a/x.sh\twhy\t\nR2: nope\twhy\t\n' > "$T/bad.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/bad.tsv" >/dev/null 2>&1
+check "one malformed row among valid ones files nothing" "[ $? -eq 2 ] && ! grep -q '^issue create' '$GH_LOG'"
+# `-` + label is a valid requirement-level row; a doubled R-prefix in the label collapses; Affected Files lists only paths
+reset; printf '%s\n' "$(printf -- '-\twhy\t\t\tR1: R2: a saved mapping')" "$(printf 'src/q.ts\twhy q\t')" > "$T/ok.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ok.tsv"); RC=$?
+check "label row accepted, prefix collapsed in stdout" "[ $RC -eq 0 ] && printf '%s\n' \"\$OUT\" | grep -q '^R1: a saved mapping	901'"
+
+check "created body: Affected Files lists only paths, checklist keeps the collapsed label" "grep -q '^- \`src/q.ts\`\$' '$T/created.901.body' && ! grep -q '^- \`R1' '$T/created.901.body' && grep -q '^- \[ \] \`R1: a saved mapping\`' '$T/created.901.body' && ! grep -q 'R1: R2:' '$T/created.901.body'"
+check "created body: DEFERRED_FROM and DEFERRED_CLASS markers" "grep -q 'FORGE:DEFERRED_FROM: #10 -->' '$T/created.901.body' && grep -q 'FORGE:DEFERRED_CLASS: engineering' '$T/created.901.body'"
+# #4739: legal path characters (parentheses, space, =, #, :) are accepted; one such row no longer aborts the batch
+reset; printf 'app/(marketing)/page.tsx\twhy\t\ndocs/My Notes.md\twhy\t\nsrc/a=b.ts\twhy\t\nsrc/#x.ts\twhy\t\nsrc/foo:bar.ts\twhy\t\n' > "$T/legal.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/legal.tsv" 2>/dev/null); RC=$?
+check "legal paths with ( ) space = # : are accepted and filed" "[ $RC -eq 0 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TSV=INVALID && grep -q '^issue create' '$GH_LOG' && grep -qF -- '- \`app/(marketing)/page.tsx\`' '$T/created.901.body' && grep -qF -- '- \`docs/My Notes.md\`' '$T/created.901.body' && grep -qF -- '- \`src/a=b.ts\`' '$T/created.901.body' && grep -qF -- '- \`src/#x.ts\`' '$T/created.901.body' && grep -qF -- '- \`src/foo:bar.ts\`' '$T/created.901.body'"
+reset; printf -- '-\tpost-deploy: [check:login-smoke] soon\t\t\tR3: soak\n' > "$T/pd.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/pd.tsv" >/dev/null 2>&1
+check "post-deploy rollup: created with the lane marker, [check:] kept, section for the parent" "grep -q 'FORGE:POSTDEPLOY_ROLLUP: default' '$T/created.901.body' && grep -q 'post-deploy: \[check:login-smoke\] soon' '$T/created.901.body' && grep -q '^### #10\$' '$T/created.901.body'"
+
+# 23. #4724: N lanes -> ONE rollup; sections per parent; duplicates stored once; owner items never join it
+reset
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:a-smoke] first\t\t\tR1: the login page renders\n-\towner: [bucket:owner] rotate the key. why\t\t\tR2: rotate the credential\n' > "$T/l1.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/l1.tsv"); RC=$?
+check "rollup: lane 1 creates one external follow-up (#901) and one rollup (#902)" "[ $RC -eq 0 ] && [ \$(grep -c '^issue create' '$GH_LOG') -eq 2 ] && grep -q 'FORGE:POSTDEPLOY_ROLLUP: default' '$T/created.902.body' && grep -q 'FORGE:DEFERRED_CLASS: external' '$T/created.901.body'"
+check "rollup: the owner item is not in the rollup" "! grep -q 'rotate the credential' '$T/created.902.body' && grep -q 'rotate the credential' '$T/created.901.body'"
+check "rollup: telemetry has per-bucket counts" "printf '%s' \"\$OUT\" | grep -q 'buckets=owner:1,post-deploy:1'"
+cp "$T/created.902.body" "$ISSUE_BODY"; : > "$GH_LOG"
+echo '{"items":[{"number":902}]}' > "$SEARCH_JSON"
+printf '{"number":902,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->"}\n' > "$T/issue.902.json"
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:a-smoke] again\t\t\tR7: The Login page renders!\n-\tpost-deploy: [bucket:date] due:2026-12-01 from:2026-10-27 later\t\t\tR8: soak for a week\n' > "$T/l2.tsv"
+OUT=$(bash "$S" --parent 11 --repo o/r --items "$T/l2.tsv"); RC=$?
+check "rollup: lane 2 appends to #902, creates nothing" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG' && grep -q '^issue edit 902' '$GH_LOG'"
+check "rollup: own section for #11, soak item added" "grep -q '^### #11\$' '$ISSUE_BODY.edited' && grep -q 'R8: soak for a week' '$ISSUE_BODY.edited' && grep -q 'FORGE:DEFERRED_FROM: #11' '$ISSUE_BODY.edited'"
+check "rollup: duplicate text from another lane stored once" "[ \$(grep -ci 'login page' '$ISSUE_BODY.edited') -eq 1 ] && printf '%s\n' \"\$OUT\" | grep -q '^R7: The Login page renders!.902'"
+# a chain: parent 20 is itself a follow-up of #10 -> the items go under the root #10, no new issue
+reset
+cp "$T/created.902.body" "$ISSUE_BODY" 2>/dev/null || true
+echo '{"items":[{"number":901}]}' > "$SEARCH_JSON"
+printf '{"number":901,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->"}\n' > "$T/issue.901.json"
+printf '{"number":20,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}\n' > "$T/issue.20.json"
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:b-smoke] chain\t\t\tR9: a chained check\n' > "$T/l3.tsv"
+bash "$S" --parent 20 --repo o/r --items "$T/l3.tsv" >/dev/null 2>&1
+check "rollup: a follow-up of a follow-up appends under its root parent, no new issue" "! grep -q '^issue create' '$GH_LOG' && grep -q 'a chained check' '$ISSUE_BODY.edited' && ! grep -q '^### #20' '$ISSUE_BODY.edited'"
+# verify-now: its own per-parent follow-up, never the rollup
+reset
+printf -- '-\tpost-deploy: [bucket:verify-now] on default already\t\t\tR1: check it now\n' > "$T/vn.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/vn.tsv")
+check "verify-now: separate per-parent issue, class verify-now, no rollup marker" "grep -q 'FORGE:DEFERRED_CLASS: verify-now' '$T/created.901.body' && ! grep -q POSTDEPLOY_ROLLUP '$T/created.901.body' && printf '%s' \"\$OUT\" | grep -q 'buckets=verify-now:1'"
+# an owner bucket on a post-deploy class row is rerouted to external
+reset
+printf -- 'x/y.sh\towner: [bucket:owner] spend\t\tpost-deploy\n' > "$T/ow.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/ow.tsv" >/dev/null 2>&1
+check "owner bucket never lands in post-deploy, even when the row says so" "grep -q 'FORGE:DEFERRED_CLASS: external' '$T/created.901.body' && ! grep -q POSTDEPLOY_ROLLUP '$T/created.901.body'"
+
 echo "passed=$PASS failed=$FAIL"
 [ "$FAIL" -eq 0 ]

package/scripts/hotspots.sh

@@ -6,7 +6,7 @@
 # yq (optional) only to read forge.yaml. Run from the repo root.
 #
 # Usage: hotspots.sh [--base <ref>] [--] <path>...
-# Config: forge.yaml maintenance.hotspot {enabled, file_lines, growth_lines, exclude_globs}; defaults true/2000/150/[]
+# Config: forge.yaml maintenance.hotspot {enabled, file_lines, growth_lines, exclude_globs}; defaults true/2000/150/[] (lockfiles are always excluded)
 #   (also when forge.yaml or yq is missing); maintenance.generated_paths (forge#4519): shell globs of generated,
 #   bot-owned files, default [].
 # Output (stdout, one JSON object):
@@ -57,7 +57,28 @@ if [ -n "$BASE" ]; then
   MB=$(git merge-base "$BASE" HEAD) || die "no merge base for $BASE and HEAD"
 fi
 HAS_HEAD=0; git rev-parse --verify -q "HEAD^{commit}" >/dev/null && HAS_HEAD=1
-GLOBS=$(printf '%s' "$CFG" | jq -r '.exclude_globs[]')
+# #4685: lockfiles are never hotspots (one dependency adds hundreds of lines); configured globs come on top
+LOCKFILE_GLOBS='package-lock.json
+*/package-lock.json
+yarn.lock
+*/yarn.lock
+pnpm-lock.yaml
+*/pnpm-lock.yaml
+bun.lockb
+*/bun.lockb
+Cargo.lock
+*/Cargo.lock
+poetry.lock
+*/poetry.lock
+uv.lock
+*/uv.lock
+go.sum
+*/go.sum
+Gemfile.lock
+*/Gemfile.lock
+composer.lock
+*/composer.lock'
+GLOBS=$(printf '%s\n%s' "$LOCKFILE_GLOBS" "$(printf '%s' "$CFG" | jq -r '.exclude_globs[]')")
 GEN_GLOBS=$(printf '%s' "$GEN_CFG" | jq -r '.[]')
 # 0 when $1 matches a newline-separated list of shell patterns in $2 (`*` crosses `/`)
 glob_hit() {

package/scripts/hotspots.test.sh

@@ -116,5 +116,14 @@ if grep -q '"rev-list"' "$TMP/trace.json"; then ok; else bad "git trace not capt
 if grep -qE '"(cat-file|show)"' "$TMP/trace.json"; then bad "blob read without --base"; else ok; fi
 if [ -e "$TMP/net.log" ]; then bad "network tool invoked: $(tr '\n' ' ' < "$TMP/net.log")"; else ok; fi
 
+# ---- #4685: lockfiles are excluded by default, with no forge.yaml; ordinary files are not ----
+new_repo
+lines web.lock 10; mkdir -p web; lines web/package-lock.json 10; lines app.py 10; commit base
+git checkout -q -b feat2
+lines more 900; cat more >> web/package-lock.json; cat more >> app.py; commit grow
+OUT="$(bash "$S" --base main -- web/package-lock.json app.py)"
+eq "lockfile excluded" "$(q '.files[0] | [.excluded,.growth]')" '[true,900]'
+eq "ordinary file not excluded" "$(q '.files[1].excluded')" 'false'
+
 echo "hotspots.test.sh: $PASS passed, $FAILN failed"
 [ "$FAILN" -eq 0 ]

package/scripts/plan-validate-live.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * scripts/plan-validate-live.mjs — bootstrap-validate's dependency-order rules on LIVE GitHub state (#4659)
+ *
+ * `forgedock plan validate --live` and the parallel-start gate in `forgedock orchestrate`. Deterministic, no LLM.
+ * Milestone (train) order: due_on ascending (nulls last), then milestone number; GitHub has no explicit order field.
+ * Each cross-milestone `Depends on` edge is `ok` (dep in an earlier milestone and closed), `held` (earlier, not
+ * shipped) or `invalid` (dep in a later milestone). Edges are read with the engine's parseDependsOn.
+ */
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { parseDependsOn } from "../bin/engine/phases.mjs";
+
+/** Milestones in train order. Input: [{ title, number, due_on }]. */
+export function orderMilestones(milestones) {
+  const due = (m) => (m?.due_on ? Date.parse(m.due_on) : Infinity);
+  return [...milestones].sort((a, b) => (due(a) - due(b) || 0) || (a.number ?? 0) - (b.number ?? 0)).map((m) => m.title);
+}
+
+/**
+ * @param {{ order: string[], issues: Array<{ number: number, milestone: string|null, body?: string, state?: string }> }} live
+ * @returns {{ ok: boolean, edges: Array<{ from: number, to: number, fromMilestone: string, toMilestone: string, state: "ok"|"held"|"invalid" }> }}
+ */
+export function classifyEdges({ order, issues }) {
+  const index = new Map(order.map((t, i) => [t, i]));
+  const byNumber = new Map(issues.map((it) => [it.number, it]));
+  const edges = [];
+  for (const it of issues) {
+    if (!it.milestone || !index.has(it.milestone)) continue;
+    for (const n of parseDependsOn(it.body, it.number)) {
+      const dep = byNumber.get(n);
+      if (!dep?.milestone || dep.milestone === it.milestone || !index.has(dep.milestone)) continue;
+      const state = index.get(dep.milestone) > index.get(it.milestone) ? "invalid"
+        : String(dep.state).toUpperCase() === "CLOSED" ? "ok" : "held";
+      edges.push({ from: it.number, to: n, fromMilestone: it.milestone, toMilestone: dep.milestone, state });
+    }
+  }
+  return { ok: !edges.some((e) => e.state === "invalid"), edges };
+}
+
+export function formatLiveReport({ edges }) {
+  if (!edges.length) return "plan validate --live: no cross-milestone edges";
+  const lines = edges.map((e) => `${e.state}: #${e.from} (${e.fromMilestone}) depends on #${e.to} (${e.toMilestone})`);
+  const n = (s) => edges.filter((e) => e.state === s).length;
+  return `${lines.join("\n")}\nplan validate --live: ${n("ok")} ok, ${n("held")} held, ${n("invalid")} invalid`;
+}
+
+const parse = (s) => { try { return JSON.parse(String(s)); } catch { return null; } };
+
+/** Read milestones and all issues of `repo` through `gh` (injectable: async (args) => stdout). */
+export async function readLive({ gh, repo }) {
+  const r = repo ? ["-R", repo] : [];
+  const ms = parse(await gh(["api", `repos/${repo || "{owner}/{repo}"}/milestones?state=all&per_page=100`, "--paginate", "--slurp"]));
+  const issues = parse(await gh(["issue", "list", ...r, "--state", "all", "--limit", "1000", "--json", "number,body,state,milestone"]));
+  if (!Array.isArray(ms) || !Array.isArray(issues)) throw new Error("could not read milestones/issues from GitHub");
+  return { order: orderMilestones(ms.flat()), issues: issues.map((i) => ({ ...i, milestone: i.milestone?.title ?? null })) };
+}
+
+/**
+ * Parallel-start gate: dependencies of `issues` (not themselves in the batch) that are not merged into `baseOf(issue)`.
+ * A dep is merged when it is CLOSED by a PR that is merged with that base. Unreadable issues are skipped (fail open:
+ * the engine's own openDependency still guards each lane); an unreadable dep counts as unmet.
+ * @returns {Promise<Array<{ issue: number, dep: number, base: string, why: string }>>}
+ */
+export async function unmetDependencies({ issues, baseOf, gh, repo }) {
+  const r = repo ? ["-R", repo] : [];
+  const view = async (n, fields) => parse(await gh(["issue", "view", String(n), ...r, "--json", fields]));
+  const inBatch = new Set(issues);
+  const unmet = [];
+  for (const n of issues) {
+    let rec;
+    try { rec = await view(n, "body,milestone"); } catch { rec = null; }
+    if (!rec || !rec.milestone) continue;
+    const base = await baseOf(n);
+    if (!base) continue;
+    for (const dep of parseDependsOn(rec.body, n).filter((d) => !inBatch.has(d))) {
+      let why = null;
+      try {
+        const d = await view(dep, "state,closedByPullRequestsReferences");
+        if (String(d?.state).toUpperCase() !== "CLOSED") why = "not closed";
+        else {
+          let merged = false;
+          for (const pr of d.closedByPullRequestsReferences ?? []) {
+            const p = parse(await gh(["pr", "view", String(pr.number), ...r, "--json", "baseRefName,mergedAt"]));
+            if (p?.mergedAt && p.baseRefName === base) { merged = true; break; }
+          }
+          if (!merged) why = `closed but not merged into ${base}`;
+        }
+      } catch { why = "unreadable"; }
+      if (why) unmet.push({ issue: n, dep, base, why });
+    }
+  }
+  return unmet;
+}
+
+const ghExec = async (args) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 100 * 1024 * 1024, timeout: 60000 });
+
+/** CLI body: `plan validate --live [--repo owner/repo] [--json]`. Returns the exit code (1 when any edge is invalid). */
+export async function runLive(argv, { gh = ghExec, out = (t) => process.stdout.write(`${t}\n`), err = (t) => process.stderr.write(`${t}\n`) } = {}) {
+  if (argv[0] !== "validate" || !argv.includes("--live")) { err("usage: forgedock plan validate --live [--repo owner/repo] [--json]"); return 2; }
+  const i = argv.indexOf("--repo");
+  const repo = i >= 0 ? argv[i + 1] : "";
+  let report;
+  try { report = classifyEdges(await readLive({ gh, repo })); } catch (e) { err(`plan validate --live: ${e.message}`); return 2; }
+  out(argv.includes("--json") ? JSON.stringify(report) : formatLiveReport(report));
+  return report.ok ? 0 : 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exitCode = await runLive(process.argv.slice(2));
+}

package/scripts/readiness.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// readiness.mjs — preview/deploy gate readiness from external prerequisites (forge#4660).
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// Usage: readiness.mjs [--repo|-R owner/name] [--target preview|staging|prod] [--digest] [--issues file.json|-]
+//
+// A prerequisite is an open issue labelled `needs-human:external` whose body has a `gates:` line
+// (`preview|staging-deploy|prod-deploy|feature-flag:<name>`, comma separated) and an `owner:` line.
+// A code issue that carries its own `gates:` line names a milestone the gate still needs.
+// Default output is the Readiness report; --digest prints the ordered human actions; --target prints
+// DEPLOYABLE or NOT DEPLOYABLE for that target and exits 1 when not deployable.
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const EXTERNAL_LABEL = "needs-human:external";
+const GATE_RE = /^(?:preview|staging-deploy|prod-deploy|feature-flag:[A-Za-z0-9._-]+)$/;
+/** Deploy target -> the gate whose open prerequisites make it not deployable. */
+export const TARGET_GATE = { preview: "preview", staging: "staging-deploy", prod: "prod-deploy" };
+
+const labelNames = (i) => (Array.isArray(i?.labels) ? i.labels.map((l) => (typeof l === "string" ? l : l?.name)) : []);
+
+/** Valid gate names from the issue body's `gates:` line(s); invalid entries are dropped. */
+export function parseGates(body) {
+  const out = [];
+  for (const m of String(body ?? "").matchAll(/^[ \t]*gates:[ \t]*(.*)$/gim)) {
+    for (const g of m[1].split(",").map((s) => s.trim().replace(/^`|`$/g, ""))) if (GATE_RE.test(g) && !out.includes(g)) out.push(g);
+  }
+  return out;
+}
+
+/** `owner:` value, or null. */
+export function parseOwner(body) {
+  const m = /^[ \t]*owner:[ \t]*(\S.*?)[ \t]*$/im.exec(String(body ?? ""));
+  return m ? m[1] : null;
+}
+
+const deps = (body) => {
+  const m = /^[ \t]*depends on[ \t]*:?[ \t]*(.*)$/gim;
+  const out = new Set();
+  for (const x of String(body ?? "").matchAll(m)) for (const n of x[1].matchAll(/#(\d+)/g)) out.add(Number(n[1]));
+  return [...out];
+};
+
+/**
+ * `issues`: open issues { number, title, body, labels, milestone?, createdAt? }; `now`: ms.
+ * Returns { gates: { <gate>: { red, blocksMerge, prerequisites:[{number,title,owner,ageDays}], milestones:[title] } }, digest:[...] }.
+ */
+export function readiness(issues, now = Date.now()) {
+  const list = Array.isArray(issues) ? issues : [];
+  const prereqs = list.filter((i) => labelNames(i).includes(EXTERNAL_LABEL));
+  const gates = {};
+  const slot = (g) => (gates[g] ??= { red: true, blocksMerge: false, prerequisites: [], milestones: [] });
+  const entry = (i) => {
+    const t = Date.parse(i.createdAt);
+    return { number: i.number, title: String(i.title ?? ""), owner: parseOwner(i.body), ageDays: Number.isFinite(t) ? Math.max(0, Math.floor((now - t) / 86400000)) : null };
+  };
+  for (const i of prereqs) for (const g of parseGates(i.body)) slot(g).prerequisites.push(entry(i));
+  for (const i of list) {
+    if (labelNames(i).includes(EXTERNAL_LABEL)) continue;
+    const ms = typeof i.milestone === "string" ? i.milestone : i.milestone?.title;
+    if (!ms) continue;
+    for (const g of parseGates(i.body)) if (gates[g] && !gates[g].milestones.includes(ms)) gates[g].milestones.push(ms);
+  }
+  return { gates, digest: digest(prereqs, now) };
+}
+
+/** Open prerequisites in dependency order (a prerequisite follows the open ones it depends on); `after` lists those. */
+export function digest(prereqs, now = Date.now()) {
+  const byNum = new Map(prereqs.map((i) => [i.number, i]));
+  const after = (i) => deps(i.body).filter((n) => n !== i.number && byNum.has(n));
+  const done = new Set(), order = [], visiting = new Set();
+  const visit = (i) => {
+    if (done.has(i.number) || visiting.has(i.number)) return; // a cycle is cut, never loops
+    visiting.add(i.number);
+    for (const n of after(i)) visit(byNum.get(n));
+    visiting.delete(i.number);
+    done.add(i.number);
+    order.push(i);
+  };
+  [...prereqs].sort((a, b) => a.number - b.number).forEach(visit);
+  return order.map((i) => {
+    const t = Date.parse(i.createdAt);
+    return { number: i.number, title: String(i.title ?? ""), owner: parseOwner(i.body), gates: parseGates(i.body),
+      ageDays: Number.isFinite(t) ? Math.max(0, Math.floor((now - t) / 86400000)) : null, after: after(i), unblocked: after(i).length === 0 };
+  });
+}
+
+/** `{ deployable, openPrerequisites }` for a target (preview|staging|prod). A feature-flag gate never affects it. */
+export function deployable(report, target) {
+  const g = report.gates[TARGET_GATE[target]];
+  const open = g ? g.prerequisites : [];
+  return { deployable: open.length === 0, openPrerequisites: open };
+}
+
+const who = (p) => `#${p.number} ${p.title.slice(0, 60)} (owner: ${p.owner ?? "unassigned"}, age: ${p.ageDays ?? "?"}d)`;
+
+export function formatReadinessReport(report) {
+  const names = Object.keys(report.gates).sort();
+  if (!names.length) return "Readiness: no open external prerequisites";
+  const lines = ["Readiness (open external prerequisites per gate):"];
+  for (const g of names) {
+    const x = report.gates[g];
+    const flag = g.startsWith("feature-flag:") ? " (flag-gated features may merge; gate stays red)" : "";
+    lines.push(`  ${g}: RED${flag}`, ...x.prerequisites.map((p) => `    - ${who(p)}`));
+    lines.push(`    code milestones needed: ${x.milestones.length ? x.milestones.join(", ") : "none recorded"}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatReadinessDigest(report) {
+  if (!report.digest.length) return "Digest: no open human actions";
+  return ["Digest (human actions, dependency order):", ...report.digest.map((d, i) =>
+    `  ${i + 1}. #${d.number} ${d.title.slice(0, 60)} [${d.gates.join(",") || "no gates"}] owner: ${d.owner ?? "unassigned"}${d.unblocked ? " - unblocked" : ` - after ${d.after.map((n) => `#${n}`).join(", ")}`}`)].join("\n");
+}
+
+function main(argv) {
+  const opt = (f) => { const k = argv.indexOf(f); return k >= 0 ? argv[k + 1] : undefined; };
+  const src = opt("--issues");
+  let issues;
+  if (src) issues = JSON.parse(readFileSync(src === "-" ? 0 : src, "utf8"));
+  else {
+    const repo = opt("--repo") ?? opt("-R");
+    const r = spawnSync("gh", ["issue", "list", ...(repo ? ["-R", repo] : []), "--state", "open", "--limit", "200", "--json", "number,title,body,labels,milestone,createdAt"], { encoding: "utf8" });
+    if (r.status !== 0) { console.error("readiness: gh issue list failed"); return 2; }
+    issues = JSON.parse(r.stdout || "[]");
+  }
+  const report = readiness(issues);
+  const target = opt("--target");
+  if (target) {
+    if (!TARGET_GATE[target]) { console.error("readiness: --target must be preview|staging|prod"); return 2; }
+    const d = deployable(report, target);
+    console.log(d.deployable ? `DEPLOYABLE ${target}` : [`NOT DEPLOYABLE ${target}: ${TARGET_GATE[target]} gate has ${d.openPrerequisites.length} open prerequisite(s)`, ...d.openPrerequisites.map((p) => `  - ${who(p)}`)].join("\n"));
+    return d.deployable ? 0 : 1;
+  }
+  console.log(argv.includes("--digest") ? formatReadinessDigest(report) : formatReadinessReport(report));
+  return 0;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/scripts/review-prepare.sh

@@ -232,6 +232,21 @@ dom_f API_DESIGN "router|routes"
 # --- Phase 2: read-only checks + the trusted full-build config gate ---
 P2_FINDINGS=""
 p2() { P2_FINDINGS="${P2_FINDINGS}${1}"$'\n'; }
+# --- review.context staleness (#4666): advisory, never blocks. Unreadable config/checker/gh = unknown, not stale ---
+CTX_GENERATED_AT=""; CTX_STALE="false"; CTX_ADVISORY="false"
+_rc=""; if type forge_root >/dev/null 2>&1; then _rc="$(forge_root 2>/dev/null)/bin/review-context.mjs"; fi
+if [ "$CONFIG_READABLE" = "true" ] && [ -f "$_rc" ] && command -v node >/dev/null 2>&1; then
+    _rcj=$(node "$_rc" check --config "$CONFIG_FILE" --root "${TOP:-$(dirname "$CONFIG_FILE")}" --repo "$REPO" --json 2>/dev/null || true)
+    if printf '%s' "$_rcj" | jq -e . >/dev/null 2>&1; then
+        CTX_GENERATED_AT=$(printf '%s' "$_rcj" | jq -r '.generated_at // ""')
+        [ "$(printf '%s' "$_rcj" | jq -r '.stale')" = "true" ] && CTX_STALE="true"
+        [ "$(printf '%s' "$_rcj" | jq -r '.advisory')" = "true" ] && CTX_ADVISORY="true"
+        while IFS= read -r _l; do [ -n "$_l" ] && p2 "REVIEW_CONTEXT_STALE: $_l"; done <<EOFRC
+$(printf '%s' "$_rcj" | jq -r '.reasons[]?.detail')
+EOFRC
+        [ "$CTX_ADVISORY" = "true" ] && p2 "REVIEW_CONTEXT_STALE: context generated ${CTX_GENERATED_AT}, $(printf '%s' "$_rcj" | jq -r '.merged_since') PRs merged since (limit $(printf '%s' "$_rcj" | jq -r '.max_merged_prs')): advisory"
+    fi
+fi
 HAS_TS=$(printf '%s\n' "$FILES" | grep -E '\.(tsx?|jsx?)$' | head -1)
 HAS_PY=$(printf '%s\n' "$FILES" | grep -E '\.py$' | head -1)
 TS_BUILD=$(cfg .verification.commands.typescript.build); PY_FORMAT=$(cfg .verification.commands.python.format)
@@ -664,6 +679,7 @@ CTX=$(jq -n \
     --argjson sa "$SCORE_AUTH" --argjson sb "$SCORE_BILLING" --argjson sc "$SCORE_CONCURRENCY" --argjson sd "$SCORE_DATABASE" --argjson si "$SCORE_INFRA" \
     --argjson ss "$SCORE_SECURITY" --argjson ssc "$SCORE_SCRAPING" --argjson sf "$SCORE_FRONTEND" --argjson sap "$SCORE_API" \
     --arg cissue "$ISSUE_NUM" --arg cflags "$CONTRACT_RISK_FLAGS" \
+    --arg cgen "$CTX_GENERATED_AT" --arg cstale "$CTX_STALE" --arg cadv "$CTX_ADVISORY" \
     --arg rdepth "$REVIEW_DEPTH" --arg rweight "$REVIEW_WEIGHT" --arg rtier "$ROSTER_TIER" --arg rreason "$ROSTER_REASON" --argjson agents "$(j_words "$SELECTED_AGENTS")" \
     --arg dmode "$REVIEW_MODE" --arg dfrom "$DELTA_FROM" --arg dcarried "$CARRIED_FROM" --argjson drounds "$FULL_ROUNDS" --slurpfile dfiles "$TMP_DIR/dfiles.json" \
     --arg pname "$PROJECT_NAME" --rawfile pctx "$TMP_DIR/pctx.txt" --arg scraping_on "$SCRAPING_ON" --arg rpath "$REPO_PATH" \
@@ -684,7 +700,7 @@ CTX=$(jq -n \
      contract: {issue: ($cissue | tonumber? // null), flags: $cflags},
      roster: {tier: $rtier, review_depth: $rdepth, review_weight: $rweight, reason: $rreason, agents: $agents},
      delta: {mode: $dmode, from: $dfrom, carried_from: $dcarried, full_rounds: $drounds, files: $dfiles[0]},
-     config: {project_name: $pname, project_context: $pctx, scraping_configured: ($scraping_on == "true"), repo_path: $rpath,
+     config: {project_name: $pname, project_context: $pctx, context_generated_at: $cgen, context_stale: ($cstale == "true"), context_advisory: ($cadv == "true"), scraping_configured: ($scraping_on == "true"), repo_path: $rpath,
               domains: {auth: $d_auth, billing: $d_billing, concurrency: $d_conc, infra: $d_infra, database: $d_db, frontend: $d_fe, security: $d_sec, api: $d_api, scraping: $d_scr}},
      templates: {source: $tsrc, base: $tbase, monolithic_catalog: $tmono},
      index_slices: {auth: $i_auth, billing: $i_billing, database: $i_db, api: $i_api, frontend: $i_fe, infrastructure: $i_infra},

package/scripts/review-prepare.test.sh

@@ -488,5 +488,22 @@ eq "oversized slices JSON is over 128 KiB" '.slices | tojson | length > 131072'
 eq "oversized security slice keeps every path" '.slices.security.paths | length' 1100
 eq "oversized full_files keeps every path" '.full_files | length' 1100
 
+# --- 13. stale review.context (#4666): REVIEW_CONTEXT_STALE finding + config flags; a fresh context emits neither ---
+printf '{"name":"app","dependencies":{"react":"18"}}\n' > "$REPO_DIR/package.json"
+STALE_CFG="$WORK/stale.yaml"
+printf 'project:\n  name: Demo\nreview:\n  tech_stack: "Next.js 15, React"\n  context: "Repo is docs-only; no code yet."\n  context_generated_at: "2026-01-01"\n' > "$STALE_CFG"
+setup feat/x staging "services/api/auth.py" "+x = 1"
+CFG_OVERRIDE="$STALE_CFG" prep "$ROOT"
+rc_is "stale context does not block" 0
+eq "stale context flagged in config" '.config.context_stale' true
+eq "stale context carries its generation date" '.config.context_generated_at' 2026-01-01
+eq "stale context emits REVIEW_CONTEXT_STALE (docs-only)" '[.phase2.findings[] | select(startswith("REVIEW_CONTEXT_STALE:") and contains("docs-only"))] | length' 1
+eq "stale context emits REVIEW_CONTEXT_STALE (tech_stack)" '[.phase2.findings[] | select(startswith("REVIEW_CONTEXT_STALE:") and contains("Next.js"))] | length' 1
+printf 'project:\n  name: Demo\nreview:\n  tech_stack: "React"\n  context: "A React app."\n' > "$STALE_CFG"
+CFG_OVERRIDE="$STALE_CFG" prep "$ROOT"
+eq "fresh context is not stale" '.config.context_stale' false
+eq "fresh context emits no REVIEW_CONTEXT_STALE" '[.phase2.findings[] | select(startswith("REVIEW_CONTEXT_STALE:"))] | length' 0
+rm -f "$REPO_DIR/package.json"
+
 echo "review-prepare tests: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]

package/scripts/settle-scope.mjs

@@ -0,0 +1,74 @@
+/**
+ * scripts/settle-scope.mjs — scope freeze and convergence for a milestone's settle (#4665). Pure, no I/O, no LLM.
+ *
+ * Settle (run the batch, re-check buildable, repeat) freezes the milestone's issue set when it begins. Issues filed
+ * later are classified by source: decomposition children of a frozen issue stay in the milestone (the parent's
+ * contract) and join the measured set; deferred follow-ups go to the next milestone or the backlog; review findings
+ * and anything else are counted as growth but are not part of the measured set.
+ */
+
+const DEFERRED_FROM_RE = /<!--\s*FORGE:DEFERRED_FROM:\s*#(\d+)\s*-->/;
+const FINDING_RE = /<!--\s*FORGE:REVIEW_FINDING\b|\breview[- ]finding\b/i;
+
+export const SOURCES = ["decomposition-child", "deferred-followup", "review-finding", "other"];
+
+/** The issue numbers open or closed in the milestone when settle begins. @param {Array<{number:number}|number>} issues */
+export function freezeScope(issues) {
+  return new Set((issues ?? []).map((i) => (typeof i === "number" ? i : i?.number)).filter(Number.isSafeInteger));
+}
+
+/**
+ * @param {{ issue: { number: number, body?: string, parent?: number|null }, measured: Set<number>, decomposedParents?: Set<number> }} a
+ * `measured` is the frozen set plus the children already admitted; `decomposedParents` the issues that were decomposed.
+ * `issue.parent` is the decomposed parent when known (e.g. from the engine's decompose record).
+ * @returns {{ source: string, target: "milestone"|"next-milestone-or-backlog"|"unchanged" }}
+ */
+export function classifyNew({ issue, measured, decomposedParents = new Set() }) {
+  const body = String(issue?.body ?? "");
+  const parent = Number.isSafeInteger(issue?.parent) ? issue.parent : null;
+  if (parent !== null && measured.has(parent) && (decomposedParents.size === 0 || decomposedParents.has(parent))) {
+    return { source: "decomposition-child", target: "milestone" };
+  }
+  if (DEFERRED_FROM_RE.test(body)) return { source: "deferred-followup", target: "next-milestone-or-backlog" };
+  if (FINDING_RE.test(body)) return { source: "review-finding", target: "unchanged" };
+  return { source: "other", target: "unchanged" };
+}
+
+/**
+ * Convergence on the frozen set plus the (transitive) children of decomposed issues in it.
+ * @param {{ frozen: Set<number>, current: Array<{ number: number, state?: string, body?: string, parent?: number|null }>, decomposedParents?: Set<number> }} a
+ * @returns {{ measured: number[], open: number[], grew: number, bySource: Record<string, number[]>, converged: boolean }}
+ */
+export function convergence({ frozen, current, decomposedParents = new Set() }) {
+  const measured = new Set(frozen);
+  const bySource = Object.fromEntries(SOURCES.map((s) => [s, []]));
+  const fresh = (current ?? []).filter((i) => !frozen.has(i.number));
+  // Children can be filed under children: admit until no more join.
+  let changed = true;
+  const seen = new Set();
+  while (changed) {
+    changed = false;
+    for (const it of fresh) {
+      if (seen.has(it.number)) continue;
+      const c = classifyNew({ issue: it, measured, decomposedParents });
+      if (c.source !== "decomposition-child") continue;
+      seen.add(it.number); measured.add(it.number); bySource[c.source].push(it.number); changed = true;
+    }
+  }
+  for (const it of fresh) {
+    if (seen.has(it.number)) continue;
+    bySource[classifyNew({ issue: it, measured, decomposedParents }).source].push(it.number);
+  }
+  const open = (current ?? []).filter((i) => measured.has(i.number) && String(i.state ?? "OPEN").toUpperCase() !== "CLOSED").map((i) => i.number);
+  const grew = SOURCES.reduce((n, s) => n + bySource[s].length, 0);
+  return { measured: [...measured], open, grew, bySource, converged: open.length === 0 };
+}
+
+/** The STOP report text: how much the set grew and where the new issues came from. */
+export function formatStopReport({ frozen, result, passes = null, limit = null }) {
+  const parts = SOURCES.filter((s) => result.bySource[s].length).map((s) => `${s} ${result.bySource[s].length} (${result.bySource[s].map((n) => `#${n}`).join(", ")})`);
+  const pass = passes !== null && limit !== null ? ` after ${passes}/${limit} passes` : "";
+  const open = result.open.map((n) => `#${n}`).join(", ") || "none";
+  return `settle STOP${pass}: ${result.open.length} open in the measured set (${open}); frozen ${frozen.size}, set grew by ${result.grew}`
+    + (parts.length ? `: ${parts.join("; ")}` : "");
+}

package/scripts/systemd/forgedock-bot-token-refresh.service

@@ -0,0 +1,7 @@
+[Unit]
+Description=Refresh the ForgeDock GitHub App installation token (1h lifetime)
+
+[Service]
+Type=oneshot
+# Edit the path to your ForgeDock checkout (or the persisted ~/.forge copy), then see docs/CONFIG.md "Bot token refresh".
+ExecStart=%h/.forge/scripts/refresh-bot-token.sh

package/scripts/systemd/forgedock-bot-token-refresh.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Refresh the ForgeDock bot token every 45 minutes
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=45min
+# Run a missed refresh right after the host wakes or the user manager restarts.
+Persistent=true
+
+[Install]
+WantedBy=timers.target