@intentsolutions/audit-harness 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `@intentsolutions/audit-harness` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-04-21
+
+Initial release. Extracted from the `audit-tests` Claude Code skill v7.0.0 to enable in-repo enforcement without global skill installation.
+
+### Added
+
+- `audit-harness verify` — SHA-256 hash verification for pinned policy files
+- `audit-harness init` — initialize/re-init the `.harness-hash` manifest
+- `audit-harness list` — list pinned files
+- `audit-harness escape-scan` — detect AI escape patterns in a diff (coverage threshold lowering, test deletion, architecture bypasses, test skip markers)
+- `audit-harness arch` — dispatch language-appropriate architecture checker (dependency-cruiser / import-linter / ArchUnit / deptrac / arch-go)
+- `audit-harness bias` — count common test-bias patterns
+- `audit-harness gherkin-lint` — advisory Gherkin quality check
+- `audit-harness crap` — CRAP (Complexity × Coverage) scorer for Python, JS/TS, Go, Rust
+
+### Key design decisions
+
+- **Scripts stay as shell/python.** Not a TypeScript port — battle-tested implementations, language-portable, minimal dependencies.
+- **Thin Node CLI.** `bin/audit-harness.js` is a dispatcher only; all logic lives in `scripts/`.
+- **Policy-driven thresholds.** `escape-scan.sh` reads floors from `tests/TESTING.md` in the target repo, not from the script source.
+- **Zero runtime dependencies** beyond Node 18+, bash, and Python 3 (only if using `crap` command).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Longshore / Intent Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @intentsolutions/audit-harness
+
+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
+
+A small CLI wrapping 6 deterministic scripts:
+
+| Command | Purpose |
+|---|---|
+| `audit-harness verify` | Verify hash-pinned artifacts haven't changed since `--init` |
+| `audit-harness init` | Pin the current state of engineer-owned policy files |
+| `audit-harness list` | Show pinned files |
+| `audit-harness escape-scan --staged` | Detect AI attempts to lower test thresholds, delete tests, bypass architecture rules |
+| `audit-harness arch` | Run language-appropriate architecture-rule checker (dependency-cruiser / import-linter / ArchUnit / deptrac / arch-go) |
+| `audit-harness bias` | Count common test-bias patterns |
+| `audit-harness gherkin-lint` | Advisory Gherkin quality check |
+| `audit-harness crap` | CRAP (Complexity × Coverage) scorer — Python, Go, JS/TS, Rust |
+
+## Install
+
+```bash
+pnpm add -D @intentsolutions/audit-harness
+# or: npm install --save-dev @intentsolutions/audit-harness
+# or: yarn add --dev @intentsolutions/audit-harness
+```
+
+## Quick usage
+
+### Pre-commit hook (`.husky/pre-commit`)
+
+```bash
+#!/usr/bin/env sh
+pnpm exec audit-harness escape-scan --staged
+pnpm exec audit-harness verify
+```
+
+### CI workflow (`.github/workflows/ci.yml`)
+
+```yaml
+  containment:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v6
+        with: { node-version: '20', cache: 'pnpm' }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec audit-harness verify
+      - run: pnpm exec audit-harness escape-scan --range origin/main..HEAD
+```
+
+### Engineer workflow — change a policy threshold
+
+```bash
+# 1. Edit tests/TESTING.md to change coverage.line from 80 to 75
+# 2. Re-init to accept the change
+pnpm exec audit-harness init
+# 3. Commit the updated manifest alongside the policy change
+git add tests/TESTING.md .harness-hash
+git commit -m "chore(test): lower coverage floor to 75"
+```
+
+## The containment model
+
+The harness enforces this rule: **policy changes must be conscious, not silent.**
+
+Engineer-owned files (`tests/TESTING.md`, `features/*.feature`, `.dependency-cruiser.cjs`, `stryker.conf.json`, etc.) are hashed into a manifest. Any diff that changes their content without a fresh `audit-harness init` is caught by pre-commit / CI and **REFUSED**.
+
+AI agents remain useful (they can read policy, they can implement within constraints). What they can't do is silently weaken the constraints. That's the entire design.
+
+See `audit-tests/references/philosophy.md` in the companion skill for the full rationale.
+
+## The 7-layer testing taxonomy
+
+This harness sits inside a larger framework:
+
+```
+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
+L4  Integration / Contract / Migration         ← Infrastructure wiring
+L3  Unit + Coverage + Mutation + Arch + CRAP   ← Code-level correctness  ← audit-harness lives here
+L2  Static analysis / Lint / Types / Secrets   ← Read-only scanning
+L1  Git hooks / CI enforcement                 ← The cheapest gate       ← audit-harness enables this
+```
+
+The harness commands serve L1 (escape-scan in pre-commit + CI) and L3 (CRAP, architecture, bias, hash-pin).
+
+## Exit codes
+
+Important for CI scripting:
+
+| Exit | Command | Meaning |
+|---|---|---|
+| 0 | any | Clean |
+| 1 | escape-scan | CHALLENGE — requires engineer-approved comment |
+| 2 | verify | `HARNESS_TAMPERED` — pinned file changed |
+| 2 | escape-scan | REFUSE — pipeline halted |
+| 3 | verify | No manifest (fresh repo, not an error) |
+
+## Language support
+
+Most scripts are language-agnostic (shell + regex). CRAP has per-language backends:
+
+| Language | CRAP | Arch | Notes |
+|---|---|---|---|
+| Python | radon + coverage.py | import-linter | full support |
+| JS/TS | complexity-report + c8 | dependency-cruiser | full support |
+| Go | gocyclo + go test -cover | arch-go | full support |
+| Rust | rust-code-analysis + tarpaulin | (custom) | coverage integration pending |
+| Java/Kotlin | — | ArchUnit | via language-native tooling |
+| .NET | — | ArchUnitNET | via language-native tooling |
+| PHP | — | deptrac | via language-native tooling |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## 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
+
+## Versioning
+
+SemVer. Breaking changes to the CLI surface bump major; new commands bump minor; bug fixes bump patch.
+
+## Contributing
+
+This is infrastructure code. Changes need to be conservative. Before opening a PR:
+
+1. Read `audit-tests/references/philosophy.md` (in the companion skill) to understand the escape-grammar design
+2. Run `bash scripts/escape-scan.sh --staged` on your own diff — yes, the harness tests itself
+3. Add test cases if you're adding a new pattern to escape-scan or a new command to the CLI

