forgedock 1.16.2 → 1.18.0

package/scripts/review-roster.test.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Tests for scripts/review-roster.sh (risk-tiered reviewer roster, forge#3599): the tier cases, the path triggers that
+# escalate in every tier, and the regression table of the 13 review-driven holds. Run: bash scripts/review-roster.test.sh
+# (bash 3.2 compatible)
+#
+# Hold table fixture: the changed-line count, file count and file list of each PR, the PR's linked-issue lineage, and
+# the reviewers whose posted findings were CRITICAL or BLOCKER on it (from the FORGE:REVIEW-AGENT comments). The
+# regression gate: at least one catching reviewer stays selected on every hold, and the sole catcher always does.
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+SCRIPT="$DIR/review-roster.sh"
+pass=0; fail=0
+ok() { pass=$((pass+1)); }
+bad() { fail=$((fail+1)); echo "FAIL: $1"; }
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/review-roster.XXXXXX")
+trap 'rm -rf "$WORK"' EXIT
+
+SEL=""; TIER=""; REASON=""
+# run <files, newline separated> <review-roster flags...>
+run() {
+  printf '%s\n' "$1" > "$WORK/files"; shift
+  out=$(bash "$SCRIPT" --files-file "$WORK/files" "$@") || { bad "script exited non-zero for: $*"; return 1; }
+  SEL=$(printf '%s\n' "$out" | sed -n 's/^SELECTED_AGENTS=//p')
+  TIER=$(printf '%s\n' "$out" | sed -n 's/^TIER=//p')
+  REASON=$(printf '%s\n' "$out" | sed -n 's/^REASON=//p')
+}
+has() { case " $SEL " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
+expect_sel() { if [ "$SEL" = "$2" ]; then ok; else bad "$1: roster '$SEL', want '$2' (tier $TIER; $REASON)"; fi; }
+expect_has() { if has "$2"; then ok; else bad "$1: '$2' missing from '$SEL' (tier $TIER; $REASON)"; fi; }
+expect_not() { if has "$2"; then bad "$1: '$2' should not be in '$SEL' (tier $TIER)"; else ok; fi; }
+expect_tier() { if [ "$TIER" = "$2" ]; then ok; else bad "$1: tier '$TIER', want '$2'"; fi; }
+
+SC_QUIET="AUTH=0 BILLING=0 CONCURRENCY=0 DATABASE=0 INFRA=0 SECURITY=1 SCRAPING=0 FRONTEND=0 API=0"
+SC_NOISY="AUTH=3 BILLING=1 CONCURRENCY=0 DATABASE=1 INFRA=3 SECURITY=4 SCRAPING=0 FRONTEND=2 API=2"
+SC_BUSY="AUTH=3 BILLING=3 CONCURRENCY=3 DATABASE=3 INFRA=3 SECURITY=1 SCRAPING=0 FRONTEND=2 API=2"
+
+# Case 1: a small diff gives Security only, even when diff-text scores are loud
+run "commands/foo.md" --scores "$SC_NOISY" --changed-lines 40 --changed-files 1
+expect_sel "small diff" "security"; expect_tier "small diff" small
+run "scripts/a.sh
+scripts/b.sh" --scores "$SC_NOISY" --changed-lines 60 --changed-files 2
+expect_sel "60-line boundary" "security"
+# a single file is small up to 150 lines, not beyond
+run "scripts/a.sh" --scores "$SC_QUIET" --changed-lines 120 --changed-files 1
+expect_tier "single file" small
+run "scripts/a.sh" --scores "$SC_QUIET" --changed-lines 400 --changed-files 1
+expect_tier "single large file" standard
+
+# Case 2: a small diff touching bin/engine/** adds concurrency and spec-cli
+run "bin/engine/phases.mjs" --scores "$SC_QUIET" --changed-lines 30 --changed-files 1 --spec-cli true
+expect_has "small bin/engine" concurrency; expect_has "small bin/engine" spec-cli; expect_has "small bin/engine" security; expect_tier "small bin/engine" small
+run "bin/engine/phases.mjs" --scores "$SC_QUIET" --changed-lines 30 --changed-files 1 --spec-cli false
+expect_has "consumer repo bin/engine" concurrency; expect_not "consumer repo bin/engine" spec-cli
+
+# Case 3: a fix PR gives Security only
+run "commands/orchestrate/phase-4-execution.md
+commands/work-on.md" --scores "$SC_NOISY" --changed-lines 200 --changed-files 2 --fix-pr true --source-severity MEDIUM
+expect_sel "fix PR" "security"; expect_tier "fix PR" fix-pr
+
+# Case 4: a fix PR whose source finding was HIGH adds the domain agent
+run "commands/work-on.md" --scores "AUTH=0 BILLING=0 CONCURRENCY=2 DATABASE=0 INFRA=0 FRONTEND=0 API=0" --changed-lines 40 --fix-pr true --source-severity HIGH --source-domain Concurrency
+expect_sel "fix PR, HIGH source finding" "security concurrency"
+run "commands/work-on.md" --scores "AUTH=0 BILLING=0 CONCURRENCY=2 DATABASE=0 INFRA=0 FRONTEND=0 API=0" --changed-lines 40 --fix-pr true --source-severity critical
+expect_sel "fix PR, CRITICAL source, top domain" "security concurrency"
+
+# Case 5: CONTRACT HIGH_RISK escalates in every tier
+for tier_args in "--changed-lines 30 --changed-files 1" "--changed-lines 100" "--changed-lines 400" "--changed-lines 30 --fix-pr true"; do
+  # shellcheck disable=SC2086
+  run "svc/x.py" --scores "$SC_QUIET" $tier_args --contract-flags "HIGH_RISK CONTRACT_AUTH CONTRACT_BILLING"
+  expect_has "HIGH_RISK ($tier_args)" auth; expect_has "HIGH_RISK ($tier_args)" billing; expect_has "HIGH_RISK ($tier_args)" concurrency
+done
+run "svc/x.py" --scores "$SC_QUIET" --changed-lines 30 --contract-flags "CONTRACT_AUTH"
+expect_not "CONTRACT_AUTH without HIGH_RISK" auth
+
+# Case 6: --thorough and milestone give the full union
+run "svc/x.py" --scores "$SC_BUSY" --changed-lines 10 --thorough true
+expect_tier "thorough" full
+for d in security auth billing concurrency database infra frontend api; do expect_has "thorough" "$d"; done
+expect_not "thorough, scraping not configured" scraper
+run "svc/x.py" --scores "$SC_BUSY SCRAPING=3" --changed-lines 10 --milestone true --scraping-configured true
+expect_tier "milestone" full; expect_has "milestone" scraper
+
+# Path gates: auth and infra only by path; the other path triggers fire in the small tier
+run "svc/app/routers/session.py" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "auth path" auth
+run "scripts/trusted-comments.sh" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "trust-filter path" auth
+run "commands/review-pr.md" --scores "AUTH=3 INFRA=3 DATABASE=0 BILLING=0 CONCURRENCY=0" --changed-lines 120
+expect_not "auth from prose score alone" auth; expect_not "infra from prose score alone" infra
+run ".github/workflows/ci.yml" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "infra path" infra
+run "docker-compose.prod.yml" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "docker path" infra
+run "db/migrations/0042_add.sql" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "migration path" database
+run "sdk/node/src/index.ts" --scores "$SC_QUIET" --changed-lines 20 --changed-files 1
+expect_has "sdk path" api
+run "svc/x.py" --scores "AUTH=2 BILLING=2" --changed-lines 20 --changed-files 1
+expect_has "cross-critical" auth; expect_has "cross-critical" billing
+run "svc/x.py" --scores "BILLING=3 CONCURRENCY=3" --changed-lines 20 --changed-files 1 --churn true
+expect_has "churn hot-spot top domain" billing
+run "svc/x.py" --scores "BILLING=3" --changed-lines 20 --changed-files 2
+expect_not "billing score in small tier" billing
+run "svc/x.py
+svc/y.py" --scores "BILLING=3" --changed-lines 100
+expect_has "billing score in medium tier" billing; expect_has "billing score in medium tier" concurrency
+
+# Tier shape: standard keeps the top-2 baseline, medium does not
+run "web/src/app/a.tsx
+web/src/b.tsx" --scores "FRONTEND=3 API=2 BILLING=1 DATABASE=1" --changed-lines 300
+expect_tier "standard" standard; expect_has "standard" frontend; expect_has "standard" api; expect_not "standard top-2 only" billing
+run "web/src/app/a.tsx
+web/src/b.tsx" --scores "FRONTEND=3 API=2" --changed-lines 100
+expect_sel "medium has no baseline" "security"
+run "svc/x.py" --scores "FRONTEND=3" --changed-lines ""
+expect_tier "unknown size" standard; expect_has "unknown size" frontend
+run "commands/x.md
+commands/y.md" --scores "$SC_QUIET" --changed-lines 300 --spec-cli true
+expect_has "standard commands/** adds spec-cli" spec-cli
+run "commands/x.md
+commands/y.md" --scores "$SC_QUIET" --changed-lines 100 --spec-cli true
+expect_not "medium commands/** has no spec-cli" spec-cli
+
+# Roster output is canonical and duplicate free
+run "bin/engine/a.mjs
+.github/workflows/a.yml" --scores "$SC_BUSY" --changed-lines 300 --spec-cli true
+n=$(printf '%s' "$SEL" | tr ' ' '\n' | grep -c .); u=$(printf '%s' "$SEL" | tr ' ' '\n' | sort -u | grep -c .)
+if [ "$n" -eq "$u" ]; then ok; else bad "duplicate roster entries in '$SEL'"; fi
+case "$SEL" in *[A-Z]*) bad "non-canonical roster '$SEL'" ;; *) ok ;; esac
+
+# Unknown flag fails (callers fall back to the full union)
+if bash "$SCRIPT" --bogus 1 >/dev/null 2>&1; then bad "unknown flag accepted"; else ok; fi
+
+# Regression table: the 13 review-driven holds. Columns: PR | lines | files | fix-PR | catchers (CRITICAL/BLOCKER) | sole catcher | file list
+hold() {
+  pr="$1"; lines="$2"; nf="$3"; fixpr="$4"; catchers="$5"; sole="$6"; files="$7"
+  run "$(printf '%s' "$files" | tr ' ' '\n')" --scores "$SC_QUIET" --changed-lines "$lines" --changed-files "$nf" --fix-pr "$fixpr" --spec-cli true
+  found=""
+  for c in $catchers; do has "$c" && found=1; done
+  if [ -n "$found" ]; then ok; else bad "hold #$pr: none of [$catchers] selected: '$SEL' (tier $TIER)"; fi
+  if [ -n "$sole" ]; then if has "$sole"; then ok; else bad "hold #$pr: sole catcher '$sole' not selected: '$SEL'"; fi; fi
+  if has security; then ok; else bad "hold #$pr: security missing"; fi
+}
+hold 3426 126 3 true "security concurrency" "" "commands/orchestrate/phase-4-execution.md commands/work-on.md commands/work-on/remediate.md"
+hold 3438 227 8 false "spec-cli" "spec-cli" "commands/review-pr-agents/protocols.md commands/review-pr.md commands/work-on.md commands/work-on/remediate.md commands/work-on/review.md docs/WORK-ON-RUNTIME.md docs/spec/review-protocol.md scripts/forge-root.test.sh"
+hold 3461 454 12 false "security spec-cli" "" "commands/work-on.md commands/work-on/build.md commands/work-on/build/implement.md commands/work-on/close.md commands/work-on/decompose.md docs/CONFIG.md docs/spec/forge-protocol-v1.md forge.yaml.example packages/protocol/src/types.js scripts/check-spec-markers.sh scripts/diff-size.sh scripts/diff-size.test.sh"
+hold 3464 53 2 true "security concurrency" "" "commands/orchestrate/phase-4-execution.md commands/work-on.md"
+hold 3480 56 3 true "security" "" "commands/orchestrate/phase-4-execution.md commands/work-on.md scripts/check-spec-markers.sh"
+hold 3490 220 3 false "security" "" "commands/review-pr-staging.md commands/review-pr.md scripts/review-pr-arguments.test.sh"
+hold 3500 263 5 false "security" "" ".github/workflows/check-commands.yml commands/work-on/build/validate.md commands/work-on/review.md scripts/check-branch-ancestry.sh scripts/check-branch-ancestry.test.sh"
+hold 3502 813 11 false "concurrency" "concurrency" "bin/engine-cli.mjs bin/engine.mjs bin/engine/phases-args.test.mjs bin/engine/phases.mjs bin/engine/runlog.mjs bin/tests/engine-crash.test.mjs bin/tests/engine-phases.test.mjs bin/tests/engine-runlog.test.mjs bin/tests/engine.test.mjs docs/WORK-ON-RUNTIME.md packages/protocol/src/phases.js"
+hold 3509 274 6 false "security spec-cli" "" "bin/engine.mjs bin/engine/phases.mjs bin/tests/engine-crash.test.mjs bin/tests/engine-phases.test.mjs bin/tests/engine-runlog.test.mjs bin/tests/engine.test.mjs"
+hold 3513 205 7 false "security concurrency infra spec-cli" "" "commands/orchestrate/phase-4-execution.md commands/review-pr.md commands/work-on.md commands/work-on/remediate.md commands/work-on/review.md docs/WORK-ON-RUNTIME.md scripts/check-spec-markers.sh"
+hold 3520 4977 9 false "concurrency" "concurrency" "bin/engine-cli.mjs bin/engine.mjs bin/engine/runlog.mjs bin/forgedock.mjs bin/runner.mjs bin/tests/engine.test.mjs bin/tests/runner.test.mjs commands/orchestrate/phase-4-execution.md devdocs/modules/runner.md"
+hold 3524 156 5 false "spec-cli" "spec-cli" "bin/engine.mjs bin/engine/phases.mjs bin/runner.mjs bin/tests/engine-phases.test.mjs bin/tests/engine.test.mjs"
+hold 3555 137 8 false "security" "" "bin/engine/phases.mjs bin/tests/engine-phases.test.mjs commands/work-on/build.md commands/work-on/build/implement.md commands/work-on/decompose.md commands/work-on/investigate.md packages/protocol/CHANGELOG.md packages/protocol/src/phases.js"
+
+# forge#3862: extended review depth (from the build's review_weight / scope flag) only ever adds reviewers
+SC_TOP="AUTH=0 BILLING=1 CONCURRENCY=0 DATABASE=1 INFRA=0 SECURITY=1 SCRAPING=0 FRONTEND=2 API=2"
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 40 --changed-files 1
+expect_tier "no depth flag stays small" small; expect_sel "no depth flag stays security-only" "security"
+case "$out" in *DEPTH=*) bad "standard roster prints no DEPTH line" ;; *) ok ;; esac
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 40 --changed-files 1 --review-depth STANDARD
+expect_tier "STANDARD depth stays small" small
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 40 --changed-files 1 --review-depth extended
+expect_tier "lowercase depth is not EXTENDED" small
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 40 --changed-files 1 --review-depth EXTENDED
+expect_tier "EXTENDED lifts small to standard" standard; expect_has "EXTENDED keeps security" security
+expect_has "EXTENDED small adds top domains" frontend; expect_has "EXTENDED small adds top domains" api
+case "$out" in *DEPTH=extended*) ok ;; *) bad "extended roster prints DEPTH=extended" ;; esac
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 400 --changed-files 6
+expect_not "standard top-2 omits the third domain" database
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 400 --changed-files 6 --review-depth EXTENDED
+expect_has "EXTENDED standard takes a third domain" database; expect_has "EXTENDED standard keeps security" security
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 30 --fix-pr true --review-depth EXTENDED
+expect_tier "EXTENDED lifts fix-pr to standard" standard
+run "svc/a.py" --scores "$SC_TOP" --changed-lines 400 --thorough true --review-depth EXTENDED
+expect_tier "full stays full" full
+
+echo "review-roster: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/run-shell-tests.sh

