forgedock 1.26.0 → 1.28.0

package/scripts/check-devdocs-freshness.test.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# check-devdocs-freshness.test.sh — fixture PRs for scripts/check-devdocs-freshness.sh (forge#4185).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/check-devdocs-freshness.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+
+git init -q --bare "$TMP/origin.git"
+git clone -q "$TMP/origin.git" "$TMP/w" 2>/dev/null
+cd "$TMP/w" || exit 1
+git config user.email t@example.com; git config user.name t
+mkdir -p bin/lean scripts/fixtures devdocs/modules devdocs/decisions
+printf 'export const x = 1;\n' > bin/lean/lean.mjs
+printf 'test\n' > bin/lean/lean.test.mjs
+printf '#!/bin/sh\necho foo\n' > scripts/foo.sh
+printf 'fixture\n' > scripts/fixtures/f.txt
+printf '# lean\n' > devdocs/modules/lean.md
+printf '# runner\n' > devdocs/modules/runner.md
+: > devdocs/decisions/.gitkeep
+cat > devdocs/index.yaml <<'EOF'
+version: 2
+domains:
+  lean:
+    docs:
+      - path: modules/lean.md
+modules:
+  - name: runner
+    glob: "bin/runner*"
+    path: modules/runner.md
+    authority: required
+
+  - name: lean
+    glob: "bin/lean/*"
+    path: modules/lean.md
+    authority: required
+
+always_load: []
+EOF
+cat > NORTHSTAR.md <<'EOF'
+# North Star
+
+## Non-negotiables
+
+1. Deterministic first.
+
+## Runtime map
+
+| Path | Role |
+|---|---|
+| `bin/lean/*` | lean engine |
+
+## Anti-goals
+
+- More agents.
+EOF
+git add -A; git commit -qm base; git branch -M staging; git push -q origin staging 2>/dev/null
+git checkout -q -b feat
+
+reset() { git reset -q --hard origin/staging; git clean -qfd; }
+commit() { git add -A; git commit -qm change; }
+run() { # name want_rc [env...]
+  local name="$1" want="$2"; shift 2
+  env PR_BODY="" "$@" bash "$S" origin/staging >"$TMP/out" 2>&1
+  local rc=$?
+  if [ "$rc" = "$want" ]; then PASS=$((PASS+1)); else bad "$name: rc=$rc want=$want"; cat "$TMP/out"; fi
+}
+
+reset; printf 'export const x = 2;\n' > bin/lean/lean.mjs; commit
+run "bin/lean/lean.mjs without docs fails" 1
+grep -q 'bin/lean/lean.mjs' "$TMP/out" || bad "failure output names bin/lean/lean.mjs"
+
+reset; printf 'export const x = 2;\n' > bin/lean/lean.mjs; printf '# lean\nnew entry\n' > devdocs/modules/lean.md; commit
+run "bin/lean/lean.mjs + dossier passes" 0
+
+reset; printf 'export const x = 2;\n' > bin/lean/lean.mjs; printf '# runner\nedit\n' > devdocs/modules/runner.md; commit
+run "bin/lean/lean.mjs + unrelated dossier fails" 1
+
+reset; printf 'export const x = 2;\n' > bin/lean/lean.mjs; commit
+run "exemption line passes" 0 PR_BODY="Summary
+docs-not-needed: refactor only, no behaviour change"
+run "CRLF exemption line passes" 0 PR_BODY="$(printf 'Summary\r\ndocs-not-needed: typo fix\r\n')"
+run "empty exemption reason fails" 1 PR_BODY="docs-not-needed:   "
+run "inline mention is not an exemption" 1 PR_BODY="we said docs-not-needed: no"
+printf 'docs-not-needed: via file\n' > "$TMP/body"
+env PR_BODY="" bash "$S" origin/staging --body-file "$TMP/body" >"$TMP/out" 2>&1 && PASS=$((PASS+1)) || bad "--body-file exemption passes"
+
+reset; printf 'test2\n' > bin/lean/lean.test.mjs; printf 'fixture2\n' > scripts/fixtures/f.txt; printf 'x\n' > scripts/new.test.sh; commit
+run "test-only and fixture changes pass" 0
+
+reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; commit
+run "scripts/foo.sh without docs fails" 1
+
+reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; printf '# ADR\n' > devdocs/decisions/4185-x.md; commit
+run "scripts/foo.sh + new decision passes" 0
+
+reset; printf '# ADR\n' > devdocs/decisions/4185-x.md; git add -A; git commit -qm adr; git push -q origin HEAD:staging 2>/dev/null
+git fetch -q origin; reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; printf '# ADR\nedited\n' > devdocs/decisions/4185-x.md; commit
+run "editing an existing decision does not count" 1
+
+reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; sed -i.bak 's/Deterministic first./Deterministic first, always./' NORTHSTAR.md; rm -f NORTHSTAR.md.bak; commit
+run "NORTHSTAR edit outside Runtime map fails" 1
+
+reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; sed -i.bak 's/| lean engine |/| lean engine (canonical) |/' NORTHSTAR.md; rm -f NORTHSTAR.md.bak; commit
+run "NORTHSTAR edit inside Runtime map passes" 0
+
+reset; printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; sed -i.bak '/| `bin\/lean\/\*` | lean engine |/d' NORTHSTAR.md; rm -f NORTHSTAR.md.bak; commit
+run "NORTHSTAR row deleted inside Runtime map passes" 0
+
+reset; printf 'readme\n' > README.md; commit
+run "no relevant changes pass" 0
+
+reset
+env PR_BODY="" bash "$S" no/such-ref >"$TMP/out" 2>&1; [ $? = 2 ] && PASS=$((PASS+1)) || bad "unknown base ref exits 2"
+env bash "$S" >"$TMP/out" 2>&1; [ $? = 2 ] && PASS=$((PASS+1)) || bad "missing base ref and no upstream exits 2"
+
+# #4220: without a base ref the branch's upstream is the base (CI always passes it explicitly).
+git branch -q --set-upstream-to=origin/staging
+printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; commit
+env PR_BODY="" bash "$S" >"$TMP/out" 2>&1; [ $? = 1 ] && PASS=$((PASS+1)) || bad "no base ref: upstream diff, docs missing fails"
+printf 'docs-not-needed: fixture\n' > "$TMP/body"
+env PR_BODY="" bash "$S" --body-file "$TMP/body" >"$TMP/out" 2>&1; [ $? = 0 ] && PASS=$((PASS+1)) || bad "no base ref + --body-file uses the upstream"
+printf '# ADR\n' > devdocs/decisions/4220-x.md; commit
+env PR_BODY="" bash "$S" >"$TMP/out" 2>&1; [ $? = 0 ] && PASS=$((PASS+1)) || bad "no base ref: upstream diff with a new decision passes"
+git branch -q --unset-upstream
+
+echo "check-devdocs-freshness.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" = 0 ]

