forgedock 1.9.0 → 1.9.1

package/commands/orchestrate/phase-4-execution.md

@@ -2837,10 +2837,20 @@ When `CASCADE_MAX_AMPLIFICATION` is not `off`, and the current ratio is greater
 **Deterministic breaker check (MANDATORY on every dispatch path — engine CLI, Agent-spawn fallback, or a hand-driven orchestrator):** the in-spec bookkeeping above only runs when the Step 4B/4C bash runs. A batch driven through the Agent-spawn fallback never evaluated it and reached about 2 findings per merge (2026-10-08 audit). Before dispatching ANY `review-finding` issue at `priority:P3` or below, and after every completed merge, run `scripts/amplification-breaker.sh` against GitHub state. Its exit code is authoritative, and it overrides an in-memory `AMPLIFICATION_BREAKER_TRIPPED=false`:
 
 ```bash
+# Same resolver as review-pr §6B.5: plugin root, FORGE_ROOT, FORGEDOCK_HOME, newest pinned plugin cache
+# (CLAUDE_CONFIG_DIR, then ~/.claude), then the repo's own scripts/.
 AMP_SCRIPT=""
-for _c in '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}"; do
-  case "$_c" in /*) [ -z "$AMP_SCRIPT" ] && [ -f "$_c/scripts/amplification-breaker.sh" ] && AMP_SCRIPT="$_c/scripts/amplification-breaker.sh" ;; esac
+_cands="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}")"
+for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
+  [ -n "$_cfg" ] || continue
+  _cands="$_cands
+$(find -L "$_cfg/plugins/cache/forgedock/forgedock" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | awk -F/ '$NF ~ /^[0-9]+\.[0-9]+\.[0-9]+$/{split($NF,a,".");printf "%d %d %d %s\n",a[1],a[2],a[3],$0}' | sort -k1,1nr -k2,2nr -k3,3nr | cut -d' ' -f4- || true)"
 done
+_cands="$_cands
+$PWD"
+while IFS= read -r _c; do
+  case "$_c" in /*) [ -z "$AMP_SCRIPT" ] && [ -f "$_c/scripts/amplification-breaker.sh" ] && AMP_SCRIPT="$_c/scripts/amplification-breaker.sh" ;; esac
+done <<< "$_cands"
 if [ "$AMPLIFICATION_BREAKER" != "off" ]; then
   if [ -n "$AMP_SCRIPT" ]; then
     AMP_LINE=$(bash "$AMP_SCRIPT" --since "$BATCH_T0" -R {GH_REPO}); AMP_RC=$?

package/commands/quality-gate.md

@@ -277,6 +277,7 @@ the gate rather than leaving the workflow blocked.
 - **2R (Registry checks)**: ALWAYS run — executes all promoted checks from `scripts/check-registry/manifest.json` <!-- Added: forge#1331 -->
 - **2R.5 (Adaptive gate.d checks)**: ALWAYS run when `adaptive_scripts.enabled` — executes `.forgedock/scripts/gate.d/*.sh`; each script is repo-specific and was promoted from a recurring finding pattern <!-- Added: forge#1739 -->
 - **2G.8 (Wire-through proof)**: Run if `WIRE_THROUGH` in DOMAINS — demands each newly added conditional path be demonstrably reachable <!-- Added: forge#1731 -->
+- **2G.10 (Spec bash syntax)**: Run if `FORGE_GRAPH` in DOMAINS and any `commands/**/*.md` changed — `bash -n` on changed ```bash blocks in specs (HIGH); shellcheck advisory
 - **2G.9 (Danger-zone recurrence)**: Run if `FORGE_GRAPH` in DOMAINS — cross-references injected danger-zone rule cards from FORGE:CONTEXT against the diff; violations tagged `known-pattern-recurrence` (HIGH) <!-- Added: forge#1744 -->
 - **2U (Coverage-reduction check)**: ALWAYS run (`COVERAGE_REDUCTION` in DOMAINS) — flags diffs that delete test files, remove test cases, add skip markers, or remove/disable workflow test steps <!-- Added: forge#3257 -->
 - **2S (Test failure classification)**: Run if any Step 2 check invoked a test suite and it failed — classifies the failure as PRE_BROKEN, FLAKY, or REAL using `scripts/flaky-quarantine.sh` <!-- Added: forge#1336 -->
