Merge pull request #7 from pylon-code/chore/pylon-fork-sync-api

chore(pylon): harden fork synchronization

Author: rynfar

.github/workflows/pylon-upstream-sync.yml

@@ -10,6 +10,7 @@ concurrency:
   cancel-in-progress: false
 
 permissions:
+  actions: read
   contents: write
   issues: write
   pull-requests: read
@@ -30,15 +31,14 @@ jobs:
           ref: pylon
           fetch-depth: 0
 
-      - name: Mirror Prime and open a draft merge pull request
+      - name: Mirror Prime and prepare a review candidate
         id: sync
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PYLON_SYNC_PR_TOKEN: ${{ secrets.PYLON_SYNC_PR_TOKEN }}
         run: scripts/pylon-sync-upstream.sh
 
   verify:
-    name: Verify candidate with trusted fork CI
+    name: Verify candidate ${{ needs.sync.outputs.candidate_sha }} with trusted fork CI
     needs: sync
     if: needs.sync.outputs.candidate_sha != ''
     permissions:

PYLON.md

@@ -11,9 +11,13 @@ This repository is Pylon's long-lived Prime Agent fork. It follows Prime upstrea
 
 While this repository has only one write-capable human, `pylon` requires pull requests, strict hosted checks, conversation resolution, and recorded maintainer approval, but zero GitHub approvals. The protection applies to administrators so direct pushes cannot bypass it. Raise the required approval count when a second eligible reviewer exists.
 
-The daily `Pylon upstream sync` workflow fast-forwards `main`, prepares a clean merge candidate, and runs it through the trusted `pylon` CI definition with no secrets or persisted Git credentials. With a narrowly scoped `PYLON_SYNC_PR_TOKEN`, it opens a draft merge pull request. Without that token, it opens or updates one candidate-ready issue with the exact PR link. A conflict opens or updates one blocker issue and requires a human resolution branch from `pylon`; the workflow never resolves conflicts automatically.
+The daily `Pylon upstream sync` workflow updates `main` through GitHub's fork `merge-upstream` API, verifies that it exactly matches Prime, prepares one deterministic merge candidate, and runs a new candidate through the trusted `pylon` CI definition with no secrets or persisted Git credentials. An unchanged candidate skips duplicate CI only after the Actions API confirms that its stored run and candidate-bound aggregate succeeded. The workflow opens or updates one candidate-ready issue with a prefilled link and the exact draft title, body, label, and branch requirements. A conflict opens or updates one blocker issue and requires a human resolution branch from `pylon`; the workflow never resolves conflicts automatically.
 
-Sync and manual conflict-resolution pull requests must use merge commits so `pylon` retains ancestry from the exact upstream commit. The mirror and candidate branch pushes must use the built-in `GITHUB_TOKEN`: replacing it with a PAT or app token would allow an upstream-owned push workflow to execute when `main` advances. A separate PR-only app token may be used only by `gh pr create`; never expose it to Git credentials or candidate verification.
+`main` must be governed by one active repository ruleset with no bypass actors. That ruleset blocks updates except GitHub fork fetch-and-merge, requires linear history, and forbids force-pushes and deletion. The workflow reads the effective branch rules and registered Prime fork parent before calling `merge-upstream`, then verifies the returned source and exact commit. GitHub may fast-forward the mirror but may not write a divergent merge commit. Maintainers must also audit that the ruleset keeps an empty bypass list because GitHub hides other actors from low-privilege workflow tokens.
+
+GitHub requires this repository to permit squash or rebase merging before `main` can require linear history. Pylon permits squash merging only for that platform prerequisite; sync and manual conflict-resolution pull requests must still use merge commits on `pylon` so the product branch retains ancestry from the exact upstream commit. If Prime starts adding merge commits to its current linear history again, synchronization must stop for a protection-design review. Do not temporarily disable the mirror guard and rerun automation.
+
+Mirror automation must use only the built-in `GITHUB_TOKEN`: it never pushes directly to `main`, has no PAT or app token, and never falls back to a credential that could bypass `main` protections or trigger inherited upstream publication. Candidate branches also use the built-in token and require a human-opened pull request.
 
 ## Upstream overlap decisions