Skip to main content

Github Stack

@mgreten/github-stackv2026.11.10.1· MIT· 11d agoBEHAVIORS
01README

Composition lifecycle for a GitHub native multi-PR stack (gh stack) — validate a declared linear plan, finalize one-commit units, cascade restacks, pin a composed head, and submit gated, idempotent, ordered draft PRs linked as one GitHub stack. Non-interactive only.

02Behaviors1
@mgreten/github-stackv2026.11.10.1github_stack.ts
fn validateStackPlan()
Validate a declared multi-PR stack plan and persist it as the stack-plan-<stack> resource: enforces a strict linear chain via validateStackShape (base relations are explicit fields, never inferred) AND a complete, non-overlapping acceptance-criterion partition (every criterion maps to exactly one unit). Throws-and-writes-nothing on any inferred/ambiguous/cyclic/gapped/duplicate ordering or a criterion assigned to two units or to none; a degenerate one-unit plan is legal and matches the single-PR
fn finalizeStackUnitCommit(index: number, expectedBranch: string, baseBranch: string)
Finalize one stack unit's commit: reuses the single-commit invariant PER UNIT — asserts the worktree is clean, HEAD^ === unitBaseSha (the unit's declared parent head, or the repo base for unit 0), and exactly one commit ahead (git rev-list --count unitBaseSha..HEAD === 1) — then persists a per-unit stack-unit-<stack>-<index> evidence record pinned to the unit's base and head SHA. Fail-closed on a multi-commit unit (must be re-scoped into two units) or a unit whose parent SHA differs from its dec
ArgumentTypeDescription
indexnumber
expectedBranchstring
baseBranchstring
fn restackAbove(patchedIndex: number)
Restack every unit above a patched unit: after a patch to unit k rewrites its head SHA, rebases each unit k+1..n onto its (new) parent head via `git rebase --onto` (independent of any stack tool), asserts each restacked unit is STILL exactly one commit ahead of its new parent and the chain stays linear, recomputes each unit's head SHA, and records a stack-restack-<stack> audit trail of old->new SHA per unit, marking unit k and every restacked unit stale so their evidence is regenerated. The casc
ArgumentTypeDescription
patchedIndexnumber
fn validateComposedHead(unitTipShas: array)
Validate that the whole stack works as a whole: asserts the live stack is linear and each unit's actual parent matches the DECLARED plan baseUnit (parentage read from git, compared to the plan — never a stack tool's view), computes the composed head = the topmost unit's tip, asserts the supplied unitTipShas equals the restacked reality in order (rejecting any mixed/stale SHA), and persists a composed-head-validation-<stack> artifact pinning composedHeadSha AND the ordered unitTipShas. A degenera
ArgumentTypeDescription
unitTipShasarray
fn submitStack(baseBranch?: string, unitTipShas: array)
Submit a validated stack as gated, idempotent, ordered draft PRs on GitHub's native stacks: bottom-up per unit, with the parent read from the DECLARED plan (never inferred), checks `gh pr list --head <branch>` ground truth — if a conforming OPEN DRAFT PR already exists at the unit's expected head+base it is recorded as reused (no push, no duplicate), else pushes the exact validated tip (`git push --force-with-lease` pinned to the observed remote branch SHA) and opens `gh pr create --draft --base
ArgumentTypeDescription
baseBranch?string
unitTipShasarray

Resources

stackPlan(90d)— A declared multi-PR stack plan: an ordered linear chain of units each with an explicit baseUnit (never inferred), a branch, a complete non-overlapping acceptance-criterion partition, and the repo base branch; keyed by stack id; a one-unit plan degenerates to the single-PR flow
stackUnitEvidence(90d)— Per-unit commit evidence for one stack unit: pinned to the unit's base and head SHA, asserting exactly one commit ahead of its declared parent; keyed by stack id and unit index; stale:true marks evidence a restack cascade invalidated
stackRestack(90d)— The restack audit trail after a patch to a lower unit forced a cascade: old->new SHA per restacked unit and which units were marked stale for regeneration; keyed by stack id
composedHeadValidation(90d)— The composed-head validation proving the whole stack works as a whole: the composed head SHA and the ordered per-unit tip SHAs, with live parentage asserted against the DECLARED plan; rejects any mixed/stale SHA; keyed by stack id
stackDraftPr(90d)— One submitted-or-reused draft PR in a stack: pinned to the unit's commitSha/branch/baseBranch/prNumber/prUrl; reused:true means a conforming open draft PR already existed and was not re-submitted; keyed by stack id and unit index
stackDraftPrs(90d)— The composed ordered list of all stack draft PRs plus the collapse-guard assertion (declaredUnitCount === submittedPrCount); keyed by stack id
03Stats
A
100 / 100
Downloads
2
Archive size
21.1 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
04Platforms
05Labels