package/scripts/check-spec-markers.sh

@@ -91,7 +91,9 @@ MARKER_REGISTRY="
   BENCH_SCORECARD
   BLAST_RADIUS
   BLOCKED_ON_HUMAN_MERGE
+  BOOTSTRAP_PLAN
   BODY
+  BOOTSTRAP_PLAN
   BUILDER
   BUILD_BLOCKED
   CALIBRATION_CHECK
@@ -106,6 +108,7 @@ MARKER_REGISTRY="
   COORD_ISSUE
   CRITIQUE
   DECISION_RECORD
+  BOOTSTRAP_PLAN
   DECOMPOSED
   DECOMPOSE_BLOCKED
   DEGRADED_REREVIEW

package/scripts/check-spec-size.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# check-spec-size.sh — PR spec-size budget (forge#3762).
+# check-spec-size.sh — PR spec-size budget for every command spec (forge#3762, #4164).
 # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #
@@ -13,7 +13,9 @@
 # Exit:  0 pass/exempt, 1 budget violation, 2 usage/base-ref error (fail closed)
 #
 # Rules (against the merge-base of HEAD and the PR base, compared in bytes):
-#   1. Budgeted specs may not grow by more than 2% or more than 4096 bytes.
+#   1. Every commands/**/*.md spec (head files plus files deleted at head) may not grow by more
+#      than 2% or more than 4096 bytes. A new spec (absent at the base) may be at most 4096 bytes.
+#      CEILINGS adds a per-file hard size cap (path:max_bytes) checked whatever the growth.
 #   2. The NET count of canonical block markers across all of commands/**/*.md
 #      may not rise (moving a block between files, or replacing one with a stub,
 #      is allowed). Count-based until the shared helper lands (#3493).
@@ -25,8 +27,9 @@ set -uo pipefail
 
 BASE="${1:-${BASE_REF:-origin/staging}}"
 PCT_NUM=2            # 2%
-ABS_MAX=4096         # bytes
-BUDGETED="commands/review-pr.md commands/review-pr-staging.md commands/work-on/remediate.md commands/work-on/review.md commands/work-on.md"
+ABS_MAX=4096         # bytes; also the size cap for a new spec
+# Per-file hard ceilings, one path:max_bytes per line (a spec converted to a script stub stays small).
+CEILINGS="commands/issue.md:15360"
 
 SUMMARY="${GITHUB_STEP_SUMMARY:-/dev/stdout}"
 out() { printf '%s\n' "$*" >> "$SUMMARY"; }
@@ -67,27 +70,42 @@ out "## Spec-size budget (base: \`$BASE\`)"
 out ""
 out "| File | Base | Head | Delta | Delta % | Status |"
 out "|------|-----:|-----:|------:|--------:|--------|"
