forgedock 1.18.0 → 1.19.0

package/docs/CONFIG.md

@@ -481,13 +481,17 @@ engine:
 | `<key>_model` | string | No | Model alias (`sonnet`, `opus`, `haiku`) or full model id passed as `--model`. Invalid values are ignored. |
 | `<key>_max_turns` | integer | No | Positive integer passed as `--max-turns`. Invalid values are ignored. |
 
+| `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.
+
 **Precedence** (model): `engine.<key>_model`, then the run-level model the caller passed explicitly, then omitted. `max_turns` comes only from this section. No defaults ship.
 
 **Version gate**: the flags are added only when the installed `claude --version` supports them (`--max-turns` is hidden from `claude --help`, so help text is never scraped); an unparseable version omits both flags.
 
 **Turn exhaustion**: when `--max-turns` is exhausted the run ends `engine-error` (detail `max-turns`) and the phase is never committed, so `forgedock run-issue --retry` re-enters the same phase. Raise `<key>_max_turns` before retrying. Phase runlog events record `model` and `turns` next to `usage` so a limit can be sized from measured turn counts.
 
-**Per-run scratch dir** (`tmp_root`): every engine child runs with `TMPDIR` and `CLAUDE_CODE_TMPDIR` set to `<tmp_root>/<issue>` so venvs and Claude session data stay off a size-limited `/tmp`. `engine.tmp_root` is an absolute or `~`-prefixed path; default `~/.forge/tmp`. When `tmp_root` is unset and the operator already exported `TMPDIR` or `CLAUDE_CODE_TMPDIR`, that choice is respected and never cleaned. The dir is removed on a terminal outcome and kept on `engine-error` so `--retry` resumes. A disk-full/quota failure (EDQUOT, ENOSPC, errno -28/-122) ends a retryable `engine-error` (outcome code `infra.disk_quota`), never `needs-human`.
+**Per-run scratch dir** (`tmp_root`): every engine child runs with `TMPDIR` and `CLAUDE_CODE_TMPDIR` set to `<tmp_root>/<repo-key>/<issue>` so venvs and Claude session data stay off a size-limited `/tmp`. `engine.tmp_root` is an absolute or `~`-prefixed path; default `~/.forge/tmp`. The `<repo-key>` is the checkout's directory name plus 8 hex characters of a hash of its real path, so the same issue number in two repos never shares a dir; the dir is created `0700` and an existing symlink or dir owned by another user is not used (the child keeps the inherited tmp). Old `<tmp_root>/<issue>` dirs from earlier versions are not migrated. When `tmp_root` is unset and the operator already exported `TMPDIR` or `CLAUDE_CODE_TMPDIR`, that choice is respected and never cleaned. The dir is removed on a terminal outcome and kept on `engine-error` so `--retry` resumes. A disk-full/quota failure (EDQUOT, ENOSPC, errno -28/-122) ends a retryable `engine-error` (outcome code `infra.disk_quota`), never `needs-human`.
 
 **Commands that use this section**: CLI backend (`runCommand` in `bin/runner.mjs`)
 
@@ -736,6 +740,10 @@ verification:
     - name: "web"
       container: "acme-web-blue"
       health_url: "http://localhost:3000"
+
+  consumer_sweep:
+    mode: advisory         # advisory (default) | blocking
+    budget_seconds: 60     # wall-clock budget for the sweep
 ```
 
 | Field | Type | Required | Description |
@@ -746,8 +754,87 @@ verification:
 | `services[].name` | string | **Yes (per entry)** | Human-readable service name |
 | `services[].container` | string | No | Docker container name for `docker exec` verification |
 | `services[].health_url` | string | No | Local URL for container-level health checks |
+| `ci_local` | object | No | Local CI gate settings (see below) |
+| `consumer_sweep.mode` | string | No | `advisory` (default): the validate consumer sweep (`scripts/consumer-sweep.sh`, V4.6) records unaddressed referencing sites and never fails. `blocking`: unaddressed sites fail validate with `consumer_unaddressed`, build runs one repair round, and sites still unaddressed are recorded as `CONSUMERS: unresolved` and passed to review as known risk (never `needs-human`). Flip to `blocking` only after `bash scripts/consumer-sweep.sh --eval-history 20` shows a mean of at most 2 flagged sites per merge and none above 10 on your repo |
+| `consumer_sweep.budget_seconds` | integer | No | Wall-clock budget for the sweep (default `60`). When it runs out the sweep stops with `BUDGET_EXCEEDED`, reports the partial result, and never fails, in either mode |
+
+**Commands that use this section**: `quality-gate`, `validate` (V2 runs `verification.commands`; V4.8 runs the local CI gate; health checks and `consumer_sweep`), `work-on`
+
+### `verification.ci_local` (OPTIONAL)
+
+Validate Phase V4.8 runs `scripts/ci-local.sh` before review: it derives the repo's pull-request checks from its own CI
+definitions and runs them locally in the build worktree, so deterministic CI failures are fixed in build (at most 2 fix
+iterations; a failure still unfixable after that is DEGRADED by default, see `mode`). It never contacts GitHub and never triggers a remote
+workflow; remote CI still runs once, at merge. Everything works with no configuration.
+
+```yaml
+verification:
+  ci_local:
+    mode: advisory
+    exclude_jobs: ["gha:ci:e2e-*"]
+    include_jobs: []
+    extra_commands:
+      - "make lint-docs"
+    services: auto
+    budget_minutes: 15
+    max_parallel: 4
+```
 
