forgedock 1.8.1 → 1.8.2

package/docs/CODEX.md

@@ -48,6 +48,8 @@ Examples:
 | `commands/work-on/investigate.md` | `forge-work-on-investigate` |
 | `commands/work-on/build/context.md` | `forge-work-on-build-context` |
 
+Nested `Skill("{FORGE_SKILL_PREFIX}work-on:build")` references in the specs resolve under Codex to `forge-work-on-build` (prefix `forge-`, `-` nesting); see `Skill Name Resolution` in `commands/work-on.md`.
+
 `commands/review-pr-agents.md` is excluded because it is a read-on-demand catalog, not a standalone entrypoint.
 
 ## How the Adapter Works

package/docs/CONFIG.md

@@ -379,6 +379,14 @@ orchestration:
     # Number of consecutive merged-unit observations at ratio >= 1.0 before
     # printing a convergence warning. Default: 3.
     convergence_window: 3
+
+    # On-by-default amplification circuit breaker (forge#3060). Counts ALL
+    # cascade findings (new surface as well as same-lineage refinements). When
+    # the ratio stays >= 1.0 for convergence_window merged units, P3-and-below
+    # admission pauses, the operator gets a report (ratio + queue size), and the
+    # paused P3s wait for bounded P3 batches. P1/P2 are never affected, and
+    # `policy: all` / unlimited overrides do not disable it. "on" (default) | "off".
+    amplification_breaker: on
 ```
 
 | Field | Type | Required | Description |
@@ -394,6 +402,9 @@ orchestration:
 | `cascade.p3_same_file_defer` | boolean | No | Defer P3 findings sharing a file with the active batch. Default: `true` |
 | `cascade.max_amplification` | positive number or `"off"` | No | Opt-in ceiling for same-lineage refinement dispatch. Default: `"off"` |
 | `cascade.convergence_window` | positive integer | No | Consecutive ratio observations at or above 1.0 before warning. Default: 3 |
+| `cascade.amplification_breaker` | `on` \| `off` | No | Pause P3-and-below cascade admission while the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units. Counts all cascade findings (not only same-lineage); P1/P2 unaffected; independent of `cascade.policy`, so `policy: all` does not disable it. Paused P3s route to bounded P3 batches. Default: `on`. Opt out with `off` (boolean `false` is accepted as `off`, `true` as `on`). |
+
+**Upgrade note — `cascade.amplification_breaker` is on by default**: existing configs that do not set this key now get the breaker automatically. During a batch, once the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units (it can trip at exactly 1.0 over 3 units), P3-and-below cascade admission pauses; paused P3s are routed to bounded P3 batches rather than dispatched individually. P1/P2 are unaffected. To keep the previous behavior, set `orchestration.cascade.amplification_breaker: off` (or `false`). Release notes for the version that introduced this default should call out the change.
 
 **Hard invariant — not configurable**: safety exclusions (findings whose `## Problem` section indicates security/billing/anti-bot/auth concerns) are never batched and never auto-admitted by any `cascade.policy`, including `all`. That exclusion is enforced upstream of this section (the P3 batching eligibility check) and has no corresponding key here by design.
 

package/package.json

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

package/scripts/build-spec-graph.mjs

@@ -224,13 +224,14 @@ function commandNodeFromPath(rel) {
   };
 }
 
