forgedock 1.37.0 → 1.38.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/bin/engine/outcome-codes.mjs +12 -3
  2. package/bin/engine/telemetry-seam.mjs +5 -0
  3. package/bin/engine-cli.mjs +97 -18
  4. package/bin/forgedock.mjs +13 -2
  5. package/bin/lean/activation.mjs +76 -0
  6. package/bin/lean/activation.test.mjs +75 -0
  7. package/bin/lean/admission.mjs +17 -1
  8. package/bin/lean/batch.mjs +51 -21
  9. package/bin/lean/batch.test.mjs +95 -5
  10. package/bin/lean/conformance.mjs +53 -4
  11. package/bin/lean/conformance.test.mjs +24 -1
  12. package/bin/lean/decision-engine.mjs +217 -0
  13. package/bin/lean/decision-engine.test.mjs +159 -0
  14. package/bin/lean/effects.mjs +39 -13
  15. package/bin/lean/execution.mjs +74 -5
  16. package/bin/lean/execution.test.mjs +64 -1
  17. package/bin/lean/explore.test.mjs +1 -1
  18. package/bin/lean/guards.mjs +3 -2
  19. package/bin/lean/guards.test.mjs +24 -3
  20. package/bin/lean/heavy.mjs +15 -2
  21. package/bin/lean/heavy.test.mjs +31 -2
  22. package/bin/lean/issuewatch-release.mjs +245 -0
  23. package/bin/lean/issuewatch-release.test.mjs +244 -0
  24. package/bin/lean/issuewatch.mjs +386 -0
  25. package/bin/lean/issuewatch.test.mjs +280 -0
  26. package/bin/lean/lane.mjs +4 -3
  27. package/bin/lean/lane.test.mjs +12 -0
  28. package/bin/lean/lean.mjs +103 -16
  29. package/bin/lean/lean.test.mjs +127 -5
  30. package/bin/lean/needs-human-premise.mjs +177 -0
  31. package/bin/lean/needs-human-premise.test.mjs +136 -0
  32. package/bin/lean/orchestrate-blocked.test.mjs +71 -0
  33. package/bin/lean/orchestrate.mjs +93 -21
  34. package/bin/lean/postdeploy-check.mjs +88 -2
  35. package/bin/lean/postdeploy-check.test.mjs +78 -0
  36. package/bin/lean/prodwatch-sources.mjs +165 -0
  37. package/bin/lean/prodwatch-sources.test.mjs +108 -0
  38. package/bin/lean/prompts.mjs +9 -3
  39. package/bin/lean/recovery.test.mjs +14 -0
  40. package/bin/lean/relay.mjs +182 -0
  41. package/bin/lean/relay.test.mjs +214 -0
  42. package/bin/lean/sandbox-provider.contract.test.mjs +13 -1
  43. package/bin/lean/sandbox-remote.mjs +53 -9
  44. package/bin/lean/sched.test.mjs +30 -0
  45. package/bin/lean/schedd-health.mjs +69 -0
  46. package/bin/lean/schedd-health.test.mjs +51 -0
  47. package/bin/lean/schedd.mjs +29 -12
  48. package/bin/lean/schedd.test.mjs +40 -4
  49. package/bin/lean/sequence.mjs +57 -24
  50. package/bin/lean/sequence.test.mjs +71 -0
  51. package/bin/pool/agent.mjs +15 -1
  52. package/bin/pool/router.mjs +43 -5
  53. package/bin/runner.mjs +18 -1
  54. package/commands/deploy-pr.md +12 -0
  55. package/commands/forgedock-init.md +1 -0
  56. package/commands/orchestrate/phase-4-execution.md +1 -0
  57. package/commands/orchestrate.md +1 -0
  58. package/commands/review-pr.md +17 -13
  59. package/docs/CONFIG.md +73 -2
  60. package/docs/DECISIONS.md +32 -0
  61. package/docs/ISSUE-WATCH.md +95 -0
  62. package/docs/NORTHSTAR-TEMPLATE.md +21 -0
  63. package/docs/OUTCOME-CODES.md +2 -1
  64. package/docs/TELEMETRY.md +7 -0
  65. package/package.json +1 -2
  66. package/pool/README.md +1 -1
  67. package/pool/image/Dockerfile +2 -1
  68. package/pool/image/cs-relay +31 -0
  69. package/pool/image/entrypoint.sh +10 -0
  70. package/pool/install/install-schedd.sh +22 -0
  71. package/pool/install/unit-hardening.sh +6 -0
  72. package/scripts/postdeploy-rollup-link.sh +40 -0
  73. package/scripts/postdeploy-rollup-link.test.sh +46 -0
  74. package/scripts/refresh-bot-token.sh +122 -0
  75. package/scripts/review-delta.sh +14 -4
  76. package/scripts/review-delta.test.sh +21 -0
  77. package/scripts/review-finalize.sh +69 -25
  78. package/scripts/review-finalize.test.sh +32 -0
  79. package/scripts/review-pr-arguments.test.sh +10 -0
  80. package/scripts/review-pr-changed-verification.test.sh +54 -0
  81. package/scripts/review-pr-delta-wiring.test.sh +1 -1
