forgedock 1.28.0 → 1.29.0

package/docs/CONFIG.md

@@ -402,6 +402,12 @@ orchestration:
     # paused P3s wait for bounded P3 batches. P1/P2 are never affected, and
     # `policy: all` / unlimited overrides do not disable it. "on" (default) | "off".
     amplification_breaker: on
+
+  # In-batch recovery (#4267): recovery lanes `forgedock orchestrate` launches
+  # per issue for a mechanical needs-human (ci.red, base.conflict, ...).
+  # Default 1; 0 disables in-batch recovery.
+  recovery:
+    max_attempts: 1
 ```
 
 | Field | Type | Required | Description |
@@ -410,6 +416,7 @@ orchestration:
 | `breaker.errors` / `breaker.window_min` | integer | No | `forgedock orchestrate` circuit breaker (#4121): after `errors` engine-errors within `window_min` minutes the batch stops admitting lanes, lets running lanes finish, and keeps the rest pending for `--resume`. `errors: 0` turns it off. Default: 3 in 30 |
 | `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held, gh unavailable) before its row is final. `host.busy` deferrals are not capped. Default: 3 |
 | `global_parallel` | integer | No | `forgedock orchestrate` (#4191): host-wide cap on running lanes across every batch and repo on the host, enforced through the host lane registry (`~/.forge/sched/`, or `FORGEDOCK_SCHED_DIR`). A freed slot goes to the highest-priority queued issue (`priority:P<n>` / `P<n>` labels, unlabelled P2); within a priority, slots are shared across repos by weight (#4193: `forgedock sched weight <owner/repo> N`, `--clear` resets; default equal, FIFO inside a repo), and priority always dominates weights; running lanes are never preempted and `--parallel` K still bounds each batch. `forgedock sched cap N` overrides it live for the whole host (`--clear` reverts); `forgedock sched show` lists the weights, slots and the queue. Default: unset (no global cap) |
+| `recovery.max_attempts` | integer | No | `forgedock orchestrate` in-batch recovery (#4267): how many recovery lanes the batch launches per issue for a `needs-human` with a mechanical code (`ci.red`, `base.conflict`, `ci-pending` on a conflicting PR, `contract.invalid` after a mid-run issue edit, `builder.block_untyped`). A recovery lane (`run-issue --recover <code>`) removes `needs-human`, posts a `FORGE:DECISION`, resumes the open PR and re-queues the issue with its dependents. If it ends anything but `merged`, the issue is labelled `needs-human` again with a recovery-evidence `FORGE:NEEDS_HUMAN` comment. Human codes are never recovered. Flat form: `recovery_max_attempts`. Default: 1; `0` disables in-batch recovery (a mechanical `needs-human` is final, as before). |
 | `cascade.policy` | string | No | `all` \| `balanced` \| `conservative`. Default: `balanced` |
 | `cascade.max_generation` | integer or `"unlimited"` | No | Max cascade generation admitted at Phase 1 resolve time. Default: 1 |
 | `cascade.batch_max_generation` | integer | No | Finite maximum member generation that an automated P3 batch may aggregate. Default: 2 |
@@ -422,6 +429,8 @@ orchestration:
 | `cascade.convergence_window` | positive integer | No | Consecutive ratio observations at or above 1.0 before warning. Default: 3 |
 | `cascade.amplification_breaker` | `on` \| `off` | No | Pause P3-and-below cascade admission while the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units. Counts all cascade findings (not only same-lineage); P1/P2 unaffected; independent of `cascade.policy`, so `policy: all` does not disable it. Paused P3s route to bounded P3 batches. Default: `on`. Opt out with `off` (boolean `false` is accepted as `off`, `true` as `on`). |
 
+**Upgrade note — in-batch recovery is on by default** (1.29.0): without `orchestration.recovery.max_attempts`, `forgedock orchestrate` launches one recovery lane per issue for a mechanical `needs-human` before reporting it. To keep the previous behavior (every `needs-human` final), set `orchestration.recovery.max_attempts: 0`.
+
 **Upgrade note — `cascade.amplification_breaker` is on by default**: existing configs that do not set this key now get the breaker automatically. During a batch, once the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units (it can trip at exactly 1.0 over 3 units), P3-and-below cascade admission pauses; paused P3s are routed to bounded P3 batches rather than dispatched individually. P1/P2 are unaffected. To keep the previous behavior, set `orchestration.cascade.amplification_breaker: off` (or `false`). See [RELEASE-NOTES.md](RELEASE-NOTES.md) for the release that introduced this default.
 
 **Hard invariant — not configurable**: safety exclusions (findings whose `## Problem` section indicates security/billing/anti-bot/auth concerns) are never batched and never auto-admitted by any `cascade.policy`, including `all`. That exclusion is enforced upstream of this section (the P3 batching eligibility check) and has no corresponding key here by design.
@@ -552,6 +561,10 @@ engine:
 | `lane_limits` | map | No | Cap each core lane's whole process tree (#4115), under `pipeline:` or `engine:`: `memory_max` (for example `3G`) and `cpu_quota` (for example `150%`). When set and `systemd-run --user --scope` works (probed once), the builder CLI is spawned as `systemd-run --user --scope -q -p MemoryMax=... -p CPUQuota=... -- claude ...`; elsewhere the caps are ignored. Write it nested or flat (`lane_limits_memory_max`, `lane_limits_cpu_quota`). While a builder runs the engine polls host load and memory every 15 s against the `admission` thresholds: over them it SIGSTOPs the lane's process group, under them SIGCONT, and never pauses longer than 10 minutes. |
 | `admission` | map | No | Host-resource admission for the core work-on (#4105), checked before the lease, worktree or any GitHub call. When a check fails the run ends `deferred` (code `host.busy`, exit 75) with a last line such as `issue #N → deferred (host busy: mem 1.2G < 2G; retry in 60s)`; no lease is taken and nothing is posted. Keys: `enabled` (default `true`; `false` disables admission), `min_free_mem_mb` (default 2048; `MemAvailable` from `/proc/meminfo`, else `os.freemem()`), `min_free_tmp_mb` (default 1024; free space of the run TMPDIR filesystem, `~/.forge/tmp`, and of `/tmp`, via `statfs`), `max_load_per_core` (default 4; 1-minute load average divided by cores). Write it nested (`engine:` then `admission:` with the keys indented) or flat as `admission_enabled`, `admission_min_free_mem_mb`, `admission_min_free_tmp_mb`, `admission_max_load_per_core`; the parser reads one nested level into `engine`. `/orchestrate` requeues a host-busy lane and lowers K by 1 for 5 minutes. |
 | `merge_wait` | string | No | Core work-on merge gate. `required` (default): wait only for the status checks the base branch requires: the union of classic branch protection (`gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`, contexts and checks) and repository rulesets (`gh api repos/{o}/{r}/rules/branches/{base}`, `required_status_checks` rules); with neither (404 or empty) merge right after review PASS. A merge rejected by base branch policy (PR `MERGEABLE` but `BLOCKED`) is waited on and retried within the CI budget, then left `ci-pending`; it is never base-synced and never `base.conflict`. A failing required check is `needs-human`; a pending one is polled with backoff and never `needs-human`. `all`: wait for every check (`scripts/wait-ci-green.sh`). `none`: merge right after review. Always `--match-head-commit` at the reviewed head. The policy used is recorded in the `FORGE:WORK-ON` comment. |
+| `context_pack` | string | No | Context pack (#4275). Before the plan call the core compiles the issue's GitHub/git neighbourhood into a small, budgeted pack: linked issues and PRs (parent, `Depends on`, body links, same-repo cross-references, siblings), prior attempts, merged PRs on the issue's files that were reverted or whose decisions/findings name a symbol from the issue, and repo-fact file pointers. `shadow` (default): the pack is compiled, posted on the issue as a collapsed `FORGE:CONTEXT` comment and logged as a `CONTEXT_PACK` event; the builder prompt is unchanged. `on`: it is also appended to the plan prompt as hints. `off`: nothing is gathered, posted or logged. The pack never enters the text contract quotes are checked against. Values read from linked issues' `FORGE:STATE` are kept only when they are outcome codes. Compare with `forgedock stats --context-ab`. |
+| `context_pack_sources` | string | No | Comma list of the pack sources to use: `graph`, `attempts`, `ledger`, `facts`. Default: all four. |
+| `context_pack_bytes` | integer | No | Hard byte cap of the pack; items that do not fit are dropped whole and counted. Default: 6144. |
+| `context_pack_days` | integer | No | Window of the merged-PR ledger, in days. Default: 30. |
 | `ci_pending_max_minutes` | integer | No | Minutes the engine waits for CI when the review phase ends BLOCKED with "checks still pending", or the remediate phase holds at its M7 re-gate on "CI pending" (the merge gate's wait window ended while CI was still running). Default: 90. Invalid values are ignored. This key is flat like the others but is not part of the `<key>_model` / `<key>_max_turns` pattern. |
 
 **CI still pending**: the engine polls `scripts/wait-ci-green.sh` (no model calls) one read per poll on a 60 s, 2 min, 4 min, 5 min (cap) backoff with +/-20% jitter, while the lease keeps renewing, then re-dispatches the phase that was waiting, review or remediate (idempotent at an unchanged head: review re-runs the merge gate and merges; remediate resumes at its M7 re-gate). Before each poll it reads `gh api rate_limit` (not itself rate-limited) and, below 10% of the REST budget, sleeps until the window resets instead of polling; a rate-limited or transient (5xx, network) poll is retried and never re-dispatches the phase. Red CI takes the normal ci-gate path. When the budget is exhausted the run ends `needs-human` with outcome code `review.ci_pending_timeout`; `--retry` resumes. Each wait emits a `ci_pending_wait` telemetry event (`docs/TELEMETRY.md`) with the minutes waited, polls made and rate-limit sleeps.
@@ -595,6 +608,7 @@ verify:
   skip_paths: "*.md,docs/**"    # optional, comma-separated; default *.md,*.mdx,*.rst,*.txt,docs/**,devdocs/**
   max_rounds: 2                 # optional CI fix rounds before needs-human (default 2)
   precheck_timeout_seconds: 300 # optional per-command timeout of the declared pre-PR checks (default 300)
+  check_run: true               # optional; post the forgedock/verify check run (default false)
 ```
 
 | Key | Type | Required | Description |
@@ -605,6 +619,7 @@ verify:
 | `skip_paths` | string | No | Comma-separated globs. A glob without `/` matches the basename anywhere; `**` spans directories. When every changed file matches, the lane skips CI verification (a docs-only lane runs no CI matrix). |
 | `max_rounds` | integer | No | Builder fix rounds for red CI (0–10, default 2). Also bounds the merge-time fix rounds and the declared-check fix rounds below, in every mode. |
 | `precheck_timeout_seconds` | integer | No | Timeout of each declared check command (1–3600, default 300); a timed-out command counts as failed (exit 124). |
+| `check_run` | boolean | No | Default `false` (no Checks API call, behaviour unchanged). `true`: after each push of a reviewed head (PR open, base-sync, merge-time fix round) the engine posts one completed `forgedock/verify` check run on that head (forge#4270), `success` iff every deterministic gate the lane already ran passed: declared check commands, undeclared package edges, docs freshness, contract scope, validate ids, requirement status, hotspot growth, amendments. The output carries each gate's id, pass/fail and evidence as JSON; the run log records a `VERIFY` event. Report only: ForgeDock never makes it required and never waits on it (it is ignored by its own CI waits); requiring it is the repository's branch-protection choice. Creating check runs needs a token that may (a GitHub App with `checks: write`); a Checks API failure is logged as an anomaly and never fails the lane. |
 
 **Flow** (`ci`/`hybrid`, `bin/lean/verify.mjs` `runCiVerify`):
 

package/docs/OUTCOME-CODES.md

@@ -87,6 +87,20 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `awaiting_merge` | Clean result held for a merge decision | remediate | Terminal reason `awaiting-merge` |
 | `unclassified` | Fallback for an absent or unknown code | engine | The raw reason is kept alongside |
 
+## Needs-human classes (forge#4267)
+
+`classifyNeedsHuman(row)` in `bin/engine/outcome-codes.mjs` sorts a lane result into one of three classes, so
+`forgedock orchestrate` recovers mechanical outcomes inside the batch:
+
+- **recoverable**:
+  - needs-human with `ci.red`, `base.conflict` or `builder.block_untyped`;
+  - `contract.invalid` when the issue was edited mid-run (`issueEdited`);
+  - `ci-pending` on a conflicting PR, recovered as `base.conflict`.
+
+  The runner relaunches the issue once per `orchestration.recovery.max_attempts` (default 1) as a recovery lane (`run-issue --recover <code>`), under the normal admission rules. That lane removes the `needs-human` label, posts `FORGE:DECISION`, and resumes the open PR: base-sync, then CI fix rounds from the failed-check logs. Dependents stay queued. A merged recovery is reported as `recovered`. A failed one is final, keeps the recovery evidence on the row, and skips its dependents. A failed recovery stays `needs-human`: the lane re-adds the label (with a `FORGE:NEEDS_HUMAN` comment carrying the evidence) only for a final `needs-human` or `ci-pending`; the batch runner re-adds it, once, for a final `engine-error` or `deferred` after the recovery pass (those may be requeued, so the lane cannot know). `invalid`, `decomposed`, `dependency-*` and `merged` never re-label.
+- **human**: `builder.blocked`, which is only reached by a typed human block: credentials, spend, promotion, customer or product-decision. It is never recovered, it skips dependents, and it is the only class in the report's escalation list.
+- **terminal**: every other code. No recovery runs, dependents are skipped, and the row is reported as `unrecovered`.
+
 ## Known limits
 
 - `build.acceptance_failed` covers malformed specs too until the gate sentinel distinguishes them.

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,15 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## v1.29.0: in-batch recovery and context pack on by default
+
+- **In-batch recovery** (`orchestration.recovery.max_attempts`, default 1): `forgedock orchestrate` now launches one recovery lane per issue for a mechanical `needs-human` (`ci.red`, `base.conflict`, `ci-pending` on a conflicting PR, `contract.invalid` after a mid-run issue edit, `builder.block_untyped`). The lane removes `needs-human`, resumes the PR and re-queues the issue. A recovery that ends anything but `merged` re-applies `needs-human` with a recovery-evidence `FORGE:NEEDS_HUMAN` comment.
+- **Context pack** (`engine.context_pack`, default `shadow`): each core run compiles a budgeted pack of the issue's links, prior attempts and related merged PRs, posts it as a collapsed `FORGE:CONTEXT` comment and logs `CONTEXT_PACK`; the builder prompt is unchanged in shadow. `FORGE:CONTEXT` and other engine-posted `<!-- FORGE:` comments are never quotable by contract requirements, and only outcome codes are read from linked issues' `FORGE:STATE`.
+- **Pre-PR test map**: `.forge/test-map.json` is read from the base ref (else the main checkout), never the lane worktree. `scripts/test-map.sh` no longer maps deploy/publish/release/push/secret steps, and a `- run: |` block ends at sibling step keys (`env:`, `shell:`). Regenerate the map.
+- **`forgedock/verify` check**: only gates that ran count; with none, the check is `neutral` ("no gates ran") instead of `success`.
+
+Action: set `orchestration.recovery.max_attempts: 0` to keep every `needs-human` final, and `engine.context_pack: off` to stop the `FORGE:CONTEXT` comment. Rerun `scripts/test-map.sh` if you keep a test map. See docs/CONFIG.md.
+
 ## Core work-on: per-phase comments (GitHub as the knowledge graph)
 
 The core builder now writes three markdown stage notes with fixed heading templates (`.forge-lean/investigation.md`, `plan.md`, `implementation.md`) next to the machine-readable `result.json`. The engine posts each as its own comment, live while the builder session runs (the CLI call is now asynchronous; a file is posted once its mtime is stable for 2 s) and the rest in order right after the session, before review: `FORGE:INVESTIGATION` (`## Investigation Report`, also carries the `FORGE:VALIDATE` alias marker), `FORGE:PLAN` (`## Implementation Plan`), `FORGE:IMPLEMENTATION` (`## Implementation Complete`, with branch and files changed computed by the engine), then `FORGE:REVIEW` (`## Review`: fixes the issue yes/no with evidence, regression check with what was checked, notes). A missing or blank file is rendered from the `result.json` fields ("not reported" for gaps); builder-written `<!-- FORGE:` markers are stripped and each comment is capped at 60k characters. At the end (merged, invalid or needs-human) one `FORGE:TRAJECTORY` comment (`## Pipeline Trajectory`, also carrying the `FORGE:WORK-ON` alias marker) replaces the old register comment: phase table, decisions, anomalies, cost, tokens, wall time. The PR body shows the root cause, the deliverables table and the verification. No extra model sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/check-spec-markers.sh

@@ -107,6 +107,7 @@ MARKER_REGISTRY="
   CONTRACT
   COORD_ISSUE
   CRITIQUE
+  DECISION
   DECISION_RECORD
   BOOTSTRAP_PLAN
   DECOMPOSED

package/scripts/fixtures/test-map/go/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+on:
+  pull_request:
+    paths:
+      - '**.go'
+      - 'go.mod'
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: golangci-lint run ./...
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: test
+        run: |
+          go mod download
+          go test ./...
+      - name: docs
+        run: ./scripts/check-docs

package/scripts/fixtures/test-map/go/Makefile

@@ -0,0 +1,5 @@
+build:
+	go build ./...
+
+test:
+	go test ./...

package/scripts/fixtures/test-map/go/README.md

@@ -0,0 +1 @@
+fixture

package/scripts/fixtures/test-map/go/go.mod

@@ -0,0 +1,3 @@
+module example.com/fixture
+
+go 1.22

package/scripts/fixtures/test-map/go/internal/util/util.go

@@ -0,0 +1,3 @@
+package util
+
+func Double(n int) int { return n * 2 }

package/scripts/fixtures/test-map/go/main.go

@@ -0,0 +1,3 @@
+package main
+
+func main() {}

package/scripts/fixtures/test-map/node/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "fixture-node",
+  "private": true,
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}

package/scripts/fixtures/test-map/node/packages/ui/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fixture/ui",
+  "scripts": { "test": "vitest run", "typecheck": "tsc --noEmit" }
+}

package/scripts/fixtures/test-map/node/packages/ui/src/button.tsx

@@ -0,0 +1 @@
+export const Button = () => null;

package/scripts/fixtures/test-map/node/pnpm-lock.yaml

@@ -0,0 +1 @@
+lockfileVersion: '9.0'

package/scripts/fixtures/test-map/node/src/a.ts

@@ -0,0 +1 @@
+export const a = 1;

package/scripts/fixtures/test-map/node/vitest.config.ts

@@ -0,0 +1 @@
+export default {};

package/scripts/fixtures/test-map/python/pkg/mod.py

@@ -0,0 +1,2 @@
+def add(a, b):
+    return a + b

package/scripts/fixtures/test-map/python/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "fixture-python"
+version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

package/scripts/fixtures/test-map/python/tests/test_mod.py

@@ -0,0 +1,5 @@
+from pkg.mod import add
+
+
+def test_add():
+    assert add(1, 2) == 3

package/scripts/fixtures/test-map/python/uv.lock

@@ -0,0 +1 @@
+version = 1

package/scripts/repo-facts.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# repo-facts.sh — deterministic repo facts the builder reads instead of re-learning them each lane (forge#4272). No LLM,
+# no network, runs none of the repo's commands: git + jq + awk + node. Codebase-agnostic.
+#
+# Usage: repo-facts.sh [--repo-path DIR] [--output FILE | --stdout]
+#   default output <repo>/.forge/repo-facts.json, rewritten on every run (an optional cache; the builder prompt cites
+#   it by path when present, deleting it restores today's prompts).
+# Output: {"version":1,
+#   "toolchain": bin/lean/toolchain.mjs detectPins(repo) {pm, node, notes} (forge#4163),
+#   "slow_suites": [{command, source, why}]: test-map entries (.forge/test-map.json when valid, else test-map.sh) whose
+#     command names e2e|playwright|cypress|integration|docker, or whose CI job sets `services:` or timeout-minutes >= 20,
+#   "layer_rules": {packages:[{name,dir}], edges:[{from,to,kind,manifest}], boundary_configs:[path]}: the workspace
+#     package graph at HEAD, same workspace and edge definitions as scripts/structure-delta.sh (forge#4159); boundary
+#     configs are eslint/dependency-cruiser/Nx files naming boundary rules,
+#   "hotspots": scripts/hotspots.sh over the tracked files, over-threshold and not excluded, by hotspot desc, max 20
+#     (forge#4195)}
+# Exit: 0 ok | 2 usage or bad repo path. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "repo-facts: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="."; OUT=""; STDOUT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo-path) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: repo-facts.sh [--repo-path DIR] [--output FILE | --stdout]"; REPO="$2"; shift 2 ;;
+    --output) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: repo-facts.sh [--repo-path DIR] [--output FILE | --stdout]"; OUT="$2"; shift 2 ;;
+    --stdout) STDOUT=1; shift ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+[ -d "$REPO" ] || die "repo path not found: $REPO"
+case "$OUT" in ""|/*) ;; *) OUT="$PWD/$OUT" ;; esac
+cd "$REPO" || die "cannot enter $REPO"
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/repo-facts.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+HAS_HEAD=0; git rev-parse --verify -q "HEAD^{commit}" >/dev/null 2>&1 && HAS_HEAD=1
+# -z and quotepath=off (#4298): non-ASCII and spaced paths come out verbatim, never C-quoted
+if [ "$HAS_HEAD" = 1 ]; then git -c core.quotepath=off ls-tree -r -z --name-only HEAD | tr '\0' '\n' > "$T/files"; else : > "$T/files"; fi
+# file content at HEAD
+at_head() { git show "HEAD:$1" 2>/dev/null; }
+
+# ---- toolchain (reuses #4163 detection) ----
+TOOLCHAIN=$(node --input-type=module -e '
+  const { detectPins } = await import(process.argv[1]);
+  console.log(JSON.stringify(await detectPins(process.argv[2])));
+' "$HERE/../bin/lean/toolchain.mjs" "$PWD" 2>/dev/null) || TOOLCHAIN=""
+printf '%s' "$TOOLCHAIN" | jq -e 'type == "object"' >/dev/null 2>&1 || TOOLCHAIN='{"pm":null,"node":null,"notes":["toolchain detection failed"]}'
+
+# ---- slow suites ----
+MAP=""
+[ -f .forge/test-map.json ] && MAP=$(jq -c 'select(.version == 1 and (.entries | type == "array"))' .forge/test-map.json 2>/dev/null)
+[ -n "$MAP" ] || MAP=$(bash "$HERE/test-map.sh" --stdout 2>/dev/null)
+[ -n "$MAP" ] || MAP='{"version":1,"entries":[]}'
+# CI jobs: "workflow#jobs.<job> TAB services(0|1) TAB timeout-minutes(0 when unset)"
+: > "$T/jobs"
+grep -E '^\.github/workflows/[^/]+\.(yml|yaml)$' "$T/files" | while IFS= read -r wf; do
+  [ -f "$wf" ] || continue
+  awk -v wf="$wf" '
+    function indent(s) { match(s, /^ */); return RLENGTH }
+    function flush() { if (job != "") print wf "#jobs." job "\t" svc "\t" tmo }
+    /^jobs:[ \t]*$/ { on = 1; next }
+    on && /^[^ \t#]/ { flush(); job = ""; on = 0; next }
+    on && /^ +[A-Za-z0-9_-]+:[ \t]*$/ && (jind == 0 || indent($0) == jind) { flush(); jind = indent($0); job = $0; sub(/^ +/, "", job); sub(/:.*$/, "", job); svc = 0; tmo = 0; next }
+    on && job != "" && indent($0) == jind + 2 && /^ *services:/ { svc = 1 }
+    on && job != "" && indent($0) == jind + 2 && /^ *timeout-minutes:[ \t]*[0-9]+/ { t = $0; sub(/^ *timeout-minutes:[ \t]*/, "", t); tmo = t + 0 }
+    END { flush() }
+  ' "$wf" >> "$T/jobs"
+done
+JOBS=$(jq -R -s -c '[split("\n")[] | select(length > 0) | split("\t") | {key: .[0], value: {services: (.[1] == "1"), timeout: (.[2] | tonumber)}}] | from_entries' < "$T/jobs")
+SLOW=$(printf '%s' "$MAP" | jq -c --argjson jobs "$JOBS" '
+  [.entries[] | . as $e
+   | ($e.command | ascii_downcase | [scan("e2e|playwright|cypress|integration|docker")] | first) as $w
+   | ($jobs[$e.source] // null) as $j
+   | (if $w then "command names \($w)"
+      elif $j and $j.services then "CI job \($e.source) uses services"
+      elif $j and $j.timeout >= 20 then "CI job \($e.source) sets timeout-minutes \($j.timeout)"
+      else null end) as $why
+   | select($why) | {command: $e.command, source: $e.source, why: $why}]')
+
+# ---- layer rules: workspace packages and their edges at HEAD (structure-delta.sh definitions) ----
+{
+  at_head package.json | jq -r '(.workspaces // empty) | if type == "array" then .[] elif type == "object" then (.packages // [])[] else empty end | strings' 2>/dev/null
+  at_head pnpm-workspace.yaml | awk '
+    /^packages:/ { on = 1; next }
+    on && /^[^ \t#-]/ { on = 0 }
+    on && /^[ \t]*-[ \t]*/ { sub(/^[ \t]*-[ \t]*/, ""); sub(/[ \t]+#.*$/, ""); gsub(/["\047]/, ""); sub(/[ \t]+$/, ""); if ($0 != "") print }'
+} | sed 's#^\./##; s#/$##' | sort -u > "$T/globs"
+to_re() { printf '%s' "$1" | sed 's/[.+^$()|{}[]/\\&/g; s/\*\*/%%/g; s/\*/[^\/]*/g; s/%%/.*/g; s/?/[^\/]/g'; }
+: > "$T/inc"; : > "$T/exc"; : > "$T/names"; : > "$T/deps"
+while IFS= read -r g; do
+  case "$g" in \!*) echo "^$(to_re "${g#!}")\$" >> "$T/exc" ;; *) echo "^$(to_re "$g")\$" >> "$T/inc" ;; esac
+done < "$T/globs"
+if [ -s "$T/inc" ]; then
+  grep -E '/package\.json$' "$T/files" | grep -v -E '(^|/)node_modules/' | while IFS= read -r m; do
+    d=${m%/package.json}
+    grep -qE -f "$T/inc" <<<"$d" || continue
+    if [ -s "$T/exc" ] && grep -qE -f "$T/exc" <<<"$d"; then continue; fi
+    at_head "$m" > "$T/pj" || continue
+    n=$(jq -r '.name // empty | strings' "$T/pj" 2>/dev/null)
+    [ -n "$n" ] || continue
+    printf '%s\t%s\t%s\n' "$d" "$m" "$n" >> "$T/names"
+    jq -r --arg m "$m" '["dependencies","devDependencies","peerDependencies"][] as $k | (.[$k] // {}) | objects | keys[] | [$m, $k, .] | @tsv' "$T/pj" 2>/dev/null >> "$T/deps"
+  done
+fi
+PACKAGES=$(jq -R -s -c '[split("\n")[] | select(length > 0) | split("\t") | {name: .[2], dir: .[0]}] | sort_by(.name)' < "$T/names")
+EDGES=$(awk -F'\t' '
+  FILENAME == ARGV[1] { name[$2] = $3; ws[$3] = 1; next }
+  ($3 in ws) && ($1 in name) && name[$1] != $3 { print name[$1] "\t" $3 "\t" $2 "\t" $1 }
+' "$T/names" "$T/deps" | sort -u | jq -R -s -c '[split("\n")[] | select(length > 0) | split("\t") | {from: .[0], to: .[1], kind: .[2], manifest: .[3]}]')
+: > "$T/bfiles"
+while IFS= read -r f; do
+  case "${f##*/}" in
+    .eslintrc|.eslintrc.*|eslint.config.*|.dependency-cruiser.*|nx.json|project.json)
+      # here-string, not `at_head | grep -q`: under pipefail an early grep exit SIGPIPEs at_head and reads as no match (#4298)
+      c=$(at_head "$f"); grep -qE 'boundaries|forbidden|depConstraints|DependOnLibsWithTags|no-restricted-paths' <<<"$c" && printf '%s\n' "$f" >> "$T/bfiles" ;;
+  esac
+done < "$T/files"
+BOUNDARY=$(jq -R -s -c 'split("\n") | map(select(length > 0))' < "$T/bfiles")
+
+# ---- hotspots (reuses #4195 facts) ----
+# hotspots.sh with no paths reports its config; only files over file_lines can be hotspots, so only those are passed
+HOT='[]'
+FL=$(bash "$HERE/hotspots.sh" 2>/dev/null | jq -r 'select(.enabled) | .file_lines' 2>/dev/null)
+if [ -s "$T/files" ] && [ -n "$FL" ]; then
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    n=$(wc -l < "$f" | tr -d ' '); [ "$n" -gt "$FL" ] && printf '%s\n' "$f"
+  done < "$T/files" > "$T/big"
+  H=""; [ -s "$T/big" ] && { H=$(tr '\n' '\0' < "$T/big" | xargs -0 -n 200 bash "$HERE/hotspots.sh" -- 2>/dev/null) || H=""; }
+  HOT=$(printf '%s' "$H" | jq -s -c '[.[].files[]? | select(.over and (.excluded | not)) | {path, lines, commits_90d, hotspot}] | sort_by(-.hotspot, .path) | .[:20]' 2>/dev/null) || HOT='[]'
+  [ -n "$HOT" ] || HOT='[]'
+fi
+
+FACTS=$(jq -n -c --argjson tc "$TOOLCHAIN" --argjson slow "$SLOW" --argjson pk "$PACKAGES" --argjson ed "$EDGES" --argjson bc "$BOUNDARY" --argjson hot "$HOT" \
+  '{version: 1, toolchain: $tc, slow_suites: $slow, layer_rules: {packages: $pk, edges: $ed, boundary_configs: $bc}, hotspots: $hot}') || die "jq failed"
+
+if [ "$STDOUT" = 1 ]; then printf '%s\n' "$FACTS"; exit 0; fi
+[ -n "$OUT" ] || OUT=".forge/repo-facts.json"
+mkdir -p "$(dirname "$OUT")" || die "cannot create $(dirname "$OUT")"
+printf '%s\n' "$FACTS" > "$OUT.tmp.$$" && mv "$OUT.tmp.$$" "$OUT" || die "cannot write $OUT"
+echo "$OUT"

package/scripts/repo-facts.test.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# repo-facts.test.sh — cases for scripts/repo-facts.sh (forge#4272).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/repo-facts.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/repo-facts-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+
+new_repo() {
+  rm -rf "$TMP/$1"; mkdir -p "$TMP/$1"; cd "$TMP/$1" || exit 1
+  git init -q -b main; git config user.email t@example.com; git config user.name t; git config commit.gpgsign false
+}
+commit() { git add -A; git commit -qm "$1"; }
+lines() { i=0; : > "$1"; while [ $i -lt "$2" ]; do echo "l$i" >> "$1"; i=$((i+1)); done; }
+
+# ---- 1. pins, slow suites, package edge, boundary config, hotspot ----
+new_repo full
+mkdir -p packages/a packages/b .github/workflows src
+cat > package.json <<'EOF'
+{"name":"root","private":true,"packageManager":"pnpm@9.1.0","workspaces":["packages/*"],
+ "scripts":{"test":"vitest run","lint":"eslint .","test:e2e":"playwright test"}}
+EOF
+echo "20.11.1" > .nvmrc
+echo '{"name":"@x/a","dependencies":{"@x/b":"workspace:*","left-pad":"1.0.0"}}' > packages/a/package.json
+echo '{"name":"@x/b","scripts":{"test":"vitest run"}}' > packages/b/package.json
+echo "module.exports = { rules: { 'boundaries/element-types': ['error'] } };" > .eslintrc.js
+echo "module.exports = { rules: { semi: 'error' } };" > packages/b/.eslintrc.js
+cat > .github/workflows/ci.yml <<'EOF'
+on: push
+jobs:
+  db:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres
+    steps:
+      - run: pnpm run test
+  long:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - run: make lint-all
+  quick:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: make fmt
+EOF
+lines src/big.ts 2100; commit c1
+echo x >> src/big.ts; lines src/small.ts 10; commit c2
+OUT="$(bash "$S" --stdout)"; rc=$?
+eq "rc" "$rc" 0
+eq "version" "$(q '.version')" 1
+eq "pm pin" "$(q '.toolchain.pm')" '{"name":"pnpm","version":"9.1.0","source":"package.json packageManager"}'
+eq "node pin" "$(q '.toolchain.node')" '{"spec":"20.11.1","source":".nvmrc"}'
+eq "packages" "$(q '.layer_rules.packages')" '[{"name":"@x/a","dir":"packages/a"},{"name":"@x/b","dir":"packages/b"}]'
+eq "edge" "$(q '.layer_rules.edges')" '[{"from":"@x/a","to":"@x/b","kind":"dependencies","manifest":"packages/a/package.json"}]'
+eq "boundary configs" "$(q '.layer_rules.boundary_configs')" '[".eslintrc.js"]'
+eq "services job" "$(q '[.slow_suites[] | select(.command == "pnpm run test") | .why]')" '["CI job .github/workflows/ci.yml#jobs.db uses services"]'
+eq "timeout job" "$(q '[.slow_suites[] | select(.command == "make lint-all") | .why]')" '["CI job .github/workflows/ci.yml#jobs.long sets timeout-minutes 45"]'
+eq "quick job not slow" "$(q '[.slow_suites[] | select(.command == "make fmt")] | length')" 0
+eq "hotspot" "$(q '.hotspots')" '[{"path":"src/big.ts","lines":2101,"commits_90d":2,"hotspot":4202}]'
+
+# ---- 2. a cached test map is read: its e2e command is a slow suite ----
+mkdir -p .forge
+echo '{"version":1,"entries":[{"globs":["e2e/**"],"command":"pnpm exec playwright test","cwd":".","source":"package.json#scripts.test:e2e"}]}' > .forge/test-map.json
+OUT="$(bash "$S" --stdout)"
+eq "map e2e" "$(q '.slow_suites')" '[{"command":"pnpm exec playwright test","source":"package.json#scripts.test:e2e","why":"command names playwright"}]'
+
+# ---- 3. default output file, rerun stable ----
+P="$(bash "$S")"; eq "output path" "$P" ".forge/repo-facts.json"
+cp .forge/repo-facts.json "$TMP/first.json"; bash "$S" >/dev/null
+if cmp -s .forge/repo-facts.json "$TMP/first.json"; then ok; else bad "rerun not identical"; fi
+
+# ---- 4. a repo with none of these: empty sections, exit 0 ----
+new_repo bare
+echo hi > README.md; commit init
+OUT="$(bash "$S" --stdout)"; rc=$?
+eq "bare rc" "$rc" 0
+eq "bare" "$(q '[.toolchain.pm, .toolchain.node, .slow_suites, .layer_rules, .hotspots]')" '[null,null,[],{"packages":[],"edges":[],"boundary_configs":[]},[]]'
+new_repo empty
+OUT="$(bash "$S" --stdout)"; eq "no commits rc" "$?" 0
+eq "no commits" "$(q '.hotspots')" '[]'
+
+# ---- 4b. #4298: a big boundary config matching early (pipefail + grep -q SIGPIPE) and non-ASCII / spaced paths ----
+new_repo paths
+mkdir -p "packages/é b" "apps/ü"
+echo '{"name":"root","private":true,"workspaces":["packages/*"]}' > package.json
+echo '{"name":"@x/c"}' > "packages/é b/package.json"
+{ echo "export default [{ rules: { 'boundaries/element-types': ['error'] } }];"; i=0; while [ $i -lt 20000 ]; do echo "// padding line $i to overflow the pipe buffer ......................................"; i=$((i+1)); done; } > "apps/ü/eslint.config.js"
+commit init
+OUT="$(bash "$S" --stdout)"; eq "paths rc" "$?" 0
+eq "big boundary config in a non-ASCII dir" "$(q '.layer_rules.boundary_configs')" '["apps/ü/eslint.config.js"]'
+eq "spaced non-ASCII package dir" "$(q '.layer_rules.packages')" '[{"name":"@x/c","dir":"packages/é b"}]'
+
+# ---- 5. usage ----
+bash "$S" --repo-path "$TMP/missing" >/dev/null 2>&1; eq "bad repo path" "$?" 2
+bash "$S" --bogus >/dev/null 2>&1; eq "unknown option" "$?" 2
+
+echo "repo-facts.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]