@@ -718,6 +719,34 @@ fi
 
 Do NOT suppress the finding by making the check less strict or adding fake no-op tests. The intent is a real proof that the path is reachable. <!-- Added: forge#1731 -->
 
+### 2G.10: Spec bash syntax check (FORGE_GRAPH domain)
+
+**Triggered when**: changed files include `commands/**/*.md`. Skips silently in any project without `scripts/check-spec-bash.sh`.
+
+**Why this matters**: in ForgeDock the pipeline code is bash inside Markdown specs. The executable-file checks above exclude `.md` files, and acceptance checks are mostly greps, so spec bash used to merge without ever being parsed. Reviewers were then the first to run it, which drove most review findings (2026-10-08 cascade audit). This check runs `bash -n` on every ```bash block that contains a changed line, after neutralising `{PLACEHOLDER}` notation. Blocks with pseudo tool calls (`Skill(`/`Agent(`/`Task(`) and blocks preceded by `<!-- allowlist:check-spec-bash -->` are skipped. Pre-existing blocks are never checked, so the baseline cannot block a change. `shellcheck -S error` results are advisory only.
+
+```bash
+SPEC_BASH_CHECKER="$FORGEDOCK_SCRIPTS/check-spec-bash.sh"
+[ -f "$SPEC_BASH_CHECKER" ] || SPEC_BASH_CHECKER="{WORKTREE_PATH}/scripts/check-spec-bash.sh"
+SPEC_MD_FILES=$(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '^commands/.*\.md$' || true)
+if [ -f "$SPEC_BASH_CHECKER" ] && [ -n "$SPEC_MD_FILES" ]; then
+    PR_BASE="${PR_BASE:-staging}"
+    SPEC_BASH_BASE=$(git -C "{WORKTREE_PATH}" merge-base "origin/${PR_BASE}" HEAD 2>/dev/null || true)
+    if [ -z "$SPEC_BASH_BASE" ]; then
+        echo "FORGE_GRAPH | HIGH | spec-bash | cannot resolve merge-base with origin/${PR_BASE} — spec bash not checked (fail closed)"
+    else
+        # shellcheck disable=SC2086 # SPEC_MD_FILES is a newline list of repo-relative paths without spaces
+        SPEC_BASH_REPORT=$(cd "{WORKTREE_PATH}" && bash "$SPEC_BASH_CHECKER" --base "$SPEC_BASH_BASE" --shellcheck $SPEC_MD_FILES 2>&1)
+        echo "$SPEC_BASH_REPORT"
+        echo "$SPEC_BASH_REPORT" | grep -E '^FAIL ' | while IFS= read -r hit; do
+            echo "FORGE_GRAPH | HIGH | spec-bash | ${hit#FAIL }"
+        done
+    fi
+fi
+```
+
+Report each `FAIL` line as **HIGH**: the changed block does not parse, so any agent that runs it hits a syntax error. Fix the bash. If the block is an intentional fragment (for example an `if` opened in one block and closed in the next), put `<!-- allowlist:check-spec-bash -->` on the line before the fence. `WARN` (shellcheck) lines are advisory and go in the report without blocking.
+
 ### 2G.9: Danger-zone recurrence check (FORGE_GRAPH domain) <!-- Added: forge#1744 -->
 
 **Triggered when**: `FORGE_GRAPH` in DOMAINS (changed files include `commands/*.md` specs or `scripts/*` files). Skips silently when the FORGE:CONTEXT comment on the issue contains no `### Danger-Zone Rule Cards` section (i.e., Phase C0.5 injected zero cards — nothing to cross-reference).

package/commands/review-pr.md

@@ -1692,16 +1692,27 @@ If still 0: review is clean — skip to Phase 7.
 Filing a standalone `review-finding` issue for every LOW/POSSIBLE reviewer note makes the cascade amplify (each merged fix PR spawns its own P3 issues, which spawn more). Classify each deduped finding before 6C with the deterministic classifier — do NOT hand-classify when the script resolves:
 
 - **ISSUE always**: `**Severity**: HIGH` or `CRITICAL`, or a missing/unparseable severity.
-- **Safety exemption is content-based**: a LOW or POSSIBLE finding is still filed when its file path / title / body matches the security/billing keyword set (`security|auth|authz|authn|billing|payment|stripe|charge|invoice|injection|xss|csrf|ssrf|idor|secret(s)|credential(s)|permission(s)|sql|token|password|redact`, whole words, `_`/`-`/`/` separate words — so `auth_service` matches but `author`/`tokenizer` do not), or when it came from a dedicated, signal-selected domain agent (Auth, Billing, Concurrency, Database). **Origin from the always-on General Security & Quality agent alone does NOT exempt a finding**: that agent runs on every PR, so origin-based exemption filed nearly every LOW note it raised (the 2026-10-08 cascade audit: 50 of 60 would-be notes in one batch were filed only for that reason).
+- **Safety exemption is content-based**: a LOW or POSSIBLE finding is still filed when its file path / title / body matches the security/billing keyword set (`security|auth|authz|authn|billing|payment|stripe|charge|invoice|injection|xss|csrf|ssrf|idor|secret(s)|credential(s)|permission(s)|sql|token|password|redact`, whole words, `_`/`-`/`/` separate words — so `auth_service` matches but `author`/`tokenizer` do not), or when it came from a dedicated, signal-selected domain agent (Auth, Billing, Concurrency, Database) AND is MEDIUM+ or CONFIRMED — a LOW/POSSIBLE finding stays a NOTE whichever reviewer raised it. **Origin from the always-on General Security & Quality agent alone does NOT exempt a finding**: that agent runs on every PR, so origin-based exemption filed nearly every LOW note it raised (the 2026-10-08 cascade audit: 50 of 60 would-be notes in one batch were filed only for that reason).
 - **Review-finding lineage** (the PR's linked issue `MERGE_ISSUE` carries the `review-finding` label, any priority — this PR is itself a fix for a finding): only MEDIUM findings that are CONFIRMED, or LIKELY and safety-exempt, become issues; LOW and POSSIBLE are always NOTEs. A fix for a finding must not mint a new generation of findings.
 - **Otherwise**: `**Severity**: LOW`, or `**Confidence**: POSSIBLE` below HIGH, is a NOTE unless safety-exempt; everything else (MEDIUM CONFIRMED/LIKELY) is an ISSUE.
 
 ```bash
-# Resolve the classifier: running plugin first, then the resolved ForgeDock root, then the repo copy.
+# Resolve the classifier: running plugin, FORGE_ROOT, FORGEDOCK_HOME, newest pinned forgedock plugin cache
+# under the active config dir (CLAUDE_CONFIG_DIR) then ~/.claude, then the repo's own scripts/ (ForgeDock itself).
+# The plugin-root placeholder is not always substituted in forked review runs, so the cache scan is what makes
+# consumer repos resolve the script instead of falling back to classifier=manual.
 CLASSIFY_SCRIPT=""
-for _cs in '${CLAUDE_PLUGIN_ROOT}/scripts/classify-finding.sh' "${FORGE_ROOT:+$FORGE_ROOT/scripts/classify-finding.sh}" "scripts/classify-finding.sh"; do
-  case "$_cs" in /*|scripts/*) [ -f "$_cs" ] && { CLASSIFY_SCRIPT="$_cs"; break; } ;; esac
+_cands="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}")"
+for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
+  [ -n "$_cfg" ] || continue
+  _cands="$_cands
+$(find -L "$_cfg/plugins/cache/forgedock/forgedock" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | awk -F/ '$NF ~ /^[0-9]+\.[0-9]+\.[0-9]+$/{split($NF,a,".");printf "%d %d %d %s\n",a[1],a[2],a[3],$0}' | sort -k1,1nr -k2,2nr -k3,3nr | cut -d' ' -f4- || true)"
 done
+_cands="$_cands
+$PWD"
+while IFS= read -r _c; do
+  case "$_c" in /*) [ -z "$CLASSIFY_SCRIPT" ] && [ -f "$_c/scripts/classify-finding.sh" ] && CLASSIFY_SCRIPT="$_c/scripts/classify-finding.sh" ;; esac
+done <<< "$_cands"
 FINDING_LINEAGE="none"
 if [ -n "${MERGE_ISSUE:-}" ] && gh issue view "$MERGE_ISSUE" -R {GH_REPO} --json labels --jq '.labels[].name' 2>/dev/null | grep -qx 'review-finding'; then
   FINDING_LINEAGE="review-finding"

package/commands/work-on/build/validate.md

@@ -150,7 +150,7 @@ gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human" # allowlist:check-com
 
 ## Phase V2: Format and Verify
 
-Run after quality gate passes. All tool commands are read from `forge.yaml → verification.commands`; each step logs `SKIPPED — not configured` when the corresponding key is absent rather than silently passing.
+Run after quality gate passes. All tool commands are read from `forge.yaml → verification.commands`. `forge.yaml` is usually gitignored, so it is absent from the worktree: every block below resolves `FORGE_CFG` to the worktree copy if present, else the main checkout's `forge.yaml` (via `git rev-parse --git-common-dir`). Before this, every verification command, learned test command and the SOPS chain check were silently skipped in worktree builds; each step logs `SKIPPED — not configured` when the corresponding key is absent rather than silently passing.
 
 **Track skipped checks** — initialize before any check runs:
 ```bash
@@ -178,8 +178,9 @@ run_verification_command() {
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
 
-PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' "$FORGE_CFG" 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     run_verification_command "python.format" "$PYTHON_FORMAT"
 else
@@ -195,10 +196,11 @@ Failures in `py_compile` are BLOCKING — fix before continuing.
 **TypeScript**:
 ```bash
 cd {WORKTREE_PATH}
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
 
-TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
-TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
-TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' "$FORGE_CFG" 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' "$FORGE_CFG" 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' "$FORGE_CFG" 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
     run_verification_command "typescript.format" "$TS_FORMAT"
@@ -234,8 +236,9 @@ Before running any test command below, check it against `verification.known_slow
 
 ```bash
 cd {WORKTREE_PATH}
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
 # Read directly from forge.yaml (static, operator-declared config).
-KNOWN_SLOW_TESTS=$(yq -o=json -I=0 '.verification.known_slow_tests // []' forge.yaml 2>/dev/null || echo '[]')
+KNOWN_SLOW_TESTS=$(yq -o=json -I=0 '.verification.known_slow_tests // []' "$FORGE_CFG" 2>/dev/null || echo '[]')
 
 # apply_known_slow_filter <cmd> — echoes the command to actually run, or "" to
 # skip it entirely. Matching is substring match of `pattern` against the full
@@ -274,7 +277,8 @@ After all `verification.commands` steps complete, run any commands from `forge.y
 
 ```bash
 cd {WORKTREE_PATH}
-LEARNED_TEST_COMMANDS=$(yq -o=json -I=0 '.learned.test_commands // []' forge.yaml 2>/dev/null || echo '[]')
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
+LEARNED_TEST_COMMANDS=$(yq -o=json -I=0 '.learned.test_commands // []' "$FORGE_CFG" 2>/dev/null || echo '[]')
 LEARNED_FAILED=0
 if [ -n "$LEARNED_TEST_COMMANDS" ] && [ "$LEARNED_TEST_COMMANDS" != "[]" ] && [ "$LEARNED_TEST_COMMANDS" != "null" ]; then
   echo "Running learned test commands..."
@@ -368,7 +372,8 @@ After static proxy checks, run a lightweight live browser check using Playwright
 
 ```bash
 cd {WORKTREE_PATH}
-APP_URL=$(yq '.services.app_url // ""' forge.yaml 2>/dev/null || echo '')
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
+APP_URL=$(yq '.services.app_url // ""' "$FORGE_CFG" 2>/dev/null || echo '')
 if [ -z "$APP_URL" ]; then
     echo "SKIPPED — services.app_url not configured in forge.yaml (browser signal check requires a running app URL)"
 else
@@ -442,7 +447,8 @@ ADDED_LINES=$(git diff HEAD -- {CHANGED_FILES} | grep -E '^\+' | grep -v '^+++')
 
 ```bash
 cd {WORKTREE_PATH}
-SECRETS_BACKEND=$(yq '.deploy.secrets_backend // ""' forge.yaml 2>/dev/null || echo '')
+FORGE_CFG=forge.yaml; [ -f "$FORGE_CFG" ] || { _gcd=$(git rev-parse --git-common-dir 2>/dev/null) && _gcd=$(cd "$_gcd" 2>/dev/null && pwd) && [ -f "${_gcd%/.git}/forge.yaml" ] && FORGE_CFG="${_gcd%/.git}/forge.yaml"; }  # gitignored forge.yaml exists only in the main checkout, not in worktrees
+SECRETS_BACKEND=$(yq '.deploy.secrets_backend // ""' "$FORGE_CFG" 2>/dev/null || echo '')
 if [ "$SECRETS_BACKEND" != "sops" ]; then
     echo 'SKIP: SOPS chain check — deploy.secrets_backend is not "sops". Configure deploy.secrets_backend in forge.yaml to enable.'
 fi

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,15 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Cascade follow-ups: script resolution, domain-agent notes, verification in worktrees, spec bash check
+
+- **Script resolution works in consumer repos.** `/review-pr` §6B.5 and the orchestrator breaker now find `classify-finding.sh` and `amplification-breaker.sh` through the newest pinned ForgeDock plugin cache under `CLAUDE_CONFIG_DIR`, then `~/.claude`. They also check `FORGEDOCK_HOME` and the repo's own `scripts/`, as before. Previously the plugin-root placeholder was often left unsubstituted in forked review runs, so 4 of 9 AlterLab reviews fell back to `classifier=manual`.
+- **Domain reviewers no longer file speculative LOW findings.** A finding from the Auth, Billing, Concurrency or Database reviewer is still filed as an issue only when it is MEDIUM+ or CONFIRMED. A LOW/POSSIBLE finding becomes a note whichever reviewer raised it. Security/billing keyword content still files as before.
+- **Validate reads your real `forge.yaml` in worktrees.** `forge.yaml` is usually gitignored, so it never existed in the per-issue worktree, and every `verification.commands` entry, `learned.test_commands` entry and the SOPS chain check were silently skipped. Validate now falls back to the main checkout's `forge.yaml`.
+- **The quality gate parses spec bash.** New step 2G.10 runs `scripts/check-spec-bash.sh`, which applies `bash -n` (plus advisory `shellcheck -S error`) to every changed fenced bash block in `commands/**/*.md`. Pre-existing blocks are never checked. Mark an intentional fragment with `<!-- allowlist:check-spec-bash -->` on the line before its fence.
+
+Action: expect verification commands that you configured in `forge.yaml` to start running in `/work-on` builds. If a configured command (for example a SOPS chain with `deploy.secrets_backend: sops`) was failing unnoticed, builds will now report it.
+
 ## Review-finding cascade is now bounded by code, not prose
 
 An audit of one `/orchestrate` batch found 93 `review-finding` issues filed for 46 merges, a ratio of 2.02. The §6B.5 note-disposition step was supposed to stop LOW/POSSIBLE findings from becoming issues. It was bypassed in two ways: every finding from the always-on General Security & Quality reviewer was exempt by origin, and reviewers often skipped the step entirely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "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/check-spec-bash.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-spec-bash.sh — Syntax-check the ```bash fenced blocks inside Markdown spec files.
+#
+# ForgeDock's pipeline is bash embedded in Markdown, and the quality gate's executable
+# checks skip .md files. Spec bash therefore merged without ever being parsed, and
+# reviewers became the first thing to run it (2026-10-08 audit). This script runs
+# `bash -n` on each fenced block after neutralising spec notation, and optionally
+# `shellcheck -S error`.
+#
+# Usage:
+#   check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>...
+#
+#   --base <ref>   Only check blocks that contain a line changed relative to <ref>
+#                  (`git diff -U0 <ref> -- <file>`), so pre-existing blocks never fail
+#                  a new change. Without --base every block is checked.
+#   --shellcheck   Also run `shellcheck -S error -s bash` when installed. Advisory: its hits are
+#                  reported as WARN and never fail the run (spec blocks are often fragments).
+#
+# Spec notation that is not bash is neutralised before parsing:
+#   {PLACEHOLDER} / {FORGE_SKILL_PREFIX}x  → a plain word
+#   blocks containing pseudo tool calls (Skill( / Agent( / Task( / Read( ) → SKIPPED
+#   a block whose preceding non-blank line is exactly `<!-- allowlist:check-spec-bash -->` → SKIPPED
+#   (for intentional fragments, e.g. an `if` opened in one block and closed in the next)
+#
+# Output: one line per checked block, `OK|FAIL|WARN|SKIP <file>:<start-line> <reason>`,
+# then `SPEC-BASH: checked=N failed=F skipped=S shellcheck_warnings=W`. Only bash -n fails a run.
+# Exit codes: 0 no failures, 1 at least one block failed, 2 usage error.
+#
+# Portable: bash 3.2, BSD/GNU awk and sed. Requires git only with --base.
+
+set -u
+
+BASE=""; SHELLCHECK=0; FILES=""
+usage() { echo "ERROR: Usage: check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>..." >&2; exit 2; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --base) [ "$#" -ge 2 ] || usage; BASE="$2"; shift 2 ;;
+    --shellcheck) SHELLCHECK=1; shift ;;
+    --*) usage ;;
+    *) FILES="$FILES
+$1"; shift ;;
+  esac
+done
+[ -n "$FILES" ] || usage
+
+TMPD=$(mktemp -d "${TMPDIR:-/tmp}/check-spec-bash.XXXXXX") || exit 2
+trap 'rm -rf "$TMPD"' EXIT
+
+checked=0; failed=0; skipped=0; warned=0
+
+changed_lines() { # changed_lines <file> → one new-side line number per line
+  git diff -U0 "$BASE" -- "$1" 2>/dev/null | awk '
+    /^@@/ { split($3, a, ","); s = substr(a[1], 2) + 0; n = (a[2] == "") ? 1 : a[2] + 0
+            for (i = 0; i < n; i++) print s + i }'
+}
+
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  case "$f" in *.md) ;; *) continue ;; esac
+  [ -f "$f" ] || { echo "SKIP $f missing"; continue; }
+
+  CH="$TMPD/changed"; : > "$CH"
+  if [ -n "$BASE" ]; then
+    changed_lines "$f" > "$CH"
+    [ -s "$CH" ] || continue
+  fi
+
+  # Split the file into one file per ```bash block, named by its opening line number.
+  rm -f "$TMPD"/blk.*
+  awk -v d="$TMPD" '
+    !inb && /^[ \t]*```(bash|sh)[ \t]*$/ { inb = 1; start = NR; out = d "/blk." NR; printf "" > out
+                                            if (prev ~ /^[ \t]*<!--[ \t]*allowlist:check-spec-bash[ \t]*-->[ \t]*$/) print "#ALLOWLISTED" > out
+                                            next }
+    inb && /^[ \t]*```[ \t]*$/ { inb = 0; close(out); print start "\t" NR > (d "/ranges"); next }
+    inb { print > out; next }
+    { if ($0 !~ /^[ \t]*$/) prev = $0 }
+  ' "$f"
+  [ -f "$TMPD/ranges" ] || continue
+
+  while IFS="$(printf '\t')" read -r start end; do
+    blk="$TMPD/blk.$start"
+    if [ -n "$BASE" ]; then
+      hit=$(awk -v s="$start" -v e="$end" '$1 >= s && $1 <= e { print "y"; exit }' "$CH")
+      [ "$hit" = "y" ] || continue
+    fi
+    if head -1 "$blk" | grep -q '^#ALLOWLISTED$'; then
+      skipped=$((skipped + 1)); echo "SKIP $f:$start allowlisted fragment"; continue
+    fi
+    if grep -Eq '(^|[^A-Za-z_])(Skill|Agent|Task|Read)\(' "$blk"; then
+      skipped=$((skipped + 1)); echo "SKIP $f:$start pseudo tool call"; continue
+    fi
+    # Neutralise {PLACEHOLDER} notation (and {FORGE_SKILL_PREFIX}name) into a variable expansion,
+    # so tests like [ -z "{X}" ] are not misread as constant strings.
+    sed -E 's/\{[A-Z][A-Z0-9_]*\}/${PH}/g' "$blk" > "$blk.sh"
+    checked=$((checked + 1))
+    if ! err=$(bash -n "$blk.sh" 2>&1); then
+      failed=$((failed + 1))
+      echo "FAIL $f:$start bash -n: $(printf '%s' "$err" | head -1 | sed "s|$blk.sh|block|")"
+      continue
+    fi
+    if [ "$SHELLCHECK" = 1 ] && command -v shellcheck >/dev/null 2>&1; then
+      if ! err=$(shellcheck -S error -s bash "$blk.sh" 2>&1); then
+        warned=$((warned + 1))
+        echo "WARN $f:$start shellcheck: $(printf '%s' "$err" | grep -m1 -E 'SC[0-9]+' || printf '%s' "$err" | head -1)"
+        continue
+      fi
+    fi
+    echo "OK $f:$start"
+  done < "$TMPD/ranges"
+  rm -f "$TMPD/ranges"
+done <<EOF
+$FILES
+EOF
+
+echo "SPEC-BASH: checked=$checked failed=$failed skipped=$skipped shellcheck_warnings=$warned"
+[ "$failed" -eq 0 ]

