feat(test-classifier): local --unpushed run + align path lettering with security (#52)

Add a true no-PR local path so a developer can classify failing tests on their
own machine against whatever they haven't pushed yet (committed + staged), the
testing counterpart to the security runner's --unpushed:

- ai-classifier-dispatch.sh: port resolve_unpushed_base(), add --unpushed
  (sets base + INCLUDE_STAGED), and teach the diff helpers base->index
  (committed + staged) vs base->HEAD.
- test-classifier-dispatcher.sh: skip PR discovery on --unpushed, export
  AI_REVIEW_DIFF_RANGE so the AI diffs exactly what the dispatcher accounts for
  (incl. staged), keep the run report-only (no PR to post to), and fix --help
  erroring on PR lookup before reaching the help text.
- docs/LOCAL_TEST_CLASSIFIER.md: new guide + one-word `test-classifier` zsh
  function, mirroring LOCAL_SECURITY_REVIEW.md.

Renumber the paths to match the security bundle (A = local developer run,
B = reusable CI workflow), so SETUP.md's "mirrors PR_REVIEW_SETUP step for step"
is actually true. Reconciled every Path A/B reference across SETUP.md, README,
BEDROCK.md, and LOCAL_TEST_CLASSIFIER.md; INSTALL.txt was already on this
convention.

Author: fg-nava

testing/classifier/.skills/_lib/ai-classifier-dispatch.sh

@@ -96,11 +96,42 @@ ai_review::err()  { printf '%s[%s] ERROR: %s%s\n' "${AI_C_RED}" "${SKILL_NAME}"
 #   AI_REVIEW_DRY_RUN   ("1" or "0") — print what would happen, do not call AI
 #   AI_REVIEW_NO_BLOCK  ("1" or "0") — run classification but never exit non-zero
 #   AI_REVIEW_AGAINST   (string)     — git ref to diff against (the change under test)
+#   AI_REVIEW_INCLUDE_STAGED ("1"/"0") — when set, diff base→index (committed +
+#                                        staged) instead of base→HEAD; set by --unpushed
 #   AI_REVIEW_REMAINING (array)      — any unparsed args
+
+# ── Base resolution for --unpushed ──────────────────────────────────────────
+# Resolves the "last pushed" point so --unpushed can classify everything not yet
+# pushed (committed + staged). Order: the branch's upstream; else the merge-base
+# with the remote default branch (origin/HEAD, then origin/main, origin/master).
+# Prints the base ref on success; returns non-zero if none can be determined (the
+# caller then errors and asks for an explicit --against rather than silently
+# narrowing scope). Mirrors the security dispatcher's resolver.
+ai_review::resolve_unpushed_base() {
+  local base def
+  base="$(git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)"
+  if [[ -z "${base}" ]]; then
+    # `git rev-parse --abbrev-ref origin/HEAD` echoes the literal "origin/HEAD"
+    # when the symref is unset, which would poison the fallback — use
+    # symbolic-ref, which fails cleanly with empty output.
+    def="$(git symbolic-ref --short -q refs/remotes/origin/HEAD 2>/dev/null || true)"
+    if [[ -z "${def}" ]] && git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+      def="origin/main"
+    fi
+    if [[ -z "${def}" ]] && git rev-parse --verify --quiet origin/master >/dev/null 2>&1; then
+      def="origin/master"
+    fi
+    [[ -n "${def}" ]] && base="$(git merge-base HEAD "${def}" 2>/dev/null || true)"
+  fi
+  [[ -n "${base}" ]] || return 1
+  printf '%s' "${base}"
+}
+
 ai_review::parse_args() {
   AI_REVIEW_DRY_RUN=0
   AI_REVIEW_NO_BLOCK=0
   AI_REVIEW_AGAINST=""
+  AI_REVIEW_INCLUDE_STAGED=0
   AI_REVIEW_REMAINING=()
 
   while [[ $# -gt 0 ]]; do
@@ -125,6 +156,17 @@ ai_review::parse_args() {
         AI_REVIEW_AGAINST="${1#*=}"
         shift
         ;;
+      --unpushed)
+        # Classify everything not yet pushed: committed + staged, i.e. base→index.
+        # No PR required — this is the local backstop (report-only; nothing posts).
+        if ! AI_REVIEW_AGAINST="$(ai_review::resolve_unpushed_base)"; then
+          ai_review::err "--unpushed: couldn't determine what's been pushed (no upstream and no remote default branch)."
+          ai_review::log "  Re-run with an explicit base, e.g.  --against main"
+          exit 2
+        fi
+        AI_REVIEW_INCLUDE_STAGED=1
+        shift
+        ;;
       -h|--help)
         ai_review::print_help
         exit 0
@@ -158,6 +200,11 @@ Options:
   --against <ref>      Classify failures relative to the change between <ref> and
                        HEAD (the "change under test"), e.g. --against origin/main
                        or --against HEAD~1.
+  --unpushed           Classify everything not yet pushed (committed + staged),
+                       resolving the base from the branch's upstream or the
+                       merge-base with the remote default branch. No PR needed —
+                       the run is report-only (nothing is posted). The local
+                       backstop, mirroring the security runner's --unpushed.
   -h, --help           Show this help and exit.
 
 Environment variables:
@@ -227,30 +274,43 @@ ai_review::require_cli() {
 # ── Diff collection ─────────────────────────────────────────────────────────
 # Determines whether there is a "change under test" to reason about.
 # When AI_REVIEW_AGAINST is empty, falls back to the staged diff (local use).
-# When AI_REVIEW_AGAINST is set, uses the diff between that ref and HEAD.
+# When AI_REVIEW_AGAINST is set: base→HEAD (committed range), or base→index
+# (committed + staged) under --unpushed (AI_REVIEW_INCLUDE_STAGED=1).
 ai_review::has_changes() {
   if [[ -n "${AI_REVIEW_AGAINST}" ]]; then
     if ! git rev-parse --verify --quiet "${AI_REVIEW_AGAINST}^{commit}" >/dev/null; then
       ai_review::err "Git ref not found: ${AI_REVIEW_AGAINST}"
       exit 1
     fi
-    ! git diff --quiet "${AI_REVIEW_AGAINST}" HEAD --
+    if [[ "${AI_REVIEW_INCLUDE_STAGED:-0}" == "1" ]]; then
+      ! git diff --cached --quiet "${AI_REVIEW_AGAINST}" --
+    else
+      ! git diff --quiet "${AI_REVIEW_AGAINST}" HEAD --
+    fi
   else
     ! git diff --cached --quiet
   fi
 }
 
 ai_review::changed_files() {
   if [[ -n "${AI_REVIEW_AGAINST}" ]]; then
-    git diff --name-only "${AI_REVIEW_AGAINST}" HEAD --
+    if [[ "${AI_REVIEW_INCLUDE_STAGED:-0}" == "1" ]]; then
+      git diff --cached --name-only "${AI_REVIEW_AGAINST}" --
+    else
+      git diff --name-only "${AI_REVIEW_AGAINST}" HEAD --
+    fi
   else
     git diff --cached --name-only
   fi
 }
 
 ai_review::diff_command_description() {
   if [[ -n "${AI_REVIEW_AGAINST}" ]]; then
-    echo "git diff ${AI_REVIEW_AGAINST} HEAD"
+    if [[ "${AI_REVIEW_INCLUDE_STAGED:-0}" == "1" ]]; then
+      echo "git diff --cached ${AI_REVIEW_AGAINST} (committed + staged, unpushed)"
+    else
+      echo "git diff ${AI_REVIEW_AGAINST} HEAD"
+    fi
   else
     echo "git diff --cached"
   fi

testing/classifier/.skills/test-classifier/scripts/test-classifier-dispatcher.sh

@@ -30,6 +30,7 @@
 #   test-classifier-dispatcher.sh                              # auto-discover PR; print only
 #   test-classifier-dispatcher.sh --pr 1234 --post-comment     # post the PR comment
 #   test-classifier-dispatcher.sh --against origin/main        # explicit base ref
+#   test-classifier-dispatcher.sh --unpushed                   # local: committed+staged, NO PR (report-only)
 #   test-classifier-dispatcher.sh --json-only                  # emit only the JSON block
 #   test-classifier-dispatcher.sh --gate                       # exit 1 on CLASSIFIED
 #   test-classifier-dispatcher.sh --dry-run                    # show plan, no AI call
@@ -78,12 +79,15 @@ fi
 #   --gate                Exit 1 if the result is CLASSIFIED (CI-blocking mode)
 #   --json-only           Print only the JSON block (machine consumption)
 #
-# All other flags (--dry-run, --no-block, --against) fall through to the lib.
+# All other flags (--dry-run, --no-block, --against, --unpushed) fall through to
+# the lib. --unpushed classifies the local committed+staged diff with NO PR —
+# PR discovery is skipped and the run is report-only (nothing posts).
 
 PR_NUMBER=""
 POST_COMMENT=0
 GATE_MODE=0
 JSON_ONLY=0
+WANT_HELP=0
 REMAINING_FOR_LIB=()
 
 while [[ $# -gt 0 ]]; do
@@ -116,6 +120,14 @@ while [[ $# -gt 0 ]]; do
       JSON_ONLY=1
       shift
       ;;
+    -h|--help)
+      # Defer: PR discovery runs before the lib's parser, so a bare --help left
+      # for the lib would error on PR lookup before reaching the help text. We
+      # can't print here either — the lib (which defines print_help) is sourced
+      # below. Flag it and emit right after the source.
+      WANT_HELP=1
+      shift
+      ;;
     *)
       REMAINING_FOR_LIB+=("$1")
       shift
@@ -148,8 +160,14 @@ ai_review::discover_pr_context() {
   # both the PR number and the base ref (e.g. the Jenkins adapter passing
   # CHANGE_ID + CHANGE_TARGET) supplies both flags and we skip `gh pr view`
   # entirely — gh is then needed only to post the comment.
+  # --against (explicit base) and --unpushed (local committed+staged, no PR)
+  # both fix the diff range without needing `gh pr view`. In either case skip
+  # PR discovery: the library's parser resolves the range. With --unpushed there
+  # is no PR, so comment posting stays disabled (the --post-comment guard below
+  # errors on the empty PR number) — a local run is report-only by design.
   for arg in "${REMAINING_FOR_LIB[@]+"${REMAINING_FOR_LIB[@]}"}"; do
-    if [[ "${arg}" == "--against" ]] || [[ "${arg}" == --against=* ]]; then
+    if [[ "${arg}" == "--against" ]] || [[ "${arg}" == --against=* ]] \
+       || [[ "${arg}" == "--unpushed" ]]; then
       if [[ -n "${PR_NUMBER}" ]]; then
         AI_REVIEW_PR_NUMBER="${PR_NUMBER}"
       fi
@@ -240,11 +258,12 @@ in this repository at:
 by scripts/fetch-skills.sh; when the vendored copy is absent the in-repo
 .skills/ copy is used. Either way, follow the file at the path above.)
 
-Classify the failing tests for the change under test — the diff between
-AI_REVIEW_AGAINST and HEAD:
+Classify the failing tests for the change under test. The exact git range is in
+the AI_REVIEW_DIFF_RANGE env var (base→HEAD normally; base→index, i.e. committed
++ staged, for a local --unpushed run). Use it verbatim:
 
-  git diff "\$AI_REVIEW_AGAINST" HEAD --unified=5
-  git diff "\$AI_REVIEW_AGAINST" HEAD --name-only
+  git diff \$AI_REVIEW_DIFF_RANGE --unified=5
+  git diff \$AI_REVIEW_DIFF_RANGE --name-only
 
 Follow the skill instructions in test-classifier/SKILL.md exactly:
 
@@ -295,6 +314,13 @@ PROMPT
 # shellcheck source=../../_lib/ai-classifier-dispatch.sh
 source "${LIB_PATH}"
 
+# --help was requested during arg parsing above; the lib (which defines the help
+# text) is now loaded, so emit it and exit before any PR discovery / AI call.
+if (( WANT_HELP == 1 )); then
+  ai_review::print_help
+  exit 0
+fi
+
 # ── Helpers: JSON extraction and PR-comment posting ────────────────────────
 
 # Pull the JSON block between AI_CLASSIFIER_JSON_BEGIN/END markers out of stdin.
@@ -511,6 +537,16 @@ test_classifier::run() {
 
   export AI_REVIEW_AGAINST
 
+  # The git range the AI should diff, matching the dispatcher's own accounting:
+  #   --unpushed (INCLUDE_STAGED) → `--cached <base>`  (committed + staged)
+  #   otherwise                   → `<base> HEAD`      (committed range)
+  if [[ "${AI_REVIEW_INCLUDE_STAGED:-0}" == "1" ]]; then
+    AI_REVIEW_DIFF_RANGE="--cached ${AI_REVIEW_AGAINST}"
+  else
+    AI_REVIEW_DIFF_RANGE="${AI_REVIEW_AGAINST} HEAD"
+  fi
+  export AI_REVIEW_DIFF_RANGE
+
   local classifier_output
   local invoke_rc=0
   classifier_output="$(ai_review::invoke_ai)" || invoke_rc=$?
@@ -555,7 +591,7 @@ test_classifier::run() {
       ai_review::info "Result is NO_ACTION — nothing to triage, so no PR comment is posted."
     else
       if [[ -z "${AI_REVIEW_PR_NUMBER:-}" ]]; then
-        ai_review::err "--post-comment requires a discoverable PR. Use --pr <number> or ensure 'gh pr view' resolves."
+        ai_review::err "--post-comment requires a discoverable PR. Use --pr <number> or ensure 'gh pr view' resolves. (A --unpushed local run has no PR, so it is report-only — drop --post-comment.)"
         exit 1
       fi
       local json_block

testing/classifier/README.md

@@ -59,7 +59,8 @@ testing/classifier/
 ├── INSTALL.txt                                 ← quick install steps
 ├── docs/
 │   ├── PLAYBOOK.md                             ← the prescriptive pilot playbook
-│   └── SETUP.md                                ← reusable workflow (recommended) + local + vendored setup
+│   ├── SETUP.md                                ← reusable workflow (recommended) + local + vendored setup
+│   └── LOCAL_TEST_CLASSIFIER.md                ← one-word local run (zshrc function, --unpushed)
 ├── .github/
 │   ├── copilot-instructions.md                 ← Copilot test-classification instructions
 │   └── workflows/
@@ -116,8 +117,9 @@ dispatcher contract.
 
 1. Read **`docs/PLAYBOOK.md`** — the four-verdict taxonomy, the metrics loop,
    and the embedded security-considerations section.
-2. Follow **`docs/SETUP.md`** — Path A (reusable workflow, recommended), Path B
-   (run locally), Path C (vendored workflow fallback). On **Jenkins**, follow
+2. Follow **`docs/SETUP.md`** — Path A (run locally), Path B (reusable workflow,
+   the recommended CI backstop), Path C (vendored workflow fallback). On
+   **Jenkins**, follow
    **`jenkins/README.md`** instead (the non-Actions CI path).
 3. Use **`INSTALL.txt`** for the fast-path file-copy steps.
 

testing/classifier/docs/BEDROCK.md

@@ -233,7 +233,7 @@ mandatory, not optional.
 Two ways, matching the two consumption paths in
 [`SETUP.md`](./SETUP.md).
 
-### Path A — Reusable workflow (recommended)
+### Path B — Reusable workflow (recommended)
 
 In your caller workflow (`.github/workflows/ai-test-classifier.yml`), set the
 provider inputs. The example below uses **`aws-auth: static`** — one Bedrock API
@@ -353,7 +353,7 @@ region = "<your region>"
 - **`Could not load credentials from any providers` / role not assumed** — the
   OIDC step failed. Check the role ARN, that the OIDC provider exists in the
   account, and that the trust policy's `:sub` matches `repo:<OWNER>/<REPO>:...`.
-  Confirm `id-token: write` is present **in the caller** (Path A) — the reusable
+  Confirm `id-token: write` is present **in the caller** (Path B) — the reusable
   workflow can't add it.
 - **`on-demand throughput isn't supported`** — you passed a bare model ID. Use a
   cross-region **inference profile** ID (the `us.` prefix), which is the default.