forgedock 1.18.0 → 1.20.0

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,21 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## v1.19.1: build-time self-review, ci-local under concurrency, review roster gates
+
+- **Build-time self-review (B5.6, #3971).** After implement, the risk-tier review roster's domain agents review the staged diff, and the builder fixes CONFIRMED/LIKELY findings at MEDIUM or above in one repair round before validate. Small or docs-only diffs skip. Each build that runs it spends extra reviewer tokens, which the official review should save back through fewer findings and remediation rounds. Off switch: `FORGE_SELFREVIEW=off`. Wait budget: `SELFREVIEW_WAIT_SECS` (default 600, max 1800). Telemetry: `build_selfreview`.
+- **ci-local (#4057).** The SEC-3 "every changed source reaches a test" check uses the step's own ecosystem tests, not only the step's candidates, so unrelated single-test steps are skipped instead of widened. Identical checks in several jobs run once per invocation (`cache=dedup`). Machine slots are granted in FIFO ticket order. Job lines and `ci_local_check` carry `wait_ms` apart from execution `duration_ms`. Jobs run shortest first.
+- **Review roster.** The Auth path gate also matches common auth file names (session, token, permission, login, API key) (#3847). The Infra gate covers deploy scripts, entrypoints and `compose.yaml` (#3851). The Security-only fix-PR roster applies only to fix PRs of at most 150 changed lines with a known size; larger or unknown-size fix PRs get the standard roster (#3848).
+- **Merge gate.** `review-finalize.sh verdict` derives OTHER_BLOCKING itself and persists it for `merge-gate`, so a blocking result that a base conflict or purpose regression does not explain can no longer be merged on a missing flag (#3514).
+
+Action: none required. Expect more reviewer agents per build (self-review) and per large fix PR (roster cap).
+
+## Deferred follow-up lookup no longer duplicates issues (#3606)
+
+`scripts/file-deferred-followups.sh` now finds an existing follow-up through the `FORGE:DEFERRED_ISSUE` claim marker it posts on the parent issue (REST comments, read-after-write consistent) before falling back to the lagging search index, searches closed issues as well as open ones (a closed follow-up is reopened), and after creating re-checks once: if a concurrent build filed a lower-numbered trusted follow-up, the items move to it and the newer issue is closed as a duplicate. Failed lookups still exit non-zero (`DEFERRED_LOOKUP=FAILED`).
+
+Action: none. Output rows and the `DEFERRED_TELEMETRY` line are unchanged.
+
 ## Review specs call the prepare and finalize scripts (#3841)
 
 `commands/review-pr.md` is now under 100 KB: Phases 1-3B and 6 run through `scripts/review-prepare.sh` and `scripts/review-finalize.sh`, and `commands/review-pr-staging.md` reuses both (`review-prepare.sh --no-delta` in 0C, then `review-finalize.sh extract|classify|file-prepare|file-verify` with `--scope-files` and `--prior-prs` in Phase 7) instead of carrying its own template resolution, slicing, classifier and cap copies. A staging bundle whose API diff is too large is read from `origin/<base>...origin/<head>`. CI now runs `--fence-funcs` over `commands/review-pr*.md` and `--fence-state` over the staging spec. Engine: `close.detectOutcome` reports `merged` only for a CLOSED issue that also carries `workflow:merged` (a stale label on an open issue no longer counts).

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` (execution), `wait_ms` (time queued for a machine slot), `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` \| `dedup` \| `na`, `duration_ms`, `wait_ms` (job slot wait), `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

@@ -46,7 +46,8 @@ L3) works, which is why most PRs are reviewed normally.
 ## 3. Design rules
 
 **R1 — Dispatching phases are invoked only by the router.** A *dispatching* phase is one that spawns
-`Agent(...)` sub-agents directly or through `/review-pr`: `work-on:review` and `work-on:remediate`.
+`Agent(...)` sub-agents directly or through `/review-pr`: `work-on:review`, `work-on:remediate` and, since forge#3971,
+`work-on:build` (its B5.6 self-review dispatches the risk-tier roster's domain reviewers on the staged diff).
 Only the router may invoke them, so they always run at router layer + 1 (L2 under `/orchestrate`,
 L1 solo). When another phase needs one, it returns a handoff (`status: NEXT`, `next: <phase>`) and
 the router invokes it. Concretely: review returns `next: remediate` instead of calling remediation.
@@ -59,7 +60,8 @@ re-runs the missing phases. `/review-pr` (Phase 8, via `scripts/review-finalize.
 
 **R2 — Non-dispatching forks may nest.** Phases and children that never spawn sub-agents may invoke
 further forks at any depth (F5): build → context/architect/implement/validate → quality-gate,
-review → quality-gate / missing-phase re-dispatch, remediate → close. Forking them keeps each
+review → quality-gate / missing-phase re-dispatch, remediate → close. The build children never spawn: the
+self-review reviewers are spawned by `work-on:build` itself, and its repair round is an `implement` fork. Forking them keeps each
 context small. If one of them ever needs to spawn sub-agents, it becomes a dispatching phase and
 R1 applies.
 
@@ -99,17 +101,27 @@ phase hosting `/review-pr` cannot wait on a notification. Therefore:
 | Skill | Fork | Dispatches sub-agents | Invoked by | Layer solo / orchestrated |
 |-------|------|-----------------------|------------|---------------------------|
 | `work-on` (router) | — | no | user / orchestrator worker | 0 / 1 |
-| `work-on:investigate`, `work-on:decompose`, `work-on:build`, `work-on:close` | yes | no | router | 1 / 2 |
+| `work-on:investigate`, `work-on:decompose`, `work-on:close` | yes | no | router | 1 / 2 |
+| `work-on:build` (B5.6 self-review) | yes | **yes** (self-review reviewers; degrades to a recorded skip when `Agent` is withheld) | router only (R1) | 1 / 2 |
 | `work-on:build:{context,architect,implement,validate}` | yes | no | `work-on:build` (R2) | 2 / 3 |
 | `quality-gate` | yes | no | validate (R2) | 3 / 4 |
 | `quality-gate` (stale-review re-gate) | yes | no | review (R2) | 2 / 3 |
 | `work-on:review` → `/review-pr` | yes | **yes** | router only (R1) | 1 / 2 |
 | `work-on:remediate` → `/review-pr` | yes | **yes** | router only (R1) | 1 / 2 |
 | `/review-pr` domain reviewers | Agent | no (leaves) | `/review-pr` | 2 / 3 |
+| build self-review reviewers (`FORGE:SELFREVIEW-AGENT:*`) | Agent | no (leaves) | `work-on:build` B5.6 | 2 / 3 |
 
 `/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.
+
+### Build-time self-review (forge#3971)
+
+`work-on:build` Phase B5.6 runs the risk-tier roster (`scripts/selfreview-plan.sh`, which calls `scripts/review-roster.sh` on the staged diff) before validate, with the same personas as `/review-pr` in SELF-REVIEW MODE (`commands/review-pr-agents/protocols.md`). It is not the official review: reviewers post `FORGE:SELFREVIEW-AGENT:{domain}` issue comments pinned to the staged tree (`Tree:`), never `FORGE:REVIEW-AGENT`, and `review-finalize.sh` / `verify-phase-trail.sh` ignore them. Like R6, completion is read from GitHub with a bounded wait, because reviewers spawned inside a fork report to the root session. A build at a layer where `Agent` is withheld, or any self-review failure, degrades to a recorded skip (`build_selfreview skipped=<reason>`) and never blocks the build.
+
 ## 5. Router routing
 
 | Phase result | Router action |
@@ -136,3 +148,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.20.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/architect-resume-match.test.sh

@@ -15,7 +15,7 @@ ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
 bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
 eq()  { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (got '$2', want '$3')"; fi; }
 
-SELECT_JQ='[.[][] | select((.body // "") | startswith("<!-- FORGE:ARCHITECT -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:ARCHITECT:COMPLETE -->")), other: (.body | test("<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|BUILDER)"))}]'
+SELECT_JQ='[.[][] | select((.body // "") | startswith("<!-- FORGE:ARCHITECT -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:ARCHITECT:COMPLETE -->")), other: (.body | test("\\n[ \\t]*<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|BUILDER)"))}]'
 DELETE_JQ='[.[] | select(.complete | not)] | if length == 1 and (.[0].other | not) then .[0].id else empty end'
 
 # c <id> <assoc> <type> <body>
@@ -28,7 +28,7 @@ PLAN=$'<!-- FORGE:ARCHITECT -->\n## Plan\n\n<!-- FORGE:ARCHITECT:COMPLETE -->'
 PARTIAL=$'<!-- FORGE:ARCHITECT -->\n## Plan (in progress)'
 INVEST=$'<!-- FORGE:INVESTIGATOR -->\nThe architect phase posts FORGE:ARCHITECT and FORGE:ARCHITECT:COMPLETE later.'
 CTX=$'<!-- FORGE:CONTEXT -->\nmentions <!-- FORGE:ARCHITECT -->'
-MIXED=$'<!-- FORGE:ARCHITECT -->\nquoted <!-- FORGE:INVESTIGATOR -->'
+MIXED=$'<!-- FORGE:ARCHITECT -->\nquoted:\n<!-- FORGE:INVESTIGATOR -->'
 
 eq "INVESTIGATOR mentioning FORGE:ARCHITECT is not selected" "$(arch "$(c 1 NONE Bot "$INVEST")" | jq length)" 0
 eq "INVESTIGATOR mentioning FORGE:ARCHITECT is never deleted" "$(del_id "$(c 1 NONE Bot "$INVEST")")" ""
@@ -39,10 +39,19 @@ eq "single partial plan -> delete its id" "$(del_id "$(c 4 NONE Bot "$PARTIAL")"
 eq "two partial plans -> delete nothing" "$(del_id "$(c 4 NONE Bot "$PARTIAL")"$'\n'"$(c 5 NONE Bot "$PARTIAL")")" ""
 eq "untrusted author partial ignored" "$(del_id "$(c 6 NONE User "$PARTIAL")")" ""
 eq "untrusted author complete ignored" "$(n_complete "$(c 6 NONE User "$PLAN")")" 0
-eq "partial carrying another FORGE marker is not deleted" "$(del_id "$(c 7 NONE Bot "$MIXED")")" ""
+eq "partial with another FORGE marker at a line start is not deleted" "$(del_id "$(c 7 NONE Bot "$MIXED")")" ""
 eq "investigator + partial plan -> only the plan id" "$(del_id "$(c 1 NONE Bot "$INVEST")"$'\n'"$(c 8 NONE Bot "$PARTIAL")")" 8
 eq "paginated concatenated arrays" "$(printf '[%s]\n[%s]' "$(c 1 NONE Bot "$INVEST")" "$(c 9 NONE Bot "$PLAN")" | jq -s "$SELECT_JQ" | jq '[.[] | select(.complete)] | length')" 1
 
+INLINE=$'<!-- FORGE:ARCHITECT -->\n## Approach\nFollowed the plan in `<!-- FORGE:BUILDER -->` and <!-- FORGE:INVESTIGATOR --> notes.'
+CRLF=$'<!-- FORGE:ARCHITECT -->\r\n<!-- FORGE:BUILDER -->\r\nbody'
+eq "partial quoting a marker inline is picked and deleted e1_inline_picked" "$(del_id "$(c 11 NONE Bot "$INLINE")")" 11
+eq "inline quoting partial is selected as non-other e1_inline_not_other" "$(arch "$(c 11 NONE Bot "$INLINE")" | jq -r '.[0].other')" false
+eq "marker at the start of a later line is refused e2_line_start_refused" "$(arch "$(c 12 NONE Bot "$MIXED")" | jq -r '.[0].other')" true
+eq "own first-line marker never counts as other e4_own_marker_not_other" "$(arch "$(c 13 NONE Bot "$PARTIAL")" | jq -r '.[0].other')" false
+eq "two inline-quoting partials still delete nothing e3_two_partials_none" "$(del_id "$(c 11 NONE Bot "$INLINE")"$'\n'"$(c 14 NONE Bot "$INLINE")")" ""
+eq "CRLF body with a marker line is still refused e5_crlf_refused" "$(del_id "$(c 15 NONE Bot "$CRLF")")" ""
+
 # Spec drift guard: the spec carries this exact predicate and no unanchored selector.
 ! grep -qF 'contains("FORGE:ARCHITECT")' "$SPEC" && ok "architect.md has no unanchored contains(FORGE:ARCHITECT)" || bad "architect.md still uses unanchored contains"
 grep -qF 'startswith("<!-- FORGE:ARCHITECT -->")' "$SPEC" && ok "architect.md anchors with startswith" || bad "architect.md lacks the startswith anchor"

package/scripts/build-knowledge-index.mjs

@@ -173,12 +173,14 @@ function readForgeYaml(repoPath) {
   const yamlPath = join(repoPath, 'forge.yaml');
   if (!existsSync(yamlPath)) return null;
   try {
-    const result = spawnSync('yq', ['-r', '.project.owner + "/" + .project.repo', yamlPath], {
+    const result = spawnSync('yq', ['-r', '.project.owner, .project.repo', yamlPath], {
       encoding: 'utf8',
       timeout: 5000,
     });
-    if (result.status === 0 && result.stdout.trim()) {
-      return result.stdout.trim();
+    if (result.status === 0) {
+      const [owner, name] = result.stdout.split('\n').map(l => l.trim());
+      // Both halves must be real values: a partial forge.yaml must not yield "/" or "null/x"
+      if (owner && name && owner !== 'null' && name !== 'null') return `${owner}/${name}`;
     }
   } catch (_) {
     // ignore
@@ -1576,7 +1578,7 @@ async function main() {
     repo = readForgeYaml(repoPath);
   }
   if (!repo) {
-    process.stderr.write('[ledger] ERROR: Cannot determine GitHub repo. Pass --repo owner/repo or ensure forge.yaml is present.\n');
+    process.stderr.write('[ledger] ERROR: Cannot determine GitHub repo. Pass --repo owner/repo or ensure forge.yaml has project.owner and project.repo (yq required).\n');
     process.exit(1);
   }
 
@@ -1760,6 +1762,7 @@ async function main() {
 }
 
 main().catch(e => {
-  process.stderr.write(`[ledger] FATAL: ${e.message}\n${e.stack}\n`);
+  const showStack = process.argv.includes('--verbose') || !!process.env.FORGE_DEBUG;
+  process.stderr.write(`[ledger] FATAL: ${e && e.message ? e.message : e}\n${showStack && e && e.stack ? e.stack + '\n' : ''}`);
   process.exit(1);
 });

package/scripts/builder-resume-match.test.sh

@@ -14,7 +14,7 @@ ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
 bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
 eq()  { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (got '$2', want '$3')"; fi; }
 
-SELECT_JQ='[.[][] | select((.body // "") | startswith("<!-- FORGE:BUILDER -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:BUILDER:COMPLETE -->")), other: (.body | test("<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|ARCHITECT)"))}]'
+SELECT_JQ='[.[][] | select((.body // "") | startswith("<!-- FORGE:BUILDER -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:BUILDER:COMPLETE -->")), other: (.body | test("\\n[ \\t]*<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|ARCHITECT)"))}]'
 DELETE_JQ='[.[] | select(.complete | not)] | if length == 1 and (.[0].other | not) then .[0].id else empty end'
 
 # c <id> <assoc> <type> <body>
@@ -27,7 +27,7 @@ PLAN=$'<!-- FORGE:BUILDER -->\n## Implementation\n\n<!-- FORGE:BUILDER:COMPLETE
 PARTIAL=$'<!-- FORGE:BUILDER -->\n## Implementation (in progress)'
 INVEST=$'<!-- FORGE:INVESTIGATOR -->\nThe build phase later posts FORGE:BUILDER and FORGE:BUILDER:COMPLETE.'
 CTX=$'<!-- FORGE:CONTEXT -->\nmentions <!-- FORGE:BUILDER -->'
-MIXED=$'<!-- FORGE:BUILDER -->\nquoted <!-- FORGE:INVESTIGATOR -->'
+MIXED=$'<!-- FORGE:BUILDER -->\nquoted:\n<!-- FORGE:INVESTIGATOR -->'
 
 eq "INVESTIGATOR mentioning FORGE:BUILDER is not selected" "$(arch "$(c 1 NONE Bot "$INVEST")" | jq length)" 0
 eq "INVESTIGATOR mentioning FORGE:BUILDER is never deleted" "$(del_id "$(c 1 NONE Bot "$INVEST")")" ""
@@ -38,7 +38,7 @@ eq "single partial comment -> delete its id" "$(del_id "$(c 4 NONE Bot "$PARTIAL
 eq "two partial comments -> delete nothing" "$(del_id "$(c 4 NONE Bot "$PARTIAL")"$'\n'"$(c 5 NONE Bot "$PARTIAL")")" ""
 eq "untrusted author partial ignored" "$(del_id "$(c 6 NONE User "$PARTIAL")")" ""
 eq "untrusted author complete ignored" "$(n_complete "$(c 6 NONE User "$PLAN")")" 0
-eq "partial carrying another FORGE marker is not deleted" "$(del_id "$(c 7 NONE Bot "$MIXED")")" ""
+eq "partial with another FORGE marker at a line start is not deleted" "$(del_id "$(c 7 NONE Bot "$MIXED")")" ""
 eq "investigator + partial comment -> only the comment id" "$(del_id "$(c 1 NONE Bot "$INVEST")"$'\n'"$(c 8 NONE Bot "$PARTIAL")")" 8
 eq "paginated concatenated arrays" "$(printf '[%s]\n[%s]' "$(c 1 NONE Bot "$INVEST")" "$(c 9 NONE Bot "$PLAN")" | jq -s "$SELECT_JQ" | jq '[.[] | select(.complete)] | length')" 1
 
@@ -46,6 +46,15 @@ ARCHC=$'<!-- FORGE:ARCHITECT -->\nplan; the builder will post <!-- FORGE:BUILDER
 eq "ARCHITECT mentioning the marker is not selected" "$(arch "$(c 10 NONE Bot "$ARCHC")" | jq length)" 0
 eq "unparsable input fails closed" "$(printf 'not json' | jq -s "$SELECT_JQ" 2>/dev/null | jq -r "$DELETE_JQ" 2>/dev/null)" ""
 
+INLINE=$'<!-- FORGE:BUILDER -->\n## Approach\nFollowed the plan in `<!-- FORGE:ARCHITECT -->` and <!-- FORGE:INVESTIGATOR --> notes.'
+CRLF=$'<!-- FORGE:BUILDER -->\r\n<!-- FORGE:ARCHITECT -->\r\nbody'
+eq "partial quoting a marker inline is picked and deleted e1_inline_picked" "$(del_id "$(c 11 NONE Bot "$INLINE")")" 11
+eq "inline quoting partial is selected as non-other e1_inline_not_other" "$(arch "$(c 11 NONE Bot "$INLINE")" | jq -r '.[0].other')" false
+eq "marker at the start of a later line is refused e2_line_start_refused" "$(arch "$(c 12 NONE Bot "$MIXED")" | jq -r '.[0].other')" true
+eq "own first-line marker never counts as other e4_own_marker_not_other" "$(arch "$(c 13 NONE Bot "$PARTIAL")" | jq -r '.[0].other')" false
+eq "two inline-quoting partials still delete nothing e3_two_partials_none" "$(del_id "$(c 11 NONE Bot "$INLINE")"$'\n'"$(c 14 NONE Bot "$INLINE")")" ""
+eq "CRLF body with a marker line is still refused e5_crlf_refused" "$(del_id "$(c 15 NONE Bot "$CRLF")")" ""
+
 # Spec drift guard: every mutating site carries this exact predicate and no unanchored selector.
 for f in commands/work-on/build/implement.md commands/work-on/build.md commands/work-on/build/validate.md; do
   SPEC="$ROOT/$f"

package/scripts/calibration.mjs

@@ -143,10 +143,13 @@ export function readForgeYaml(repoPath) {
   const configPath = join(repoPath, 'forge.yaml');
   if (!existsSync(configPath)) return null;
   try {
-    const result = spawnSync('yq', ['-r', '.project.owner + "/" + .project.repo', configPath], {
+    const result = spawnSync('yq', ['-r', '.project.owner, .project.repo', configPath], {
       encoding: 'utf8', timeout: 5000,
     });
-    if (result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+    if (result.status === 0) {
+      const [owner, name] = result.stdout.split('\n').map(l => l.trim());
+      if (owner && name && owner !== 'null' && name !== 'null') return `${owner}/${name}`;
+    }
   } catch (_) { /* ignore */ }
   return null;
 }

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