forgedock 1.8.4 → 1.9.1

package/scripts/check-admission-parity.mjs

@@ -13,7 +13,7 @@
  * Usage: node scripts/check-admission-parity.mjs
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import path from "node:path";
 
@@ -78,6 +78,56 @@ function extractBashMirrorPresets(specText) {
   return presets;
 }
 
+/** Recursively list *.md files under a directory. */
+function listMarkdown(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) return listMarkdown(full);
+    return entry.name.endsWith(".md") ? [full] : [];
+  });
+}
+
+/**
+ * Collect identifiers the orchestrate specs name as admission.mjs APIs:
+ * (a) names destructured from an admission.mjs import snippet (`({ a, b }) =>`), and (b) backticked `name()` calls
+ * on any line that mentions admission.mjs. Returns [{ name, file, line }], plus
+ * `{ unattributed: true, file, line }` for destructure snippets that name no module.
+ *
+ * Heuristic limits: a destructure snippet is attributed to the first `engine/<name>.mjs` path found between its
+ * `.then(({` and the next `.then(({` (or end of text), capped at 1500 chars. A snippet naming no module in that
+ * window is reported as unattributable (the lint fails closed). The backtick-call rule is line-scoped: it only
+ * fires on lines that themselves mention admission.mjs, so `plan*()` calls in other prose are not linted.
+ */
+function extractSpecNamedIdentifiers(file, text) {
+  const found = [];
+  const lineOf = (index) => text.slice(0, index).split("\n").length;
+  // The module loaded by a snippet is the first `engine/<name>.mjs` path passed after its `.then(({...}) =>`.
+  const destructure = /\.then\(\(\s*\{([^}]*)\}\s*\)\s*=>/g;
+  const starts = [...text.matchAll(destructure)].map((x) => x.index);
+  let m;
+  while ((m = destructure.exec(text))) {
+    const next = starts.find((s) => s > m.index) ?? text.length;
+    const target = text.slice(m.index, Math.min(next, m.index + 1500)).match(/engine\/([\w-]+)\.mjs/)?.[1];
+    if (!target) {
+      found.push({ unattributed: true, file, line: lineOf(m.index) });
+      continue;
+    }
+    if (target !== "admission") continue;
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s*:\s*/)[0];
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) found.push({ name, file, line: lineOf(m.index) });
+    }
+  }
+  const lines = text.split("\n");
+  lines.forEach((lineText, i) => {
+    if (!lineText.includes("admission.mjs")) return;
+    for (const call of lineText.matchAll(/`([A-Za-z_$][\w$]*)\(\)`/g)) {
+      found.push({ name: call[1], file, line: i + 1 });
+    }
+  });
+  return found;
+}
+
 async function main() {
   let admissionModule;
   try {
@@ -149,6 +199,28 @@ async function main() {
     }
   }
 
+  // Spec-lint: every admission.mjs identifier named in commands/orchestrate/** must be exported.
+  const specDir = path.join(REPO_ROOT, "commands/orchestrate");
+  let namedCount = 0;
+  for (const file of listMarkdown(specDir)) {
+    for (const { name, line, unattributed } of extractSpecNamedIdentifiers(file, readFileSync(file, "utf8"))) {
+      if (unattributed) {
+        console.error(
+          `UNATTRIBUTABLE: ${path.relative(REPO_ROOT, file)}:${line} could not attribute .then(({...}) => snippet to an engine/<module>.mjs path`,
+        );
+        failed = true;
+        continue;
+      }
+      namedCount++;
+      if (!(name in admissionModule)) {
+        console.error(
+          `MISSING EXPORT: ${path.relative(REPO_ROOT, file)}:${line} names "${name}" from admission.mjs, but it is not exported`,
+        );
+        failed = true;
+      }
+    }
+  }
+
   if (failed) {
     console.error("");
     console.error(
@@ -160,6 +232,7 @@ async function main() {
     process.exit(1);
   }
 
+  console.log(`OK: all ${namedCount} admission.mjs identifiers named in commands/orchestrate/** are exported`);
   console.log(
     `OK: admission.mjs CASCADE_PRESETS matches the phase-4-execution.md bash mirror for: ${mjsNames.join(", ")}`,
   );

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/check-spec-markers.sh

@@ -131,6 +131,7 @@ MARKER_REGISTRY="
   MEMORY_INDEXED
   MILESTONE_INDEX
   MODEL_TIER_NOTE
+  NOTE_DISPOSITION
   ORPHAN_ESCALATED
   ORPHAN_RECOVERED
   PATTERN
@@ -138,6 +139,8 @@ MARKER_REGISTRY="
   PHASE_COMPLETE
   PHASE_TRAIL_ERROR
   PHASE_TRAIL_FAILED
+  PHASE_TRAIL_OVERRIDE
+  PHASE_TRAIL_OVERRIDE_APPLIED
   PHASE_TRAIL_RELEASED
   PLAN_DAG
   PRIOR_DECISIONS
@@ -150,6 +153,7 @@ MARKER_REGISTRY="
   RECOVERY_CLAIM
   RECOVERY_CLAIM_RELEASED
   REMEDIATION
+  REREVIEW_DISPATCHED
   REREVIEW_SKIPPED
   REVIEW
   REVIEWER
@@ -289,9 +293,69 @@ fi
 # ---------------------------------------------------------------------------
 
 P4_SPEC="$COMMANDS_DIR/orchestrate/phase-4-execution.md"
-if [ -f "$P4_SPEC" ] && grep -qE 'ABSENT\) +\[ "\$\(reverify_merged_trail "\$PRED"[^)]*\)" = "OK" \] *&& *echo "DONE"' "$P4_SPEC"; then
-  echo "HIGH | $P4_SPEC | merged + needs-human + ABSENT classifies DONE via the verifier (must fail closed to GATED)" >&2
-  VIOLATIONS=$((VIOLATIONS + 1))
+if [ -f "$P4_SPEC" ]; then
+  # ABSENT arm of classify_predecessor_state() (scoped to that function body): text from a line-start "ABSENT)"
+  # inside that function body (an ABSENT) arm elsewhere is ignored) up to the first ";;", whitespace-collapsed so one-line and multi-line
+  # forms reduce to the same span.
+  ABSENT_ARM=$(awk '
+    /^classify_predecessor_state\(\)[[:space:]]*\{/ { infn = 1; next }
+    infn && !inarm && /^\}/ { infn = 0 }
+    infn && !inarm && /^[[:space:]]*ABSENT\)/ { inarm = 1 }
+    inarm {
+      line = $0
+      # Comments are not code: skip full-line comments and drop a trailing
+      # whitespace-preceded "#..." so comment text cannot satisfy or perturb
+      # the assertions below (not quote-aware; the arm text has no quoted "#").
+      if (line ~ /^[[:space:]]*#/) next
+      sub(/[[:space:]]+#.*$/, "", line)
+      idx = index(line, ";;")
+      if (idx > 0) { buf = buf " " substr(line, 1, idx - 1); exit }
+      buf = buf " " line
+    }
+    END { print buf }
+  ' "$P4_SPEC" | tr -s '[:space:]' ' ' || true)
+  # WIRE:PROVEN — manual mutation in a temp copy of commands/: renamed hold_merged_trail, renamed the ABSENT arm, ABSENT->echo DONE, and moved the comment before add-label; each fired its matching HIGH violation; comment-only GATED fires HIGH, comment-only DONE/reverify_merged_trail does not, comment-only gh issue comment before add-label does not count, real arm still passes; a decoy earlier ABSENT) arm outside classify_predecessor_state does not change the result, removing the function declaration fires ABSENT arm missing, and add-label=needs-human / single-quoted forms are accepted
+  if [ -z "${ABSENT_ARM// /}" ]; then
+    echo "HIGH | $P4_SPEC | ABSENT arm missing from classify_predecessor_state (label-only hold must be classified explicitly)" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  else
+    if [[ "$ABSENT_ARM" == *reverify_merged_trail* ]] || [[ "$ABSENT_ARM" == *DONE* ]]; then
+      echo "HIGH | $P4_SPEC | merged + needs-human + ABSENT classifies DONE / calls the verifier (must fail closed to GATED)" >&2
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+    if ! [[ "$ABSENT_ARM" =~ (echo|printf)[^\;]*GATED ]]; then
+      echo "HIGH | $P4_SPEC | ABSENT arm does not resolve to GATED" >&2
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  fi
+
+  # hold_merged_trail() (forge#3223): the needs-human label must be added
+  # before the FORGE:PHASE_TRAIL_FAILED comment is posted, so a comment can
+  # never exist without the label (comment-without-label reads as a release).
+  HOLD_ORDER=$(awk '
+    /^hold_merged_trail\(\)[[:space:]]*\{/ { infn = 1; found = 1; next }
+    infn && /^\}/ { infn = 0 }
+    infn {
+      line = $0
+      if (line ~ /^[[:space:]]*#/) next
+      sub(/[[:space:]]+#.*$/, "", line)
+      if (!cmt && (line ~ /gh issue comment/ || line ~ /FORGE:PHASE_TRAIL_FAILED/)) cmt = NR
+      if (!lbl && line ~ /add-label(=|[[:space:]]+)[\047"]?needs-human/) lbl = NR
+    }
+    END { printf "%d %d %d\n", found + 0, cmt + 0, lbl + 0 }
+  ' "$P4_SPEC" || true)
+  set -- $HOLD_ORDER
+  HOLD_FOUND="${1:-0}"; HOLD_CMT="${2:-0}"; HOLD_LBL="${3:-0}"
+  if [ "$HOLD_FOUND" -eq 0 ]; then
+    echo "HIGH | $P4_SPEC | hold_merged_trail() function missing" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  elif [ "$HOLD_CMT" -eq 0 ] || [ "$HOLD_LBL" -eq 0 ]; then
+    echo "HIGH | $P4_SPEC | hold_merged_trail() lacks the PHASE_TRAIL_FAILED comment or the needs-human add-label" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  elif [ "$HOLD_LBL" -ge "$HOLD_CMT" ]; then
+    echo "HIGH | $P4_SPEC | hold_merged_trail() posts the PHASE_TRAIL_FAILED comment before adding needs-human (label must come first)" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
 fi
 
 # ---------------------------------------------------------------------------

package/scripts/classify-finding.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# classify-finding.sh — Deterministic review-pr §6B.5 note disposition.
+#                        Decides whether one deduped review finding is filed
+#                        as a standalone `review-finding` issue (ISSUE) or
+#                        handled as a non-blocking note (NOTE).
+#
+# Usage:
+#   classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>]
+#                       [--lineage none|review-finding] [--text <T> | --text-file <F>]
+#
+#   --severity    CRITICAL | HIGH | MEDIUM | LOW (case-insensitive). Missing or
+#                 unparseable → ISSUE (fail toward filing, never drop).
+#   --confidence  CONFIRMED | LIKELY | POSSIBLE (case-insensitive). Missing is
+#                 treated as not-POSSIBLE.
+#   --agent       The `**Agent**:` value of the finding (e.g. "Security", "Auth").
+#   --lineage     `review-finding` when the PR's linked issue (MERGE_ISSUE) carries
+#                 the `review-finding` label — i.e. this PR is itself a fix for a
+#                 review finding. Default `none`.
+#   --text/--text-file  Finding title + body + affected file paths, used for the
+#                 content-based safety exemption.
+#
+# Output (stdout, one line): `ISSUE <reason>` or `NOTE <reason>`.
+# Exit codes: 0 classified, 2 usage error.
+#
+# Rules (forge#3060, tightened after the 2026-10-08 cascade audit):
+#   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) 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).
+#   3. Review-finding lineage (a fix for a finding): only MEDIUM findings that are
+#      CONFIRMED, or LIKELY and safety-exempt, become issues. LOW is always a
+#      NOTE — a fix for a finding must not mint a new generation of findings.
+#   4. Otherwise: LOW, or POSSIBLE below HIGH, is a NOTE unless safety-exempt.
+#
+# NOTEs are never discarded silently: review-pr §6B.5 fixes them in-PR, lists
+# them in the PR body, or records a drop reason in the review summary.
+#
+# Portable: bash 3.2 (macOS /bin/bash), BSD and GNU grep/tr. No network.
+
+set -u
+
+SEVERITY=""
+CONFIDENCE=""
+AGENT=""
+LINEAGE="none"
+TEXT=""
+
+usage() {
+  echo "ERROR: Usage: classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>] [--lineage none|review-finding] [--text <T> | --text-file <F>]" >&2
+  exit 2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --severity)   [ "$#" -ge 2 ] || usage; SEVERITY="$2"; shift 2 ;;
+    --confidence) [ "$#" -ge 2 ] || usage; CONFIDENCE="$2"; shift 2 ;;
+    --agent)      [ "$#" -ge 2 ] || usage; AGENT="$2"; shift 2 ;;
+    --lineage)    [ "$#" -ge 2 ] || usage; LINEAGE="$2"; shift 2 ;;
+    --text)       [ "$#" -ge 2 ] || usage; TEXT="$2"; shift 2 ;;
+    --text-file)
+      [ "$#" -ge 2 ] || usage
+      [ -r "$2" ] || { echo "ERROR: --text-file not readable: $2" >&2; exit 2; }
+      TEXT=$(cat "$2"); shift 2 ;;
+    *) usage ;;
+  esac
+done
+
+case "$LINEAGE" in
+  none|review-finding) ;;
+  *) echo "ERROR: --lineage must be 'none' or 'review-finding' (got '$LINEAGE')" >&2; exit 2 ;;
+esac
+
+upper() { printf '%s' "$1" | tr '[:lower:]' '[:upper:]' | tr -d '[:space:]'; }
+SEV=$(upper "$SEVERITY")
+CONF=$(upper "$CONFIDENCE")
+
+case "$SEV" in
+  CRITICAL|HIGH) echo "ISSUE severity-$SEV"; exit 0 ;;
+  MEDIUM|LOW) ;;
+  *) echo "ISSUE unparseable-severity"; exit 0 ;;
+esac
+
+# Safety exemption. Keywords match whole words, where `_`, `-`, `/` and other
+# punctuation separate words (so `auth_service` matches, `author` does not).
+SAFETY=""
+KW='security|auth|authz|authn|billing|payment|stripe|charge|invoice|injection|xss|csrf|ssrf|idor|secret|secrets|credential|credentials|permission|permissions|sql|token|password|redact'
+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*)
+    if [ "$SEV" = "MEDIUM" ] || [ "$CONF" = "CONFIRMED" ]; then SAFETY="${SAFETY:-domain-agent}"; fi ;;
+esac
+
+if [ "$LINEAGE" = "review-finding" ]; then
+  if [ "$SEV" = "MEDIUM" ] && { [ "$CONF" = "CONFIRMED" ] || { [ -n "$SAFETY" ] && [ "$CONF" = "LIKELY" ]; }; }; then
+    echo "ISSUE lineage-medium-${CONF:-UNKNOWN}"
+  else
+    echo "NOTE lineage-${SEV}-${CONF:-UNKNOWN}"
+  fi
+  exit 0
+fi
+
+if [ "$SEV" = "LOW" ] || [ "$CONF" = "POSSIBLE" ]; then
+  if [ -n "$SAFETY" ]; then
+    echo "ISSUE safety-exemption-$SAFETY"
+  else
+    echo "NOTE ${SEV}-${CONF:-UNKNOWN}"
+  fi
+  exit 0
+fi
+
+echo "ISSUE ${SEV}-${CONF:-UNKNOWN}"
+exit 0

