forgedock 1.26.0 → 1.27.0

package/scripts/bootstrap-validate.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * scripts/bootstrap-validate.mjs — mechanical backlog plan validator for /bootstrap (#4171, part of #4155)
+ *
+ * Validates a JSON backlog plan BEFORE any issue is created: milestones in build order, issues with plan keys,
+ * `#{{KEY}}` placeholders standing in for not-yet-created issue numbers, planned dependencies and bodies.
+ * Codebase-agnostic: it reads only the plan, never the repo, so planned (not-yet-existing) paths are fine.
+ *
+ * Plan shape:
+ *   {
+ *     "labels":     ["backend", ...],                      // optional: when given, every issue label must be in it
+ *     "milestones": [{ "key": "M1", "title": "..." }, ...],  // build order: foundation first
+ *     "issues": [{ "key": "API", "title": "...", "milestone": "M1", "labels": ["backend"],
+ *                  "deps": ["DB"], "needsHuman": false, "body": "## Problem\n..." }],
+ *     "numbers":    { "DB": 12 }                             // optional: real issue numbers once created
+ *   }
+ *
+ * Rejects: invalid-plan, unknown-dep, cycle, forward-milestone-dep, depends-on-mismatch, unresolved-placeholder,
+ * missing-section, missing-type-tag, missing-parent, missing-labels, unknown-label, code-depends-on-needs-human.
+ * `Depends on` lines are read with the engine's own parser (bin/engine/phases.mjs parseDependsOn) after placeholder
+ * resolution, so the plan and engine admission agree on what blocks what.
+ *
+ * Usage:
+ *   node scripts/bootstrap-validate.mjs <plan.json>
+ *   node scripts/bootstrap-validate.mjs -            # read the plan from stdin
+ *
+ * Exit codes:
+ *   0 = plan valid
+ *   1 = plan invalid (one `<KEY>: [code] message` line per error on stderr)
+ *   2 = usage error, unreadable file or bad JSON
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseDependsOn } from "../bin/engine/phases.mjs";
+
+const NEEDS_HUMAN_LABEL = "needs-human";
+const TYPE_TAG_RE = /\[type:(?:api|unit|e2e|manual)\]/;
+const CHECKBOX_RE = /^[ \t]*[-*+][ \t]+\[[ xX]\]/;
+const PLACEHOLDER_RE = /#\{\{([^{}]*)\}\}/g;
+// Synthetic numbers for keys without a real number: far above any real issue number, so they never collide.
+const SYNTHETIC_BASE = 1_000_000_000;
+
+// Mandatory Pipeline Issue Template sections (commands/issue.md Phase 3D). Matched case-insensitively on `## ` headings,
+// ignoring a trailing parenthetical such as "Root Cause (if known)".
+const SECTIONS = ["Problem", "Root Cause", "Affected Files", "Acceptance Criteria", "Context", "Dependencies"];
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
+const normHeading = (h) => h.replace(/\([^)]*\)\s*$/, "").trim().toLowerCase();
+
+/** True when the issue is a needs-human issue (credential, account or external input). */
+export function isNeedsHuman(issue) {
+  return issue?.needsHuman === true || (Array.isArray(issue?.labels) && issue.labels.includes(NEEDS_HUMAN_LABEL));
+}
+
+/**
+ * Replace every `#{{KEY}}` whose KEY is in `keyToNumber` with `#N`. Unknown keys are left in place.
+ * @param {string} body
+ * @param {Record<string, number>|Map<string, number>} keyToNumber
+ */
+export function resolvePlaceholders(body, keyToNumber) {
+  const map = keyToNumber instanceof Map ? keyToNumber : new Map(Object.entries(keyToNumber ?? {}));
+  return String(body ?? "").replace(PLACEHOLDER_RE, (whole, key) => {
+    const n = map.get(key);
+    return Number.isSafeInteger(n) && n > 0 ? `#${n}` : whole;
+  });
+}
+
+/** `## ` sections of a markdown body (fenced code blocks ignored): normalized heading -> content lines. */
+function sections(body) {
+  const out = new Map();
+  let current = null;
+  let fence = null;
+  for (const line of String(body).replace(/\r\n/g, "\n").split("\n")) {
+    const f = line.match(/^[ \t]*(`{3,}|~{3,})/);
+    if (f) {
+      if (!fence) fence = f[1][0];
+      else if (f[1][0] === fence) fence = null;
+      if (current) current.push(line);
+      continue;
+    }
+    const h = !fence && line.match(/^##(?!#)[ \t]+(.+?)[ \t]*#*[ \t]*$/);
+    if (h) {
+      current = [];
+      const name = normHeading(h[1]);
+      if (!out.has(name)) out.set(name, current);
+      continue;
+    }
+    if (current) current.push(line);
+  }
+  return out;
+}
+
+function checkStructure(plan) {
+  const errors = [];
+  const bad = (message) => errors.push({ issue: null, code: "invalid-plan", message });
+  if (!isObj(plan)) return [{ issue: null, code: "invalid-plan", message: "plan must be a JSON object" }];
+  if (!Array.isArray(plan.milestones) || plan.milestones.length === 0) bad("`milestones` must be a non-empty array");
+  if (!Array.isArray(plan.issues) || plan.issues.length === 0) bad("`issues` must be a non-empty array");
+  if (plan.labels !== undefined && !(Array.isArray(plan.labels) && plan.labels.every(isNonEmptyString))) {
+    bad("`labels` must be an array of strings when given");
+  }
+  if (plan.numbers !== undefined && !isObj(plan.numbers)) bad("`numbers` must be an object of KEY -> issue number");
+  if (errors.length) return errors;
+
+  const milestoneKeys = new Set();
+  plan.milestones.forEach((m, i) => {
+    if (!isObj(m) || !isNonEmptyString(m.key)) return bad(`milestones[${i}] needs a string \`key\``);
+    if (milestoneKeys.has(m.key)) bad(`duplicate milestone key ${m.key}`);
+    milestoneKeys.add(m.key);
+  });
+  const issueKeys = new Set();
+  plan.issues.forEach((it, i) => {
+    if (!isObj(it) || !isNonEmptyString(it.key)) return bad(`issues[${i}] needs a string \`key\``);
+    const at = (message) => errors.push({ issue: it.key, code: "invalid-plan", message });
+    if (issueKeys.has(it.key)) at(`duplicate issue key ${it.key}`);
+    issueKeys.add(it.key);
+    if (!isNonEmptyString(it.title)) at("needs a non-empty `title`");
+    if (!milestoneKeys.has(it.milestone)) at(`unknown milestone ${JSON.stringify(it.milestone)}`);
+    if (it.deps !== undefined && !(Array.isArray(it.deps) && it.deps.every(isNonEmptyString))) {
+      at("`deps` must be an array of issue keys");
+    }
+    if (it.labels !== undefined && !(Array.isArray(it.labels) && it.labels.every((l) => typeof l === "string"))) {
+      at("`labels` must be an array of strings");
+    }
+    if (typeof it.body !== "string") at("needs a string `body`");
+  });
+  return errors;
+}
+
+/** Issue keys on dependency cycles, each with one cycle path through it (DFS over known deps). */
+function findCycles(issues, byKey) {
+  const state = new Map(); // key -> 1 visiting | 2 done
+  const stack = [];
+  const onCycle = new Map();
+  const visit = (key) => {
+    state.set(key, 1);
+    stack.push(key);
+    for (const d of byKey.get(key).deps ?? []) {
+      if (!byKey.has(d)) continue;
+      if (state.get(d) === 1) {
+        const path = [...stack.slice(stack.indexOf(d)), d];
+        for (const k of path) if (!onCycle.has(k)) onCycle.set(k, path);
+      } else if (!state.has(d)) visit(d);
+    }
+    stack.pop();
+    state.set(key, 2);
+  };
+  for (const it of issues) if (!state.has(it.key)) visit(it.key);
+  return onCycle;
+}
+
+/**
+ * Validate a backlog plan. Never throws on bad input; structural problems come back as `invalid-plan` errors.
+ * @returns {{ ok: boolean, errors: Array<{ issue: string|null, code: string, message: string }> }}
+ */
+export function validatePlan(plan) {
+  const structural = checkStructure(plan);
+  if (structural.length) return { ok: false, errors: structural };
+
+  const errors = [];
+  const { issues, milestones } = plan;
+  const err = (issue, code, message) => errors.push({ issue, code, message });
+  const byKey = new Map(issues.map((it) => [it.key, it]));
+  const milestoneIndex = new Map(milestones.map((m, i) => [m.key, i]));
+  const declaredLabels = Array.isArray(plan.labels) ? new Set(plan.labels) : null;
+
+  // Every plan key resolves: to its real number when known, else to a unique synthetic one.
+  const keyToNumber = new Map();
+  issues.forEach((it, i) => {
+    const real = plan.numbers?.[it.key];
+    keyToNumber.set(it.key, Number.isSafeInteger(real) && real > 0 ? real : SYNTHETIC_BASE + i);
+  });
+  const numberToKey = new Map([...keyToNumber].map(([k, n]) => [n, k]));
+
+  const cycles = findCycles(issues, byKey);
+
+  for (const it of issues) {
+    const deps = it.deps ?? [];
+    const myMilestone = milestoneIndex.get(it.milestone);
+
+    for (const d of deps) {
+      const dep = byKey.get(d);
+      if (!dep) {
+        err(it.key, "unknown-dep", `depends on ${d}, which is not an issue in the plan`);
+        continue;
+      }
+      const depMilestone = milestoneIndex.get(dep.milestone);
+      if (depMilestone > myMilestone) {
+        err(it.key, "forward-milestone-dep",
+          `in milestone ${it.milestone} but depends on ${d} in later milestone ${dep.milestone}`);
+      }
+      if (!isNeedsHuman(it) && isNeedsHuman(dep)) {
+        err(it.key, "code-depends-on-needs-human",
+          `code issue depends on needs-human issue ${d}; reference it for real credentials, but keep mocks so it never blocks`);
+      }
+    }
+    if (cycles.has(it.key)) err(it.key, "cycle", `dependency cycle: ${cycles.get(it.key).join(" -> ")}`);
+
+    const labels = it.labels ?? [];
+    if (labels.filter(isNonEmptyString).length === 0) err(it.key, "missing-labels", "issue has no labels");
+    if (declaredLabels) {
+      for (const l of labels) {
+        if (isNonEmptyString(l) && !declaredLabels.has(l)) err(it.key, "unknown-label", `label ${l} is not in the plan's labels`);
+      }
+    }
+
+    const resolved = resolvePlaceholders(it.body, keyToNumber);
+    const unresolved = [...new Set([...resolved.matchAll(PLACEHOLDER_RE)].map((m) => m[0]))];
+    for (const p of unresolved) err(it.key, "unresolved-placeholder", `${p} does not match any issue key in the plan`);
+
+    const declared = new Set();
+    const strays = [];
+    for (const n of parseDependsOn(resolved)) {
+      if (numberToKey.has(n)) declared.add(numberToKey.get(n));
+      else strays.push(`#${n}`);
+    }
+    const planned = new Set(deps);
+    const missing = [...planned].filter((k) => !declared.has(k));
+    const extra = [...declared].filter((k) => !planned.has(k)).concat(strays);
+    if (missing.length || extra.length) {
+      const parts = [];
+      if (missing.length) parts.push(`planned but not declared: ${missing.join(", ")}`);
+      if (extra.length) parts.push(`declared but not planned: ${extra.join(", ")}`);
+      err(it.key, "depends-on-mismatch", `\`Depends on\` lines differ from planned deps (${parts.join("; ")})`);
+    }
+
+    const secs = sections(it.body);
+    for (const name of SECTIONS) {
+      if (!secs.has(name.toLowerCase())) err(it.key, "missing-section", `missing \`## ${name}\` section`);
+    }
+    const ac = secs.get("acceptance criteria");
+    if (ac) {
+      const items = ac.filter((l) => CHECKBOX_RE.test(l));
+      if (items.length === 0) err(it.key, "missing-section", "`## Acceptance Criteria` has no `- [ ]` checklist items");
+      const untagged = items.filter((l) => !TYPE_TAG_RE.test(l));
+      if (untagged.length) {
+        err(it.key, "missing-type-tag",
+          `${untagged.length} acceptance criteria lack a [type:api|unit|e2e|manual] tag: ${untagged[0].trim()}`);
+      }
+    }
+    const ctx = secs.get("context");
+    if (ctx && !ctx.some((l) => l.includes("**Parent**"))) err(it.key, "missing-parent", "`## Context` has no `**Parent**` line");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** One `<KEY>: [code] message` line per error; plan-level errors use `(plan)`. */
+export function formatErrors(errors) {
+  return errors.map((e) => `${e.issue ?? "(plan)"}: [${e.code}] ${e.message}`).join("\n");
+}
+
+function main(argv) {
+  const arg = argv[0];
+  if (!arg || argv.length > 1) {
+    process.stderr.write("usage: node scripts/bootstrap-validate.mjs <plan.json|->\n");
+    return 2;
+  }
+  let raw;
+  try {
+    raw = readFileSync(arg === "-" ? 0 : arg, "utf8");
+  } catch (e) {
+    process.stderr.write(`bootstrap-validate: cannot read ${arg}: ${e.message}\n`);
+    return 2;
+  }
+  let plan;
+  try {
+    plan = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`bootstrap-validate: invalid JSON: ${e.message}\n`);
+    return 2;
+  }
+  const { ok, errors } = validatePlan(plan);
+  if (!ok) {
+    process.stderr.write(formatErrors(errors) + "\n");
+    process.stderr.write(`bootstrap-validate: ${errors.length} error(s)\n`);
+    return 1;
+  }
+  process.stdout.write(`bootstrap-validate: OK (${plan.issues.length} issues, ${plan.milestones.length} milestones)\n`);
+  return 0;
+}
+
+// Run as CLI only when invoked directly, not when imported by tests.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/scripts/check-devdocs-freshness.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-devdocs-freshness.sh — docs must move with runtime behaviour (forge#4185).
+# A PR that changes non-test files under bin/lean/ or scripts/ must, for every such file, also:
+#   (a) touch a dossier whose devdocs/index.yaml `modules:` glob matches the file, or
+#   (b) change lines inside the `## Runtime map` section of NORTHSTAR.md, or
+#   (c) add a new devdocs/decisions/*.md.
+# Exempt: a `docs-not-needed: <reason>` line (non-empty reason) in the PR body.
+# Deterministic, no LLM. bash 3.2 portable (no bash-4 builtins, no PCRE grep).
+#
+# Usage: bash scripts/check-devdocs-freshness.sh <base-ref> [--body-file <file>]
+#   PR body: --body-file, else env PR_BODY (empty when unset). Diff: <base-ref>...HEAD, run from the repo root.
+# Exit: 0 fresh / exempt / nothing to check | 1 docs missing | 2 bad usage or unknown base ref
+
+set -u
+BASE="${1:-}"
+[ -n "$BASE" ] || { echo "usage: check-devdocs-freshness.sh <base-ref> [--body-file <file>]" >&2; exit 2; }
+shift
+BODY="${PR_BODY:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --body-file)
+      [ -f "${2:-}" ] || { echo "check-devdocs-freshness: body file not found: ${2:-}" >&2; exit 2; }
+      BODY=$(cat "$2"); shift 2 ;;
+    *) echo "check-devdocs-freshness: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null || { echo "check-devdocs-freshness: unknown base ref: $BASE" >&2; exit 2; }
+
+CHANGES=$(git diff --no-renames --name-status "${BASE}...HEAD") || { echo "check-devdocs-freshness: git diff failed" >&2; exit 2; }
+CHANGED=$(printf '%s\n' "$CHANGES" | awk -F'\t' 'NF>=2 {print $2}')
+
+# Behaviour files: non-test files under bin/lean/ or scripts/.
+BEHAVIOUR=$(printf '%s\n' "$CHANGED" | grep -E '^(bin/lean|scripts)/' \
+  | grep -vE '\.test\.[^/]*$|(^|/)fixtures/|^scripts/tests/' || true)
+if [ -z "$BEHAVIOUR" ]; then
+  echo "OK: no behaviour change under bin/lean/ or scripts/ — devdocs freshness not required."
+  exit 0
+fi
+
+if printf '%s\n' "$BODY" | tr -d '\r' | grep -Eq '^[[:space:]]*docs-not-needed:[[:space:]]*[^[:space:]]'; then
+  echo "OK: exempt via 'docs-not-needed:' line in the PR body."
+  exit 0
+fi
+
+# (c) a new decision record.
+DECISION=$(printf '%s\n' "$CHANGES" | awk -F'\t' '$1=="A" && $2 ~ /^devdocs\/decisions\/[^\/]+\.md$/ {print $2}' | head -1)
+
+# (b) changed lines inside NORTHSTAR.md § Runtime map (line range in HEAD vs the -U0 hunks' new-side lines).
+RUNTIME_MAP=0
+if printf '%s\n' "$CHANGED" | grep -qx 'NORTHSTAR.md' && [ -f NORTHSTAR.md ]; then
+  RANGE=$(awk '/^## /{ if (s && !e) e = NR - 1; if ($0 ~ /^## Runtime map[[:space:]]*$/) s = NR } END { if (s) { if (!e) e = NR; print s, e } }' NORTHSTAR.md)
+  if [ -n "$RANGE" ]; then
+    RS=${RANGE% *}; RE=${RANGE#* }
+    RUNTIME_MAP=$(git diff -U0 "${BASE}...HEAD" -- NORTHSTAR.md | awk -v s="$RS" -v e="$RE" '
+      /^@@/ {
+        match($0, /\+[0-9]+(,[0-9]+)?/)
+        spec = substr($0, RSTART + 1, RLENGTH - 1)
+        n = split(spec, p, ",")
+        start = p[1] + 0; cnt = (n > 1) ? p[2] + 0 : 1
+        if (cnt == 0) { lo = start; hi = start + 1 } else { lo = start; hi = start + cnt - 1 }
+        if (lo <= e && hi >= s) hit = 1
+      }
+      END { print hit ? 1 : 0 }')
+  fi
+fi
+
+# (a) dossiers: glob/path pairs from devdocs/index.yaml `modules:`.
+MODULES=""
+if [ -f devdocs/index.yaml ]; then
+  MODULES=$(awk '
+    /^modules:/ { m = 1; next }
+    m && /^[^[:space:]#]/ { m = 0 }
+    m && /^[[:space:]]*-[[:space:]]/ { if (g != "" && p != "") print g "\t" p; g = ""; p = "" }
+    m && /^[[:space:]]*(-[[:space:]]+)?glob:/ { v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); gsub(/["\047]/, "", v); g = v }
+    m && /^[[:space:]]*(-[[:space:]]+)?path:/ { v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); gsub(/["\047]/, "", v); p = v }
+    END { if (g != "" && p != "") print g "\t" p }' devdocs/index.yaml)
+fi
+
+MISSING=""
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  [ -n "$DECISION" ] && continue
+  [ "$RUNTIME_MAP" = "1" ] && continue
+  ok=0
+  if [ -n "$MODULES" ]; then
+    while IFS="$(printf '\t')" read -r glob dpath; do
+      [ -n "$glob" ] || continue
+      # shellcheck disable=SC2254
+      case "$f" in
+        $glob) printf '%s\n' "$CHANGED" | grep -qxF "devdocs/$dpath" && ok=1 ;;
+      esac
+    done <<EOF_MODULES
+$MODULES
+EOF_MODULES
+  fi
+  [ "$ok" = "1" ] || MISSING="${MISSING}${f}
+"
+done <<EOF_BEHAVIOUR
+$BEHAVIOUR
+EOF_BEHAVIOUR
+
+if [ -z "$MISSING" ]; then
+  if [ -n "$DECISION" ]; then echo "OK: new decision record $DECISION covers the behaviour change."
+  elif [ "$RUNTIME_MAP" = "1" ]; then echo "OK: NORTHSTAR.md § Runtime map updated."
+  else echo "OK: every behaviour change has its module dossier updated."; fi
+  exit 0
+fi
+
+echo "ERROR: behaviour changed under bin/lean/ or scripts/ without a docs update:"
+printf '%s' "$MISSING" | sed 's/^/  - /'
+echo ""
+echo "Fix with one of:"
+echo "  - edit the matching dossier (devdocs/index.yaml modules: glob -> devdocs/modules/*.md)"
+echo "  - update NORTHSTAR.md § Runtime map"
+echo "  - add devdocs/decisions/<issue>-<slug>.md"
+echo "  - or add a line 'docs-not-needed: <reason>' to the PR body"
+exit 1

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

@@ -0,0 +1,120 @@
+#!/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 exits 2"
+
+echo "check-devdocs-freshness.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" = 0 ]

package/scripts/ci-local/run.mjs

@@ -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());

package/scripts/ci-local.test.sh

@@ -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/northstar-docs.test.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# northstar-docs.test.sh — NORTHSTAR.md is present, small, pointed at, and devdocs selective loading still works (forge#4185).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT" || exit 1
+PASS=0; FAILN=0
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+check() { if eval "$2"; then ok; else bad "$1"; fi; }
+
+# NORTHSTAR.md: exists, under 8 KB, no unresolved ⟨confirm⟩ markers.
+check "NORTHSTAR.md exists" '[ -f NORTHSTAR.md ]'
+check "NORTHSTAR.md is under 8 KB" '[ "$(wc -c < NORTHSTAR.md | tr -d " ")" -lt 8192 ]'
+check "NORTHSTAR.md has no ⟨confirm⟩ markers" '! grep -q "⟨confirm⟩" NORTHSTAR.md'
+for s in "## Where a fix belongs" "## Runtime map" "## Non-negotiables" "## Anti-goals"; do
+  check "NORTHSTAR.md has section '$s'" 'grep -q "^$s" NORTHSTAR.md'
+done
+
+# CLAUDE.md and AGENTS.md point at it in their first line; CLAUDE.md is tracked (not gitignored).
+check "CLAUDE.md first line points at NORTHSTAR.md" 'head -1 CLAUDE.md | grep -q "NORTHSTAR\.md"'
+check "AGENTS.md first line points at NORTHSTAR.md" 'head -1 AGENTS.md | grep -q "NORTHSTAR\.md"'
+check "AGENTS.md keeps its Codex section" 'grep -q "^# ForgeDock for Codex" AGENTS.md'
+check "root CLAUDE.md is not gitignored" '! git check-ignore -q CLAUDE.md'
+check "nested CLAUDE.md stays gitignored" 'git check-ignore -q sub/CLAUDE.md'
+
+# "Pipeline Hardening Principles" resolves to NORTHSTAR.md only; audit.md points there, not at CLAUDE.md.
+HITS=$(grep -rl "Pipeline Hardening Principles" --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.forge-lean \
+  --exclude=northstar-docs.test.sh . | sed 's|^\./||')
+check "'Pipeline Hardening Principles' resolves to NORTHSTAR.md only (got: $HITS)" '[ "$HITS" = "NORTHSTAR.md" ]'
+check "commands/audit.md references NORTHSTAR.md" 'grep -q "NORTHSTAR\.md" commands/audit.md'
+check "commands/audit.md has no CLAUDE.md reference" '! grep -q "CLAUDE\.md" commands/audit.md'
+
+# lean dossier is indexed.
+check "devdocs/modules/lean.md exists" '[ -f devdocs/modules/lean.md ]'
+check "index.yaml modules has modules/lean.md" 'awk "/^modules:/{m=1;next} m&&/^[^[:space:]#]/{m=0} m" devdocs/index.yaml | grep -q "path: modules/lean.md"'
+check "index.yaml has a lean domain" 'awk "/^domains:/{m=1;next} m&&/^[^[:space:]#]/{m=0} m" devdocs/index.yaml | grep -q "^  lean:"'
+
+# Selective-loading regression: replay commands/work-on/build/context.md's always_load extraction (quote strip written portably).
+INDEX_CONTENT=$(cat devdocs/index.yaml)
+ALWAYS_LOAD_PATHS=$(echo "$INDEX_CONTENT" \
+  | awk '/^always_load:/,/^[a-z]/' \
+  | grep '^\s*-\s*path:' \
+  | sed 's/.*path:\s*//' \
+  | tr -d "\"'" \
+  | tr -d '[:space:]')
+check "always_load set is empty (NORTHSTAR.md loads via CLAUDE.md/AGENTS.md)" '[ -z "$ALWAYS_LOAD_PATHS" ]'
+check "always_load is still the empty list" 'grep -qx "always_load: \[\]" devdocs/index.yaml'
+PARSE_LINE="awk '/^always_load:/,/^[a-z]/'"
+check "context.md still parses always_load this way" 'grep -qF "$PARSE_LINE" commands/work-on/build/context.md'
+for d in pipeline github architecture devdocs scripts bin infra decisions lean; do
+  check "domain '$d' present" 'grep -q "^  $d:" devdocs/index.yaml'
+done
+for m in runner orchestrate lean; do
+  check "module '$m' present" 'grep -q "^  - name: $m$" devdocs/index.yaml'
+done
+# Every concrete (non-glob) doc path the index names exists under devdocs/.
+PATHS=$(grep -E '^[[:space:]]*-?[[:space:]]*path:' devdocs/index.yaml | sed 's/.*path:[[:space:]]*//' | tr -d "\"'" | grep -v '\*' | sort -u)
+while IFS= read -r p; do
+  [ -n "$p" ] || continue
+  check "indexed doc exists: devdocs/$p" '[ -f "devdocs/$p" ]'
+done <<EOF_PATHS
+$PATHS
+EOF_PATHS
+
+echo "northstar-docs.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" = 0 ]