@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/hooks/lib/Measure-PowerShellComplexity.ps1

@@ -0,0 +1,186 @@
+<#
+.SYNOPSIS
+    Measure cyclomatic complexity of PowerShell functions via the AST.
+
+.DESCRIPTION
+    lizard cannot parse PowerShell, so a PowerShell-primary repository had a
+    permanently unmeasured complexity dimension (#537). The platform, however,
+    CAN answer the question: PowerShell's own AST yields an exact decision-point
+    count per function, which is the same quantity lizard measures for other
+    languages.
+
+    This script is the measurement half; gate-3.sh is the verdict half. Keeping
+    them apart means the gate does not have to know a project's refactor history
+    and the script does not have to know about baselines.
+
+    Output is line-oriented and stable, because gate-3.sh parses it:
+
+        functions_measured=<n>     total functions inspected
+        max_ccn=<n>                highest CCN seen
+        over_threshold=<n>         functions with CCN > -Threshold
+        OVER <file>:<line> <name> ccn=<n>     one per over-threshold function
+        FUNC <file>:<line> <name> ccn=<n>     one per function when -List is set
+
+.PARAMETER Path
+    Files or directories to analyse. Directories are walked for *.ps1/*.psm1.
+
+.PARAMETER Threshold
+    Reporting threshold. Functions above it are emitted as OVER lines. This does
+    NOT filter FUNC lines, which is what makes a ratchet able to compare against
+    a baseline collected at a different threshold -- see #598.
+
+.PARAMETER List
+    Emit a FUNC line for every function, not just the ones over the threshold.
+    A ratchet needs the full population: comparing only OVER lines against a
+    baseline that also stores only over-threshold entries is how a brand-new
+    well-factored function (CCN 2-4) got reported as a "regression".
+
+.PARAMETER Strict
+    Treat a parse failure as a hard error (exit 3) instead of skipping the file.
+
+.EXAMPLE
+    ./Measure-PowerShellComplexity.ps1 -Path ./src -Threshold 5
+
+.EXAMPLE
+    ./Measure-PowerShellComplexity.ps1 -Path ./src -Threshold 5 -List
+
+.NOTES
+    Exit codes:
+      0  measured (findings are reported, not signalled by exit code)
+      2  no analyzable files
+      3  parse/tooling failure (fail closed)
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $false)]
+    [string[]] $Path = @('.'),
+
+    [Parameter(Mandatory = $false)]
+    [ValidateRange(1, 1000)]
+    [int] $Threshold = 5,
+
+    [Parameter(Mandatory = $false)]
+    [switch] $List,
+
+    [Parameter(Mandatory = $false)]
+    [switch] $Strict
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# --- Collect files -----------------------------------------------------------
+
+$files = New-Object System.Collections.Generic.List[string]
+$missing = 0
+
+foreach ($p in $Path) {
+    if (-not (Test-Path -LiteralPath $p)) { $missing++; continue }
+    $item = Get-Item -LiteralPath $p
+    if ($item.PSIsContainer) {
+        Get-ChildItem -LiteralPath $item.FullName -Recurse -File -Include '*.ps1', '*.psm1' |
+            ForEach-Object { $files.Add($_.FullName) }
+    }
+    elseif ($item.Extension -in @('.ps1', '.psm1')) {
+        $files.Add($item.FullName)
+    }
+}
+
+if ($files.Count -eq 0) {
+    if ($Strict -and $missing -gt 0) {
+        [Console]::Error.WriteLine("ERR no analyzable PowerShell files ($missing path(s) did not exist)")
+        exit 3
+    }
+    Write-Output 'functions_measured=0'
+    Write-Output 'max_ccn=0'
+    Write-Output 'over_threshold=0'
+    exit 2
+}
+
+# --- Count decision points ---------------------------------------------------
+#
+# CCN = 1 + number of decision points, which is the definition lizard uses.
+# Decision points in PowerShell: if / elseif, the loop keywords, catch, the
+# ternary and null-coalescing operators, and each -and/-or in a condition.
+# Declaring a function is not itself a decision, so every function starts at 1.
+
+function Get-DecisionCount {
+    param([System.Management.Automation.Language.Ast] $AstBody)
+
+    $count = 0
+
+    $count += @($AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.IfStatementAst] }, $true)).Count
+    $count += @($AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.LoopStatementAst] }, $true)).Count
+    $count += @($AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.TrapStatementAst] }, $true)).Count
+    $count += @($AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.TernaryExpressionAst] }, $true)).Count
+
+    # Binary expressions whose operator short-circuits count as decisions, which
+    # is what makes `if ($a -and $b -or $c)` score higher than `if ($a)`.
+    foreach ($bin in $AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.BinaryExpressionAst] }, $true)) {
+        $op = $null
+        try { $op = $bin.Operator } catch { continue }
+        if ($op -eq 'And' -or $op -eq 'Or') { $count++ }
+    }
+
+    # catch blocks: FindAll over class-based ASTs is not available for them, so
+    # walk TryStatementAst nodes and count their CatchClauses.
+    foreach ($try in $AstBody.FindAll({ param($n) $n -is [System.Management.Automation.Language.TryStatementAst] }, $true)) {
+        $count += @($try.CatchClauses).Count
+    }
+
+    return $count
+}
+
+$measured = 0
+$maxCcn = 0
+$over = 0
+$parseErrors = New-Object System.Collections.Generic.List[string]
+
+foreach ($file in $files) {
+    $tokens = $null
+    $errors = $null
+    $ast = $null
+    try {
+        $ast = [System.Management.Automation.Language.Parser]::ParseFile($file, [ref]$tokens, [ref]$errors)
+    }
+    catch {
+        $parseErrors.Add("$file : $($_.Exception.Message)")
+        continue
+    }
+
+    if ($errors -and $errors.Count -gt 0) {
+        $first = ($errors | Select-Object -First 1)
+        $parseErrors.Add("$file : $($first.Message)")
+        continue
+    }
+
+    $funcs = $ast.FindAll({ param($n) $n -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
+    foreach ($f in $funcs) {
+        $ccn = 1 + (Get-DecisionCount -AstBody $f.Body)
+        $measured++
+        if ($ccn -gt $maxCcn) { $maxCcn = $ccn }
+
+        if ($ccn -gt $Threshold) { $over++ }
+
+        if ($List -or $ccn -gt $Threshold) {
+            $line = $f.Extent.StartLineNumber
+            $kind = if ($ccn -gt $Threshold) { 'OVER' } elseif ($List) { 'FUNC' } else { $null }
+            if ($kind) {
+                Write-Output ('{0} {1}:{2} {3} ccn={4}' -f $kind, $file, $line, $f.Name, $ccn)
+            }
+        }
+    }
+}
+
+if ($parseErrors.Count -gt 0 -and $Strict) {
+    foreach ($pe in $parseErrors) { [Console]::Error.WriteLine("ERR parse: $pe") }
+    exit 3
+}
+elseif ($parseErrors.Count -gt 0) {
+    foreach ($pe in $parseErrors) { [Console]::Error.WriteLine("WARN parse skipped: $pe") }
+}
+
+Write-Output "functions_measured=$measured"
+Write-Output "max_ccn=$maxCcn"
+Write-Output "over_threshold=$over"
+exit 0

package/hooks/lib/coverage-total.sh

@@ -81,12 +81,27 @@ enforce_python_coverage() {
         echo "    Run the full suite for a real Python coverage check."
         return 0
       fi
-      echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below 80% threshold"
+      echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below ${COVERAGE_THRESHOLD:-80}% threshold"
       return 1
     fi
-    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ 80%)"
-  else
-    echo "⚠️  Could not determine Python coverage percentage. Ensure pytest-cov or coverage.py data exists."
+    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ ${COVERAGE_THRESHOLD:-80}%)"
+    return 0
+  fi
+
+  # #570: reaching here means the gate produced NO measurement. That is a FAILED
+  # answer to "is coverage at or above the floor?", not a lenient one — the gate
+  # exists to answer that question and answered nothing. Warning and returning 0
+  # made the gate fail-open: deleting .coverage (or a pytest run that died before
+  # writing it) disabled the coverage check while the summary still looked clean.
+  #
+  # The one legitimate exception is a subset run: nothing was measured because
+  # only part of the suite was run, so there is no total to compare.
+  if [ "${PARTIAL_TEST_RUN:-false}" = "true" ]; then
+    echo "⚠️  Could not determine Python coverage percentage (subset test run) — not blocking."
+    return 0
   fi
-  return 0
+  echo "❌ BLOCKED - Could not determine Python coverage percentage."
+  echo "   No .coverage / coverage report was produced, so the ${COVERAGE_THRESHOLD:-80}% floor"
+  echo "   cannot be verified. Run the suite with coverage (pytest --cov) and commit again."
+  return 1
 }

package/hooks/lib/gate-5c-alignment.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# Gate 5c: spec/test alignment (#585).
+#
+# Extracted from pre-commit so the contract is unit-testable without executing the
+# hook, the same way lib/coverage-total.sh and lib/sprint-gate-report.sh are.
+#
+# The defect this file exists for: the whole check sat inside
+#     if [ -f "$REQ_IDS_FILE" ] && command -v jq >/dev/null 2>&1; then
+# so in the normal state — req-ids.json is produced by `xp-gate check-alignment`
+# into .sprint-state/, which is gitignored and therefore absent in every fresh
+# clone — the gate printed NOTHING. Not PASS, not FAIL, not SKIP. The quality
+# report had no slot for it either. A repository's semantic alignment had never
+# been checked once and every report was green.
+#
+# A gate that answers "not checked" by staying silent is the same defect class as
+# #449, #499, #570, #575 and #594: silence read as success.
+
+# Test-file conventions, per language. A gate that only knows JS/TS reports
+# "0 annotated, 0 uncovered" on a PowerShell, Python, Go, Java or Kotlin
+# repository — a vacuous green (#585).
+#
+# Pester:  *.Tests.ps1, *.test.ps1 (Pester's documented naming)
+# pytest:  test_*.py, *_test.py
+# Go:      *_test.go
+# Java:    *Test.java, *Tests.java
+# Kotlin:  *Test.kt, *Tests.kt
+# JS/TS:   *.test.*, *.spec.*
+GATE5C_TEST_FILE_PATTERN='(\.(test|spec)\.(ts|tsx|js|jsx|cjs|mjs)$)|(\.([Tt]ests?)\.ps1$)|(^(test_|.*/test_)[^/]*\.py$)|(^([^/]*_test)\.py$)|(_test\.go$)|([Tt]ests?\.java$)|([Tt]ests?\.kt$)'
+
+# Is this changed-file list carrying anything that looks like a test file?
+#
+# Uses the same CHANGED_FILES variable the hook holds at that point in its flow.
+gate_5c_test_files() {
+  printf '%s\n' "${CHANGED_FILES:-}" \
+    | grep -E "$GATE5C_TEST_FILE_PATTERN" 2>/dev/null || true
+}
+
+# One-line-per-id extraction. Reads req-ids.json when jq is available and falls
+# back to grep when it is not: `jq` missing used to disable the gate silently, and
+# a JSON array of strings is simple enough to read without it.
+gate_5c_req_ids() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+  if command -v jq >/dev/null 2>&1; then
+    jq -r '.[]' "$file" 2>/dev/null && return 0
+  fi
+  # Fallback: quoted strings inside the array. Good enough for a flat id list, and
+  # it fails toward EMPTY rather than toward a bogus id.
+  grep -oE '"[^"]+"' "$file" 2>/dev/null | tr -d '"' || true
+}
+
+# The @test REQ-XXX annotations inside one file.
+gate_5c_annotations() {
+  local file="$1"
+  grep -oE '@test[[:space:]]+REQ-[A-Za-z0-9-]+' "$file" 2>/dev/null \
+    | sed 's/@test[[:space:]]*//' | sort -u || true
+}
+
+# Gate 5c entry point. Echoes the verdict; returns 1 to BLOCK.
+#
+# Reads CHANGED_FILES (set by pre-commit). Writes GATE_5C_STATUS for the report:
+# PASS, SKIP or BLOCK — never empty, because "empty" is what was broken.
+gate_5c_alignment() {
+  local req_ids_file=".sprint-state/phase-outputs/req-ids.json"
+  GATE_5C_STATUS=""
+
+  if [ ! -f "$req_ids_file" ]; then
+    # The normal state of a fresh clone: .sprint-state/ is a process artifact and
+    # gitignored. Say so, out loud, with the command that would fix it.
+    echo "  ⏭️  Gate 5c: spec/test alignment NOT CHECKED — $req_ids_file missing"
+    echo "     Run 'xp-gate check-alignment' to generate it and enable this gate."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  # Staleness: a req-ids.json older than the spec it claims to describe would let a
+  # deleted REQ keep its annotations looking valid.
+  if [ -f "specification.yaml" ] && [ "$req_ids_file" -ot "specification.yaml" ]; then
+    echo "  ⏭️  Gate 5c: spec/test alignment NOT CHECKED — req-ids.json is stale"
+    echo "     specification.yaml is newer. Run 'xp-gate check-alignment' to regenerate."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  local test_files
+  test_files=$(gate_5c_test_files)
+  if [ -z "$test_files" ]; then
+    # Reported rather than silent: without this line the operator cannot tell
+    # "nothing to check" from "the gate is broken" (#585).
+    echo "  ℹ️  Gate 5c: no test files among the staged changes — nothing to align."
+    GATE_5C_STATUS="SKIP"
+    return 0
+  fi
+
+  echo "  → Checking @test REQ-XXX annotations..."
+  local annotation_errors=0 tf req_id found
+  while read -r tf; do
+    [ -n "$tf" ] || continue
+    [ -f "$tf" ] || continue
+    while read -r req_id; do
+      [ -n "$req_id" ] || continue
+      found=$(gate_5c_req_ids "$req_ids_file" | grep -qxF "$req_id" && echo yes || true)
+      if [ -z "$found" ]; then
+        echo "❌ Gate 5c: $tf — @test $req_id: REQ ID not found in specification.yaml"
+        annotation_errors=$((annotation_errors + 1))
+      fi
+    done < <(gate_5c_annotations "$tf")
+  done < <(printf '%s\n' "$test_files")
+
+  if [ "$annotation_errors" -gt 0 ]; then
+    echo ""
+    echo "❌ $annotation_errors test annotation(s) reference non-existent REQ IDs — commit BLOCKED"
+    echo "   Fix: verify the REQ IDs against specification.yaml, or run 'xp-gate check-alignment'"
+    GATE_5C_STATUS="BLOCK"
+    return 1
+  fi
+
+  # Reverse check: REQs with no annotated test among the staged changes. Visible,
+  # non-blocking — a single commit rarely touches every requirement's test.
+  local all_reqs annotated_all="" untested=0 spec_req
+  all_reqs=$(gate_5c_req_ids "$req_ids_file")
+  while read -r tf; do
+    [ -n "$tf" ] || continue
+    [ -f "$tf" ] || continue
+    annotated_all="$annotated_all $(gate_5c_annotations "$tf")"
+  done < <(printf '%s\n' "$test_files")
+
+  while read -r spec_req; do
+    [ -n "$spec_req" ] || continue
+    if ! printf '%s\n' "$annotated_all" | tr ' ' '\n' | grep -qxF "$spec_req"; then
+      untested=$((untested + 1))
+    fi
+  done < <(printf '%s\n' "$all_reqs")
+
+  if [ "$untested" -gt 0 ]; then
+    echo "  ⚠️  [FAIL] Gate 5c: $untested REQ(s) in specification.yaml have no annotated tests"
+    echo "     This is non-blocking. Run 'xp-gate check-alignment' for the full report."
+  fi
+
+  echo "  ✅ @test annotation check complete."
+  GATE_5C_STATUS="PASS"
+  return 0
+}

