fix(ci): reduce contributor friction in PR gates

Change-Id: I1f4b06c06ca304d98f5a1151aad48f1bf4537cec

Author: heimanba

.github/pull_request_template.md

@@ -36,7 +36,8 @@
 ## Behavior / risk
 
 <!-- Required only when changing provider contracts, config/schema parsing, release/package files, or GitHub workflows.
-State the user-visible behavior or compatibility/security risk. “No user-visible behavior change” is valid for an internal refactor. -->
+State the user-visible behavior or compatibility/security risk. “No user-visible behavior change” is valid for an internal refactor.
+No special commit-message marker or history rewrite is required. -->
 
 ## Validation
 

.github/workflows/ci.yml

@@ -50,73 +50,6 @@ jobs:
           BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
         run: bun scripts/verify.ts full --step "${{ matrix.step }}"
 
-  policy-surface:
-    name: Policy surface
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
-        with:
-          fetch-depth: 0
-      - name: Require [policy] marker when control files change
-        env:
-          BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
-          HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-        run: |
-          set -euo pipefail
-
-          # The control plane: deterministic gates and the rules that govern them.
-          # Editing any of these changes what every other check enforces, so the
-          # change must be explicit — a [policy] marker in the commit range.
-          patterns='
-          .dependency-cruiser.cjs
-          sgconfig.yml
-          biome.json
-          tools/architecture/
-          .githooks/
-          .claude/hooks/
-          .github/workflows/
-          scripts/lint-changed.sh
-          scripts/verify.ts
-          scripts/verify.test.ts
-          scripts/pr-evidence.ts
-          scripts/pr-evidence.test.ts
-          scripts/release/
-          scripts/setup-githooks.sh
-          '
-
-          base="$BASE_SHA"
-          # New branch / first push: no usable base; nothing to diff against.
-          if [ -z "$base" ] || ! git cat-file -e "$base^{commit}" 2>/dev/null; then
-            echo "No base commit to compare against; skipping policy-surface check."
-            exit 0
-          fi
-
-          changed=$(git diff --name-only "$base" "$HEAD_SHA")
-          touched=""
-          for p in $patterns; do
-            hit=$(printf '%s\n' "$changed" | grep -F "$p" || true)
-            if [ -n "$hit" ]; then
-              touched="$touched$hit"$'\n'
-            fi
-          done
-
-          if [ -z "$touched" ]; then
-            echo "No control-plane files changed."
-            exit 0
-          fi
-
-          echo "Control-plane files changed:"
-          printf '%s' "$touched" | sed 's/^/  - /'
-
-          if git log "$base..$HEAD_SHA" --format=%B | grep -qF '[policy]'; then
-            echo "Found [policy] marker in commit range. OK."
-            exit 0
-          fi
-
-          echo "::error::Control-plane files changed without a [policy] marker in any commit message."
-          echo "Add '[policy]' to a commit message to acknowledge changing the verification harness itself."
-          exit 1
-
   maintainer-evidence:
     name: Maintainer evidence
     runs-on: ubuntu-latest
@@ -157,14 +90,13 @@ jobs:
   gate:
     name: Gate
     runs-on: ubuntu-latest
-    needs: [prepare-verification, verify, policy-surface, maintainer-evidence, package-compatibility]
+    needs: [prepare-verification, verify, maintainer-evidence, package-compatibility]
     if: always()
     steps:
       - name: Check results
         run: |
           if [ "${{ needs.prepare-verification.result }}" != "success" ] || \
              [ "${{ needs.verify.result }}" != "success" ] || \
-             [ "${{ needs.policy-surface.result }}" != "success" ] || \
              [ "${{ needs.maintainer-evidence.result }}" != "success" ] || \
              [ "${{ needs.package-compatibility.result }}" != "success" ]; then
             echo "One or more required checks failed."

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Every PR must satisfy:
 2. At least one maintainer approval
 3. No unresolved review comments
 
