forgedock 1.35.0 → 1.37.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

package/scripts/wait-ci-green.sh

@@ -71,11 +71,13 @@ jitter() { awk -v s="$1" -v p="$JITTER_PCT" -v r="$RANDOM" 'BEGIN{ v=s*(1-p/100+
 # classify_gh <text> -> prints one class, or nothing when the text is unrecognised:
 #   limited    real rate-limit evidence (x-ratelimit-remaining: 0, HTTP 429, "API rate limit exceeded" or GraphQL "API rate limit already exceeded", secondary rate limit,
 #              abuse detection, too many requests): a wait, bounded by the whole window
-#   auth       a bare 401/403 (bad credentials, missing scope): permanent, never waited on
+#   unauth     a bare 401 (expired token, forge#4662): the refresh timer may fix it, so a small bounded retry, then an explicit auth error
+#   auth       a bare 403 (missing scope): permanent, never waited on
 #   transient  5xx / gateway / network failures: a small bounded retry (FORGE_CI_TRANSIENT_RETRIES), never the long wait
 classify_gh() {
   if printf '%s' "$1" | grep -Eqi 'api rate limit (already )?exceeded|secondary (rate )?limit|abuse detection|x-ratelimit-remaining: *0|HTTP 429|status 429|too many requests'; then echo limited
-  elif printf '%s' "$1" | grep -Eqi 'HTTP (401|403)|status (401|403)|bad credentials|requires authentication'; then echo auth
+  elif printf '%s' "$1" | grep -Eqi 'HTTP 401|status 401|bad credentials|requires authentication'; then echo unauth
+  elif printf '%s' "$1" | grep -Eqi 'HTTP 403|status 403'; then echo auth
   elif printf '%s' "$1" | grep -Eqi 'HTTP 5[0-9][0-9]|status 5[0-9][0-9]|bad gateway|service unavailable|gateway time-?out|timed? ?out|i/o timeout|connection (reset|refused)|could not resolve host|unexpected EOF|network is unreachable|TLS handshake'; then echo transient
   fi
 }
@@ -94,6 +96,10 @@ while :; do
   START_SHA=""; _hc="$(classify_gh "$(cat "$_herr" 2>/dev/null)")"
   case "$_hc" in
     auth) emit ERROR; echo "cannot read PR #$PR head in $REPO (HTTP 401/403 without rate-limit evidence)"; exit 2 ;;
+    unauth)
+      _hfail=$((_hfail + 1))
+      if [ "$_hfail" -gt 2 ]; then emit ERROR; echo "cannot read PR #$PR head in $REPO: HTTP 401 (bot token expired or revoked?) ${_hfail} times in a row; run scripts/refresh-bot-token.sh"; exit 2; fi
+      sleep "$(jitter "$INTERVAL")" ;;
     limited)
       _hlim=$((_hlim + 1))
       if [ $(( $(date +%s) - _hstart )) -ge "$TIMEOUT" ]; then emit RATE_LIMITED; echo "PR #$PR: GitHub rate-limited for the whole ${TIMEOUT}s window reading the PR head; retry later"; exit 4; fi
@@ -117,8 +123,13 @@ while :; do
       NC_OUT="$(gh pr checks "$PR" -R "$REPO" 2>&1 || true)"
       if printf '%s' "$NC_OUT" | grep -qi 'no checks reported'; then JSON='[]'
       elif GH_CLASS="$(classify_gh "$NC_OUT")"; [ "$GH_CLASS" = auth ]; then
-        # A bare 401/403 is an auth fault that never clears: fail fast instead of waiting out the window (forge#4037).
+        # A bare 403 is an auth fault that never clears: fail fast instead of waiting out the window (forge#4037).
         emit ERROR; echo "gh pr checks refused (HTTP 401/403 without rate-limit evidence); fix the token or its scopes"; exit 2
+      elif [ "$GH_CLASS" = unauth ]; then
+        # forge#4662: an expired token is unknown state, not "no checks": back off, then fail with an explicit auth message.
+        transient=$((transient + 1))
+        if [ "$transient" -gt "$TRANSIENT_MAX" ]; then emit ERROR; echo "gh pr checks refused (HTTP 401) ${transient} times in a row; the bot token is expired or revoked, run scripts/refresh-bot-token.sh"; exit 2; fi
+        sleep "$(jitter "$INTERVAL")"; continue
       elif [ "$GH_CLASS" = transient ]; then
         # Network timeout / 5xx: a small bounded retry, never the long rate-limit wait.
         transient=$((transient + 1))