-**Commands that use this section**: `quality-gate`, `validate`
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `advisory` \| `blocking` | `advisory` | `advisory`: a runnable job still failing after the 2 fix iterations is DEGRADED (`DEGRADED_CHECKS+=ci-local`), recorded in `FORGE:BUILDER` under `### Local CI unresolved` and surfaced to review; the build is not blocked. `blocking` (opt-in): the build is blocked with `ci-local: <jobs>`. Flip to `blocking` only once telemetry (`ci_local` events) shows a low false-fail rate on your repo |
+| `exclude_jobs` | array of globs | `[]` | Job ids or names to drop from the plan (matched against `gha:<workflow>:<job>`, `gitlab:<job>`, and the job name) |
+| `include_jobs` | array of globs | `[]` | When non-empty, only matching CI jobs run (an allowlist); `extra_commands` and the portability checks (when they apply) always run |
+| `extra_commands` | array of strings or `{name, command}` | `[]` | Extra commands always added to the plan. `verification.commands` is not repeated here: V2 already runs it as the fast pre-step |
+| `services` | `auto` \| `off` | `auto` | `auto` starts a job's service containers with docker (same image, env, ports), tearing them down afterwards; without docker, or with `off`, such jobs are deferred |
+| `budget_minutes` | number | `15` | Overall wall-time budget; jobs not finished or started within it leave the run DEGRADED (never PASS, never FAIL). One invocation is capped at 9 minutes whatever this says (the Bash tool limit is 10): beyond that the run is a partial DEGRADED result and re-running resumes from the result cache (`FORGE_CI_LOCAL_MAX_INVOCATION_SECONDS`, default 540) |
+| `max_parallel` | number | `4` | Jobs run in parallel by one run (also bounded machine-wide, see below) |
+
+**Trusted config**: every field above is read from the main checkout's `forge.yaml` (for a plain checkout, the base ref's
+copy), never from the PR's own tree, so a PR cannot exclude jobs from the gate that checks it.
+
+**Where checks come from**: GitHub Actions (`.github/workflows`), GitLab CI, CircleCI, Azure Pipelines, Bitbucket Pipelines
+and Buildkite definitions, read from the trusted base ref plus the PR's own edits (a PR can add a check but cannot delete
+one). Only when the repo has NO CI definitions are its task runners used; when CI exists but its path filters leave no job
+applicable the run executes nothing and records `no_applicable_jobs` (a docs-only change never triggers a full suite) (`package.json` scripts, Makefile, justfile,
+Taskfile, tox/nox, pre-commit, pyproject tools, Cargo, Go, Maven, Gradle). Deterministic portability checks (Windows-invalid
+filenames, case collisions, CRLF in scripts, bash 3.2 constructs and GNU-only flags on added lines, plus the repo's
+`scripts/check-shell-portability.sh` when present) run only when the repo's CI definitions target macOS or Windows (a
+`macos-*`/`windows-*` runner, matrix entry or executor); for a Linux-only repo they are skipped with a note, so correct
+Linux-only code is never blocked on bash 3.2 rules.
+
+**Deferred to CI** (listed in the `FORGE:BUILDER` comment under `### Deferred to CI`, never guessed): jobs that reference
+`secrets.` or `environment:`, deploy/publish jobs, `pull_request_target`, schedule/dispatch-only workflows, unknown `uses:`
+actions, orbs, plugins and templates, service containers without docker, macOS/Windows variants on another host, matrix
+variants beyond the first host-compatible one, and jobs whose tools are not installed locally. A failed dependency install
+(for example offline) defers the job instead of failing it, and so does a failure of a job whose pinned toolchain differs
+from the host by a major version (`setup-node` 18 vs host 26: version drift, listed with its reason). A job timeout is
+DEGRADED, never FAIL, and its clock starts when the job starts executing, not while it waits for a machine slot.
+
+**Exact scoping** (runs only what the change can affect): job-level path filters from the CI definition (including
+`dorny/paths-filter` outputs) gate whole jobs; per-file linters (shellcheck, eslint, prettier, ruff, black, flake8, ...) run
+on the changed files only; tests use the ecosystem selector (`jest --findRelatedTests`, `vitest related`, `go` affected
+packages with reverse dependencies, `cargo test -p` affected crates, Maven `-pl ... -amd`, `nx affected`, `turbo --filter`) or a
+git-grep reference graph for file-list runners (pytest, mocha, `node --test`, bats, rspec, direct `*.test.*` invocations);
+changed test files always run. **Fail-safe widening**: a lockfile, build or lint config, CI definition, unreferenced shared
+fixture, an unknown file type, or an empty test selection for a changed source file widens the step to the full command (the
+reason is reported, never silently narrowed). Short module names (`app/db.py`, `__init__.py`) are matched by their qualified
+import forms. `${{ github.* }}` expressions in `run:` scripts are passed to the script as environment variables, never
+substituted into the script text. CircleCI secondary containers run on a per-job docker network and publish only declared
+(or well-known default) ports on 127.0.0.1, never `--network host`.
+Passing results are cached by input hash under `~/.forge/ci-local/results` and reused across build iterations, lanes and
+issues on the same base.
+
+**Environment** (all optional): `FORGE_CI_LOCAL_SLOTS` (machine-wide concurrent jobs across all runs, default
+`max(2, min(8, cpus/2))`; slots live under `~/.forge/ci-local.lock` and stale ones are reclaimed), `FORGE_CI_LOCAL_BUDGET_MINUTES`,
+`FORGE_CI_LOCAL_MAX_PARALLEL`, `FORGE_CI_LOCAL_JOB_TIMEOUT` (seconds, default min(900, budget)), `FORGE_CI_LOCAL_SERVICES=off`,
+`FORGE_CI_LOCAL_MAX_INVOCATION_SECONDS` (default 540), `FORGE_CI_LOCAL_HOME` (default `~/.forge`), `FORGE_CI_LOCAL_NO_CACHE=1`. Jobs run in a runner-like environment: an allowlist of
+system and toolchain variables (PATH, HOME, locale, XDG_*, CARGO_*, GOPATH, JAVA_HOME, proxies, ...) plus `CI=true`; credentials and
+ambient operator state (agent tokens, `FORGE_*`/`CLAUDE_*` settings, git hook variables) never reach them. Extra names can be
+listed in `FORGE_CI_LOCAL_PASSTHROUGH` (comma separated). Requires `node`, `git`, and mikefarah `yq` v4 for YAML CI definitions (without `yq`
+the gate is DEGRADED and reported in `verification_skipped`, never a silent pass).
+
+**Commands that use this section**: `work-on` (validate V4.8)
 
 ---
 

package/docs/OUTCOME-CODES.md

@@ -20,7 +20,8 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `review.rereview_skipped` | Re-review was skipped | reserved | No structured evidence source yet |
 | `review.blocking_issue` | Review left the PR open at an unchanged head with a filed blocking ISSUE and handed off to remediate | review | Trusted `FORGE:NOTE_DISPOSITION` on the PR with `findings_filed` > 0 and `reviewed_sha` equal to the live head |
 | `review.pr_open` | Review ended with the PR open and unmerged and no handoff signal | review | Live PR open, no `REVIEW_RESULT` remediate handoff, no `needs-human`/`workflow:remediating` label, no blocking disposition |
