@intentsolutions/audit-harness 0.1.0 → 1.1.5

package/README.md

@@ -1,5 +1,11 @@
 # @intentsolutions/audit-harness
 
+[![npm](https://img.shields.io/npm/v/@intentsolutions/audit-harness?color=cb3837&logo=npm)](https://www.npmjs.com/package/@intentsolutions/audit-harness)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Provenance](https://img.shields.io/badge/sigstore-provenance-066da5)](https://www.npmjs.com/package/@intentsolutions/audit-harness)
+
+Part of the **[Intent Eval Platform](https://github.com/intent-solutions-io/intent-eval-platform)** — the umbrella mapping the six repos that converge via a shared Evidence Bundle schema.
+
 Deterministic test-enforcement toolkit. Companion to the `audit-tests` and `implement-tests` Claude Code skills — but usable standalone in any repo that wants hash-pinned, escape-scanned, AI-proof quality gates.
 
 ## What it is
@@ -19,12 +25,36 @@ A small CLI wrapping 6 deterministic scripts:
 
 ## Install
 
+Pick the install flavor that matches your repo's ecosystem — all three publish the same CLI surface.
+
+**Node / JS / TS** (from npm):
+
 ```bash
 pnpm add -D @intentsolutions/audit-harness
 # or: npm install --save-dev @intentsolutions/audit-harness
 # or: yarn add --dev @intentsolutions/audit-harness
 ```
 
+**Python** (from PyPI):
+
+```bash
+pip install intent-audit-harness
+# or inside a project venv:
+python -m pip install intent-audit-harness
+```
+
+**Rust** (from crates.io):
+
+```bash
+cargo install intent-audit-harness
+```
+
+**Any other language** (Go, Ruby, PHP, Java, .NET, shell, etc.) — vendor the scripts:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/jeremylongshore/intent-audit-harness/main/install.sh | bash
+```
+
 ## Quick usage
 
 ### Pre-commit hook (`.husky/pre-commit`)
@@ -75,7 +105,7 @@ See `audit-tests/references/philosophy.md` in the companion skill for the full r
 
 This harness sits inside a larger framework:
 
-```
+```text
 L7  Acceptance / RTM / Personas / Journeys     ← WHAT are we proving?
 L6  E2E / BDD / Visual regression              ← User-level guarantees
 L5  Perf / Security (SAST/DAST) / A11y / Chaos ← Non-functional
@@ -115,12 +145,14 @@ Most scripts are language-agnostic (shell + regex). CRAP has per-language backen
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+Apache 2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+
+**Note:** versions `0.x` shipped under the MIT license. Starting with `v1.0.0`, the project is licensed under Apache 2.0. Existing `0.x` releases on npm remain available under their original MIT terms; new releases (`>= 1.0.0`) are Apache 2.0.
 
 ## Related
 
-- [`audit-tests` Claude Code skill](https://github.com/jeremylongshore/audit-harness#related) — diagnostic pipeline that uses this harness
-- [`implement-tests` Claude Code skill](https://github.com/jeremylongshore/audit-harness#related) — filesystem-mutating installer that installs this harness as part of L1/L3 setup
+- [`audit-tests` Claude Code skill](https://github.com/jeremylongshore/intent-audit-harness#related) — diagnostic pipeline that uses this harness
+- [`implement-tests` Claude Code skill](https://github.com/jeremylongshore/intent-audit-harness#related) — filesystem-mutating installer that installs this harness as part of L1/L3 setup
 
 ## Versioning
 

package/bin/audit-harness.js

@@ -13,14 +13,15 @@ const { existsSync } = require('node:fs');
 const SCRIPTS = resolve(__dirname, '..', 'scripts');
 
 const COMMANDS = {
-  'verify':       { script: 'harness-hash.sh',  args: ['--verify'] },
-  'init':         { script: 'harness-hash.sh',  args: ['--init'] },
-  'list':         { script: 'harness-hash.sh',  args: ['--list'] },
-  'escape-scan':  { script: 'escape-scan.sh',   args: [] },
-  'arch':         { script: 'arch-check.sh',    args: [] },
-  'bias':         { script: 'bias-count.sh',    args: [] },
-  'gherkin-lint': { script: 'gherkin-lint.sh',  args: [] },
-  'crap':         { script: 'crap-score.py',    args: [] },
+  'verify':        { script: 'harness-hash.sh',  args: ['--verify'] },
+  'init':          { script: 'harness-hash.sh',  args: ['--init'] },
+  'list':          { script: 'harness-hash.sh',  args: ['--list'] },
+  'escape-scan':   { script: 'escape-scan.sh',   args: [] },
+  'arch':          { script: 'arch-check.sh',    args: [] },
+  'bias':          { script: 'bias-count.sh',    args: [] },
+  'gherkin-lint':  { script: 'gherkin-lint.sh',  args: [] },
+  'crap':          { script: 'crap-score.py',    args: [] },
+  'emit-evidence': { script: 'emit-evidence.sh', args: [] },
 };
 
 function usage() {
@@ -39,6 +40,15 @@ Commands:
   bias                     Count test-bias patterns (tautology, smoke-only, etc.)
   gherkin-lint             Advisory Gherkin quality check
   crap [args...]           CRAP complexity × coverage scorer (multi-language)
+  emit-evidence            Wrap a gate-result JSON envelope in an in-toto
+                           Statement v1 (predicate https://evals.intentsolutions.io/gate-result/v1)
+                           Read JSON on stdin: <gate> --json | audit-harness emit-evidence
+
+Evidence Bundle (v0.3.0+):
+  All gates support --json to emit machine-readable gate-result envelopes
+  suitable for piping to emit-evidence. See SEMVER.md for compatibility rules
+  and intent-eval-lab/specs/evidence-bundle/v0.1.0-draft/SPEC.md for the
+  envelope schema.
 
 Options:
   --version, -v            Print version

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@intentsolutions/audit-harness",
-  "version": "0.1.0",
+  "version": "1.1.5",
   "description": "Deterministic test-enforcement harness — escape-scan, hash-pinning, CRAP, architecture checks, bias detection, Gherkin lint. Companion to the audit-tests and implement-tests Claude Code skills.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Jeremy Longshore <jeremy@intentsolutions.io>",
-  "homepage": "https://github.com/jeremylongshore/audit-harness",
+  "homepage": "https://github.com/jeremylongshore/intent-audit-harness",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jeremylongshore/audit-harness.git"
+    "url": "git+https://github.com/jeremylongshore/intent-audit-harness.git"
   },
   "bugs": {
-    "url": "https://github.com/jeremylongshore/audit-harness/issues"
+    "url": "https://github.com/jeremylongshore/intent-audit-harness/issues"
   },
   "keywords": [
     "testing",
@@ -33,15 +33,17 @@
     "scripts",
     "README.md",
     "LICENSE",
+    "NOTICE",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "test": "bash scripts/escape-scan.sh --staged || true",
+    "prepublishOnly": "node bin/audit-harness.js --version"
+  },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "test": "bash scripts/escape-scan.sh --staged || true"
   }
-}
+}

package/scripts/arch-check.sh

@@ -39,7 +39,31 @@ mkdir -p "$REPORT_DIR"
 emit_result() {
   local tool="$1" status="$2" violations="$3" log="$4"
   if [[ "$JSON_OUT" -eq 1 ]]; then
-    printf '{"tool":"%s","status":"%s","violations":%s,"log":"%s"}\n' \
+    # status: pass / fail / missing-tool / not-configured
+    local result
+    case "$status" in
+      pass) result="PASS" ;;
+      fail) result="FAIL" ;;
+      missing-tool|not-configured) result="NOT_APPLICABLE" ;;
+      *) result="ADVISORY" ;;
+    esac
+    local input_hash="sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    local policy_hash="sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    # Best-effort: input_hash is the source tree fingerprint when running against ROOT/src
+    if [[ -d "${ROOT}/src" ]]; then
+      input_hash=$(find "${ROOT}/src" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" \) -exec sha256sum {} \; 2>/dev/null | sort | sha256sum | awk '{print "sha256:"$1}')
+    fi
+    # Hash the architecture rule config (whichever tool's config was used)
+    for cfg in .dependency-cruiser.js .dependency-cruiser.cjs .importlinter deptrac.yaml arch-go.yml; do
+      if [[ -f "${ROOT}/${cfg}" ]]; then
+        policy_hash=$(sha256sum "${ROOT}/${cfg}" | awk '{print "sha256:"$1}')
+        break
+      fi
+    done
+    local fail_block=""
+    [[ "$result" == "FAIL" ]] && fail_block=',"failure_mode":"arch-violation"'
+    printf '{"gate_id":"audit-harness:%s:arch-check","result":"%s"%s,"input_hash":"%s","policy_hash":"%s","metadata":{"tool":"%s","status":"%s","violations":%s,"log":"%s"}}\n' \
+      "${AUDIT_HARNESS_SIDE:-ci}" "$result" "$fail_block" "$input_hash" "$policy_hash" \
       "$tool" "$status" "$violations" "$log"
   else
     echo "arch-check: tool=$tool status=$status violations=$violations"

package/scripts/bias-count.sh

@@ -1,20 +1,48 @@
 #!/usr/bin/env bash
 # Quick test bias pattern counter
-# Usage: bash bias-count.sh [test-directory]
+# Usage: bash bias-count.sh [test-directory] [--json]
 #
 # Scans test files for common bias patterns that weaken test suites.
 # See references/test-quality-deep-audit.md Section 1 for full details.
+#
+# JSON mode:
+#   stdout = single JSON object suitable for piping to `audit-harness emit-evidence`
+#   stderr = unchanged human-readable summary (preserves backward-compat)
+#   exit code unchanged (always 0; advisory gate)
 
 set -euo pipefail
 
-TEST_DIR="${1:-tests}"
+JSON_OUT=0
+TEST_DIR="tests"
+
+# Peel --json from anywhere; first non-flag positional is TEST_DIR.
+_pos=()
+for arg in "$@"; do
+  case "$arg" in
+    --json) JSON_OUT=1 ;;
+    *) _pos+=("$arg") ;;
+  esac
+done
+[[ "${#_pos[@]}" -gt 0 ]] && TEST_DIR="${_pos[0]}"
 
 if [ ! -d "$TEST_DIR" ]; then
-  echo "ERROR: Test directory '$TEST_DIR' not found"
-  echo "Usage: bash bias-count.sh [test-directory]"
+  if [[ "$JSON_OUT" -eq 1 ]]; then
+    printf '{"gate_id":"audit-harness:%s:bias-count","result":"NOT_APPLICABLE","input_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","policy_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","metadata":{"reason":"test directory not found","path":"%s"}}\n' \
+      "${AUDIT_HARNESS_SIDE:-ci}" "$TEST_DIR"
+  fi
+  echo "ERROR: Test directory '$TEST_DIR' not found" >&2
+  echo "Usage: bash bias-count.sh [test-directory] [--json]" >&2
   exit 1
 fi
 
+# Hash the test directory tree as the "input"
+INPUT_HASH=$(find "$TEST_DIR" -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.php" -o -name "*.rb" \) -exec sha256sum {} + 2>/dev/null | sort | sha256sum | awk '{print "sha256:"$1}')
+
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  exec 3>&1   # save stdout for the JSON object
+  exec 1>&2   # redirect human-readable to stderr
+fi
+
 echo "═══════════════════════════════════════"
 echo "  TEST BIAS SCAN — $TEST_DIR"
 echo "═══════════════════════════════════════"
@@ -75,14 +103,32 @@ printf "  %-30s %s\n" "Per-100-tests rate" "$RATE"
 echo
 
 # Grade
+GRADE="LOW"
 if [ "$(echo "$RATE <= 5" | bc)" -eq 1 ]; then
+  GRADE="LOW"
   echo "  Grade: LOW — no action needed"
 elif [ "$(echo "$RATE <= 15" | bc)" -eq 1 ]; then
+  GRADE="MODERATE"
   echo "  Grade: MODERATE — review flagged tests"
 elif [ "$(echo "$RATE <= 30" | bc)" -eq 1 ]; then
+  GRADE="HIGH"
   echo "  Grade: HIGH — systematic remediation needed"
 else
+  GRADE="CRITICAL"
   echo "  Grade: CRITICAL — full rewrite of flagged tests"
 fi
 echo
 echo "═══════════════════════════════════════"
+
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  # Restore stdout for JSON emission
+  exec 1>&3 3>&-
+  # bias-count is advisory — never FAILs, severity rises with grade
+  case "$GRADE" in
+    LOW) sev="info" ;;
+    MODERATE) sev="warn" ;;
+    HIGH|CRITICAL) sev="error" ;;
+  esac
+  printf '{"gate_id":"audit-harness:%s:bias-count","result":"ADVISORY","advisory_severity":"%s","input_hash":"%s","policy_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","metadata":{"test_count":%d,"assertion_count":%d,"assertion_density":"%s","bias_total":%d,"per_100_rate":"%s","grade":"%s"}}\n' \
+    "${AUDIT_HARNESS_SIDE:-ci}" "$sev" "$INPUT_HASH" "$TEST_COUNT" "$ASSERT_COUNT" "$DENSITY" "$TOTAL_BIAS" "$RATE" "$GRADE"
+fi

package/scripts/crap-score.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import argparse
 import csv
+import hashlib
 import json
 import os
 import shutil
@@ -36,6 +37,19 @@ class MethodScore:
     kind: str  # "src" or "test"
 
 
+# Directories to skip during candidate discovery AND the --json input-hash
+# walk. Single source of truth — both call sites MUST use this set so a repo
+# with `reports/` (or `.next/`, `.nuxt/`, `.cache/`) gets identical treatment
+# in both the candidate scan and the input-hash computation. Adding a dir
+# here removes it from BOTH passes; that's the invariant this constant exists
+# to preserve.
+EXCLUDED_DIRS = {
+    ".git", ".venv", "venv", "node_modules", "__pycache__",
+    "dist", "build", "target", ".tox", ".mypy_cache", ".pytest_cache",
+    ".next", ".nuxt", ".cache", "reports",
+}
+
+
 def crap(complexity: int, coverage_pct: float) -> float:
     cov = max(0.0, min(100.0, coverage_pct)) / 100.0
     return (complexity ** 2) * ((1.0 - cov) ** 3) + complexity
@@ -81,12 +95,11 @@ def score_python(root: Path, kind: str) -> list[MethodScore]:
         scanned = [t for t in candidates if (root / t).is_dir()]
         if not scanned:
             test_dirs = {"tests", "test", "spec", "specs", "features", "__tests__"}
-            ignore = {".git", ".venv", "venv", "node_modules", "dist", "build", "target", ".tox", ".mypy_cache", ".pytest_cache", "reports", "__pycache__"}
             scanned = [
                 p.name for p in root.iterdir()
                 if p.is_dir()
                 and not p.name.startswith(".")
-                and p.name not in ignore
+                and p.name not in EXCLUDED_DIRS
                 and p.name not in test_dirs
                 and any(p.rglob("*.py"))
             ]
@@ -171,7 +184,7 @@ def score_go(root: Path, kind: str) -> list[MethodScore]:
 
     coverage: dict[str, float] = {}
     cov_out = root / "coverage.out"
-    if not cov_out.is_file():
+    if not cov_out.is_file() and which_or_none("go"):
         run(["go", "test", "-coverprofile=coverage.out", "-covermode=atomic", "./..."], root)
     if cov_out.is_file() and which_or_none("go"):
         rc, out, _ = run(["go", "tool", "cover", "-func=coverage.out"], root)
@@ -263,7 +276,6 @@ def score_rust(root: Path, kind: str) -> list[MethodScore]:
         except json.JSONDecodeError:
             continue
         fpath = rec.get("name", "")
-        metrics = rec.get("metrics", {}).get("cyclomatic", {})
         for func in rec.get("spaces", []):
             c = int(func.get("metrics", {}).get("cyclomatic", {}).get("sum", 1))
             complexity.append((fpath, func.get("name", "<anon>"), c))
@@ -302,6 +314,10 @@ def main() -> int:
                     help="Test CRAP max (default 15)")
     ap.add_argument("--threshold-avg", type=float, default=10.0,
                     help="Project average max (default 10)")
+    ap.add_argument("--json", action="store_true",
+                    help="Emit gate-result envelope JSON on stdout (suitable for piping "
+                         "to `audit-harness emit-evidence`). Preserves existing CSV/JSON "
+                         "files written under --out.")
     args = ap.parse_args()
 
     root = Path(args.root).resolve()
@@ -377,7 +393,51 @@ def main() -> int:
     if args.format in ("json", "both"):
         (out_dir / "summary.json").write_text(json.dumps(summary, indent=2))
 
-    print(json.dumps({"pass": pass_, "summary_path": str(out_dir / "summary.json")}))
+    if args.json:
+        side = os.environ.get("AUDIT_HARNESS_SIDE", "ci")
+        # input_hash: SHA256 over all production+test source-file contents under root, sorted.
+        # Use os.walk with directory pruning instead of rglob — large vendored trees
+        # (node_modules, .venv, .git, build outputs) would otherwise dominate the walk
+        # cost on big repos and waste IO on files we already filter out by extension.
+        digest = hashlib.sha256()
+        exts = (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt", ".cs", ".php", ".rb")
+        collected: list[Path] = []
+        for dirpath, dirs, files in os.walk(root):
+            dirs[:] = [d for d in dirs if d not in EXCLUDED_DIRS]
+            for fn in files:
+                if fn.endswith(exts):
+                    collected.append(Path(dirpath) / fn)
+        for fp in sorted(collected):
+            digest.update(fp.read_bytes())
+        input_hash = f"sha256:{digest.hexdigest()}"
+        # policy_hash: SHA256 over the threshold tuple (stable, deterministic)
+        policy_repr = f"prod={args.threshold_prod}|test={args.threshold_test}|avg={args.threshold_avg}".encode()
+        policy_hash = f"sha256:{hashlib.sha256(policy_repr).hexdigest()}"
+        result = "PASS" if pass_ else "FAIL"
+        envelope = {
+            "gate_id": f"audit-harness:{side}:crap-score",
+            "result": result,
+            "input_hash": input_hash,
+            "policy_hash": policy_hash,
+            "metadata": {
+                "language": lang,
+                "thresholds": summary["thresholds"],
+                "production_max_crap": summary["production"]["max_crap"],
+                "production_avg_crap": summary["production"]["avg_crap"],
+                "production_methods_scored": summary["production"]["methods_scored"],
+                "production_blockers_count": len(prod_blockers),
+                "test_max_crap": summary["test"]["max_crap"],
+                "test_methods_scored": summary["test"]["methods_scored"],
+                "test_blockers_count": len(test_blockers),
+                "avg_fail": avg_fail,
+                "summary_path": str(out_dir / "summary.json"),
+            },
+        }
+        if not pass_:
+            envelope["failure_mode"] = "crap-threshold-exceeded"
+        print(json.dumps(envelope))
+    else:
+        print(json.dumps({"pass": pass_, "summary_path": str(out_dir / "summary.json")}))
     return 0 if pass_ else 1
 
 

package/scripts/emit-evidence.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# emit-evidence.sh — wrap a gate-result JSON envelope in an in-toto Statement v1.
+#
+# Reads a gate-result envelope JSON document from stdin (or --input), augments it
+# with the fields the runner knows (timestamp, runner version, commit_sha), and
+# emits a complete in-toto Statement v1 to stdout. Optionally signs the Statement
+# via `cosign sign-blob` and/or pushes to the Rekor transparency log.
+#
+# Per intent-eval-lab/specs/evidence-bundle/v0.1.0-draft/SPEC.md the emitted
+# Statement carries predicateType https://evals.intentsolutions.io/gate-result/v1.
+#
+# Usage:
+#   <gate> --json | bash emit-evidence.sh                          # unsigned, prints Statement
+#   bash emit-evidence.sh --input gate.json                        # read from file
+#   bash emit-evidence.sh --sign --key cosign.key < gate.json      # cosign key-based sign
+#   bash emit-evidence.sh --sign --keyless < gate.json             # cosign keyless (Fulcio OIDC)
+#   bash emit-evidence.sh --sign --rekor-url https://rekor.sigstore.dev < gate.json
+#   bash emit-evidence.sh --output bundle/row.json < gate.json
+#
+# Flags:
+#   --input PATH       Read gate-result JSON from PATH instead of stdin
+#   --output PATH      Write Statement (DSSE envelope if --sign) to PATH instead of stdout
+#   --sign             Sign the Statement via cosign. Default: --keyless.
+#   --keyless          Force cosign keyless signing (OIDC). Default when --sign and no --key.
+#   --key PATH         Cosign keyref. Use instead of --keyless.
+#   --rekor-url URL    Push the signed attestation to Rekor at URL. Implies --sign.
+#                      Default Rekor URL when present without value: https://rekor.sigstore.dev
+#   --no-sign          Explicitly skip signing (default behavior; documents the choice)
+#   --runner-version V Override the runner version string (default: from package.json)
+#   --commit-sha SHA   Override the commit SHA (default: git rev-parse HEAD)
+#   --help, -h         Print help
+#
+# Exit codes:
+#   0 — Statement emitted successfully
+#   1 — input JSON malformed or missing required fields
+#   2 — signing requested but cosign not available
+#   3 — Rekor push requested but failed
+#
+# CISO gate (per ISEDC v1 Q1, 2026-05-10): pushing to a public transparency log
+# (Rekor) against the predicate URI https://evals.intentsolutions.io/gate-result/v1
+# is BLOCKED until DNSSEC + CAA records are verified on the namespace. The script
+# does NOT enforce this — that is operator discipline. See bead `iel-4zr` in
+# intent-eval-platform/intent-eval-lab/.beads/.
+
+set -euo pipefail
+
+INPUT="-"
+OUTPUT=""
+SIGN=0
+KEYLESS=0
+KEYREF=""
+REKOR_URL=""
+RUNNER_VERSION_OVERRIDE=""
+COMMIT_SHA_OVERRIDE=""
+PREDICATE_URI="https://evals.intentsolutions.io/gate-result/v1"
+STATEMENT_TYPE="https://in-toto.io/Statement/v1"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --input)       INPUT="$2"; shift 2 ;;
+    --output)      OUTPUT="$2"; shift 2 ;;
+    --sign)        SIGN=1; shift ;;
+    --keyless)     SIGN=1; KEYLESS=1; shift ;;
+    --key)         SIGN=1; KEYREF="$2"; shift 2 ;;
+    --rekor-url)
+                   SIGN=1
+                   if [[ "${2:-}" =~ ^-- ]] || [[ -z "${2:-}" ]]; then
+                     REKOR_URL="https://rekor.sigstore.dev"
+                     shift
+                   else
+                     REKOR_URL="$2"
+                     shift 2
+                   fi
+                   ;;
+    --no-sign)     SIGN=0; shift ;;
+    --runner-version) RUNNER_VERSION_OVERRIDE="$2"; shift 2 ;;
+    --commit-sha)  COMMIT_SHA_OVERRIDE="$2"; shift 2 ;;
+    --help|-h)     sed -n '2,40p' "$0"; exit 0 ;;
+    *) echo "emit-evidence: unknown flag $1" >&2; exit 1 ;;
+  esac
+done
+
+# --- Read input ---
+if [[ "$INPUT" == "-" ]]; then
+  GATE_JSON=$(cat)
+else
+  if [[ ! -r "$INPUT" ]]; then
+    echo "emit-evidence: cannot read $INPUT" >&2
+    exit 1
+  fi
+  GATE_JSON=$(cat "$INPUT")
+fi
+
+if [[ -z "$GATE_JSON" ]]; then
+  echo "emit-evidence: empty input" >&2
+  exit 1
+fi
+
+# --- Resolve runner + commit metadata ---
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PKG_JSON="${SCRIPT_DIR}/../package.json"
+
+if [[ -n "$RUNNER_VERSION_OVERRIDE" ]]; then
+  RUNNER="$RUNNER_VERSION_OVERRIDE"
+elif [[ -f "$PKG_JSON" ]]; then
+  # Pass PKG_JSON via argv so paths with quotes/spaces/specials don't break the python source.
+  VER=$(python3 -c "import json, sys; print(json.load(open(sys.argv[1]))['version'])" "$PKG_JSON" 2>/dev/null || echo "unknown")
+  RUNNER="audit-harness@${VER}"
+else
+  RUNNER="audit-harness@unknown"
+fi
+
+if [[ -n "$COMMIT_SHA_OVERRIDE" ]]; then
+  COMMIT_SHA="$COMMIT_SHA_OVERRIDE"
+else
+  COMMIT_SHA=$(git rev-parse HEAD 2>/dev/null || echo "0000000")
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# --- Compose the Statement via python (deterministic JSON shape, escaping handled) ---
+STATEMENT=$(GATE_JSON="$GATE_JSON" PREDICATE_URI="$PREDICATE_URI" STATEMENT_TYPE="$STATEMENT_TYPE" \
+  RUNNER="$RUNNER" COMMIT_SHA="$COMMIT_SHA" TIMESTAMP="$TIMESTAMP" \
+  python3 - <<'PY'
+import json, os, sys
+
+gate = json.loads(os.environ["GATE_JSON"])
+
+required = ["gate_id", "result", "input_hash", "policy_hash"]
+missing = [k for k in required if k not in gate]
+if missing:
+    sys.stderr.write(f"emit-evidence: gate-result missing required keys: {missing}\n")
+    sys.exit(1)
+
+# Augment predicate with runner-supplied fields
+predicate = {
+    "gate_id":     gate["gate_id"],
+    "result":      gate["result"],
+    "policy_hash": gate["policy_hash"],
+    "input_hash":  gate["input_hash"],
+    "timestamp":   os.environ["TIMESTAMP"],
+    "runner":      os.environ["RUNNER"],
+    "commit_sha":  os.environ["COMMIT_SHA"],
+}
+
+# Carry forward optional fields if present
+for opt in ("metadata", "failure_mode", "advisory_severity"):
+    if opt in gate:
+        predicate[opt] = gate[opt]
+
+# Subject naming: subject.name MUST equal predicate.gate_id (SPEC § 6 R8)
+# Subject digest: subject.digest.sha256 MUST equal predicate.input_hash (SPEC § 6 R9)
+input_hash = gate["input_hash"]
+if not input_hash.startswith("sha256:"):
+    sys.stderr.write(f"emit-evidence: input_hash must be sha256:-prefixed, got: {input_hash}\n")
+    sys.exit(1)
+digest_hex = input_hash[len("sha256:"):]
+
+statement = {
+    "_type":         os.environ["STATEMENT_TYPE"],
+    "subject":       [{
+        "name":   gate["gate_id"],
+        "digest": {"sha256": digest_hex},
+    }],
+    "predicateType": os.environ["PREDICATE_URI"],
+    "predicate":     predicate,
+}
+
+print(json.dumps(statement))
+PY
+)
+
+if [[ -z "$STATEMENT" ]]; then
+  echo "emit-evidence: failed to compose Statement" >&2
+  exit 1
+fi
+
+# --- OTel event (best-effort no-op if collector absent) ---
+# Fire agent.rollout.gate.evaluated per intent-eval-lab/000-docs/001-DR-RFC-...md.
+# We emit a single OTLP-shaped JSON line to stderr when AUDIT_HARNESS_OTEL=1
+# OR an OTEL_EXPORTER_OTLP_ENDPOINT is set. Real exporter wiring is consumer-side;
+# we emit a structured signal that any collector can scrape via stderr capture.
+if [[ "${AUDIT_HARNESS_OTEL:-0}" == "1" ]] || [[ -n "${OTEL_EXPORTER_OTLP_ENDPOINT:-}" ]]; then
+  GATE_ID=$(echo "$GATE_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('gate_id',''))" 2>/dev/null || echo "")
+  RESULT=$(echo "$GATE_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('result',''))" 2>/dev/null || echo "")
+  printf '[OTEL] {"name":"agent.rollout.gate.evaluated","attributes":{"gate.id":"%s","gate.result":"%s","gate.runner":"%s","gate.commit_sha":"%s"},"timestamp":"%s"}\n' \
+    "$GATE_ID" "$RESULT" "$RUNNER" "$COMMIT_SHA" "$TIMESTAMP" >&2
+fi
+
+# --- Sign + emit ---
+emit() {
+  local content="$1"
+  if [[ -n "$OUTPUT" ]]; then
+    mkdir -p "$(dirname "$OUTPUT")"
+    printf '%s\n' "$content" > "$OUTPUT"
+    echo "emit-evidence: wrote $OUTPUT" >&2
+  else
+    printf '%s\n' "$content"
+  fi
+}
+
+if [[ "$SIGN" -eq 0 ]]; then
+  emit "$STATEMENT"
+  exit 0
+fi
+
+# Signing requires cosign. We use `cosign attest-blob` if available (canonical
+# in-toto signing), falling back to `cosign sign-blob` with the Statement as the
+# blob (less canonical but functional for verification round-trip).
+if ! command -v cosign >/dev/null 2>&1; then
+  echo "emit-evidence: --sign requested but cosign is not installed (https://docs.sigstore.dev/cosign/installation/)" >&2
+  exit 2
+fi
+
+# Stage the Statement to a temp file for cosign to consume
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+STATEMENT_FILE="$TMP/statement.json"
+printf '%s\n' "$STATEMENT" > "$STATEMENT_FILE"
+ENVELOPE_FILE="$TMP/envelope.dsse.json"
+
+COSIGN_ARGS=("attest-blob" "--predicate" "$STATEMENT_FILE" "--type" "$PREDICATE_URI")
+if [[ -n "$KEYREF" ]]; then
+  COSIGN_ARGS+=("--key" "$KEYREF")
+elif [[ "$KEYLESS" -eq 1 ]] || [[ -z "$KEYREF" ]]; then
+  COSIGN_ARGS+=("--yes")   # accept Fulcio OIDC keyless
+fi
+if [[ -n "$REKOR_URL" ]]; then
+  COSIGN_ARGS+=("--rekor-url" "$REKOR_URL")
+  COSIGN_ARGS+=("--tlog-upload=true")
+else
+  COSIGN_ARGS+=("--tlog-upload=false")
+fi
+COSIGN_ARGS+=("--output-signature" "$ENVELOPE_FILE")
+# `cosign attest-blob` needs a "blob" — the input the predicate attests to.
+# Per SPEC subject naming, that's the input_hash; we use a virtual artifact name.
+ARTIFACT_NAME="$(echo "$STATEMENT" | python3 -c "import json,sys; print(json.load(sys.stdin)['subject'][0]['name'])")"
+
+# Write a placeholder blob whose sha256 == the declared input_hash. This makes
+# the DSSE envelope's subject coherent with the predicate.
+# (Cosign re-hashes the blob; we trust the gate's input_hash to be the canonical
+# subject. For v0.x we accept this round-trip-by-construction.)
+BLOB_FILE="$TMP/$ARTIFACT_NAME.blob"
+# A real subject artifact would be the file the gate evaluated; for the envelope
+# we use the in-band predicate as the blob. Verification only needs the DSSE
+# wrap + the predicate, not the original artifact bytes.
+cp "$STATEMENT_FILE" "$BLOB_FILE"
+
+if ! cosign "${COSIGN_ARGS[@]}" "$BLOB_FILE" >&2; then
+  echo "emit-evidence: cosign signing failed" >&2
+  exit 3
+fi
+
+emit "$(cat "$ENVELOPE_FILE")"
+echo "emit-evidence: signed envelope emitted${REKOR_URL:+ (Rekor: $REKOR_URL)}" >&2
+exit 0