forgedock 1.27.0 → 1.28.0

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/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

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.
 

package/commands/forgedock-init.md

@@ -544,6 +544,13 @@ verification:
     - "{SERVICE_PREFIX}"
 ```
 
+**env** (optional, off by default; never auto-filled): lanes already read the repo's toolchain pins (`packageManager`, `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`) at lane setup. Write this section only when the user asks for it (`--interactive`). `toolchain` overrides the pinned package manager (or `off`); `setup` runs once per fresh lane worktree before the builder, e.g. a dev-DB reconcile script. See docs/CONFIG.md → `env`.
+```yaml
+env:
+  toolchain: "{PM}@{VERSION}"
+  setup: "{SETUP_COMMAND}"
+```
+
 ### 5C: Section merge strategy
 
 For each optional section that is ALREADY ACTIVE in forge.yaml (detected in Phase 1C):