-| `build.acceptance_failed` | Newest acceptance gate marker is blocked | build | `FORGE:ACCEPTANCE_GATE:FAILED`/`:BLOCKED` or `FORGE:BUILD_BLOCKED` |
+| `review.ci_pending_timeout` | CI was still pending at the merge gate after the engine's bounded wait (`engine.ci_pending_max_minutes`) ran out | engine | Review ended `REVIEW_RESULT` `status: BLOCKED` with a blocker containing `checks still pending` (or remediate held at its M7 re-gate on `CI pending`), and `scripts/wait-ci-green.sh` still reported pending when the budget expired |
+| `build.acceptance_failed` | Newest acceptance gate marker is blocked | build | `FORGE:ACCEPTANCE_GATE:FAILED`/`:BLOCKED` or `FORGE:BUILD_BLOCKED` (`:DEGRADED` is a pass-class marker, not blocked) |
 | `build.acceptance_malformed` | Acceptance spec was malformed | reserved | Indistinguishable from `build.acceptance_failed` by sentinel alone |
 | `build.size_over_gate` | Retired (forge#3862): the old size gate routed a finished build to decompose; never emitted now, kept so historic runs still parse | reserved | A finished build is never routed to decompose |
 | `build.cohesive` | Retired (forge#3862): the old size gate judged an oversized diff cohesive | reserved | No size gate remains |
@@ -28,12 +29,15 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `remediate.deferred_live_run` | Remediation deferred to a live earlier run | remediate, engine | Trusted `FORGE:REMEDIATION_DEFERRED` record |
 | `remediate.re_escalated` | Remediation re-escalated to a human | remediate | `**Re-gate outcome**: RE-ESCALATED` |
 | `remediate.unfixable` | Remediation judged the findings unfixable | remediate | `**Re-gate outcome**: UNFIXABLE` |
+| `remediate.inpr_requested` | Re-gate approved but requested one further in-PR fix round; the run continues, never `needs-human` | remediate | `**Re-gate outcome**: INPR-FIX-REQUESTED` |
 | `ci.red` | CI failed | reserved | `REVIEW_RESULT` carries no CI field yet |
 | `ci.timeout` | CI timed out | reserved | `REVIEW_RESULT` carries no CI field yet |
 | `base.conflict` | Base-branch conflict blocked the PR | reserved | `REVIEW_RESULT` carries no conflict field yet |
 | `rate_limited` | Session or usage limit outlasted the pause budget | engine | `err.usageLimit` / `err.resetAtEpochMs` |
 | `engine.error` | Engine or tool failure (missing key/SDK, CLI crash, max turns, unresolved args, runner threw every attempt) | engine | `err.code` |
 | `infra.disk_quota` | Disk full or quota exhausted (EDQUOT/ENOSPC, errno -28/-122); retryable infra failure, never `needs-human` | engine | Runner error text |
+| `infra.cli_spawn_transient` | CLI spawn failed transiently before the child ran (ETIMEDOUT, EAGAIN, ENOMEM, EMFILE); retried with backoff on a separate bounded counter that does not consume a phase attempt | engine | `err.code` `CLI_SPAWN_TRANSIENT` |
+| `cli.timeout` | CLI child ran and was killed at the wall-clock limit; a normal attempt (consumes one of `maxAttempts`), usage recorded when the CLI emitted any | engine | `err.code` `CLI_TIMEOUT` |
 | `lease.held` | Another live agent holds the issue lease | engine | Foreign live lease on acquire |
 | `dependency.open` | A trusted `**Depends on**: #N` dependency is still open, so the run was refused before any state write | engine | Trusted issue body `**Depends on**` line + the dependency issue's open state |
 | `dependency.unreadable` | The issue body or a declared dependency could not be read, so the run was refused (fail closed) | engine | Failed or unparsable `gh api` read |

package/docs/STATS.md

@@ -14,6 +14,10 @@ npx forgedock stats [--since <version|date>] [--repo <owner/repo>] [--json] [--r
 versions at or above it; `--since 2026-10-01` keeps activity on or after the date. `--compact` prints one row per
 version (the table embedded in the staging review summary). `--json` is machine-readable.
 
+`--since` also bounds the GitHub crawl: only issues and comments updated on or after the window start are read (a version
+is resolved to its tag time minus one day; an unknown tag falls back to a full crawl and says so on stderr). Progress is
+printed to stderr while crawling, so `--json` stdout stays parseable.
+
 ## Sources
 
 1. **GitHub (primary).** Issues, PRs and labels of the target repo, plus trusted `<!-- FORGE:TELEMETRY v1 -->` comments
@@ -21,8 +25,9 @@ version (the table embedded in the staging review summary). `--json` is machine-
    `scripts/trusted-comments.sh`); `part=N` comments are concatenated and records are deduped on `eid`. All `gh` calls
    are argv-based. Needs an authenticated `gh`.
 2. **Local cache (optional).** `~/.forge/stats-cache/<owner>_<repo>/cache.json` (`FORGE_STATS_CACHE_DIR`) holds what was
-   fetched plus an `updated_at` watermark, so the next run only re-reads items updated since. It is safe to delete (the
-   cost is one full re-fetch); a corrupt cache is treated as empty. `--refresh` ignores it, `--no-cache` never touches it.
+   fetched, an `updated_at` watermark (the next run only re-reads items updated since) and a `coveredFrom` floor (the
+   oldest window start crawled, so a later, wider `--since` crawls the uncovered gap instead of under-reporting). It is
+   safe to delete (the cost is one full re-fetch); a corrupt cache is treated as empty. `--refresh` ignores it, `--no-cache` never touches it.
 3. **Local run logs (optional).** `~/.forge/runs/*.jsonl` (`FORGE_RUNS_DIR`) for runs that predate the engine's
    `phase_attempt` / `run_terminal` records. A run already present on GitHub is not counted twice. Only runs whose
    `RUN_START.repo` equals the target repo are used. `--no-local` skips them.
@@ -59,5 +64,7 @@ instead of failing.
 
 ## Limits
 
-Issues and PRs are listed by `updated_at`, so the first run on a large repo makes one comment request per item that has
-comments. Telemetry comments are edited in place; if a cached item looks stale, run with `--refresh`.
+Comments are read from the repo-wide `issues/comments?since=` endpoint (a few paginated calls); only issues with a trusted
+telemetry comment in the window get their full comment list re-read (6 in parallel, backing off when the API rate limit is
+low). A run with no `--since` and no cache still walks the whole history once. Telemetry comments are edited in place, which
+the comment window catches; if a cached item still looks stale, run with `--refresh`.

package/docs/TELEMETRY.md

@@ -33,9 +33,12 @@ is dropped. Payload keys are `[A-Za-z0-9_]+` and cannot shadow the shared keys;
 |-------|-----------|---------|
 | `diff_size` | `scripts/diff-size.sh`; `work-on/build.md` B5.5 (final result) | `lines`, `excluded`, `ws_lines`, `review_weight`, `modules`, `result`; the script emits the legacy `threshold` and `OK` \| `OVER` \| `COHESIVE`, the B5.5 call site emits the final `result` = `OK` \| `EXTENDED_REVIEW` \| `SCOPE_FLAGGED` \| `OVERRIDDEN` plus `estimate` (plan), `actual` (whitespace-insensitive lines), `scope` = `ok` \| `out_of_plan` \| `no_baseline` and `review_depth` = `STANDARD` \| `EXTENDED` (calibration inputs, forge#3862) |
 | `acceptance_gate` | `work-on/build.md` B6.5 (`phase=build`); `scripts/review-acceptance-gate.sh` (`phase=review`) | `phase`, `verified`, `failed`, `malformed`, `deferred` |
-| `finding_disposition` | `scripts/classify-finding.sh`, one per finding | `severity`, `confidence`, `agent`, `disposition` = `ISSUE` \| `NOTE` \| `INPR_FIX`, `reason` |
+| `finding_disposition` | `scripts/classify-finding.sh`, one per finding | `severity`, `confidence`, `agent`, `scope` = `introduced` \| `pre-existing` \| `unknown` (from the diff; `unknown` when not supplied), `disposition` = `ISSUE` \| `NOTE` \| `INPR_FIX` (also MEDIUM LIKELY when `scope=introduced`), `reason` |
 | `review_panel` | `review-pr.md` Phase 4 | `agents_selected`, `agents_completed`, `mode` = `FULL` \| `DELTA` \| `BASE_SYNC_ONLY` |
-| `ci_gate` | `scripts/wait-ci-green.sh` | `result` = `PASS` \| `FAIL` \| `ERROR` \| `TIMEOUT`, `rc`, `checks` |
+| `ci_gate` | `scripts/wait-ci-green.sh` | `result` = `PASS` \| `FAIL` \| `ERROR` \| `TIMEOUT` \| `RATE_LIMITED` (rc 4: GitHub throttled or briefly unavailable for the whole window; retryable, never a verdict), `rc`, `checks` |
+| `ci_pending_wait` | the engine (`bin/engine/telemetry-seam.mjs`, one per finished CI-pending wait at the merge gate; `phase` = `review` \| `remediate`) | `pr`, `minutes_waited`, `result` = `green` \| `red` \| `error` \| `timeout`, `polls` (CI reads made), `rate_limit_sleeps` (polls that were rate-limited plus sleeps until the budget reset) |
+| `ci_local` | `scripts/ci-local.sh run` (validate V4.8), one per run | `result` = `PASS` \| `FAIL` \| `DEGRADED`, `jobs_run`, `jobs_deferred`, `jobs_failed`, `duration_ms`, `fix_iterations` (0 first run, 1 and 2 after fixes), `checks`, `cache_hits`, `narrowed` (checks run on a subset or skipped for no impact), `widened` (checks widened to the full command), `selected` / `total` (summed scope) |
+| `ci_local_check` | `scripts/ci-local.sh run`, one per scoped, widened or executed check (at most 20 per run) | `job`, `selector`, `selected`, `total`, `cache` = `hit` \| `miss` \| `na`, `duration_ms`, `widen` (reason or `none`). A remote-CI failure at merge on a check recorded here as narrowed is a selector bug |
 | `liveness` | `scripts/remediate-liveness.sh` | `decision` = `PROCEED` \| `DEFER` \| `EXHAUSTED`, `why` |
 | `phase_attempt` | the engine (`bin/engine/telemetry-seam.mjs`, one per phase attempt; `phase` = the phase id) | `attempt`, `model`, `turns`, `duration_ms`, `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` (any value the runner did not report is omitted) |
 | `run_terminal` | the engine (`terminate()`, one per run segment) | `reason` (terminal reason), `code` (see `docs/OUTCOME-CODES.md`), `wall_ms` (this engine process, start to terminal) |

package/docs/WORK-ON-RUNTIME.md

@@ -110,6 +110,10 @@ phase hosting `/review-pr` cannot wait on a notification. Therefore:
 `/orchestrate` Step 4B item 6.4 dispatches a worker that runs `work-on <pr> --remediate`: worker L1,
 remediate L2, reviewers L3, same as the table.
 
+### Pre-handoff base sync and union registries (forge#3969)
+
+`work-on:review` merges `origin/<base>` into the branch before the first push, so a PR is never born stale and a conflict is resolved while the build context is warm. Hand-maintained append-only registries (test lists, cron targets) are the usual conflict source; `scripts/detect-append-registries.sh` ranks them from history and proves a `.gitattributes` `merge=union` entry safe (`--check-union`). Union is allowed only for line-independent files, never YAML/JSON maps or ordered lists (see `.gitattributes`). `scripts/review-delta.sh` still treats a hand-resolved merge as not `BASE_SYNC_ONLY`, but accepts a merge whose tree is exactly what a mechanical `git merge-tree` of the same parents produces (a clean or union merge), so union registries take the no-panel fast path.
+
 ## 5. Router routing
 
 | Phase result | Router action |
@@ -136,3 +140,17 @@ remediate L2, reviewers L3, same as the table.
 ## 8. Outcome codes
 
 Every `PHASE_FAILED`, blocked `PHASE_COMMIT` and `RUN_TERMINAL` run-log event carries a machine-readable `code` from a closed, versioned enum (`bin/engine/outcome-codes.mjs`), and `FORGE:STATE` records the causing code as `outcomeCode`. Codes come from structured evidence only, never from the prose `detail`; an unmapped outcome is `unclassified` with the raw reason kept. See `docs/OUTCOME-CODES.md`.
+
+## Remediation re-gate outcomes and spawn retries (forge#4021)
+
+The `**Re-gate outcome**` token in a `FORGE:REMEDIATION:COMPLETE` trail is a closed vocabulary the engine parses:
+`AUTO-LANDED`, `HELD-AWAITING-MERGE`, `RE-ESCALATED`, `UNFIXABLE`, `REREVIEW-REQUIRED` and `INPR-FIX-REQUESTED`.
+`INPR-FIX-REQUESTED` (with `**INPR round**: N`) means the re-review approved but posted a `FORGE:INPR_FIX` work
+order. The engine commits `remediate` with `outputs.remediation = "inpr-fix"`, re-arms it once, and re-reviews. The
+`INPR_REMEDIATION` marker count bounds it: a second request escalates to `needs-human`.
+
+A CLI spawn failure (`ETIMEDOUT`, `EAGAIN`, `ENOMEM`, `EMFILE`) carries `code = "CLI_SPAWN_TRANSIENT"`. The engine
+retries it after a 10s/30s/60s backoff on a separate counter (max 3) that does not consume a phase attempt; once
+spent, normal attempt accounting applies. `ETIMEDOUT` (a `FORGEDOCK_CLI_TIMEOUT_MS` kill) is in this class by design,
+so a phase that times out every time can run up to `maxAttempts + 3` full-length CLI sessions; lower the timeout or
+max attempts if that cost is unacceptable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -48,7 +48,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"bin/stats/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
+    "test": "bash scripts/with-run-tmpdir.sh node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"bin/stats/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
     "test:sh": "bash scripts/run-shell-tests.sh",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",

package/packages/protocol/src/types.js

@@ -109,7 +109,7 @@ export const RESERVED_TYPES = {
     partialSentinel: null,
     inlineValue: false,
     requiredFields: [],
-    reGateOutcomeValues: ['AUTO-LANDED', 'HELD-AWAITING-MERGE', 'RE-ESCALATED', 'UNFIXABLE'],
+    reGateOutcomeValues: ['AUTO-LANDED', 'HELD-AWAITING-MERGE', 'RE-ESCALATED', 'UNFIXABLE', 'INPR-FIX-REQUESTED', 'REREVIEW-REQUIRED'],
   },
   TRAJECTORY: {
     type: 'TRAJECTORY',

package/scripts/acceptance-red-green.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# acceptance-red-green.sh — red-green proof for one acceptance test: it must FAIL on the base commit and PASS on head.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: acceptance-red-green.sh --repo-path <worktree> --base-ref <ref> --test-cmd "<cmd>" [--timeout <sec>]
+# Runs <cmd> in <worktree> (head) first. Only when head RAN does it create a detached base worktree at
+# `git merge-base HEAD <base-ref>` (under mktemp -d, never inside the repo), overlay head's changed test files
+# onto it, and run <cmd> there. Each run is classified with classify-test-run.sh.
+# Prints exactly one line on stdout:   BASE=<FAILED|RAN|RAN_NOTHING|UNRUNNABLE|SKIPPED> HEAD=<FAILED|RAN|RAN_NOTHING|UNRUNNABLE>
+#   FAILED      the run executed and failed
+#   RAN         the run executed and passed
+#   RAN_NOTHING the runner exercised nothing
+#   UNRUNNABLE  could not execute (timeout 124, not executable 126/127, worktree/overlay/classifier failure)
+#   SKIPPED     base was not run because head did not PASS
+# Never prints a verdict on success of cleanup: the base worktree is removed on every exit path (trap + explicit remove).
+# Callers map: HEAD=RAN BASE=FAILED -> proof; BASE=RAN -> passes on base (gate FAIL); anything else that is not a proof -> DEGRADED/FAIL.
+# Exit: 0 line printed | 2 usage error (stdout empty so callers fail closed)
+# Bash 3.2 portable.
+set -uo pipefail
+
+REPO=""; BASE_REF=""; CMD=""; TMO=300
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo-path) REPO="${2-}"; shift 2 ;;
+    --base-ref) BASE_REF="${2-}"; shift 2 ;;
+    --test-cmd) CMD="${2-}"; shift 2 ;;
+    --timeout) TMO="${2-}"; shift 2 ;;
+    *) echo "usage: acceptance-red-green.sh --repo-path <dir> --base-ref <ref> --test-cmd <cmd> [--timeout <sec>]" >&2; exit 2 ;;
+  esac
+done
+[ -n "$REPO" ] && [ -d "$REPO" ] && [ -n "$BASE_REF" ] && [ -n "$CMD" ] || { echo "usage: acceptance-red-green.sh --repo-path <dir> --base-ref <ref> --test-cmd <cmd> [--timeout <sec>]" >&2; exit 2; }
+case "$TMO" in ''|*[!0-9]*) TMO=300 ;; esac
+CLS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/classify-test-run.sh"
+
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/forge-redgreen.XXXXXX") || { echo "BASE=UNRUNNABLE HEAD=UNRUNNABLE"; exit 0; }
+BASE_WT="$WORK/base"; ADDED=false
+cleanup() {
+  [ "$ADDED" = "true" ] && git -C "$REPO" worktree remove --force "$BASE_WT" >/dev/null 2>&1
+  ADDED=false
+  rm -rf "$WORK"
+  git -C "$REPO" worktree prune >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+TIMEOUT_BIN=$(command -v timeout || command -v gtimeout || true)
+
+# run_in <dir> -> prints the classification word
+run_in() {
+  local dir="$1" out="$WORK/out.$$.txt" rc cls
+  if [ -n "$TIMEOUT_BIN" ]; then ( cd "$dir" && "$TIMEOUT_BIN" "$TMO" bash -c "$CMD" ) >"$out" 2>&1; rc=$?
+  else ( cd "$dir" && bash -c "$CMD" ) >"$out" 2>&1; rc=$?; fi
+  case "$rc" in 124|126|127) echo UNRUNNABLE; return ;; esac
+  cls=$(bash "$CLS" "$rc" "$out" 2>/dev/null)
+  case "$cls" in FAILED|RAN|RAN_NOTHING) echo "$cls" ;; *) echo UNRUNNABLE ;; esac
+}
+
+HEAD_RES=$(run_in "$REPO")
+if [ "$HEAD_RES" != "RAN" ]; then echo "BASE=SKIPPED HEAD=$HEAD_RES"; exit 0; fi
+
+BASE_SHA=$(git -C "$REPO" merge-base HEAD "$BASE_REF" 2>/dev/null)
+[ -n "$BASE_SHA" ] && git -C "$REPO" worktree add --detach "$BASE_WT" "$BASE_SHA" >/dev/null 2>&1 && ADDED=true
+if [ "$ADDED" != "true" ]; then echo "BASE=UNRUNNABLE HEAD=$HEAD_RES"; exit 0; fi
+
+# Overlay: head's changed test files onto base (a new test file does not exist at base; running without it is a false red).
+is_test_path() {
+  case "$1" in
+    /*|..|../*|*/../*|*/..) return 1 ;;
+  esac
+  case "$1" in
+    test/*|tests/*|spec/*|__tests__/*|*/test/*|*/tests/*|*/spec/*|*/__tests__/*|*.test.*|*_test.*|*.spec.*|*_spec.*|*/test_*|test_*) return 0 ;;
+  esac
+  return 1
+}
+OVERLAY_OK=true
+CHANGED=$( { git -C "$REPO" diff --name-only "$BASE_SHA" 2>/dev/null; git -C "$REPO" ls-files --others --exclude-standard 2>/dev/null; } | sort -u )
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  is_test_path "$f" || continue
+  [ -f "$REPO/$f" ] && [ ! -L "$REPO/$f" ] || continue   # deleted at head, or a symlink: never copied
+  mkdir -p "$BASE_WT/$(dirname "$f")" && cp -p "$REPO/$f" "$BASE_WT/$f" 2>/dev/null && [ -f "$BASE_WT/$f" ] || OVERLAY_OK=false
+done <<< "$CHANGED"
+# Untracked dependency tree (never in git): link it so a missing install is not mistaken for a red run.
+[ -d "$REPO/node_modules" ] && [ ! -e "$BASE_WT/node_modules" ] && ln -s "$REPO/node_modules" "$BASE_WT/node_modules" 2>/dev/null
+
+if [ "$OVERLAY_OK" != "true" ]; then BASE_RES=UNRUNNABLE; else BASE_RES=$(run_in "$BASE_WT"); fi
+cleanup   # explicit; the EXIT trap is the backstop
+echo "BASE=$BASE_RES HEAD=$HEAD_RES"
+exit 0