@@ -19,6 +19,9 @@ set -u
 SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 REPO_ROOT=$(cd "$SCRIPT_DIR/.." && pwd)
 cd "$REPO_ROOT" || exit 1
+# Gate scripts emit best-effort telemetry (forge#3834); suites run with it off so stubbed gh calls never buffer into ~/.forge.
+# scripts/telemetry.test.sh sets its own environment.
+export FORGE_TELEMETRY=off
 
 TIMEOUT_SECS="${SHELL_TEST_TIMEOUT:-300}"
 # WIRE:PROVEN — manual: SHELL_TEST_TIMEOUT=abc and SHELL_TEST_TIMEOUT=0 both print the error and exit 2

package/scripts/telemetry.test.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Tests for scripts/lib/telemetry.sh (forge_emit): record shape per event, upsert, rollover, buffer/flush,
+# kill switch, never-fails guarantee. No network: gh is replaced via FORGE_TELEMETRY_GH.
+set -u
+HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+LIB="$HERE/lib/telemetry.sh"
+PASS=0; FAIL=0
+ok() { PASS=$((PASS+1)); }
+bad() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
+check() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got '$2', want '$3')"; fi; }
+
+TD=$(mktemp -d); trap 'rm -rf "$TD"' EXIT
+export TD FORGE_REPO=o/r FORGE_ISSUE=5 FORGE_TELEMETRY_BUFFER_DIR="$TD/buf"
+unset FORGE_TELEMETRY FORGE_PR FORGE_RUN FORGE_PHASE FORGE_TELEMETRY_MAX_CHARS
+cat > "$TD/gh" <<'STUB'
+#!/usr/bin/env bash
+echo "$*" >> "$TD/calls"
+case "$*" in
+  "api --paginate "*) if [ -f "$TD/comments.json" ]; then cat "$TD/comments.json"; else echo '[]'; fi ;;
+  "api -X PATCH"*) b="${@: -1}"; printf '%s' "${b#body=}" > "$TD/patched" ;;
+  "api -X POST"*) b="${@: -1}"; printf '%s' "${b#body=}" > "$TD/posted" ;;
+esac
+STUB
+cat > "$TD/gh-fail" <<'STUB'
+#!/usr/bin/env bash
+exit 1
+STUB
+chmod +x "$TD/gh" "$TD/gh-fail"
+export FORGE_TELEMETRY_GH="$TD/gh"
+set_comments() { jq -n --arg b "$1" --arg t "${2:-Bot}" '[{id:77,body:$b,user:{type:$t},author_association:"NONE"}]' > "$TD/comments.json"; }
+nrec() { printf '%s\n' "$1" | grep -c '^{'; }
+reset() { rm -rf "$TD/calls" "$TD/posted" "$TD/patched" "$TD/comments.json" "$TD/buf"; }
+
+. "$LIB"
+
+# 1. One fixture per event shape: record carries the shared keys plus the payload, typed.
+reset
+forge_emit diff_size lines=10 excluded=2 threshold=0 result=OK
+REC=$(grep '^{' "$TD/posted")
+check "post has marker" "$(head -n 1 "$TD/posted")" "<!-- FORGE:TELEMETRY v1 -->"
+check "shared keys" "$(printf '%s' "$REC" | jq -c 'keys_unsorted[:9]')" '["v","ts","forge_version","repo","issue","pr","run","phase","event"]'
+check "issue number" "$(printf '%s' "$REC" | jq -r '.issue')" "5"
+check "pr null" "$(printf '%s' "$REC" | jq -r '.pr')" "null"
+check "numeric payload" "$(printf '%s' "$REC" | jq -r '.lines + .excluded')" "12"
+check "string payload" "$(printf '%s' "$REC" | jq -r '.result')" "OK"
+for fx in "acceptance_gate phase=review verified=3 failed=0 malformed=1 deferred=0:phase" \
+          "finding_disposition severity=HIGH confidence=CONFIRMED agent=auth disposition=ISSUE reason=severity-HIGH:disposition" \
+          "review_panel agents_selected=4 agents_completed=4 mode=FULL:mode" \
+          "ci_gate result=PASS rc=0 checks=7:checks" \
+          "liveness decision=DEFER why=lease:decision"; do
+  reset; FORGE_PR=9 forge_emit ${fx%%:*}
+  key=${fx##*:}; ev=${fx%% *}
+  check "fixture $ev event" "$(grep '^{' "$TD/posted" | jq -r '.event')" "$ev"
+  check "fixture $ev key $key" "$(grep '^{' "$TD/posted" | jq -r --arg k "$key" 'has($k)')" "true"
+done
+# review-side events go to the PR, others to the issue
+reset; FORGE_PR=9 forge_emit review_panel mode=FULL; grep -q 'issues/9/comments' "$TD/calls" && ok || bad "review_panel targets PR"
+reset; FORGE_PR=9 forge_emit diff_size lines=1; grep -q 'issues/5/comments' "$TD/calls" && ok || bad "diff_size targets issue"
+
+# 2. Sanitising: reserved keys, bad keys, backticks and newlines never reach the record.
+reset
+forge_emit x repo=evil 'a b=1' ok='a`b
+c'
+REC=$(grep '^{' "$TD/posted")
+check "reserved key ignored" "$(printf '%s' "$REC" | jq -r '.repo')" "o/r"
+check "value sanitised" "$(printf '%s' "$REC" | jq -r '.ok')" "a_b c"
+check "bad key dropped" "$(printf '%s' "$REC" | jq 'has("a b")')" "false"
+
+# 3. Upsert edits the single trusted comment in place; an untrusted one is ignored.
+reset; forge_emit ci_gate result=PASS; set_comments "$(cat "$TD/posted")"
+forge_emit liveness decision=PROCEED
+check "upsert patches" "$(nrec "$(cat "$TD/patched")")" "2"
+check "no second post" "$(grep -c 'POST' "$TD/calls")" "1"
+reset; forge_emit ci_gate result=PASS; set_comments "$(cat "$TD/posted")" User; rm -f "$TD/posted"
+forge_emit liveness decision=PROCEED
+[ -f "$TD/posted" ] && [ ! -f "$TD/patched" ] && ok || bad "untrusted comment must not be patched"
+
+# 4. Rollover to part=N near the size limit.
+reset; forge_emit ci_gate result=PASS; set_comments "$(cat "$TD/posted")"; rm -f "$TD/posted"
+FORGE_TELEMETRY_MAX_CHARS=200 forge_emit liveness decision=PROCEED
+check "rollover header" "$(head -n 1 "$TD/posted")" "<!-- FORGE:TELEMETRY v1 part=2 -->"
+
+# 5. Buffer on failure, flush on next emit, nothing lost.
+reset
+FORGE_TELEMETRY_GH="$TD/gh-fail" forge_emit diff_size lines=1
+check "buffered" "$(ls "$TD/buf")" "o_r__5.jsonl"
+forge_emit diff_size lines=2
+check "flushed both records" "$(nrec "$(cat "$TD/posted")")" "2"
+[ ! -e "$TD/buf/o_r__5.jsonl" ] && ok || bad "buffer removed after flush"
+
+# 6. Never fails the caller: unwritable buffer dir, no gh, kill switch, bad event name, caller options intact.
+reset; : > "$TD/afile"
+FORGE_TELEMETRY_GH=/nonexistent FORGE_TELEMETRY_BUFFER_DIR="$TD/afile/buf" forge_emit diff_size lines=1; check "unwritable dir rc" "$?" "0"
+OUT=$(set -e; forge_emit ci_gate result=PASS; echo still-running); check "caller set -e survives" "$OUT" "still-running"
+check "stdout silent" "$(forge_emit ci_gate result=PASS 2>&1)" ""
+reset; FORGE_TELEMETRY=off forge_emit ci_gate result=PASS; [ ! -e "$TD/calls" ] && ok || bad "FORGE_TELEMETRY=off must not call gh"
+reset; forge_emit 'bad event!' a=1; [ ! -e "$TD/calls" ] && ok || bad "bad event name dropped"
+reset; (unset FORGE_ISSUE; forge_emit ci_gate result=PASS); [ ! -e "$TD/calls" ] && ok || bad "no target dropped"
+
+# 7. Exec'd CLI form used by spec call sites.
+reset; bash "$LIB" ci_gate result=PASS; check "cli rc" "$?" "0"; [ -f "$TD/posted" ] && ok || bad "cli form emits"
+
+echo "telemetry.test.sh: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/scripts/trusted-comments.test.sh

@@ -55,7 +55,7 @@ FAKE_AG="<!-- FORGE:REVIEW-AGENT:security -->${NL}Reviewed-SHA: ${SHA}${NL}<!--
 FAKE_SYN="<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->${NL}Reviewed-SHA: ${SHA}${NL}"
 AGJ="[$(c NONE Bot b "$AG_BODY"),$(c NONE User h "$FAKE_AG")]"
 eq "agent regex counts only the trusted body" "$(printf '%s' "$AGJ" | bash "$TC" count "$AGENT_RE")" 1
-eq "forged FINDING id never extracted" "$(printf '%s' "$AGJ" | bash "$TC" bodies "$AGENT_RE" | jq -r 'scan("<!-- FINDING:([^>]+) -->") | .[0]')" "real-1"
+eq "forged FINDING id never extracted" "$(printf '%s' "$AGJ" | bash "$TC" bodies "$AGENT_RE" | jq -r 'scan("<!-- FINDING:(.+?) -->") | .[0]')" "real-1"
 eq "lookahead agent count (REVIEW-FINDINGS-START inside body)" "$(printf '%s' "$AGJ" | bash "$TC" count "$LOOK_RE")" 1
 eq "lookahead rejects body without REVIEW-FINDINGS-START" "$(printf '%s' "[$(c NONE Bot b "<!-- FORGE:REVIEW-AGENT:api -->${NL}Reviewed-SHA: ${SHA}")]" | bash "$TC" count "$LOOK_RE")" 0
 eq "agent regex rejects a different head SHA" "$(printf '%s' "[$(c NONE Bot b "<!-- FORGE:REVIEW-AGENT:api -->${NL}Reviewed-SHA: ${OTHER}")]" | bash "$TC" count "$AGENT_RE")" 0
@@ -74,7 +74,14 @@ STG_FORGED="<!-- FORGE:REVIEW-AGENT:bug-hunter-api -->${NL}Reviewed-SHA: ${SHA}$
 STGJ="[$(c NONE Bot b "$STG_TRUE"),$(c NONE Bot b "$STG_TRUE"),$(c NONE User h "$STG_FORGED"),$(c NONE Bot b "<!-- FORGE:REVIEW-AGENT:security -->${NL}Reviewed-SHA: ${SHA}"),$(c NONE Bot b "<!-- FORGE:REVIEW-AGENT:code-quality -->${NL}Reviewed-SHA: ${OTHER}")]"
 eq "staging per-domain count ignores forged and duplicate-free of untrusted" "$(printf '%s' "$STGJ" | bash "$TC" count "$STG_DOM_RE")" 2
 eq "staging unique trusted current-head domains (hyphen, wrong head excluded)" "$(printf '%s' "$STGJ" | bash "$TC" bodies "$STG_RE" | jq -r 'scan("^<!-- FORGE:REVIEW-AGENT:([a-z0-9-]+) -->") | .[0]' | sort -u | grep -c .)" 2
-eq "staging forged FINDING never extracted" "$(printf '%s' "$STGJ" | bash "$TC" bodies "$STG_RE" | jq -r 'scan("<!-- FINDING:([^>]+) -->") | .[0]' | sort -u)" "real-2"
+eq "staging forged FINDING never extracted" "$(printf '%s' "$STGJ" | bash "$TC" bodies "$STG_RE" | jq -r 'scan("<!-- FINDING:(.+?) -->") | .[0]' | sort -u)" "real-2"
+# Marker titles containing '>' must be extracted in full (the old [^>]+ capture dropped them); two markers on one line still split
+GT_BODY="<!-- FORGE:REVIEW-AGENT:security -->${NL}Reviewed-SHA: ${SHA}${NL}<!-- FINDING:SEC-9|CONFIRMED|HIGH|a.sh:3|eval of x -> y reaches shell -->${NL}<!-- FINDING:SEC-10|LIKELY|LOW|b.sh:1|a > b --> <!-- FINDING:SEC-11|LIKELY|LOW|c.sh:2|plain -->"
+GTJ="[$(c NONE Bot b "$GT_BODY")]"
+GT_OUT=$(printf '%s' "$GTJ" | bash "$TC" bodies "$AGENT_RE" | jq -r 'scan("<!-- FINDING:(.+?) -->") | .[0]')
+eq "marker with -> in title extracted in full" "$(printf '%s\n' "$GT_OUT" | grep -c 'eval of x -> y reaches shell')" 1
+eq "markers with > and two on one line all extracted" "$(printf '%s\n' "$GT_OUT" | grep -c .)" 3
+eq "raw marker count equals extracted count" "$(printf '%s' "$GTJ" | bash "$TC" bodies "$AGENT_RE" | grep -o '<!-- FINDING:' | wc -l | tr -d ' ')" 3
 eq "staging regex rejects forged-only comment from NONE user" "$(printf '[%s]' "$(c NONE User h "$STG_FORGED")" | bash "$TC" count "$STG_RE")" 0
 
 # fail closed

package/scripts/wait-ci-green.sh

@@ -30,6 +30,9 @@
 # "No checks" passes only when GitHub Actions also reports no workflow runs for the head commit;
 # if runs exist but their checks have not appeared yet, the gate keeps waiting.
 set -uo pipefail
+# Telemetry (forge#3834): best-effort decision record; never changes stdout, stderr or the exit code.
+_TEL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/telemetry.sh"; [ -f "$_TEL" ] && . "$_TEL" 2>/dev/null
+type forge_emit >/dev/null 2>&1 || forge_emit() { :; }
 
 PR=""; REPO=""
 TIMEOUT="${FORGE_CI_TIMEOUT:-540}"; INTERVAL="${FORGE_CI_INTERVAL:-20}"; SETTLE="${FORGE_CI_SETTLE:-45}"
@@ -50,7 +53,11 @@ case "$REPO" in */*) ;; *) usage ;; esac
 for v in "$TIMEOUT" "$INTERVAL" "$GRACE" "$SETTLE"; do case "$v" in ''|*[!0-9]*) usage ;; esac; done
 [ "$INTERVAL" -ge 1 ] || INTERVAL=1
 
-emit() { echo "CI_GATE: $1"; echo "CI_GATE_HEAD: ${START_SHA:-unknown}"; }
+emit() {
+  case "$1" in PASS) _rc=0 ;; FAIL) _rc=1 ;; TIMEOUT) _rc=3 ;; *) _rc=2 ;; esac
+  FORGE_REPO="${FORGE_REPO:-$REPO}" FORGE_PR="${FORGE_PR:-$PR}" forge_emit ci_gate result="$1" rc="$_rc" checks="${total:-0}"
+  echo "CI_GATE: $1"; echo "CI_GATE_HEAD: ${START_SHA:-unknown}"
+}
 head_sha() { gh pr view "$PR" -R "$REPO" --json headRefOid --jq '.headRefOid' 2>/dev/null; }
 START_SHA="$(head_sha)"
 if [ -z "$START_SHA" ]; then START_SHA=""; emit ERROR; echo "cannot read PR #$PR head in $REPO"; exit 2; fi

package/scripts/wait-ci-green.test.sh

@@ -68,7 +68,7 @@ expect "every result names the gated head" "CI_GATE_HEAD: abc1234" "$(printf '%s
 
 # Static guard: every autonomous `gh pr merge` command line in the pipeline specs must be preceded
 # (within 25 lines) by a CI gate result check. Prose/manual instructions are not command lines.
-for spec in commands/review-pr.md commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
+for spec in commands/review-pr.md scripts/review-finalize.sh commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
   bad=$(awk '
     { line[NR]=$0 }
     /^[[:space:]]*(MERGE_RESULT=\$\()?gh pr merge / {
@@ -78,7 +78,7 @@ for spec in commands/review-pr.md commands/work-on/review.md commands/work-on/re
   expect "every autonomous merge in $spec is CI-gated" "" "$bad"
 done
 # Every autonomous merge pins the gated head (forge#3187): no merge line may omit --match-head-commit.
-for spec in commands/review-pr.md commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
+for spec in commands/review-pr.md scripts/review-finalize.sh commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
   unpinned=$(grep -nE '^[[:space:]]*(MERGE_RESULT=\$\(|MERGE_OUTPUT=\$\()?gh pr merge ' "$HERE/../$spec" | grep -v -- '--match-head-commit')
   expect "every autonomous merge in $spec pins the gated head" "" "$unpinned"
 done
@@ -90,7 +90,7 @@ if grep -qE '^[[:space:]]*(MERGE_RESULT=\$\()?gh pr merge ' "$HERE/../commands/w
 
 # Reviewed-head guard: review-pr Phase 8 must refuse to merge a head other than the reviewed commit,
 # and the work-on callers must route "stale review" to a re-review, never a manual merge.
-grep -qF '${GATED_HEAD#"$REVIEWED_SHORT"}' "$HERE/../commands/review-pr.md" && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: review-pr Phase 8 lacks reviewed-head guard"; }
+grep -qF '${GATED_HEAD#"$REVIEWED_SHORT"}' "$HERE/../scripts/review-finalize.sh" && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: review-pr Phase 8 (scripts/review-finalize.sh merge-gate) lacks reviewed-head guard"; }
 for f in commands/work-on/review.md; do
   grep -q 'stale review' "$HERE/../$f" && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: $f does not route stale review"; }
 done

package/templates/forge.yaml.minimal

@@ -42,3 +42,12 @@ branches:
   default: "main"
   staging: "staging"
   feature_pattern: "milestone/{slug}"
+
+# =============================================================================
+# DECOMPOSITION (OPTIONAL)
+# Set close_parent: true to close a decomposed parent issue at decomposition
+# (default false: it stays open until its last child closes).
+# =============================================================================
+
+# decomposition:
+#   close_parent: false