feat: pre-merge infra validation hook (Phase 17a)

forgejo_admin commented

2026-03-17 03:59:22 +00:00

Contributor

Lineage

plan-pal-e-agency → Phase 17 → Phase 17a (pre-merge infra validation gate)

Repo

forgejo_admin/claude-custom

User Story

As the platform operator
I want a PreToolUse hook that blocks merging infra PRs without validation evidence
So that infrastructure changes are never merged without plan/kustomize output, reducing Change Failure Rate

Context

Currently no pre-merge validation for infrastructure changes. Kustomize overlays and terraform changes are only tested after merge, creating CFR risk. The sop-platform-tf-changes SOP documents the desired validation patterns but enforcement is manual.

This hook runs on mcp__forgejo__merge_approved_pr — same event as the existing block-mcp-merge.sh but a separate check. It only fires for infra repos (pal-e-platform, pal-e-services, pal-e-deployments).

File Targets

Files to create:

hooks/check-infra-validation.sh — the PreToolUse hook script

Files to modify:

settings.json — register the new hook under the PreToolUse > mcp__forgejo__merge_approved_pr matcher

Files NOT to touch:

hooks/block-mcp-merge.sh — existing merge gate, separate concern
Any agent definition files

Acceptance Criteria

hooks/check-infra-validation.sh exists and is executable
Hook is registered in settings.json under PreToolUse with matcher mcp__forgejo__merge_approved_pr
For non-infra repos: hook exits 0 (pass through)
For pal-e-platform: checks Woodpecker CI status — pipeline must have passed (green)
For pal-e-services: checks PR body or comments for tofu plan or Plan: evidence
For pal-e-deployments: checks PR body or comments for kubectl kustomize or kustomize build evidence
If no evidence found: exits 2 with clear message explaining what's needed and referencing sop-platform-tf-changes
Hook reads repo owner/name from stdin JSON (the merge tool call parameters)

Test Expectations

Manual: Run hook with non-infra repo JSON → exit 0
Manual: Run hook with pal-e-services repo JSON + PR body containing "tofu plan" → exit 0
Manual: Run hook with pal-e-services repo JSON + PR body without evidence → exit 2
Run command: bash -n hooks/check-infra-validation.sh (syntax check)

Constraints

Clone to /tmp/claude-custom-{branch} — never work in ~/claude-custom directly
Use Forgejo API with basic auth sourced from ~/secrets/pal-e-services/forgejo.env (same pattern as hooks/forgejo-helper.sh)
Use Woodpecker API for CI status checks — source creds from ~/secrets/pal-e-services/woodpecker.env if it exists, otherwise from env vars
The hook receives stdin JSON from Claude Code's PreToolUse event — parse with jq
Do NOT access pal-e-docs
Keep the script self-contained — no external dependencies beyond jq, curl, bash

Checklist

PR opened
Tests pass (syntax check)
No unrelated changes

project-pal-e-agency — project this affects
todo-pre-merge-infra-validation — full spec with pseudocode and evidence patterns

### Lineage `plan-pal-e-agency` → Phase 17 → Phase 17a (pre-merge infra validation gate) ### Repo `forgejo_admin/claude-custom` ### User Story As the platform operator I want a PreToolUse hook that blocks merging infra PRs without validation evidence So that infrastructure changes are never merged without plan/kustomize output, reducing Change Failure Rate ### Context Currently no pre-merge validation for infrastructure changes. Kustomize overlays and terraform changes are only tested after merge, creating CFR risk. The `sop-platform-tf-changes` SOP documents the desired validation patterns but enforcement is manual. This hook runs on `mcp__forgejo__merge_approved_pr` — same event as the existing `block-mcp-merge.sh` but a separate check. It only fires for infra repos (pal-e-platform, pal-e-services, pal-e-deployments). ### File Targets Files to create: - `hooks/check-infra-validation.sh` — the PreToolUse hook script Files to modify: - `settings.json` — register the new hook under the PreToolUse > `mcp__forgejo__merge_approved_pr` matcher Files NOT to touch: - `hooks/block-mcp-merge.sh` — existing merge gate, separate concern - Any agent definition files ### Acceptance Criteria - [ ] `hooks/check-infra-validation.sh` exists and is executable - [ ] Hook is registered in `settings.json` under PreToolUse with matcher `mcp__forgejo__merge_approved_pr` - [ ] For non-infra repos: hook exits 0 (pass through) - [ ] For `pal-e-platform`: checks Woodpecker CI status — pipeline must have passed (green) - [ ] For `pal-e-services`: checks PR body or comments for `tofu plan` or `Plan:` evidence - [ ] For `pal-e-deployments`: checks PR body or comments for `kubectl kustomize` or `kustomize build` evidence - [ ] If no evidence found: exits 2 with clear message explaining what's needed and referencing `sop-platform-tf-changes` - [ ] Hook reads repo owner/name from stdin JSON (the merge tool call parameters) ### Test Expectations - [ ] Manual: Run hook with non-infra repo JSON → exit 0 - [ ] Manual: Run hook with pal-e-services repo JSON + PR body containing "tofu plan" → exit 0 - [ ] Manual: Run hook with pal-e-services repo JSON + PR body without evidence → exit 2 - Run command: `bash -n hooks/check-infra-validation.sh` (syntax check) ### Constraints - Clone to `/tmp/claude-custom-{branch}` — never work in `~/claude-custom` directly - Use Forgejo API with basic auth sourced from `~/secrets/pal-e-services/forgejo.env` (same pattern as `hooks/forgejo-helper.sh`) - Use Woodpecker API for CI status checks — source creds from `~/secrets/pal-e-services/woodpecker.env` if it exists, otherwise from env vars - The hook receives stdin JSON from Claude Code's PreToolUse event — parse with `jq` - Do NOT access pal-e-docs - Keep the script self-contained — no external dependencies beyond jq, curl, bash ### Checklist - [ ] PR opened - [ ] Tests pass (syntax check) - [ ] No unrelated changes ### Related - `project-pal-e-agency` — project this affects - `todo-pre-merge-infra-validation` — full spec with pseudocode and evidence patterns