feat: add agent-native repository guardrails

Author: alxxjohn

README.md

@@ -159,4 +159,3 @@ func main() {
 - [Homebrew packaging](docs/homebrew.md)
 - [Checks reference](docs/checks.md)
 - [Architecture](docs/architecture.md)
-- [Competitive roadmap](docs/competitive-roadmap.md)

benchmarks/manifest.example.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "corpus": "codeguard-public-prs-v1",
+  "entries": [
+    {
+      "id": "go-example-pr-1",
+      "language": "go",
+      "repository": "github.com/example/go-service",
+      "pull_request": 1,
+      "base_revision": "replace-with-immutable-base-commit",
+      "head_revision": "replace-with-immutable-head-commit",
+      "worktree": "go-example-pr-1",
+      "config": ".codeguard/codeguard.yaml"
+    }
+  ]
+}

cmd/codeguard-benchmark/main.go

@@ -0,0 +1,61 @@
+// codeguard-benchmark is a deliberately separate developer tool for frozen PR
+// corpus measurements. It never fetches repositories; provision them first.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/devr-tools/codeguard/internal/benchmark"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+	switch os.Args[1] {
+	case "export":
+		export(os.Args[2:])
+	case "run":
+		run(os.Args[2:])
+	default:
+		usage()
+		os.Exit(2)
+	}
+}
+
+func export(args []string) {
+	flags := flag.NewFlagSet("export", flag.ExitOnError)
+	manifestPath := flags.String("manifest", "", "benchmark manifest JSON")
+	out := flags.String("out", "", "corpus export JSON")
+	_ = flags.Parse(args)
+	manifest, err := benchmark.Load(*manifestPath)
+	fail(err)
+	fail(benchmark.WriteJSON(*out, manifest.Export()))
+}
+
+func run(args []string) {
+	flags := flag.NewFlagSet("run", flag.ExitOnError)
+	manifestPath := flags.String("manifest", "", "benchmark manifest JSON")
+	out := flags.String("out", "", "result JSON")
+	binary := flags.String("binary", "codeguard", "CodeGuard binary")
+	workRoot := flags.String("work-root", "", "directory containing provisioned worktrees")
+	warm := flags.Int("warm-repeats", 3, "warm scan repeats per entry")
+	_ = flags.Parse(args)
+	manifest, err := benchmark.Load(*manifestPath)
+	fail(err)
+	result, err := benchmark.Run(context.Background(), manifest, benchmark.RunOptions{Binary: *binary, WorkRoot: *workRoot, WarmRepeats: *warm})
+	fail(err)
+	fail(benchmark.WriteJSON(*out, result))
+}
+
+func usage() { fmt.Fprintln(os.Stderr, "usage: codeguard-benchmark <export|run> [flags]") }
+func fail(err error) {
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

docs/README.md

@@ -12,4 +12,4 @@
 - [Homebrew packaging](homebrew.md)
 - [Architecture](architecture.md)
 - [Checks](checks.md)
-- [Competitive roadmap](competitive-roadmap.md)
+- [Frozen PR benchmarks](benchmarks.md)

docs/ai-quality.md

@@ -47,6 +47,7 @@ This brief tracks the AI-generated-code quality features currently implemented i
 - Verified auto-fix
   - `codeguard.VerifyFix(...)` and `codeguard.GenerateVerifiedFix(ctx, req)` only return patches after diff-scoped verification and inferred or explicit verification tests pass in an isolated workspace
   - `codeguard fix -ai` exposes the same verified-fix flow from the CLI for one selected finding
+  - `codeguard fix-batch -input fixes.json` verifies explicitly supplied, catalogued deterministic fixes together in one isolated workspace and returns only their aggregate patch. It never modifies the working tree. The input is a JSON object with an `items` array of `{ "finding": { ... }, "candidate": { "diff": "..." } }` entries; use `-format json` to retain included, skipped, and failed item details.
 - Natural-language custom rules
   - custom rule packs can use `natural_language` instructions alongside regex and path matchers
   - evaluation is command-driven through the optional AI runtime and produces normal custom-rule findings

docs/benchmarks.md

@@ -0,0 +1,41 @@
+# Frozen PR benchmarks
+
+CodeGuard benchmarks PR-time scans using a small, versioned corpus of frozen
+public pull-request checkouts. The repository does not fetch or vendor those
+projects: the benchmark operator provisions each checkout at the exact commit
+listed in the manifest, then runs the harness locally or in a dedicated CI
+job.
+
+The manifest schema is versioned and machine-readable. Each entry records a
+repository, PR number, immutable base/head revisions, language, a worktree
+name relative to `-work-root`, and a relative CodeGuard configuration path.
+Use [manifest.example.json](../benchmarks/manifest.example.json) as the
+onboarding template. Do not replace immutable revisions with branch names.
+
+Export the corpus identity for an auditable result bundle:
+
+```sh
+go run ./cmd/codeguard-benchmark export \
+  -manifest benchmarks/manifest.json -out corpus.json
+```
+
+After provisioning the listed worktrees beneath a single directory, measure
+each diff scan:
+
+```sh
+go run ./cmd/codeguard-benchmark run \
+  -manifest benchmarks/manifest.json \
+  -work-root /private/tmp/codeguard-benchmark-worktrees \
+  -binary ./dist/codeguard -warm-repeats 3 -out results.json
+```
+
+Results contain a first-process `cold` run and the requested `warm` repeats
+for each entry. “Cold” means a fresh CodeGuard process; it does not claim to
+clear the host filesystem cache or alter the repository's configured cache.
+Record p50/p95 separately for cold and warm runs, and include the exported
+corpus metadata next to any published figures.
+
+Runtime is only one benchmark lane. Use the existing ground-truth detector
+corpus for precision/noise, and verified-fix fixtures for proposal coverage,
+verifier acceptance, and independently validated acceptance. Do not collapse
+the three lanes into a single competitive score.

docs/checks.md

@@ -46,7 +46,43 @@ Each top-level boolean enables or disables an entire check family.
 
 `context` covers agent-context legibility: when the key is omitted the family defaults to enabled in full scans and disabled in diff scans; see [Agent Context](#agent-context).
 
-`supply_chain` is opt-in and currently covers normalized manifest parsing plus initial policy checks for missing lockfiles, content-based lockfile drift validation, unpinned dependencies, dependency license policy resolved from local manifest and installed metadata where available, and Cargo manifest hygiene for missing package licenses and non-hermetic dependency sources.
+`supply_chain` is opt-in and currently covers normalized manifest parsing plus initial policy checks for missing lockfiles, content-based lockfile drift validation, unpinned dependencies, dependency license policy resolved from local manifest and installed metadata where available, local advisory-cache vulnerability matching, and Cargo manifest hygiene for missing package licenses and nonhermetic dependency sources.
+
+Set `output.format` to `cyclonedx` (or pass `codeguard scan -format cyclonedx`) to emit the normalized dependency artifacts as deterministic CycloneDX 1.6 JSON. The SBOM contains declared dependency versions or requirements when a resolver version is unavailable; it does not execute project code or contact a registry.
+
+### Offline advisory cache
+
+Vulnerability matching is opt-in. It reads a local, versioned JSON cache only; CodeGuard never contacts an advisory service during a scan. Configure the cache relative to the target root (or provide an absolute path):
+
+```yaml
+checks:
+  supply_chain: true
+  supply_chain_rules:
+    detect_vulnerabilities: true
+    advisory_cache_path: .codeguard/advisories.json
+```
+
+The first supported cache schema is `schema_version: 1`. Each advisory has an ecosystem matching CodeGuard's normalized ecosystem (`go`, `npm`, `python`, or `cargo`), a package, and one or more comma-separated version comparators. Matching is restricted to concrete pinned dependency versions to avoid claims based on unresolved ranges.
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-07-21T00:00:00Z",
+  "source": "approved-advisory-export-2026-07-21",
+  "advisories": [
+    {
+      "id": "CVE-2026-12345",
+      "ecosystem": "npm",
+      "package": "example-library",
+      "affected_versions": [">=1.0.0, <1.2.4"],
+      "fixed_version": "1.2.4",
+      "url": "https://example.invalid/advisories/CVE-2026-12345"
+    }
+  ]
+}
+```
+
+Findings contain the advisory identifier, source, generated timestamp, and cache age as non-sensitive metadata. Refreshing the cache is intentionally outside scan execution and should be handled by an approved, auditable update process.
 
 `contracts` covers API compatibility against a diff base. When omitted, it is enabled in diff scans and disabled in full scans. It checks exported Go declarations, public C++ headers, OpenAPI documents, protobuf schemas, and destructive migrations.