/pr-shepherd-contract

name: pr-shepherd-contract
description: "GitHub adapter binding for the shepherd contract: turn a real pull request into observed events, resolve the responsible actor from commit authorship, and persist the waiting contract under the workspace so a later pass (or process) can resume it."

PR Shepherd Contract (GitHub adapter)

The GitHub binding for the provider-neutral shepherd contract (`src/shepherd_contract.py`). The contract defines WHAT a shepherd task is responsible for and WHICH observed events count; this skill supplies the GitHub-specific half:

• **Observation** — `observe(repo, number)` reads live PR state via the

GitHub CLI (`gh api`) and emits one `ObservedEvent` (merged / closed unmerged / updated).

• **Actor resolution** — `resolve_actor(repo, number)` uses the last

non-merge commit's author email (`git.commit_author_email`), not the account login, because several actors can push under one login.

• **Persistence** — `save(task_id, scope, state)` / `load(task_id)` /

`resume(task_id)` keep the durable contract record under `<workspace>/state/shepherd/`, create-or-advance only (never rebind), so a different process can pick the objective up later.

Usage

Import from the skill's scripts directory (the module bootstraps `src/` onto `sys.path` itself):

import sys, pathlib
sys.path.insert(0, str(repo_root / "skills" / "pr-shepherd-contract" / "scripts"))
import shepherd_github as g

scope = g.scope_for("owner/repo", 123, g.resolve_actor("owner/repo", 123))
g.save("task-abc", scope, "waiting", "shepherding PR 123")
# ... later, any process:
state, why = g.resume("task-abc")

Tests: `tests/shepherd-github-durability.test.py`, `tests/shepherd-github-integrity.test.py` (contract policy itself: `tests/shepherd-contract-admission.test.py`).