(feat) lattice harness: deterministic contribution-quality checks

.claude/settings.json

@@ -4,5 +4,18 @@
       "Bash(rg:*)"
     ],
     "deny": []
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run --with pyyaml python .lattice/bin/run_check.py --tier inner --event posttooluse"
+          }
+        ]
+      }
+    ]
   }
-}
+}

.github/workflows/lattice-checks.yaml

@@ -0,0 +1,118 @@
+# GENERATED BY .lattice/bin/install_checks.py — DO NOT EDIT.
+# Lattice version: v0 (9a6d454aa88f). Re-run the installer to update.
+# GATE-tier checks: pre-merge CI. warn-only steps never block; promotion to
+# enforced (blocking) happens through the improvement loop on T2 evidence.
+name: Lattice Checks
+
+on:
+  push:
+    branches: [main, "release-**"]
+  pull_request:
+    branches: [main, "release-**"]
+
+permissions:
+  contents: read
+
+jobs:
+  lattice-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - name: "GATE CORE-CHK-001 — uv run --with pyyaml python .lattice/bin/install_checks.py --verify"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py CORE-CHK-001 --event ci
+      - name: "GATE CORE-INS-002 — sh .lattice/bin/checks/forbidden_zones.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py CORE-INS-002 --event ci
+      - name: "GATE CORE-INS-005 — sh .lattice/bin/checks/change_size.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py CORE-INS-005 --event ci
+      - name: "GATE CORE-INS-007 — uv run --extra dev python .lattice/bin/checks/deps_added.py"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py CORE-INS-007 --event ci
+      - name: "GATE CORE-INS-008 — sh .lattice/bin/checks/commit_format.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py CORE-INS-008 --event ci
+      - name: "GATE ITS-CHK-001 REPO-CHK-002 — uv build"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py ITS-CHK-001 REPO-CHK-002 --event ci
+      - name: "GATE ITS-INS-002 — uv run --extra dev python .lattice/bin/checks/its_algo_interface.py"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py ITS-INS-002 --event ci
+      - name: "GATE ITS-INS-004 — uv run --extra dev python .lattice/bin/checks/its_lm_interface.py"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py ITS-INS-004 --event ci
+      - name: "GATE ITS-INS-010 — uv run --extra dev python .lattice/bin/checks/its_variant_inherits.py"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py ITS-INS-010 --event ci
+      - name: "GATE PRAXIS-INS-011 REPO-INS-002 — sh .lattice/bin/checks/git_no_ai_attribution.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PRAXIS-INS-011 REPO-INS-002 --event ci
+      - name: "GATE PRAXIS-INS-012 RUST-INS-013 — cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D clippy::too_many_lines -D clippy::cognitive_complexity"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PRAXIS-INS-012 RUST-INS-013 --event ci
+      - name: "GATE PYTHON-CHK-003 — sh -c 'make proto-compile && uv run --extra dev python -m pytest tests/ --ignore=tests/e2e'"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PYTHON-CHK-003 --event ci
+      - name: "GATE PYTHON-CHK-004 — uv run --with vermin vermin -t=3.11- --no-tips --violations its_hub/"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PYTHON-CHK-004 --event ci
+      - name: "GATE REPO-INS-001 — sh .lattice/bin/checks/git_signoff.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py REPO-INS-001 --event ci
+      - name: "GATE REPO-INS-004 — sh .lattice/bin/checks/no_generated_tracked.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py REPO-INS-004 --event ci
+      - name: "GATE REPO-INS-005 — sh .lattice/bin/checks/lint_scope.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py REPO-INS-005 --event ci
+      - name: "GATE RUST-CHK-001 — cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-CHK-001 --event ci
+      - name: "GATE RUST-CHK-003 — cargo test --manifest-path rust/Cargo.toml"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-CHK-003 --event ci
+      - name: "GATE RUST-CHK-006 — sh -c 'RUSTDOCFLAGS=\"-D warnings\" cargo doc --manifest-path rust/Cargo.toml --no-deps --document-private-items'"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-CHK-006 --event ci
+      - name: "GATE RUST-INS-002 — cargo clippy --manifest-path rust/Cargo.toml -- -D unsafe_code"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-002 --event ci
+      - name: "GATE RUST-INS-004 — cargo clippy --manifest-path rust/Cargo.toml -- -D clippy::await_holding_lock"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-004 --event ci
+      - name: "GATE RUST-INS-005 — cargo clippy --manifest-path rust/Cargo.toml -- -D clippy::unwrap_used -D clippy::expect_used -D clippy::panic -D clippy::indexing_slicing"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-005 --event ci
+      - name: "GATE RUST-INS-006 — cargo clippy --manifest-path rust/Cargo.toml -- -D clippy::allow_attributes"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-006 --event ci
+      - name: "GATE RUST-INS-008 — cargo clippy --manifest-path rust/Cargo.toml -- -D missing_docs"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-008 --event ci
+      - name: "GATE RUST-INS-010 — cargo clippy --manifest-path rust/Cargo.toml -- -D clippy::todo -D clippy::unimplemented -D clippy::exit"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-010 --event ci
+      - name: "GATE RUST-INS-015 — sh .lattice/bin/checks/git_pr_size.sh"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py RUST-INS-015 --event ci
+      - name: Upload T2 traces
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lattice-t2-traces
+          path: .lattice/traces/T2/
+          if-no-files-found: ignore