package/scripts/wait-ci-green.test.sh

@@ -74,7 +74,9 @@ expect "rate limited for the whole window is RATE_LIMITED rc 4" "4|CI_GATE: RATE
 expect "more than 5 rate-limit hits are not an ERROR" "0|CI_GATE: PASS" "$(run "$(mk rlmany RATE RATE RATE RATE RATE RATE RATE "$P")" --timeout 60)"
 # forge#4037: only real rate-limit evidence is RATE_LIMITED; a bare 401/403 fails fast; timeouts/5xx are a small bounded retry.
 expect "bare 403 is a permanent error rc 2" "2|CI_GATE: ERROR" "$(run "$(mk a403 A403 "$P")" --timeout 60)"
-expect "bare 401 is a permanent error rc 2" "2|CI_GATE: ERROR" "$(run "$(mk a401 A401 "$P")" --timeout 60)"
+# forge#4662: a 401 is a refreshable token, so it is retried a bounded number of times before it is an error.
+expect "401 then pass retries (token refreshed meanwhile)" "0|CI_GATE: PASS" "$(run "$(mk a401 A401 "$P")" --timeout 60)"
+expect "persistent 401 is rc 2 after the bounded retries" "2|CI_GATE: ERROR" "$(run "$(mk a401all A401)" --timeout 60)"
 expect "HTTP 429 is RATE_LIMITED rc 4" "4|CI_GATE: RATE_LIMITED" "$(run "$(mk r429 R429)" --timeout 2)"
 expect "x-ratelimit-remaining: 0 on a 403 is RATE_LIMITED rc 4" "4|CI_GATE: RATE_LIMITED" "$(run "$(mk rhdr RHDR)" --timeout 2)"
 expect "network timeout then pass retries" "0|CI_GATE: PASS" "$(run "$(mk tmo TMO "$P")")"

package/templates/bootstrap/needs-human-issue.md

@@ -1,10 +1,13 @@
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 <!-- /bootstrap needs-human issue: one per credential, account or external input (OAuth client, cloud or DNS account,
-payment keys, API keys, legal review). Label it needs-human and set "needsHuman": true in the plan. Code issues
+payment keys, API keys, legal review). Label it needs-human and needs-human:external (the script adds the latter), give it a `gates:` line (preview|staging-deploy|prod-deploy|feature-flag:<name>) and an `owner:` line, and set "needsHuman": true in the plan. Code issues
 reference it (#{{KEY}}) but never list it under Dependencies; their mocks keep dev and CI green. Copy from "## Problem" down. -->
 ## Problem
 
+gates: preview
+owner: maintainer
+
 {which credential, account or external input is needed, and which issues use it}
 
 ### Setup steps

package/templates/github-actions/migration-journal-guard.test.mjs

@@ -0,0 +1,26 @@
+// Guard test template for repos with a drizzle-style migration journal (#4661). Copy it next to your tests and set JOURNAL.
+// Newest-only migrators (drizzle `migrate()`) skip an entry whose `when` is older than one already applied. CI migrates a
+// fresh database, so it never notices; parallel milestone branches interleave stamps and hit this on persistent databases.
+// Run in CI with the base ref fetched: BASE_REF=origin/main node --test migration-journal-guard.test.mjs
+//
+// Optional upgrade test (repo-specific, not provided): migrate a database to the base's head, apply the branch's
+// migrations, then assert that every migration the branch added is recorded as applied.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const JOURNAL = process.env.JOURNAL ?? "drizzle/meta/_journal.json";
+const BASE_REF = process.env.BASE_REF ?? "origin/main";
+const entries = JSON.parse(readFileSync(JOURNAL, "utf8")).entries;
+
+test("journal `when` strictly increases", () => {
+  for (let i = 1; i < entries.length; i++) assert.ok(entries[i].when > entries[i - 1].when, `${entries[i].tag} when ${entries[i].when} is not after ${entries[i - 1].tag}`);
+});
+
+test("no new entry is older than the base max `when`", (t) => {
+  let base;
+  try { base = JSON.parse(execFileSync("git", ["show", `${BASE_REF}:${JOURNAL}`], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })).entries; } catch { return t.skip(`no ${JOURNAL} at ${BASE_REF}`); }
+  const known = new Set(base.map((e) => e.tag)), max = Math.max(...base.map((e) => e.when));
+  for (const e of entries.filter((x) => !known.has(x.tag))) assert.ok(e.when > max, `${e.tag} when ${e.when} is not above the base max ${max}: re-stamp it with the generator`);
+});