package/bin/audit-harness.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * audit-harness CLI dispatcher
+ *
+ * Thin wrapper that invokes the canonical shell/python implementations in scripts/.
+ * Keeping the scripts as-is (not a TS port) for v0.x — they're battle-tested
+ * and language-portable. The CLI just adds discoverability + cross-platform-ish shell resolution.
+ */
+const { spawn } = require('node:child_process');
+const { resolve, dirname } = require('node:path');
+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: [] },
+};
+
+function usage() {
+  console.log(`audit-harness — deterministic test-enforcement toolkit
+
+Usage:
+  audit-harness <command> [args...]
+
+Commands:
+  verify                   Verify hash-pinned artifacts (exit 2 = HARNESS_TAMPERED)
+  init                     Initialize or re-init the .harness-hash manifest
+  list                     List currently pinned files
+  escape-scan <source>     Scan a diff for escape attempts
+                           source: --staged | --range A..B | - (stdin) | path.patch
+  arch                     Run architecture-rule checks (Wall 7)
+  bias                     Count test-bias patterns (tautology, smoke-only, etc.)
+  gherkin-lint             Advisory Gherkin quality check
+  crap [args...]           CRAP complexity × coverage scorer (multi-language)
+
+Options:
+  --version, -v            Print version
+  --help, -h               Print this help
+
+Exit codes (escape-scan):
+  0 = clean
+  1 = CHALLENGE (engineer-approved comment required)
+  2 = REFUSE (pipeline halted)
+`);
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  usage();
+  process.exit(0);
+}
+
+if (cmd === '--version' || cmd === '-v') {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const entry = COMMANDS[cmd];
+if (!entry) {
+  console.error(`audit-harness: unknown command '${cmd}'`);
+  usage();
+  process.exit(2);
+}
+
+const scriptPath = resolve(SCRIPTS, entry.script);
+if (!existsSync(scriptPath)) {
+  console.error(`audit-harness: script not found at ${scriptPath}`);
+  process.exit(2);
+}
+
+const isPython = entry.script.endsWith('.py');
+const interpreter = isPython ? 'python3' : 'bash';
+const finalArgs = [scriptPath, ...entry.args, ...rest];
+
+const child = spawn(interpreter, finalArgs, { stdio: 'inherit' });
+child.on('exit', (code, signal) => {
+  if (signal) {
+    console.error(`audit-harness: ${entry.script} killed by ${signal}`);
+    process.exit(128);
+  }
+  process.exit(code ?? 0);
+});
+child.on('error', (err) => {
+  console.error(`audit-harness: failed to spawn ${interpreter}: ${err.message}`);
+  process.exit(2);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@intentsolutions/audit-harness",
+  "version": "0.1.0",
+  "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",
+  "author": "Jeremy Longshore <jeremy@intentsolutions.io>",
+  "homepage": "https://github.com/jeremylongshore/audit-harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/audit-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jeremylongshore/audit-harness/issues"
+  },
+  "keywords": [
+    "testing",
+    "test-audit",
+    "hash-pin",
+    "escape-scan",
+    "crap",
+    "architecture",
+    "mutation-testing",
+    "coverage-gate",
+    "7-layer-testing",
+    "claude-code",
+    "ai-containment"
+  ],
+  "bin": {
+    "audit-harness": "./bin/audit-harness.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "bash scripts/escape-scan.sh --staged || true"
+  }
+}

package/scripts/arch-check.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# arch-check.sh — Wall 7 architecture-constraint dispatcher.
+#
+# Detects the primary language of the repo, invokes the appropriate
+# dependency / architecture checker with the project's rule pack, and
+# normalizes the exit code.
+#
+# Exit codes:
+#   0 — all rules pass
+#   1 — rule violations detected
+#   2 — no tool installed / no config / unsupported language
+#
+# Usage:
+#   bash arch-check.sh              # run from repo root
+#   bash arch-check.sh --json       # emit JSON summary to stdout
+#   bash arch-check.sh --help
+
+set -euo pipefail
+
+ROOT="${ROOT:-$(pwd)}"
+JSON_OUT=0
+REPORT_DIR="${ROOT}/reports/arch"
+
+usage() {
+  sed -n '2,20p' "$0"
+  exit 0
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --json) JSON_OUT=1 ;;
+    --help|-h) usage ;;
+    *) echo "arch-check: unknown flag $arg" >&2; exit 2 ;;
+  esac
+done
+
+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' \
+      "$tool" "$status" "$violations" "$log"
+  else
+    echo "arch-check: tool=$tool status=$status violations=$violations"
+    echo "           log=$log"
+  fi
+}
+
+# 1. dependency-cruiser (JS/TS)
+if [[ -f "${ROOT}/.dependency-cruiser.js" || -f "${ROOT}/.dependency-cruiser.cjs" ]]; then
+  LOG="${REPORT_DIR}/dep-cruiser.log"
+  if command -v npx >/dev/null 2>&1; then
+    if npx --no-install dependency-cruiser --validate --output-type err "${ROOT}/src" > "$LOG" 2>&1; then
+      emit_result dependency-cruiser pass 0 "$LOG"
+      exit 0
+    else
+      VIOL=$(grep -c "error" "$LOG" || echo 0)
+      emit_result dependency-cruiser fail "$VIOL" "$LOG"
+      exit 1
+    fi
+  else
+    emit_result dependency-cruiser missing-tool 0 "$LOG"
+    exit 2
+  fi
+fi
+
+# 2. import-linter (Python)
+if [[ -f "${ROOT}/.importlinter" ]] || grep -q "^\[importlinter\]" "${ROOT}/pyproject.toml" 2>/dev/null; then
+  LOG="${REPORT_DIR}/import-linter.log"
+  if command -v lint-imports >/dev/null 2>&1; then
+    if (cd "$ROOT" && lint-imports) > "$LOG" 2>&1; then
+      emit_result import-linter pass 0 "$LOG"
+      exit 0
+    else
+      VIOL=$(grep -c "BROKEN" "$LOG" || echo 0)
+      emit_result import-linter fail "$VIOL" "$LOG"
+      exit 1
+    fi
+  else
+    emit_result import-linter missing-tool 0 "$LOG"
+    exit 2
+  fi
+fi
+
+# 3. deptrac (PHP)
+if [[ -f "${ROOT}/deptrac.yaml" ]]; then
+  LOG="${REPORT_DIR}/deptrac.log"
+  if [[ -x "${ROOT}/vendor/bin/deptrac" ]]; then
+    if (cd "$ROOT" && vendor/bin/deptrac analyse --no-progress) > "$LOG" 2>&1; then
+      emit_result deptrac pass 0 "$LOG"
+      exit 0
+    else
+      VIOL=$(grep -Ec "violation" "$LOG" || echo 0)
+      emit_result deptrac fail "$VIOL" "$LOG"
+      exit 1
+    fi
+  else
+    emit_result deptrac missing-tool 0 "$LOG"
+    exit 2
+  fi
+fi
+
+# 4. arch-go
+if [[ -f "${ROOT}/arch-go.yml" ]]; then
+  LOG="${REPORT_DIR}/arch-go.log"
+  if command -v arch-go >/dev/null 2>&1; then
+    if (cd "$ROOT" && arch-go) > "$LOG" 2>&1; then
+      emit_result arch-go pass 0 "$LOG"
+      exit 0
+    else
+      VIOL=$(grep -c "Violation" "$LOG" || echo 0)
+      emit_result arch-go fail "$VIOL" "$LOG"
+      exit 1
+    fi
+  else
+    emit_result arch-go missing-tool 0 "$LOG"
+    exit 2
+  fi
+fi
+
+# 5. ArchUnit (Java/Kotlin) — run via build tool
+if [[ -f "${ROOT}/build.gradle" || -f "${ROOT}/build.gradle.kts" ]] && \
+   grep -rq "com.tngtech.archunit" "${ROOT}" --include="*.gradle*" 2>/dev/null; then
+  LOG="${REPORT_DIR}/archunit.log"
+  if [[ -x "${ROOT}/gradlew" ]]; then
+    if (cd "$ROOT" && ./gradlew test --tests '*ArchitectureTest*' --tests '*ArchTest*') > "$LOG" 2>&1; then
+      emit_result archunit pass 0 "$LOG"
+      exit 0
+    else
+      VIOL=$(grep -Ec "violated|FAILED" "$LOG" || echo 0)
+      emit_result archunit fail "$VIOL" "$LOG"
+      exit 1
+    fi
+  else
+    emit_result archunit missing-tool 0 "$LOG"
+    exit 2
+  fi
+fi
+
+# No tool / config found
+emit_result none not-configured 0 "$REPORT_DIR/none.log"
+exit 2