-We keep the contribution path open: documentation, examples, and ordinary small changes do not need a design document or a special PR label. Changes to provider contracts, configuration/schema parsing, release/package files, or GitHub workflows have a small additional requirement: fill in the **Behavior / risk** and **Validation** sections of the PR description. This lets maintainers review the contract and its evidence before reading an implementation diff.
+We keep the contribution path open: documentation, examples, and ordinary small changes do not need a design document, a special PR label, or a commit-message marker. Changes to provider contracts, configuration/schema parsing, release/package files, GitHub workflows, or verification policy have a small additional requirement: fill in the **Behavior / risk** and **Validation** sections of the PR description. This lets maintainers review the contract and its evidence before reading an implementation diff without asking contributors to rewrite commit history. A generated `bun.lock` change by itself is handled by audit and compatibility checks.
 
 Maintainers should enable the repository settings that make the same policy effective at merge time: require the `Gate` and `Analyze TypeScript` checks, require one approving review, dismiss stale approvals, require approval of the latest push, and require resolved conversations. CODEOWNERS review and a merge queue are intentionally not required for routine contributions at the current project stage.
 

apps/server/tsconfig.json

@@ -2,7 +2,7 @@
 	"extends": "../../tsconfig.base.json",
 	"compilerOptions": {
 		"lib": ["ESNext", "DOM", "DOM.Iterable"],
-		"types": ["node"],
+		"types": ["node", "bun"],
 		"resolveJsonModule": true,
 		"paths": {
 			"@/*": ["./src/*"],

docs/contributing/maintainer-review.md

@@ -17,7 +17,7 @@ OpenAgentPack welcomes exploratory and AI-assisted contributions. The merge bar
 | CLI or SDK behavior | `Gate` | Contract plus a regression test or reproduction |
 | Provider contracts, config/schema, release/package files, workflows | `Gate` plus CodeQL | Behavior/risk and validation evidence; inspect compatibility and security impact |
 
-The PR evidence check deliberately applies only to the third row. It does not require a design document, a linked Issue, or an AI-use declaration.
+The PR evidence check deliberately applies only to the third row. It does not require a design document, a linked Issue, an AI-use declaration, a special commit-message marker, or a history rewrite. A generated `bun.lock` change by itself is covered by audit and compatibility checks rather than the evidence gate.
 
 ## GitHub settings
 

scripts/pr-evidence.test.ts

@@ -3,10 +3,21 @@ import { requiresMaintainerEvidence, validateMaintainerEvidence } from "./pr-evi
 
 describe("pull-request maintainer evidence", () => {
 	test("does not add a merge barrier for ordinary contribution paths", () => {
-		expect(requiresMaintainerEvidence(["README.md", "packages/cli/src/program.ts"])).toBe(false);
+		expect(requiresMaintainerEvidence(["README.md", "packages/cli/src/program.ts", "bun.lock"])).toBe(false);
 		expect(validateMaintainerEvidence("", ["README.md"])).toBeUndefined();
 	});
 
+	test("uses PR evidence instead of commit-message markers for control-plane changes", () => {
+		const files = [".github/workflows/ci.yml", "scripts/verify.ts"];
+		expect(requiresMaintainerEvidence(files)).toBe(true);
+		expect(validateMaintainerEvidence("## Summary\nAdjust CI", files)).toContain("## Behavior / risk");
+	});
+
+	test("treats package manifests, but not the generated lockfile alone, as high risk", () => {
+		expect(requiresMaintainerEvidence(["packages/sdk/package.json"])).toBe(true);
+		expect(requiresMaintainerEvidence(["bun.lock"])).toBe(false);
+	});
+
 	test("asks for behavior and validation evidence on high-risk paths", () => {
 		const files = ["packages/sdk/src/internal/providers/interface.ts"];
 		expect(requiresMaintainerEvidence(files)).toBe(true);

scripts/pr-evidence.ts

@@ -1,9 +1,18 @@
 import { existsSync } from "node:fs";
 
 const highRiskPathPatterns = [
+	// Verification and automation control plane. These changes require explicit
+	// PR evidence, but never a special commit message or history rewrite.
+	/^\.dependency-cruiser\.cjs$/,
+	/^sgconfig\.yml$/,
+	/^biome\.json$/,
+	/^tools\/architecture\//,
+	/^\.githooks\//,
+	/^\.claude\/hooks\//,
 	/^\.github\/workflows\//,
+	/^scripts\/(?:lint-changed\.sh|verify(?:\.test)?\.ts|pr-evidence(?:\.test)?\.ts|setup-githooks\.sh)$/,
 	/^scripts\/release\//,
-	/^(?:package\.json|bun\.lock)$/,
+	/(?:^|\/)package\.json$/,
 	/^packages\/sdk\/src\/internal\/(?:parser\/|types\/(?:config|session)\.ts|providers\/(?:interface|capabilities|registry|base-client)\.ts)/,
 ];