-/** Map a Skill(skill="X") target to a command node id. The skill name uses the
+/** Map a Skill(skill="X") target to a command node id (an optional leading
+ *  `{FORGE_SKILL_PREFIX}` namespace placeholder is stripped). The skill name uses the
  *  same `:`-delimited convention as our sub-phase names (e.g. "work-on:build").
  *  Specs also write the `/`-delimited form (e.g. "work-on/review"); normalize it
  *  to the colon form so both resolve to the same node (kept in sync with the
  *  dangling-ref check in validate-spec-graph.sh). */
 function skillTargetToId(skill) {
-  return `cmd:${skill.replace(/\//g, ":")}`;
+  return `cmd:${skill.replace(/^\{FORGE_SKILL_PREFIX\}/, "").replace(/\//g, ":")}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -325,6 +326,12 @@ function build() {
         }
       }
 
+      // WRITES via the protocol codec (forge#1727): `cli.js emit X` / `forge-annotation.sh write X`
+      // produce the `<!-- FORGE:X -->` opening tag that is then posted, so they count as writes.
+      for (const m of line.matchAll(/(?:cli\.js|forge-annotation\.sh)\s+(?:emit|write)\s+([A-Z][A-Z0-9_]*)\b/g)) {
+        addEdge(fromId, "WRITES", `ann:FORGE:${m[1]}`, { file: rel, line: li + 1 });
+      }
+
       // READS: command consumes a FORGE annotation.
       //   jq forms:  contains("FORGE:X"), contains("FORGE:X:"),
       //              test("<!-- FORGE:X: ..."), capture("<!-- FORGE:X: ...")
@@ -351,7 +358,7 @@ function build() {
       // Skill(skill="X"), and colon Skill(skill: "X") — with `/`-delimited
       // sub-phase targets and uppercase/leading-digit names. Kept in sync with
       // the dangling-ref check in validate-spec-graph.sh.
-      for (const m of line.matchAll(/Skill\(\s*(?:skill\s*[:=]\s*)?["']([A-Za-z0-9][A-Za-z0-9:_/-]*)["']/g)) {
+      for (const m of line.matchAll(/Skill\(\s*(?:skill\s*[:=]\s*)?["']((?:\{FORGE_SKILL_PREFIX\})?[A-Za-z0-9][A-Za-z0-9:_/-]*)["']/g)) {
         const targetId = skillTargetToId(m[1]);
         // Only link if the target resolves to a known command/sub-phase node.
         if (nodes.has(targetId)) {
@@ -457,7 +464,7 @@ function selfCheck(graph, quiet) {
 
   const hash = graph.graph.builtFromHash;
   const checks = [
-    ["work-on WRITES FORGE:TRAJECTORY", has("cmd:work-on", "WRITES", "ann:FORGE:TRAJECTORY")],
+    ["work-on:close WRITES FORGE:TRAJECTORY", has("cmd:work-on:close", "WRITES", "ann:FORGE:TRAJECTORY")],
     ["review-pr READS FORGE:CONTRACT", has("cmd:review-pr", "READS", "ann:FORGE:CONTRACT")],
     ["builtFromHash is a sha256 hex digest", typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash)],
   ];

package/scripts/check-spec-markers.sh

@@ -89,18 +89,21 @@ MARKER_REGISTRY="
   BLOCKED_ON_HUMAN_MERGE
   BODY
   BUILDER
+  BUILD_BLOCKED
   CALIBRATION_CHECK
   CARD
-  CLASS
   CHECKPOINT
+  CI_REMEDIATION
   CLAIM
   CLAIM_RELEASED
+  CLASS
   CONTEXT
   CONTRACT
   COORD_ISSUE
   CRITIQUE
   DECISION_RECORD
   DECOMPOSED
+  DECOMPOSE_BLOCKED
   DESIGN
   DISPATCH
   DISPATCHER
@@ -133,6 +136,9 @@ MARKER_REGISTRY="
   PATTERN
   PHASE
   PHASE_COMPLETE
+  PHASE_TRAIL_ERROR
+  PHASE_TRAIL_FAILED
+  PHASE_TRAIL_RELEASED
   PLAN_DAG
   PRIOR_DECISIONS
   PRIOR_GIST
@@ -140,6 +146,9 @@ MARKER_REGISTRY="
   PUSH_BLOCKED
   PUSH_BLOCKED_EMPTY_BRANCH
   PUSH_FAILED
+  QUALITY_GATE
+  RECOVERY_CLAIM
+  RECOVERY_CLAIM_RELEASED
   REMEDIATION
   REREVIEW_SKIPPED
   REVIEW
@@ -152,6 +161,7 @@ MARKER_REGISTRY="
   SPAWN_POLICY
   SPEC_DOCTOR_COMPLETE
   SPEC_LOADED
+  STALE_REREVIEW
   STALL_DETECTED
   STATE
   SYNTHESIS_BRIEF

package/scripts/checkbox-sections.test.sh

@@ -20,33 +20,18 @@ extract_classifier() {
 }
 
 CLOSE_BLOCK=$(extract_block "$ROOT/commands/work-on/close.md")
-INLINE_BLOCK=$(extract_block "$ROOT/commands/work-on.md")
-[[ "$CLOSE_BLOCK" == "$INLINE_BLOCK" ]] || {
-  printf 'FAIL: mirrored classifier blocks differ\n' >&2
-  exit 1
-}
-
+[ -n "$CLOSE_BLOCK" ] || { printf 'FAIL: close.md structural computation block not found\n' >&2; exit 1; }
 CLOSE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on/close.md")
-INLINE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on.md")
-[[ "$CLOSE_CLASSIFIER" == "$INLINE_CLASSIFIER" ]] || {
-  printf 'FAIL: mirrored classifier implementations differ\n' >&2
+[ -n "$CLOSE_CLASSIFIER" ] || { printf 'FAIL: close.md classifier not found\n' >&2; exit 1; }
+# close.md is the single owner of the classifier; the work-on.md router must not carry a copy.
+if grep -q '^FENCE_COUNT=' "$ROOT/commands/work-on.md"; then
+  printf 'FAIL: work-on.md (router) must not contain a copy of the close-path classifier\n' >&2
   exit 1
-}
-
-if grep -q 'echo "\$BODY\|echo "\$BODY_STRIPPED' \
-  "$ROOT/commands/work-on/close.md" "$ROOT/commands/work-on.md"; then
+fi
+if grep -q 'echo "\$BODY\|echo "\$BODY_STRIPPED' "$ROOT/commands/work-on/close.md"; then
   printf 'FAIL: arbitrary issue bodies must be piped with printf, not echo\n' >&2
   exit 1
 fi
-
-grep -Fq 'Keep the structural computation above and its consuming multi-phase guard' "$ROOT/commands/work-on.md" || {
-  printf 'FAIL: Phase 6A sync invariant must cover the consuming guard\n' >&2
-  exit 1
-}
-grep -Fq 'The guard is `CHECKBOX_SECTIONS >= 2 OR SUBISSUE_ITEMS > 0`' "$ROOT/commands/work-on.md" || {
-  printf 'FAIL: Phase 6A must document the Phase C1 guard\n' >&2
-  exit 1
-}
 grep -Fq 'if [ "${CHECKBOX_SECTIONS:-0}" -ge 2 ] || [ "${SUBISSUE_ITEMS:-0}" -gt 0 ]; then' "$ROOT/commands/work-on/close.md" || {
   printf 'FAIL: Phase C1 multi-phase guard changed unexpectedly\n' >&2
   exit 1
@@ -64,4 +49,4 @@ SINGLE_BODY=$'## Acceptance Criteria\n- [ ] complete this work'
   exit 1
 }
 
-printf 'PASS: mirrored classifier supports setext section boundaries\n'
+printf 'PASS: close-path classifier supports setext section boundaries\n'

package/scripts/extract-affected-files.sh

@@ -83,7 +83,10 @@
 
 set -euo pipefail
 
-EXT_REGEX='`[^`]*\.(py|tsx?|jsx?|sql|json|ya?ml|mjs|js|sh|md)`'
+# An optional line-reference suffix is accepted and stripped: review findings cite
+# `file.md:211`, `file.sh:104-114,162` or `file.md:~1685`, which the strict form missed,
+# leaving every finding-batch DAG on the low-confidence body fallback (field test).
+EXT_REGEX='`[^`]*\.(py|tsx?|jsx?|sql|json|ya?ml|mjs|js|sh|md)(:~?[0-9][0-9,~-]*)?`'
 
 # --------------------------------------------------------------------------- #
 # Argument parsing — mirrors scripts/issue-dedup.sh's -R / -R\ * case arms
@@ -190,7 +193,7 @@ extract_paths() {
   # locales` otherwise) — a portability trap the original inline pseudocode
   # in phase-3-dependency.md carried (forge#2436) and that this script fixes
   # by not needing PCRE at all.
-  grep -oE "$EXT_REGEX" <<< "$1" 2>/dev/null | tr -d '`' | sort -u || true
+  grep -oE "$EXT_REGEX" <<< "$1" 2>/dev/null | tr -d '`' | sed -E 's/:~?[0-9][0-9,~-]*$//' | sort -u || true
 }
 
 PROVENANCE="none"

package/scripts/extract-affected-files.test.sh

@@ -472,6 +472,33 @@ MOCK_GH_CONTRACT_FAIL=1 MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
 
 unset MOCK_GH_CONTRACT_FAIL
 
+# --------------------------------------------------------------------------- #
+# Line-reference suffixes (field test, orchestrate #3149 / stress batch): review
+# findings cite paths as `file:line`, `file:a-b,c` or `file:~n`. Those must be
+# extracted with the suffix stripped, and the same file cited twice deduplicated.
+# --------------------------------------------------------------------------- #
+BODY_LINESUFFIX="$TMP_FIXTURES/body-linesuffix.md"
+cat > "$BODY_LINESUFFIX" <<'EOF'
+## Problem
+
+Gate trusts agent-chosen band.
+
+## Affected Files
+
+1. `scripts/verify-phase-trail.sh:211` — band not cross-checked
+2. `scripts/verify-phase-trail.sh:104-114,162` — pagination
+3. `commands/orchestrate/phase-4-execution.md:~1685` — completion check
+4. `commands/work-on/build/validate.md:433` — QG PASS not SHA-bound
+
+## Source Branch Context
+
+**Code branch**: `staging`
+EOF
+unset MOCK_GH_COMMENTS
+MOCK_GH_BODY="$BODY_LINESUFFIX" assert_output \
+  "line-reference suffixes are stripped and deduplicated" \
+  "body-fallback" "commands/orchestrate/phase-4-execution.md,commands/work-on/build/validate.md,scripts/verify-phase-trail.sh" 2390 -R test/repo
+
 # --------------------------------------------------------------------------- #
 # Summary
 # --------------------------------------------------------------------------- #

package/scripts/forge-root.test.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# forge-root.test.sh — guards the canonical FORGE_ROOT bootstrap (forge#3098).
+# Plugin installs set neither FORGEDOCK_HOME nor FORGE_HOME; the specs must resolve ForgeDock's OWN
+# install root (never the consumer repo) and fail closed when it cannot be found.
+# Usage: bash scripts/forge-root.test.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"; ROOT="$HERE/.."
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+expect() { [ "$2" = "$3" ] && ok || bad "$1 (got '$3' want '$2')"; }
+
+SITES="commands/work-on.md commands/work-on/review.md commands/work-on/investigate.md commands/work-on/decompose.md commands/work-on/build.md commands/work-on/close.md commands/review-pr.md commands/orchestrate/phase-1-resolve.md commands/orchestrate/phase-4-execution.md"
+
+# extract the bootstrap block (comment line .. closing top-level fi), indentation stripped
+# Block ends at the first line (after the marker) that starts with `fi` at the marker's own indentation.
+# extract <file> <n> prints the n-th (1-based) bootstrap copy in the file.
+extract() { awk -v want="$2" '/# FORGE_ROOT bootstrap/{c++; if(c==want){f=1; match($0,/^[ ]*/); ind=RLENGTH}} f{l=$0; sub(/^[ ]+/,"",l); print l} f&&match($0,/^[ ]*fi$/)&&RLENGTH-2==ind{exit}' "$ROOT/$1"; }
+count_copies() { grep -c '# FORGE_ROOT bootstrap' "$ROOT/$1"; }
+extract commands/work-on.md 1 > "$T/canon"
+[ -s "$T/canon" ] && ok || bad "canonical bootstrap not found in work-on.md"
+# Expected copies per file are DERIVED from the number of FORGE_ROOT resolution loops
+# (`FORGE_ROOT="$_c"` lines) so adding a site never needs a hardcoded count here; count_copies
+# (marker comments) must still agree with it, which catches a loop pasted without its marker.
+want_copies() { grep -c 'FORGE_ROOT="\$_c"' "$ROOT/$1"; }
+for f in $SITES; do
+  n=$(count_copies "$f"); expect "exact bootstrap copy count in $f" "$(want_copies "$f")" "$n"
+  i=1
+  while [ "$i" -le "$n" ]; do   # compare EVERY copy
+    extract "$f" "$i" > "$T/s"
+    cmp -s "$T/canon" "$T/s" && ok || bad "bootstrap copy $i in $f differs from canonical"
+    i=$((i+1))
+  done
+done
+# the canonical block must not contain the stale lexical glob / unfiltered marketplaces glob
+grep -v '^[[:space:]]*#' "$T/canon" > "$T/canon.code"   # code only: the comments name the banned constructs
+grep -qE 'mapfile|readarray|declare -A|sort[^|]* -[a-zA-Z]*V' "$T/canon.code" && bad "canonical bootstrap uses a bash-4+/non-portable construct" || ok
+grep -q 'sort -k1,1nr -k2,2nr -k3,3nr' "$T/canon.code" && ok || bad "canonical bootstrap lacks numeric component version sort"
+grep -qF 'marketplaces/*; do' "$T/canon" && bad "canonical bootstrap globs all marketplaces" || ok
+# review.md must hard-exit on an unreadable trail
+grep -qE 'TRAIL_RC.* -ge 2 .*exit 1' "$ROOT/commands/work-on/review.md" && ok || bad "work-on/review.md lacks hard exit guard for TRAIL_RC>=2"
+# behavioral: execute the guard line itself. rc>=2 => BLOCKED on STDOUT + exit 1; rc 0/1 => falls through.
+grep -E 'TRAIL_RC.* -ge 2 .*exit 1' "$ROOT/commands/work-on/review.md" | head -1 > "$T/guard"
+for rc in 2 127; do
+  out=$(TRAIL_RC=$rc bash -c "$(cat "$T/guard")" 2>/dev/null); grc=$?
+  expect "review guard exits 1 for TRAIL_RC=$rc" 1 "$grc"
+  # The guard prints the full REVIEW_RESULT block (multi-line) to STDOUT.
+  expect "review guard prints REVIEW_RESULT block for TRAIL_RC=$rc" "REVIEW_RESULT:|  status: BLOCKED|  blocker: phase trail unreadable (rc=$rc)" "$(printf '%s\n' "$out" | grep -E '^(REVIEW_RESULT:|  status:|  blocker:)' | paste -sd'|' -)"
+done
+for rc in 0 1; do
+  out=$(TRAIL_RC=$rc bash -c "$(cat "$T/guard"); echo passed" 2>&1); expect "review guard falls through for TRAIL_RC=$rc" passed "$out"
+done
+
+# no consumer-repo fallback / fail-open remains in the gates
+for f in $SITES; do
+  grep -nE 'FORGE_HOME:-\$?\{?\{?REPO_PATH\}*/scripts' "$ROOT/$f" >/dev/null && bad "repo-path fallback in $f" || ok
+done
+for f in commands/review-pr.md commands/work-on/review.md; do
+  grep -nE '^[[:space:]]*TRAIL_RC=0[[:space:]]*$' "$ROOT/$f" >/dev/null && bad "fail-open TRAIL_RC=0 in $f" || ok
+done
+
+run() { # run <home> [env assignments...] -> prints FORGE_ROOT
+  # CLAUDE_PLUGIN_ROOT=<v> is NOT an env var in a real session: Claude Code substitutes the literal
+  # text ${CLAUDE_PLUGIN_ROOT} when it loads a plugin spec. Simulate exactly that; every other
+  # assignment is passed through as environment.
+  local h="$1"; shift; local code; code="$(cat "$T/canon")"; local a; local envs=()
+  for a in "$@"; do
+    case "$a" in
+      CLAUDE_PLUGIN_ROOT=*) code="$(printf '%s' "$code" | awk -v v="${a#CLAUDE_PLUGIN_ROOT=}" '{gsub(/\$\{CLAUDE_PLUGIN_ROOT\}/, v); print}')" ;;
+      *) envs+=("$a") ;;
+    esac
+  done
+  ( cd "$T/consumer" && env -i PATH="$PATH" HOME="$h" ${envs[@]+"${envs[@]}"} "$SH" -c "$code; printf %s \"\$FORGE_ROOT\"" )
+}
+# Run the behavioral cases under every available shell: bash always, zsh when installed (macOS ships it;
+# zsh aborts on an unmatched glob, which the bootstrap must not trigger). FORGE_ROOT_TEST_SHELLS overrides.
+SHELLS="${FORGE_ROOT_TEST_SHELLS:-bash}"
+if [ -z "${FORGE_ROOT_TEST_SHELLS:-}" ] && command -v zsh >/dev/null 2>&1; then SHELLS="bash zsh"; fi
+for SH in $SHELLS; do
+echo "== bootstrap behavior under: $SH"
+mkdir -p "$T/consumer/scripts"; : > "$T/consumer/scripts/verify-phase-trail.sh"   # hostile/lookalike consumer repo
+mkscripts() {
+  mkdir -p "$1/scripts" "$1/bin/engine"
+  : > "$1/scripts/verify-phase-trail.sh"; : > "$1/scripts/lint-dispatch-prompt.sh"; : > "$1/scripts/is-docs-only.sh"
+  : > "$1/bin/engine/resolve.mjs"; : > "$1/bin/engine/orchestrate-canary.mjs"; : > "$1/bin/engine/admission.mjs"
+}
+# plugin install: no env vars at all
+mkscripts "$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0"
+expect "plugin cache resolves with no env" "$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0" "$(run "$T/h1")"
+expect "CLAUDE_PLUGIN_ROOT resolves" "$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0" "$(run "$T/empty" CLAUDE_PLUGIN_ROOT="$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0")"
+# nothing installed: empty (never the consumer repo, never a relative path)
+expect "unresolvable stays empty" "" "$(run "$T/empty")"
+expect "relative FORGE_HOME ignored" "" "$(run "$T/empty" FORGE_HOME=.)"
+# explicit FORGEDOCK_HOME is authoritative, even if bogus (caller then fails closed)
+expect "FORGEDOCK_HOME authoritative" "$T/nowhere" "$(run "$T/h1" FORGEDOCK_HOME="$T/nowhere")"
+# symlink install (install.sh): ~/.claude/commands/work-on.md -> <clone>/commands/work-on.md
+mkdir -p "$T/clone/commands" "$T/h2/.claude/commands"; mkscripts "$T/clone"; : > "$T/clone/commands/work-on.md"
+ln -sf "$T/clone/commands/work-on.md" "$T/h2/.claude/commands/work-on.md"
+expect "install.sh symlink resolves" "$(cd "$T/clone" && pwd -P)" "$(cd "$(run "$T/h2")" && pwd -P)"
+expect "FORGE_HOME without scripts falls through" "$(cd "$T/clone" && pwd -P)" "$(cd "$(run "$T/h2" FORGE_HOME="$T/h2/.claude")" && pwd -P)"
+
+# newest cached version wins (1.10.0 must beat 1.9.0)
+for v in 1.9.0 1.10.0 1.2.0; do mkscripts "$T/h3/.claude/plugins/cache/mk/forgedock/$v"; done
+expect "newest cached version wins" "$T/h3/.claude/plugins/cache/mk/forgedock/1.10.0" "$(run "$T/h3")"
+# HOME containing a space still resolves
+mkscripts "$T/sp ace/.claude/plugins/cache/mk/forgedock/2.0.0"
+expect "space in HOME resolves" "$T/sp ace/.claude/plugins/cache/mk/forgedock/2.0.0" "$(run "$T/sp ace")"
+# relative FORGEDOCK_HOME / CLAUDE_PLUGIN_ROOT rejected (fail closed => empty)
+expect "relative FORGEDOCK_HOME rejected" "" "$(run "$T/h1" FORGEDOCK_HOME=scripts/..)"
+expect "relative CLAUDE_PLUGIN_ROOT ignored" "" "$(run "$T/empty" CLAUDE_PLUGIN_ROOT=../consumer)"
+# a candidate with only one of the two needed scripts is rejected
+mkdir -p "$T/h4/.claude/plugins/cache/mk/forgedock/1.0.0/scripts"; : > "$T/h4/.claude/plugins/cache/mk/forgedock/1.0.0/scripts/verify-phase-trail.sh"
+expect "partial install (missing lint script) rejected" "" "$(run "$T/h4")"
+# stale install: has the two original gate scripts but lacks is-docs-only.sh / engine modules => rejected
+for missing in scripts/is-docs-only.sh bin/engine/resolve.mjs bin/engine/orchestrate-canary.mjs bin/engine/admission.mjs; do
+  rm -rf "$T/h12"; mkscripts "$T/h12/.claude/plugins/cache/mk/forgedock/1.0.0"; rm -f "$T/h12/.claude/plugins/cache/mk/forgedock/1.0.0/$missing"
+  expect "stale install missing $missing rejected" "" "$(run "$T/h12")"
+done
+# a stale newest version is skipped in favor of a complete older one
+rm -rf "$T/h13"; mkscripts "$T/h13/.claude/plugins/cache/mk/forgedock/1.0.0"; mkscripts "$T/h13/.claude/plugins/cache/mk/forgedock/2.0.0"
+rm -f "$T/h13/.claude/plugins/cache/mk/forgedock/2.0.0/scripts/is-docs-only.sh"
+expect "stale newest skipped for complete older" "$T/h13/.claude/plugins/cache/mk/forgedock/1.0.0" "$(run "$T/h13")"
+# non-ForgeDock marketplace dirs are ignored; ForgeDock-named ones resolve
+mkscripts "$T/h5/.claude/plugins/marketplaces/other-tool"
+expect "non-ForgeDock marketplace ignored" "" "$(run "$T/h5")"
+mkscripts "$T/h6/.claude/plugins/marketplaces/forgedock"
+expect "forgedock marketplace resolves" "$T/h6/.claude/plugins/marketplaces/forgedock" "$(run "$T/h6")"
+
+# release outranks its own pre-release; a newer pre-release core still beats an older release
+rm -rf "$T/h7"   # fixture is mutated below; reset per shell
+mkscripts "$T/h7/.claude/plugins/cache/mk/forgedock/1.9.0-rc1"; mkscripts "$T/h7/.claude/plugins/cache/mk/forgedock/1.9.0"
+expect "release beats its pre-release" "$T/h7/.claude/plugins/cache/mk/forgedock/1.9.0" "$(run "$T/h7")"
+mkscripts "$T/h7/.claude/plugins/cache/mk/forgedock/2.0.0-rc1"
+expect "newer-core pre-release beats older release" "$T/h7/.claude/plugins/cache/mk/forgedock/2.0.0-rc1" "$(run "$T/h7")"
+# version component decides, not the marketplace name (zz sorts after aa lexically but holds the older version)
+mkscripts "$T/h8/.claude/plugins/cache/zz-market/forgedock/1.0.0"; mkscripts "$T/h8/.claude/plugins/cache/aa-market/forgedock/1.1.0"
+expect "version beats marketplace name" "$T/h8/.claude/plugins/cache/aa-market/forgedock/1.1.0" "$(run "$T/h8")"
+# a non-forgedock plugin in the cache is ignored even with a higher version
+mkscripts "$T/h9/.claude/plugins/cache/mk/otherplugin/9.9.9"; mkscripts "$T/h9/.claude/plugins/cache/mk/forgedock/1.0.0"
+expect "non-forgedock cache plugin ignored" "$T/h9/.claude/plugins/cache/mk/forgedock/1.0.0" "$(run "$T/h9")"
+# unmatched globs: empty cache dir, absent marketplaces dir, absent ~/.claude entirely (must not abort under zsh)
+mkdir -p "$T/h10/.claude/plugins/cache"
+expect "empty cache, no match, no abort" "" "$(run "$T/h10")"
+expect "no ~/.claude at all, no abort" "" "$(run "$T/empty")"
+expect "unmatched glob does not break later candidates" "$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0" "$(run "$T/h10" CLAUDE_PLUGIN_ROOT="$T/h1/.claude/plugins/cache/mk/forgedock/1.0.0")"
+# plugin root (textually substituted) outranks an exported FORGE_HOME that also has the scripts:
+# the running plugin's own files win over a stale clone named by a global env var (forge#3147 field test)
+mkscripts "$T/h11/stale-clone"; mkscripts "$T/h11/running-plugin"
+expect "substituted plugin root beats FORGE_HOME" "$T/h11/running-plugin" "$(run "$T/h11" FORGE_HOME="$T/h11/stale-clone" CLAUDE_PLUGIN_ROOT="$T/h11/running-plugin")"
+# unsubstituted placeholder (non-Claude runtime) is a literal, rejected by the /* check, never expanded
+expect "unsubstituted placeholder ignored, FORGE_HOME used" "$T/h11/stale-clone" "$(run "$T/h11" FORGE_HOME="$T/h11/stale-clone")"
+expect "unsubstituted placeholder safe under set -u" "" "$( cd "$T/consumer" && env -i PATH="$PATH" HOME="$T/empty" "$SH" -c "set -u; $(cat "$T/canon"); printf %s \"\$FORGE_ROOT\"" 2>&1 )"
+# the env var alone (no substitution) must NOT be relied on: Claude Code does not export it to Bash
+expect "CLAUDE_PLUGIN_ROOT env var alone is not a candidate" "" "$( cd "$T/consumer" && env -i PATH="$PATH" HOME="$T/empty" CLAUDE_PLUGIN_ROOT="$T/h11/running-plugin" "$SH" -c "$(cat "$T/canon"); printf %s \"\$FORGE_ROOT\"" )"
+done
+# the canonical block must use the exact substitutable spelling, single-quoted (no :- form, which Claude Code leaves verbatim)
+grep -qF "'\${CLAUDE_PLUGIN_ROOT}'" "$T/canon.code" && ok || bad "canonical bootstrap lacks the substitutable '\${CLAUDE_PLUGIN_ROOT}' candidate"
+grep -qF 'CLAUDE_PLUGIN_ROOT:-' "$T/canon.code" && bad "canonical bootstrap uses \${CLAUDE_PLUGIN_ROOT:-}, which Claude Code never substitutes" || ok
+
+# no hand-built file:// URL from FORGE_ROOT remains; imports go through pathToFileURL (a '#', '?' or space in the path must survive)
+for f in $SITES commands/work-on/close.md; do
+  grep -nE 'file://\$\{?(FORGE_ROOT|\(pwd\))' "$ROOT/$f" >/dev/null && bad "concatenated file:// URL in $f" || ok
+done
+if command -v node >/dev/null 2>&1; then
+  for d in "we#ird" "sp ace" "q?x"; do
+    mkdir -p "$T/url/$d/bin/engine"; echo 'export const v = 42;' > "$T/url/$d/bin/engine/resolve.mjs"
+    out=$(node -e 'import(require("node:url").pathToFileURL(process.argv[1]).href).then(m => process.stdout.write(String(m.v)))' "$T/url/$d/bin/engine/resolve.mjs" 2>&1)
+    expect "pathToFileURL import survives path '$d'" 42 "$out"
+  done
+fi
+
+echo "forge-root tests: pass=$PASS fail=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/is-docs-only.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# is-docs-only.sh — the single docs-only predicate shared by review-pr.md Phase 8,
+# work-on/review.md R1.5 and orchestrate/phase-4-execution.md (forge#3134, forge#3145).
+# Reads a newline-separated changed-file list on stdin. Callers MUST feed BOTH sides of every rename
+# (git diff --no-renames, or filename + previous_filename from the PR files API): a rename-collapsed
+# list hides the source path of a file moved into docs/.
+# Exit 0 iff the list is non-empty and EVERY path is a Markdown file that is positively allowlisted AND
+# is not executable pipeline/agent instruction content:
+#   - only *.md counts (docs/** non-markdown assets do NOT); matching is case-insensitive, leading ./ ignored
+#   - allowlist (unknown paths fail closed): docs/**/*.md, or a root-level README*/CHANGELOG*/CONTRIBUTING/SECURITY/GOVERNANCE *.md
+#   - any ".." path segment is rejected
+#   - excluded at ANY depth (even under docs/): commands/, devdocs/, templates/, skills/, agents/, hooks/,
+#     .claude/, .claude-plugin/, .agents/, .codex/, .cursor/, .github/, .opencode/, .gemini/, .kiro/ directories
+#   - excluded at ANY depth by exact basename: agents.md, claude.md, claude.local.md, skill.md, gemini.md
+#     (and dotted variants such as AGENTS.override.md); docs like skillset.md or agents-guide.md are fine
+# Exit 1 otherwise (including empty input: fail closed).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+awk '
+  NF==0 {next}
+  { n++; p=tolower($0); sub(/^\.\//, "", p) }
+  !(p ~ /\.md$/) {bad=1; next}
+  p ~ /(^|\/)\.\.(\/|$)/ {bad=1; next}
+  p ~ /(^|\/)(commands|devdocs|templates|skills|agents|hooks|\.claude|\.claude-plugin|\.agents|\.codex|\.cursor|\.github|\.opencode|\.gemini|\.kiro)\// {bad=1; next}
+  p ~ /(^|\/)(agents|claude|skill|gemini)(\.[^\/]*)?\.md$/ {bad=1; next}
+  p ~ /^docs\/.+\.md$/ {next}
+  p ~ /^(readme|changelog)[^\/]*\.md$/ {next}
+  p ~ /^(contributing|security|governance)\.md$/ {next}
+  {bad=1}
+  END{exit (bad || n==0)}
+'

package/scripts/is-docs-only.test.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# is-docs-only.test.sh — cases for scripts/is-docs-only.sh (forge#3134).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/is-docs-only.sh"
+PASS=0; FAILN=0
+t() { # name want files...
+  local name="$1" want="$2"; shift 2
+  printf '%s\n' "$@" | bash "$S"; local rc=$?
+  if [ "$rc" = "$want" ]; then PASS=$((PASS+1)); else FAILN=$((FAILN+1)); echo "FAIL: $name (rc=$rc want $want)"; fi
+}
+t "docs md" 0 docs/a.md README.md docs/sub/b.md
+t "root AGENTS.md" 1 AGENTS.md
+t "root CLAUDE.md" 1 docs/a.md CLAUDE.md
+t "nested AGENTS.md" 1 sub/AGENTS.md
+t "nested CLAUDE.md" 1 pkg/x/CLAUDE.md
+t ".codex md" 1 .codex/x.md
+t "SKILL.md" 1 skills/a/SKILL.md
+t ".github md" 1 .github/x.md
+t ".agents md" 1 .agents/skills/x.md
+t ".claude md" 1 .claude/x.md
+t "commands md" 1 commands/work-on.md
+t "nested commands md" 1 pkg/commands/x.md
+t "docs non-md" 1 docs/diagram.png
+t "docs yml" 1 docs/a.md docs/site/mkdocs.yml
+t "code file" 1 docs/a.md bin/x.mjs
+t "empty" 1
+t "blank only" 1 "" ""
+t "case agents.md" 1 agents.md
+t "case Skill.md" 1 Skill.md
+t "case Commands dir" 1 Commands/x.md
+t "case .GitHub" 1 .GitHub/x.md
+t "CLAUDE.local.md" 1 CLAUDE.local.md
+t "GEMINI.md" 1 GEMINI.md
+t ".cursor rules" 1 .cursor/rules/x.md
+t "hooks md" 1 hooks/README.md
+t ".claude-plugin" 1 .claude-plugin/x.md
+t "upper .MD (case-insensitive markdown)" 0 docs/a.MD
+t "leading ./ docs" 0 ./docs/a.md
+t "leading ./ excluded" 1 ./commands/x.md
+t "docs traversal" 1 docs/../commands/x.md
+t "valid + blank lines" 0 docs/a.md "" README.md
+t "rename pair (source in commands/)" 1 commands/x.md docs/x.md
+t "rename collapsed dest only (caller bug, predicate alone cannot see)" 0 docs/x.md
+t "devdocs md" 1 devdocs/agent/custom-instructions.md
+t "templates devdocs agent md" 1 templates/devdocs/agent/x.md
+t ".opencode md" 1 .opencode/x.md
+t ".gemini md" 1 .gemini/x.md
+t ".kiro md" 1 .kiro/steering/x.md
+t "skills dir md" 1 skills/a/readme.md
+t "templates md" 1 templates/x.md
+t "unknown dir md fails closed" 1 notes/x.md
+t "nested unknown README fails closed" 1 pkg/README.md
+t "docs/skillset.md accepted" 0 docs/skillset.md
+t "docs/Agents-guide.md accepted" 0 docs/Agents-guide.md
+t "docs/AGENTS.md rejected" 1 docs/AGENTS.md
+t "AGENTS.override.md rejected" 1 AGENTS.override.md
+t "docs/skill.md rejected" 1 docs/skill.md
+t "root CHANGELOG" 0 CHANGELOG.md
+t "root CONTRIBUTING" 0 CONTRIBUTING.md
+t "docs under devdocs-named dir" 1 docs/devdocs/x.md
+echo "is-docs-only: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]