package/scripts/bias-count.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Quick test bias pattern counter
+# Usage: bash bias-count.sh [test-directory]
+#
+# Scans test files for common bias patterns that weaken test suites.
+# See references/test-quality-deep-audit.md Section 1 for full details.
+
+set -euo pipefail
+
+TEST_DIR="${1:-tests}"
+
+if [ ! -d "$TEST_DIR" ]; then
+  echo "ERROR: Test directory '$TEST_DIR' not found"
+  echo "Usage: bash bias-count.sh [test-directory]"
+  exit 1
+fi
+
+echo "═══════════════════════════════════════"
+echo "  TEST BIAS SCAN — $TEST_DIR"
+echo "═══════════════════════════════════════"
+echo
+
+TOTAL_BIAS=0
+
+count_pattern() {
+  local label="$1"
+  local pattern="$2"
+  local count
+  count=$(grep -rn "$pattern" "$TEST_DIR" 2>/dev/null | wc -l)
+  TOTAL_BIAS=$((TOTAL_BIAS + count))
+  printf "  %-30s %d\n" "$label" "$count"
+}
+
+echo "BIAS PATTERNS"
+echo "─────────────────────────────────────"
+count_pattern "Smoke-only (is not None)" "is not None$"
+count_pattern "Smoke-only (assertIsNotNone)" "assertIsNotNone"
+count_pattern "Smoke-only (toBeDefined)" "toBeDefined()"
+count_pattern "Tautological (sorted==sorted)" "sorted.*==.*sorted"
+count_pattern "Tautological (len==len)" "len.*==.*len"
+count_pattern "Symmetric input (0,0)" "(0, 0)"
+count_pattern "Symmetric input (1,1)" "(1, 1)"
+count_pattern "Symmetric input (100,100)" "(100, 100)"
+count_pattern "Range-only assertion" "assert.*<=.*<="
+count_pattern 'Substring check (in str)' '" in '
+echo
+
+# Count test functions
+TEST_COUNT=$(grep -rn "def test_\|it('\|it(\"\\|test('\|test(\"" "$TEST_DIR" 2>/dev/null | wc -l)
+
+# Count total assertions
+ASSERT_COUNT=$(grep -rn "assert\b\|assertEqual\|expect(" "$TEST_DIR" 2>/dev/null | wc -l)
+
+# Assertion density
+if [ "$TEST_COUNT" -gt 0 ]; then
+  DENSITY=$(echo "scale=2; $ASSERT_COUNT / $TEST_COUNT" | bc)
+else
+  DENSITY="0"
+fi
+
+# Per-100 bias rate
+if [ "$TEST_COUNT" -gt 0 ]; then
+  RATE=$(echo "scale=1; $TOTAL_BIAS * 100 / $TEST_COUNT" | bc)
+else
+  RATE="0"
+fi
+
+echo "SUMMARY"
+echo "─────────────────────────────────────"
+printf "  %-30s %d\n" "Test functions" "$TEST_COUNT"
+printf "  %-30s %d\n" "Total assertions" "$ASSERT_COUNT"
+printf "  %-30s %s\n" "Assertion density" "$DENSITY per test"
+printf "  %-30s %d\n" "Bias patterns found" "$TOTAL_BIAS"
+printf "  %-30s %s\n" "Per-100-tests rate" "$RATE"
+echo
+
+# Grade
+if [ "$(echo "$RATE <= 5" | bc)" -eq 1 ]; then
+  echo "  Grade: LOW — no action needed"
+elif [ "$(echo "$RATE <= 15" | bc)" -eq 1 ]; then
+  echo "  Grade: MODERATE — review flagged tests"
+elif [ "$(echo "$RATE <= 30" | bc)" -eq 1 ]; then
+  echo "  Grade: HIGH — systematic remediation needed"
+else
+  echo "  Grade: CRITICAL — full rewrite of flagged tests"
+fi
+echo
+echo "═══════════════════════════════════════"

