Add claude structured review output

.gitattributes

@@ -0,0 +1 @@
+bin/pushgate.mjs linguist-generated=true

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,8 +26,9 @@
 
 <!-- How did you verify this works? What edge cases did you consider? -->
 
-- [ ] `bash -n hook/pre-push` passes with no output
-- [ ] `bash -n install.sh` passes with no output
+- [ ] `pnpm test` passes
+- [ ] `pnpm run check:shell` passes with no output
+- [ ] `pnpm run lint:shell` passes
 - [ ] Manually tested the hook on a real repository
 - [ ] Tested on macOS
 - [ ] Tested on Linux
@@ -43,4 +44,4 @@
 
 ## Screenshots / output
 
-<!-- If your change affects terminal output, paste a before/after example here. -->
+<!-- If your change affects terminal output, paste a before/after example here. -->

.github/workflows/ci.yml

@@ -7,17 +7,36 @@ on:
 
 jobs:
   validate:
-    name: Validate shell scripts
+    name: Validate shell scripts and config
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Check hook syntax
-        run: bash -n hook/pre-push
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
 
-      - name: Check installer syntax
-        run: bash -n install.sh
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install Node dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build TypeScript config layer
+        run: pnpm build
+
+      - name: Test Node layer and hook harness
+        run: pnpm test
+
+      - name: Check shell syntax
+        run: pnpm run check:shell
+
+      - name: Install ShellCheck
+        run: sudo apt-get update && sudo apt-get install --yes shellcheck
+
+      - name: Check shell scripts with ShellCheck
+        run: pnpm run lint:shell
 
       - name: Verify hook is executable
         run: |
@@ -65,7 +84,7 @@ jobs:
 
       - name: Verify templates contain required keys
         run: |