package/scripts/classify-finding.test.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/classify-finding.sh (review-pr §6B.5 note disposition).
+# Run: bash scripts/classify-finding.test.sh   (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/classify-finding.sh"
+pass=0; fail=0
+
+expect() { # expect <ISSUE|NOTE> <description> -- args...
+  want="$1"; desc="$2"; shift 3
+  got=$(bash "$S" "$@" 2>/dev/null | cut -d' ' -f1)
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want $want, got '${got}')"; fi
+}
+expect_exit() { # expect_exit <code> <description> -- args...
+  want="$1"; desc="$2"; shift 3
+  bash "$S" "$@" >/dev/null 2>&1; got=$?
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want exit $want, got $got)"; fi
+}
+
+# --- Rule 1: high severity and unparseable severity always file ---
+expect ISSUE "CRITICAL files"                 -- --severity CRITICAL --confidence POSSIBLE
+expect ISSUE "HIGH POSSIBLE files"            -- --severity HIGH --confidence POSSIBLE
+expect ISSUE "HIGH on lineage files"          -- --severity HIGH --confidence LIKELY --lineage review-finding
+expect ISSUE "missing severity files"         -- --severity "" --confidence LIKELY
+expect ISSUE "unknown severity files"         -- --severity INFO
+expect ISSUE "lowercase high files"           -- --severity high
+
+# --- Rule 4: non-lineage ---
+expect ISSUE "MEDIUM CONFIRMED files"         -- --severity MEDIUM --confidence CONFIRMED --text "loop exits early"
+expect ISSUE "MEDIUM LIKELY files"            -- --severity MEDIUM --confidence LIKELY --text "loop exits early"
+expect NOTE  "MEDIUM POSSIBLE no-safety note" -- --severity MEDIUM --confidence POSSIBLE --text "loop exits early"
+expect NOTE  "LOW CONFIRMED no-safety note"   -- --severity LOW --confidence CONFIRMED --text "stale comment wording"
+expect NOTE  "LOW from Security agent, no keyword, is a NOTE (audit fix)" -- --severity LOW --confidence CONFIRMED --agent "Security" --text "comment wording drifted"
+expect NOTE  "LOW from General Security & Quality, no keyword" -- --severity LOW --confidence LIKELY --agent "General Security & Quality" --text "duplicated predicate in NOTE count"
+
+# --- Safety exemption (content-based) ---
+expect ISSUE "LOW with injection keyword"     -- --severity LOW --confidence POSSIBLE --text "shell injection via unquoted var"
+expect ISSUE "LOW with auth_service path"     -- --severity LOW --confidence LIKELY --text "src/auth_service.py:12 missing check"
+expect ISSUE "LOW with Secrets (case)"        -- --severity LOW --confidence LIKELY --text "Secrets leak to log"
+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 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"
+expect NOTE  "lineage LOW security keyword still note" -- --severity LOW --confidence CONFIRMED --lineage review-finding --text "injection nit"
+expect ISSUE "lineage MEDIUM CONFIRMED files" -- --severity MEDIUM --confidence CONFIRMED --lineage review-finding --text "logic bug"
+expect NOTE  "lineage MEDIUM LIKELY no-safety note" -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "logic bug"
+expect ISSUE "lineage MEDIUM LIKELY with keyword files" -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "token leaks"
+expect NOTE  "lineage MEDIUM POSSIBLE with keyword note" -- --severity MEDIUM --confidence POSSIBLE --lineage review-finding --text "token leaks"
+
+# --- text-file input ---
+TMPF=$(mktemp "${TMPDIR:-/tmp}/classify-finding-test.XXXXXX")
+printf 'Title: unchecked xss sink\n' > "$TMPF"
+expect ISSUE "text-file keyword"              -- --severity LOW --confidence LIKELY --text-file "$TMPF"
+rm -f "$TMPF"
+
+# --- usage errors ---
+expect_exit 2 "unknown flag"                  -- --bogus x
+expect_exit 2 "bad lineage"                   -- --severity LOW --lineage P3
+expect_exit 2 "missing flag value"            -- --severity
+expect_exit 2 "unreadable text-file"          -- --severity LOW --text-file /nonexistent/x
+expect_exit 0 "valid call exits 0"            -- --severity LOW
+
+echo "classify-finding.test.sh: passed=$pass failed=$fail"
+[ "$fail" -eq 0 ]