-for f in $BUDGETED; do
-  [ -f "$f" ] || [ "$(base_size "$f")" != 0 ] || continue
+ceiling_of() { printf '%s\n' "$CEILINGS" | awk -F: -v f="$1" '$1 == f {print $2; exit}'; }
+HEAD_FILES=$(git ls-files 'commands/*.md' | sort -u)
+BASE_FILES=$(git ls-tree -r --name-only "$BASE" -- commands | grep -E '\.md$' | sort -u)
+ALL_FILES=$(printf '%s\n%s\n' "$HEAD_FILES" "$BASE_FILES" | sort -u)
+SPECS=0
+for f in $ALL_FILES; do
+  [ -n "$f" ] || continue
+  SPECS=$((SPECS + 1))
   b=$(base_size "$f")
   h=0; [ -f "$f" ] && h=$(wc -c < "$f" | tr -d ' ')
   g=$((h - b))
+  cap=$(ceiling_of "$f")
   status="ok"
-  if [ "$g" -gt 0 ] && { [ $((g * 100)) -gt $((b * PCT_NUM)) ] || [ "$g" -gt "$ABS_MAX" ]; }; then
-    status="OVER BUDGET"; FAILURES=$((FAILURES + 1))
+  if [ "$b" -eq 0 ]; then
+    [ "$h" -gt "$ABS_MAX" ] && status="OVER BUDGET (new spec > $ABS_MAX bytes)"
+  elif [ "$g" -gt 0 ] && { [ $((g * 100)) -gt $((b * PCT_NUM)) ] || [ "$g" -gt "$ABS_MAX" ]; }; then
+    status="OVER BUDGET"
+  fi
+  if [ -n "$cap" ] && [ "$h" -gt "$cap" ]; then
+    status="OVER CEILING ($cap bytes)"
   fi
+  # Only changed or failing specs get a row; the table would otherwise list every spec.
+  [ "$g" -ne 0 ] || [ "$status" != "ok" ] || continue
+  [ "$status" = "ok" ] || FAILURES=$((FAILURES + 1))
   if [ "$b" -gt 0 ]; then
     p=$(awk -v g="$g" -v b="$b" 'BEGIN{printf "%+.2f%%", g*100/b}')
   else p="n/a"; fi
   out "| \`$f\` | $b | $h | $g | $p | $status |"
 done
+out ""
+out "$SPECS spec(s) budgeted; unchanged specs within budget are not listed."
 
 # Net marker total across every commands/**/*.md: head (working tree, incl. new
 # files) vs base (incl. files deleted at head). Fail only when the total rises.
 HEAD_TOTAL=0; BASE_TOTAL=0; MARKER_ROWS=""
-HEAD_FILES=$(git ls-files 'commands/*.md' | sort -u)
-BASE_FILES=$(git ls-tree -r --name-only "$BASE" -- commands | grep -E '\.md$' | sort -u)
-for f in $(printf '%s\n%s\n' "$HEAD_FILES" "$BASE_FILES" | sort -u); do
+for f in $ALL_FILES; do
   [ -n "$f" ] || continue
   hc=0; [ -f "$f" ] && hc=$(grep -cE "$MARKERS" "$f" 2>/dev/null || true); hc=${hc:-0}
   bc=$(git show "$BASE:$f" 2>/dev/null | grep -cE "$MARKERS" 2>/dev/null || true); bc=${bc:-0}

package/scripts/check-spec-size.test.sh

@@ -45,8 +45,30 @@ run "over 4 KB fails" 1
 reset; gen 5 >> commands/review-pr.md     # small growth under both limits
 run "small growth passes" 0
 
-reset; gen 5000 >> commands/other.md      # not a budgeted spec
-run "non-budgeted growth passes" 0
+# Every spec is budgeted (#4164): top-level and nested specs outside the old review list
+reset; gen 5000 >> commands/other.md
+run "formerly unbudgeted spec growth fails" 1; has "other spec flagged" "| \`commands/other.md\`"
+reset; gen 1000 > commands/work-on/nested.md; git add -A; git commit -qm nested; git push -q origin HEAD:staging 2>/dev/null; git fetch -q origin staging
+gen 100 >> commands/work-on/nested.md
+run "nested spec over 2% fails" 1
+git reset -q --hard HEAD~1; git push -q -f origin HEAD:staging 2>/dev/null; git fetch -q origin staging; reset
+reset; gen 2 >> commands/other.md
+run "unbudgeted-before small growth passes" 0
+
+# New specs: up to 4096 bytes
+reset; gen 100 > commands/brand-new.md; git add -A    # ~2.8 KB
+run "new spec under 4 KB passes" 0
+reset; gen 200 > commands/brand-new.md; git add -A    # ~5.6 KB
+run "new spec over 4 KB fails" 1; has "new spec flagged" "new spec >"
+
+# Per-file ceiling: commands/issue.md may not exceed 15360 bytes whatever the growth
+reset; head -c 15300 /dev/zero | tr '\0' 'x' > commands/issue.md; git add -A; git commit -qm issue; git push -q origin HEAD:staging 2>/dev/null; git fetch -q origin staging
+printf '%050d' 0 >> commands/issue.md                 # 15350 bytes: +0.3%, under the cap
+run "ceiling: under the cap passes" 0
+printf '%050d' 0 >> commands/issue.md                 # 15400 bytes: +0.65% (within 2%/4 KB) but over the cap
+run "ceiling: over the cap fails" 1; has "ceiling flagged" "OVER CEILING (15360 bytes)"
+run "ceiling: exempt label waives" 0 PR_LABELS="spec-size-exempt"
+git reset -q --hard HEAD~1; git push -q -f origin HEAD:staging 2>/dev/null; git fetch -q origin staging; reset
 
 reset; gen 100 > commands/review-pr.md    # shrink
 run "shrink passes" 0
