automated-qa 0.11.0

package/schemas/verify-read-only.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/verify-read-only.schema.json",
+  "title": "verify.read-only.json",
+  "description": "The repository's declaration that specific POST paths read rather than write, so the forced-state pass may substitute a response for them. Committed, explicit, and exhaustive: every entry is one literal path, never a pattern -- a wildcard could sweep a real write into a lane that replays it. A declared path is added to a cell's apiTargets for the forced-state pass ONLY; nothing else in qa replays it, and no other method is declarable. See lib/qa/forced-states.mjs loadReadOnlyPosts() and AGENTS.md, section Run inputs, writes, and coverage.",
+  "type": "object",
+  "required": ["schema_version", "read_only_posts"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "read_only_posts": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 128,
+      "items": {
+        "type": "object",
+        "required": ["path", "why"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "description": "One literal, absolute request path. No wildcard, query string, or fragment: a pattern is not a declaration.",
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 512,
+            "pattern": "^/[^*?#]{1,511}$"
+          },
+          "why": {
+            "description": "Why this POST changes nothing. Written for the reviewer who has to believe it, not for the parser.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          }
+        }
+      }
+    }
+  }
+}

package/templates/github-workflow.yml

@@ -0,0 +1,80 @@
+name: frontend-verify
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  AUTOMATED_QA_REPO: https://github.com/ArkashJ/Automated_QA
+  AUTOMATED_QA_REF: main
+
+jobs:
+  static:
+    name: frontend-verify / static gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Clone frontend-verify
+        run: git clone --depth 1 --branch "$AUTOMATED_QA_REF" "$AUTOMATED_QA_REPO" "$RUNNER_TEMP/automated-qa"
+
+      - name: Static gate
+        run: node "$RUNNER_TEMP/automated-qa/bin/qa.mjs" verify "$GITHUB_WORKSPACE"
+
+  # This job always starts (GitHub Actions cannot read `secrets` directly in a
+  # job-level `if:`), but every step below is gated on FRONTEND_VERIFY_BASE
+  # being set, so it is a no-op until that secret exists.
+  runtime:
+    name: frontend-verify / runtime gate
+    runs-on: ubuntu-latest
+    env:
+      FRONTEND_VERIFY_BASE: ${{ secrets.FRONTEND_VERIFY_BASE }}
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: Checkout
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Clone frontend-verify
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        run: git clone --depth 1 --branch "$AUTOMATED_QA_REF" "$AUTOMATED_QA_REPO" "$RUNNER_TEMP/automated-qa"
+
+      - name: Install Chromium for Playwright
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        run: npx playwright install chromium
+
+      - name: Runtime gate
+        id: gate
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        continue-on-error: true
+        run: node "$RUNNER_TEMP/automated-qa/bin/qa.mjs" verify "$GITHUB_WORKSPACE" --base "$FRONTEND_VERIFY_BASE" --prod
+
+      - name: Generate SARIF
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        run: node "$RUNNER_TEMP/automated-qa/bin/qa.mjs" show ci "$GITHUB_WORKSPACE" --format sarif --out "$RUNNER_TEMP/frontend-verify.sarif"
+
+      - name: Upload SARIF
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' }}
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ${{ runner.temp }}/frontend-verify.sarif
+
+      - name: Fail if the runtime gate found findings
+        if: ${{ env.FRONTEND_VERIFY_BASE != '' && steps.gate.outcome == 'failure' }}
+        run: exit 1

package/templates/pre-commit.sample

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# frontend-verify pre-commit gate.
+#
+# Copy this to .git/hooks/pre-commit (or wherever your hook manager reads
+# samples from, e.g. .husky/pre-commit) and make it executable:
+#   cp .verify-hooks/pre-commit.sample .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# Static only (fast; runs on every commit). Run it bare — its own exit status
+# is the gate: 0 clean, 1 findings, 2 could not run. Do not append anything
+# after `||` that does not end in `exit 1`, or a failure reads as green.
+set -euo pipefail
+
+AUTOMATED_QA="${FRONTEND_VERIFY_SKILL_ROOT:-$HOME/.claude/skills/frontend-verify}"
+REPO="$(git rev-parse --show-toplevel)"
+
+if [ ! -d "$AUTOMATED_QA" ]; then
+  echo "frontend-verify: $AUTOMATED_QA not found (set FRONTEND_VERIFY_SKILL_ROOT); skipping" >&2
+  exit 0
+fi
+
+bash "$AUTOMATED_QA/verify.sh" "$REPO"