.github/workflows/lattice-deep.yaml

@@ -0,0 +1,47 @@
+# GENERATED BY .lattice/bin/install_checks.py — DO NOT EDIT.
+# Lattice version: v0 (9a6d454aa88f). Re-run the installer to update.
+# DEEP-tier checks: scheduled job, off the merge path. Failures are surfaced
+# for the next improvement-loop pass, never blocking a merge.
+name: Lattice Deep Checks
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"  # Mondays 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lattice-deep:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: "DEEP PYTHON-CHK-005 — sh -c 'make proto-compile && uv run --extra dev python -m pytest tests/ --ignore=tests/e2e --cov=its_hub --cov-report=term-missing'"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PYTHON-CHK-005 --event scheduled
+      - name: "DEEP PYTHON-CHK-006 — uv run --with pip-audit pip-audit"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PYTHON-CHK-006 --event scheduled
+      - name: "DEEP PYTHON-CHK-007 — uv run --with ty ty check its_hub/"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py PYTHON-CHK-007 --event scheduled
+      - name: "DEEP REPO-INS-006 — sh -c 'make proto-compile && uv run --extra dev python -m pytest tests/ --ignore=tests/e2e --cov=its_hub --cov-report=xml -q >/dev/null && uv run --with diff-cover diff-cover coverage.xml --compare-branch origin/main --fail-under 100'"
+        continue-on-error: true  # warn-only
+        run: uv run --with pyyaml python .lattice/bin/run_check.py REPO-INS-006 --event scheduled
+      - name: Upload T2 traces
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lattice-t2-traces
+          path: .lattice/traces/T2/
+          if-no-files-found: ignore

.gitignore

@@ -190,6 +190,18 @@ results/
 
 .its-hub/
 .claude/worktrees/