-          required_keys="agent review tools ignore_paths"
+          required_keys="version ai review tools ignore_paths"
           for f in templates/*.yml; do
             for key in $required_keys; do
               if ! grep -q "^${key}:" "$f"; then

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+dist/
+node_modules/
+.understand-anything/*
+!.understand-anything/.understandignore
+docs/ONBOARDING.md

.nvmrc

@@ -0,0 +1 @@
+24.16.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.2.0"
+  ".": "3.5.0"
 }

.understand-anything/.understandignore

@@ -0,0 +1,5 @@
+# Exclude generated internals from architecture analysis.
+# They remain tracked and tested as distribution/release artifacts.
+
+bin/pushgate.mjs
+src/generated/*-validator.ts

CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [3.5.0](https://github.com/rootstrap/ai-pushgate/compare/v3.4.0...v3.5.0) (2026-06-23)
+
+
+### Features
+
+* allow repo-local pushgate runner overrides ([#51](https://github.com/rootstrap/ai-pushgate/issues/51)) ([b10c62c](https://github.com/rootstrap/ai-pushgate/commit/b10c62cf62b17f5a749431875954265d7c4b789d))
+
+
+### Bug Fixes
+
+* improve logging message format in pre-push hook ([#54](https://github.com/rootstrap/ai-pushgate/issues/54)) ([9d96f0a](https://github.com/rootstrap/ai-pushgate/commit/9d96f0a8627b11f78eef4564f84438da1d63647e))
+
+## [3.4.0](https://github.com/rootstrap/ai-pushgate/compare/v3.3.1...v3.4.0) (2026-06-22)
+
+
+### Features
+
+* add gitleaks plugin integration ([#49](https://github.com/rootstrap/ai-pushgate/issues/49)) ([ad085c1](https://github.com/rootstrap/ai-pushgate/commit/ad085c1ff8c10a9c4f59bb23cc33d9cb3415a65f))
+
+## [3.3.1](https://github.com/rootstrap/ai-pushgate/compare/v3.3.0...v3.3.1) (2026-06-18)
+
+
+### Bug Fixes
+
+* enhance JSON parsing and validation in AI review output ([#37](https://github.com/rootstrap/ai-pushgate/issues/37)) ([f4ec545](https://github.com/rootstrap/ai-pushgate/commit/f4ec545409a414fb75188effc8c27003faa21024))
+
+## [3.3.0](https://github.com/rootstrap/ai-pushgate/compare/v3.2.0...v3.3.0) (2026-06-15)
+
+
+### Features
+
+* add GitHub Copilot AI provider ([#34](https://github.com/rootstrap/ai-pushgate/issues/34)) ([9c33155](https://github.com/rootstrap/ai-pushgate/commit/9c33155c1ebe6819cd674c62e064f8233c510000))
+
+## [3.2.0](https://github.com/rootstrap/ai-pushgate/compare/v3.1.0...v3.2.0) (2026-06-14)
+
+
+### Features
+
+* normalize structured AI review output ([#32](https://github.com/rootstrap/ai-pushgate/issues/32)) ([4c2d05f](https://github.com/rootstrap/ai-pushgate/commit/4c2d05fd0751b4490be3c92b2ba50cd8787d92df))
+
+## [3.1.0](https://github.com/rootstrap/ai-pushgate/compare/v3.0.0...v3.1.0) (2026-06-08)
+
+
+### Features
+
+* add local AI provider interface and Claude adapter ([#29](https://github.com/rootstrap/ai-pushgate/issues/29)) ([8d95e23](https://github.com/rootstrap/ai-pushgate/commit/8d95e23f62c62596cb95b3cceb09cd04946c87a6))
+
+## [3.0.0](https://github.com/rootstrap/ai-pushgate/compare/v2.2.0...v3.0.0) (2026-06-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* Claude Code CLI is now mandatory and has to be installed to use the hook.
+
+### Features
+
+* add v2 config schema validation ([#20](https://github.com/rootstrap/ai-pushgate/issues/20)) ([8e262e7](https://github.com/rootstrap/ai-pushgate/commit/8e262e7e9184a0bb9c833ce3f5610c817c7c20f3))
+* check for version updates on hook run ([6354834](https://github.com/rootstrap/ai-pushgate/commit/6354834a8b684e0b04285c991e897c12ed009ecc))
+* display hook version upon installation ([452e766](https://github.com/rootstrap/ai-pushgate/commit/452e766301846e26932e674046b654677350ac4d))
+* enhance pre-push error handling and output reporting ([#24](https://github.com/rootstrap/ai-pushgate/issues/24)) ([c046e31](https://github.com/rootstrap/ai-pushgate/commit/c046e3166e5b4a013ffd80dd529fad86a3783053))
+* implement changed-file path policy and resolver for Git diffs ([#25](https://github.com/rootstrap/ai-pushgate/issues/25)) ([983cd2b](https://github.com/rootstrap/ai-pushgate/commit/983cd2ba0acbfc2c98046ad6e072eae2148c32fd))
+* implement local skip controls ([#28](https://github.com/rootstrap/ai-pushgate/issues/28)) ([37a1243](https://github.com/rootstrap/ai-pushgate/commit/37a1243a5bdba44f0fd01aa06f35b809ca6c4b2a))
+* initial commit ([e035cf1](https://github.com/rootstrap/ai-pushgate/commit/e035cf17f71909cbc47d103d9f759c915d7fe413))
+* update installation instructions in README and product contract documentation ([#17](https://github.com/rootstrap/ai-pushgate/issues/17)) ([e60ae7b](https://github.com/rootstrap/ai-pushgate/commit/e60ae7bd217c5315180f1d4a698ece114b4ec791))
+* update README and add product contract documentation for Pushgate ([#16](https://github.com/rootstrap/ai-pushgate/issues/16)) ([0c76c5e](https://github.com/rootstrap/ai-pushgate/commit/0c76c5e9c7999d335e547c7c43d64629f09f4504))
+
+
+### Bug Fixes
+
+* **node template:** add covered file extensions ([1e3a256](https://github.com/rootstrap/ai-pushgate/commit/1e3a25645febb59e2e8bf78088051a9663914bdd))
+* **pre-push:** clarify category usage in findings response format ([b20acb4](https://github.com/rootstrap/ai-pushgate/commit/b20acb4b279d86fa313cbd55d096670f89d3b33b))
+* **pre-push:** enhance review instructions for better context access ([bd7c3d1](https://github.com/rootstrap/ai-pushgate/commit/bd7c3d1e478cfa55b6c737f780f46096d7304ab0))
+* show more informative logs when Claude CLI is not installed ([5ff8df4](https://github.com/rootstrap/ai-pushgate/commit/5ff8df4b48f10e3b8bef612fc131062d64ba289c))
+* update release configuration ([5ee951e](https://github.com/rootstrap/ai-pushgate/commit/5ee951e354a7b01605719400e2e9e897e4a4bcb2))
+
+
+### Code Refactoring
+
+* enhance install script with structured comments and checks ([99a25be](https://github.com/rootstrap/ai-pushgate/commit/99a25be12c22c1330e1f0e7636e5875541b17e04))
+
 ## [2.2.0](https://github.com/rootstrap/ai-git-hooks/compare/v2.1.2...v2.2.0) (2026-04-08)
 
 

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to ai-git-hooks
+# Contributing to ai-pushgate
 
 Thank you for your interest in contributing! This document covers everything
 you need to know to get changes merged.
@@ -14,11 +14,32 @@ All changes — including from maintainers — must go through a pull request. D
 ## Development setup
 
 ```bash
-git clone git@github.com:rootstrap/ai-git-hooks.git
-cd ai-git-hooks
+git clone git@github.com:rootstrap/ai-pushgate.git
+cd ai-pushgate
+
+# Let Corepack use the pnpm version pinned in package.json
+corepack enable
+pnpm install
+```
+
+Pushgate uses pnpm for its Node config parser, runner tests, and scripts. The
+installed command is a small Node entrypoint, the hook and installer are shell,
+and templates remain YAML.
+
+## Generated runner
+
+`bin/pushgate.mjs` is a checked-in generated artifact for the installer-managed
+runner. Edit the TypeScript source under `src/`, then regenerate the runner:
+
+```bash
+pnpm run bundle
 ```
 
-No dependencies to install — the project is pure shell scripts and YAML.
+The bundle is generated by `scripts/build-runner.mjs` from `src/cli.ts`.
+Large `bin/pushgate.mjs` diffs are expected when dependencies, schemas, or
+runner source change because esbuild inlines runtime helpers and package code.
+Use `pnpm run bundle:analyze` to inspect bundle composition; the generated
+analysis files are written under ignored `dist/` output.
 
 ---
 
@@ -66,30 +87,42 @@ commit as-is and customise from there.
 
 ### Fixing the hook script
 
-`hook/pre-push` has been hardened over many iterations. Before making changes:
+`hook/pre-push` is the thin delegator between Git and the managed Pushgate
+runner. Before making changes:
 
 - Run `bash -n hook/pre-push` to validate syntax before committing
-- Avoid `eval`, heredoc variable expansion, and unquoted variable interpolation
-- File lists must always be passed as arrays, never as interpolated strings
-- Test on both macOS (BSD tools) and Linux (GNU tools) if possible — `sed`,
-  `grep`, and `printf` behave differently between them
+- Keep hook arguments, stdin, and exit codes intact across the runner boundary
+- Keep missing-runner and incompatible-protocol diagnostics actionable
+- Avoid adding policy execution back into the installed hook
 
 ### Fixing the installer
 
 `install.sh` follows the same shell safety rules as the hook. Additionally:
 - It must work when piped through `bash` (`curl ... | bash`)
-- It must not assume any tools beyond `bash`, `curl`, and `git` are available
+- It must not assume any tools beyond `bash`, `curl`, `git`, and `node` are available
 
 ---
 
 ## Testing your changes
 
-There is no automated test suite yet. To test manually:
+Run the automated tests before manual hook or installer checks:
 
 ```bash
+# Install config parser dependencies
+pnpm install
+
+# Typecheck the Node layer, validate config fixtures, and run the hook harness
+# against disposable Git repos and local tool/provider stubs
+pnpm test
+
 # Validate shell syntax
-bash -n hook/pre-push
-bash -n install.sh
+pnpm run check:shell
+
+# Run ShellCheck's error-level static checks when ShellCheck is installed
+pnpm run lint:shell
+
+# Inspect generated runner bundle composition
+pnpm run bundle:analyze
 
 # Test the installer locally (from inside a git repo)
 bash install.sh --template node
@@ -99,15 +132,27 @@ bash install.sh --template node
 git push
 ```
 
+For manual testing against an unpublished runner build without replacing the
+stable managed install for every repo on the machine, point one repository at
+your local build:
+
+```bash
+pnpm run bundle
+git config --local pushgate.runner /absolute/path/to/bin/pushgate.mjs
+git push
+git config --unset --local pushgate.runner
+```
+
 For template changes, install the template into a representative project and
 verify the configured tools run correctly against changed files.
 
 ---
 
 ## Pull request checklist
 
-- [ ] `bash -n hook/pre-push` passes with no output
-- [ ] `bash -n install.sh` passes with no output
+- [ ] `pnpm test` passes
+- [ ] `pnpm run check:shell` passes with no output
+- [ ] `pnpm run lint:shell` passes when ShellCheck is installed
 - [ ] Commit messages follow Conventional Commits
 - [ ] New templates include all keys from an existing template
 - [ ] `README.md` updated if a new template was added
@@ -120,4 +165,4 @@ verify the configured tools run correctly against changed files.
 Releases are fully automated via `release-please`. When your PR is merged to
 `main`, release-please analyses the commit messages and opens a Release PR if
 there is anything releasable. Merging the Release PR creates the GitHub Release
-and git tag automatically — you don't need to do anything manually.
+and git tag automatically — you don't need to do anything manually.