package/verify.sh

@@ -0,0 +1,385 @@
+#!/usr/bin/env bash
+# One command. Inventory -> classify -> sweep, in that order, cheapest first.
+#
+#   verify.sh <repoRoot> [--base URL] [--lane LANE] [--width N] [--quiet]
+#                        [--mutate] [--ratchet] [--resume] [--prod] [--no-warm]
+#                        [--widths 390,1440] [--states [empty,error,...]]
+#                        [--exercise [budget]] [--no-journeys]
+#                        [--capture [--capture-full] [--capture-dir DIR]]
+#
+#   --lane     one of source/public-runtime/mock-contract/real-integration/
+#              mfa-integration; defaults to public-runtime when --base is
+#              given. The two real lanes provision and verify every declared
+#              persona through the host-harness launcher (verify.auth-
+#              launcher.mjs) and its identity oracle BEFORE measuring anything
+#              -- see ARCHITECTURE.md. --auth/--login/--login-user/--login-pass/--login-path
+#              are removed; there is no credential flag any more.
+#
+#   verify.sh /path/to/repo                          static only, seconds, no install
+#   verify.sh /path/to/repo --base http://localhost:3000   + the runtime sweep
+#
+#   --mutate   DESTRUCTIVE, opt-in: allows an app-owned journey declaring
+#              mutates:true to write. Generic guessed replay is disabled and
+#              fails closed. Dev database only.
+#   --ratchet  fix-loop guard: after the measured source changes, total findings
+#              may never exceed the best run seen (.verify/ratchet.json). Repeated
+#              runtime measurements of identical source may vary without becoming
+#              a fabricated source regression; the best still tightens.
+#   --resume   continue an aborted sweep instead of restarting it; already
+#              measured routes are kept, unmeasured ones are re-visited.
+#   --prod     the base URL is a PRODUCTION build, so timing findings grade
+#              normally. Without it they are P3: against a dev server the number
+#              measured is the compiler's, not the app's.
+#   --no-warm  skip the precompile pass. The warm pass exists because a dev
+#              server compiles a route on first request (measured: 30.5s) and a
+#              mock service worker does not intercept until it controls a page.
+#   --capture  photograph every measured cell and index the images beside what
+#              was measured for that page (.verify/capture/index.html). OFF by
+#              default -- a screenshot of an authenticated app is user data.
+#              --capture-full takes the whole page; --capture-dir relocates it.
+#   --delay MS pause this long before each cell's navigation. Against a shared,
+#              rate-limited target the sweep's OWN request volume can trip the
+#              target's rate limiter -- --parallel already defaults to 1
+#              (serial), so this is the remaining lever to slow the sweep down.
+#
+#   Multiple principals: put <repo>/verify.roles.json beside the repo and each
+#   role sweeps only the routes it OWNS -- ownership and expected identity
+#   only now, never a credential store. See "Roles" in SKILL.md.
+#
+#   Nothing else may build while the sweep runs -- a concurrent web build starves
+#   the dev server and the whole run aborts as "server unreachable".
+#
+# Exit: 0 clean · 1 P0/P1 findings (or ratchet regression) · 2 could not run.
+# That exit code is the definition of done -- it is what a Stop hook, a
+# pre-commit hook or CI reads. Everything else here is reporting.
+set -uo pipefail
+
+SKILL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO=""; BASE=""; WIDTH=""; QUIET=0; MUTATE=0; RATCHET=0; PARALLEL=""; PASSTHRU=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base)  BASE="${2:-}"; shift 2 ;;
+    # Removed: a credential value must never be an argv value. Fail loudly and
+    # name the replacement, not "unknown flag" -- an operator who used this
+    # yesterday needs to hear where it went.
+    --auth|--login|--login-user|--login-pass|--login-path)
+      echo "verify: --${1#--} was removed -- use the host-harness launcher, invoked by persona name (verify.auth-launcher.mjs)" >&2
+      exit 2 ;;
+    --width) WIDTH="${2:-}"; shift 2 ;;
+    --parallel) PARALLEL="${2:-}"; shift 2 ;;
+    --quiet) QUIET=1; shift ;;
+    --mutate) MUTATE=1; shift ;;
+    --ratchet) RATCHET=1; shift ;;
+    # Straight through to sweep.mjs. --resume continues an aborted sweep instead
+    # of restarting it, --prod says the base URL is a production build so timing
+    # findings grade normally, --no-warm skips the precompile pass.
+    --resume|--prod|--no-warm|--no-journeys|--leak-check|--dark) PASSTHRU+=( "$1" ); shift ;;
+    # --capture/--capture-full photograph every measured cell. Opt-in, and they
+    # must reach sweep.mjs: without these arms the flag fell through to the
+    # positional branch below and was dropped in silence, so `qa verify --capture`
+    # measured normally and wrote no pixels while claiming the flag was accepted.
+    --capture|--capture-full) PASSTHRU+=( "$1" ); shift ;;
+    --lane|--launcher|--launcher-timeout|--oracle-path|--capture-dir|--theme-storage-key) PASSTHRU+=( "$1" "${2:-}" ); shift 2 ;;
+    --auth-lease-fd)
+      [ -n "${2:-}" ] || { echo 'verify: --auth-lease-fd needs a value' >&2; exit 2; }
+      PASSTHRU+=( "$1" "$2" ); shift 2 ;;
+    # --exercise [budget]  click every visible, enabled control on a measured
+    #                      cell (default budget 40) and grade whether it does
+    #                      anything. Bare --exercise uses the default budget.
+    --exercise) PASSTHRU+=( "$1" ); case "${2:-}" in ''|--*) ;; *) PASSTHRU+=( "$2" ); shift ;; esac; shift ;;
+    --nav-timeout|--warm-timeout|--settle|--delay) PASSTHRU+=( "$1" "${2:-}" ); shift 2 ;;
+    # --widths 390,1440   the cell matrix: every route at every width. Half the
+    #                     invariants here are width-dependent, so a one-width run
+    #                     grades an app nobody uses at one width.
+    # --states [kinds]    force empty/error/forbidden/malformed/slow on the data
+    #                     each route actually fetches, and grade what it renders.
+    #                     Bare --states runs all five.
+    --widths|--text-floor|--integrity-share) PASSTHRU+=( "$1" "${2:-}" ); shift 2 ;;
+    --states) PASSTHRU+=( "$1" ); case "${2:-}" in ''|--*) ;; *) PASSTHRU+=( "$2" ); shift ;; esac; shift ;;
+    -h|--help) sed -n '2,40p' "$0"; exit 0 ;;
+    *) [ -z "$REPO" ] && REPO="$1" || true; shift ;;
+  esac
+done
+
+[ -z "$REPO" ] && REPO="$PWD"
+REPO="$(cd "$REPO" 2>/dev/null && pwd)" || { echo "verify: no such directory" >&2; exit 2; }
+command -v node >/dev/null || { echo "verify: node not found" >&2; exit 2; }
+
+OUT="$REPO/.verify"
+mkdir -p "$OUT"
+say() { [ "$QUIET" -eq 1 ] || printf '%s\n' "$*"; }
+rc=0
+
+# The JSON declarations are trust-boundary inputs. Use the same loaders and
+# schema validator as `qa verify --preflight` before inventory starts, so a bad
+# roles/CRUD file cannot spend a scan or reach the runtime sweep. This checks
+# no journey module: app-owned JavaScript is untrusted and only opens when a
+# runtime journey phase actually needs it.
+if ! node --input-type=module -e '
+  import { pathToFileURL } from "node:url";
+  const { checkInputDeclarations } = await import(pathToFileURL(process.argv[2] + "/lib/qa/doctor.mjs"));
+  const failed = checkInputDeclarations(process.argv[1], process.argv[2]).filter((check) => check.level === "fail");
+  for (const check of failed) {
+    console.error(`verify: preflight ${check.id}: ${check.detail}`);
+    if (check.fix) console.error(`verify: preflight fix: ${check.fix}`);
+  }
+  process.exit(failed.length ? 2 : 0);
+' "$REPO" "$SKILL" >"$OUT/preflight.log" 2>&1; then
+  cat "$OUT/preflight.log" >&2
+  echo "verify: preflight failed before inventory" >&2
+  exit 2
+fi
+
+say ""
+say "  frontend-verify  $REPO"
+
+# --- 1. inventory (always; also the route list the sweep uses) --------------
+if ! node "$SKILL/bin/inventory.mjs" "$REPO" >"$OUT/inventory.log" 2>&1; then
+  cat "$OUT/inventory.log" >&2; echo "verify: inventory failed" >&2; exit 2
+fi
+[ "$QUIET" -eq 1 ] || sed -n '2,5p' "$OUT/inventory.log"
+if ! node --input-type=module -e '
+  import fs from "node:fs"; import { pathToFileURL } from "node:url";
+  const { shapes } = await import(pathToFileURL(process.argv[1]));
+  let value; try { value = JSON.parse(fs.readFileSync(process.argv[2], "utf8")); } catch { process.exit(1); }
+  const problem = shapes.inventory(value);
+  if (problem) { console.error("verify: inventory report is invalid: " + problem); process.exit(1); }
+' "$SKILL/lib/qa/reports.mjs" "$OUT/inventory.json"; then
+  echo "verify: inventory did not produce valid evidence" >&2
+  exit 2
+fi
+
+# A sync risk that names the routes it breaks is a real defect, and the only one
+# of the three phases that does not already exit non-zero on its own.
+if [ "$QUIET" -eq 1 ]; then
+  node -e 'try { process.exit(require(process.argv[1]).syncRisks.some((r) => r.severity === "P1") ? 1 : 0) } catch { process.exit(0) }' "$OUT/inventory.json" || rc=1
+else
+  node -e '
+    let p1 = [];
+    try { p1 = require(process.argv[1]).syncRisks.filter((r) => r.severity === "P1") } catch { process.exit(0) }
+    if (!p1.length) process.exit(0);
+    console.log("");
+    console.log("  " + p1.length + " P1 sync risk(s) -- a write with no invalidation, on routes that render it:");
+    for (const r of p1.slice(0, 12)) console.log("    " + r.detail);
+    if (p1.length > 12) console.log("    ... and " + (p1.length - 12) + " more in .verify/inventory.json");
+    process.exit(1);
+  ' "$OUT/inventory.json" || rc=1
+fi
+
+# --- 2. classify (always) ---------------------------------------------------
+# Delete before running, exactly as autonomous-verify.sh quarantines a stale
+# sweep.json. classify.mjs exits 1 for "found findings" AND 1 for an uncaught
+# exception, so a crash was indistinguishable from a clean detection -- and the
+# PREVIOUS run's classify.json stayed on disk, got archived as `produced:
+# classify true`, and its findings were reported as this run's. Stale evidence
+# presented as current is worse than no evidence: it is the one failure mode
+# that survives review, because the report looks entirely normal.
+rm -f "$OUT/classify.json"
+node "$SKILL/bin/classify.mjs" "$REPO" >"$OUT/classify.log" 2>&1
+cls=$?
+[ "$QUIET" -eq 1 ] || sed -n '2,40p' "$OUT/classify.log"
+# No report on disk means the classifier did not complete, whatever it exited
+# with. That is INVALID -- could not run -- never "clean" and never "findings".
+if [ ! -f "$OUT/classify.json" ]; then
+  echo "" >&2
+  echo "  INVALID  classify produced no report (exit $cls)" >&2
+  echo "  The static classifier could not complete, so its defect classes are" >&2
+  echo "  UNMEASURED, not clean. See $OUT/classify.log" >&2
+  exit 2
+fi
+[ "$cls" -ne 0 ] && rc=1
+
+# Optional repo-owned rule packs. The baseline remains dependency-free and
+# unchanged; packs are explicit, versioned modules under .verify/rules/.
+if [ -d "$REPO/.verify/rules" ]; then
+  node "$SKILL/bin/rules.mjs" "$REPO" >"$OUT/rules.log" 2>&1
+  packs=$?
+  [ "$QUIET" -eq 1 ] || cat "$OUT/rules.log"
+  case "$packs" in
+    0) ;;
+    1) rc=1 ;;
+    2) exit 2 ;;
+    *) exit 2 ;;
+  esac
+fi
+
+# --- 3. sweep (only with --base; needs the app running) ---------------------
+if [ -n "$BASE" ]; then
+  args=( --repo "$REPO" --base "$BASE" )
+  [ -n "$WIDTH" ] && args+=( --width "$WIDTH" )
+  [ -n "$PARALLEL" ] && args+=( --parallel "$PARALLEL" )
+  [ "$MUTATE" -eq 1 ] && args+=( --mutate )
+  [ ${#PASSTHRU[@]} -gt 0 ] && args+=( "${PASSTHRU[@]}" )
+  # Keep the previous report available to --resume, but never accept it as
+  # this invocation's evidence if the child exits before publishing a report.
+  sweep_started="$(mktemp "$OUT/.sweep-start.XXXXXX")" || exit 2
+  sweep_before=""
+  if [ -f "$OUT/sweep.json" ]; then
+    sweep_before="$(node -e 'const fs=require("fs"),crypto=require("crypto"); process.stdout.write(crypto.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$OUT/sweep.json")"
+  fi
+  printf 'QA_SWEEP_STARTED\n' >"$OUT/sweep.log"
+  node "$SKILL/bin/sweep.mjs" "${args[@]}" >>"$OUT/sweep.log" 2>&1
+  sw=$?
+  printf '\nQA_SWEEP_RC=%s\n' "$sw" >>"$OUT/sweep.log"
+  fresh=0
+  if [ -f "$OUT/sweep.json" ]; then
+    sweep_after="$(node -e 'const fs=require("fs"),crypto=require("crypto"); process.stdout.write(crypto.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$OUT/sweep.json")"
+    { [ -z "$sweep_before" ] || [ "$sweep_after" != "$sweep_before" ]; } && fresh=1
+  fi
+  [ "$QUIET" -eq 1 ] || sed -n '2,40p' "$OUT/sweep.log"
+  # A crash can exit 1 just like a finding; a wrapper can even exit 0 with
+  # nothing written. Require completed evidence as well as a recognized exit.
+  if { [ "$sw" -ne 0 ] && [ "$sw" -ne 1 ]; } || [ "$fresh" -ne 1 ] || ! node -e '
+    try {
+      const s = require(process.argv[1]), since = Math.floor(require("fs").statSync(process.argv[2]).mtimeMs);
+      const started = Date.parse(s.started), finished = Date.parse(s.finished);
+      const failures = [
+        [s.status === "invalid", "status-invalid"],
+        [s.integrity?.ok !== true, "integrity"],
+        [!Number.isFinite(started) || !Number.isFinite(finished), "timestamps"],
+        [finished + 1000 < since, "stale-finished"],
+        [finished < started, "time-order"],
+        [!Array.isArray(s.routes) || !Array.isArray(s.unreached), "route-arrays"],
+        [!Number.isInteger(s.summary?.routesReached) || !Number.isInteger(s.summary?.routesRequested), "route-counts"],
+        [s.summary?.routesReached <= 0 || s.summary?.routesReached > s.summary?.routesRequested, "route-denominator"],
+      ].filter(([failed]) => failed).map(([, code]) => code);
+      if (failures.length) {
+        console.error("sweep evidence invalid: " + failures.join(","));
+        process.exit(1);
+      }
+    } catch { console.error("sweep evidence invalid: unreadable"); process.exit(1); }
+  ' "$OUT/sweep.json" "$sweep_started"; then
+    rm -f "$sweep_started"
+    echo "verify: INVALID sweep did not produce fresh completed evidence (exit $sw) -- see $OUT/sweep.log" >&2
+    exit 2
+  fi
+  rm -f "$sweep_started"
+  runtime_counts=$(node --input-type=module -e '
+    import fs from "node:fs"; import { pathToFileURL } from "node:url";
+    const { runtimeGateSummary } = await import(pathToFileURL(process.argv[1]));
+    const sweep = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+    const c = runtimeGateSummary(sweep, { repo: process.argv[3] });
+    process.stdout.write([c.raw, c.accepted, c.live, c.gating].join(" "));
+  ' "$SKILL/lib/qa/reports.mjs" "$OUT/sweep.json" "$REPO") || {
+    echo "verify: runtime adjudication failed; findings remain unmeasured" >&2
+    exit 2
+  }
+  read -r runtime_raw runtime_accepted runtime_live runtime_gating <<<"$runtime_counts"
+  if [ "${runtime_accepted:-0}" -gt 0 ]; then
+    say "  runtime findings  $runtime_raw raw  ·  $runtime_accepted adjudicated  ·  $runtime_live active"
+  fi
+  if [ "${runtime_gating:-0}" -gt 0 ] || { [ "$sw" -ne 0 ] && [ "${runtime_accepted:-0}" -eq 0 ]; }; then rc=1; fi
+else
+  say ""
+  say "  runtime sweep skipped (no --base). Static analysis cannot see whether the"
+  say "  code runs -- pass --base http://localhost:3000 with the app up to cover that."
+fi
+
+# PASS must mean "measured, and clean" -- never "measured nothing". A repo with no
+# routes is one the tool did not understand, and reporting it green is the exact
+# failure this whole skill exists to prevent.
+ROUTES=$(node -e 'try { console.log(require(process.argv[1]).counts.routes) } catch { console.log(0) }' "$OUT/inventory.json")
+if [ "${ROUTES:-0}" -eq 0 ]; then
+  echo "" >&2
+  echo "  INCONCLUSIVE  0 routes found in $REPO" >&2
+  echo "  Nothing was measured, so this is not a pass. Either this is not a frontend" >&2
+  echo "  repo, or its router is not one inventory.mjs recognises (Next app/pages," >&2
+  echo "  react-router config, or a src/routes file convention)." >&2
+  exit 2
+fi
+
+# --- ratchet (opt-in): a fix loop that trades one finding for two is going
+# backwards, and an agent mid-loop will not notice on its own. After source changes,
+# total findings (every severity, all phases) may never exceed the best run seen;
+# repeated runtime measurements of the exact same source may vary without being
+# mislabeled as a source regression. The baseline still tightens on every
+# improvement. Static-only and runtime runs measure different things, so a mode
+# switch resets the baseline instead of comparing them.
+if [ "$RATCHET" -eq 1 ]; then
+  ROUT=/dev/stdout; [ "$QUIET" -eq 1 ] && ROUT=/dev/null
+  node --input-type=module -e '
+    import fs from "node:fs"; import { pathToFileURL } from "node:url";
+    const { ratchetUpdate } = await import(pathToFileURL(process.argv[1]));
+    const out = process.argv[2], mode = process.argv[3], repo = process.argv[4];
+    const j = (f) => { try { return JSON.parse(fs.readFileSync(out + "/" + f, "utf8")); } catch { return null; } };
+    const inv = j("inventory.json"), cls = j("classify.json"), sw = mode === "runtime" ? j("sweep.json") : null;
+    // Exit 2 is never a pass, so it can never be a baseline either (#80): the
+    // sweep step above already exits 2 -- before this block runs at all -- on
+    // integrity failure, so this is a second, explicit guard on the same
+    // invariant rather than one this block relies on the shell script above
+    // to enforce silently. A run that did not measure the app must never
+    // tighten (or loosen) what "best" means.
+    if (sw && sw.integrity && sw.integrity.ok === false) {
+      console.error("  ratchet skipped -- this run failed its own integrity gate and can never become the baseline");
+      process.exit(1);
+    }
+    const file = out + "/ratchet.json";
+    const prev = j("ratchet.json");
+    const next = ratchetUpdate({ inventory: inv, classify: cls, sweep: sw, mode, previous: prev, repo });
+    if (next.regression) {
+      console.error("  RATCHET  " + next.total + " active findings, best was " + next.best + " in the same measured scope -- this change went backwards; fix or revert it");
+      process.exit(1);
+    }
+    fs.writeFileSync(file, JSON.stringify(next.state, null, 2));
+    console.log("  ratchet  " + next.total + " active findings (best " + next.best + ", " + next.accepted + " adjudicated, scope " + next.scope.slice(-12) + ")");
+  ' "$SKILL/lib/qa/reports.mjs" "$OUT" "$([ -n "$BASE" ] && echo runtime || echo static)" "$REPO" >"$ROUT" || rc=1
+fi
+
+# PASS must carry the DENOMINATOR. "No P0/P1 findings" over 41 of 51 routes and
+# over 51 of 51 are different claims, and printing them identically is how a
+# partial run gets read as a clean one -- the exact failure this skill exists for.
+# The verdict LEADS with its denominator, and the unmeasured routes are broken
+# out by reason directly beneath it.
+#
+# The line this replaces read "PASS  51 routes analysed, no P0/P1 findings" with
+# the coverage appended after a middot. Two things were wrong with that, and
+# both are the failure this whole tool exists to prevent:
+#   - "51 routes analysed" counted the INVENTORY while the findings covered only
+#     the 41 the sweep attempted, so the headline number and the claim beneath it
+#     had different denominators;
+#   - the coverage rode at the END of the line, after the verdict a reader has
+#     already acted on.
+# SKILL.md states the contract as "no P0/P1 over 41 of 51 routes" -- so that is
+# the literal shape printed here, and every unmeasured route says WHY it was not
+# measured and what would measure it. All numbers come from sweep.json's
+# `summary`, the same single source lib/qa/depth.mjs reads; nothing is
+# recomputed here, so the two can never disagree.
+COVER=""
+UNMEASURED=""
+if [ -n "$BASE" ]; then
+  COVER=$(node -e '
+    try {
+      const s = require(process.argv[1]).summary ?? {};
+      if (s.routesRequested == null) process.exit(0);
+      // The denominator is what the INVENTORY found, not what the sweep chose
+      // to attempt. Printing "41 of 41" for a 51-route app because ten routes
+      // carry a dynamic segment is that same failure, committed by the line
+      // written to prevent it.
+      const denom = s.routesInInventory ?? s.routesRequested;
+      process.stdout.write(" over " + s.routesReached + " of " + denom + " routes");
+    } catch {}
+  ' "$OUT/sweep.json" 2>/dev/null)
+  UNMEASURED=$(node -e '
+    try {
+      const s = require(process.argv[1]).summary ?? {};
+      if (s.routesRequested == null) process.exit(0);
+      const rows = [
+        [s.routesDynamicSkipped ?? 0, "dynamic segment -- promote .verify/journeys.draft.mjs"],
+        [s.routesUnreached ?? 0, "redirected -- landed somewhere else, so this route is a coverage gap"],
+        [s.routesUnowned ?? 0, "unowned -- no role in verify.roles.json claims it"],
+      ].filter(([n]) => n > 0);
+      for (const [n, why] of rows) {
+        process.stdout.write("\n        " + String(n).padStart(3) + " NOT MEASURED  " + why);
+      }
+    } catch {}
+  ' "$OUT/sweep.json" 2>/dev/null)
+else
+  COVER=" over $ROUTES routes, STATICALLY ONLY"
+  UNMEASURED="
+        no runtime invariant was measured -- pass --base URL with the app running"
+fi
+
+say ""
+if [ "$rc" -eq 0 ]; then say "  PASS  no P0/P1 findings$COVER$UNMEASURED"
+else say "  FAIL  P0/P1 findings above$COVER  ·  reports in $OUT/$UNMEASURED"; fi
+exit "$rc"