package/scripts/crap-score.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+"""CRAP (Change Risk Analyzer and Predictor) calculator — multi-language.
+
+Reads language-native complexity and coverage outputs, computes
+    CRAP(m) = C(m)^2 * (1 - cov(m)/100)^3 + C(m)
+for every method, ranks them, and emits CSV + JSON.
+
+Walls 5 and 6 of the Seven Walls (audit-tests skill):
+  - Production code: no method CRAP > 30; project average <= 10.
+  - Test code:       no method CRAP > 15.
+
+Thresholds are configurable via --threshold (local tuning is logged).
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class MethodScore:
+    language: str
+    path: str
+    method: str
+    complexity: int
+    coverage: float
+    crap: float
+    kind: str  # "src" or "test"
+
+
+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
+
+
+def detect_language(root: Path) -> str:
+    candidates = [
+        ("pyproject.toml", "python"),
+        ("setup.py", "python"),
+        ("package.json", "js"),
+        ("go.mod", "go"),
+        ("Cargo.toml", "rust"),
+        ("pom.xml", "java"),
+        ("build.gradle", "java"),
+        ("build.gradle.kts", "java"),
+        ("composer.json", "php"),
+        ("Gemfile", "ruby"),
+        ("*.csproj", "dotnet"),
+    ]
+    for pattern, lang in candidates:
+        if "*" in pattern:
+            if any(root.glob(pattern)):
+                return lang
+        elif (root / pattern).is_file():
+            return lang
+    return "unknown"
+
+
+def which_or_none(cmd: str) -> str | None:
+    return shutil.which(cmd)
+
+
+def run(cmd: list[str], cwd: Path) -> tuple[int, str, str]:
+    p = subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True, check=False)
+    return p.returncode, p.stdout, p.stderr
+
+
+# ---------- Python: radon + coverage ----------
+
+def score_python(root: Path, kind: str) -> list[MethodScore]:
+    if kind == "src":
+        candidates = ["src", "myapp", "app"]
+        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 test_dirs
+                and any(p.rglob("*.py"))
+            ]
+    else:
+        candidates = ["tests", "test"]
+        scanned = [t for t in candidates if (root / t).is_dir()]
+    if not scanned:
+        return []
+
+    if which_or_none("radon") is None:
+        print("[crap-score] radon not installed (pip install radon)", file=sys.stderr)
+        return []
+
+    complexity: dict[tuple[str, str], int] = {}
+    for tgt in scanned:
+        rc, out, err = run(["radon", "cc", "-s", "-a", "-j", tgt], root)
+        if rc != 0 or not out.strip():
+            continue
+        try:
+            data = json.loads(out)
+        except json.JSONDecodeError:
+            continue
+        for fpath, blocks in data.items():
+            for block in blocks:
+                name = block.get("name") or ""
+                method_key = (fpath, name)
+                complexity[method_key] = int(block.get("complexity", 0))
+
+    coverage: dict[str, float] = {}
+    cov_json = root / "coverage.json"
+    if not cov_json.is_file() and which_or_none("coverage"):
+        run(["coverage", "json", "-o", "coverage.json", "--fail-under=0"], root)
+    if cov_json.is_file():
+        try:
+            cov_data = json.loads(cov_json.read_text())
+            for fpath, summary in cov_data.get("files", {}).items():
+                pct = summary.get("summary", {}).get("percent_covered", 0.0)
+                coverage[fpath] = float(pct)
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    scores: list[MethodScore] = []
+    for (fpath, name), c in complexity.items():
+        cov = coverage.get(fpath, 0.0)
+        scores.append(
+            MethodScore(
+                language="python",
+                path=fpath,
+                method=name,
+                complexity=c,
+                coverage=cov,
+                crap=crap(c, cov),
+                kind=kind,
+            )
+        )
+    return scores
+
+
+# ---------- Go: gocyclo + go test -cover ----------
+
+def score_go(root: Path, kind: str) -> list[MethodScore]:
+    if which_or_none("gocyclo") is None:
+        print("[crap-score] gocyclo not installed", file=sys.stderr)
+        return []
+
+    rc, out, _ = run(["gocyclo", "-ignore", "_test.go" if kind == "src" else ".*\\.go$", "."], root)
+    complexity: list[tuple[str, str, int]] = []
+    for line in out.splitlines():
+        parts = line.strip().split()
+        if len(parts) < 4:
+            continue
+        try:
+            c = int(parts[0])
+        except ValueError:
+            continue
+        pkg = parts[1]
+        func = parts[2]
+        fpath = parts[3].split(":", 1)[0]
+        include = fpath.endswith("_test.go") if kind == "test" else not fpath.endswith("_test.go")
+        if include:
+            complexity.append((fpath, f"{pkg}.{func}", c))
+
+    coverage: dict[str, float] = {}
+    cov_out = root / "coverage.out"
+    if not cov_out.is_file():
+        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)
+        for line in out.splitlines():
+            parts = line.split()
+            if len(parts) >= 3 and parts[-1].endswith("%"):
+                fpath = parts[0].split(":", 1)[0]
+                try:
+                    pct = float(parts[-1].rstrip("%"))
+                except ValueError:
+                    continue
+                coverage[fpath] = pct
+
+    scores: list[MethodScore] = []
+    for fpath, name, c in complexity:
+        cov = coverage.get(fpath, 0.0)
+        scores.append(
+            MethodScore(
+                language="go", path=fpath, method=name, complexity=c,
+                coverage=cov, crap=crap(c, cov), kind=kind,
+            )
+        )
+    return scores
+
+
+# ---------- JS/TS: complexity-report + c8 ----------
+
+def score_js(root: Path, kind: str) -> list[MethodScore]:
+    cr_bin = which_or_none("cr") or which_or_none("complexity-report")
+    if cr_bin is None:
+        print("[crap-score] complexity-report not installed (npm i -D complexity-report)", file=sys.stderr)
+        return []
+    target = "src" if kind == "src" else "tests"
+    if not (root / target).is_dir():
+        return []
+    rc, out, _ = run([cr_bin, "--format", "json", target], root)
+    if rc != 0 or not out.strip():
+        return []
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError:
+        return []
+
+    cov_path = root / "coverage" / "coverage-summary.json"
+    coverage: dict[str, float] = {}
+    if cov_path.is_file():
+        try:
+            cov_data = json.loads(cov_path.read_text())
+            for fpath, summary in cov_data.items():
+                if fpath == "total":
+                    continue
+                lines_pct = summary.get("lines", {}).get("pct", 0.0)
+                coverage[fpath] = float(lines_pct)
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    scores: list[MethodScore] = []
+    for report in data.get("reports", []):
+        fpath = report.get("path", "")
+        cov = coverage.get(fpath, 0.0)
+        for func in report.get("functions", []):
+            c = int(func.get("cyclomatic", 1))
+            scores.append(
+                MethodScore(
+                    language="js", path=fpath, method=func.get("name", "<anon>"),
+                    complexity=c, coverage=cov, crap=crap(c, cov), kind=kind,
+                )
+            )
+    return scores
+
+
+# ---------- Rust: rust-code-analysis + tarpaulin ----------
+
+def score_rust(root: Path, kind: str) -> list[MethodScore]:
+    rca = which_or_none("rust-code-analysis-cli")
+    if rca is None:
+        print("[crap-score] rust-code-analysis-cli not installed", file=sys.stderr)
+        return []
+    target = "src" if kind == "src" else "tests"
+    if not (root / target).is_dir():
+        return []
+    rc, out, _ = run([rca, "-m", "-O", "json", "-p", target], root)
+    if rc != 0 or not out.strip():
+        return []
+    complexity: list[tuple[str, str, int]] = []
+    for line in out.splitlines():
+        try:
+            rec = json.loads(line)
+        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))
+    scores: list[MethodScore] = []
+    for fpath, name, c in complexity:
+        scores.append(
+            MethodScore(
+                language="rust", path=fpath, method=name, complexity=c,
+                coverage=0.0, crap=crap(c, 0.0), kind=kind,
+            )
+        )
+    return scores
+
+
+DISPATCH = {
+    "python": score_python,
+    "go": score_go,
+    "js": score_js,
+    "rust": score_rust,
+}
+
+
+# ---------- CLI ----------
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--root", default=".", help="Repository root")
+    ap.add_argument("--target", choices=["src", "test", "both"], default="both")
+    ap.add_argument("--format", choices=["csv", "json", "both"], default="both")
+    ap.add_argument("--out", default="reports/crap", help="Output directory")
+    ap.add_argument("--lang", default="auto",
+                    help="Force language (python|go|js|rust); default auto-detect")
+    ap.add_argument("--threshold-prod", type=float, default=30.0,
+                    help="Production CRAP max (default 30)")
+    ap.add_argument("--threshold-test", type=float, default=15.0,
+                    help="Test CRAP max (default 15)")
+    ap.add_argument("--threshold-avg", type=float, default=10.0,
+                    help="Project average max (default 10)")
+    args = ap.parse_args()
+
+    root = Path(args.root).resolve()
+    lang = args.lang if args.lang != "auto" else detect_language(root)
+    if lang not in DISPATCH:
+        print(f"[crap-score] unsupported language: {lang}", file=sys.stderr)
+        return 2
+
+    if any(t != d for t, d in (
+        (args.threshold_prod, 30.0),
+        (args.threshold_test, 15.0),
+        (args.threshold_avg, 10.0),
+    )):
+        print(f"[crap-score] threshold override: prod={args.threshold_prod} "
+              f"test={args.threshold_test} avg={args.threshold_avg}",
+              file=sys.stderr)
+
+    kinds = ["src", "test"] if args.target == "both" else [args.target]
+    all_scores: list[MethodScore] = []
+    for kind in kinds:
+        all_scores.extend(DISPATCH[lang](root, kind))
+
+    out_dir = root / args.out
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.format in ("csv", "both"):
+        for kind in kinds:
+            ranked = sorted(
+                [s for s in all_scores if s.kind == kind],
+                key=lambda s: s.crap, reverse=True,
+            )
+            csv_path = out_dir / f"crap-{kind}.csv"
+            with csv_path.open("w", newline="") as fh:
+                w = csv.writer(fh)
+                w.writerow(["rank", "crap", "complexity", "coverage_pct", "path", "method"])
+                for i, s in enumerate(ranked, 1):
+                    w.writerow([i, f"{s.crap:.2f}", s.complexity,
+                                f"{s.coverage:.1f}", s.path, s.method])
+
+    src_scores = [s for s in all_scores if s.kind == "src"]
+    test_scores = [s for s in all_scores if s.kind == "test"]
+    prod_max = max((s.crap for s in src_scores), default=0.0)
+    test_max = max((s.crap for s in test_scores), default=0.0)
+    prod_avg = (sum(s.crap for s in src_scores) / len(src_scores)) if src_scores else 0.0
+
+    prod_blockers = [asdict(s) for s in src_scores if s.crap > args.threshold_prod]
+    test_blockers = [asdict(s) for s in test_scores if s.crap > args.threshold_test]
+    avg_fail = prod_avg > args.threshold_avg
+
+    pass_ = not (prod_blockers or test_blockers or avg_fail)
+
+    summary = {
+        "language": lang,
+        "thresholds": {
+            "production_max": args.threshold_prod,
+            "test_max": args.threshold_test,
+            "project_avg_max": args.threshold_avg,
+        },
+        "production": {
+            "methods_scored": len(src_scores),
+            "max_crap": round(prod_max, 2),
+            "avg_crap": round(prod_avg, 2),
+            "blockers": prod_blockers,
+        },
+        "test": {
+            "methods_scored": len(test_scores),
+            "max_crap": round(test_max, 2),
+            "blockers": test_blockers,
+        },
+        "pass": pass_,
+    }
+
+    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")}))
+    return 0 if pass_ else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/escape-scan.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# escape-scan.sh — detect AI escape attempts in a proposed diff.
+#
+# Scans a unified diff (from git or a patch file) for patterns that indicate
+# the AI is trying to lower a wall instead of meeting the bar.
+#
+# Severity grammar:
+#   FLAG      → logged, does not halt (printed on stderr)
+#   CHALLENGE → require engineer-approved reason (exit 1)
+#   REFUSE    → halt the pipeline (exit 2)
+#
+# Exit codes:
+#   0 — clean
+#   1 — CHALLENGE (at least one must-challenge pattern matched)
+#   2 — REFUSE (at least one refuse pattern matched, or hash mismatch)
+#
+# Usage:
+#   git diff | bash escape-scan.sh -
+#   bash escape-scan.sh path/to/change.patch
+#   bash escape-scan.sh --staged          # git diff --cached
+#   bash escape-scan.sh --range HEAD~1..HEAD
+
+set -euo pipefail
+
+DIFF_SRC=""
+VERIFY_HASH=1
+ROOT="${ROOT:-$(pwd)}"
+HASH_SCRIPT="$(dirname "$0")/harness-hash.sh"
+
+if [[ "$#" -eq 0 ]]; then
+  echo "escape-scan: pass a diff source (- for stdin, --staged, --range, or a patch file)" >&2
+  exit 2
+fi
+
+case "$1" in
+  -) DIFF_SRC="/dev/stdin" ;;
+  --staged) DIFF_SRC=$(mktemp); git diff --cached > "$DIFF_SRC" ;;
+  --range) DIFF_SRC=$(mktemp); git diff "$2" > "$DIFF_SRC"; shift ;;
+  --no-hash) VERIFY_HASH=0; shift; DIFF_SRC="$1" ;;
+  --help|-h)
+    sed -n '2,22p' "$0"; exit 0 ;;
+  *) DIFF_SRC="$1" ;;
+esac
+
+if [[ ! -r "$DIFF_SRC" ]]; then
+  echo "escape-scan: cannot read $DIFF_SRC" >&2
+  exit 2
+fi
+
+REFUSE=0
+CHALLENGE=0
+FLAG=0
+
+# --- Load floor thresholds from tests/TESTING.md (fallback to defaults) ---
+# Reads canonical thresholds so audits enforce the repo's policy, not a
+# hardcoded script-level guess. Format expected in TESTING.md (policy section):
+#   coverage.line: 80
+#   coverage.branch: 70
+#   mutation.kill_rate: 70
+COVERAGE_LINE_FLOOR=80
+COVERAGE_BRANCH_FLOOR=70
+MUTATION_FLOOR=70
+TESTING_MD="$ROOT/tests/TESTING.md"
+if [[ -f "$TESTING_MD" ]]; then
+  v=$(grep -Ei '^\s*coverage\.line\s*:' "$TESTING_MD" | head -1 | sed -E 's/.*:\s*([0-9]+).*/\1/')
+  [[ -n "$v" ]] && COVERAGE_LINE_FLOOR="$v"
+  v=$(grep -Ei '^\s*coverage\.branch\s*:' "$TESTING_MD" | head -1 | sed -E 's/.*:\s*([0-9]+).*/\1/')
+  [[ -n "$v" ]] && COVERAGE_BRANCH_FLOOR="$v"
+  v=$(grep -Ei '^\s*mutation\.kill_rate\s*:' "$TESTING_MD" | head -1 | sed -E 's/.*:\s*([0-9]+).*/\1/')
+  [[ -n "$v" ]] && MUTATION_FLOOR="$v"
+fi
+
+# Collect only added lines (prefix + but not +++)
+added_lines=$(grep -E '^\+[^+]' "$DIFF_SRC" || true)
+file_headers=$(grep -E '^\+\+\+ ' "$DIFF_SRC" || true)
+
+note() {
+  local severity="$1" msg="$2"
+  echo "[$severity] $msg" >&2
+  case "$severity" in
+    REFUSE) REFUSE=$((REFUSE + 1)) ;;
+    CHALLENGE) CHALLENGE=$((CHALLENGE + 1)) ;;
+    FLAG) FLAG=$((FLAG + 1)) ;;
+  esac
+}
+
+# --- REFUSE: coverage threshold edits ---
+# Floor is policy-driven (tests/TESTING.md coverage.line). Any explicit
+# threshold lower than the floor is an escape attempt.
+check_below_floor() {
+  local line="$1" floor="$2"
+  local n
+  n=$(printf '%s\n' "$line" | grep -oE '[0-9]+' | head -1)
+  [[ -n "$n" ]] && [[ "$n" -lt "$floor" ]]
+}
+while IFS= read -r line; do
+  if [[ "$line" =~ fail_under[[:space:]]*=[[:space:]]*[0-9] ]] || [[ "$line" =~ --cov-fail-under=[0-9] ]]; then
+    if check_below_floor "$line" "$COVERAGE_LINE_FLOOR"; then
+      note REFUSE "coverage fail_under lowered below policy floor ($COVERAGE_LINE_FLOOR) — escape attempt"
+    fi
+  fi
+  if [[ "$line" =~ \"(branches|lines|functions|statements)\"[[:space:]]*:[[:space:]]*[0-9] ]]; then
+    if check_below_floor "$line" "$COVERAGE_LINE_FLOOR"; then
+      note REFUSE "Jest/c8 coverageThreshold lowered below policy floor ($COVERAGE_LINE_FLOOR) — escape attempt"
+    fi
+  fi
+done <<< "$added_lines"
+if echo "$added_lines" | grep -Eq 'coverageThreshold[[:space:]]*:[[:space:]]*0'; then
+  note REFUSE "coverageThreshold set to 0 (escape attempt)"
+fi
+if echo "$added_lines" | grep -Eq 'minimum[[:space:]]*=[[:space:]]*0\.[0-7]'; then
+  note REFUSE "JaCoCo minimum lowered (escape attempt)"
+fi
+
+# --- REFUSE: architecture bypasses ---
+if echo "$added_lines" | grep -Eq 'depcruise-disable|@ArchIgnore|skip_violations|ignore_imports[[:space:]]*=|severity[[:space:]]*:[[:space:]]*"warn"'; then
+  note REFUSE "architecture rule bypass (depcruise-disable / @ArchIgnore / skip_violations / ignore_imports / severity downgrade)"
+fi
+
+# --- REFUSE: wholesale test deletion (file headers only) ---
+# Detect deleted test files with no compensating additions
+deleted_tests=$(grep -E '^--- a/.*test.*|^--- a/.*spec.*' "$DIFF_SRC" | grep -v 'test.*\.md$' || true)
+added_tests=$(echo "$file_headers" | grep -E '\+\+\+ b/.*test.*|\+\+\+ b/.*spec.*' || true)
+if [[ -n "$deleted_tests" && -z "$added_tests" ]]; then
+  note REFUSE "test file(s) deleted without compensating additions"
+fi
+
+# --- REFUSE: .feature file mutation (hash check) ---
+if [[ "$VERIFY_HASH" -eq 1 && -f "$ROOT/.harness-hash" && -x "$HASH_SCRIPT" ]]; then
+  if ! (cd "$ROOT" && bash "$HASH_SCRIPT" --verify >/dev/null 2>&1); then
+    note REFUSE "HARNESS_TAMPERED — pinned .feature or rule-config file changed"
+  fi
+fi
+# Also REFUSE if the diff itself touches .feature files
+if echo "$file_headers" | grep -Eq '\+\+\+ b/.*\.feature'; then
+  note REFUSE ".feature file modified (human-owned artifact)"
+fi
+
+# --- CHALLENGE: test skip markers ---
+if echo "$added_lines" | grep -Eq '@pytest\.mark\.skip|\.skip\(|\.only\(|@Ignore\b|@Disabled\b|@SkipTest\b'; then
+  note CHALLENGE "test skip marker added (requires engineer-approved reason)"
+fi
+
+# --- CHALLENGE: mutation bypass markers ---
+if echo "$added_lines" | grep -Eq 'pragma:[[:space:]]*no[[:space:]]*mutate|Stryker[[:space:]]*disable|@DoNotMutate'; then
+  note CHALLENGE "mutation bypass marker added"
+fi
+
+# --- CHALLENGE: assertion weakening (diff-aware) ---
+# Look at removed+added pairs: old was a strong assertion, new is weak
+# Heuristic: new line contains assertTrue(True) / toBeDefined() / is not None
+if echo "$added_lines" | grep -Eq 'assertTrue\(True\)|assertEquals\(true,[[:space:]]*true\)'; then
+  note CHALLENGE "trivially-true assertion added (assertTrue(True) equivalent)"
+fi
+
+# --- FLAG: weak-assertion patterns (informational) ---
+if echo "$added_lines" | grep -Eq 'toBeDefined\(\)|\.is not None'; then
+  note FLAG "smoke-only assertion pattern (consider tightening)"
+fi
+
+# --- Summary & exit ---
+echo "escape-scan: REFUSE=$REFUSE CHALLENGE=$CHALLENGE FLAG=$FLAG"
+if [[ "$REFUSE" -gt 0 ]]; then
+  echo "escape-scan: pipeline halted (REFUSE)" >&2
+  exit 2
+fi
+if [[ "$CHALLENGE" -gt 0 ]]; then
+  echo "escape-scan: pipeline needs engineer approval (CHALLENGE)" >&2
+  exit 1
+fi
+exit 0

package/scripts/gherkin-lint.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# gherkin-lint.sh — Advisory Gherkin quality check for Wall 1.
+#
+# If gherkin-lint is installed (npm i -g gherkin-lint) it is used. Otherwise
+# falls back to awk-based rubric checks for imperative verbs, CSS selectors
+# in steps, missing Background, and overlong scenarios.
+#
+# Non-blocking by default (exit 0 on warnings). Use --strict to turn warnings
+# into failures.
+#
+# Usage:
+#   bash gherkin-lint.sh [--path features/] [--strict]
+
+set -euo pipefail
+
+PATH_ARG="features/"
+STRICT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --path) PATH_ARG="$2"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    --help|-h)
+      sed -n '2,15p' "$0"; exit 0 ;;
+    *) echo "gherkin-lint: unknown flag $1" >&2; exit 2 ;;
+  esac
+done
+
+if [[ ! -d "$PATH_ARG" ]]; then
+  echo "gherkin-lint: path not found: $PATH_ARG" >&2
+  exit 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)); }
+
+# 1. Prefer official gherkin-lint if available
+if command -v gherkin-lint >/dev/null 2>&1; then
+  echo "gherkin-lint: using installed linter"
+  if ! gherkin-lint "$PATH_ARG"; then
+    ERROR_COUNT=1
+  fi
+else
+  echo "gherkin-lint: falling back to awk rubric (install gherkin-lint for full rules)"
+
+  while IFS= read -r -d '' feature; do
+    # Imperative verbs / CSS selectors in steps (declarative warning)
+    awk -v file="$feature" '
+      /^[[:space:]]*(Given|When|Then|And|But)/ {
+        line = $0
+        if (line ~ /click|type|fill[ _]in|press|select.*from[ _]dropdown/) {
+          printf "WARN  %s:%d imperative verb in step (prefer declarative)\n", file, NR
+        }
+        if (line ~ /#[a-zA-Z][-a-zA-Z0-9_]*|\.[a-zA-Z][-a-zA-Z0-9_]*[[:space:]]|xpath/) {
+          printf "WARN  %s:%d CSS selector / xpath in step (prefer business language)\n", file, NR
+        }
+      }
+    ' "$feature"
+
+    # Scenario length (> 10 steps)
+    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|^$/ {
+        if (sc && steps > 10) {
+          printf "WARN  %s:%d scenario has %d steps (>10 is too long)\n", file, sc, steps
+        }
+        if (NR != sc) { sc = 0; steps = 0 }
+      }
+      END {
+        if (sc && steps > 10) {
+          printf "WARN  %s:%d scenario has %d steps (>10 is too long)\n", file, sc, steps
+        }
+      }
+    ' "$feature"
+
+    # Repeated Givens without Background (3+ identical Given lines)
+    dupe=$(awk '/^[[:space:]]*Given/ { print }' "$feature" | sort | uniq -c | awk '$1 >= 3 { print }')
+    if [[ -n "$dupe" ]] && ! grep -q "^[[:space:]]*Background:" "$feature"; then
+      warn "$feature" 0 "repeated Given lines without Background block"
+    fi
+
+    # "And" at scenario start (grammar error)
+    awk -v file="$feature" '
+      prev_blank = 1
+      /^[[:space:]]*$/ { prev_blank = 1; next }
+      /^[[:space:]]*Scenario/ { in_scenario = 1; step_count = 0; next }
+      /^[[:space:]]*(Given|When|Then|And|But)/ {
+        if (in_scenario && step_count == 0 && /^[[:space:]]*And/) {
+          printf "ERROR %s:%d scenario starts with And (use Given/When/Then)\n", file, NR
+        }
+        step_count++
+      }
+    ' "$feature"
+
+  done < <(find "$PATH_ARG" -name "*.feature" -print0)
+fi
+
+echo ""
+echo "gherkin-lint summary: $WARN_COUNT warning(s), $ERROR_COUNT error(s)"
+
+if [[ "$ERROR_COUNT" -gt 0 ]]; then
+  exit 1
+fi
+if [[ "$STRICT" -eq 1 && "$WARN_COUNT" -gt 0 ]]; then
+  exit 1
+fi
+exit 0

package/scripts/harness-hash.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# harness-hash.sh — SHA-256 manifest for engineer-owned artifacts.
+#
+# Pins .feature files and architecture rule configs. Any byte change to a
+# pinned file without a fresh --init is treated as HARNESS_TAMPERED and
+# 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
+#
+# Exit codes:
+#   0 — OK (pin matches, or init succeeded)
+#   2 — HARNESS_TAMPERED (hash mismatch)
+#   3 — no manifest found (--verify without --init)
+
+set -euo pipefail
+
+ROOT="${ROOT:-$(pwd)}"
+MANIFEST="${ROOT}/.harness-hash"
+
+PATTERNS=(
+  # Wall 1: acceptance
+  "features/**/*.feature"
+  "features/*.feature"
+  # Wall 7: architecture rule configs
+  ".dependency-cruiser.js"
+  ".dependency-cruiser.cjs"
+  ".importlinter"
+  "deptrac.yaml"
+  "arch-go.yml"
+  # Java ArchUnit tests
+  "src/test/java/**/*ArchTest*.java"
+  "src/test/java/**/*ArchitectureTest*.java"
+  # .NET ArchTests
+  "test/**/*ArchTests.cs"
+  "tests/**/*ArchTests.cs"
+  # Coverage thresholds (edits to these are escape attempts — hash them)
+  ".c8rc.json"
+  "stryker.conf.json"
+  "stryker.config.js"
+)
+
+collect_files() {
+  local out=()
+  shopt -s nullglob globstar
+  for pattern in "${PATTERNS[@]}"; do
+    for f in $pattern; do
+      [[ -f "$f" ]] && out+=("$f")
+    done
+  done
+  # de-dupe
+  printf '%s\n' "${out[@]}" | sort -u
+}
+
+hash_files() {
+  local files
+  files=$(collect_files)
+  if [[ -z "$files" ]]; then
+    return 0
+  fi
+  while IFS= read -r f; do
+    printf '%s  %s\n' "$(sha256sum "$f" | awk '{print $1}')" "$f"
+  done <<< "$files"
+}
+
+cmd_init() {
+  cd "$ROOT"
+  hash_files > "$MANIFEST"
+  local count
+  count=$(wc -l < "$MANIFEST" | tr -d ' ')
+  echo "harness-hash: pinned $count file(s) → $MANIFEST"
+}
+
+cmd_verify() {
+  cd "$ROOT"
+  if [[ ! -f "$MANIFEST" ]]; then
+    echo "harness-hash: no manifest at $MANIFEST (run --init)" >&2
+    exit 3
+  fi
+  local current
+  current=$(hash_files)
+  local expected
+  expected=$(cat "$MANIFEST")
+
+  # 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"
+    exit 0
+  fi
+  echo "HARNESS_TAMPERED: pinned artifact changed" >&2
+  echo "$diff_out" >&2
+  exit 2
+}
+
+cmd_list() {
+  cd "$ROOT"
+  if [[ ! -f "$MANIFEST" ]]; then
+    echo "harness-hash: no manifest (run --init)" >&2
+    exit 3
+  fi
+  awk '{print $2}' "$MANIFEST"
+}
+
+case "${1:-}" in
+  --init)   cmd_init ;;
+  --verify) cmd_verify ;;
+  --list)   cmd_list ;;
+  --help|-h|*)
+    sed -n '2,20p' "$0"
+    exit 0
+    ;;
+esac