package/hooks/lib/jscpd-run.sh

@@ -1,12 +1,51 @@
 #!/usr/bin/env bash
 # ============================================================================
-# Gate 2 duplicate-code helpers (issue #477)
+# Gate 2 duplicate-code helpers (issue #477, #591)
 #
 # Extracted from pre-commit so the outcome contract is unit-testable without
 # executing the hook, and so an installed hook can source it the same way it
 # sources the other libraries in this directory.
 # ============================================================================
 
+# The default ignore set: what Gate 2 must NOT treat as refactorable source when
+# the project expresses no preference (#591).
+#
+# jscpd's own defaults treat .yaml, .txt and .log as scannable formats. On a
+# data-heavy project that reports an exemptions manifest, a golden snapshot and
+# two build logs as "duplicate code" — measured as 48.72% duplication on a
+# fixture that contained no source at all. The number is worse than noise: a
+# reader cannot tell "yaml rows that must repeat" from "two methods that were
+# really copy-pasted", so the honest response is to stop reading Gate 2 and take
+# the real duplicates down with it. The reporter's own tally: 176 clones
+# reported, 6 refactorable.
+#
+# Deliberately NARROW. Every entry is a file class whose duplication is its data
+# shape or its artifact nature, never a refactoring target. Real source
+# extensions are untouched — pinned by a control case, because an ignore set that
+# also swallowed .ts/.java/.py would report a permanent clean and look healthier
+# than before the fix.
+JSCPD_DEFAULT_IGNORE_PATTERNS='(^|/)(node_modules|dist|build|target|coverage|out|\.next|\.nuxt|vendor)/|\.log$|\.txt$|\.(ya?ml)$|golden|baseline\.json$|evidence'
+
+# Human-readable form, printed by the gate so the baseline is auditable (#591
+# point 3). Silence about the default is the same defect as silence about a
+# skipped gate: the user cannot answer "what did it scan".
+jscpd_default_ignore_patterns() {
+  printf '%s\n' "jscpd default ignore (no jscpd.conf.json): build output (node_modules, dist, build, target, coverage, out, vendor), *.log, *.txt, *.yaml/*.yml, *golden*, *baseline.json, *evidence*"
+}
+
+# Is this path covered by the default ignore set? Exit 0 = ignore it.
+#
+# XP_GATE_JSCPD_DEFAULT_IGNORE=0 disables the set entirely: a project that
+# genuinely wants YAML compared must be able to say so, or the default would make
+# some real duplicates unreachable.
+jscpd_is_default_ignored() {
+  local _path="$1"
+  if [ "${XP_GATE_JSCPD_DEFAULT_IGNORE:-1}" = "0" ]; then
+    return 1
+  fi
+  printf '%s\n' "$_path" | grep -qE "$JSCPD_DEFAULT_IGNORE_PATTERNS"
+}
+
 # Echo the jscpd config the gate should pass, or nothing when the project has
 # none.
 #

