forgedock 1.35.0 → 1.37.0

package/docs/TELEMETRY.md

@@ -5,6 +5,8 @@ counts can be measured without re-reading comments with a model. GitHub is the s
 by code (never by a model) into a `FORGE:TELEMETRY` comment, and everything can be rebuilt from the GitHub API alone.
 Local files are only a cache.
 
+For a stable, versioned stream aimed at outside consumers (JSONL sink, signed webhook) see [EVENTS.md](EVENTS.md).
+
 ## Where records live
 
 - One `<!-- FORGE:TELEMETRY v1 -->` comment per issue, or per PR for review-side events (`review_panel`,
@@ -41,7 +43,7 @@ is dropped. Payload keys are `[A-Za-z0-9_]+` and cannot shadow the shared keys;
 | `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`, `trigger` (#4362: why the attempt ran, one of `plan`, `build`, `block_correction`, `contract_correction`, `precheck`, `structure`, `docs`, `enumerating`, `sequence`, `ci_unavailable`, `ci_red`, `conformance`, `review`, `merge_ci`, `timeout_restart`, `recovery`; `restart_of` = the trigger a `timeout_restart` replaced), `model`, `backend` (`cli`/`api`), `turns`, `duration_ms`, `cost_usd` (the raw reported value: a running total when the attempt resumed a CLI session), `cost_usd_delta` (#4407: this attempt's cost; consumers sum it when present, else `cost_usd`), `cost_usd_session` (the CLI session's running total), `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) |
+| `run_terminal` | the engine (`terminate()`, one per run segment) | `experiment` and `arm` (#4629, only when forge.yaml declares an `experiment:`; also on `phase_attempt`), `reason` (terminal reason), `code` (see `docs/OUTCOME-CODES.md`), `wall_ms` (this engine process, start to terminal) |
 
 The engine records carry `run` = `r_<issue>_<start epoch seconds>` (one per `forgedock run-issue` process) so `forgedock stats`
 (`docs/STATS.md`) can group the attempts of a run and tell a finished run from an unfinished one. They are the GitHub-side

package/docs/site/install.md

@@ -0,0 +1,89 @@
+# Install
+
+Everything you need to install ForgeDock and keep it up to date. For a first run, `npx forgedock demo` needs no setup beyond the requirements below.
+
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai/) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
+
+```bash
+npx forgedock # checks your environment, installs commands into ~/.claude/commands/ (available in every Claude Code session on this machine), detects your repo, and hands you a reviewed forge.yaml
+```
+
+For OpenCode, install namespaced native commands without changing your provider
+or user-owned settings. When migrating an older ForgeDock adapter, it removes
+only exact ForgeDock-managed legacy entries from `opencode.json`:
+
+```bash
+npx forgedock opencode install
+# restart OpenCode, then: /forge/work-on <issue>
+```
+
+See [OpenCode support](../OPENCODE.md) for architecture, token-loading rules,
+current parity boundaries, and lifecycle commands.
+
+**Install is always global**, to `~/.claude/commands/`. `--global` is still accepted on the command line for backward compatibility but has no effect — there's no other install location to opt out of.
+
+> **Want engine-mode dispatch?** `npx forgedock` is transient — the `forgedock` binary isn't persisted in PATH after install. `/orchestrate` and `/autopilot` use agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (`forgedock run-issue`) with its durable phase table and fail-closed review gate, run `npm install -g forgedock` instead.
+
+One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated `forge.yaml` to review — press Enter to accept. Run `npx forgedock init` any time afterward to re-generate the config only.
+
+Installing also registers a SessionStart hook, so every Claude Code session
+in a forge-managed directory starts already knowing ForgeDock runs it.
+Per-directory control: `npx forgedock enable` / `disable` / `status`.
+
+Then just open Claude Code and run `/work-on <issue>`.
+
+> **Cost:** ForgeDock is free and open-source. It orchestrates sessions on **your** Claude account — no compute resold, no per-task markup. A typical `/work-on` run on a straightforward bug costs about what a 15–20 minute manual Claude Code session does.
+
+<details>
+<summary><strong>Other install options & commands</strong></summary>
+
+**Claude Code plugin marketplace** (Claude Code v2.1.143+):
+
+```
+/plugin marketplace add RapierCraftStudios/ForgeDock
+/plugin install forgedock@forgedock
+```
+
+Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock init` to generate `forge.yaml`.
+
+**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan. `npx forgedock run` picks an execution backend automatically (`--backend auto`, the default): if the Claude Code CLI (`claude`) is installed and already authenticated (Pro/Max subscription or a CLI-managed key), it drives the command through that — **no separate `ANTHROPIC_API_KEY` required**. It never falls back to the paid Anthropic API implicitly: without a CLI it fails with `CLI_BACKEND_UNAVAILABLE` unless the owner opted in (forge.yaml `execution.agent_backend: api` plus `FORGEDOCK_ALLOW_API_BACKEND=1`; see [CONFIG.md](../CONFIG.md#execution-optional)). Force either path explicitly with `--backend cli` / `--backend api` (or `FORGEDOCK_BACKEND=cli|api`) — the API backend is what CI environments without an interactive `claude` login should use. `npx forgedock run-issue <issue>` executes the same command specs on the durable engine (event-sourced run log, leases, crash-safe resume).
+
+**Brand-new project?** `/bootstrap "<idea>"` (or `npx forgedock bootstrap "<idea>" --dry-run` to preview) turns an idea into a validated, milestone-ordered GitHub backlog that `/orchestrate` can build. See [Start a New Project with ForgeDock](start-a-new-project.md).
+
+**Explicit install command:**
+
+```bash
+npx forgedock install           # installs into ~/.claude/commands/
+npx forgedock install --global  # same thing — --global is accepted but is a no-op
+```
+
+**Maintenance:**
+
+```bash
+npx forgedock update      # relink commands + refresh the SessionStart hook
+npx forgedock enable      # turn ForgeDock on for this directory
+npx forgedock disable     # turn ForgeDock off for this directory
+npx forgedock status      # show ForgeDock's state for this directory
+npx forgedock doctor      # installation health check with fix hints
+npx forgedock report      # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
+npx forgedock uninstall   # remove commands, the hook, and tracked copies
+npx forgedock help        # show everything
+```
+
+> Running `npx forgedock` from *inside* this repo uses the local working tree. From your own project, use `npx forgedock@latest` to pin the published release.
+
+</details>
+
+<details>
+<summary><strong>A note on install location</strong></summary>
+
+ForgeDock briefly experimented with a project-scoped-by-default install mode. It was backed out after causing a "split-brain" bug (`detect` assumed project-scoped while the installer still wrote globally — [#1589](https://github.com/RapierCraftStudios/ForgeDock/issues/1589)), so every version you'd realistically install today only ever writes to `~/.claude/commands/`. `--global` is still accepted as a flag for old scripts/muscle memory, but it changes nothing.
+
+If you're carrying an older `--global` habit in scripts or CI, it's harmless to leave it — `npx forgedock --global` and `npx forgedock` do exactly the same thing.
+
+</details>
+
+**After upgrading**: run `npx forgedock labels setup` once per repo. Repos created before the `workflow:remediating` state (forge#3541) lack that label; the pipeline now creates it on demand (best-effort), but the setup command is the supported way to sync all labels.
+
+
+

package/docs/site/start-a-new-project.md

@@ -256,7 +256,7 @@ Two milestones, a spike, four build issues and one needs-human issue. `INVITES`
       ],
       "deps": [],
       "needsHuman": true,
-      "body": "## Problem\n\nCreate the Resend API key that #{{INVITES}} uses to send email.\n\n### Setup steps\n\n1. Create an API key at https://resend.com/api-keys with sending access only.\n2. Store it as the `RESEND_API_KEY` deploy secret.\n\n### Environment variables\n\n- `RESEND_API_KEY` — Resend sending key\n\n### Secret handling\n\nNever commit the key or paste it into issues. Until it exists, dev and CI use the mock mailer.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `docs/setup/resend.md` — new\n\n## Acceptance Criteria\n\n- [ ] Key stored as a deploy secret [type:manual]\n- [ ] The real mailer replaces the mock in staging [type:manual]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nNone.\n"
+      "body": "## Problem\n\ngates: preview\nowner: maintainer\n\nCreate the Resend API key that #{{INVITES}} uses to send email.\n\n### Setup steps\n\n1. Create an API key at https://resend.com/api-keys with sending access only.\n2. Store it as the `RESEND_API_KEY` deploy secret.\n\n### Environment variables\n\n- `RESEND_API_KEY` — Resend sending key\n\n### Secret handling\n\nNever commit the key or paste it into issues. Until it exists, dev and CI use the mock mailer.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `docs/setup/resend.md` — new\n\n## Acceptance Criteria\n\n- [ ] Key stored as a deploy secret [type:manual]\n- [ ] The real mailer replaces the mock in staging [type:manual]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nNone.\n"
     }
   ]
 }

package/docs/spec/label-state-machine.md

@@ -22,6 +22,12 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
 | `workflow:engine-error` | Pipeline blocked by the engine/tool itself breaking (CLI crash, missing SDK/API key, exhausted retries with no attempt ever reaching a real outcome) — not a genuine content-level judgment call | `terminate()` in `bin/engine.mjs` (also removes a stacked `workflow:remediating`, and adds `needs-human` when the run was remediating) |
 
+`needs-human:external` vs `parked:<code>` (forge#4656): bare `needs-human` conflated two states. `needs-human:external` is a real external prerequisite (credential, account, sign-off); its structured comment must name an owner and an unblock condition. `parked:<terminal-code>` (plus `remediation-queue`) is a mechanical park (`ci.red` after the last round, `conformance.*`, `review_incomplete`): the comment carries the code and the PR, the batch runner still sees the issue, and once recovery attempts run out it waits in the single `/work-on:remediate` queue instead of the human queue. Migrating a legacy `needs-human` issue: `classifyLegacyNeedsHuman` reads its last FORGE terminal annotation; an unclassifiable one defaults to `external`. A gate (hold list, settle, `/milestone ship` pre-flight) that waits on an issue the scheduler will not admit emits `GATE_DEADLOCK issue=#N gate=G age=Nm` (`bin/lean/gatewatch.mjs`) within one pass.
+
+Milestone lifecycle (forge#4657): `building -> shipped:staging -> deployed:default -> closed`, recorded as `<!-- FORGE:LIFECYCLE {json} -->` in the milestone description (`bin/lean/lifecycle.mjs`); forge.yaml `milestones.close_on` (`staging|default`, default `default`) picks where it closes, and a milestone with open issues never closes. `/milestone ship` requires every open issue to be closed or carried over with a target milestone and a class (`engineering|external|post-deploy|wont-do`); `needs-human:external`, flag/legal-gated and off-base-dependent issues are never demoted to fast lane. `pipeline-status` lists `SHIPPED_WITH_OPEN` and `EMPTY_BUT_OPEN`.
+
+`gates:` (forge#4660): a `needs-human:external` issue names what it blocks in its body, `gates: preview|staging-deploy|prod-deploy|feature-flag:<name>` (comma separated), with an `owner:` line; `Depends on #N` between prerequisites orders the digest. `scripts/readiness.mjs` turns open prerequisites into the `pipeline-status` Readiness section (per gate: prerequisites with owner and age, code milestones needed), a dependency-ordered human-action digest, and the `deploy-info` verdict: a target (preview, staging, prod) is NOT DEPLOYABLE while its gate has open prerequisites. A `feature-flag:<name>` gate stays red while open but never blocks merging flag-gated features or any deploy target.
+
 `workflow:remediating` vs `needs-human` (forge#3541): `needs-human` is reserved for genuine human decisions and external actions (an exhausted remediation bound, an unresolvable conflict, a policy gate, spend, real-environment validation). Work the pipeline fixes by itself (a pure base-sync, a red CI gate, an in-PR finding round) is marked `workflow:remediating` instead, so operators are not alerted and orchestrate does not hold DAG dependents as GATED. `work-on:remediate` accepts either label (a bare `needs-human` from an older run still works), swaps it for `workflow:in-review` on a FIXABLE run, and on every BLOCKED/UNFIXABLE exit clears `workflow:remediating` and asserts `needs-human`.
 
 `workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` only clears `needs-human` (best-effort) when the target state is `workflow:awaiting-merge` — every other forward transition leaves a pre-existing `needs-human` label untouched, preserving its sticky/terminal semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.35.0",
+  "version": "1.37.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/pool/install/install-agent.sh

@@ -72,16 +72,17 @@ log "building lane image (first run takes several minutes)"
 FD_VERSION="$(jq -r .version /opt/computeshare/package.json)"
 docker build -q -t "forgedock-lane:${FD_VERSION}" --build-arg "FORGEDOCK_VERSION=${FD_VERSION}" /opt/computeshare/pool/image >/dev/null
 
+. /opt/computeshare/pool/install/unit-hardening.sh
 cat > /etc/systemd/system/computeshare-agent.service <<EOF
 [Unit]
 Description=computeshare agent
 After=docker.service network-online.target
 Requires=docker.service
+$(unit_start_limit)
 
 [Service]
 ExecStart=/opt/node/bin/node /opt/computeshare/bin/pool/cli.mjs agent --config /etc/computeshare/agent.json
-Restart=always
-RestartSec=5
+$(unit_hardening system)
 
 [Install]
 WantedBy=multi-user.target
@@ -89,6 +90,7 @@ EOF
 systemctl daemon-reload
 systemctl enable computeshare-agent >/dev/null
 systemctl restart computeshare-agent
+unit_oom_hint forgedock-pool-agent
 
 for i in $(seq 1 20); do
   if curl -fsS "http://127.0.0.1:${PORT}/health" >/dev/null 2>&1; then

package/pool/install/install-router.sh

@@ -10,6 +10,7 @@ PORT="${ROUTER_PORT:-7710}"
 TS_IP="$(tailscale ip -4 | head -1)"
 [[ "$TS_IP" == 100.* ]] || { echo "no Tailscale IPv4 found" >&2; exit 1; }
 NODE="$(command -v node)"
+. "$REPO_ROOT/pool/install/unit-hardening.sh"
 
 mkdir -p "$CONF_DIR" && chmod 700 "$CONF_DIR"
 umask 077
@@ -37,11 +38,11 @@ cat > "$HOME/.config/systemd/user/computeshare-router.service" <<EOF
 [Unit]
 Description=computeshare router
 After=network-online.target tailscaled.service
+$(unit_start_limit)
 
 [Service]
 ExecStart=$NODE $REPO_ROOT/bin/pool/cli.mjs router --config $CONF_DIR/router.json
-Restart=always
-RestartSec=5
+$(unit_hardening user)
 
 [Install]
 WantedBy=default.target
@@ -49,6 +50,7 @@ EOF
 systemctl --user daemon-reload
 systemctl --user enable --now computeshare-router >/dev/null
 systemctl --user restart computeshare-router
+unit_oom_hint forgedock-pool-router
 loginctl enable-linger "$USER" 2>/dev/null || true
 
 # ForgeDock reads execution.token_env from the env, then the OS keychain (service forgedock, account = the name).

package/pool/install/install-schedd.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Installs `forgedock schedd` (the host scheduler daemon) as a systemd --user service with the shared OOM/restart hardening.
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+NODE="$(command -v node)"
+. "$REPO_ROOT/pool/install/unit-hardening.sh"
+
+mkdir -p "$HOME/.config/systemd/user"
+cat > "$HOME/.config/systemd/user/forgedock-schedd.service" <<UNIT
+[Unit]
+Description=forgedock schedd
+$(unit_start_limit)
+
+[Service]
+ExecStart=$NODE $REPO_ROOT/bin/forgedock.mjs schedd
+$(unit_hardening user)
+
+[Install]
+WantedBy=default.target
+UNIT
+systemctl --user daemon-reload
+systemctl --user enable --now forgedock-schedd >/dev/null
+systemctl --user restart forgedock-schedd
+unit_oom_hint forgedock-schedd
+loginctl enable-linger "$USER" 2>/dev/null || true
+echo "[forgedock] schedd unit installed"

package/pool/install/unit-hardening.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Shared [Service] hardening for the long-lived ForgeDock units (router, agent, schedd). Source it; it defines functions only.
+# A kill of these drops every in-flight lane, so they get the lowest OOM score the manager allows and survive repeated SIGTERMs.
+
+# unit_oom_score_adj user|system: root may go negative; an unprivileged user manager cannot go below its own value.
+unit_oom_score_adj() {
+  if [ "$1" = system ]; then echo -500; return; fi
+  local pid v
+  pid="$(ps -o pid= -C systemd -U "$(id -u)" 2>/dev/null | head -1 | tr -d ' ')"
+  v="$(cat "/proc/${pid:-self}/oom_score_adj" 2>/dev/null || echo 0)"
+  echo "${v:-0}"
+}
+
+# unit_hardening user|system: the [Service] lines (no section header), for use inside a unit heredoc.
+unit_hardening() {
+  printf 'OOMScoreAdjust=%s\nRestart=always\nRestartSec=5\n' "$(unit_oom_score_adj "${1:-user}")"
+}
+
+# unit_start_limit: the [Unit] line that disables the start rate limit. systemd honours StartLimitIntervalSec only in [Unit], never in [Service].
+unit_start_limit() {
+  printf 'StartLimitIntervalSec=0\n'
+}
+
+# unit_oom_hint <process title>: one line when a userspace OOM killer runs. Never edits any OOM config.
+unit_oom_hint() {
+  if pgrep -x earlyoom >/dev/null 2>&1; then
+    echo "[forgedock] earlyoom is running: exempt this service by name with: --avoid '(^|/)$1\$' (earlyoom -h)"
+  elif pgrep -x systemd-oomd >/dev/null 2>&1; then
+    echo "[forgedock] systemd-oomd is running: add ManagedOOMPreference=omit to the unit via a drop-in to exempt $1"
+  fi
+  return 0
+}

package/scripts/acceptance-red-green.sh

@@ -12,7 +12,8 @@
 #   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)
+#   UNRUNNABLE  could not execute (timeout 124, not executable 126/127, worktree/overlay/classifier failure, or head failed
+#               only on a missing host module/command such as `No module named pytest`; forge#4655)
 #   SKIPPED     base was not run because head did not PASS (never a missing file: head's new test files are overlaid)
 # 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.
@@ -54,7 +55,23 @@ run_in() {
   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
+  case "$cls" in FAILED|RAN|RAN_NOTHING) ;; *) echo UNRUNNABLE; return ;; esac
+  # forge#4655: a head run that failed only because the host lacks an interpreter module or command (No module named
+  # pytest, X: command not found) is the environment, not the change: UNRUNNABLE. A module the repo itself tracks stays FAILED.
+  if [ "$cls" = "FAILED" ] && [ "$dir" = "$REPO" ] && host_missing "$out"; then echo UNRUNNABLE; return; fi
+  echo "$cls"
+}
+
+# host_missing <output_file>: true when the output names a missing third-party python module or a missing command
+host_missing() {
+  local f="$1" name
+  name=$(sed -n "s/.*No module named '\{0,1\}\([A-Za-z0-9_-]\{1,\}\).*/\1/p" "$f" | head -1)
+  if [ -n "$name" ]; then
+    git -C "$REPO" ls-files 2>/dev/null | tr '/' '\n' | grep -qxE "$name(\.py)?" && return 1
+    return 0
+  fi
+  name=$(sed -n 's/.*[ :]\([A-Za-z0-9_.-][A-Za-z0-9_.-]*\): command not found.*/\1/p' "$f" | head -1)
+  [ -n "$name" ]
 }
 
 HEAD_RES=$(run_in "$REPO")

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

@@ -38,6 +38,8 @@ mkdir -p "$R2/tests"; printf 'echo "1 passed"\n' > "$R2/tests/t.sh"; git -C "$R2
 check "passes on base" "BASE=RAN HEAD=RAN" "$R2" "bash tests/t.sh"
 
 # 3. head fails: base is not run
+check "head missing host module is UNRUNNABLE, not a failure (#4655)" "BASE=SKIPPED HEAD=UNRUNNABLE" "$R1" "echo \"/usr/bin/python3: No module named 'pytest_nonexistent_x'\" >&2; exit 1"
+check "head unquoted No module named pytest is UNRUNNABLE (#4655)" "BASE=SKIPPED HEAD=UNRUNNABLE" "$R1" "echo '/usr/bin/python3: No module named pytest' >&2; exit 1"
 check "head failure skips base" "BASE=SKIPPED HEAD=FAILED" "$R1" "bash app.sh; exit 1"
 
 # 4. RAN_NOTHING on head

package/scripts/bench-lightlane.mjs

@@ -31,6 +31,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { detectApiShape } from "../bin/lean/apishape.mjs";
+import { benchRecord } from "../bin/experiment.mjs";
 
 export const ARMS = ["light", "full", "control"];
 export const TARGETS = Object.freeze({ cost_vs_control: 1.2, wall_vs_model: 1.3 });
@@ -225,7 +226,7 @@ export function aggregate(rows) {
     false_fix_le_control: t(L.n && C.n ? L.false_fix_rate <= C.false_fix_rate : null, L.false_fix_rate, C.false_fix_rate),
     zero_undetected_api_shape: t(L.n ? L.undetected_api_shape === 0 : null, L.undetected_api_shape, 0),
   };
-  return { arms, light_eligible: { ...le, control_cost_usd: ce.cost_usd.sum, ids: [...eligIds].sort() }, targets };
+  return { arms, light_eligible: { ...le, control_cost_usd: ce.cost_usd.sum, ids: [...eligIds].sort() }, targets, record: benchRecord({ source: "bench-lightlane", arms, targets }) }; // #4629
 }
 
 /** JSONL (or a JSON array) -> rows. */

package/scripts/bootstrap-create.mjs

@@ -218,7 +218,8 @@ export function createBacklog(plan, { io, repo, config = {}, base }) {
 
   // Labels: create only the missing ones (never overwrite an existing label's colour or description).
   const haveLabels = new Set((json(["label", "list", "-R", repo, "--limit", "1000", "--json", "name"]) ?? []).map((l) => l.name));
-  const wanted = new Set(plan.issues.flatMap((it) => [...(it.labels ?? []), priorityLabel(it)]).filter(Boolean));
+  const issueLabels = (it) => [...(it.labels ?? []), priorityLabel(it), ...(isNeedsHuman(it) ? ["needs-human:external"] : [])].filter(Boolean); // #4660
+  const wanted = new Set(plan.issues.flatMap(issueLabels));
   for (const l of wanted) if (!haveLabels.has(l)) gh(["label", "create", l, "-R", repo]);
 
   // Milestones in build order, each with its lane branch.
@@ -253,7 +254,7 @@ export function createBacklog(plan, { io, repo, config = {}, base }) {
       return;
     }
     const args = ["issue", "create", "-R", repo, "--title", it.title, "--body-file", "-", "--milestone", milestoneTitle.get(it.milestone)];
-    for (const l of [...(it.labels ?? []), priorityLabel(it)].filter(Boolean)) args.push("--label", l);
+    for (const l of new Set(issueLabels(it))) args.push("--label", l);
     const body = finalBody(it);
     const out = gh(args, body);
     const number = parseIssueNumber(out);

package/scripts/bootstrap-validate.mjs

@@ -19,6 +19,8 @@
  * missing-section, missing-type-tag, missing-parent, missing-labels, unknown-label, code-depends-on-needs-human,
  * missing-design-spec (a `ui` issue lacks a design-spec item), hero-not-routed (a `hero` issue never names `/design`),
  * missing-needs-human-section (a needs-human issue lacks setup steps, env var names or secret handling) (#4176).
+ * Warns (never fails; exit stays 0): deploy-last (#4665: every milestone holding deploy workflows comes after the feature
+ * milestones, so nothing can be previewed or deployed until they all ship).
  * `Depends on` lines are read with the engine's own parser (bin/engine/phases.mjs parseDependsOn) after placeholder
  * resolution, so the plan and engine admission agree on what blocks what.
  *
@@ -35,8 +37,10 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseDependsOn } from "../bin/engine/phases.mjs";
+import { parseGates } from "./readiness.mjs";
 
 const NEEDS_HUMAN_LABEL = "needs-human";
+const EXTERNAL_LABEL = "needs-human:external"; // #4660: external prerequisite; its `gates:` line names what it blocks
 const TYPE_TAG_RE = /\[type:(?:api|unit|e2e|manual)\]/;
 const CHECKBOX_RE = /^[ \t]*[-*+][ \t]+\[[ xX]\]/;
 const PLACEHOLDER_RE = /#\{\{([^{}]*)\}\}/g;
@@ -66,13 +70,17 @@ const NEEDS_HUMAN_PARTS = [
   ["env var name (e.g. `API_KEY`)", /`[A-Z][A-Z0-9]*_[A-Z0-9_]+`/],
 ];
 
+// #4665: an issue holds deploy work when its title or body names a deploy workflow or a staging environment definition.
+const DEPLOY_RE = /\.github\/workflows\/[^\s`'")]*deploy|\bdeploy(?:ment)? workflow\b|\bstaging environment\b/i;
+const isDeployIssue = (it) => DEPLOY_RE.test(`${it?.title ?? ""}\n${it?.body ?? ""}`);
+
 const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const isNonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
 const normHeading = (h) => h.replace(/\([^)]*\)\s*$/, "").trim().toLowerCase();
 
 /** True when the issue is a needs-human issue (credential, account or external input). */
 export function isNeedsHuman(issue) {
-  return issue?.needsHuman === true || (Array.isArray(issue?.labels) && issue.labels.includes(NEEDS_HUMAN_LABEL));
+  return issue?.needsHuman === true || (Array.isArray(issue?.labels) && (issue.labels.includes(NEEDS_HUMAN_LABEL) || issue.labels.includes(EXTERNAL_LABEL)));
 }
 
 /**
@@ -175,7 +183,7 @@ function findCycles(issues, byKey) {
 
 /**
  * Validate a backlog plan. Never throws on bad input; structural problems come back as `invalid-plan` errors.
- * @returns {{ ok: boolean, errors: Array<{ issue: string|null, code: string, message: string }> }}
+ * @returns {{ ok: boolean, errors: Array<{ issue: string|null, code: string, message: string }>, warnings?: Array<{ issue: string|null, code: string, message: string }> }}
  */
 export function validatePlan(plan) {
   const structural = checkStructure(plan);
@@ -275,12 +283,30 @@ export function validatePlan(plan) {
     if (isNeedsHuman(it)) {
       const lacking = NEEDS_HUMAN_PARTS.filter(([, re]) => !re.test(it.body)).map(([name]) => name);
       if (lacking.length) err(it.key, "missing-needs-human-section", `needs-human issue lacks: ${lacking.join(", ")}`);
+      if (!parseGates(it.body).length) {
+        err(it.key, "missing-gates", "needs-human issue has no valid `gates:` line (preview|staging-deploy|prod-deploy|feature-flag:<name>)");
+      }
     }
   }
-  return { ok: errors.length === 0, errors };
+  return { ok: errors.length === 0, errors, warnings: deployWarnings(issues, milestones) };
+}
+
+/** #4665: `deploy-last` when deploy work exists but none of it sits in milestones 1-2 (needs >= 3 milestones). */
+function deployWarnings(issues, milestones) {
+  const index = new Map(milestones.map((m, i) => [m.key, i]));
+  const deploy = issues.filter(isDeployIssue);
+  if (!deploy.length || milestones.length < 3) return [];
+  const at = deploy.map((it) => index.get(it.milestone));
+  if (at.some((i) => i <= 1)) return [];
+  const where = [...new Set(at.map((i) => milestones[i]?.key).filter(Boolean))].join(", ");
+  return [{
+    issue: deploy[0].key, code: "deploy-last",
+    message: `deploy workflows are only in ${where ? `milestone ${where}` : "later milestones"}, none in the first two; put a thin deployable slice (CI deploy workflow, staging environment, seed) in the first or second milestone`,
+  }];
 }
 
 /** One `<KEY>: [code] message` line per error; plan-level errors use `(plan)`. */
+export const formatWarnings = (warnings) => formatErrors(warnings);
 export function formatErrors(errors) {
   return errors.map((e) => `${e.issue ?? "(plan)"}: [${e.code}] ${e.message}`).join("\n");
 }
@@ -305,7 +331,8 @@ function main(argv) {
     process.stderr.write(`bootstrap-validate: invalid JSON: ${e.message}\n`);
     return 2;
   }
-  const { ok, errors } = validatePlan(plan);
+  const { ok, errors, warnings = [] } = validatePlan(plan);
+  if (warnings.length) process.stderr.write(formatErrors(warnings).replace(/^/gm, "warning: ") + "\n");
   if (!ok) {
     process.stderr.write(formatErrors(errors) + "\n");
     process.stderr.write(`bootstrap-validate: ${errors.length} error(s)\n`);

package/scripts/eval-gate-scorecard.mjs

@@ -30,6 +30,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { benchRecord } from "../bin/experiment.mjs";
 
 /** Fields the fresh scorecard must have (matches eval-scorecard-aggregator.mjs's output). */
 export const REQUIRED_FIELDS = [
@@ -137,6 +138,12 @@ export function evaluateGate(
     fresh_run_id: fresh.run_id ?? null,
     baseline_run_id: baseline.run_id ?? null,
     reason,
+    // #4629: the shared result record; the target is null (never a pass) when the rate assertion was skipped
+    record: benchRecord({
+      source: "eval-gate",
+      arms: { baseline: { success_rate_pct: baseline.success_rate_pct }, fresh: { n: freshIssuesRun, success_rate_pct: fresh.success_rate_pct } },
+      targets: { success_rate_within_threshold: { pass: rateAssertionSkipped ? null : pass, value: dropPp, limit: thresholdPp } },
+    }),
   };
 }