package/bin/runner.mjs CHANGED
@@ -1537,6 +1537,19 @@ function toFiniteUsageNumber(value) {
1537
1537
  */
1538
1538
  export const CLI_ARGV_PROMPT_MAX_BYTES = 64 * 1024;
1539
1539
 
1540
+ /**
1541
+ * forge#4763: Windows CreateProcess caps the WHOLE command line at 32,767 UTF-16 chars (8,191 through a cmd.exe
1542
+ * shim), so on win32 the prompt plus every other argument must stay under this conservative bound.
1543
+ */
1544
+ export const CLI_ARGV_PROMPT_MAX_BYTES_WIN32 = 16 * 1024;
1545
+
1546
+ /** forge#4763: true when the prompt must go over stdin: prompt bytes plus the other argv bytes exceed the platform bound. */
1547
+ export function promptGoesViaStdin(prompt, otherArgs = [], platform = process.platform) {
1548
+ const max = platform === "win32" ? CLI_ARGV_PROMPT_MAX_BYTES_WIN32 : CLI_ARGV_PROMPT_MAX_BYTES;
1549
+ const rest = platform === "win32" ? otherArgs.reduce((n, a) => n + Buffer.byteLength(String(a), "utf-8") + 1, 0) : 0;
1550
+ return Buffer.byteLength(String(prompt ?? ""), "utf-8") + rest > max;
1551
+ }
1552
+
1540
1553
  /** forge#4129: spawn errnos that fail the same way on every rerun (argv too big, binary missing or not executable). */
1541
1554
  export const DETERMINISTIC_SPAWN_ERRNOS = Object.freeze(["E2BIG", "ENOENT", "EACCES", "ENOEXEC", "ENAMETOOLONG"]);
1542
1555
 
@@ -1594,7 +1607,11 @@ export function runCliBackend({
1594
1607
  // directory gets cleaned up.
1595
1608
  let tmpDir = null;
1596
1609
  // forge#4129: a prompt over the argv bound is sent on stdin instead of as the `--print` argument.
1597
- const promptViaStdin = Buffer.byteLength(String(userMessage ?? ""), "utf-8") > CLI_ARGV_PROMPT_MAX_BYTES;
1610
+ // forge#4763: the other argv (flags, system-prompt file path) counts toward the Windows command-line cap.
1611
+ const promptViaStdin = promptGoesViaStdin(userMessage, [
1612
+ "--print", "--output-format", "json", ...optionalFlags, "--dangerously-skip-permissions",
1613
+ ...(systemPrompt ? ["--append-system-prompt-file", join(os.tmpdir(), "forgedock-cli-system-prompt-XXXXXX", "system-prompt.txt")] : []),
1614
+ ]);
1598
1615
  const promptArgs = promptViaStdin ? [] : [userMessage];
1599
1616
  let cliArgs = [
1600
1617
  "--print",
@@ -293,6 +293,18 @@ ${ISSUE_REFS:-None}
293
293
  ${CLOSES_LINE}
294
294
  **Source**: \`${SOURCE}\`
295
295
  **Target**: \`${PR_TARGET}\`"
296
+
297
+ # #4727: a staging -> default deploy PR links the release lane's post-deploy rollup (deterministic; empty = no link, never blocks)
298
+ if [ "$SOURCE" = "$STAGING_BRANCH" ] && [ "$PR_TARGET" = "$DEFAULT_BRANCH" ]; then
299
+ _l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
300
+ ROLLUP_LINK=""
301
+ for _c in '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l"; do
302
+ case "$_c" in /*) [ -z "$ROLLUP_LINK" ] && [ -f "$_c/scripts/postdeploy-rollup-link.sh" ] && ROLLUP_LINK=$(bash "$_c/scripts/postdeploy-rollup-link.sh" --repo "$GH_REPO" 2>/dev/null || true) ;; esac
303
+ done
304
+ [ -n "$ROLLUP_LINK" ] && PR_BODY="${PR_BODY}
305
+
306
+ ${ROLLUP_LINK}"
307
+ fi
296
308
  fi
297
309
  ```
298
310
 
@@ -442,6 +442,7 @@ Whichever path is taken, Phase 5F makes sure the board has every ForgeDock field
442
442
  - `DETECTED_HEALTH_PATH` is set (from Phase 2E) AND a base domain is known → compose full `HEALTH_ENDPOINT` URL directly. Do not ask.
443
443
  - Container name prefixes detected in Phase 2C → use them directly as `internal_service_patterns`. Do not ask for confirmation.
444
444
  - Nothing detected for health endpoint AND nothing detected for containers AND `INTERACTIVE=false` → skip this section silently.
445
+ - `vitest` in `package.json` or `pytest` in `pyproject.toml`/`requirements*.txt` → suggest (never write silently; ask when `INTERACTIVE=true`, else print it as a commented hint) the changed-file commands `verification.commands.typescript.test_changed: "vitest related $FORGE_CHANGED_FILES --run"` and `verification.commands.python.test_changed`, plus `typescript.typecheck_changed` for large TypeScript repos (`/review-pr` Phase 2 exports `$FORGE_CHANGED_FILES`; see `docs/CONFIG.md`).
445
446
  - `INTERACTIVE=true` → show detected values and ask for confirmation:
446
447
  ```
447
448
  Detected potential health endpoint path: {DETECTED_PATH}
@@ -2269,6 +2269,7 @@ done
2269
2269
  echo "#{NUMBER}: engine fallback claim lost or could not be verified — no duplicate Agent dispatch."
2270
2270
  fi
2271
2271
  else
2272
+ [ "${DRY_RUN:-}" = "true" ] || gh issue edit "{NUMBER}" -R {GH_REPO} --add-label "workflow:engine-error" 2>/dev/null || true # idempotent: keep the partial-work run visible to doctor I10
2272
2273
  echo "#{NUMBER}: engine-error with non-empty committed state (partial work exists) — NOT auto-falling back. Resume from the last committed phase with: forgedock run-issue {NUMBER} --retry --lane {PR_BASE} (a session-limit hit during a phase ends here; --retry reopens only engine-error runs)."
2273
2274
  fi
2274
2275
  ```
@@ -114,6 +114,7 @@ remaining maintenance once no feature is pending; otherwise the rest ends `held
114
114
  priority, slots are shared across repos by weight (`forgedock sched weight <owner/repo> N`, default equal). Logical
115
115
  edges you found in step 2.4 must be written to the dependent issue as a `Depends on #X` line before launching. The
116
116
  last lines are the report table.
117
+ Issue-level readiness (#4773): a trusted author's `Blocked by #N` / `Depends on #N` line is a DAG edge, and `--add` prints the edges it created; an issue labelled `blocked` (`orchestration.blocked_label`) is admitted but not dispatched until the label is removed.
117
118
  - **Agent lane (only when the `forgedock` CLI is unavailable).** Spawn one background agent per issue.
118
119
  The prompt is:
119
120
 
@@ -110,7 +110,7 @@ case "$PR_REF" in
110
110
  "") ;;
111
111
  *) PR_NUMBER="$PR_REF" ;;
112
112
  esac
113
- AUTO_MERGE=false; THOROUGH=false
113
+ AUTO_MERGE=false; THOROUGH=false; MANUAL_PR=false; OWNER_REQUESTED=false
114
114
  MERGE_ISSUE=""; MERGE_BASE=""; MERGE_WORKTREE=""; MERGE_GH_FLAG=""; REPO_FLAG=""; REPO=""
115
115
  arg_i=1
116
116
  case "$PR_REF" in -*) PR_NUMBER=""; arg_i=0 ;; esac # leading flag, no PR ref
@@ -119,6 +119,8 @@ while [ "$arg_i" -lt "${#ARG_TOKENS[@]}" ]; do
119
119
  case "$arg_t" in
120
120
  --auto-merge) AUTO_MERGE=true ;; # flag parse only, no side effect <!-- allowlist:check-command-side-effects -->
121
121
  --thorough) THOROUGH=true ;;
122
+ --manual-pr) MANUAL_PR=true ;; # flag parse only, no side effect <!-- allowlist:check-command-side-effects -->
123
+ --owner-requested) OWNER_REQUESTED=true ;; # flag parse only <!-- allowlist:check-command-side-effects -->
122
124
  --issue|--base|--worktree)
123
125
  # A value that is empty or starts with "-" is another flag: treat the value as missing, do not consume it
124
126
  arg_v="${ARG_TOKENS[$((arg_i + 1))]:-}"
@@ -172,7 +174,7 @@ fi
172
174
 
173
175
  **Argument injection hardening** <!-- Added: forge#3466 -->: the loader substitutes `$ARGUMENTS` textually, so the block reads it from a quoted heredoc and rejects any string containing a quote, backtick, dollar sign, backslash, newline or tab (it parses nothing and binds `PR_NUMBER`, `REPO`, `MERGE_*` empty with `AUTO_MERGE=false`; a run with no PR number stops in Phase -1). The executor MUST replace the `NONCE` in the `FORGE_ARGS_EOF_NONCE` placeholder with a fresh random hex string first, so a caller cannot pre-compute the delimiter. Callers pass `--gh-flag -R owner/repo` unquoted.
174
176
 
175
- **`--auto-merge` requires `--issue`** <!-- Added: forge#3102, forge#3124 -->: the Phase 8 phase-trail gate verifies the linked issue. Never infer `MERGE_ISSUE` from the PR (the closing reference and the branch suffix are author-controlled): with `AUTO_MERGE=true` and no `MERGE_ISSUE`, Phase 8 does not merge and returns `REVIEW_RESULT: status: BLOCKED`, blocker "auto-merge requires --issue".
177
+ **`--auto-merge` requires `--issue` (or `--manual-pr`)** <!-- Added: forge#3102, forge#3124 -->: the Phase 8 phase-trail gate verifies the linked issue. Never infer `MERGE_ISSUE` from the PR (the closing reference and the branch suffix are author-controlled): with `AUTO_MERGE=true` and no `MERGE_ISSUE`, Phase 8 does not merge and returns `REVIEW_RESULT: status: BLOCKED`, blocker "auto-merge requires --issue". **`--manual-pr`** <!-- Added: forge#4770 -->, for a hand-built PR the owner asked to merge, skips only the phase-trail preflight (recorded as `FORGE:PHASE_TRAIL_SKIPPED`); every other gate runs. `merge-gate` refuses it when `--issue` is a pipeline issue, or when the PR closes one unless `--owner-requested` (the owner's explicit instruction). `/work-on` and `/orchestrate` never pass either flag.
176
178
 
177
179
  ### Thoroughness Flag
178
180
 
@@ -305,6 +307,7 @@ git worktree add --detach "$REVIEW_WT" "$REVIEW_SHA" 2>/dev/null
305
307
  CFG="${FORGE_CONFIG:-$MAIN_ROOT/forge.yaml}"
306
308
  vcmd() { yq ".verification.commands.${1}.${2} // \"\"" "$CFG" 2>/dev/null || echo ''; }
307
309
  CHANGED=$(jq -r '.full_files[]?' "$CTX" 2>/dev/null); [ -n "$CHANGED" ] || CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only) # Phase 1 list survives an API 406 (forge#4154)
310
+ export FORGE_CHANGED_FILES=$(printf '%s\n' "$CHANGED" | while IFS= read -r f; do [ -f "$f" ] && printf '%s\n' "$f"; done) # existing changed files, newline-separated, for *_changed commands (env var, never spliced into the eval'd string)
308
311
  [ -d "$MAIN_ROOT/node_modules" ] && [ ! -e node_modules ] && ln -s "$MAIN_ROOT/node_modules" node_modules
