@intentsolutions/audit-harness 0.1.0 → 1.1.6

package/scripts/gen-layer-applicability.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+audit-harness gen-layer-applicability — project the canonical registry datum into
+the human-readable layer-applicability matrix.
+
+`schemas/audit-profile/registry.v1.json` is THE single source of truth for "which
+gates apply to repo-type X, in which dimension, at what applicability". This
+generator renders `schemas/audit-profile/layer-applicability.md` as a PROJECTION
+of that datum so the doc can never silently drift from the registry the classifier
+actually resolves against (PP-PLAN-040 Phase 0, bead c2b).
+
+Modes:
+  (default)      print the rendered markdown to stdout
+  --write        write it to schemas/audit-profile/layer-applicability.md
+  --check        regenerate in-memory and diff against the committed file;
+                 exit 1 on drift (the CI `layer-applicability-drift` gate)
+
+Stdlib only. Read-only except in --write mode (which only writes the one doc).
+"""
+import argparse
+import difflib
+import hashlib
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REGISTRY = os.path.join(HERE, "..", "schemas", "audit-profile", "registry.v1.json")
+DOC = os.path.join(HERE, "..", "schemas", "audit-profile", "layer-applicability.md")
+
+GLYPH = {"required": "✅", "recommended": "⭕", "conditional": "⚠", "waived": "❌"}
+
+
+def sha256_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return "sha256:" + h.hexdigest()
+
+
+def row(gate):
+    app = gate.get("applicability", "")
+    return "| `{gid}` | {dim} | {glyph} {app} | {enf} | {tool} |".format(
+        gid=gate["gate_id"],
+        dim=gate.get("dimension", ""),
+        glyph=GLYPH.get(app, ""),
+        app=app,
+        enf=gate.get("enforcement", "advisory"),
+        tool=("`" + gate["tool"] + "`") if gate.get("tool") else "—",
+    )
+
+
+def table(gates):
+    out = ["| Gate | Dimension | Applicability | Enforcement | Tool |",
+           "|---|---|---|---|---|"]
+    out += [row(g) for g in sorted(gates, key=lambda g: (g.get("dimension", ""), g["gate_id"]))]
+    return "\n".join(out)
+
+
+def render(registry, registry_hash):
+    lines = []
+    a = lines.append
+    a("# Layer Applicability — GENERATED from `registry.v1.json`")
+    a("")
+    a("> ⚠️ **GENERATED FILE — do not edit by hand.**")
+    a("> Source of truth: [`registry.v1.json`](registry.v1.json) "
+      "(the canonical dimension→gate datum; `classify` resolves against it).")
+    a("> Regenerate: `audit-harness gen-layer-applicability --write` "
+      "(or `python3 scripts/gen-layer-applicability.py --write`).")
+    a("> CI gate `layer-applicability-drift` fails the build if this file drifts from the registry.")
+    a(">")
+    a(f"> registry `{registry_hash}`")
+    a("")
+    a(registry.get("description", "").strip())
+    a("")
+    a("**Legend (applicability):** "
+      + " · ".join(f"{GLYPH[k]} {k}" for k in ("required", "recommended", "conditional", "waived")))
+    a("")
+    a("Every gate defaults to `enforcement: advisory`. Blocking is **earned** — "
+      "engineer-pinned in the target repo's `tests/TESTING.md`, FP-rate-gated "
+      "(see [`gate-promotion.md`](../../docs/gate-promotion.md)).")
+    a("")
+    a("## Base gates (apply to every repo)")
+    a("")
+    a(table(registry.get("base", [])))
+    a("")
+    a("## By classification")
+    a("")
+    a("A repo carries the **UNION** of every classification it matches "
+      "(`classify` never picks a single winner). Gates dedup by `gate_id`, "
+      "keeping the highest applicability.")
+    a("")
+    for kind in sorted(registry.get("classifications", {})):
+        a(f"### `{kind}`")
+        a("")
+        a(table(registry["classifications"][kind]))
+        a("")
+    overlays = registry.get("overlays", {})
+    if overlays:
+        a("## Overlays")
+        a("")
+        for name in sorted(overlays):
+            ov = overlays[name]
+            a(f"### `{name}`")
+            a("")
+            a(ov.get("description", "").strip())
+            promote = ov.get("promote_to_required", [])
+            if promote:
+                a("")
+                a("Promotes to **required**: " + ", ".join(f"`{d}`" for d in promote) + ".")
+            a("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Project registry.v1.json -> layer-applicability.md")
+    ap.add_argument("--write", action="store_true", help="write the doc to its canonical path")
+    ap.add_argument("--check", action="store_true", help="fail (exit 1) if the committed doc drifts")
+    ap.add_argument("--registry", default=REGISTRY)
+    ap.add_argument("--out", default=DOC)
+    args = ap.parse_args()
+
+    registry_path = os.path.abspath(args.registry)
+    with open(registry_path, "r", encoding="utf-8") as f:
+        registry = json.load(f)
+    rendered = render(registry, sha256_file(registry_path))
+
+    if args.check:
+        try:
+            with open(args.out, "r", encoding="utf-8") as f:
+                current = f.read()
+        except FileNotFoundError:
+            print(f"gen-layer-applicability: {args.out} missing — run --write", file=sys.stderr)
+            sys.exit(1)
+        if current != rendered:
+            diff = difflib.unified_diff(
+                current.splitlines(True), rendered.splitlines(True),
+                fromfile="committed", tofile="generated",
+            )
+            sys.stderr.write("".join(diff))
+            sys.stderr.write("\ngen-layer-applicability: DRIFT — regenerate with --write\n")
+            sys.exit(1)
+        print("gen-layer-applicability: layer-applicability.md matches the registry datum")
+        sys.exit(0)
+
+    if args.write:
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(rendered)
+        print(f"gen-layer-applicability: wrote {os.path.relpath(args.out, os.path.join(HERE, '..'))}")
+        sys.exit(0)
+
+    sys.stdout.write(rendered)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/gherkin-lint.sh

@@ -15,11 +15,13 @@ set -euo pipefail
 
 PATH_ARG="features/"
 STRICT=0
+JSON_OUT=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --path) PATH_ARG="$2"; shift 2 ;;
     --strict) STRICT=1; shift ;;
+    --json) JSON_OUT=1; shift ;;
     --help|-h)
       sed -n '2,15p' "$0"; exit 0 ;;
     *) echo "gherkin-lint: unknown flag $1" >&2; exit 2 ;;
@@ -27,15 +29,40 @@ while [[ $# -gt 0 ]]; do
 done
 
 if [[ ! -d "$PATH_ARG" ]]; then
+  if [[ "$JSON_OUT" -eq 1 ]]; then
+    printf '{"gate_id":"audit-harness:%s:gherkin-lint","result":"NOT_APPLICABLE","input_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","policy_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","metadata":{"reason":"path not found","path":"%s"}}\n' \
+      "${AUDIT_HARNESS_SIDE:-ci}" "$PATH_ARG"
+  fi
   echo "gherkin-lint: path not found: $PATH_ARG" >&2
   exit 2
 fi
 
+INPUT_HASH=$(find "$PATH_ARG" -name "*.feature" -type f -exec sha256sum {} \; 2>/dev/null | sort | sha256sum | awk '{print "sha256:"$1}')
+
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  exec 3>&1
+  exec 1>&2
+fi
+
 WARN_COUNT=0
 ERROR_COUNT=0
 
 warn() { echo "WARN  $1:$2 $3"; WARN_COUNT=$((WARN_COUNT + 1)); }
-err()  { echo "ERROR $1:$2 $3"; ERROR_COUNT=$((ERROR_COUNT + 1)); }
+
+# process_awk_output — funnel awk-printed WARN/ERROR lines through the bash
+# counters so the summary + exit code reflect awk-fallback findings (the
+# subprocesses below can't otherwise touch the parent-shell counters).
+# Single-pass awk counts both at once; no-match handled cleanly under
+# set -euo pipefail via the `+0` numeric coercions.
+process_awk_output() {
+  local out="$1"
+  [ -z "$out" ] && return 0
+  local w=0 e=0
+  read -r w e < <(awk '/^WARN /{w++} /^ERROR /{e++} END {print w+0, e+0}' <<< "$out")
+  WARN_COUNT=$((WARN_COUNT + w))
+  ERROR_COUNT=$((ERROR_COUNT + e))
+  printf '%s\n' "$out"
+}
 
 # 1. Prefer official gherkin-lint if available
 if command -v gherkin-lint >/dev/null 2>&1; then
@@ -48,7 +75,7 @@ else
 
   while IFS= read -r -d '' feature; do
     # Imperative verbs / CSS selectors in steps (declarative warning)
-    awk -v file="$feature" '
+    process_awk_output "$(awk -v file="$feature" '
       /^[[:space:]]*(Given|When|Then|And|But)/ {
         line = $0
         if (line ~ /click|type|fill[ _]in|press|select.*from[ _]dropdown/) {
@@ -58,10 +85,10 @@ else
           printf "WARN  %s:%d CSS selector / xpath in step (prefer business language)\n", file, NR
         }
       }
-    ' "$feature"
+    ' "$feature")"
 
     # Scenario length (> 10 steps)
-    awk -v file="$feature" '
+    process_awk_output "$(awk -v file="$feature" '
       /^[[:space:]]*Scenario/ { sc = NR; steps = 0; sn = $0; next }
       /^[[:space:]]*(Given|When|Then|And|But)/ { if (sc) steps++ }
       /^[[:space:]]*Scenario|^[[:space:]]*Feature|^$/ {
@@ -75,7 +102,7 @@ else
           printf "WARN  %s:%d scenario has %d steps (>10 is too long)\n", file, sc, steps
         }
       }
-    ' "$feature"
+    ' "$feature")"
 
     # Repeated Givens without Background (3+ identical Given lines)
     dupe=$(awk '/^[[:space:]]*Given/ { print }' "$feature" | sort | uniq -c | awk '$1 >= 3 { print }')
@@ -84,9 +111,7 @@ else
     fi
 
     # "And" at scenario start (grammar error)
-    awk -v file="$feature" '
-      prev_blank = 1
-      /^[[:space:]]*$/ { prev_blank = 1; next }
+    process_awk_output "$(awk -v file="$feature" '
       /^[[:space:]]*Scenario/ { in_scenario = 1; step_count = 0; next }
       /^[[:space:]]*(Given|When|Then|And|But)/ {
         if (in_scenario && step_count == 0 && /^[[:space:]]*And/) {
@@ -94,7 +119,7 @@ else
         }
         step_count++
       }
-    ' "$feature"
+    ' "$feature")"
 
   done < <(find "$PATH_ARG" -name "*.feature" -print0)
 fi
@@ -102,6 +127,25 @@ fi
 echo ""
 echo "gherkin-lint summary: $WARN_COUNT warning(s), $ERROR_COUNT error(s)"
 
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  exec 1>&3 3>&-
+  result="PASS"
+  sev_block=""
+  if [[ "$ERROR_COUNT" -gt 0 ]]; then
+    result="FAIL"
+  elif [[ "$WARN_COUNT" -gt 0 ]]; then
+    if [[ "$STRICT" -eq 1 ]]; then
+      result="FAIL"
+    else
+      result="ADVISORY"
+      sev_block=',"advisory_severity":"warn"'
+    fi
+  fi
+  printf '{"gate_id":"audit-harness:%s:gherkin-lint","result":"%s"%s,"input_hash":"%s","policy_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","metadata":{"warnings":%d,"errors":%d,"strict":%s,"path":"%s"}}\n' \
+    "${AUDIT_HARNESS_SIDE:-ci}" "$result" "$sev_block" "$INPUT_HASH" "$WARN_COUNT" "$ERROR_COUNT" \
+    "$([[ "$STRICT" -eq 1 ]] && echo true || echo false)" "$PATH_ARG"
+fi
+
 if [[ "$ERROR_COUNT" -gt 0 ]]; then
   exit 1
 fi

package/scripts/harness-hash.sh

@@ -6,19 +6,48 @@
 # causes escape-scan.sh to REFUSE the AI diff.
 #
 # Usage:
-#   bash harness-hash.sh --init      # write manifest (engineer-initiated)
-#   bash harness-hash.sh --verify    # compare current hashes to manifest
-#   bash harness-hash.sh --list      # show which files are pinned
+#   bash harness-hash.sh --init           # write manifest (engineer-initiated)
+#   bash harness-hash.sh --verify         # compare current hashes to manifest
+#   bash harness-hash.sh --verify --json  # machine-readable JSON to stdout (verify only)
+#   bash harness-hash.sh --list           # show which files are pinned
 #
 # Exit codes:
 #   0 — OK (pin matches, or init succeeded)
 #   2 — HARNESS_TAMPERED (hash mismatch)
 #   3 — no manifest found (--verify without --init)
+#
+# JSON mode:
+#   stdout = single JSON object suitable for piping to `audit-harness emit-evidence`
+#   stderr = unchanged human-readable summary (preserves backward-compat)
+#   exit codes unchanged
 
 set -euo pipefail
 
+# Cross-platform SHA-256: `sha256sum` ships with GNU coreutils (Linux);
+# macOS only has `shasum -a 256`. Both produce identical `<hash>  <file>`
+# output, so downstream awk parsing is unchanged.
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256_CMD=(sha256sum)
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256_CMD=(shasum -a 256)
+else
+  echo "harness-hash: neither sha256sum nor shasum found in PATH" >&2
+  exit 2
+fi
+
 ROOT="${ROOT:-$(pwd)}"
 MANIFEST="${ROOT}/.harness-hash"
+JSON_OUT=0
+
+# Peel --json from anywhere in args (additive, doesn't disturb existing arg shape)
+_filtered_args=()
+for arg in "$@"; do
+  case "$arg" in
+    --json) JSON_OUT=1 ;;
+    *) _filtered_args+=("$arg") ;;
+  esac
+done
+set -- "${_filtered_args[@]+"${_filtered_args[@]}"}"
 
 PATTERNS=(
   # Wall 1: acceptance
@@ -42,6 +71,27 @@ PATTERNS=(
   "stryker.config.js"
 )
 
+# Optional per-repo extra patterns appended from .harness-hash-extra-patterns
+# at the repo root. Used by repos whose policy files don't match the default
+# canonical patterns above — e.g., the audit-harness repo itself pins its own
+# scripts (scripts/*.sh + scripts/*.py + bin/audit-harness.js), which are the
+# policy enforcement surface but aren't covered by the consumer-facing
+# defaults. Lines beginning with `#` are comments; blank lines are ignored.
+# This mechanism is additive — repos without the file get exactly the
+# default behavior, so consumer repos are not affected.
+EXTRA_PATTERNS_FILE="${ROOT}/.harness-hash-extra-patterns"
+if [[ -f "${EXTRA_PATTERNS_FILE}" ]]; then
+  while IFS= read -r line || [[ -n "${line}" ]]; do
+    # strip inline comments
+    line="${line%%#*}"
+    # trim leading + trailing whitespace
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ -z "${line}" ]] && continue
+    PATTERNS+=("${line}")
+  done < "${EXTRA_PATTERNS_FILE}"
+fi
+
 collect_files() {
   local out=()
   shopt -s nullglob globstar
@@ -61,7 +111,7 @@ hash_files() {
     return 0
   fi
   while IFS= read -r f; do
-    printf '%s  %s\n' "$(sha256sum "$f" | awk '{print $1}')" "$f"
+    printf '%s  %s\n' "$("${SHA256_CMD[@]}" "$f" | awk '{print $1}')" "$f"
   done <<< "$files"
 }
 
@@ -76,6 +126,10 @@ cmd_init() {
 cmd_verify() {
   cd "$ROOT"
   if [[ ! -f "$MANIFEST" ]]; then
+    if [[ "$JSON_OUT" -eq 1 ]]; then
+      printf '{"gate_id":"audit-harness:%s:harness-hash","result":"NOT_APPLICABLE","input_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","policy_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","metadata":{"reason":"no manifest at %s (run --init)"}}\n' \
+        "${AUDIT_HARNESS_SIDE:-ci}" "$MANIFEST"
+    fi
     echo "harness-hash: no manifest at $MANIFEST (run --init)" >&2
     exit 3
   fi
@@ -84,13 +138,32 @@ cmd_verify() {
   local expected
   expected=$(cat "$MANIFEST")
 
+  local manifest_hash
+  manifest_hash=$("${SHA256_CMD[@]}" "$MANIFEST" | awk '{print "sha256:"$1}')
+
+  local pinned_count
+  pinned_count=$(echo "$expected" | grep -c '^' || true)
+
   # Compare sorted manifests so order doesn't matter
   local diff_out
   diff_out=$(diff <(echo "$expected" | sort) <(echo "$current" | sort) || true)
   if [[ -z "$diff_out" ]]; then
-    echo "harness-hash: OK"
+    if [[ "$JSON_OUT" -eq 1 ]]; then
+      printf '{"gate_id":"audit-harness:%s:harness-hash","result":"PASS","input_hash":"%s","policy_hash":"%s","metadata":{"pinned_count":%d}}\n' \
+        "${AUDIT_HARNESS_SIDE:-ci}" "$manifest_hash" "$manifest_hash" "$pinned_count"
+      echo "harness-hash: OK" >&2
+    else
+      echo "harness-hash: OK"
+    fi
     exit 0
   fi
+  if [[ "$JSON_OUT" -eq 1 ]]; then
+    # diff output may contain quotes/newlines; encode as a single-line escaped string
+    local diff_escaped
+    diff_escaped=$(printf '%s' "$diff_out" | python3 -c 'import sys, json; print(json.dumps(sys.stdin.read()))')
+    printf '{"gate_id":"audit-harness:%s:harness-hash","result":"FAIL","failure_mode":"HARNESS_TAMPERED","input_hash":"%s","policy_hash":"%s","metadata":{"pinned_count":%d,"diff":%s}}\n' \
+      "${AUDIT_HARNESS_SIDE:-ci}" "$manifest_hash" "$manifest_hash" "$pinned_count" "$diff_escaped"
+  fi
   echo "HARNESS_TAMPERED: pinned artifact changed" >&2
   echo "$diff_out" >&2
   exit 2

package/scripts/scan.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""
+audit-harness scan — read-only security / hygiene / skill-quality gate-runner
+(PP-PLAN-040 Phase 4 / E6).
+
+For every `dimension: security | hygiene | skill-quality` gate in a repo's
+audit-profile/v1, scan runs the right external tool with the repo present and wraps
+its exit code into a `gate-result/v1` row (JSON array, stdout). Advisory-first; a
+missing tool degrades to ADVISORY indeterminate (never a false FAIL). It NEVER
+fixes anything and NEVER reimplements a scanner.
+
+Strategies:
+  - local      hygiene-readme: deterministic README presence check (no tool).
+  - shell-out  every gate carrying a `tool` (gitleaks, osv-scanner, semgrep, syft,
+               markdownlint, lychee, ...): run it if on PATH; clean exit -> PASS;
+               findings -> ADVISORY(error) (or FAIL under --strict / blocking);
+               tool absent -> ADVISORY indeterminate.
+  - consume    skill-quality skill-behavioral (tool j-rig): CONSUME a j-rig
+               Evidence Bundle verdict row (--jrig-verdict PATH or a default
+               location). The harness does NOT run behavioral judgment itself —
+               it ingests j-rig's verdict. No verdict -> ADVISORY indeterminate.
+
+Stdlib only. No network beyond whatever the shelled-out tool does (and the only
+network-touching gates fail open to indeterminate). No filesystem mutation.
+"""
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+if HERE not in sys.path:
+    sys.path.insert(0, HERE)
+import classify as C  # noqa: E402
+
+EMPTY_SHA = "sha256:" + hashlib.sha256(b"").hexdigest()
+SCAN_DIMENSIONS = {"security", "hygiene", "skill-quality"}
+
+# tool -> argv (run with cwd=repo). "generation" tools (syft) are PASS on exit 0,
+# INDETERMINATE on failure (they produce an artifact, they don't pass/fail policy).
+TOOL_CMD = {
+    "gitleaks": (["gitleaks", "detect", "--no-banner"], "scan"),
+    "osv-scanner": (["osv-scanner", "-r", "."], "scan"),
+    "semgrep": (["semgrep", "scan", "--error", "--quiet"], "scan"),
+    "syft": (["syft", "."], "generation"),
+    "markdownlint": (["markdownlint", "."], "scan"),
+    "lychee": (["lychee", "--offline", "--no-progress", "."], "scan"),
+}
+
+
+def sha256_str(s):
+    return "sha256:" + hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def make_row(gate_id, result, *, policy_hash, input_hash, commit_sha, runner,
+             metadata=None, failure_mode=None, advisory_severity=None):
+    row = {
+        "gate_id": gate_id, "result": result, "policy_hash": policy_hash,
+        "input_hash": input_hash,
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "runner": runner, "commit_sha": commit_sha,
+    }
+    if metadata:
+        row["metadata"] = metadata
+    if failure_mode is not None:
+        row["failure_mode"] = failure_mode
+    if advisory_severity is not None:
+        row["advisory_severity"] = advisory_severity
+    return row
+
+
+def gate_suffix(gate_id):
+    return gate_id.rsplit(":", 1)[-1]
+
+
+def indeterminate(gate, commit_sha, runner, reason, policy):
+    return make_row(gate["gate_id"], "ADVISORY", policy_hash=sha256_str(policy),
+                    input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                    advisory_severity="warn",
+                    metadata={"indeterminate": True, "reason": reason})
+
+
+def run_readme(repo, gate, commit_sha, runner, strict):
+    enforcement = gate.get("enforcement", "advisory")
+    present = any(os.path.isfile(os.path.join(repo, n))
+                 for n in ("README.md", "README.rst", "README.txt", "README"))
+    if present:
+        return make_row(gate["gate_id"], "PASS", policy_hash=sha256_str("hygiene:readme"),
+                        input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                        metadata={"method": "local-presence", "signal": "README present"})
+    result, fm, sev = ("FAIL", "hygiene:readme-missing", None) if (strict or enforcement == "blocking") \
+        else ("ADVISORY", None, "warn")
+    return make_row(gate["gate_id"], result, policy_hash=sha256_str("hygiene:readme"),
+                    input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                    failure_mode=fm, advisory_severity=sev,
+                    metadata={"method": "local-presence", "reason": "no README found"})
+
+
+def run_tool(tool, repo, gate, commit_sha, runner, strict):
+    enforcement = gate.get("enforcement", "advisory")
+    policy = f"tool:{tool}"
+    if tool not in TOOL_CMD:
+        return indeterminate(gate, commit_sha, runner,
+                             f"no invocation wired for tool '{tool}'", policy)
+    if shutil.which(tool) is None:
+        return indeterminate(gate, commit_sha, runner,
+                             f"{tool} not on PATH — {gate.get('dimension')} unmeasured", policy)
+    argv, kind = TOOL_CMD[tool]
+    try:
+        proc = subprocess.run(argv, cwd=repo, capture_output=True, text=True, timeout=300)
+    except Exception as e:
+        return indeterminate(gate, commit_sha, runner, f"{tool} failed to run: {e}", policy)
+    if proc.returncode == 0:
+        return make_row(gate["gate_id"], "PASS", policy_hash=sha256_str(policy),
+                        input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                        metadata={"method": "shell-out", "tool": tool})
+    if kind == "generation":
+        # syft etc. failing to generate is infra, not a policy violation
+        return indeterminate(gate, commit_sha, runner,
+                             f"{tool} could not generate artifact (exit {proc.returncode})", policy)
+    detail = (proc.stdout or proc.stderr).strip()[:2000]
+    result, fm, sev = ("FAIL", f"scan:{tool}-findings", None) if (strict or enforcement == "blocking") \
+        else ("ADVISORY", None, "error")
+    return make_row(gate["gate_id"], result, policy_hash=sha256_str(policy),
+                    input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                    failure_mode=fm, advisory_severity=sev,
+                    metadata={"method": "shell-out", "tool": tool, "detail": detail})
+
+
+def consume_jrig(repo, gate, commit_sha, runner, strict, verdict_path):
+    """Ingest a j-rig Evidence Bundle verdict row — never run judgment here."""
+    policy = "consume:j-rig"
+    candidates = [verdict_path] if verdict_path else []
+    candidates += [os.path.join(repo, p) for p in
+                   (".j-rig/verdict.json", ".jrig/verdict.json", "j-rig-verdict.json")]
+    path = next((p for p in candidates if p and os.path.isfile(p)), None)
+    if path is None:
+        return indeterminate(gate, commit_sha, runner,
+                             "no j-rig verdict available — run j-rig eval and pass --jrig-verdict",
+                             policy)
+    verdict = C.read_json(path)
+    if not isinstance(verdict, dict):
+        return indeterminate(gate, commit_sha, runner, f"unreadable j-rig verdict at {path}", policy)
+    # Pass through j-rig's own result if present; otherwise interpret a boolean pass.
+    enforcement = gate.get("enforcement", "advisory")
+    jres = verdict.get("result") or ("PASS" if verdict.get("passed") else "FAIL")
+    meta = {"method": "consume-j-rig", "source": os.path.relpath(path, repo),
+            "jrig": {k: verdict.get(k) for k in ("result", "passed", "layers_passed", "baseline_delta")
+                     if k in verdict}}
+    if jres == "PASS":
+        return make_row(gate["gate_id"], "PASS", policy_hash=sha256_str(policy),
+                        input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner, metadata=meta)
+    result, fm, sev = ("FAIL", "skill-quality:jrig-fail", None) if (strict or enforcement == "blocking") \
+        else ("ADVISORY", None, "error")
+    return make_row(gate["gate_id"], result, policy_hash=sha256_str(policy),
+                    input_hash=EMPTY_SHA, commit_sha=commit_sha, runner=runner,
+                    failure_mode=fm, advisory_severity=sev, metadata=meta)
+
+
+def compute_profile(repo, registry_path, profile_arg):
+    if profile_arg == "-":
+        return json.load(sys.stdin)
+    if profile_arg:
+        with open(profile_arg, "r", encoding="utf-8") as f:
+            return json.load(f)
+    out = subprocess.run([sys.executable, os.path.join(HERE, "classify.py"), repo,
+                          "--registry", registry_path], capture_output=True, text=True)
+    if out.returncode != 0:
+        sys.stderr.write(out.stderr)
+        raise SystemExit(2)
+    return json.loads(out.stdout)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Security/hygiene/skill-quality gate-runner -> gate-result/v1")
+    ap.add_argument("repo", nargs="?", default=".")
+    ap.add_argument("--strict", action="store_true", help="treat a finding/gap as FAIL (exit 1)")
+    ap.add_argument("--registry", default=C.DEFAULT_REGISTRY)
+    ap.add_argument("--profile", default=None, help="pinned audit-profile/v1 (PATH or '-')")
+    ap.add_argument("--jrig-verdict", default=None, help="path to a j-rig Evidence Bundle verdict to consume")
+    args = ap.parse_args()
+
+    repo = os.path.abspath(args.repo)
+    runner = f"audit-harness@{C.harness_version()}"
+
+    override_path = os.path.join(repo, ".audit-harness.yml")
+    override = C.parse_override(override_path) if os.path.isfile(override_path) else {"disable": False}
+    if override.get("disable") or os.environ.get("AUDIT_HARNESS_DISABLE") == "1":
+        sys.stderr.write("audit-harness: KILL-SWITCH active — scan skipped (no rows emitted)\n")
+        print("[]")
+        sys.exit(0)
+
+    profile = compute_profile(repo, os.path.abspath(args.registry), args.profile)
+    commit_sha = profile.get("subject", {}).get("commit_sha") or C.git_short_sha(repo)
+
+    gates = [g for g in profile.get("gates", [])
+             if g.get("dimension") in SCAN_DIMENSIONS and g.get("enforcement") != "disabled"]
+
+    rows = []
+    for gate in gates:
+        suffix = gate_suffix(gate["gate_id"])
+        tool = gate.get("tool")
+        if suffix == "hygiene-readme":
+            rows.append(run_readme(repo, gate, commit_sha, runner, args.strict))
+        elif tool == "j-rig":
+            rows.append(consume_jrig(repo, gate, commit_sha, runner, args.strict, args.jrig_verdict))
+        elif tool:
+            rows.append(run_tool(tool, repo, gate, commit_sha, runner, args.strict))
+        else:
+            rows.append(indeterminate(gate, commit_sha, runner,
+                                      f"gate '{suffix}' has no tool wired in this harness version",
+                                      f"scan:{suffix}"))
+
+    print(json.dumps(rows, indent=2))
+    n_fail = sum(1 for r in rows if r["result"] == "FAIL")
+    n_adv = sum(1 for r in rows if r["result"] == "ADVISORY")
+    n_pass = sum(1 for r in rows if r["result"] == "PASS")
+    sys.stderr.write(f"audit-harness scan: {n_pass} PASS, {n_adv} ADVISORY, {n_fail} FAIL "
+                     f"across {len(rows)} gate(s)\n")
+    sys.exit(1 if n_fail else 0)
+
+
+if __name__ == "__main__":
+    main()