feat: implement changed-file path policy and resolver for Git diffs

README.md

@@ -109,7 +109,7 @@ ai:
       model: claude-sonnet-4-20250514
 
 review:
-  target_branch: main       # diff base: git diff <target_branch>...HEAD
+  target_branch: main       # local ref for git diff <target_branch>...HEAD
   context_lines: 10         # surrounding context lines included in the diff
   max_lines_for_full_file: 300  # below this threshold, full file contents are sent
                                 # instead of just the diff for richer context
@@ -125,14 +125,14 @@ tools:
     command: ["bundle", "exec", "brakeman", "--no-pager", "--quiet"]
     # no {changed_files} → runs on the whole project
 
-# Files and patterns excluded from tool checks and AI review
+# Gitignore-like repo-relative paths excluded from tool checks and AI review
 ignore_paths:
   - "*.lock"
   - "dist/**"
   - "coverage/**"
 ```
 
-V2 configs must declare `version: 2`. Core config sections are strict, provider-specific config belongs below `ai.providers.<provider>`, and tool commands are argv arrays rather than shell strings. Reviewer focus and default finding-category instructions live with the built-in review prompt rather than the v2 config surface. See `docs/v2-config-schema.md` for the schema boundary and migration behavior for `.push-review.yml`.
+V2 configs must declare `version: 2`. Core config sections are strict, provider-specific config belongs below `ai.providers.<provider>`, and tool commands are argv arrays rather than shell strings. Reviewer focus and default finding-category instructions live with the built-in review prompt rather than the v2 config surface. See `docs/v2-config-schema.md` for the schema boundary, changed-file policy, and migration behavior for `.push-review.yml`.
 
 ## Available templates
 

docs/product-contract-plan.md

@@ -77,8 +77,8 @@ The initial installation path is installer-first: `install.sh` installs the Push
 
 ### Local Checks
 
-- Define the base-ref algorithm when the configured target branch is absent locally, a push creates a new branch, or a remote ref differs from local history.
-- Freeze changed-file semantics for deleted files, renames, binary files, generated files, ignored paths, extension filters, and filenames with whitespace.
+- The changed-file resolver uses the locally resolvable configured target branch and fails explicitly when Git cannot use that ref or find its diff base with `HEAD`; it does not auto-fetch or silently choose a remote or push-range fallback.
+- Keep normalized changed-file semantics shared for deleted files, renames, binary files, ignored paths, extension filters, and filenames with whitespace as deterministic and AI consumers land.
 - Decide check mode defaults and failure handling for missing commands, timeouts, warnings, fail-fast, and checks that must run on the whole repo.
 - Define which local blocking checks must have a CI mirror and how local-only exceptions are recorded.
 
@@ -98,7 +98,7 @@ The initial installation path is installer-first: `install.sh` installs the Push
 
 ### Support And Verification
 
-- Freeze supported platforms and shells before choosing parser, timeout, path glob, and packaging implementations.
+- The initial changed-file path-policy layer targets macOS and Linux; Windows and Git Bash support remains a deliberate support boundary for later parser, timeout, path glob, and packaging decisions.
 - Build a test harness that creates temporary Git repos and stubs checks and AI providers before moving behavior out of the existing Bash hook.
 - Decide migration and release messaging for old repository names, old config files, old hook output prefixes, and existing install URLs.
 

docs/v2-config-schema.md

@@ -65,6 +65,25 @@ tools:
     command: ["npx", "prettier", "--check", "{changed_files}"]
 ```
 
+## Changed-File Policy
+
+The changed-file path policy resolves `review.target_branch` locally and uses
+the documented `<target_branch>...HEAD` Git diff range. If that ref is missing
+or Git cannot find a merge base with `HEAD`, Pushgate fails with an explicit
+diagnostic instead of fetching, guessing a remote variant, or switching to a
+different history range.
+
+`ignore_paths` uses gitignore-like rules against Git's repo-relative paths.
+Patterns such as `*.lock` match basenames across the changed tree, while
+directory rules such as `dist/**` remove that generated subtree before
+deterministic tools or AI consume the shared changed-file list. Tool
+`extensions` are suffix filters over the remaining current paths; deleted files
+remain in normalized changed-file metadata but are not live argv paths for
+later changed-file tool commands.
+
+The initial path-policy implementation targets macOS and Linux behavior.
+Windows and Git Bash path support remain explicit follow-up scope.
+
 ## Review Prompt
 
 Legacy `.push-review.yml` stored reviewer `focus`, `blocking_categories`, and

package.json

@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
+    "ignore": "^7.0.5",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
@@ -26,6 +27,10 @@
     "./config": {
       "types": "./dist/config/index.d.ts",
       "default": "./dist/config/index.js"
+    },
+    "./path-policy": {
+      "types": "./dist/path-policy/index.d.ts",
+      "default": "./dist/path-policy/index.js"
     }
   }
 }

schemas/pushgate-config-v2.schema.json

@@ -26,7 +26,7 @@
       "$ref": "#/definitions/ai"
     },
     "ignore_paths": {
-      "description": "Glob-like changed-file paths omitted by later Pushgate layers.",
+      "description": "Gitignore-like repo-relative changed-file paths omitted by later Pushgate layers.",
       "type": "array",
       "default": [],
       "items": {