@@ -89,9 +111,10 @@ run "copy without removal still fails" 1
 # Shared-helper stubs (forge#3778): the sourced-helper stub shape carries none of the markers, so converting an inlined block to a stub
 # is a net reduction, while re-pasting the full block still fails.
 STUB_LOC='type forge_resolve >/dev/null 2>&1 || for _r in "${FORGEDOCK_HOME:-}"; do . "$_r/scripts/lib/forge-resolve.sh"; done'
-reset; printf '%s\n' "$STUB_LOC" '. "$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP' 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/other.md
+# (appended to the large work-on.md so the byte budget stays out of the marker cases)
+reset; printf '%s\n' "$STUB_LOC" '. "$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP' 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/work-on.md
 run "one-tag-per-stub design passes" 0
-reset; : > commands/donor.md; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/other.md
+reset; : > commands/donor.md; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/work-on.md
 run "block converted to a stub passes" 0
 reset; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=""' >> commands/other.md
 run "stub plus a re-pasted resolver block fails" 1

package/scripts/ci-local/lib.mjs

@@ -327,7 +327,7 @@ export function shellQuote(s) {
 // An allowlist, not a blacklist: remote CI starts from a clean environment, so ambient operator state (agent
 // credentials, install-root overrides, git hook variables such as GIT_DIR/GIT_INDEX_FILE, FORGE_*/CLAUDE_* settings)
 // must not reach the jobs. Toolchain variables are passed through; credential-looking names are always dropped.
-const ENV_EXACT = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'TERM', 'TMPDIR', 'TMP', 'TEMP', 'TZ', 'COLORTERM', 'NO_COLOR', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'DOCKER_HOST', 'JAVA_HOME', 'GOPATH', 'GOROOT', 'GOFLAGS', 'GOCACHE', 'GOMODCACHE', 'GOPROXY', 'GOTOOLCHAIN', 'VIRTUAL_ENV', 'PYTHONPATH', 'PYTHONDONTWRITEBYTECODE', 'RUSTFLAGS', 'RUSTUP_HOME', 'SDKMAN_DIR', 'PNPM_HOME', 'BUN_INSTALL', 'NVM_DIR', 'NVM_BIN', 'NVM_INC', 'RBENV_ROOT', 'PYENV_ROOT', 'ASDF_DIR', 'ASDF_DATA_DIR', 'MISE_DATA_DIR', 'HOMEBREW_PREFIX', 'ComSpec', 'SystemRoot', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'MSYSTEM']);
+const ENV_EXACT = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'TERM', 'TMPDIR', 'TMP', 'TEMP', 'TZ', 'COLORTERM', 'NO_COLOR', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'DOCKER_HOST', 'JAVA_HOME', 'GOPATH', 'GOROOT', 'GOFLAGS', 'GOCACHE', 'GOMODCACHE', 'GOPROXY', 'GOTOOLCHAIN', 'VIRTUAL_ENV', 'PYTHONPATH', 'PYTHONDONTWRITEBYTECODE', 'RUSTFLAGS', 'RUSTUP_HOME', 'SDKMAN_DIR', 'PNPM_HOME', 'BUN_INSTALL', 'NVM_DIR', 'NVM_BIN', 'NVM_INC', 'RBENV_ROOT', 'PYENV_ROOT', 'ASDF_DIR', 'ASDF_DATA_DIR', 'MISE_DATA_DIR', 'HOMEBREW_PREFIX', 'ComSpec', 'SystemRoot', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'MSYSTEM', 'FORGE_HOST_PARALLELISM']);
 const ENV_PREFIX = ['LC_', 'XDG_', 'CARGO_', 'MAVEN_', 'M2_', 'GRADLE_', 'DOTNET_', 'npm_config_', 'NPM_CONFIG_', 'YARN_', 'UV_', 'POETRY_', 'PIP_CACHE', 'FORGE_CI_LOCAL_'];
 // Substring tokens are unambiguous; short ones (PASS, PAT, KEY, IDENT, CRED, SESSION, COOKIE) match only as whole
 // name segments (or a trailing _KEY) so benign names such as FORGE_CI_LOCAL_PASSTHROUGH or PATH are kept.
@@ -347,6 +347,13 @@ export function scrubbedEnv(extra = {}) {
   return Object.assign(env, extra);
 }
 
+// Host-derived worker cap a ForgeDock lane exports (#4182): never run more jobs/slots than FORGE_HOST_PARALLELISM.
+export function capParallel(n, env = process.env) {
+  const s = String(env?.FORGE_HOST_PARALLELISM ?? '').trim();
+  const p = /^\d+$/.test(s) ? Number(s) : 0;
+  return p > 0 ? Math.min(n, p) : n;
+}
+
 export function homeForgeDir() {
   return process.env.FORGE_CI_LOCAL_HOME || path.join(process.env.HOME || os.homedir(), '.forge');
 }