309
312
  run_step() { # run_step <lang> <step> <tail-lines>: prints the exit code; empty command = SKIPPED
310
313
  local c; c=$(vcmd "${1}" "${2}")
@@ -320,24 +323,25 @@ if printf '%s\n' "$CHANGED" | grep -qE '\.(tsx?|jsx?)$'; then
320
323
  if [ ! -d node_modules ]; then
321
324
  echo "SKIPPED — deps unavailable in per-PR worktree (no node_modules in main checkout); typecheck/build not run, not a type-error finding"
322
325
  else
323
- run_step typescript lint 30; run_step typescript typecheck 50; TSC_RC=$?
326
+ run_step typescript lint 30; run_step typescript typecheck 50; TSC_RC=$?; run_step typescript typecheck_changed 50
324
327
  if [ "$REQUIRES_FULL_BUILD" = "true" ] || [ "$TSC_RC" -eq 0 ]; then run_step typescript build 30; fi
325
328
  fi
326
329
  fi
327
330
  CLASSIFIER=$(forge_resolve flaky-quarantine.sh) # install roots only: the PR under review is author-controlled
328
- for L in python typescript go rust; do
329
- TEST_CMD=$(vcmd "$L" test); [ -n "$TEST_CMD" ] || continue
330
- echo "=== Running tests (${L}): ${TEST_CMD} ==="; eval "$TEST_CMD" 2>&1 | tail -30; TEST_EXIT=${PIPESTATUS[0]}
331
+ for L in python typescript go rust; do for T in test test_changed; do
332
+ TEST_CMD=$(vcmd "$L" "$T"); [ -n "$TEST_CMD" ] || continue
333
+ echo "=== Running tests (${L}.${T}): ${TEST_CMD} ==="; eval "$TEST_CMD" 2>&1 | tail -30; TEST_EXIT=${PIPESTATUS[0]}; echo "EXIT ${L}.${T}=${TEST_EXIT}"
331
334
  [ "$TEST_EXIT" -eq 0 ] && continue
332
335
  if [ -n "$CLASSIFIER" ]; then
333
336
  CL_RESULT=$(bash "$CLASSIFIER" --test "$TEST_CMD" --base "$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main)" --retries 3 2>&1); echo "$CL_RESULT"
334
337
  CL=$(printf '%s\n' "$CL_RESULT" | sed -n 's/^CLASSIFICATION:[[:space:]]*\([A-Z_]*\).*/\1/p' | head -n 1)
335
338
  else CL=""; fi
336
- case "$CL" in PRE_BROKEN|FLAKY) echo "ADVISORY (not blocking): ${L} tests classified ${CL}, quarantined" ;; *) echo "BLOCKING: ${L} tests failed (exit ${TEST_EXIT}), classified REAL" ;; esac
337
- done
338
- if [ -z "$(vcmd python test)" ] && [ -z "$(vcmd typescript test)" ]; then echo "SKIPPED — no test commands configured in verification.commands"; fi
339
+ case "$CL" in PRE_BROKEN|FLAKY) echo "ADVISORY (not blocking): ${L} tests (${T}) classified ${CL}, quarantined" ;; *) echo "BLOCKING: ${L} tests (${T}) failed (exit ${TEST_EXIT}), classified REAL" ;; esac
340
+ done; done
341
+ if [ -z "$(vcmd python test)$(vcmd typescript test)$(vcmd python test_changed)$(vcmd typescript test_changed)" ]; then echo "SKIPPED — no test commands configured in verification.commands"; fi
339
342
  ```
340
343
 
344
+ - Optional changed-file steps `typescript.typecheck_changed`, `typescript.test_changed`, `python.test_changed` read `$FORGE_CHANGED_FILES` and count as Phase 2 evidence like their full-repo twins (a non-zero `EXIT typescript.typecheck_changed` blocks; `test_changed` follows the REAL/ADVISORY rule below); they keep a large repo from SKIPPED.
341
345
  - `EXIT typescript.typecheck` / `EXIT typescript.build` non-zero is **CONFIRMED blocking** (typecheck alone misses SSG/prerender failures, so Phase 1 blocks a full-build lane with no `typescript.build`). `BLOCKING: ... REAL` tests and `EXIT python.format` non-zero on a full-build lane block; `ADVISORY` (pre-broken or flaky per `.forgedock/quarantine.jsonl`) never does; other lint/format output is judged per finding.
342
346
  - **2G**: when `pyproject.toml` or `package.json` is in the file list, read the added dependency lines in the PR diff and flag new, unpinned or unexpected ones. **2J** (informational): when `CONTRACT_ISSUE` is set, compare the file list with the Deliverables of its trusted FORGE:CONTRACT (`scripts/check-contract-scope.sh list`); flag 5 or more unexplained uncontracted non-doc files in the summary.
343
347
 
@@ -668,7 +672,7 @@ A standalone issue per LOW/POSSIBLE note makes the cascade amplify (each merged
668
672
  - **Review-finding lineage** (`MERGE_ISSUE` carries `review-finding`: this PR fixes a finding): only MEDIUM findings that are CONFIRMED, or LIKELY and safety-exempt, become issues; the rest are NOTEs. A MEDIUM tagged `**Fix efficacy**: fails|regresses` (the linked issue is not fixed) is never damped.
669
673
  - **Cross-head re-flag** (`NOTE reflag-*`): a finding an earlier head's trusted review or `FORGE:NOTE_DISPOSITION` already covered is not filed again; never for HIGH/CRITICAL or rows whose linked issue is closed.
670
674
  - **Per-review cap**: at most `review.max_filed_findings` ISSUEs (default 2; 1 under lineage; `0` valid), ranked by severity, confidence, safety domain; the overflow is `NOTE capped` (listed, never filed or dropped). HIGH/CRITICAL are never capped and still block via §7B.
671
- - **Contract scope**: a finding under a verified `deferred → #N` item (verified = open non-PR issue by a trusted author with the `FORGE:DEFERRED_FROM` marker and an exact checklist line `- [ ] \`path\`` for that path, never a body substring) of the trusted FORGE:CONTRACT (`scripts/check-contract-scope.sh list`) is `NOTE contract-deferred #N` (commented there, not filed; counted only after #N is still OPEN and the comment succeeded, otherwise the finding takes the disposition it would have had absent the contract, normally filed, a LOW/POSSIBLE one stays a NOTE), under `accepted-risk` it is `NOTE contract-accepted-risk`; never for HIGH/CRITICAL, `not-affected`, safety-exempt or this PR's own files, nor on missing, untrusted or closed contract input.
675
+ - **Contract scope** (re-read the trusted FORGE:CONTRACT): a finding under a verified `deferred → #N` item (verified = open non-PR issue by a trusted author with the `FORGE:DEFERRED_FROM` marker and an exact checklist line `- [ ] \`path\`` for that path, never a body substring) of the trusted FORGE:CONTRACT (`scripts/check-contract-scope.sh list`) is `NOTE contract-deferred #N` (commented there, not filed; counted only after #N is still OPEN and the comment succeeded, otherwise the finding takes the disposition it would have had absent the contract, normally filed, a LOW/POSSIBLE one stays a NOTE), under `accepted-risk` it is `NOTE contract-accepted-risk`; never for HIGH/CRITICAL, `not-affected`, safety-exempt or this PR's own files, nor on missing, untrusted or closed contract input.
672
676
 
673
677
  Each NOTE gets one disposition: (1) **fix in this PR**, only comment, documentation or test-only changes as a follow-up commit (any executable change is filed or re-reviewed in full; never push unreviewed code under `--auto-merge`); (2) **list in the PR body** under `## Non-blocking notes` (edit, never replace; `mktemp` file named for the PR number, read back to confirm); (3) **drop** duplicates, stale-comment nits and speculation. NOTES never reach the filing call. The 6A dry run printed the NOTE list: decide the fixed and dropped counts (`NOTES_FIXED`, `NOTES_DROPPED`, default 0; other plain NOTEs count as listed), then the 6C fence runs `classify` for real.
674
678
 
@@ -837,7 +841,7 @@ bash "$RF" calibrate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" --o
837
841
  **One script owns every Phase 8 gate (MANDATORY; a gate is never skipped, reordered or hand-run).** `review-finalize.sh merge-gate` runs, in order, and stops at the first refusal: the note-disposition preflight (a trusted `FORGE:NOTE_DISPOSITION` must exist), the in-PR fix gate (an unanswered trusted `FORGE:INPR_FIX` at the current head blocks), the phase-trail preflight (`scripts/verify-phase-trail.sh` on the linked issue; `--issue` is mandatory and never inferred; an infrastructure failure is `BLOCKED` plus `needs-human`) <!-- Added: forge#3061 -->, the degraded-gate review (`degraded-gate-unreviewed` unless a `### Degraded Paths Reviewed` section covers each degraded check), the guard-state flags below (`VERDICT` is `APPROVED` or `CHANGES REQUESTED`, the others `true`/`false`; an empty or unsubstituted value aborts with `needs-human`; `--other-blocking true` when 7B criterion 1, 2, 3 or 5 fired), routing (a base conflict as the ONLY blocker routes to the base-sync path, `blocker: base-conflict`; any other hold adds `needs-human`), the pre-merge mergeability guard on fresh state, the previously-escalated guard (parks at `workflow:awaiting-merge`, never merges), the CI gate (`scripts/wait-ci-green.sh`) with the reviewed-head guard (only the commit the `FORGE:REVIEW_ROUTE` sha approved; a docs-only delta is allowed), and finally the merge with `--match-head-commit`. Every gate fails closed.
838
842
 
839
843
  ```bash
840
- PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"
844
+ PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; MANUAL_PR="{MANUAL_PR}"; OWNER_REQUESTED="{OWNER_REQUESTED}"
841
845
  MERGE_ISSUE="{MERGE_ISSUE}"; MERGE_BASE="{MERGE_BASE}"; IS_MILESTONE_TO_STAGING="{IS_MILESTONE_TO_STAGING}"
842
846
  VERDICT="{VERDICT}"; HAS_PURPOSE_REGRESSION="{HAS_PURPOSE_REGRESSION}"; CALIBRATION_NEEDS_HUMAN="{CALIBRATION_NEEDS_HUMAN}"; CTX="{CONTEXT_FILE}"
843
847
  TRUST_NEEDS_HUMAN="{TRUST_NEEDS_HUMAN}"; BASE_CONFLICT="{BASE_CONFLICT}"; OTHER_BLOCKING="{OTHER_BLOCKING}"; TABLE_CELL_KEY="{TABLE_CELL_KEY}"
@@ -846,7 +850,7 @@ RF=$(forge_resolve review-finalize.sh) # install roots only, never the PR chec
846
850
  [ -n "$RF" ] || { echo "REVIEW_RESULT: status: BLOCKED, blocker: scripts/review-finalize.sh not resolvable (set FORGEDOCK_HOME to the ForgeDock install); refusing to continue (fail closed)"; exit 1; } # STOP
847
851
  # The calibration note derives from issue text: `calibrate` (Phase 7B.5) wrote it to this file; it is passed by path, never substituted into a shell word.
848
852
  OUT_DIR="$(dirname "$CTX")/review-finalize-${PR_NUMBER}"
849
- GATE_OUT=$(bash "$RF" merge-gate --pr "$PR_NUMBER" --repo "$REPO" --issue "$MERGE_ISSUE" --base "$MERGE_BASE" \
853
+ GATE_OUT=$(bash "$RF" merge-gate --pr "$PR_NUMBER" --repo "$REPO" ${MERGE_ISSUE:+--issue "$MERGE_ISSUE"} --base "$MERGE_BASE" $([ "$MANUAL_PR" = "true" ] && echo --manual-pr) $([ "$OWNER_REQUESTED" = "true" ] && echo --owner-requested) \
850
854
  --verdict "$VERDICT" --has-purpose-regression "$HAS_PURPOSE_REGRESSION" --calibration-needs-human "$CALIBRATION_NEEDS_HUMAN" --calibration-note-file "$OUT_DIR/calibration-note.txt" \
851
855
  --trust-needs-human "$TRUST_NEEDS_HUMAN" --base-conflict "$BASE_CONFLICT" --other-blocking "$OTHER_BLOCKING" --table-cell-key "$TABLE_CELL_KEY" --out-dir "$OUT_DIR"); GATE_RC=$?
852
856
  printf '%s\n' "$GATE_OUT"
@@ -859,7 +863,7 @@ exit "$GATE_RC"
859
863
 
860
864
  **Outcome mapping.** Report the script's output; never re-run its gates by hand and never `gh pr merge` yourself.
861
865
  - Exit 0, `MERGE_OUTCOME=merged` (`MERGE_STATE=MERGED`): merged. `merge-failed`: the merge did not land (the script commented on the issue). `parked-awaiting-merge`: parked per the previously-escalated guard; the script performs the transition itself (`transition-label.sh ... awaiting-merge`, prose fallback `gh issue edit --add-label "workflow:awaiting-merge"`).
862
- - Exit 3: print the `REVIEW_RESULT: status: BLOCKED, blocker: ...` line and stop; `MERGE_OUTCOME=` names the case (`base-conflict`, `needs-human`, `protection-blocked`, `stale-review`, `ci-not-green`). A `base-conflict` blocker carries no label (the autonomous base sync is pipeline work, not a human decision), so every caller of `--auto-merge` MUST map it explicitly: `work-on:review` R4, the router's Phase 0A.1 re-review fallback and `orchestrate` re-review Step 3 each set `workflow:remediating` (falling back to `needs-human`), and a standalone caller runs `/work-on <issue> --remediate`. A caller never leaves the issue unlabelled at `workflow:in-review`. A CI gate TIMEOUT prints `CI_GATE_TIMEOUT`: re-run the same fence up to 3 more times. A phase-trail blocker with no MISSING lines (`phase trail unreadable (rc=N)`, `auto-merge requires --issue`) is an infrastructure or usage failure: callers neither re-run phases nor merge manually.
866
+ - Exit 3: print the `REVIEW_RESULT: status: BLOCKED, blocker: ...` line and stop; `MERGE_OUTCOME=` names the case (`base-conflict`, `needs-human`, `protection-blocked`, `stale-review`, `ci-not-green`). A `base-conflict` blocker carries no label (the autonomous base sync is pipeline work, not a human decision), so every caller of `--auto-merge` MUST map it explicitly: `work-on:review` R4, the router's Phase 0A.1 re-review fallback and `orchestrate` re-review Step 3 each set `workflow:remediating` (falling back to `needs-human`), and a standalone caller runs `/work-on <issue> --remediate`. A caller never leaves the issue unlabelled at `workflow:in-review`. A CI gate TIMEOUT prints `CI_GATE_TIMEOUT`: re-run the same fence up to 3 more times. A phase-trail blocker with no MISSING lines (`phase trail unreadable (rc=N)`, `auto-merge requires --issue`, `manual-pr refused: ...`) is an infrastructure or usage failure: callers neither re-run phases nor merge manually.
863
867
  - Exit 3 with `blocker: degraded-gate-unreviewed` (`needs-human` added): the linked issue's gate is DEGRADED and no trusted review comment for the current head has a `### Degraded Paths Reviewed` section with a `- name: how reviewed` item for every degraded check. Not a code defect: `work-on:review` (R4) re-runs the review once so the section is added. Never merge by hand. <!-- Added: forge#3628 -->
864
868
  - Exit 4: `REVIEW_RESULT: status: PHASE_TRAIL_FAILED` plus the `MISSING:` lines. Return that status and stop: this phase never re-runs the missing phases and never escalates to `needs-human`; `work-on:review` (R4) alone owns re-dispatching them (forge#3102).
865
869
 
package/docs/CONFIG.md CHANGED
@@ -148,7 +148,7 @@ agents:
148
148
  | Field | Type | Required | Default | Description |
149
149
  |-------|------|----------|---------|-------------|
150
150
  | `default_model` | string | No | `"sonnet"` | Short alias — `"sonnet"`, `"opus"`, or `"haiku"` — the same values the Agent/Task tool's `model` parameter accepts. This is the only form that works for interactive command-spec sub-agent spawning. |
151
- | `subagent_model` | string | No | `default_model`, else `"sonnet"` | Short alias, same accepted values as `default_model`. Overrides the model used for child agents spawned internally by a top-level command (see above). Omit to inherit `default_model`. |
151
+ | `subagent_model` | string | No | `default_model`, else `"sonnet"` | Short alias, same accepted values as `default_model`. Overrides the model used for child agents spawned internally by a top-level command (see above). Omit to inherit `default_model`. In engine lanes (core work-on), only this field is read, with no `default_model` fallback. When set, it is the default model of subagents that have no model of their own. When unset, the operator's own `CLAUDE_CODE_SUBAGENT_MODEL` (if any) stays in effect. In every lane session, ForgeDock-defined agents such as the explorer keep their own model: an ambient `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` in the operator's settings is turned off (#4843, #4849). **Upgrade note (1.38.1):** a `_FORCE=1` cap in your settings.json no longer applies to ForgeDock-defined agents in lanes. To pin model-less subagents, set this field. |
152
152
 
153
153
  **Resolution order** (highest precedence first):
154
154
  1. `--model <id>` — CLI flag, `npx forgedock run` only (headless; main agent only).
@@ -437,6 +437,7 @@ orchestration:
437
437
  | `max_concurrent` | integer | No | Max concurrent top-level `/work-on` dispatches. It does not bound cascade growth; under `policy: all` it raises drain and spawn throughput together. Default: 12. |
438
438
  | `breaker.errors` / `breaker.window_min` | integer | No | `forgedock orchestrate` circuit breaker (#4121): after `errors` engine-errors within `window_min` minutes the batch stops admitting lanes, lets running lanes finish, and keeps the rest pending for `--resume`. `errors: 0` turns it off. Default: 3 in 30 |
439
439
  | `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held, gh unavailable) before its row is final. `host.busy` and `sandbox.capacity` (sandbox pool full) deferrals are not capped. Default: 3 |
440
+ | `blocked_label` | string | No | `forgedock orchestrate` (#4773): an open issue carrying this label is admitted to the batch but not dispatched; removing the label releases it on the next scheduler pass. A `Blocked by #N` / `Depends on #N` line in the body of a trusted author (OWNER, MEMBER, COLLABORATOR or a bot) is a DAG edge to #N, and `--add` prints the edges it created. Empty turns the label off. Default: `blocked` |
440
441
  | `global_parallel` | integer | No | `forgedock orchestrate` (#4191): host-wide cap on running lanes across every batch and repo on the host, enforced through the host lane registry (`~/.forge/sched/`, or `FORGEDOCK_SCHED_DIR`). A freed slot goes to the highest-priority queued issue (`priority:P<n>` / `P<n>` labels, unlabelled P2); within a priority, slots are shared across repos by weight (#4193: `forgedock sched weight <owner/repo> N`, `--clear` resets; default equal, FIFO inside a repo), and priority always dominates weights; running lanes are never preempted and `--parallel` K still bounds each batch. `forgedock sched cap N` overrides it live for the whole host (`--clear` reverts); `forgedock sched show` lists the weights, slots and the queue. Default: unset (no global cap) |
441
442
  | `recovery.max_attempts` | integer | No | `forgedock orchestrate` in-batch recovery (#4267): how many recovery lanes the batch launches per issue for a `needs-human` with a mechanical code (`ci.red`, `base.conflict`, `ci-pending` on a conflicting PR, `contract.invalid` after a mid-run issue edit, `builder.block_untyped`). A recovery lane (`run-issue --recover <code>`) removes `needs-human`, posts a `FORGE:DECISION`, resumes the open PR and re-queues the issue with its dependents. If it ends anything but `merged`, the issue is labelled `needs-human` again with a recovery-evidence `FORGE:NEEDS_HUMAN` comment. Human codes are never recovered. Flat form: `recovery_max_attempts`. Default: 1; `0` disables in-batch recovery (a mechanical `needs-human` is final, as before). |
442
443
  | `base_sync.enabled` | boolean | No | `forgedock orchestrate` parked-PR base sync (#4525): every 10 min while the batch runs, an open PR of a `needs-human` row is merged with its moved base in a throwaway worktree. A clean merge, or one whose only conflicts are hunks where both sides purely added lines in a `union_globs` file, is pushed as a plain merge commit (never forced). Any other conflict is aborted, the branch left alone, and its paths are posted once per base sha as a `FORGE:DECISION` on the issue. Sequence/`_journal.json` files are never resolved here. Flat form: `base_sync_enabled`. Default: `true`; `false` opts out. |
@@ -465,6 +466,19 @@ orchestration:
465
466
 
466
467
  ---
467
468
 
469
+ ## `decisions` (OPTIONAL)
470
+
471
+ Decision engine (#4766, see [DECISIONS.md](DECISIONS.md)). The parser has one nesting level and no arrays, so lists are comma-separated.
472
+
473
+ | Key | Type | Description |
474
+ |---|---|---|
475
+ | `policy` | string | The repo's north-star file. Default `NORTHSTAR.md`, falling back to `CLAUDE.md`, then `AGENTS.md`. |
476
+ | `mode` | string | `shadow` (default: post `FORGE:DECISION (shadow)`, keep the label) or `live` (clear `needs-human`, requeue). |
477
+ | `human_only` | list | Authority-matrix classes that always stay human. Default `spend,credentials,external-publish,customer-send,prod-write,promotion,legal`. |
478
+ | `hint_<class>` | list | Match words for a class; replaces the built-in hints, and is required for a class that is not built in. |
479
+ | `veto_hours` | number | Owner veto window after a live decision (default 24). |
480
+ | `reversal_max` | number | Reversal rate (0-1) above which live falls back to shadow (default 0.2, minimum sample 5). |
481
+
468
482
  ## `hygiene` (OPTIONAL)
469
483
 
470
484
  Automatic reclaim of what ForgeDock leaves behind (#4183), using the `forgedock gc` reaper. Only resources ForgeDock provably owns are reclaimed: entries of a stale lane ledger, Docker containers and volumes labelled `forgedock.owner=1`, `lean-*`/`agent-*` dirs under `.claude/worktrees`, `feat/issue-<n>-lean` branches of closed issues, and ForgeDock scratch under `~/.forge/tmp`. Everything else is reported, never touched, and so are unpushed or uncommitted work, live lanes, protected branches and branches with an open PR. Block form only.
@@ -610,6 +624,49 @@ engine:
610
624
 
611
625
  ---
612
626
 
627
+ ## `issue_watch` (OPTIONAL)
628
+
629
+ Named, scoped, capped watches for `forgedock issue-watch` (see [ISSUE-WATCH.md](ISSUE-WATCH.md)). Write `issue_watch:`, then `watches:`, then one block per watch name. The release keys need `mode: release` and at least a `threshold` or `immediate`.
630
+
631
+ ```yaml
632
+ issue_watch:
633
+ watches:
634
+ nomilestone:
635
+ milestone: none
636
+ exclude_labels: [epic, post-deploy]
637
+ include_followups: defer-only
638
+ mode: batch
639
+ parallel: 12
640
+ release-1-4:
641
+ version: "1.4"
642
+ max_issues: 300
643
+ until: 2026-11-15T00:00:00Z
644
+ ```
645
+
646
+ | Key | Type | Required | Description |
647
+ |---|---|---|---|
648
+ | `milestone` | string | No | Milestone title or slug, or `none`. |
649
+ | `labels`, `exclude_labels` | list | No | Labels that must / must not be present. |
650
+ | `search` | string | No | `gh search` query. |
651
+ | `title_regex` | string | No | Regex tested against the title. |
652
+ | `since` | ISO time | No | Only issues created at or after it. |
653
+ | `version` | `x.y` | No | Target version from the milestone title or a `version:x.y` label. |
654
+ | `lane` | string | No | Pin the lane; never a default branch. Default: the issue's own lane. |
655
+ | `max_issues` | integer | No | Total claims; at N the watch drains and exits. Default: none (forever). |
656
+ | `max_inflight` | integer | No | Claims in flight at once. Default 4. |
657
+ | `until` | ISO time | No | Stop claiming at this time, drain and exit. |
658
+ | `mode` | string | No | `per-issue` (default), `batch` or `release` (pool, then cut themed releases). |
659
+ | `parallel` | integer | No | K of the batch in `batch` mode. Default 4. |
660
+ | `include_followups` | string | No | `none` (default) or `defer-only`. |
661
+ | `postdeploy_rollup` | issue number | No | Release issue that collects post-deploy-only follow-ups as checklist lines. |
662
+ | `threshold` | map | release | `{ min_issues, min_score, max_age_days }`; any one fires a release. |
663
+ | `immediate` | list | release | `label:<name>` or `priority:P0..P3` entries that cut a release now with only their theme. |
664
+ | `max_release_issues` | integer | release | Cap on a release set, closure included. Default 40. |
665
+ | `theme_map` | block | release | `<theme>: [label:<x>, scope:<x>, path:<glob>]` rules, one theme per line. |
666
+ | `tracker` | issue number | release | Issue that gets the `FORGE:RELEASE_PLAN` comment. Default: the first issue of the release. |
667
+
668
+ ---
669
+
613
670
  ## `followups` (OPTIONAL)
614
671
 
615
672
  Deferred follow-ups (`scripts/file-deferred-followups.sh`) are filed as one issue per class per parent: `engineering`, `post-deploy`, `external` and `ops`. Each carries the label `followup:<class>` (`external` also `external-prerequisite`, and states the parent it is a prerequisite of) and inherits the parent's milestone. A requirement may set an optional `class` in the contract; otherwise `post-deploy` items are `post-deploy` and the rest `engineering`. A parent milestone that has shipped (closed) is replaced by the next open milestone by due date, else `followups.default_milestone`.
@@ -619,6 +676,18 @@ followups:
619
676
  default_milestone: "Backlog" # optional: milestone title used when the parent's milestone has shipped and no later one is open
620
677
  ```
621
678
 
679
+ ## `rollouts` (OPTIONAL)
680
+
681
+ ```yaml
682
+ rollouts:
683
+ files: "config/rollouts.json,src/flags.py" # comma-separated rollout registry / env flag list paths
684
+ dormant_days: 14 # dormancy report threshold (default 14)
685
+ ```
686
+
687
+ A diff that adds a key to one of these files with a default of `false`, `0`, `off` or `null` (#4769) must be covered by an activation row in the contract: a `defer` requirement with bucket `owner:promote:<flag>` (a trailing `*` matches a prefix) or a `deliver` row whose why names the flag. Without one conformance fails with `activation_missing`, and an acceptance criterion naming `shadow`, `cohort` or `treated` fails with `mode_unreachable`. Without `rollouts` nothing changes.
688
+
689
+ A post-deploy check whose output has a line `BLOCKED: <flag> = off ...` is not a failure: it posts one `FORGE:ROLLOUT_ASK` owner ask per flag on the rollup and parks `awaiting-measurement`; the ask is posted again only when the output (the evidence) changes. `dormancyReport` (`bin/lean/activation.mjs`) lists introduced flags still `off` after `dormant_days`, with days dormant and the parent issue, through an injected read-only `flagState(flag)` hook; a `keep-off` decision for a flag (or `PREFIX*`) silences it.
690
+
622
691
  ## `post_deploy` (OPTIONAL)
623
692
 
624
693
  Deferred follow-ups whose items are all post-deploy checks are parked (`awaiting-promotion`, no lane) until the parent's fix is on `branches.default`. Keys: `precondition_cmd` (exit 0 ready, 1 parked) and `min_age` (soak window, e.g. `24h`).
@@ -883,8 +952,9 @@ execution:
883
952
  | `fallback_local` | boolean | No | `true`: a remote-placed lane runs on the host while the provider reports no agent online (`GET {endpoint}/status -> {"online": N}`, the built-in router answers it with `online`, `total` and per-agent `ok`/`paused`), so a batch completes locally with every pool agent offline or asleep (forge#4547). Default `false`: such lanes defer (`sandbox.capacity`). A missing or failing `/status` is unknown and never triggers it. |
884
953
  | `unreachable_window_min` | number | No | Remote providers: how long a lane keeps polling (with backoff, up to 30s) after the provider's transport fails (connection refused/reset, `fetch failed`, timeout, 502/503/504) before it ends `deferred` with `sandbox.unreachable` (forge#4672). Inside the window the lane never ends and the sandbox is never torn down; after it the sandbox is kept and adopted on the next attempt or `--resume`; the engine-error breaker does not count it. `adopt` applies the same window. Default: 5 |
885
954
  | `on_budget` | string | No | `stop` (default): running lanes finish and the rest end `held` (`execution budget: ...`) for a later `--resume`. `local`: the rest run as detached host lanes. |
886
- | `host_capabilities` | list | No | Host-only capabilities the dispatching host has and a sandbox does not relay (forge#4542): names such as `sops`, `prod_monitor`, `ops_credentials`. A lane whose issue text names one (built-in signals: `.secrets/*.enc.yaml`, `sops`, `ssh *-monitor`, `obs-psql`, `credentials.yaml`; a declared name written out; `host_capability_patterns`) is placed `local` in `remote` and `hybrid` mode with the reason `host capability: <name>`, since remote providers (computeshare included) relay none of them. A remote lane that still blocks as `credentials` naming only a declared capability ends `env.capability_remote` (recoverable) and is rerun locally once. |
955
+ | `host_capabilities` | list | No | Host-only capabilities the dispatching host has and a sandbox does not relay (forge#4542): names such as `sops`, `prod_monitor`, `ops_credentials`. A lane whose issue text names one (built-in signals: `.secrets/*.enc.yaml`, `sops`, `ssh *-monitor`, `obs-psql`, `credentials.yaml`; a declared name written out; `host_capability_patterns`) is placed `local` in `remote` and `hybrid` mode with the reason `host capability: <name>`, unless the provider relays it (`relay_commands`, forge#4778; otherwise remote providers relay none). A remote lane that still blocks as `credentials` naming only a declared capability ends `env.capability_remote` (recoverable) and is rerun locally once. |
887
956
  | `host_capability_patterns` | list | No | `name:regex` entries (case-insensitive) that also mean the lane needs capability `name`, e.g. `vault:vault\s+kv`. An invalid entry is ignored. |
957
+ | `relay_commands` | list | No | Read-only capability relay (forge#4778): `capability:command` entries, e.g. `prod_monitor:obs-psql` or `prod_monitor:obs-*` (exact name, or a prefix glob with one trailing `*`; no `/`, whitespace or other glob characters). A `remote`/`pool` lane needing a listed capability is placed remote: the sandbox runs the command unchanged (a `cs-relay` shim), the request goes sandbox -> pool agent -> router queue, and the dispatching host picks it up on its status poll, gates it against this list and runs it with no shell, a 120 s timeout and a 1 MB output cap, redacting known secrets; a refused command gets rc 126 and the key never leaves the host. List only read-only wrappers, never `sops` or `ops_credentials`. The frozen contract's simple validate / repro_test commands that pass the gate are pre-fetched at dispatch and shipped with the lane (96 KB cap). An older router or agent without the relay makes `cs-relay` exit 125, the lane blocks as `credentials` and is recovered locally once, as before. |
888
958
  | `cost_per_minute` | number | No | USD per sandbox-minute, used when the provider reports no cost of its own (the `container` provider never does). Default `0`. |
889
959
 
890
960
  **Lifecycle:** each sandbox is listed in the lane ledger (`~/.forge/ledger/<batch>/sandbox-<n>.json`, kind `sandbox`) before it starts and removed from it only after teardown succeeded: on success, failure, a lane that exits without a result, and adopt after `--resume`. A sandbox left by a killed dispatcher is reaped by `forgedock gc --apply` (scope `--sandboxes`). The container provider mounts the checkout's git dir read-only at `/src` (cloned to the container's own `/work`), `~/.forge/verify-cache` read-only at `/cache`, and the batch `lanes/` dir at `/result`.
@@ -1209,6 +1279,7 @@ verification:
1209
1279
  | `ci_local` | object | No | Local CI gate settings (see below) |
1210
1280
  | `commands.<lang>.<step>` | string | No | Toolchain commands (`format`, `lint`, `typecheck`, `test`, `build`) per language key (`python`, `typescript`, ...); see `forge.yaml.example`. An absent key logs `SKIPPED — not configured` |
1211
1281
  | `commands.typescript.lint` | string | No | TypeScript lint. Validate runs it like `typescript.typecheck` (bounded by `FORGEDOCK_VERIFICATION_TIMEOUT_SECONDS`, default 120 s; a failure blocks). The core engine reads it from the trusted `forge.yaml` (main checkout or base ref, never the PR's tree), and `bin/lean/checks.mjs` prints it in place of the discovered lint. Without it, a turbo lint is scoped to the changed packages (`--filter=[base]`), not their dependents. Prefer a changed-files, cached lint |
1282
+ | `commands.typescript.test_changed`, `commands.typescript.typecheck_changed`, `commands.python.test_changed` | string | No | Changed-file scoped steps for `/review-pr` Phase 2 (repos where the full typecheck or suite is too slow or heavy). They run in the per-PR worktree and read the PR's changed files that still exist from `$FORGE_CHANGED_FILES` (newline-separated environment variable; never spliced into the command string). Reported as Phase 2 evidence with `EXIT <lang>.<step>=<code>` like the full-repo steps; a non-zero `typecheck_changed` blocks, a failing `test_changed` follows the REAL/flaky rule of `test`. Examples: `vitest related $FORGE_CHANGED_FILES --run`; `pytest -q $(printf '%s\n' $FORGE_CHANGED_FILES \| grep 'test_.*\.py$')`. For `typecheck_changed`, filter the compiler output to the changed files so pre-existing errors elsewhere do not block. `forgedock init` suggests them when vitest or pytest is detected |
1212
1283
  | `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 |
1213
1284
  | `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 |
1214
1285
 
@@ -0,0 +1,32 @@
1
+ # Decision engine (#4766)
2
+
3
+ Settles a lane's decision-only `needs-human` escalation against the target repo's own north star instead of parking it.
4
+ Only external actions stay with a human. Code: `bin/lean/decision-engine.mjs`. Config: [`decisions:`](CONFIG.md).
5
+
6
+ ## Flow
7
+
8
+ 1. **Policy.** `decisions.policy` (default `NORTHSTAR.md`, then `CLAUDE.md`, `AGENTS.md`) holds objectives, non-negotiables and the
9
+ authority matrix. `decisions.human_only` names the classes that stay human: spend, credentials, external-publish,
10
+ customer-send, prod-write, promotion, legal (each with match hints; override with `hint_<class>`). See
11
+ [NORTHSTAR-TEMPLATE.md](NORTHSTAR-TEMPLATE.md).
12
+ 2. **Deterministic split** (`splitEscalation`, no model): from the terminal code, block type and matrix hints, into
13
+ `recovery` (retryable code, recovery owns it), `evidence` (missing read-only production data, e.g. `conformance.unimplemented`),
14
+ `post-deploy` (all items post-deploy), `external`, `decision` or `mixed`. External parts are left untouched.
15
+ 3. **One judgment call per decision part.** Inputs: the issue, the options listed, the policy file and the anchored register
16
+ (#4695) as precedent. The answer records the choice, the cited clause, the rejected alternative, reversibility and confidence.
17
+ 4. **Guardrails.** A one-way or low-confidence answer, or one with no clause, escalates with the analysis attached (`FORGE:DECISION (escalated)`),
18
+ never a guess. Settled decisions are written to the anchored register, so later lanes follow them; changing one needs a `supersedes`.
19
+ 5. **Shadow, then live.** Shadow (default) posts `FORGE:DECISION (shadow)` and keeps the label. Live posts `FORGE:DECISION`, clears
20
+ `needs-human` and requeues (`orchestrate --requeue`); a mixed issue keeps the label for its external part.
21
+ 6. **Veto.** A `forge:decision-veto` label, or a reply starting with `veto` within `veto_hours`, restores `needs-human` and reverts the requeue.
22
+ 7. **Idempotent** on the escalation comment id (`Escalation: <id>` in the engine's comment).
23
+
24
+ ## Metrics
25
+
26
+ `decision_engine` telemetry ([TELEMETRY.md](TELEMETRY.md)): decided, escalated, vetoed, reversed, needs-human before/after. A reversal rate above
27
+ `reversal_max` turns the engine back to shadow. The batch report lists every decision under `decided`.
28
+
29
+ ## Not in this module
30
+
31
+ The `issue-watch` stage that lists `needs-human` issues and calls `settle` (`sweep_needs_human`, `--dry-run` via `classify`, caps, status counts)
32
+ lands with #4765. Running a declared monitor query for `evidence` and folding `post-deploy` items into the release checklist are follow-ups.
@@ -0,0 +1,95 @@
1
+ # Issue watch
2
+
3
+ `forgedock issue-watch` keeps feeding matching open issues into lanes until a cap is reached. Each **watch** is named, scoped and capped; several run on one repo.
4
+
5
+ ```
6
+ forgedock issue-watch run [--name <w>] [--repo owner/repo] [--once] [--interval <s>] [--dry-run]
7
+ forgedock issue-watch status [--name <w>] [--repo owner/repo]
8
+ ```
9
+
10
+ `--name` defaults to the only watch in forge.yaml, else `default` (every trusted issue, no caps). `--once` does one pass. `--interval` is the seconds between passes (default 300).
11
+
12
+ ## Config
13
+
14
+ ```yaml
15
+ issue_watch:
16
+ watches:
17
+ nomilestone:
18
+ milestone: none
19
+ exclude_labels: [epic, post-deploy]
20
+ include_followups: defer-only
21
+ mode: batch
22
+ parallel: 12
23
+ release-1-4:
24
+ version: "1.4"
25
+ max_issues: 300
26
+ until: 2026-11-15T00:00:00Z
27
+ ```
28
+
29
+ Keys are listed in [CONFIG.md](CONFIG.md#issue_watch-optional). An unknown key, a bad mode, regex, number or date fails the watch at load.
30
+
31
+ ## State and claims
32
+
33
+ Each watch has `~/.forge/watch/<owner>__<repo>/<name>/` (or `$FORGEDOCK_WATCH_DIR`) with a `lock` and `status.json`. The lock is per (repo, name): a second `run` of the same watch is refused while the first is alive, and a dead holder is taken over. Different names run side by side. `~/.forge/watch/<owner>__<repo>/claims.json` is shared by every watch of the repo, so an issue has at most one claim across all of them. The claim is taken under a directory lock before anything is launched.
34
+
35
+ ## Selectors
36
+
37
+ All optional, AND-ed. Only issues from an owner, member or collaborator are claimed (bot-filed issues only through `include_followups`).
38
+
39
+ | Key | Meaning |
40
+ |---|---|
41
+ | `milestone` | a milestone title or slug, or `none` for issues without one |
42
+ | `labels` / `exclude_labels` | every listed label present / none present |
43
+ | `search` | a `gh search` query, passed to `gh issue list --search` |
44
+ | `title_regex` | JavaScript regex tested against the title |
45
+ | `since` | ISO time; only issues created at or after it |
46
+ | `version` | `x.y`, from the milestone title (first `x.y` in it) or else a `version:x.y` label |
47
+
48
+ The lane follows the repo rule: a milestone issue goes to `milestone/<slug>` (forge.yaml `branches.feature_pattern`), anything else to `branches.staging`. `lane:` pins one lane for the watch but is refused when it is a default branch.
49
+
50
+ ## Caps and forever mode
51
+
52
+ - `max_issues: N`: total claims over the watch's lifetime. At N the watch **drains**: no new claims, retry and verify only. When nothing is inflight it exits with a summary.
53
+ - `until: <ISO time>`: the same, at that time.
54
+ - `max_inflight` (default 4): claims in flight at once.
55
+ - With neither `max_issues` nor `until` the watch runs forever: it keeps claiming, retrying (a deferred lane, exit 75, is relaunched up to 3 times) and verifying (an issue counts as verified once it is closed).
56
+
57
+ ## Modes
58
+
59
+ - `mode: per-issue` (default): one `forgedock run-issue` per claim.
60
+ - `mode: batch`: claims are `--add`ed to one long-lived `orchestrate` batch, so its K (`parallel:`), the `Depends on` DAG (claims are ordered dependencies first), the supervisor and the report apply. When the batch writes its report the watch starts a new one with the next claims.
61
+
62
+ - `mode: release`: see [Release mode](#release-mode).
63
+
64
+ ## Follow-ups
65
+
66
+ `include_followups: defer-only` claims bot-filed `follow-up:` issues that have an unchecked `— defer` item. Post-deploy-only follow-ups are not claimed: with `postdeploy_rollup: <issue>` each is appended once as a checklist line to that release issue. Other bot issues stay excluded.
67
+
68
+ ## Status
69
+
70
+ `status` prints the selector, claims against `max_issues`, inflight, merged, verified, failed and the time remaining.
71
+
72
+ ## Release mode
73
+
74
+ `mode: release` claims nothing immediately. It pools the issues that match the selectors and cut a **themed release** when a trigger fires, then orchestrates just that set.
75
+
76
+ ```yaml
77
+ issue_watch:
78
+ watches:
79
+ staging-releases:
80
+ milestone: none
81
+ mode: release
82
+ threshold: { min_issues: 15, min_score: 40, max_age_days: 5 }
83
+ immediate: [label:security, priority:P0]
84
+ max_release_issues: 40
85
+ theme_map:
86
+ security: [label:security, path:infra/ssh-guard/**]
87
+ stealth: [path:services/worker/**/anti_detection/**, label:scraper]
88
+ ```
89
+
90
+ - **Triggers** (any one fires): `min_issues`; a priority-weighted `min_score` (P0=8, P1=4, P2=2, P3=1, no priority label = 1; labels `P1` or `priority:P1`); `max_age_days` (the oldest pooled issue); `immediate` entries (`label:<name>` or `priority:P0..P3`), which cut a release now with only the theme of the highest-priority immediate issue.
91
+ - **Themes**: `theme_map` rules `label:`, `scope:` (the conventional-commit scope of the title) and `path:` (a glob matched against paths named in the title or body); the first theme in config order wins, and a title scope equal to a theme name also matches. Issues no rule classifies get one LLM call (`claude --print`), counted in `status` as `llm-classified`; without an answer they join theme `general`.
92
+ - **Decision**: each theme scores Σ priority weights + age (0.1 per day, at most 3 per issue) + a rank bonus from an ordered `Release priorities:` list in the repo's NORTHSTAR.md (inline `a, b` or bullets); ties go to that order, then the name. The top theme (or the forced immediate theme) ships with the closure of its `Depends on` issues: a prerequisite from another theme is pulled in and marked, and the set is capped at `max_release_issues` (default 40; an issue whose closure does not fit stays pooled).
93
+ - **Run**: the watch posts a `FORGE:RELEASE_PLAN` comment (theme, reasons, included, pulled and excluded issues, policy) on `tracker:` (default: the first issue of the set), tags the set (milestone `release/<theme>-<date>` for a milestone target, else label `release:<theme>-<date>`), and starts one `orchestrate` batch. When the batch reports it opens the deploy PR (lane to the default branch) once. **The watch never merges it**; promotion stays human-only.
94
+ - **Roll over**: issues left out stay pooled and keep their age. `max_issues` and `until` stop new releases.
95
+ - `forgedock issue-watch run --name <w> --dry-run` prints `would cut: <theme> (N issues, score S; ...)`, the triggers, the theme scores and each issue's theme, and writes nothing.
@@ -0,0 +1,21 @@
1
+ # NORTHSTAR template for target repos
2
+
3
+ Copy to `NORTHSTAR.md` and set `decisions.policy` in `forge.yaml` (default: `NORTHSTAR.md`). The decision engine ([DECISIONS.md](DECISIONS.md))
4
+ cites a clause of this file for every decision it makes; with no applicable clause it escalates.
5
+
6
+ ```markdown
7
+ # <Project> North Star
8
+
9
+ ## Objectives and metrics
10
+ 1. <what the project optimises, with the metric that measures it>
11
+
12
+ ## Non-negotiables
13
+ 1. <a rule a decision may never break>
14
+
15
+ ## Authority matrix (stays human)
16
+ Mirrors `decisions.human_only` in forge.yaml: spend, credentials, external publish, customer-facing send,
17
+ production write or root, staging to main promotion, legal.
18
+
19
+ ## Decide yourself
20
+ Everything else that is reversible and covered by a clause above. Prefer the option that is cheaper to undo.
21
+ ```
@@ -77,6 +77,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
77
77
  | `review.failed` | Core work-on: the fix/regression review failed twice (or could not resume the builder) | lean | Reviewer verdict FAIL |
78
78
  | `review.no_verdict` | Core work-on: the reviewer returned no parseable verdict twice | lean | Unparsable reviewer output |
79
79
  | `contract.invalid` | Core work-on: the builder's contract.json stayed invalid after one correction (missing requirement rows, a quote not verbatim from the issue, a defer without a why, no validate commands) | lean | `validateContract` problems after the correction resume |
80
+ | `contract.invalid_command` | Core work-on (#4761): a frozen validate command was rejected by its runner's own CLI (vitest `Unknown option` for `-q`, jest `Unrecognized CLI Parameter`, pytest `unrecognized arguments`) after the engine's normalised rerun (vitest `-q` → `--reporter=dot`) did not clear it. A contract defect, not `conformance.unimplemented`: no builder resume. `validateContract` also rejects vitest `-q`/`--quiet` up front. Ends `needs-human`; recoverable and mechanical | lean | `gate()` rerun `{rc, output}` classified by `conformance.mjs` `cliUsageError` |
80
81
  | `review.incomplete` | Core work-on: the conformance review twice returned no complete rows (a generic PASS, a missing requirement/scope/preserve row, evidence in a file that does not exist); nothing merged | lean | `checkCompleteness` problems on both reviewer runs |
81
82
  | `review.inconsistent` | Core work-on: the reviewer twice said NONCONFORMING without any failing row; the reviewer is re-asked, the builder's resume is not spent | lean | Verdict/row mismatch on both reviewer runs |
82
83
  | `conformance.omission` | Core work-on: an issue requirement is missing from or narrowed by the frozen contract, after one builder resume | lean | Review `issue_coverage` row not `covered` |
@@ -106,7 +107,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
106
107
  `forgedock orchestrate` recovers mechanical outcomes inside the batch:
107
108
 
108
109
  - **recoverable**:
109
- - needs-human with `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing`, `env.repro_unrunnable`, `env.capability_remote` or `budget.exceeded`;
110
+ - needs-human with `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing`, `env.repro_unrunnable`, `env.capability_remote`, `contract.invalid_command` or `budget.exceeded`;
110
111
  - `contract.invalid` when the issue was edited mid-run (`issueEdited`);
111
112
  - `ci-pending` on a conflicting PR, recovered as `base.conflict`.
112
113
 
package/docs/TELEMETRY.md CHANGED
@@ -68,3 +68,10 @@ Records contain ids, counts and codes only: never comment bodies, issue text, fi
68
68
  are restricted to `A-Za-z0-9 _.:/#@+=,-` (anything else becomes `_`) and truncated to 200 characters, so a value
69
69
  cannot carry markup, backticks or newlines into the comment. Treat the comment as public to anyone who can read the
70
70
  issue or PR.
71
+
72
+ ## `decision_engine` (#4766)
73
+
74
+ One record per escalation the north-star decision engine handled (`bin/lean/decision-engine.mjs`): `decided`, `escalated`,
75
+ `vetoed`, `reversed` (counts, 0 or 1 per issue), `mode` (`shadow` or `live`), and `needs_human_before` / `needs_human_after`
76
+ (the repo's open needs-human count around a sweep). A reversal rate (`reversed` over `decided`) above `decisions.reversal_max`
77
+ turns the engine back to shadow. See [DECISIONS.md](DECISIONS.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forgedock",
3
- "version": "1.37.0",
3
+ "version": "1.38.1",
4
4
  "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
5
5
  "bin": {
6
6
  "forgedock": "bin/forgedock.mjs"
@@ -43,7 +43,6 @@
43
43
  "examples/",
44
44
  "packages/protocol/src/",
45
45
  "scripts/",
46
- "!scripts/refresh-bot-token.sh",
47
46
  "templates/",
48
47
  "LICENSE",
49
48
  "README.md"
package/pool/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  ForgeDock's built-in remote compute pool (imported from computeshare; AGPL-3.0-or-later).
4
4
 
5
5
  - `bin/pool/` router, agent, docker/http/store helpers and `cli.mjs` (`node bin/pool/cli.mjs router|agent|install-command ...`).
6
- - `pool/image/` lane image recipe (Dockerfile, shims, entrypoint, `cs-cred` credential relay).
6
+ - `pool/image/` lane image recipe (Dockerfile, shims, entrypoint, `cs-cred` credential relay, `cs-relay` read-only capability relay: allowlisted commands executed on the dispatching host, #4778).
7
7
  - `pool/install/` agent installers (Windows/WSL, native Linux, router).
8
8
  Native Linux agent (root, systemd): `pool/install/install-agent-linux.sh --router URL --token CODE [--name N --cpus N --mem GB --dry-run]`.
9
9
  - Tests: `bin/tests/computeshare.test.mjs`.
@@ -39,8 +39,9 @@ RUN curl -LsSf "https://astral.sh/uv/${UV_VERSION}/install.sh" | env UV_INSTALL_
39
39
 
40
40
  COPY entrypoint.sh /usr/local/bin/cs-entrypoint
41
41
  COPY cs-cred /usr/local/bin/cs-cred
42
+ COPY cs-relay /usr/local/bin/cs-relay
42
43
  COPY gh-shim /opt/cs/bin/gh
43
44
  COPY claude-shim /opt/cs/bin/claude
44
- RUN chmod 0755 /usr/local/bin/cs-entrypoint /usr/local/bin/cs-cred /opt/cs/bin/gh /opt/cs/bin/claude
45
+ RUN chmod 0755 /usr/local/bin/cs-entrypoint /usr/local/bin/cs-cred /usr/local/bin/cs-relay /opt/cs/bin/gh /opt/cs/bin/claude
45
46
  WORKDIR /work
46
47
  ENTRYPOINT ["/usr/local/bin/cs-entrypoint"]
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env bash
2
+ # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
3
+ # SPDX-License-Identifier: AGPL-3.0-or-later
4
+ # cs-relay <cmd> [args...]: runs an allowlisted read-only command on the dispatching host (#4778) and replays its
5
+ # output and exit code. A dispatch-time pre-fetch (CS_RELAY_PREFETCH_B64) with the same argv is served without a call.
6
+ # The sandbox only sends argv; the host gates it (refused: rc 126). No relay, HTTP error or timeout: rc 125.
7
+ set -uo pipefail
8
+ [ $# -gt 0 ] || { echo "usage: cs-relay <cmd> [args...]" >&2; exit 2; }
9
+ argv=$(jq -cn '$ARGS.positional' --args -- "$@") || { echo "relay unavailable: jq failed" >&2; exit 125; }
10
+ replay() { # $1: {rc, stdout, stderr}
11
+ jq -j '.stdout // ""' <<<"$1"
12
+ jq -j '.stderr // ""' <<<"$1" >&2
13
+ exit "$(jq -r 'if (.rc|type) == "number" then .rc else 1 end' <<<"$1")"
14
+ }
15
+ if [ -n "${CS_RELAY_PREFETCH_B64:-}" ]; then
16
+ hit=$(base64 -d <<<"$CS_RELAY_PREFETCH_B64" 2>/dev/null | jq -c --argjson a "$argv" 'first(.[] | select(.argv == $a)) // empty' 2>/dev/null || true)
17
+ [ -n "$hit" ] && replay "$hit"
18
+ fi
19
+ [ -n "${CS_RELAY_BASE:-}" ] || { echo "relay unavailable: no relay (CS_RELAY_BASE)" >&2; exit 125; }
20
+ auth="authorization: Bearer ${CS_CRED_TOKEN:-}"
21
+ rid=$(jq -cn --argjson a "$argv" '{argv: $a}' | curl -fsS --max-time 30 -H "$auth" -H 'content-type: application/json' --data-binary @- "$CS_RELAY_BASE" | jq -r '.rid // empty') \
22
+ || { echo "relay unavailable: request failed" >&2; exit 125; }
23
+ [ -n "$rid" ] || { echo "relay unavailable: no request id" >&2; exit 125; }
24
+ deadline=$(( $(date +%s) + ${CS_RELAY_TIMEOUT_S:-300} ))
25
+ while [ "$(date +%s)" -lt "$deadline" ]; do
26
+ out=$(curl -fsS --max-time 30 -H "$auth" "$CS_RELAY_BASE/$rid") || { echo "relay unavailable: poll failed" >&2; exit 125; }
27
+ [ "$(jq -r '.state // empty' <<<"$out")" = done ] && replay "$out"
28
+ sleep 2
29
+ done
30
+ echo "relay unavailable: timed out after ${CS_RELAY_TIMEOUT_S:-300}s" >&2
31
+ exit 125