package/scripts/acceptance-red-green.test.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# acceptance-red-green.test.sh — tests for scripts/acceptance-red-green.sh (real temp git repos, no network)
+# Usage: bash scripts/acceptance-red-green.test.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RG="$SCRIPT_DIR/acceptance-red-green.sh"
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+export TMPDIR="$TMP/tmpdir"; mkdir -p "$TMPDIR"
+PASS=0; FAILN=0
+ok() { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+
+# make_repo <dir>: base commit on branch main with app.sh (defect: prints bad), then a feature branch is the caller's job
+make_repo() {
+  git init -q -b main "$1" && git -C "$1" config user.email t@t && git -C "$1" config user.name t
+  printf 'echo bad\n' > "$1/app.sh"; git -C "$1" add -A; git -C "$1" commit -qm base
+  git -C "$1" update-ref refs/remotes/origin/main HEAD
+}
+fix_head() { printf 'echo good\n' > "$1/app.sh"; git -C "$1" add -A; git -C "$1" commit -qm fix; }
+leaked() { git -C "$1" worktree list | wc -l | tr -d ' '; }
+check() { # name want repo cmd [extra...]
+  local name="$1" want="$2" repo="$3" cmd="$4" got
+  got=$(bash "$RG" --repo-path "$repo" --base-ref origin/main --test-cmd "$cmd" 2>/dev/null)
+  if [ "$got" = "$want" ]; then ok "$name"; else bad "$name: want '$want' got '$got'"; fi
+  if [ "$(leaked "$repo")" = "1" ] && [ -z "$(ls "$TMPDIR")" ]; then ok "$name: base worktree and tmp dir cleaned"; else bad "$name: leaked worktree or tmp ($(leaked "$repo") worktrees)"; fi
+}
+
+# 1. real red-green proof: test greps the fixed output, new test file only exists at head (overlay)
+R1="$TMP/r1"; make_repo "$R1"; fix_head "$R1"
+mkdir -p "$R1/tests"; printf 'test "$(bash app.sh)" = good && echo "1 passed"\n' > "$R1/tests/t.sh"; git -C "$R1" add -A; git -C "$R1" commit -qm test
+check "red on base, green on head (new test file overlaid)" "BASE=FAILED HEAD=RAN" "$R1" "bash tests/t.sh"
+
+# 2. passes on base: test never touches the defect
+R2="$TMP/r2"; make_repo "$R2"; fix_head "$R2"
+mkdir -p "$R2/tests"; printf 'echo "1 passed"\n' > "$R2/tests/t.sh"; git -C "$R2" add -A; git -C "$R2" commit -qm test
+check "passes on base" "BASE=RAN HEAD=RAN" "$R2" "bash tests/t.sh"
+
+# 3. head fails: base is not run
+check "head failure skips base" "BASE=SKIPPED HEAD=FAILED" "$R1" "bash app.sh; exit 1"
+
+# 4. RAN_NOTHING on head
+check "runner that exercises nothing on head" "BASE=SKIPPED HEAD=RAN_NOTHING" "$R1" "echo 'no tests ran'"
+
+# 5. command not found (127) on head
+check "rc 127 is UNRUNNABLE" "BASE=SKIPPED HEAD=UNRUNNABLE" "$R1" "definitely-not-a-command-xyz"
+
+# 6. base cannot execute: the command only exists at head (non-test file), so base yields 127
+R3="$TMP/r3"; make_repo "$R3"; fix_head "$R3"
+printf 'echo "1 passed"\n' > "$R3/runner.sh"; chmod +x "$R3/runner.sh"; git -C "$R3" add -A; git -C "$R3" commit -qm runner
+check "base rc 127 (runner absent at base) is UNRUNNABLE" "BASE=UNRUNNABLE HEAD=RAN" "$R3" "./runner.sh"
+
+# 7. base ref unresolvable: worktree cannot be created
+got=$(bash "$RG" --repo-path "$R1" --base-ref origin/does-not-exist --test-cmd "bash tests/t.sh" 2>/dev/null)
+[ "$got" = "BASE=UNRUNNABLE HEAD=RAN" ] && ok "unresolvable base ref is UNRUNNABLE" || bad "unresolvable base ref: got '$got'"
+[ "$(leaked "$R1")" = "1" ] && ok "no worktree after failed setup" || bad "worktree leaked after failed setup"
+
+# 8. non-test files are never overlaid (a changed source file stays at base)
+R4="$TMP/r4"; make_repo "$R4"; fix_head "$R4"
+check "source file stays at base (no overlay of non-test files)" "BASE=FAILED HEAD=RAN" "$R4" 'test "$(bash app.sh)" = good && echo "1 passed"'
+
+# 9. timeout is UNRUNNABLE when a timeout binary exists
+if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
+  got=$(bash "$RG" --repo-path "$R1" --base-ref origin/main --test-cmd "sleep 5" --timeout 1 2>/dev/null)
+  [ "$got" = "BASE=SKIPPED HEAD=UNRUNNABLE" ] && ok "timeout is UNRUNNABLE" || bad "timeout: got '$got'"
+fi
+
+# 10. usage errors print nothing and exit 2
+out=$(bash "$RG" --repo-path "$R1" 2>/dev/null); rc=$?
+{ [ "$rc" -eq 2 ] && [ -z "$out" ]; } && ok "missing args exit 2, empty stdout" || bad "usage: rc=$rc out='$out'"
+
+echo "$PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/cap-findings.test.sh

@@ -6,6 +6,8 @@
 # Run: bash scripts/cap-findings.test.sh   (bash 3.2 compatible)
 
 set -u
+# Every mktemp below lands in one private dir that the EXIT trap removes (forge#4016).
+_SUITE_TMP=$(mktemp -d); export TMPDIR="$_SUITE_TMP"; trap 'rm -rf "$_SUITE_TMP"' EXIT
 DIR=$(cd "$(dirname "$0")" && pwd)
 S="$DIR/cap-findings.sh"
 pass=0; fail=0

package/scripts/check-contract-scope.test.sh

@@ -6,6 +6,8 @@
 # Run: bash scripts/check-contract-scope.test.sh   (bash 3.2 compatible)
 
 set -u
+# Every mktemp below lands in one private dir that the EXIT trap removes (forge#4016).
+_SUITE_TMP=$(mktemp -d); export TMPDIR="$_SUITE_TMP"; trap 'rm -rf "$_SUITE_TMP"' EXIT
 DIR=$(cd "$(dirname "$0")" && pwd)
 S="$DIR/check-contract-scope.sh"
 pass=0; fail=0

package/scripts/check-edge-cases.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-edge-cases.sh — Enforce that every FORGE:ARCHITECT edge case maps to a test in the diff or an untestable reason.
+#
+# Usage: check-edge-cases.sh --architect <file> --builder <file> --base <ref> [--repo <path>]
+#
+# <architect> is a FORGE:ARCHITECT comment body (or the extracted block); only the text between
+# <!-- FORGE:EDGE_CASES:BEGIN --> and <!-- FORGE:EDGE_CASES:END --> is parsed. One record per line:
+#   EDGE: id=e1 kind=error|edge|concurrency description=<free text>
+# Only id= and kind= are parsed; the description is free text and is never interpreted. ids match ^e[0-9]+$.
+# <builder> is a FORGE:BUILDER comment body (may be empty or absent content). Lines parsed:
+#   EDGE_TEST: id=e1 test=<path>::<name>
+#   EDGE_TEST: id=e1 untestable=<non-empty reason, spaces allowed>
+#
+# An id is covered when it has a non-empty untestable= reason, or a test=<path>::<name> where <name> (fixed-string)
+# appears in a line ADDED to <path> by the change (merge-base(base,HEAD) to the working tree, plus untracked files).
+# Pre-existing tests never satisfy a new edge case.
+#
+# Exit codes:
+#   0  covered, or no edge-case block / empty block (prints "SKIP: ..."); on success prints "MAPPED_TESTS: <n>"
+#   1  UNMAPPED: <id> | TEST_NOT_IN_DIFF: <id> <path>::<name> | EMPTY_REASON: <id> | DUPLICATE_ID: <id>
+#   2  malformed block or EDGE_TEST line, bad arguments, unreadable input, unresolvable base, git failure —
+#      NEVER a pass; callers report DEGRADED
+#
+# Offline, values are data (never eval'd). Portable to bash 3.2: no mapfile, no associative arrays.
+
+set -uo pipefail
+
+ARCH=""; BUILDER=""; BASE=""; REPO="."
+USAGE="usage: check-edge-cases.sh --architect <file> --builder <file> --base <ref> [--repo <path>]"
+die2() { echo "check-edge-cases: $*" >&2; exit 2; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --architect) [ "$#" -ge 2 ] || die2 "--architect needs a value"; ARCH="$2"; shift 2 ;;
+    --builder)   [ "$#" -ge 2 ] || die2 "--builder needs a value"; BUILDER="$2"; shift 2 ;;
+    --base)      [ "$#" -ge 2 ] || die2 "--base needs a value"; BASE="$2"; shift 2 ;;
+    --repo)      [ "$#" -ge 2 ] || die2 "--repo needs a value"; REPO="$2"; shift 2 ;;
+    *) die2 "$USAGE" ;;
+  esac
+done
+[ -n "$ARCH" ] && [ -n "$BUILDER" ] && [ -n "$BASE" ] || die2 "$USAGE"
+[ -f "$ARCH" ] || die2 "architect file not found: $ARCH"
+[ -f "$BUILDER" ] || die2 "builder file not found: $BUILDER"
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/check-edge-cases.XXXXXX") || die2 "mktemp failed"
+trap 'rm -rf "$TMP"' EXIT
+
+# ---- extract BEGIN..END regions of the architect body --------------------------------------------------
+awk -v out="$TMP/region" '
+  index($0, "<!-- FORGE:EDGE_CASES:BEGIN -->") { if (inb) { bad = 1 } inb = 1; seen = 1; next }
+  index($0, "<!-- FORGE:EDGE_CASES:END -->")   { if (!inb) { bad = 1 } inb = 0; next }
+  inb { print > out }
+  END { if (inb || bad) exit 3; if (!seen) exit 4 }
+' "$ARCH"
+case $? in
+  0) ;;
+  4) echo "SKIP: no edge-case block"; exit 0 ;;
+  *) die2 "unbalanced FORGE:EDGE_CASES:BEGIN/END markers" ;;
+esac
+
+# ---- parse EDGE records ---------------------------------------------------------------------------------
+: > "$TMP/ids"; : > "$TMP/dups"
+EDGE_RE='^EDGE: id=(e[0-9]+) kind=(error|edge|concurrency)([[:space:]]|$)'
+LN=0
+if [ -f "$TMP/region" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    LN=$((LN+1)); line="${line%$'\r'}"
+    trimmed="${line#"${line%%[![:space:]]*}"}"
+    case "$trimmed" in ""|'```'*) continue ;; esac
+    [[ "$trimmed" =~ $EDGE_RE ]] || die2 "line $LN: malformed EDGE record: $trimmed"
+    id="${BASH_REMATCH[1]}"
+    if grep -Fxq -- "$id" "$TMP/ids"; then echo "$id" >> "$TMP/dups"; else echo "$id" >> "$TMP/ids"; fi
+  done < "$TMP/region"
+fi
+if [ ! -s "$TMP/ids" ]; then echo "SKIP: empty edge-case block"; exit 0; fi
+
+# ---- parse EDGE_TEST lines of the builder body ----------------------------------------------------------
+: > "$TMP/maps"   # id<TAB>test|untestable<TAB>value
+: > "$TMP/mapdups"
+PRE='^(-[[:space:]]+)?EDGE_TEST:[[:space:]]+id=(e[0-9]+)[[:space:]]+(test|untestable)=(.*)$'
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+  trimmed="${line#"${line%%[![:space:]]*}"}"
+  case "$trimmed" in *EDGE_TEST:*) ;; *) continue ;; esac
+  case "$trimmed" in EDGE_TEST:*|"- EDGE_TEST:"*) ;; *) continue ;; esac   # only line-leading records, not prose mentions
+  [[ "$trimmed" =~ $PRE ]] || die2 "malformed EDGE_TEST line: $trimmed"
+  mid="${BASH_REMATCH[2]}"; mkind="${BASH_REMATCH[3]}"; mval="${BASH_REMATCH[4]}"
+  mval="${mval#"${mval%%[![:space:]]*}"}"; mval="${mval%"${mval##*[![:space:]]}"}"
+  if awk -F'\t' -v s="$mid" '$1==s {ok=1} END{exit ok?0:1}' "$TMP/maps"; then echo "$mid" >> "$TMP/mapdups"; continue; fi
+  printf '%s\t%s\t%s\n' "$mid" "$mkind" "$mval" >> "$TMP/maps"
+done < "$BUILDER"
+
+# ---- repo, base, merge-base -----------------------------------------------------------------------------
+case "$BASE" in ""|-*) die2 "invalid --base: '$BASE'" ;; esac
+git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1 || die2 "not a git work tree: $REPO"
+git -C "$REPO" rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 || die2 "cannot resolve base ref '$BASE'"
+MB=$(git -C "$REPO" merge-base "$BASE" HEAD 2>/dev/null) || die2 "no merge base between '$BASE' and HEAD"
+
+# added_has <path> <name>: 0 when <name> (fixed string) occurs in a line added to <path>
+added_has() {
+  local p="$1" n="$2" rc
+  if git -C "$REPO" ls-files --error-unmatch -- "$p" >/dev/null 2>&1; then
+    git -C "$REPO" diff -U0 --no-color "$MB" -- "$p" > "$TMP/d" 2>/dev/null || die2 "git diff failed for $p"
+    awk -v n="$n" '/^\+\+\+/ {next} /^\+/ { if (index($0, n) > 0) ok=1 } END{exit ok?0:1}' "$TMP/d"; return $?
+  fi
+  # untracked (new, not yet staged) file: every line is added
+  git -C "$REPO" ls-files --others --exclude-standard -- "$p" > "$TMP/u" 2>/dev/null || die2 "git ls-files failed"
+  [ -s "$TMP/u" ] || return 1
+  [ -f "$REPO/$p" ] || return 1
+  awk -v n="$n" 'index($0, n) > 0 {ok=1} END{exit ok?0:1}' "$REPO/$p"; rc=$?
+  return "$rc"
+}
+
+# ---- check ----------------------------------------------------------------------------------------------
+RC=0; MAPPED=0
+while IFS= read -r d; do [ -n "$d" ] && { echo "DUPLICATE_ID: $d"; RC=1; }; done < "$TMP/dups"
+while IFS= read -r d; do [ -n "$d" ] && { echo "DUPLICATE_ID: $d (EDGE_TEST)"; RC=1; }; done < "$TMP/mapdups"
+PATH_RE='^[A-Za-z0-9_./@+=:,-]+$'
+NAME_RE='^[^[:space:]]{1,200}$'
+while IFS= read -r id; do
+  row=$(awk -F'\t' -v s="$id" '$1==s {print; exit}' "$TMP/maps")
+  if [ -z "$row" ]; then echo "UNMAPPED: $id"; RC=1; continue; fi
+  mkind=$(printf '%s' "$row" | cut -f2); mval=$(printf '%s' "$row" | cut -f3-)
+  if [ "$mkind" = untestable ]; then
+    [ -n "$mval" ] || { echo "EMPTY_REASON: $id"; RC=1; }
+    continue
+  fi
+  case "$mval" in *::*) ;; *) die2 "$id: test= must be <path>::<name>: $mval" ;; esac
+  tpath="${mval%%::*}"; tname="${mval##*::}"
+  case "$tpath" in -*) die2 "$id: test path must not start with '-'" ;; esac
+  [[ "$tpath" =~ $PATH_RE ]] || die2 "$id: invalid test path: $tpath"
+  [[ "$tname" =~ $NAME_RE ]] || die2 "$id: invalid test name"
+  if added_has "$tpath" "$tname"; then MAPPED=$((MAPPED+1)); else echo "TEST_NOT_IN_DIFF: $id $tpath::$tname"; RC=1; fi
+done < "$TMP/ids"
+
+if [ "$RC" -eq 0 ]; then
+  echo "OK: edge cases covered ($(wc -l < "$TMP/ids" | tr -d ' ') id(s))"
+  echo "MAPPED_TESTS: $MAPPED"
+fi
+exit "$RC"