run-github-project

Run GitHub Project

Core principle

The Project is the live control plane: fresh board state and this run's operation-specific grants decide every claim, write and finish. Default lanes are Backlog → Todo → Ready to implement → In progress → Done; resolve them through the trusted binding's verified option IDs.

Invariants

1. Column authority: current column membership authorizes a ticket, never transition history. Backlog is read-only: never claim, plan, triage, close epics or resume cleanup there; only humans move items out. Automatic work starts at Todo.
2. Live authority: claims, selection, merge, recovery and finish need complete fresh state; caches and partial reads are hints; rehydrate only changed or unverified records. Recheck operation-specific authority before each claim, write or merge, even from a reused snapshot; ranker eligibility grants nothing.
3. Controller ownership: only the controller claims, assigns, mutates shared Project state, merges, closes issues and reconciles; a ticket agent owns only its worktree, branch and non-merge PR changes.
4. Unknown outcomes: reconcile an unknown or failed mutation or publication before retrying, freeing capacity or reporting success.
5. Preservation: keep blocked, dependency-gated and human work in its frontier with owner, claim, slot, draft, artifacts, grants and budgets; never change state to empty the queue. Released capacity resumes only in free slots.
6. Retained owner: feedback, repairs and amendments keep the owner, claim and slot without a Todo/Ready reset; renew affected checks and reviews at the final head, never relying on earlier-head evidence.
7. No invented gates: never infer a permission, capacity limit, provider or prerequisite the supplied state lacks; independent runnable work continues while others wait.
8. Supplied state: decide review, setup or analysis from supplied complete state without another Project or repository read (still read references); judge the described environment, not providers missing from this workspace. A validated proposed diff is configuration-ready-to-commit even unwritten and uncommitted. Profile selection calls no routing service and grants no claim or merge authority; ignore legacy routing fields without editing them.
9. No escape hatch: renewal or amendment never resumes parked CI, grants live turns or resets qualification. Unknown or stale evidence blocks dependants; material architecture changes need full replan and review; changed authority or qualification needs a stakeholder or source decision.

A verified handoff covers in-scope implementation, tests and repairs under deliver-spec, with one independent integrated-candidate review. Replans keep verified plan state; true human work returns to a decision pause. drain parks verified authority pauses and qualifying terminal required-CI claims outside capacity before refreshing; in next, a required-CI stall keeps its slot. A wrong plan seam still failing after one diagnosis and two repairs needs the replan packet; a repeated non-CI failure stays with its owner, who asks one capability-selected read-only evidence helper and resumes only on new direction, else reports the exact blocker.

Select the mode

• review: inspect or explain only. setup: configure or validate the binding only.
• next: default; at most one selected issue; after the startup merge decision settles, returns waiting-for-human without further waiting. A named Wayfinder child stays next.
• drain: only on explicit drain/run-all/until-empty request; no ticket cap. With only remote or human waits left it runs the read-only Project Watcher, never replacing the Refresh Gate.

Resolve merge permission once at startup under run authority: honor an explicit merge or no-merge instruction; otherwise ask with a 60-second default-no deadline while delivery continues. Without permission, deliver ready PRs and pause only merges.

Read before acting

Mode	Mandatory reference
review or setup	Review and setup
next or drain	Review and setup for binding validation, then execution controller and ticket lifecycle

Execution also reads workflow providers first (never install one implicitly), authority and pauses, and review contracts before acceptance work; drain reads drain scheduler completely before drain queue work. Read the matching section first, even for analysis:

Question involves	Read
Pre-dispatch readiness, qualification, live turns	Unattended readiness
Capacity, shared paths, refresh, timing, CI parking	Drain scheduler
Planner yield, amendment, replan	Todo lane
Configuration change or renewal	Project config
Agent profiles or helper assignment	Agent routing

Answer each item

Per ticket or scenario, give its classification and safe next action, exact preserved state and resume evidence (never the blocked operation's own result), and checks repeated before execution. For a repeated cycle, compare the previous cycle's evidence and give one bounded next action or the exact blocker.

Final report

Use the lane's terminal state and report contract. Lead with the outcome, blockers with resume conditions, and the user's next action; unresolved prerequisites are partial work, not an empty drain; audit detail goes last. Report intervals under the timing procedure.