forgedock 1.26.0 → 1.28.0

package/bin/runner.mjs

@@ -359,6 +359,37 @@ export function resolveConfiguredDefaultModel(cwd) {
   }
 }
 
+/**
+ * Whether the owner approved the paid API backend as the `auto` fallback (#4257).
+ * Needs both forge.yaml `execution.agent_backend: api` in `cwd` (repo owner) and
+ * env `FORGEDOCK_ALLOW_API_BACKEND=1` (host owner), so a committed config edit
+ * alone cannot start billing an API key. Never throws.
+ *
+ * @param {{cwd?: string, env?: object}} [opts]
+ * @returns {boolean}
+ */
+export function isApiBackendApproved({ cwd = process.cwd(), env = process.env } = {}) {
+  if (String(env?.FORGEDOCK_ALLOW_API_BACKEND ?? "").trim() !== "1") return false;
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return false;
+    return parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.execution?.agent_backend === "api";
+  } catch {
+    return false;
+  }
+}
+
+/** #4257: typed error when `auto` finds no usable CLI and the API backend is not approved. */
+function cliUnavailableError(detail = "The claude CLI is not available") {
+  const err = new Error(
+    `${detail}, and the API backend is never used implicitly. Install and authenticate the \`claude\` CLI, ` +
+      "or opt in to the API backend (forge.yaml `execution.agent_backend: api` plus FORGEDOCK_ALLOW_API_BACKEND=1), " +
+      "or pass --backend api.",
+  );
+  err.code = "CLI_BACKEND_UNAVAILABLE";
+  return err;
+}
+
 /**
  * Resolve the CLI backend timeout from forge.yaml's
  * `pipeline.cli_timeout_minutes` field, if it is a positive integer.
@@ -854,6 +885,7 @@ export function checkExecutionBackend({
   apiKey = env.ANTHROPIC_API_KEY,
   resolveCliFn = resolveClaudeCliBinary,
   spawnImpl = spawnSync,
+  apiApproved = isApiBackendApproved({ cwd, env }),
   sdkAvailableFn = () => {
     try {
       createRequire(import.meta.url).resolve("@anthropic-ai/sdk");
@@ -884,7 +916,8 @@ export function checkExecutionBackend({
         return { ready: true, backend: "cli", reason: "resolved-cli" };
       }
     }
-    if (requested === "cli") {
+    // #4257: auto never crosses to the paid API backend without the owner's opt-in.
+    if (requested === "cli" || !apiApproved) {
       return { ready: false, backend: "cli", reason: "cli-unavailable" };
     }
   }
@@ -905,7 +938,8 @@ export function checkExecutionBackend({
  * CLI and prefer it when present — but diverge on (a) which override
  * values are valid and whether an invalid one throws or is silently
  * ignored, and (b) what to return when the CLI probe fails (`resolveBackend`
- * always falls back to `"api"`; `resolveEnrichBackend` falls back to `"api"`
+ * falls back to `"api"` only with the owner's opt-in, else `"cli"` (#4257);
+ * `resolveEnrichBackend` falls back to `"api"`
  * only if `ANTHROPIC_API_KEY` is set, else `"none"`). Rather than force
  * those into one shape, this shared helper implements exactly the common
  * two steps and defers to a `cliFallback` callback for the diverging tail,
@@ -954,24 +988,27 @@ export function resolveBackendLadder({
  *   2. `"auto"` (the default) probes `isClaudeCliAvailable()`: prefers the
  *      CLI backend when a working `claude` install is detected (reuses
  *      whatever credentials the CLI already has — Pro/Max OAuth or a
- *      CLI-managed key — with no ANTHROPIC_API_KEY required), otherwise
- *      falls back to the API backend unchanged (existing behavior for every
- *      caller that never opts in to this feature).
+ *      CLI-managed key — with no ANTHROPIC_API_KEY required). Without a CLI it
+ *      falls back to the API backend ONLY when the owner opted in
+ *      (`isApiBackendApproved()`, #4257); otherwise it returns `"cli"` and
+ *      `runCommand()` fails with a typed `CLI_BACKEND_UNAVAILABLE`. The API
+ *      backend is never the implicit default.
  *
  * Delegates its shared "override-or-probe-CLI" shape to
  * `resolveBackendLadder()` (issue #2026) — this function retains its own
  * `VALID_BACKENDS` throw-on-invalid check (NOT shared; see that helper's
- * doc comment) and its own no-API-key-check fallback (always `"api"`,
- * unconditionally — the API key itself is validated lazily downstream, only
+ * doc comment) and its own opt-in-gated fallback (`"api"` only when
+ * approved — the API key itself is validated lazily downstream, only
  * if/when the api backend is actually selected).
  *
  * @param {object} [opts]
  * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
  * @param {string} [opts.cwd]       - Working directory for the CLI probe.
  * @param {object} [opts.env]       - Runtime environment used for capability checks.
+ * @param {Function} [opts.isCliAvailableFn] - Injectable CLI-presence probe (test seam).
  * @returns {"cli"|"api"}
  */
