github-sync

GitHub Sync

Define one bounded synchronization between local Runx state and a GitHub repository. The skill makes direction, resource set, filters, content identity, scope, cursor, and authority posture explicit before the selected GitHub transport is allowed to read or mutate GitHub.

The default github-sync runner performs the requested pull or push. plan is the explicit no-effect runner; pull and push remain explicit execution lanes for compatible callers. Pulls are bounded reads. A push carries one to eight typed mutations under the admitted repository grant and returns an individual status, sync reference, and mutation digest for every item. It closes only on independent GitHub readback for every applied item. A partial or unknown item is deferred for reconciliation and is never silently retried. No GitHub token enters this package.

Composes

• data-store#append_event
• data-store#read_projection

When to use it

Use github-sync when an operator needs a reproducible pull or push contract for issues, pull requests, threads, or a mixed batch—especially when cursor state must survive across runs. Use plan only when the requested outcome is a plan. Use pull for an explicitly selected read lane. Use push for one already-decided issue, pull-request, or thread mutation. Batches are bounded and best-effort, not atomic: if one item fails, the result identifies each item and the operator must reconcile before retrying. Use issue-triage to decide what an issue means and issue-to-pr to govern an implementation lane.

Do not use a plan as evidence that remote state was read or changed. Only the native runx.provider.operation.v1 result from pull or push is provider evidence. Do not silently turn a denied push into a pull.

How it works

1. Validate the exact owner/name repository, direction, resource kind, bounded filters, maximum result count, and requested scope.
2. A pull plan requires read scope and records the exact resources a provider may fetch.
3. A push plan requires write scope and one to eight typed mutations. It rejects unknown fields and oversized content, then returns ready_for_execution; planning itself does not grant provider authority.
4. Optional plan_and_append_cursor composes the canonical data-store skill to append the bounded plan and read the projection back. That proves local cursor persistence, not GitHub synchronization; this package does not own a second cursor database or storage adapter.
5. The default runner selects the same bounded read or write path from the validated direction. pull executes the plan with repo.read. push hashes the exact mutation set with the native digest tool, executes it under the admitted repo.write scope, verifies the returned digest, and reads the resource back. Both runners use the native provider lane.