ci(spec-sync): use fine-grained PAT (SPEC_SYNC_TOKEN) instead of a GitHub App

Org-owned App creation needs org-owner permission; a repo-scoped fine-grained PAT
(Contents+PRs RW) is the self-serve workaround and still satisfies the anti-recursion
requirement (not GITHUB_TOKEN, so gate workflows fire). All three writes — checkout,
claude-code-action, gh pr create — use the same token. Swappable for an org App later.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yzld2002

.github/workflows/spec-sync.yml

@@ -15,16 +15,12 @@ jobs:
     env:
       V1_SPEC_URL: https://api.va.staging.landing.ai/v1/ade/openapi.json  # staging drives the loop
     steps:
-      - name: Mint GitHub App token
-        id: app-token
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.SPEC_SYNC_APP_ID }}
-          private-key: ${{ secrets.SPEC_SYNC_APP_PRIVATE_KEY }}
-
       - uses: actions/checkout@v6
         with:
-          token: ${{ steps.app-token.outputs.token }}
+          # SPEC_SYNC_TOKEN is a fine-grained PAT (Contents: RW, Pull requests: RW)
+          # scoped to this repo. It must NOT be the default GITHUB_TOKEN: pushes/PRs
+          # authored by GITHUB_TOKEN do not trigger the gate workflows (anti-recursion).
+          token: ${{ secrets.SPEC_SYNC_TOKEN }}
           fetch-depth: 0     # tags needed for surface-lock baseline
 
       - name: Install Rye
@@ -76,7 +72,7 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          github_token: ${{ steps.app-token.outputs.token }}
+          github_token: ${{ secrets.SPEC_SYNC_TOKEN }}
           prompt: |
             The previous commit updated specs/v1-ade.json and regenerated reference
             models in specs/_generated/v1_models.py. Update the SDK to match the spec
@@ -93,7 +89,7 @@ jobs:
       - name: Open sync PR
         if: steps.drift.outputs.code == '10'
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.SPEC_SYNC_TOKEN }}
         run: |
           gh pr create \
             --base main \

CONTRIBUTING.md

@@ -147,10 +147,13 @@ Every spec-sync PR (and any PR to `main`) must pass `.github/workflows/pr-gates.
 
 Spec-sync PRs are AI-drafted and **require human review** before merge.
 
-**Secrets required:** `SPEC_SYNC_APP_ID` + `SPEC_SYNC_APP_PRIVATE_KEY` (a GitHub App with
-`contents: write` and `pull-requests: write` — needed because commits pushed with the default
-`GITHUB_TOKEN` do not trigger the gate workflows), `ANTHROPIC_API_KEY`, and
-`LANDINGAI_ADE_STAGING_APIKEY`.
+**Secrets required:** `SPEC_SYNC_TOKEN` (a fine-grained PAT scoped to this repo with
+`Contents: Read and write` and `Pull requests: Read and write`), `ANTHROPIC_API_KEY`, and
+`LANDINGAI_ADE_STAGING_APIKEY`. `SPEC_SYNC_TOKEN` must **not** be the default `GITHUB_TOKEN`:
+pushes and PRs authored by `GITHUB_TOKEN` do not trigger the gate workflows (GitHub
+anti-recursion), so the gates would never run on the sync PR. A GitHub App installation token
+(org-owned) is the cleaner long-term choice and can replace the PAT without other workflow
+changes.
 
 **V2:** once the aide gateway serves its curated spec unauthenticated, add `specs/v2-aide.json` and
 its URL as a second drift-check in the workflow; the two-phase machinery is unchanged.