package/scripts/ci-local/parallelism.test.mjs

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { scrubbedEnv, capParallel } from "./lib.mjs";
+
+describe("ci-local host parallelism (#4182)", () => {
+  it("scrubbedEnv passes FORGE_HOST_PARALLELISM through and still drops secrets", () => {
+    const keep = { FORGE_HOST_PARALLELISM: process.env.FORGE_HOST_PARALLELISM, FD_TEST_API_TOKEN: process.env.FD_TEST_API_TOKEN, FORGE_OTHER_SETTING: process.env.FORGE_OTHER_SETTING };
+    process.env.FORGE_HOST_PARALLELISM = "2"; process.env.FD_TEST_API_TOKEN = "s3cret"; process.env.FORGE_OTHER_SETTING = "x";
+    try {
+      const env = scrubbedEnv({});
+      assert.equal(env.FORGE_HOST_PARALLELISM, "2");
+      assert.equal(env.FD_TEST_API_TOKEN, undefined);
+      assert.equal(env.FORGE_OTHER_SETTING, undefined, "other FORGE_* settings stay out");
+    } finally {
+      for (const [k, v] of Object.entries(keep)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+    }
+  });
+
+  it("capParallel caps slots/job parallelism at a positive FORGE_HOST_PARALLELISM, else leaves them alone", () => {
+    assert.equal(capParallel(4, { FORGE_HOST_PARALLELISM: "2" }), 2);
+    assert.equal(capParallel(1, { FORGE_HOST_PARALLELISM: "2" }), 1);
+    assert.equal(capParallel(4, {}), 4);
+    for (const bad of ["0", "abc", "-1", "", " "]) assert.equal(capParallel(4, { FORGE_HOST_PARALLELISM: bad }), 4, JSON.stringify(bad));
+  });
+});

package/scripts/ci-local/run.mjs

@@ -11,7 +11,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { run as runSync, commandExists, scrubbedEnv, homeForgeDir, sha256, fileHash, toolVersion, shellSplit } from './lib.mjs';
+import { run as runSync, commandExists, scrubbedEnv, capParallel, homeForgeDir, sha256, fileHash, toolVersion, shellSplit } from './lib.mjs';
 import { shellArgv } from './adapters/common.mjs';
 import { checkPortability } from './adapters/portability.mjs';
 
@@ -25,7 +25,7 @@ for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => { clean
 // ---- machine-wide slot semaphore ----
 function slotCount() {
   const n = Number(process.env.FORGE_CI_LOCAL_SLOTS);
-  return n > 0 ? n : Math.max(2, Math.min(8, Math.floor(os.cpus().length / 2)));
+  return capParallel(n > 0 ? n : Math.max(2, Math.min(8, Math.floor(os.cpus().length / 2))));
 }
 function alive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }
 
@@ -117,6 +117,16 @@ class Tail {
 async function portFree(port) { return new Promise((res) => { const s = net.createServer(); s.once('error', () => res(false)); s.listen(port, '127.0.0.1', () => s.close(() => res(true))); }); }
 const HEALTH_FLAGS = new Set(['--health-cmd', '--health-interval', '--health-timeout', '--health-retries', '--health-start-period', '--shm-size']);
 
+// forge#4181: ownership labels from the lane (FORGE_DOCKER_LABELS); a standalone run fills in defaults so it is labelled too.
+const LABEL_KEYS = ['owner', 'batch', 'lane', 'issue', 'expires'];
+export function dockerLabelArgs(env = process.env, now = Date.now()) {
+  const got = new Map();
+  for (const e of String(env.FORGE_DOCKER_LABELS || '').split(/\s+/)) { const m = /^forgedock\.([a-z]+)=([A-Za-z0-9_.-]+)$/.exec(e); if (m && !got.has(m[1])) got.set(m[1], m[2]); }
+  const dflt = { owner: '1', batch: 'adhoc', lane: `ci-local-${process.pid}`, issue: '0', expires: String(now + 6 * 3600 * 1000) };
+  for (const k of LABEL_KEYS) if (!got.has(k)) got.set(k, dflt[k]);
+  return [...got].flatMap(([k, v]) => ['--label', `forgedock.${k}=${v}`]);
+}
+
 async function startServices(job, log) {
   const started = [];
   const stop = () => { for (const n of started) runSync('docker', ['rm', '-f', n], { timeout: 30000 }); started.length = 0; };
@@ -128,11 +138,12 @@ async function startServices(job, log) {
   if (!commandExists('docker') || runSync('docker', ['info'], { timeout: 20000 }).code !== 0) return { error: 'docker is not available', finish };
   // forge#4040 (SEC-6): one docker network per job; nothing runs with --network host.
   net = `forge-ci-net-${process.pid}-${job.id.replace(/[^A-Za-z0-9_.-]/g, '-')}`.slice(0, 120);
-  const nr = runSync('docker', ['network', 'create', net], { timeout: 30000 });
+  const labels = dockerLabelArgs();
+  const nr = runSync('docker', ['network', 'create', ...labels, net], { timeout: 30000 });
   if (nr.code !== 0) { net = ''; return { error: `docker network create failed: ${(nr.err || nr.out).split('\n')[0]}`, finish }; }
   for (const svc of job.services) {
     const name = `forge-ci-${process.pid}-${job.id.replace(/[^A-Za-z0-9_.-]/g, '-')}-${svc.name}`.slice(0, 120);
-    const args = ['run', '-d', '--rm', '--name', name, '--network', net, '--network-alias', svc.name];
+    const args = ['run', '-d', '--rm', ...labels, '--name', name, '--network', net, '--network-alias', svc.name];
     const hostPorts = [];
     for (const p of svc.ports || []) {
       const m = /^(?:(\d+):)?(\d+)(?:\/(tcp|udp))?$/.exec(String(p).trim());
@@ -361,7 +372,7 @@ export async function runPlan(plan, o = {}) {
   // (DEGRADED) and a re-run resumes from the result cache.
   const maxInvS = Number(process.env.FORGE_CI_LOCAL_MAX_INVOCATION_SECONDS) || 540;
   const budgetS = Math.min(requestedS, maxInvS); const capped = requestedS > maxInvS;
-  const maxParallel = o.maxParallel || plan.config.max_parallel || Number(process.env.FORGE_CI_LOCAL_MAX_PARALLEL) || 4;
+  const maxParallel = capParallel(o.maxParallel || plan.config.max_parallel || Number(process.env.FORGE_CI_LOCAL_MAX_PARALLEL) || 4);
   const tmpRoot = fs.mkdtempSync(path.join(process.env.TMPDIR || os.tmpdir(), 'forge-ci-local.'));
   cleanups.add(() => { try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ } });
   const ctx = {

package/scripts/ci-local/scoping.mjs

@@ -342,6 +342,7 @@ export function scopeCommand(cmd, cwdRel, sctx, depth = 0) {
 
   let r = null;
   if (LINTERS[tool] && !(LINTERS[tool].sub && !LINTERS[tool].sub.has(rest[1]))) r = scopeLint(tool, rest, cmd, cwdRel, sctx, join);
+  else if (tool === 'tsc') r = scopeTsc(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'jest') r = scopeJest(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'vitest') r = scopeVitest(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'pytest' || tool === 'py.test' || (/^python[0-9.]*$/.test(tool) && rest[1] === '-m' && rest[2] === 'pytest')) r = scopeRunner('pytest', tool === 'pytest' || tool === 'py.test' ? rest.slice(1) : rest.slice(3), tool === 'pytest' || tool === 'py.test' ? [rest[0]] : rest.slice(0, 3), cmd, cwdRel, sctx, join);
@@ -507,6 +508,87 @@ function scopeMaven(rest, cmd, cwdRel, sctx, join) {
   return scoped(join([...rest, '-pl', [...mods].sort().join(','), '-amd']), mods.size, null, 'maven-affected');
 }
 
+// ---- TypeScript compiler: the owning tsconfig project(s) of the changed files and of the files that reference them ----
+const TS_EXT = set('ts tsx mts cts js jsx mjs cjs');
+const TSC_VALUE = set('-p --project -t --target -m --module --outDir --outFile --rootDir --lib --jsx --tsBuildInfoFile --declarationDir --moduleResolution --baseUrl --types --typeRoots --locale --generateTrace --maxNodeModuleJsDepth --moduleDetection --verbatimModuleSyntax');
+
+// tsconfig.json is JSON with comments and trailing commas; null when unreadable.
+function readTsconfig(sctx, dir) {
+  sctx.cache.tsconfig = sctx.cache.tsconfig || new Map();
+  if (sctx.cache.tsconfig.has(dir)) return sctx.cache.tsconfig.get(dir);
+  let cfg = null;
+  try {
+    const raw = fs.readFileSync(path.join(sctx.repo, dir, 'tsconfig.json'), 'utf8');
+    const noComments = raw.replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m, q) => q || '');
+    cfg = JSON.parse(noComments.replace(/,(\s*[}\]])/g, '$1'));
+  } catch { cfg = null; }
+  sctx.cache.tsconfig.set(dir, cfg);
+  return cfg;
+}
+
+// The directory of the nearest tsconfig.json above `file` ('.' for the repo root), or '' when none owns it.
+export function tsProjectOf(sctx, file) {
+  for (let d = px.dirname(file); ; d = px.dirname(d)) {
+    if (sctx.present.has(d === '.' ? 'tsconfig.json' : `${d}/tsconfig.json`)) return d;
+    if (d === '.' || d === '/') return '';
+  }
+}
+
+// A project `tsc -b` can build: composite itself, or listed in another tsconfig's `references`.
+function tsBuildable(sctx, dir) {
+  const cfg = readTsconfig(sctx, dir);
+  if (cfg && cfg.compilerOptions && cfg.compilerOptions.composite === true) return true;
+  if (!sctx.cache.tsRefs) {
+    sctx.cache.tsRefs = new Set();
+    for (const f of sctx.tracked) {
+      if (px.basename(f) !== 'tsconfig.json' || !sctx.present.has(f)) continue;
+      const from = px.dirname(f); const c = readTsconfig(sctx, from);
+      for (const r of (c && Array.isArray(c.references) ? c.references : [])) {
+        if (!r || typeof r.path !== 'string') continue;
+        const to = px.normalize(px.join(from, r.path));
+        sctx.cache.tsRefs.add(to.endsWith('.json') ? px.dirname(to) : to);
+      }
+    }
+  }
+  return sctx.cache.tsRefs.has(dir);
+}
+
+function scopeTsc(rest, cmd, cwdRel, sctx, join) {
+  const flags = []; let project = ''; let build = false; const buildTargets = [];
+  for (let i = 1; i < rest.length; i++) {
+    const t = rest[i];
+    if (t === '-p' || t === '--project') { if (i + 1 >= rest.length) return full(cmd, '', { selector: 'unscoped:tsc-args' }); project = rest[++i]; continue; }
+    if (t.startsWith('--project=')) { project = t.slice(10); continue; }
+    if (t === '-b' || t === '--build') { build = true; continue; }
+    if (t === '-w' || t === '--watch') return full(cmd, '', { selector: 'unscoped:tsc-watch' });
+    if (t.startsWith('-')) { flags.push(t); if (TSC_VALUE.has(t) && i + 1 < rest.length) flags.push(rest[++i]); continue; }
+    if (!build) return full(cmd, '', { selector: 'unscoped:tsc-explicit-files' });
+    buildTargets.push(t);
+  }
+  if (/[$`*?]/.test(project) || buildTargets.some((t) => /[$`*?]/.test(t))) return full(cmd, '', { selector: 'unscoped:complex-target' });
+  // The project this command checks: -p X, the single -b target, else the tsconfig in its cwd.
+  const targetOf = (t) => { const r = rel(cwdRel, t); return r.endsWith('.json') ? px.dirname(r) : r; };
+  if (buildTargets.length > 1) return full(cmd, '', { selector: 'unscoped:explicit-targets' });
+  const target = project ? targetOf(project) : buildTargets.length ? targetOf(buildTargets[0]) : rel(cwdRel, '.');
+  if (sctx.widen) return full(cmd, sctx.widen, { selector: 'tsc-project' });
+  const un = unmappedFile(sctx.changed, TS_EXT);
+  if (un) return full(cmd, `unknown-language: ${un}`, { selector: 'tsc-project' });
+  const r = reach(sctx);
+  if (r.widen) return full(cmd, r.widen, { selector: 'tsc-project' });
+  const tsFiles = [...r.files].filter((f) => TS_EXT.has(extOf(f)));
+  if (!tsFiles.length) return skipNo(0, null, 'tsc-project', 'no changed TS/JS file');
+  const owners = dedupe(tsFiles.map((f) => tsProjectOf(sctx, f)).filter(Boolean))
+    .filter((d) => target === '.' || d === target || d.startsWith(target + '/')).sort();
+  if (!owners.length) return skipNo(0, null, 'tsc-project', `no changed TS/JS file in ${target}`);
+  // A command already aimed at one non-root project is that project's check: keep it as is.
+  if (target !== '.') return scoped(cmd, owners.length, null, 'tsc-project', { projects: owners });
+  if (owners.includes('.')) return full(cmd, 'root-project', { selector: 'tsc-project', projects: owners });
+  if (owners.length === 1) return scoped(join([rest[0], build ? '-b' : '-p', fromCwd(cwdRel, owners[0]), ...flags]), 1, null, 'tsc-project', { projects: owners });
+  if (!owners.every((d) => tsBuildable(sctx, d))) return full(cmd, 'multi-project', { selector: 'tsc-project', projects: owners });
+  // Build mode rejects --noEmit; composite projects emit their declarations as the repo's own build does.
+  return scoped(join([rest[0], '-b', ...owners.map((d) => fromCwd(cwdRel, d)), ...flags.filter((f) => f !== '--noEmit')]), owners.length, null, 'tsc-project', { projects: owners });
+}
+
 function scopeMono(tool, rest, cmd, sctx, join) {
   if (sctx.widen) return full(cmd, sctx.widen, { selector: `${tool}-affected` });
   const base = sctx.from || sctx.baseRef;

package/scripts/ci-local.test.sh

@@ -432,7 +432,7 @@ SHIM
 chmod +x "$T/bin/docker"
 export FAKE_DOCKER_LOG="$T/docker.log"
 : > "$FAKE_DOCKER_LOG"
-OUT=$(PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
+OUT=$(env -u FORGE_DOCKER_LABELS PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
 eq "a service job runs when docker is available" 0 "$RC"
 LOG=$(cat "$FAKE_DOCKER_LOG")
 has "container is started with the same image" "$LOG" "postgres:16"
@@ -442,6 +442,18 @@ has "health options are passed through" "$LOG" "--health-cmd"
 hasnt "options off the safe list are dropped" "$LOG" "--privileged"
 has "container is named per run" "$LOG" "forge-ci-"
 has "container is torn down" "$LOG" "rm -f"
+# forge#4181: the network and every container carry the forgedock.* ownership labels; standalone runs get defaults
+RUNL=$(grep '^run -d' <<<"$LOG"); NETL=$(grep '^network create' <<<"$LOG")
+for k in owner=1 batch=adhoc lane=ci-local- issue=0 expires=; do has "4181: container label forgedock.$k" "$RUNL" "--label forgedock.$k"; has "4181: network label forgedock.$k" "$NETL" "--label forgedock.$k"; done
+has "4181: container keeps --rm" "$RUNL" "--rm"
+: > "$FAKE_DOCKER_LOG"
+OUT=$(FORGE_DOCKER_LABELS="forgedock.owner=1 forgedock.batch=b9 forgedock.lane=lean-42 forgedock.issue=42 forgedock.expires=1792434600394 other=x forgedock.bad=a;b" PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
+eq "4181: a labelled run passes" 0 "$RC"
+RUNL=$(grep '^run -d' "$FAKE_DOCKER_LOG"); NETL=$(grep '^network create' "$FAKE_DOCKER_LOG")
+for l in batch=b9 lane=lean-42 issue=42 expires=1792434600394; do has "4181: container gets lane label $l" "$RUNL" "--label forgedock.$l"; has "4181: network gets lane label $l" "$NETL" "--label forgedock.$l"; done
+hasnt "4181: non-forgedock entries are dropped" "$RUNL" "other=x"
+hasnt "4181: malformed entries are dropped" "$RUNL" "forgedock.bad"
+hasnt "4181: env labels replace the defaults" "$RUNL" "batch=adhoc"
 : > "$FAKE_DOCKER_LOG"
 OUT=$(FAKE_DOCKER_INFO_RC=1 PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
 eq "docker absent defers the service job (exit 0)" 0 "$RC"
@@ -776,7 +788,7 @@ OUT=$(PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch ma
 LOG=$(cat "$FAKE_DOCKER_LOG")
 eq "SEC-6: the circleci service job runs" 0 "$RC"
 hasnt "SEC-6: no --network host" "$LOG" "--network host"
-has "SEC-6: a per-job docker network is created" "$LOG" "network create forge-ci-net-"
+has "SEC-6: a per-job docker network is created" "$(grep '^network create' <<<"$LOG")" "forge-ci-net-"
 has "SEC-6: the container joins it" "$LOG" "--network forge-ci-net-"
 has "SEC-6: only the declared/default port is published, on 127.0.0.1" "$LOG" "-p 127.0.0.1:54331:5432"
 has "SEC-6: the network is removed afterwards" "$LOG" "network rm forge-ci-net-"

package/scripts/fixtures/symbol-index/other/sample.rb

@@ -0,0 +1,3 @@
+def greet(name)
+  "hi #{name}"
+end

package/scripts/fixtures/symbol-index/py/pkg/__init__.py

@@ -0,0 +1 @@
+from .c import value

package/scripts/fixtures/symbol-index/py/pkg/a.py

@@ -0,0 +1,5 @@
+from pkg import b
+
+
+def run():
+    return b.step()

package/scripts/fixtures/symbol-index/py/pkg/b.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+from . import c
+
+if TYPE_CHECKING:
+    from . import a
+
+
+def step():
+    from .a import run  # function-local: not a module-level edge
+    return c.value + (0 if run else 1)
+
+
+from .a import run as _run_alias  # noqa: E402  module-level a <-> b cycle

package/scripts/fixtures/symbol-index/py/pkg/c.py

@@ -0,0 +1 @@
+value = 1

package/scripts/fixtures/symbol-index/py/sample.py

@@ -0,0 +1,41 @@
+"""Fixture module for symbol-index.test.sh. SECRET_DOCSTRING_MARKER"""
+import os
+from collections import OrderedDict as OD
+
+__all__ = ["Greeter", "greet", "fetch", "LIMIT"]
+
+LIMIT = 10
+_cache = OD()
+
+
+def _normalise(name):
+    return name.strip().lower()
+
+
+def greet(name):
+    return "hi " + _normalise(name)
+
+
+async def fetch(key):
+    return _cache.get(key, LIMIT)
+
+
+def helper():
+    return os.getcwd()
+
+
+class Greeter:
+    """SECRET_CLASS_DOC_MARKER"""
+
+    def __init__(self, name):
+        self.name = name
+
+    @property
+    def text(self):
+        return greet(self.name)
+
+    def _shout(self):
+        return self.text.upper()
+
+    def shout(self):
+        return self._shout()

package/scripts/fixtures/symbol-index/ts/sample.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+
+export const LIMIT = 10;
+
+export function load(path: string): string {
+  return readFileSync(path, "utf8").slice(0, LIMIT);
+}
+
+export class Loader {
+  read(path: string): string {
+    return load(path);
+  }
+}