package/scripts/check-spec-bash.test.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-spec-bash.sh. Run: bash scripts/check-spec-bash.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-spec-bash.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-spec-bash-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+FENCE='```'
+
+check() { # check <want_rc> <want_substring> <desc> -- args...
+  want_rc="$1"; want="$2"; desc="$3"; shift 4
+  out=$(cd "$T" && bash "$S" "$@" 2>&1); rc=$?
+  case "$out" in *"$want"*) ok=1 ;; *) ok=0 ;; esac
+  if [ "$rc" = "$want_rc" ] && [ "$ok" = 1 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (rc=$rc)"; printf '%s\n' "$out" | sed 's/^/    /'; fi
+}
+
+cat > "$T/good.md" <<EOF
+# Good
+${FENCE}bash
+if [ -z "{GH_REPO}" ]; then echo none; fi
+gh issue view {NUMBER} -R {GH_REPO} --json labels
+${FENCE}
+Prose with it's apostrophe and an unbalanced ( paren.
+EOF
+
+cat > "$T/bad.md" <<EOF
+# Bad
+${FENCE}bash
+if [ -n "\$X" ]; then
+  echo "unterminated
+fi
+${FENCE}
+EOF
+
+cat > "$T/pseudo.md" <<EOF
+${FENCE}bash
+OUT=\$(Skill(skill="x", args="y"))
+${FENCE}
+EOF
+
+cat > "$T/allow.md" <<EOF
+<!-- allowlist:check-spec-bash -->
+${FENCE}bash
+if true; then
+${FENCE}
+EOF
+
+cat > "$T/prose-mention.md" <<EOF
+Use \`<!-- allowlist:check-spec-bash -->\` before an intentional fragment.
+${FENCE}bash
+if true; then
+${FENCE}
+EOF
+
+cat > "$T/notbash.md" <<EOF
+${FENCE}yaml
+key: [unclosed
+${FENCE}
+EOF
+
+check 0 "OK good.md:2"                  "valid block with placeholders passes" -- good.md
+check 1 "FAIL bad.md:2 bash -n"         "unterminated quote fails"             -- bad.md
+check 0 "SKIP pseudo.md:1 pseudo tool"  "pseudo tool call skipped"             -- pseudo.md
+check 0 "SKIP allow.md:2 allowlisted"   "allowlisted fragment skipped"         -- allow.md
+check 0 "checked=0 failed=0"            "non-bash fence ignored"               -- notbash.md
+check 1 "FAIL prose-mention.md:2"      "prose mention of the marker does not allowlist" -- prose-mention.md
+check 1 "checked=2 failed=1 skipped=1"  "multi-file summary"                   -- good.md bad.md pseudo.md
+check 2 ""                              "no files is a usage error"            --
+check 2 ""                              "unknown flag"                         -- --bogus good.md
+
+# --base: only blocks touching changed lines are checked, so pre-existing breakage never fails a change.
+( cd "$T" && git init -q . && git -c user.email=t@t -c user.name=t add bad.md good.md && git -c user.email=t@t -c user.name=t commit -q -m base )
+check 0 "checked=0 failed=0"            "--base with no change checks nothing" -- --base HEAD bad.md good.md
+printf '\nnew prose line\n' >> "$T/bad.md"
+check 0 "checked=0 failed=0"            "--base: prose change outside a broken block passes" -- --base HEAD bad.md
+cat >> "$T/good.md" <<EOF
+${FENCE}bash
+for x in a b; do
+  echo "\$x"
+${FENCE}
+EOF
+check 1 "FAIL good.md:"                 "--base: newly added broken block fails" -- --base HEAD good.md
+
+echo "check-spec-bash.test.sh: passed=$pass failed=$fail"
+[ "$fail" -eq 0 ]

package/scripts/classify-finding.sh

@@ -29,7 +29,7 @@
 #   1. HIGH/CRITICAL, or unparseable severity → ISSUE.
 #   2. Safety exemption is CONTENT-based: the text matches the security/billing
 #      keyword set, or the finding came from a dedicated, signal-selected domain
-#      agent (Auth, Billing, Concurrency, Database). Origin from the always-on
+#      agent (Auth, Billing, Concurrency, Database) and is MEDIUM+ or CONFIRMED. Origin from the always-on
 #      "General Security & Quality" agent alone NO LONGER exempts a finding —
 #      that agent runs on every PR, so origin-based exemption filed nearly every
 #      LOW note it raised (50 of 60 would-be notes in the audited batch).
@@ -93,9 +93,12 @@ KW='security|auth|authz|authn|billing|payment|stripe|charge|invoice|injection|xs
 if printf '%s' "$TEXT" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9\n' ' ' | grep -Eqw "($KW)"; then
   SAFETY="keyword"
 fi
+# A dedicated domain agent rescues a finding only when it is MEDIUM+ or CONFIRMED:
+# a LOW/POSSIBLE finding stays a NOTE whichever reviewer raised it.
 AGENT_LC=$(printf '%s' "$AGENT" | tr '[:upper:]' '[:lower:]')
 case "$AGENT_LC" in
-  auth*|billing*|concurrency*|database*) SAFETY="${SAFETY:-domain-agent}" ;;
+  auth*|billing*|concurrency*|database*)
+    if [ "$SEV" = "MEDIUM" ] || [ "$CONF" = "CONFIRMED" ]; then SAFETY="${SAFETY:-domain-agent}"; fi ;;
 esac
 
 if [ "$LINEAGE" = "review-finding" ]; then

package/scripts/classify-finding.test.sh

@@ -44,10 +44,13 @@ expect ISSUE "LOW with Secrets (case)"        -- --severity LOW --confidence LIK
 expect ISSUE "LOW with permission-check"      -- --severity LOW --confidence LIKELY --text "permission-check skipped"
 expect NOTE  "'author' is not 'auth'"         -- --severity LOW --confidence LIKELY --text "author field unused"
 expect NOTE  "'tokenizer' is not 'token'"     -- --severity LOW --confidence LIKELY --text "tokenizer splits oddly"
-expect ISSUE "LOW from Auth domain agent"     -- --severity LOW --confidence LIKELY --agent "Auth" --text "nit"
-expect ISSUE "LOW from Billing domain agent"  -- --severity LOW --confidence POSSIBLE --agent "billing" --text "nit"
-expect ISSUE "LOW from Database agent"        -- --severity LOW --confidence POSSIBLE --agent "Database" --text "nit"
-expect ISSUE "LOW from Concurrency agent"     -- --severity LOW --confidence POSSIBLE --agent "Concurrency" --text "nit"
+expect ISSUE "LOW CONFIRMED from Auth domain agent" -- --severity LOW --confidence CONFIRMED --agent "Auth" --text "nit"
+expect ISSUE "MEDIUM POSSIBLE from Billing agent"  -- --severity MEDIUM --confidence POSSIBLE --agent "billing" --text "nit"
+expect NOTE  "LOW LIKELY from Auth domain agent is a NOTE" -- --severity LOW --confidence LIKELY --agent "Auth" --text "nit"
+expect NOTE  "LOW POSSIBLE from Database agent is a NOTE"  -- --severity LOW --confidence POSSIBLE --agent "Database" --text "nit"
+expect NOTE  "LOW POSSIBLE Concurrency reviewer is a NOTE (AlterLab #34671)" -- --severity LOW --confidence POSSIBLE --agent "Concurrency reviewer" --text "lock edge cases"
+expect ISSUE "LOW CONFIRMED Concurrency reviewer files" -- --severity LOW --confidence CONFIRMED --agent "Concurrency reviewer" --text "lock edge cases"
+expect ISSUE "keyword still rescues LOW POSSIBLE from domain agent" -- --severity LOW --confidence POSSIBLE --agent "Database" --text "sql injection"
 
 # --- Rule 3: review-finding lineage (fix for a finding) ---
 expect NOTE  "lineage LOW CONFIRMED note"     -- --severity LOW --confidence CONFIRMED --lineage review-finding --text "nit"