-export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env } = {}) {
+export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env, isCliAvailableFn = isClaudeCliAvailable } = {}) {
   if (!VALID_BACKENDS.has(requested)) {
     throw new Error(
       `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
@@ -982,7 +1019,8 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd(), env =
     override: requested === "auto" ? undefined : requested,
     validOverrides: new Set(["cli", "api"]),
     cwd,
-    cliFallback: () => "api",
+    isCliAvailableFn,
+    cliFallback: () => (isApiBackendApproved({ cwd, env }) ? "api" : "cli"),
   });
 }
 
@@ -2789,7 +2827,9 @@ export function renderSummaryCard(ctx) {
  * @param {string} [opts.backend]            - "cli" | "api" | "auto" (default
  *   "auto"). Resolution order when omitted: $FORGEDOCK_BACKEND env > "auto".
  *   "auto" prefers the local Claude Code CLI when detected (no
- *   ANTHROPIC_API_KEY needed), else falls back to the API backend. This
+ *   ANTHROPIC_API_KEY needed); without a CLI it uses the API backend only
+ *   with the owner's opt-in (`isApiBackendApproved()`, #4257), else it fails
+ *   with a typed CLI_BACKEND_UNAVAILABLE — api is never the default. This
  *   precedence is intentional/shipped (issue #2003's accepted acceptance
  *   criteria) and is NOT changed by issue #2020 — that issue only adds a
  *   discoverability notice (below) for the case where the ladder silently
@@ -2840,6 +2880,7 @@ export async function runCommand(opts = {}) {
 
   if (resolvedBackend === "cli" && backend === "auto") {
     const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
+    // #4257: readiness only reports api when the owner approved it.
     if (readiness.backend === "api") resolvedBackend = "api";
   }
 
@@ -2938,6 +2979,8 @@ export async function runCommand(opts = {}) {
       sessionFlags = buildMinimalSessionFlags(commandName, caps);
     }
     if (!resolvedBin && backend === "auto") {
+      // #4257: never cross to the paid API backend without the owner's opt-in.
+      if (!isApiBackendApproved({ cwd, env: runtimeEnv })) throw cliUnavailableError();
       resolvedBackend = "api";
     } else if (!resolvedBin) {
       const err = new Error("The configured claude CLI path disappeared before invocation.");

package/bin/stats/github-source.mjs

@@ -163,7 +163,7 @@ async function* listIssuePages(gh, repo, startSince) {
 }
 
 const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), createdAt: it.created_at ?? null, closedAt: it.closed_at ?? null,
-  updatedAt: it.updated_at ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
+  updatedAt: it.updated_at ?? null, milestone: it.milestone?.title ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
 
 const CHECKPOINT_EVERY = 1000;
 const RATE_CHECK_EVERY = 50;

package/bin/stats/index.mjs

@@ -13,6 +13,7 @@ import { aggregate, DEFAULT_MIN_N } from "./aggregate.mjs";
 import { fetchGithubRecords, isValidRepo, toModel } from "./github-source.mjs";
 import { readLocalRuns, runsDir } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
+import { edgeQuery, parseEdge, verdictMix } from "./query.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -34,10 +35,14 @@ delta against the previous version and a low-n flag for samples under 10. Missin
   --min-n N             low-n threshold (default ${DEFAULT_MIN_N})
   --release-times FILE  "<version> <epoch-seconds>" lines used to estimate versions of unversioned records
                         (default: git tags v* of the ForgeDock checkout)
+
+Audit queries (forge#4165; JSON, from structure_delta / run_terminal telemetry, no comment bodies read):
+  --edge FROM:TO        merged PRs that added the dependency or import edge FROM -> TO (e.g. @s/web:@s/db)
+  --milestone M         conformance verdict mix and per-day structure series for milestone M
 `;
 
 export function parseArgs(argv) {
-  const o = { since: null, repo: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const o = { since: null, repo: null, edge: null, milestone: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
   const val = (i, name) => {
     const v = argv[i + 1];
     if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
@@ -51,6 +56,8 @@ export function parseArgs(argv) {
     if (name === "--since") o.since = take();
     else if (name === "--repo") o.repo = take();
     else if (name === "--release-times") o.releaseTimes = take();
+    else if (name === "--edge") { const v = take(); if (!parseEdge(v)) throw new Error("--edge must be FROM:TO"); o.edge = v; }
+    else if (name === "--milestone") o.milestone = take();
     else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
     else if (name === "--json") o.json = true;
     else if (name === "--refresh") o.refresh = true;
@@ -153,6 +160,11 @@ export async function buildReport(opts, deps = {}) {
   if (bound.note) (deps.warn ?? ((m) => process.stderr.write(`forgedock stats: ${m}\n`)))(bound.note);
   const gh = await fetchGithubRecords({ repo, since: bound.since, refresh: opts.refresh, useCache: opts.cache, gh: deps.gh, env,
     onProgress: deps.onProgress, sleep: deps.sleep, now: deps.now });
+  if (opts.edge || opts.milestone) { // forge#4165: audit query instead of the version report
+    const e = opts.edge ? parseEdge(opts.edge) : null;
+    const query = { ...(e ? { edge: { ...e, prs: edgeQuery(gh.records, e.from, e.to) } } : {}), ...(opts.milestone ? { mix: verdictMix(gh.records, gh.items, opts.milestone) } : {}) };
+    return { repo, sources: { github: { items: gh.items.length, records: gh.records.length, cached: gh.fromCache } }, query };
+  }
   const model = toModel(repo, gh);
   const ghKeys = new Set(model.runs.map((r) => `${r.repo}#${r.issue}`));
   let local = [];
@@ -178,7 +190,7 @@ export async function runStats(argv, deps = {}) {
   }
   try {
     const report = await buildReport(opts, { onProgress: makeProgressPrinter(), ...deps });
-    process.stdout.write(`${opts.json ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
+    process.stdout.write(`${opts.json || report.query ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
     return 0;
   } catch (err) {
     process.stderr.write(`forgedock stats: ${err.message}\n`);

package/bin/stats/query.mjs

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4165: deterministic audit queries over FORGE:TELEMETRY records, so `/audit` answers "which PRs added A→B?" and
+ * "what is the conformance verdict mix for milestone M?" from structured events instead of comment archaeology.
+ * Inputs are the records and issue metadata `fetchGithubRecords` already returns; no extra API call, no model.
+ *   structure_delta (lean, merge-time): deps_added / new_edges / removed_edges as "from:to" comma lists, pr, milestone
+ *   run_terminal: reason, pr, milestone, conformance_mode, shadow_would
+ */
+
+const list = (v) => (typeof v === "string" && v !== "none" ? v.split(",").filter(Boolean) : []);
+const day = (ts) => (typeof ts === "string" ? ts.slice(0, 10) : "unknown");
+
+/** "from:to" -> {from, to}; package names hold no ":" so the last ":" splits (a scoped name keeps its "/"). */
+export function parseEdge(s) {
+  const i = String(s ?? "").lastIndexOf(":");
+  if (i <= 0 || i === String(s).length - 1) return null;
+  return { from: String(s).slice(0, i), to: String(s).slice(i + 1) };
+}
+
+/**
+ * Milestone of a record: its issue's milestone from the crawled metadata (the exact title), else the record's own field
+ * (the emitter replaces characters outside [A-Za-z0-9 _.:/#@+=,-] with "_", so it may differ from the title).
+ */
+function milestoneOf(r, byIssue) {
+  return byIssue.get(r.issue)?.milestone ?? (typeof r.milestone === "string" && r.milestone ? r.milestone : null);
+}
+
+/**
+ * PRs (and issues) whose merged change added the edge from→to: `kind` "package" (a package.json dependency) or
+ * "import" (value imports). Oldest first; one row per issue and kind (the latest record wins).
+ */
+export function edgeQuery(records, from, to) {
+  const key = `${from}:${to}`;
+  const rows = new Map();
+  for (const r of records) {
+    if (r?.event !== "structure_delta") continue;
+    for (const [field, kind] of [["deps_added", "package"], ["new_edges", "import"]]) {
+      if (!list(r[field]).includes(key)) continue;
+      const k = `${r.issue}\u0000${kind}`;
+      const prev = rows.get(k);
+      if (!prev || String(r.ts ?? "") >= String(prev.ts ?? "")) rows.set(k, { issue: r.issue ?? null, pr: r.pr ?? null, ts: r.ts ?? null, kind, milestone: r.milestone ?? null });
+    }
+  }
+  return [...rows.values()].sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")) || (a.issue ?? 0) - (b.issue ?? 0));
+}
+
+/**
+ * Conformance verdict mix of finished runs (run_terminal) and the per-day structure series (structure_delta), for one
+ * milestone or, with `milestone` null, for the whole repo. `items` is the crawled issue metadata ({number, milestone}).
+ */
+export function verdictMix(records, items = [], milestone = null) {
+  const byIssue = new Map(items.map((i) => [i.number, i]));
+  const sel = (r) => milestone == null || milestoneOf(r, byIssue) === milestone;
+  const terms = records.filter((r) => r?.event === "run_terminal" && sel(r));
+  const count = (xs, f) => xs.reduce((m, x) => { const k = f(x); if (k != null) m[k] = (m[k] ?? 0) + 1; return m; }, {});
+  const series = new Map();
+  for (const r of records) {
+    if (r?.event !== "structure_delta" || r.phase !== "merge" || !sel(r)) continue;
+    const d = day(r.ts);
+    const s = series.get(d) ?? { date: d, merged: 0, deps_added: 0, new_edges: 0, removed_edges: 0 };
+    s.merged++; s.deps_added += list(r.deps_added).length; s.new_edges += list(r.new_edges).length; s.removed_edges += list(r.removed_edges).length;
+    series.set(d, s);
+  }
+  return {
+    milestone, runs: terms.length,
+    verdicts: count(terms, (r) => (typeof r.shadow_would === "string" ? r.shadow_would : null)),
+    modes: count(terms, (r) => (typeof r.conformance_mode === "string" ? r.conformance_mode : null)),
+    reasons: count(terms, (r) => (typeof r.reason === "string" ? r.reason : null)),
+    series: [...series.values()].sort((a, b) => a.date.localeCompare(b.date)),
+  };
+}

package/bin/stats/stats.test.mjs

@@ -14,6 +14,7 @@ import { fetchGithubRecords, parseTelemetryComments, runsFromRecords, toModel }
 import { buildReport, makeProgressPrinter, parseArgs, parseSince, runStats, sinceToTimestamp } from "./index.mjs";
 import { readLocalRuns } from "./local-source.mjs";
 import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
+import { edgeQuery, parseEdge, verdictMix } from "./query.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const fx = (f) => join(here, "fixtures", f);
@@ -471,3 +472,56 @@ describe("cli", () => {
     try { assert.equal(await runStats(["--repo", "bad repo"]), 2); } finally { process.stderr.write = real; }
   });
 });
+
+describe("audit queries (forge#4165)", () => {
+  const rec = (o) => ({ v: 1, repo: "o/r", run: null, forge_version: "1.20.0", ...o });
+  const RECS = [
+    rec({ eid: "s1", ts: "2026-10-10T10:00:00Z", issue: 11, pr: 21, phase: "merge", event: "structure_delta", deps_added: "@s/web:@s/db", new_edges: "none", removed_edges: "none", decisions: "K1:lint", milestone: "M One" }),
+    rec({ eid: "s2", ts: "2026-10-11T10:00:00Z", issue: 12, pr: 22, phase: "merge", event: "structure_delta", deps_added: "none", new_edges: "@s/web:@s/db,@s/web:@s/core", removed_edges: "@s/a:@s/b", milestone: "M One" }),
+    rec({ eid: "s3", ts: "2026-10-11T11:00:00Z", issue: 13, pr: 23, phase: "merge", event: "structure_delta", deps_added: "none", new_edges: "@s/x:@s/db" }),
+    rec({ eid: "s4", ts: "2026-10-09T10:00:00Z", issue: 14, phase: "implement", event: "structure_delta", edges_added: 1 }),
+    rec({ eid: "t1", ts: "2026-10-10T10:01:00Z", issue: 11, pr: 21, event: "run_terminal", reason: "merged", conformance_mode: "shadow", shadow_would: "conforms", milestone: "M One" }),
+    rec({ eid: "t2", ts: "2026-10-11T10:01:00Z", issue: 12, pr: 22, event: "run_terminal", reason: "merged", conformance_mode: "shadow", shadow_would: "conformance.scope" }),
+    rec({ eid: "t3", ts: "2026-10-11T11:01:00Z", issue: 13, pr: 23, event: "run_terminal", reason: "merged", conformance_mode: "enforce", milestone: "M Two" }),
+  ];
+  const ITEMS = [{ number: 11, milestone: "M One" }, { number: 12, milestone: "M One" }, { number: 13, milestone: null }];
+
+  it("parseEdge splits on the last colon and rejects malformed input", () => {
+    assert.deepEqual(parseEdge("@s/web:@s/db"), { from: "@s/web", to: "@s/db" });
+    for (const bad of ["", "nocolon", ":b", "a:"]) assert.equal(parseEdge(bad), null, bad);
+  });
+  it("lists the PRs that added an edge, package or import, oldest first; exact element match only", () => {
+    assert.deepEqual(edgeQuery(RECS, "@s/web", "@s/db"), [
+      { issue: 11, pr: 21, ts: "2026-10-10T10:00:00Z", kind: "package", milestone: "M One" },
+      { issue: 12, pr: 22, ts: "2026-10-11T10:00:00Z", kind: "import", milestone: "M One" },
+    ]);
+    assert.deepEqual(edgeQuery(RECS, "@s/web", "@s/d"), [], "a prefix is not the edge");
+    assert.deepEqual(edgeQuery(RECS, "@s/a", "@s/b"), [], "a removed edge is not an added one");
+  });
+  it("verdict mix and structure series for a milestone (issue metadata first, then the record's own field)", () => {
+    const m = verdictMix(RECS, ITEMS, "M One");
+    assert.equal(m.runs, 2);
+    assert.deepEqual(m.verdicts, { conforms: 1, "conformance.scope": 1 });
+    assert.deepEqual(m.modes, { shadow: 2 });
+    assert.deepEqual(m.series, [{ date: "2026-10-10", merged: 1, deps_added: 1, new_edges: 0, removed_edges: 0 }, { date: "2026-10-11", merged: 1, deps_added: 0, new_edges: 2, removed_edges: 1 }]);
+    assert.equal(verdictMix(RECS, [], "M Two").runs, 1, "falls back to the record's milestone");
+    assert.equal(verdictMix(RECS, ITEMS, null).runs, 3, "no milestone: the whole repo");
+  });
+  it("buildReport --edge/--milestone answers from telemetry records alone; the version report is unchanged without them", async () => {
+    const body = `<!-- FORGE:TELEMETRY v1 -->\n\`\`\`jsonl\n${RECS.filter((r) => r.issue === 11 || r.issue === 12).map((r) => JSON.stringify(r)).join("\n")}\n\`\`\``;
+    const issues = [11, 12].map((n) => ({ number: n, labels: [], created_at: "2026-10-09T00:00:00Z", closed_at: null, updated_at: "2026-10-11T12:00:00Z", user: { type: "Bot" }, milestone: { title: "M One" } }));
+    const gh = (args) => {
+      const path = args.find((a) => a.startsWith("repos/")) ?? "";
+      if (/issues\/(11|12)\/comments$/.test(path)) return JSON.stringify(path.includes("/11/") ? [{ body, user: { type: "Bot" } }] : []);
+      if (/issues\/comments\?/.test(path)) return JSON.stringify(/page=1(&|$)/.test(path) ? [{ body, user: { type: "Bot" }, issue_url: "https://api.github.com/repos/o/r/issues/11" }] : []);
+      return JSON.stringify(issues);
+    };
+    const opts = { repo: "o/r", local: false, cache: false, minN: 10, ...parseArgs(["--edge", "@s/web:@s/db", "--milestone", "M One"]) };
+    const report = await buildReport({ ...opts, repo: "o/r", local: false, cache: false }, { gh, env: ENV, releaseTimes: [] });
+    assert.deepEqual(report.query.edge.prs.map((p) => [p.pr, p.kind]), [[21, "package"], [22, "import"]]);
+    assert.deepEqual(report.query.mix.verdicts, { conforms: 1, "conformance.scope": 1 });
+    assert.ok(!("groups" in report));
+    assert.throws(() => parseArgs(["--edge", "nocolon"]), /--edge must be FROM:TO/);
+    assert.deepEqual([parseArgs([]).edge, parseArgs([]).milestone], [null, null]);
+  });
+});

package/commands/adopt.md

@@ -421,6 +421,9 @@ Where `{reason}` is a brief signal: "confirmed bug + file refs", "P1 + acceptanc
 
 4. To re-run adoption on newly added issues:
    \`/adopt\` (already-labeled issues are skipped automatically)
+
+{If the repo's boundary config contains an allow-all rule (check as in `/forgedock-init` 2G: eslint-plugin-boundaries `from: [X], allow: ['*']`, dependency-cruiser with no `forbidden` rules, Nx `onlyDependOnLibsWithTags: ['*']`), add once:}
+5. Your boundary config allows every package to import every package ({FILE}: {RULE}). Consider tightening it per package; core work-on only reports import growth along allowed edges.
 ```
 
 ---

package/commands/audit.md

@@ -94,6 +94,8 @@ Read `$ARGUMENTS` carefully. The user is describing a failure — extract:
 
 ### 1B: Find related GitHub artifacts
 
+Events first: `forgedock stats --repo {GH_REPO} --edge FROM:TO` (PRs that added an edge) or `--milestone M` (verdict mix, edge series) reads `structure_delta`/`run_terminal` telemetry. Read only the matched issues; parse comments below only when the events are missing.
+
 Start from whatever the user provides (issue number, PR number, or description) and expand outward:
 
 ```bash
@@ -261,14 +263,9 @@ Classify where the breakdown occurred. Use these categories:
 - **Root cause**: The single most impactful failure point. If THIS had worked, the problem wouldn't have reached production.
 - **Contributing factors**: Other pipeline links that could have caught it as a safety net but didn't.
 
-### 3D: Cross-reference with Pipeline Hardening Principles
-
-Before proposing a fix, check which layer it belongs to (from CLAUDE.md):
+### 3D: Cross-reference with the hardening layers
 
-- **Quality gate** → static analysis, grep-catchable patterns
-- **Review agents** → semantic reasoning, library API contracts, cross-service interactions
-- **Domain detection** → broad category matching, not per-bug-instance
-- **Builder rules** → prevention at write time, simple memorable rules
+Before proposing a fix, pick its layer from `NORTHSTAR.md` § Where a fix belongs: the earliest, cheapest layer that would have stopped it (issue spec/plan rule → builder rule → deterministic check → domain detection → review prompt line → new agent, last resort).
 
 **Do NOT propose a quality-gate grep check for a reasoning failure. Do NOT propose a review-agent prompt change for a pattern grep could catch.**
 
@@ -368,7 +365,7 @@ Files that need changes:
 - If tightening a review agent: describe the reasoning step to add
 - If adding context/architect guidance: describe the lookup or trace step}
 
-**Hardening layer justification** (per CLAUDE.md Pipeline Hardening Principles):
+**Hardening layer justification** (per `NORTHSTAR.md` § Where a fix belongs):
 {Explain why this fix belongs in the proposed layer and not another}
 
 ### Related Prior Work

package/commands/autopilot.md

@@ -28,6 +28,8 @@ You are a fully autonomous deploy loop for this project. Your job is to **detect
 
 **Issue selection and priority**: Phase 2 (Fast Lane Loop) dispatches all eligible open issues **concurrently** via the durable engine — ordering is irrelevant at dispatch time because all issues start simultaneously. For scenarios requiring sequential, priority-ordered dispatch (P0 before P1 before P2, unlabeled excluded), use `scripts/select-fix-targets.sh` as the entry point. This script will be the substitution point when #1743 (economic scheduling) implements value/cost-based ordering. <!-- Added: forge#1752 -->
 
+**Maintenance budget** (#4197, only with forge.yaml `maintenance.enabled: true`): the batch runner admits P0/P1 features > maintenance-labelled issues within `maintenance.share` of lane starts (0.2 = 1 in 5) > P2+ features, and `when_idle` drains maintenance when no feature is pending. When `maintenance.scan: weekly` and the newest issue carrying a `FORGE:MAINT` marker (open or closed: `gh issue list --state all --search "FORGE:MAINT in:body" --limit 1 --json createdAt`) is older than 7 days, or none exists, run `scripts/maintenance-scan.sh --print-issue-args` once before Phase 2 and file each printed line through `/issue` programmatic mode, `Skill(skill="{FORGE_SKILL_PREFIX}issue", args=<line>)`; never raw `gh issue create`. The scan is deterministic, already deduplicated by marker, and prints nothing under threshold.
+
 **This command overrides the standard "never merge to main" rule.** `/autopilot` IS the authorized deploy system. It ships staging→main and milestone→staging→main as part of normal operation.
 
 **This command resumes from wherever the pipeline is stuck.** It always reads current GitHub state before taking any action.

package/commands/bootstrap.md

@@ -0,0 +1,35 @@
+---
+description: Guided idea-to-backlog setup for a brand-new project — interview, defaults, doubts, spike doc, validated orchestrate-ready backlog
+argument-hint: "<free text | path to docs> [--dry-run] [--spike <path>]"
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /bootstrap — idea to orchestrate-ready backlog
+
+**Input**: $ARGUMENTS
+
+This spec holds only judgment. All GitHub writes run in `scripts/bootstrap-create.mjs`. Templates live in `$(forge_root)/templates/bootstrap/`.
+
+```bash
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+BOOT_TPL="$(forge_root)/templates/bootstrap"; VALIDATE=$(forge_resolve bootstrap-validate.mjs); CREATE=$(forge_resolve bootstrap-create.mjs)
+[ -n "$VALIDATE" ] && [ -n "$CREATE" ] || { echo "ERROR: bootstrap scripts not found in a trusted ForgeDock install" >&2; exit 3; }
+```
+
+1. **Read the input.** Use the free text, or read each doc at the given path(s).
+2. **Interview** from `interview.md`. Cover every aspect it lists, briefly and conversationally. Skip what the input already answers.
+3. **Fill the blanks.** Give every unanswered aspect a sensible default with a one-line rationale tied to what the user said, using the closest `stack-profiles.md` preset. Show them all in ONE editable "Here's what I assumed" list and apply the user's edits.
+4. **Ask only genuine doubts** (they change architecture or cost: native vs PWA, data residency, self-host vs managed DB, product name, repo owner). Ask with AskUserQuestion, at most 4 multiple-choice questions per batch, each with a recommended option. Everything else stays a default. Headless (no AskUserQuestion, e.g. `npx forgedock bootstrap`): take each recommended option and list it under "Here's what I assumed".
+5. **Spike doc.** Write `technical-spike.md` to `--spike` (default `docs/engineering/technical-spike.md`); set the plan's `spikeDoc` to that path. Fill every section and give each decision an ADR-style `**Rationale**:` line.
+6. **Plan JSON** in `$TMPDIR` (shape: header of `bootstrap-validate.mjs` and `bootstrap-create.mjs`):
+   - Milestones in build order, foundation first.
+   - A `SPIKE` parent issue.
+   - Sub-issues from `issue-body.md` with planned paths, `[type:*]` tags, `priority` and `component`.
+   - `"ui": true` issues carry the full design spec. `"hero": true` issues route to `/design`.
+   - One `needs-human-issue.md` issue per credential, account or external input. Code issues reference it as `#{{KEY}}` but never depend on it, and name the mock that keeps dev and CI green.
+   - Sub-issues point at the spike via `**Parent**` only, never `Depends on`.
+   - `guardrails` and `domainRules` from the interview.
+7. **Validate.** Run `node "$VALIDATE" <plan>`. Fix the plan until it exits 0. Never create from an invalid plan.
+8. **Create.** Run `node "$CREATE" <plan>`, adding `--dry-run` when the input has it (preview only, GitHub untouched). The script reuses existing issues by title and parent, so on an error re-run the same command to resume.
+9. **Hand off.** Print the script's hand-off verbatim: what was created (links), what needs a human (links), and the `/orchestrate` command per milestone, in order.

package/commands/cleanup.md

@@ -12,6 +12,8 @@ install: extras
 
 Scan the entire development environment for rot and fix it. This is a maintenance command — run periodically or after large orchestration batches. It covers 6 domains: stale labels, orphaned issues and dead claims boards, worktree/branch pruning, milestone hygiene, and Project board sync.
 
+Issues this command or a `dead-code` finding produces carry the `maintenance` label, so `forgedock orchestrate` dispatches them within the maintenance budget (forge.yaml `maintenance.share`, #4197), not the feature queue.
+
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
 ---
@@ -47,7 +49,7 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 |-------|--------|
 | `labels` or empty | Fix stale/missing workflow labels on closed issues; detect OPEN issues stuck in intermediate states (Phase 1D) |
 | `orphans` | Close open issues whose PRs are already merged (Phase 2A/2B), and close dead orchestrate claims boards (Phase 2C) |
-| `branches` | Prune worktrees and remote branches for merged PRs |
+| `branches` | Reclaim ForgeDock-owned worktrees, tmp, docker and orphans via `forgedock gc` (3A/3B); prune remote branches for merged PRs (3C) |
 | `milestones` | Report milestones with 0 open issues (advisory — never closes) |
 | `board` | Sync closed issues to Project board with correct terminal state |
 | `batch-p3` | Sweep: fold stale unbatched P3 review findings into surface-area-grouped batch issues (same file, then leaf directory) |
@@ -321,32 +323,15 @@ echo "Claims boards closed: $BOARDS_CLOSED"
 
 ## Phase 3: Worktree & Branch Pruning
 
-### 3A: Identify worktrees with merged PRs
+### 3A/3B: Reclaim owned worktrees, tmp, docker and orphans (the `forgedock gc` reaper, #4183)
 
 ```bash
 cd {REPO_PATH}
-
-# For each worktree (excluding the main one), check if its branch has a merged PR
-REPO_NAME=$(basename "{REPO_PATH}")
-git worktree list --porcelain | grep "^worktree " | grep -v "/$REPO_NAME$" | sed 's/^worktree //' | while read wt; do
-  branch=$(git -C "$wt" branch --show-current 2>/dev/null)
-  if [ -n "$branch" ]; then
-    merged_pr=$(gh pr list --head "$branch" --state merged --json number --jq '.[0].number' 2>/dev/null)
-    if [ -n "$merged_pr" ]; then
-      echo "STALE_WT|$wt|$branch|PR#$merged_pr"
-    fi
-  fi
-done
+npx forgedock gc --worktrees --tmp --docker --processes          # dry-run report
+npx forgedock gc --worktrees --tmp --docker --processes --apply  # reclaim
 ```
 
-### 3B: Remove stale worktrees and local branches
-
-For each worktree with a merged PR:
-```bash
-git worktree remove "$WORKTREE_PATH" --force
-git branch -D "$BRANCH_NAME" 2>/dev/null || true
-echo "Removed: $WORKTREE_PATH ($BRANCH_NAME)"
-```
+It honours `forge.yaml` `hygiene:` TTLs and reclaims only what ForgeDock owns (stale lane ledgers, `lean-*`/`agent-*` worktrees that are clean and pushed, including unregistered dirs, `forgedock.owner=1` containers/volumes, `~/.forge/tmp` scratch, orphaned lane processes). Everything else is reported, never removed. Include its summary table in the report.
 
 ### 3C: Prune merged remote branches
 

package/commands/forge-stats.md

@@ -56,7 +56,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 
 `scripts/check-spec-size.sh` (job `spec-size-budget` in `check-commands.yml`, PRs only) enforces a budget that is independent of the line-count `.baselines`; the baseline is refreshed on release via `/forge-stats baseline`. It compares bytes against the PR base:
 
-- `review-pr.md`, `review-pr-staging.md`, `work-on/remediate.md`, `work-on/review.md`, `work-on.md` may not grow by more than 2% or 4 KB. Shrinking always passes.
+- Every `commands/**/*.md` spec may not grow by more than 2% or 4 KB; a new spec may be at most 4 KB. Shrinking always passes.
+- Per-file hard ceilings (`CEILINGS` in the script) cap a spec whatever its growth: `commands/issue.md` 15 KB (its procedure lives in `scripts/issue-create.sh`, #4164).
 - No `commands/**` file may gain a copy of a canonical block (FORGE_ROOT bootstrap, TRUSTED_SCRIPT/HELPER_SCRIPT resolver, FENCE_BOOTSTRAP anchor); the per-file marker count may not rise. The shared helpers (`scripts/lib/forge-resolve.sh`, `scripts/lib/fence-bootstrap.sh`) are sourced through marker-free stubs, so a conversion reads as a net reduction.
 - Exemption: the `spec-size-exempt` PR label only (needs triage rights; a PR-body marker is not honoured). The job summary lists the per-file delta and any waiver.