feat(test-classifier): post-to-PR + --submit one-shot metrics (auto-mint, Testing Events) (#61)

* feat(test-classifier): let the zsh function pass flags through (post to PR)

The test-classifier function hardcoded its arg mapping (no-arg → --unpushed,
$1 → --against $1) and swallowed everything else, so there was no way to post a
comment — you had to drop down to calling the dispatcher directly. That's a dead
end for the common "classify and post to my PR" case.

New routing (back-compatible):
  - no args        → --unpushed              (unchanged)
  - bare ref       → --against <ref>         (unchanged)
  - starts with -  → passed straight through (NEW: --pr 42 --post-comment,
                     --post-comment, --dry-run, --json-only, …)
  - ref + flags    → --against <ref> <flags> (NEW combo)

So `test-classifier --pr 42 --post-comment` now just works. Verified all six
routing forms against a stub dispatcher; function is bash- and zsh-clean.

Docs updated: function header, "what it does", Usage (with posting examples),
and the report-only framing (now "report-only by default; opt in to posting").
Added a note that locally-posted comments are dev-authored, so metricsai needs
--all-authors / METRICSAI_TESTING_GITHUB_AUTHORS to count them.

* feat(test-classifier): --submit — classify, post, prompt, record in one shot

Streamlines the manual local metrics loop (Foad's idea): instead of post comment
→ react 👍/👎 on GitHub → wait for the weekly harvest, capture the signal right
after the run. --submit implies --post-comment, then on an interactive run
prompts "Was the classification helpful? [y/n]" and appends ONE row to the
Sheet's Testing Events tab — repo, pr, comment_id, verdict, category, confidence,
thumbs_up, thumbs_down, reason (the same column contract the harvester writes).

- Capture the new comment's id from the post (was discarded) for the row.
- submit_metrics_row(): TTY-gated prompt; collapses multiple classifications to
  one representative verdict by most-actionable rank; appends via the Sheets
  values:append API to the "Testing Events" tab (NOT the weekly CXT/DMOD/… tabs).
- Non-TTY / CI: posts the comment, skips the prompt + row (no hang) — CI metrics
  still come from the central weekly harvest.
- No GOOGLE_SHEETS_TOKEN/SHEET_ID: records the answer to the terminal, warns no
  sink, still posts. Reuses the harvester's exact env var names.

Works through the zsh function as-is (it passes flags through):
test-classifier --pr 42 --submit. Verified: payload + Testing-Events URL build
correctly, append fails gracefully on bad creds, non-TTY gate trips, verdict
collapse picks the most-actionable. bash -n clean.

* feat(test-classifier): --submit auto-mints token; align to Testing Events 10-col

Make --submit set-and-forget and match the live sheet.

Auto-mint (no per-session token juggling):
- --submit mints a short-lived Sheets token via gcloud by impersonating the
  pilot SA (defaults to metrics-sheets-writer@nava-labs.iam.gserviceaccount.com,
  the SA the central sweep uses; override with METRICSAI_SA_EMAIL). An explicit
  GOOGLE_SHEETS_TOKEN still wins (CI). gcloud/impersonation failure → warns,
  still posts the comment.

Column alignment (the Testing Events tab header):
  repo, pr, comment_id, comment_created_at, verdict, category, confidence,
  thumbs_up, thumbs_down, reason
- --submit now emits comment_created_at (from the comment POST response, else
  date -u) — captured alongside the comment id. Adds the 10th column (reason).
- The shell harvester (test_classifier_comments.sh) is aligned to the same 10
  columns + order (it already had .created_at for windowing; now emits it).
- Fix the A1 range: the tab name has a space, so it must be single-quoted —
  'Testing Events'!A1 (matches the sweep). Both writers now default to it.

Docs: SHEET_ID = the pilot sheet; one-line ~/.zshrc setup; auto-mint + override
notes; two-writers-one-tab (deduped by comment_id) clarified.

* fix(test-classifier): --submit posts via the metricsai webhook, not direct Sheets API

Switch --submit to Brian's webhook transport (the one that actually works) and
fix a false-failure bug found while probing the live endpoint.

- Replace the SA / gcloud / direct Sheets values:append path with a POST to the
  metricsai Apps Script webhook: flat JSON named fields + reserved _tab / _key,
  same as metricsai's client. Env is now METRICSAI_WEBHOOK_URL +
  METRICSAI_WEBHOOK_KEY (both static — no service account, no short-lived token,
  no gcloud). The SA approach was a dead end: gcloud ignores --scopes for
  impersonated accounts, so the minted token lacked the spreadsheets scope.
- The script aligns fields by header name, so column order no longer matters;
  _tab defaults to "Testing Events" (override: METRICSAI_WEBHOOK_TAB).
- Fix success detection: the write happens at the /exec 302, and following that
  redirect can 405 on the final Drive hop even though the row landed. Stop using
  `curl -f -L` (false failure) — capture the first-hop status; 200/302 = success.

Verified live against the real webhook: a full 10-field row posts and lands in
the Testing Events tab with every value under its correct header.

Also: gitignore .env.local / .env so local webhook creds never get committed.

Author: fg-nava

.gitignore

@@ -1 +1,3 @@
 .claude/settings.local.json
+.env.local
+.env

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

@@ -29,6 +29,7 @@
 # Usage:
 #   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 --pr 1234 --submit           # post + prompt "helpful?" + append a Testing Events row
 #   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
@@ -40,6 +41,13 @@
 #
 # Required when --post-comment is used:
 #   gh CLI installed and authenticated; or GH_TOKEN exported
+#
+# Required when --submit posts the metrics row (interactive runs only):
+#   METRICSAI_WEBHOOK_URL + METRICSAI_WEBHOOK_KEY (the metricsai Apps Script
+#   endpoint + the AI Metrics API key — both static, set once). Row posts to the
+#   "Testing Events" tab (override: METRICSAI_WEBHOOK_TAB). Absent → posts the
+#   comment + prompts but skips the row. Same transport metricsai uses; no
+#   service account or gcloud token needed.
 
 set -euo pipefail
 
@@ -72,6 +80,10 @@ SKILL_PATH_CANONICAL=".skills/test-classifier/SKILL.md"
 #
 #   --pr <number>         Explicit PR number (overrides auto-discovery)
 #   --post-comment        Post ONE PR comment via gh api (omit to print only)
+#   --submit              Implies --post-comment; then (interactive only) prompts
+#                         "Was this helpful?" and appends one Testing Events row
+#                         to the Sheet with the verdict + 👍/👎. Non-TTY/CI: posts
+#                         and skips the prompt + row.
 #   --gate                Exit 1 if the result is CLASSIFIED (CI-blocking mode)
 #   --json-only           Print only the JSON block (machine consumption)
 #
@@ -84,6 +96,9 @@ POST_COMMENT=0
 GATE_MODE=0
 JSON_ONLY=0
 WANT_HELP=0
+SUBMIT=0
+POSTED_COMMENT_ID=""        # set by the post functions; consumed by --submit
+POSTED_COMMENT_CREATED=""   # the comment's created_at (ISO-8601) from the API
 REMAINING_FOR_LIB=()
 
 while [[ $# -gt 0 ]]; do
@@ -108,6 +123,14 @@ while [[ $# -gt 0 ]]; do
       POST_COMMENT=1
       shift
       ;;
+    --submit)
+      # Streamlined local loop: post the comment AND, when run interactively,
+      # prompt "Was this helpful?" and append the answer as one Testing Events
+      # row to the Sheet. Implies --post-comment (the row needs the comment_id).
+      SUBMIT=1
+      POST_COMMENT=1
+      shift
+      ;;
     --gate)
       GATE_MODE=1
       shift
@@ -489,16 +512,21 @@ post_issue_comment_to_github() {
   local pr_number="$2"
   local body="$3"
 
-  # Pass the body via --field so gh handles JSON escaping for us.
-  if ! gh api \
+  # Pass the body via --field so gh handles JSON escaping for us. Capture id +
+  # created_at (for --submit's metrics row); empty string on failure.
+  local resp=""
+  resp="$(gh api \
         "repos/${repo_slug}/issues/${pr_number}/comments" \
         --method POST \
-        --field body="${body}" >/dev/null; then
+        --field body="${body}" --jq '"\(.id)\t\(.created_at)"' 2>/dev/null || true)"
+  if [[ -z "$resp" || "$resp" == $'\t' ]]; then
     echo "ERROR: 'gh api' issue-comment call failed." >&2
     echo "       Check your gh auth status and that your token has 'pull-requests: write'" >&2
     echo "       (or 'issues: write')." >&2
     return 1
   fi
+  POSTED_COMMENT_ID="${resp%%$'\t'*}"
+  POSTED_COMMENT_CREATED="${resp#*$'\t'}"
 }
 
 # Post ONE classification comment to the PR. Args: PR number, comment body.
@@ -547,13 +575,19 @@ post_comment_to_github() {
 
   if [[ -n "$anchor_path" && -n "$commit_id" ]]; then
     echo "[test-classifier] Posting classification as a review comment on ${repo_slug} PR #${pr_number} (anchored to ${anchor_path})..."
-    if gh api \
+    # Capture id + created_at from the response so --submit can record them.
+    # jq joins them with a tab; empty string on failure.
+    local resp=""
+    resp="$(gh api \
           "repos/${repo_slug}/pulls/${pr_number}/comments" \
           --method POST \
           --field body="${body}" \
           --field commit_id="${commit_id}" \
           --field path="${anchor_path}" \
-          --field subject_type=file >/dev/null 2>&1; then
+          --field subject_type=file --jq '"\(.id)\t\(.created_at)"' 2>/dev/null || true)"
+    if [[ -n "$resp" && "$resp" != $'\t' ]]; then
+      POSTED_COMMENT_ID="${resp%%$'\t'*}"
+      POSTED_COMMENT_CREATED="${resp#*$'\t'}"
       echo "[test-classifier] Review comment posted. Awaiting the developer's 👍/👎 reaction (and a reply reason on a 👎)."
       return 0
     fi
@@ -570,6 +604,121 @@ post_comment_to_github() {
   echo "[test-classifier] Comment posted (issue comment). Awaiting the developer's 👍/👎 reaction."
 }
 
+# ── --submit: prompt "Was this helpful?" and post one row via the webhook ───
+# Streamlines the manual local loop: instead of (post comment → react 👍/👎 on
+# GitHub → a separate weekly harvest), capture the developer's signal right after
+# the run and POST it to the metricsai Google Apps Script webhook — the SAME
+# transport metricsai uses (flat JSON body, fields aligned by header name, plus
+# reserved `_tab` and `_key`). No service account, no gcloud, no token expiry —
+# just two static env vars the developer sets once.
+#
+# Fields (aligned by header name on the Apps Script side):
+#   repo, pr, comment_id, comment_created_at, verdict, category, confidence,
+#   thumbs_up, thumbs_down, reason   (+ _tab="Testing Events", _key=<api key>)
+#
+# Env:
+#   METRICSAI_WEBHOOK_URL   the Apps Script /exec endpoint        (required)
+#   METRICSAI_WEBHOOK_KEY   the "AI Metrics" API key (body _key)  (required)
+#   METRICSAI_WEBHOOK_TAB   destination tab; defaults to Testing Events
+#
+# Gated: only runs interactively (TTY, not CI) — non-interactive runs post the
+# comment and skip the prompt + POST (no human signal to record, no hang).
+# Missing URL/key → records the answer to the terminal, warns, still posts the
+# comment.
+#
+# Args: PR number, the extracted classifier JSON.
+submit_metrics_row() {
+  local pr_number="$1"
+  local classifier_json="$2"
+
+  if [[ ! -t 0 ]] || [[ "${CI:-}" == "true" ]]; then
+    ai_review::info "--submit: non-interactive run — comment posted; skipping the helpfulness prompt + metrics row." >&2
+    return 0
+  fi
+  if ! command -v python3 &>/dev/null; then
+    ai_review::warn "--submit: python3 not found; cannot build the metrics row — skipping it." >&2
+    return 0
+  fi
+
+  # Prompt for the tuning signal. Empty/invalid → skip (don't guess a verdict).
+  local answer reason="" thumbs_up=0 thumbs_down=0
+  printf '%s' "  Was the classification helpful? [y/n] (enter to skip): " >&2
+  read -r answer
+  case "${answer}" in
+    y|Y|yes|YES) thumbs_up=1 ;;
+    n|N|no|NO)
+      thumbs_down=1
+      printf '%s' "  Optional one-line reason (enter to skip): " >&2
+      read -r reason
+      ;;
+    *)
+      ai_review::info "--submit: no answer — skipping the metrics row (comment still posted)." >&2
+      return 0
+      ;;
+  esac
+
+  local webhook_url="${METRICSAI_WEBHOOK_URL:-}"
+  local webhook_key="${METRICSAI_WEBHOOK_KEY:-}"
+  local webhook_tab="${METRICSAI_WEBHOOK_TAB:-Testing Events}"
+  if [[ -z "${webhook_url}" || -z "${webhook_key}" ]]; then
+    ai_review::warn "--submit: METRICSAI_WEBHOOK_URL / METRICSAI_WEBHOOK_KEY not set — recorded your answer but didn't post a row." >&2
+    ai_review::log  "  Export both (the metricsai webhook URL + the AI Metrics API key) to enable the sink." >&2
+    return 0
+  fi
+
+  local repo_slug
+  repo_slug="$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null || echo "")"
+
+  # The classifier may emit multiple classifications; the Testing Events row is
+  # per-comment, so collapse to one representative verdict by most-actionable
+  # rank (APPLICATION_BUG > TEST_BUG > FLAKY_FAILURE > ENVIRONMENT_ISSUE) — the
+  # same rule the harvester uses. Returns: verdict<TAB>category<TAB>confidence.
+  local repr
+  repr="$(printf '%s' "${classifier_json}" | python3 -c '
+import json, sys
+RANK = {"APPLICATION_BUG":3,"TEST_BUG":2,"FLAKY_FAILURE":1,"ENVIRONMENT_ISSUE":0}
+try:
+    cls = (json.load(sys.stdin) or {}).get("classifications") or []
+except Exception:
+    cls = []
+if not cls:
+    print("\t\t"); sys.exit(0)
+best = max(cls, key=lambda c: RANK.get(c.get("verdict",""), -1))
+print("\t".join([best.get("verdict","") or "", best.get("category","") or "", best.get("confidence","") or ""]))
+' 2>/dev/null || printf '\t\t')"
+  local verdict category confidence
+  IFS=$'\t' read -r verdict category confidence <<< "${repr}"
+
+  # comment_created_at comes from the comment POST response; fall back to now.
+  local created_at="${POSTED_COMMENT_CREATED:-}"
+  [[ -n "${created_at}" ]] || created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")"
+
+  # Flat JSON body: named fields (Apps Script aligns by header) + reserved
+  # _tab / _key. Built with python3 so values are safely JSON-escaped.
+  local body
+  body="$(python3 -c '
+import json, sys
+keys = ["repo","pr","comment_id","comment_created_at","verdict","category",
+        "confidence","thumbs_up","thumbs_down","reason","_tab","_key"]
+print(json.dumps(dict(zip(keys, sys.argv[1:1+len(keys)]))))
+' "${repo_slug}" "${pr_number}" "${POSTED_COMMENT_ID}" "${created_at}" "${verdict}" "${category}" "${confidence}" "${thumbs_up}" "${thumbs_down}" "${reason}" "${webhook_tab}" "${webhook_key}")"
+
+  # The Apps Script writes the row in doPost and answers /exec with a 302 to a
+  # googleusercontent URL. The WRITE has already happened at that 302 — following
+  # it can 405 on the final Drive hop even though the row landed, so we must NOT
+  # use `-f -L` (that reports a false failure). Capture the first-hop status and
+  # treat 200/302 as success; don't follow the redirect.
+  local http_code
+  http_code="$(curl -sS -o /dev/null -w '%{http_code}' -X POST "${webhook_url}" \
+        -H "Content-Type: application/json" \
+        -d "${body}" 2>/dev/null || echo "000")"
+  if [[ "${http_code}" == "200" || "${http_code}" == "302" ]]; then
+    ai_review::ok "--submit: posted a row to the metrics webhook (tab=${webhook_tab}, verdict=${verdict:-?}, $([ "${thumbs_up}" = 1 ] && echo 👍 || echo 👎))."
+  else
+    ai_review::warn "--submit: webhook POST failed (HTTP ${http_code}; your answer was not recorded). Check METRICSAI_WEBHOOK_URL / METRICSAI_WEBHOOK_KEY." >&2
+  fi
+}
+
 # ── Custom run loop (mirrors the security PR dispatcher) ────────────────────
 test_classifier::run() {
   # Discover the PR (and inject --against into REMAINING_FOR_LIB).
@@ -592,6 +741,7 @@ test_classifier::run() {
     ai_review::log  "  PR number:      ${AI_REVIEW_PR_NUMBER:-(none — using --against directly)}"
     ai_review::log  "  Diff source:    $(ai_review::diff_command_description)"
     ai_review::log  "  Post comment:   ${POST_COMMENT}"
+    ai_review::log  "  Submit metrics: ${SUBMIT}"
     ai_review::log  "  Gate mode:      ${GATE_MODE}"
     ai_review::log  "  Changed files:"
     ai_review::changed_files | sed 's/^/    /'
@@ -679,6 +829,12 @@ test_classifier::run() {
       local comment_body
       comment_body="$(render_pr_comment_body "${json_block}")"
       post_comment_to_github "${AI_REVIEW_PR_NUMBER}" "${comment_body}"
+
+      # --submit: prompt for the helpfulness signal and append a Testing Events
+      # row (interactive only; no-ops cleanly in CI / non-TTY).
+      if (( SUBMIT == 1 )); then
+        submit_metrics_row "${AI_REVIEW_PR_NUMBER}" "${json_block}"
+      fi
     fi
   fi
 

testing/classifier/docs/LOCAL_TEST_CLASSIFIER.md

@@ -24,8 +24,9 @@ and uses the same `--unpushed` scope rule. This is the ergonomics layer over
   while you're still iterating.
 - **It's a local preview, not the gate.** The PR run (Path B) is the recorded
   backstop that feeds the metrics loop. The local run is for the developer's own
-  fast feedback before pushing; it is **report-only** — it never posts a PR
-  comment (there's no PR to post to) and never blocks anything.
+  fast feedback before pushing; it never blocks anything. By default it's
+  **report-only** (prints to your terminal, posts nothing) — but you can opt in
+  to posting against a real PR with `--pr N --post-comment` (see Usage).
 - **OBSERVED on demand.** By default a local run is INFERRED (it predicts from
   the diff — read-only, never touches your machine's toolchain). Opt into
   OBSERVED with `AI_RUN_SUITE=1` to have the agent actually locate, install, and
@@ -60,9 +61,12 @@ it's only needed for the PR-based modes (`--pr` / auto-discovery / `--post-comme
 Paste this block into `~/.zshrc`, then `source ~/.zshrc` (or open a new shell):
 
 ```zsh
-# AI test classifier — local, report-only.
-#   <no arg>  → classify everything not yet pushed (committed + staged)
-#   <ref>     → classify the committed range <ref>..HEAD
+# AI test classifier.
+#   <no arg>   → classify everything not yet pushed (committed + staged); report-only
+#   <ref>      → classify the committed range <ref>..HEAD; report-only
+#   <flags...> → passed straight to the dispatcher. This is how you post to a PR:
+#                test-classifier --pr 42 --post-comment   (or --post-comment to
+#                auto-discover the current branch's PR). Needs gh authed.
 # Prefix with AI_RUN_SUITE=1 to run the suite locally (OBSERVED) instead of
 # inferring from the diff:  AI_RUN_SUITE=1 test-classifier
 test-classifier() {
@@ -72,12 +76,19 @@ test-classifier() {
   disp="$root/testing/classifier/.skills/test-classifier/scripts/test-classifier-dispatcher.sh"
   [ -x "$disp" ] \
     || { echo "✗ test-classifier dispatcher not found/executable: $disp"; return 1; }
-  if [ -n "$1" ]; then
-    echo "▶ test-classifier: ${1}..HEAD (committed range)"
-    "$disp" --against "$1"
-  else
+  if [ "$#" -eq 0 ]; then
+    # No args → classify everything not yet pushed (committed + staged).
     echo "▶ test-classifier: all not-yet-pushed changes (committed + staged)"
     "$disp" --unpushed
+  elif [ "${1#-}" != "$1" ]; then
+    # First arg is a flag (starts with -) → pass everything straight through.
+    # This is how you post to a PR: test-classifier --pr 42 --post-comment
+    "$disp" "$@"
+  else
+    # First arg is a bare ref → --against <ref>; pass any remaining flags too.
+    local ref="$1"; shift
+    echo "▶ test-classifier: ${ref}..HEAD (committed range)"
+    "$disp" --against "$ref" "$@"
   fi
 }
 ```
@@ -89,13 +100,18 @@ What the function does:
    function works from any subdirectory.
 2. **Locates the dispatcher** under `testing/classifier/` and confirms it's
    executable.
-3. **Runs the classifier** by calling the dispatcher directly:
+3. **Runs the classifier** by calling the dispatcher:
    - **no argument** → `--unpushed`: everything not yet pushed (committed +
      staged). The base is your branch's upstream, falling back to the merge-base
      with the remote default branch. If neither can be determined (e.g. a
      brand-new branch with no remote), it errors and asks for an explicit ref
      rather than silently classifying less than you expect.
-   - **a ref** → `--against <ref>`: the committed range `<ref>..HEAD`.
+   - **a bare ref** → `--against <ref>`: the committed range `<ref>..HEAD`.
+   - **anything starting with `-`** → passed straight through to the dispatcher.
+     This is how you post to a PR — `test-classifier --pr 42 --post-comment`
+     (or just `--post-comment` to auto-discover the current branch's PR), plus
+     any other dispatcher flag (`--dry-run`, `--json-only`, …). You can combine a
+     ref with flags too: `test-classifier origin/main --post-comment`.
 
 ---
 
@@ -107,7 +123,72 @@ test-classifier origin/main           # the committed range origin/main..HEAD
 test-classifier HEAD~1                # just the last commit
 
 AI_RUN_SUITE=1 test-classifier        # run the suite locally and triage REAL failures (OBSERVED)
+
+# Post the result as a PR comment (needs an open PR + gh authed):
+test-classifier --post-comment              # auto-discovers the current branch's PR
+test-classifier --pr 42 --post-comment      # explicit PR number
+AI_RUN_SUITE=1 test-classifier --pr 42 --post-comment   # OBSERVED + post
+
+# Streamlined: post AND record the metric in one shot (see --submit below):
+test-classifier --pr 42 --submit
+```
+
+> **Posting authorship.** A locally-posted comment is authored by **you**, not
+> `github-actions[bot]`. For the comment to be picked up by the weekly metrics
+> harvest, `metricsai` must be told to count your author (`--all-authors` or
+> `METRICSAI_TESTING_GITHUB_AUTHORS`); by default it only counts the CI bot. For
+> just *posting to the PR*, this doesn't matter.
+
+---
+
+## `--submit` — classify, post, and record the metric in one shot
+
+The slow path to metrics is: post a comment → react 👍/👎 on GitHub later → wait
+for the weekly harvest. `--submit` collapses that into the run you're already
+doing. After classifying and posting, it prompts right in the terminal:
+
 ```
+  Was the classification helpful? [y/n] (enter to skip):
+```
+
+Your answer is appended **immediately** as one row to the Sheet's **Testing
+Events** tab — verdict, file context, confidence, and your 👍/👎 (with an optional
+one-line reason on a 👎). No GitHub round-trip, no separate harvest.
+
+```bash
+test-classifier --pr 42 --submit                 # classify (INFERRED) → post → ask → record
+AI_RUN_SUITE=1 test-classifier --pr 42 --submit  # OBSERVED → post → ask → record
+test-classifier --submit                         # auto-discovers the current branch's PR
+```
+
+**Requirements:** everything `--post-comment` needs (open PR + `gh` authed),
+**plus** the metricsai webhook creds — two static values, set once in `~/.zshrc`:
+
+```bash
+export METRICSAI_WEBHOOK_URL="https://script.google.com/macros/s/<id>/exec"
+export METRICSAI_WEBHOOK_KEY="<the AI Metrics API key>"
+```
+
+That's the whole setup. `--submit` POSTs the row to the same Google Apps Script
+webhook `metricsai` uses (flat JSON body; the script aligns fields to the sheet
+by header name, so column order never matters). **No gcloud, no service account,
+no token to refresh** — both values are permanent.
+
+The row lands in the **Testing Events** tab by default; override with
+`METRICSAI_WEBHOOK_TAB`.
+
+**Behavior notes:**
+- **Interactive only.** In CI or any non-TTY run, `--submit` posts the comment
+  and **skips** the prompt + row (no human to ask, no hang). CI metrics still
+  come from the central weekly harvest.
+- **No creds → no crash.** If `METRICSAI_WEBHOOK_URL` / `METRICSAI_WEBHOOK_KEY`
+  aren't set, it records your answer to the terminal, warns, and **still posts**
+  the comment.
+- **Writes to Testing Events, not the weekly tabs.** These are per-event rows
+  (one per run), distinct from the `metricsai` weekly aggregate rows in the
+  CXT / DMOD / EMMY / OSRE tabs. The central sweep writes to the same tab — two
+  writers, one tab, deduped by `comment_id`.
+- **Pressing enter skips** the row entirely — no verdict is guessed.
 
 **Scope details.**