+.lattice/*
+!.lattice/packs/
+!.lattice/scope-map.yaml
+!.lattice/version.yaml
+!.lattice/*.md
+!.lattice/bin/
+# Working-history / meta-harness notes are kept locally but never committed;
+# the committed lattice reflects only current state.
+.lattice/history/
+# but never track runtime traces or bytecode
+.lattice/traces/
+.lattice/bin/__pycache__/
 
 # Generated Envoy proto files
 its_hub/integration/proto/

.lattice/bin/_common.py

@@ -0,0 +1,104 @@
+"""Shared lattice helpers: pack loading, versioning, freshness.
+
+Imported by both ``run_check.py`` (runtime) and ``install_checks.py``
+(materialization) so the two paths agree on what a check is and whether it is
+installable on this recipient.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LATTICE_DIR = REPO_ROOT / ".lattice"
+PACKS_DIR = LATTICE_DIR / "packs"
+SCOPE_MAP = LATTICE_DIR / "scope-map.yaml"
+VERSION_FILE = LATTICE_DIR / "version.yaml"
+TRACES_DIR = LATTICE_DIR / "traces"
+
+INSTALLABLE_TIERS = ("inner", "gate", "deep")
+
+
+def load_version() -> dict[str, Any]:
+    """Return the parsed ``version.yaml`` (declared lattice version + notes)."""
+    return yaml.safe_load(VERSION_FILE.read_text()) or {}
+
+
+def lattice_version_hash() -> str:
+    """Content hash of composed packs + scope map (SPEC §3.5), truncated.
+
+    Immutable identity of the current lattice state; recorded in every T2 trace
+    so events from different lattice versions are never conflated.
+    """
+    h = hashlib.sha256()
+    for path in sorted(PACKS_DIR.glob("*.yaml")):
+        h.update(path.read_bytes())
+    if SCOPE_MAP.exists():
+        h.update(SCOPE_MAP.read_bytes())
+    return h.hexdigest()[:12]
+
+
+def iter_checks() -> list[dict[str, Any]]:
+    """Yield every ``kind: check`` rule across all packs, pack context attached."""
+    checks: list[dict[str, Any]] = []
+    for path in sorted(PACKS_DIR.glob("*.yaml")):
+        pack = yaml.safe_load(path.read_text()) or {}
+        for rule in pack.get("rules", []) or []:
+            if rule.get("kind") != "check":
+                continue
+            enriched = dict(rule)
+            enriched["_pack"] = pack.get("name", path.stem)
+            enriched["_layer"] = pack.get("layer")
+            checks.append(enriched)
+    return checks
+
+
+def get_check(rule_id: str) -> dict[str, Any] | None:
+    """Return the single check rule with ``rule_id``, or ``None``."""
+    for check in iter_checks():
+        if check.get("id") == rule_id:
+            return check
+    return None
+
+
+def scope_prefix_exists(scope: str) -> bool:
+    """Freshness for a scope glob (SPEC §5.4).
+
+    ``**`` (whole repo) always passes. Otherwise the static directory prefix
+    before the first wildcard must exist in the recipient — this is what parks
+    the grafted ``rust/**`` packs and any ``notebooks/**`` check on a repo that
+    has neither.
+    """
+    if not scope or scope == "**":
+        return True
+    prefix = scope.split("*", 1)[0].rstrip("/")
+    if not prefix:
+        return True
+    return (REPO_ROOT / prefix).exists()
+
+
+def freshness_reason(check: dict[str, Any]) -> str | None:
+    """Return a skip reason if the check is not installable here, else ``None``."""
+    if not check.get("check_command"):
+        return "no check_command (protocol/action check, not directly installable)"
+    scope = check.get("scope", "**")
+    if not scope_prefix_exists(scope):
+        return f"scope '{scope}' does not exist in this repository"
+    return None
+
+
+def installable_checks() -> tuple[list[dict[str, Any]], list[tuple[dict[str, Any], str]]]:
+    """Split checks into (installable, skipped-with-reason) for this recipient."""
+    keep: list[dict[str, Any]] = []
+    skip: list[tuple[dict[str, Any], str]] = []
+    for check in iter_checks():
+        reason = freshness_reason(check)
+        if reason:
+            skip.append((check, reason))
+        else:
+            keep.append(check)
+    return keep, skip

.lattice/bin/checks/_range.sh

@@ -0,0 +1,29 @@
+# Shared: resolve a root-safe review base/range for git-based checks.
+# Sourced, not executed. Sets:
+#   LATTICE_HEAD       — the review tip commit
+#   LATTICE_DIFF_BASE  — diff LATTICE_HEAD against this (merge-base, else empty tree)
+#   LATTICE_LOG_RANGE  — revision range for git log
+#
+# On a pull_request event the checked-out HEAD is a synthetic merge commit that
+# is neither signed off nor conventionally formatted. Using the PR head SHA as
+# the tip excludes exactly that synthetic commit while still inspecting real
+# commits (including developer-created merges). The empty-tree fallback keeps
+# diffs valid on an initial commit or a depth-one checkout lacking origin/main.
+
+LATTICE_HEAD="HEAD"
+if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+  _sha=$(python3 -c "import json,os; d=json.load(open(os.environ['GITHUB_EVENT_PATH'])); print((d.get('pull_request') or {}).get('head',{}).get('sha') or '')" 2>/dev/null || true)
+  if [ -n "$_sha" ] && git rev-parse --verify -q "${_sha}^{commit}" >/dev/null 2>&1; then
+    LATTICE_HEAD="$_sha"
+  fi
+fi
+
+if git rev-parse --verify -q origin/main >/dev/null 2>&1; then
+  # merge-base, not origin/main: if main advances after the branch started, a
+  # plain origin/main..HEAD diff would fold in main's own changes.
+  LATTICE_DIFF_BASE="$(git merge-base origin/main "$LATTICE_HEAD" 2>/dev/null || echo origin/main)"
+  LATTICE_LOG_RANGE="origin/main..$LATTICE_HEAD"
+else
+  LATTICE_DIFF_BASE="$(git hash-object -t tree /dev/null)"
+  LATTICE_LOG_RANGE="$LATTICE_HEAD"
+fi

.lattice/bin/checks/change_size.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# CORE-INS-005 — change-size budget: prefer <= ~400 changed lines and <= ~10 files
+# in the review range, excluding lockfiles and generated files.
+set -eu
+. "$(dirname "$0")/_range.sh"
+stat=$(git diff --numstat "$LATTICE_DIFF_BASE" "$LATTICE_HEAD" -- \
+  ':(exclude)**/uv.lock' ':(exclude)**/Cargo.lock' ':(exclude)**/poetry.lock' \
+  ':(exclude)its_hub/_version.py' ':(exclude)its_hub/integration/proto/**' 2>/dev/null)
+lines=$(echo "$stat" | awk '$1 ~ /^[0-9]+$/ && $2 ~ /^[0-9]+$/ {s += $1 + $2} END {print s + 0}')
+files=$(echo "$stat" | grep -c . || true)
+echo "changed lines: $lines, files: $files (budget: 400 lines / 10 files)"
+if [ "$lines" -gt 400 ] || [ "$files" -gt 10 ]; then
+  echo "exceeds change-size budget — consider splitting the PR"
+  exit 1
+fi
+echo "within change-size budget ✓"

.lattice/bin/checks/commit_format.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# CORE-INS-008 — commit subjects follow the repo's conventional format across the
+# review range. Accepts both "type: desc" and this repo's "(type) desc" style.
+# The "why, not what" quality of the body is not machine-checkable. Range excludes
+# the synthetic PR merge commit (via _range.sh); fails closed on a git error.
+set -eu
+. "$(dirname "$0")/_range.sh"
+types='feat|fix|chore|docs|refactor|test|perf|build|ci|style|revert'
+if ! subjects=$(git log "$LATTICE_LOG_RANGE" --format='%s' 2>&1); then
+  echo "error: cannot inspect range $LATTICE_LOG_RANGE:"
+  echo "$subjects"
+  exit 1
+fi
+bad=$(printf '%s\n' "$subjects" | grep -vE "^(\(($types)\)|($types)(\([a-z0-9_-]+\))?):? " || true)
+if [ -n "$bad" ]; then
+  echo "Commit subjects not in conventional format:"
+  printf '  %s\n' "$bad"
+  exit 1
+fi
+echo "All commit subjects follow conventional format ✓"