package/hooks/lib/native-path.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Convert a POSIX path into the form a NATIVE Windows binary can open.
+#
+# #581 / #582: on WSL and in Git-Bash, `node.exe` and `gitleaks.exe` cannot open
+# `/mnt/d/projects/repo/...` or `/d/projects/repo/...`. They resolve a leading `/` to
+# `<current drive>:\`, so the path silently becomes `D:\mnt\d\projects\...` and the
+# module is "not found". The failure then gets reported as a verdict about the USER'S
+# repository:
+#
+#   Gate 9  ❌ BLOCKED - Build integrity check failed
+#           Fix type errors, broken imports, or package manifest issues
+#
+#   Gate 8  ❌ BLOCKED - Secrets detected in staged files
+#
+# Both are wrong, and both are expensive to debug: the message points at the code,
+# the cause is the shell. #582 fixed the Gate 8 instance inline; this library exists so
+# the next caller does not have to re-derive it, and so there is ONE place that knows
+# the converters — not one per gate that happened to notice.
+#
+# Relative paths are deliberately NOT converted. node resolves `scripts/x.cjs` against
+# its own cwd, which it translated correctly; converting would be pointless work and a
+# chance to get it wrong.
+
+# Does this host need POSIX -> native conversion at all?
+#
+# True when a native binary is on the far side of the shell: WSL, or MSYS/Git-Bash on
+# Windows. On a plain Linux/macOS host neither converter exists and no conversion is
+# ever wanted.
+#
+# @returns 0 when conversion applies
+native_path_applies() {
+  [ -n "${WSL_DISTRO_NAME:-}" ] && return 0
+  [ -n "${MSYSTEM:-}" ] && return 0
+  # Fallback: a converter being present IS the signal, and covers hosts that set
+  # neither marker (some CI images strip MSYSTEM).
+  command -v wslpath >/dev/null 2>&1 && return 0
+  command -v cygpath >/dev/null 2>&1 && return 0
+  return 1
+}
+
+# Convert a path to native Windows form, or echo it unchanged when that is not possible.
+#
+# Order matters. `wslpath` is WSL's converter; `cygpath` is MSYS/Git-Bash's. Asking each
+# only on its own host avoids the case where both exist and the wrong one "succeeds"
+# with a path the other binary cannot use.
+#
+# Never fails the caller: a path that cannot be converted is returned as-is, because a
+# gate that aborts here would break on hosts that need no conversion at all. Callers that
+# must know whether conversion happened should compare the input and output.
+#
+# @param {string} path path to convert
+# @returns {string} native form, or the input unchanged
+to_native_path() {
+  local _p="${1:-}"
+  [ -n "$_p" ] || return 0
+  # Only absolute paths are candidates. A relative path is resolved by the child
+  # process against a cwd it handles correctly.
+  case "$_p" in
+    /*) ;;
+    *) printf '%s' "$_p"; return 0 ;;
+  esac
+
+  local _converted=""
+  if [ -n "${WSL_DISTRO_NAME:-}" ] && command -v wslpath >/dev/null 2>&1; then
+    _converted=$(wslpath -w "$_p" 2>/dev/null || true)
+  elif command -v cygpath >/dev/null 2>&1; then
+    _converted=$(cygpath -w "$_p" 2>/dev/null || true)
+  elif command -v wslpath >/dev/null 2>&1; then
+    # wslpath without WSL_DISTRO_NAME: still the better guess than nothing.
+    _converted=$(wslpath -w "$_p" 2>/dev/null || true)
+  fi
+
+  if [ -n "$_converted" ]; then
+    printf '%s' "$_converted"
+  else
+    printf '%s' "$_p"
+  fi
+}
+
+# Convert a path only when conversion is needed, and say so when it cannot be done.
+#
+# The stricter sibling: use this where a wrong path produces a MISLEADING verdict rather
+# than a clean failure (Gate 9's "build integrity check failed", Gate 8's "secrets
+# detected"). It prints a warning to stderr when the path is absolute, the host needs
+# conversion, and nothing was converted — the case that silently becomes a false verdict.
+#
+# @param {string} path path to convert
+# @param {string} what human name for the path, used in the warning
+# @returns {string} converted path, or the input unchanged
+to_native_path_or_warn() {
+  local _p="${1:-}"
+  local _what="${2:-path}"
+  local _out
+  _out=$(to_native_path "$_p")
+  if [ "$_out" = "$_p" ]; then
+    case "$_p" in
+      /*)
+        if native_path_applies; then
+          echo "  ⚠️  could not convert $_what to native form: $_p" >&2
+          echo "      a native binary may fail to open it; the failure will look like a code defect" >&2
+        fi
+        ;;
+    esac
+  fi
+  printf '%s' "$_out"
+}

package/hooks/lib/prepush-score.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Score a pre-push gate list, or refuse to.
+
+`overall.score` is the most quotable number in a pre-push report, so it has to
+generalise over the gates it claims to summarise (#580, #577).
+
+Two shapes must produce no number at all:
+
+    no gate ran            ->  0.0/10 would claim "everything broke"
+    some gate ran, but the  -> 10.0/10 off a single passing gate would claim
+    rest never did             "everything is green"
+
+The honest answer in both cases is None — "not measured" — because either way the
+number would be a claim the run cannot support. A score is emitted only when the
+gates that ran are a MAJORITY of the gates that exist, and it always travels with
+`score_scope` naming what it covers, so no reader can quote it as global quality.
+
+Usage:
+    prepush-score.py --status PASS --status SKIP ...      # one per gate
+    prepush-score.py --report path/to/report.json        # patch in place
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+
+# Statuses grouped by what they say about the run. Kept as data rather than as
+# branches so adding a status is a one-line change and cannot silently fall
+# through to "failed" (which is exactly what DEGRADED used to do, #574).
+FAILED_STATUSES = ("FAIL", "BLOCK")
+# A degradation is a gate that ran but could not fully do its job, so it counts
+# with the warnings: a degraded gate must never be judged a hard failure.
+DEGRADED_STATUSES = ("DEGRADED", "WARN")
+
+
+def _group_by_disposition(gates: Sequence[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
+    """Split the gate list into ran / passed / failed / warned / degraded / skipped."""
+    def with_status(statuses: Sequence[str]) -> List[Dict[str, Any]]:
+        return [g for g in gates if g.get("status") in statuses]
+
+    ran = [g for g in gates if g.get("status") != "SKIP"]
+    return {
+        "ran": ran,
+        "passed": with_status(("PASS",)),
+        "failed": with_status(FAILED_STATUSES),
+        "warned": with_status(("WARN",)),
+        "degraded": with_status(DEGRADED_STATUSES),
+        "skipped": with_status(("SKIP",)),
+    }
+
+
+def _score_for(ran: Sequence[Dict[str, Any]], passed_count: int, total: int) -> Tuple[Optional[str], str]:
+    """The score and the scope it covers, or (None, reason) when it cannot apply.
+
+    A score speaks for the gates that ran, so it is only emitted when those can
+    summarise the report. Two shapes cannot:
+
+        nothing ran            -> 0.0/10 would claim "everything broke"
+        fewer than half ran    -> 10.0/10 off one passing gate would claim
+                                  "everything is green"
+
+    Six of twelve is a tie, not an endorsement, hence `* 2 <=`.
+    """
+    if not ran:
+        return None, "not measured"
+    if len(ran) * 2 <= total:
+        return None, "%d of %d gates is too few to summarise" % (len(ran), total)
+    return "%.1f/10" % (10.0 * passed_count / len(ran)), "%d of %d gates" % (len(ran), total)
+
+
+def compute(gates: Sequence[Dict[str, Any]]) -> Dict[str, Any]:
+    """Return the score fields for a gate list.
+
+    Keys: score (str | None), score_scope (str), gates_run, gates_skipped,
+    gates_total, gates_passed, gates_failed, gates_warned, gates_degraded,
+    failed_gates, skipped_gates. The rule lives here and nowhere else.
+
+    `gates_total` and `gates_passed` are counted from the list rather than taken
+    from the caller: they used to be a hardcoded 8 and a 1/0 squashed out of the
+    verdict, so a report could claim eight gates while listing twelve (#569).
+    """
+    total = len(gates)
+    groups = _group_by_disposition(gates)
+    score, scope = _score_for(groups["ran"], len(groups["passed"]), total)
+
+    return {
+        "score": score,
+        "score_scope": scope,
+        "gates_run": len(groups["ran"]),
+        "gates_skipped": len(groups["skipped"]),
+        "gates_total": total,
+        "gates_passed": len(groups["passed"]),
+        "gates_failed": len(groups["failed"]),
+        "gates_warned": len(groups["warned"]),
+        "gates_degraded": len(groups["degraded"]),
+        "failed_gates": [g.get("id") for g in groups["failed"]],
+        "skipped_gates": [g.get("id") for g in groups["skipped"]],
+    }
+
+
+def apply_to_report(report: Dict[str, Any]) -> Dict[str, Any]:
+    """Patch the score fields into a report's `overall` section, in place."""
+    overall = report.setdefault("overall", {})
+    overall.update(compute(report.get("gates", [])))
+    return report
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Score a pre-push gate list.")
+    parser.add_argument(
+        "--status",
+        action="append",
+        default=[],
+        metavar="STATUS",
+        help="status of one gate (repeatable, in gate order)",
+    )
+    parser.add_argument(
+        "--report",
+        metavar="PATH",
+        help="patch the score fields into this report JSON in place",
+    )
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.report:
+        path = Path(args.report)
+        report = json.loads(path.read_text(encoding="utf-8"))
+        apply_to_report(report)
+        path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+        return 0
+
+    if not args.status:
+        parser.error("either --report or at least one --status is required")
+
+    print(json.dumps(compute([{"status": s} for s in args.status])))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())