vouchington-tooling 2.0.2 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/manifest.json +15 -202
- package/skills/organize-github-issues/SKILL.md +20 -3
- package/skills/pr-description/SKILL.md +9 -65
- package/skills/retrospective/SKILL.md +16 -1
- package/skills/retrospective-distill/SKILL.md +1 -1
- package/skills/retrospective-distill/references/issue-body.md +6 -1
- package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
- package/skills/triage-loop/SKILL.md +111 -34
- package/skills/triage-prs/SKILL.md +26 -28
- package/skills/triage-prs/references/feedback.md +14 -2
- package/skills/triage-prs/references/rubric.md +4 -4
- package/skills/triage-sweep/SKILL.md +26 -23
- package/skills/agent-workflow/SKILL.md +0 -72
- package/skills/agent-workflow/references/evidence-sweep.md +0 -12
- package/skills/agent-workflow/references/four-refs.md +0 -74
- package/skills/agent-workflow/references/implementation-and-review.md +0 -4
- package/skills/agent-workflow/references/implementation.md +0 -20
- package/skills/agent-workflow/references/review-response.md +0 -49
- package/skills/agent-workflow/references/review.md +0 -10
- package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
- package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
- package/skills/bounded-iteration/SKILL.md +0 -92
- package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
- package/skills/dependabot/SKILL.md +0 -117
- package/skills/dotnet-test-authoring/SKILL.md +0 -24
- package/skills/git-commit-checklist/SKILL.md +0 -29
- package/skills/github-actions-authoring/SKILL.md +0 -63
- package/skills/github-actions-checklist/SKILL.md +0 -118
- package/skills/github-issue/SKILL.md +0 -121
- package/skills/glide-mq/SKILL.md +0 -52
- package/skills/glide-mq/references/lease-patterns.md +0 -44
- package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
- package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
- package/skills/npm-publishing/SKILL.md +0 -72
- package/skills/package-json-checklist/SKILL.md +0 -31
- package/skills/planning/SKILL.md +0 -37
- package/skills/planning/references/impact-discovery.md +0 -11
- package/skills/playwright-authoring/SKILL.md +0 -23
- package/skills/playwright-authoring/references/browser-reliability.md +0 -9
- package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
- package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
- package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
- package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
- package/skills/postgres-schema-design/SKILL.md +0 -31
- package/skills/postgres-schema-design/references/naming.md +0 -34
- package/skills/postgres-schema-design/references/relations.md +0 -66
- package/skills/postgres-schema-design/references/table-shapes.md +0 -78
- package/skills/pr-description/references/examples.md +0 -189
- package/skills/review-ci-logs/SKILL.md +0 -44
- package/skills/revisit-followups/SKILL.md +0 -47
- package/skills/stacked-prs/SKILL.md +0 -98
- package/skills/stacked-prs/references/drain.md +0 -177
- package/skills/stacked-prs/references/gh-stack.md +0 -147
- package/skills/static-analysis-checklist/SKILL.md +0 -32
- package/skills/storybook-authoring/SKILL.md +0 -22
- package/skills/storybook-authoring/references/component-coverage.md +0 -9
- package/skills/swift-test-authoring/SKILL.md +0 -23
- package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
- package/skills/test-authoring/SKILL.md +0 -27
- package/skills/test-authoring/references/core-practice.md +0 -16
- package/skills/test-authoring/references/dependency-boundaries.md +0 -38
- package/skills/test-authoring/references/tautological-tests.md +0 -47
- package/skills/triage-loop/references/shepherd.md +0 -64
- package/skills/vitest-test-authoring/SKILL.md +0 -22
- package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
|
@@ -1,177 +0,0 @@
|
|
|
1
|
-
# Drain and keep track
|
|
2
|
-
|
|
3
|
-
Shepherding a layer to ready and merging are different acts. The first covers every pull request
|
|
4
|
-
the worker owns in the stack at once. The second lands the whole stack in one command once every
|
|
5
|
-
layer is ready, and it is never the agent's own decision.
|
|
6
|
-
|
|
7
|
-
## Establish scope
|
|
8
|
-
|
|
9
|
-
1. Resolve the stack from `pulls/<any-layer>.stack`, and record whether the field was present. A
|
|
10
|
-
stack object supplies its number; an explicit `null` means no registered stack. A missing
|
|
11
|
-
preview field: query `stacks?pull_request=<N>`, where one result is the stack and zero means
|
|
12
|
-
unstacked. Do not treat an empty `.stack.number` alone as proof
|
|
13
|
-
that a pull request is unstacked.
|
|
14
|
-
2. Read topology from `repos/{owner}/{repo}/stacks/<n>`, ordered bottom to top. A
|
|
15
|
-
`closed && merged_at == null` layer below an open one means the stack is broken. Report it to
|
|
16
|
-
the human, and never merge across it.
|
|
17
|
-
3. Partition by ownership, using that topology read plus each member's body from `pulls/<N>` (the
|
|
18
|
-
stack response has no bodies). Shepherd only owned pull requests. Never
|
|
19
|
-
poll, fix, rebase, or push the others, but list them in every report. Owned means this session
|
|
20
|
-
opened the pull request, or a human named it in this session. After the owning worker posts
|
|
21
|
-
`/shepherd` on the top pull request, the triage loop's shepherd owns the stack and the worker
|
|
22
|
-
stops acting on it.
|
|
23
|
-
- The opened-by-me half is a durable remote fact when the repository's pull request description
|
|
24
|
-
tool stamps each body with the authoring harness and session id. Compare the stamp with the
|
|
25
|
-
current session id.
|
|
26
|
-
- The named-by-a-human half is conversational and cannot be recovered remotely. That is
|
|
27
|
-
acceptable, because the human can restate it after a compaction.
|
|
28
|
-
- Degrade explicitly. A body without a matching stamp, or with a stamp naming no session id,
|
|
29
|
-
is not owned. Report it as "ownership unverifiable" and never poll it.
|
|
30
|
-
- A parent may assign its stack to one worker by listing the pull request numbers and the
|
|
31
|
-
session id stamped on them. The worker treats that list as assigned and still refuses any
|
|
32
|
-
layer outside it.
|
|
33
|
-
|
|
34
|
-
## Shepherd the owned layers
|
|
35
|
-
|
|
36
|
-
Run one stack shepherd poll for the assigned stack, and follow its printed instructions.
|
|
37
|
-
|
|
38
|
-
- A shepherd's own "owned" mark can mean only that the author login equals the authenticated
|
|
39
|
-
viewer. Several sessions often share one account, so filter every printed row against the
|
|
40
|
-
ownership partition above before acting. Never start a per-pull-request session, fix, or push
|
|
41
|
-
for a row outside it, even when the shepherd marks it owned.
|
|
42
|
-
- Apply code fixes, rebases, pushes, and review mutations to owned layers only. Report work
|
|
43
|
-
surfaced on an unowned layer to the human.
|
|
44
|
-
- Fix on the owning layer. Commit there, rebase the layers above it (`gh stack rebase --upstack`),
|
|
45
|
-
`gh stack sync` when there are no local stack commits, `gh stack push` once, then rerun the
|
|
46
|
-
shepherd.
|
|
47
|
-
`rebase --upstack` and `push` act through the top of the stack. When an unowned layer sits above
|
|
48
|
-
an owned one, stop at that layer: do not rebase or push it, and hand the remaining rebase and
|
|
49
|
-
push to its owner.
|
|
50
|
-
- Start the shepherd with the first pull request. While the poll is in a pure wait and the
|
|
51
|
-
worktree is clean, commit the next layer once the lower layer is in decent shape. On a
|
|
52
|
-
triage result, finish it on the owning layer before more upper edits. A ready-delay schedules
|
|
53
|
-
the rerun: continue owned work on a later layer, and do not invent unrelated work.
|
|
54
|
-
- Never run a printed merge command unless the human's approval covers that layer and every open
|
|
55
|
-
layer below it, and the checks below pass. `gh stack merge <pr>` lands that pull request and
|
|
56
|
-
every layer below it.
|
|
57
|
-
- Mutating git does not parallelize. Stop the poll before a rebase, sync, or push in the stack's
|
|
58
|
-
shared worktree, because other layers' branches can be rewritten underneath it. Discard a poll
|
|
59
|
-
result that was in flight across the mutation, and start the poll again after the push lands.
|
|
60
|
-
Run at most one git mutation at a time.
|
|
61
|
-
|
|
62
|
-
### Upper-only fast-forward
|
|
63
|
-
|
|
64
|
-
A queued lower layer, or any lower layer that must not be rewritten, does not stop an upper-only
|
|
65
|
-
fast-forward, or upper review and CI work that does not write git.
|
|
66
|
-
|
|
67
|
-
- Before that push, read the forge and capture the parent head, the parent base, the upper remote
|
|
68
|
-
head, and the stack order. Read all four again immediately before pushing.
|
|
69
|
-
- Push only when all four still match, the local upper commit fast-forwards that remote head, and
|
|
70
|
-
it still contains the parent. If anything differs, or the lower layer merges or leaves the queue
|
|
71
|
-
meanwhile, stop and read the forge again. Never push from a stale capture.
|
|
72
|
-
- Do not amend, force-push, `gh stack sync`, or `gh stack rebase` a queued parent: each rewrites
|
|
73
|
-
it. When the lower layer changes, re-read topology before branch work that depends on the new
|
|
74
|
-
parent.
|
|
75
|
-
|
|
76
|
-
### Escalations persist to the pull request
|
|
77
|
-
|
|
78
|
-
When a layer needs a human, because it is ready and waiting on a merge decision or genuinely
|
|
79
|
-
blocked:
|
|
80
|
-
|
|
81
|
-
- Apply the repository's needs-human label and post one comment per escalation event, not per
|
|
82
|
-
poll, with the layer's position and what it needs.
|
|
83
|
-
- When a layer re-escalates, minimize the superseded comment (GraphQL `minimizeComment`,
|
|
84
|
-
`classifier: OUTDATED`). Clear the label once the layer no longer needs a human.
|
|
85
|
-
- A relayed merge command is for visibility only. The shepherd picks its target from ready
|
|
86
|
-
results alone and does not know what the human approved.
|
|
87
|
-
|
|
88
|
-
## Report
|
|
89
|
-
|
|
90
|
-
When the owned set settles, present the stack bottom to top: each layer's number, owner, state,
|
|
91
|
-
and whether it is ready or blocked and why. Never leave a ready bottom layer under a blocked upper
|
|
92
|
-
layer without saying so.
|
|
93
|
-
|
|
94
|
-
## Merge the whole stack
|
|
95
|
-
|
|
96
|
-
Prefer one merge of the whole stack: when every open layer is ready and inside the approval, the
|
|
97
|
-
target is the top layer, and one command lands it and every layer below it. A shepherd that prints
|
|
98
|
-
a merge for a lower layer does not change that; when the whole stack is ready, target the top.
|
|
99
|
-
|
|
100
|
-
Drain bottom-up only when the layers above will clearly take longer than the ready lower layers:
|
|
101
|
-
an open requested change or `TRIAGE`, a pending human review, a blocker, or CI far longer than
|
|
102
|
-
the wait so far. A layer a poll or a ready-delay away is not a reason. Then the target is the
|
|
103
|
-
highest layer of the ready, approved run from the bottom, still one command, and the report says
|
|
104
|
-
why the upper layers were left.
|
|
105
|
-
|
|
106
|
-
Merge only on explicit human approval. The approval names what it covers: one layer, a range, or
|
|
107
|
-
the whole stack. Approving the whole stack also covers a bottom-up drain under the rule above. It
|
|
108
|
-
does not cover a layer added after the approval. Ask before merging any layer outside it.
|
|
109
|
-
|
|
110
|
-
Immediately before the approved merge, run these checks in order:
|
|
111
|
-
|
|
112
|
-
1. `gh api repos/{owner}/{repo}/stacks/<target>` must return 404. `gh stack merge` resolves a bare
|
|
113
|
-
number as a stack number first, then a pull request number. A 200 response means `--yes` would
|
|
114
|
-
merge every layer of that stack. Stop and ask.
|
|
115
|
-
2. Re-read topology. Confirm every layer from the bottom-most open layer up to the target is open,
|
|
116
|
-
ready, and inside the approval, with nothing broken below. Re-read every layer above the
|
|
117
|
-
target too. If those layers are all ready now and the approval covers them, retarget to the
|
|
118
|
-
highest of them and restart these checks from step 1 for the new target. Never retarget past
|
|
119
|
-
the approval; report the ready layers above it and ask.
|
|
120
|
-
3. For every layer being merged, capture `pulls/<N>.head.sha` before the final poll and after it.
|
|
121
|
-
They must match. A mismatch means a push landed inside the evaluation window: discard the
|
|
122
|
-
verdict and poll again.
|
|
123
|
-
4. `gh stack merge <target> --yes` with the repository's merge strategy. It lands the target and
|
|
124
|
-
every open layer below it.
|
|
125
|
-
5. Do not `gh stack sync` here. Return to step 2 of [Establish scope](#establish-scope) and
|
|
126
|
-
re-read topology remotely: rebasing right after a merge can replay already-landed commits from
|
|
127
|
-
a stale local base ref. After a bottom-up drain, keep shepherding the layers above and merge
|
|
128
|
-
the rest the same way, preferring the whole remainder at once. Before any local edit, rebase, or push
|
|
129
|
-
on a remaining layer, rerun the fetch and ahead/behind check in
|
|
130
|
-
[Import a stack](gh-stack.md#import-a-stack-before-acting-on-it): GitHub rebases the next
|
|
131
|
-
layer remotely, so local upper branches are stale until fast-forwarded. The drain is complete when no unmerged owned layer remains.
|
|
132
|
-
|
|
133
|
-
The window between the last head read and the merge cannot be closed, because `gh stack merge`
|
|
134
|
-
has no head-SHA pin. Branch protection and rulesets are evaluated when the merge runs, and stacks
|
|
135
|
-
cannot bypass merge requirements. If the merge is rejected, re-read topology instead of retrying
|
|
136
|
-
blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the layers queue
|
|
137
|
-
together, and a failing layer is ejected along with the layers above it. The next topology
|
|
138
|
-
re-read handles that.
|
|
139
|
-
|
|
140
|
-
When you stop or are blocked (an unresolved escalation, an interrupt or pause, repeated fixes with
|
|
141
|
-
no progress, or an external blocker), report each layer's number and state. If the bottom layers
|
|
142
|
-
are ready, ask whether to drain them before continuing.
|
|
143
|
-
|
|
144
|
-
## Keep track: derive the ledger
|
|
145
|
-
|
|
146
|
-
A hand-kept list of "pull requests I opened" drifts, and a compaction or new session erases it.
|
|
147
|
-
The ownership stamp makes the ledger derivable, so state is re-read instead of recalled.
|
|
148
|
-
|
|
149
|
-
Reconcile broadly, partition narrowly. A new session opens a rival stack because it never looks for
|
|
150
|
-
the old one, so the reconcile query is deliberately unfiltered; only the partition is
|
|
151
|
-
session-filtered:
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
# Reconcile, unfiltered: it finds stacks this session did not create.
|
|
155
|
-
gh api --paginate repos/{owner}/{repo}/stacks --jq '.[] | select(.open)' # 30 per page
|
|
156
|
-
gh api --paginate "repos/{owner}/{repo}/pulls?state=open&per_page=100" \
|
|
157
|
-
--jq '.[] | {number, title, user: .user.login, body}'
|
|
158
|
-
# Partition: apply the ownership check from Establish scope to that output.
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
- Reconcile before starting anything new. At the start of work, and before opening any pull
|
|
162
|
-
request or stack, surface every open stack or unfinished layer, whoever made it.
|
|
163
|
-
- Close out; do not drift away. Close a layer that will not land. Ending or pausing a session with
|
|
164
|
-
owned open layers requires reporting them.
|
|
165
|
-
- Continue the stack instead of starting a parallel one. Dependent work for an owned open stack is
|
|
166
|
-
a new layer (`gh stack add`, after the layer cap check). For an unowned open stack, report it and
|
|
167
|
-
ask instead of adding to it or starting a rival.
|
|
168
|
-
- Derive state (which pull requests and stacks exist, their positions, their status) every time;
|
|
169
|
-
never cache it. Only intent, such as which stack is being built or what a planned layer is for,
|
|
170
|
-
belongs in the session's plan or journal, and it is a plan, not a record.
|
|
171
|
-
|
|
172
|
-
Known gaps:
|
|
173
|
-
|
|
174
|
-
- An ownership stamp is a body line any writer can edit. It is a signal, not an authorization
|
|
175
|
-
boundary, and that is sound only because every merge is human-gated.
|
|
176
|
-
- Stack and pull request numbers share no guaranteed disjointness, which is why merge check 1
|
|
177
|
-
runs before every merge.
|
|
@@ -1,147 +0,0 @@
|
|
|
1
|
-
# gh-stack mechanics
|
|
2
|
-
|
|
3
|
-
Official docs (do not copy): [About](https://docs.github.com/en/pull-requests/get-started/about-stacked-prs),
|
|
4
|
-
[CLI](https://docs.github.com/en/pull-requests/reference/stacked-prs-cli-commands),
|
|
5
|
-
[Managing](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/managing-stacked-pull-requests),
|
|
6
|
-
[Merging](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests).
|
|
7
|
-
|
|
8
|
-
## Setup
|
|
9
|
-
|
|
10
|
-
- Install on first stacked use: `gh extension install github/gh-stack`. The feature is in public
|
|
11
|
-
preview.
|
|
12
|
-
- If `gh stack` exits 9 (stacks are not enabled on the repository), do not bundle the source issues
|
|
13
|
-
into one pull request. Open one pull request on the default branch for the bottom issue, wait for
|
|
14
|
-
it to merge, then open the next. Say that stacks are unavailable.
|
|
15
|
-
- Workflows that must run on stacked pull requests must not set `pull_request.branches` or
|
|
16
|
-
`branches-ignore`. GitHub evaluates `branches: [main]` against `stack.base.ref`, but
|
|
17
|
-
`gh stack submit` opens mid-stack pull requests before the stack object exists
|
|
18
|
-
([github/gh-stack#425](https://github.com/github/gh-stack/issues/425)), so the filter skips them
|
|
19
|
-
permanently. After a workflow trigger change lands on the default branch, rebase existing stacks
|
|
20
|
-
(`gh stack rebase` or `gh stack sync`) so parent branches include it.
|
|
21
|
-
|
|
22
|
-
## Agent commands
|
|
23
|
-
|
|
24
|
-
Use only non-interactive forms, and run every `gh stack` command without a TTY. Run
|
|
25
|
-
`git config rerere.enabled true` before the first `init`, which otherwise prompts. An explicit
|
|
26
|
-
`checkout` prompts when local and remote compositions differ, and `submit --auto` prompts to
|
|
27
|
-
create ordinary pull requests when stacks are disabled; without a TTY these fail instead, so treat
|
|
28
|
-
a failure as the exit-9 recovery above rather than answering a prompt.
|
|
29
|
-
|
|
30
|
-
- `gh stack init <branch>`, rooted on the default branch only. It roots the first layer at the
|
|
31
|
-
local default branch, not `origin/<default>`, and in a linked worktree `git fetch origin` does not
|
|
32
|
-
advance that ref. Fast-forward it with `git fetch origin <default>:<default>` only when no worktree
|
|
33
|
-
has the default branch checked out. Otherwise the checkout that has it fast-forwards itself with
|
|
34
|
-
`git merge --ff-only origin/<default>`; never move it from another worktree.
|
|
35
|
-
- `gh stack add <branch>`, after the layer cap check in [SKILL.md](../SKILL.md#work-bottom-up).
|
|
36
|
-
- `gh stack checkout <stack-or-pr-number>` imports an existing remote stack. See
|
|
37
|
-
[Import a stack](#import-a-stack-before-acting-on-it).
|
|
38
|
-
- `gh stack submit --auto` creates drafts. Immediately update each new pull request's title and
|
|
39
|
-
body with the repository's pull request description tool; auto titles and bodies are not
|
|
40
|
-
sufficient, and an unstamped body fails the ownership check in [drain.md](drain.md).
|
|
41
|
-
- `gh stack link <branch-or-pr>...` (bottom to top) registers a stack without local tracking. It
|
|
42
|
-
pushes the branches and creates a draft pull request for any branch without one. Update each
|
|
43
|
-
pull request it created the same way as after `submit --auto`.
|
|
44
|
-
- `gh stack view --json` is for acting only. Never use it, or `gh stack bottom`, to decide
|
|
45
|
-
topology, ownership, or bottom-ness.
|
|
46
|
-
- `gh stack rebase`, `gh stack rebase --upstack`, `gh stack rebase --continue`,
|
|
47
|
-
`gh stack rebase --abort`.
|
|
48
|
-
- `gh stack sync` fetches, fast-forwards the trunk, cascade-rebases every layer onto its updated
|
|
49
|
-
parent, and pushes all branches with `--force-with-lease --atomic`. It rewrites every layer's
|
|
50
|
-
head, so treat it like a rebase: stop the poll first, never run it over a queued layer, and
|
|
51
|
-
expect reviewed heads to change. Do not check out the default branch. Run it without a TTY (a
|
|
52
|
-
TTY prompts on local/remote divergence; without one it aborts) and without `--prune`.
|
|
53
|
-
- `gh stack push`.
|
|
54
|
-
- `gh stack up <n>`, `gh stack down <n>`, `gh stack top`, `gh stack bottom`, for movement only.
|
|
55
|
-
- `gh stack merge <pr> --yes --squash`, or the repository's merge strategy. The pull request number
|
|
56
|
-
is required. `--yes` skips a prompt that a non-interactive runner cannot answer.
|
|
57
|
-
- `gh stack unstack [<stack-number>]` (alias `delete`) recovers a mis-rooted stack. With no
|
|
58
|
-
argument it targets the active stack. It unstacks on GitHub and removes local tracking; add
|
|
59
|
-
`--local` to remove only local tracking. Pull requests and branches survive. GitHub leaves
|
|
60
|
-
queued or auto-merge pull requests stacked, and then keeps the stack.
|
|
61
|
-
|
|
62
|
-
Never run the interactive forms: `gh stack submit` without `--auto`, `gh stack modify`, bare
|
|
63
|
-
`gh stack checkout`, `gh stack switch`, or bare `gh stack merge` (a TUI that lands the whole
|
|
64
|
-
stack). `gh stack checkout <branch>` resolves only stacks this worktree already tracks. Do not run
|
|
65
|
-
`gh stack trunk` from a linked worktree whose default branch is checked out elsewhere.
|
|
66
|
-
|
|
67
|
-
## Worktree and scope
|
|
68
|
-
|
|
69
|
-
- One worktree per stack. Move with `up` and `down`. Do not add a worktree per layer:
|
|
70
|
-
`gh stack rebase --upstack` rewrites upper branches, and git refuses to update a branch checked
|
|
71
|
-
out in another worktree.
|
|
72
|
-
- `git diff --name-only origin/<default>...HEAD` lists what lands if this layer and every layer
|
|
73
|
-
below merge.
|
|
74
|
-
- `git diff --name-only <parent>...HEAD` is this layer's review scope.
|
|
75
|
-
|
|
76
|
-
## Import a stack before acting on it
|
|
77
|
-
|
|
78
|
-
`gh stack rebase`, `sync`, `push`, and movement act only on stacks the worktree's local record
|
|
79
|
-
tracks. A stack created from another worktree, session, or machine is not tracked. Before rebasing
|
|
80
|
-
or pushing a layer, including when a shepherd instruction says to, import the stack:
|
|
81
|
-
|
|
82
|
-
1. `gh stack checkout <stack-number>`, with the number from `pulls/<N>.stack.number`. It records
|
|
83
|
-
the stack and checks out the top-most unmerged layer. When the worktree already tracks a
|
|
84
|
-
matching stack it only switches branches, so remote-tracking refs can be stale.
|
|
85
|
-
2. Resolve the remote gh-stack uses once (`remote.pushDefault` when set, else the only remote,
|
|
86
|
-
else `origin`), and read `origin` below as that remote.
|
|
87
|
-
3. gh-stack keeps existing local layer branches as they are, so a stale one makes the next rebase
|
|
88
|
-
start from stale commits. Run `git fetch origin`, then for each unmerged layer branch `<b>` run
|
|
89
|
-
`git rev-list --left-right --count "$b...origin/$b"` (left: local-only commits; right: commits
|
|
90
|
-
only on the pull request head). Branch names may contain shell metacharacters: pass each as a
|
|
91
|
-
quoted variable, never paste it into a command line, and skip names that start with `-`:
|
|
92
|
-
- `0 0`: up to date.
|
|
93
|
-
- `0 N`: fast-forward. Use `git merge --ff-only origin/<b>` on the checked-out layer and
|
|
94
|
-
`git branch -f <b> origin/<b>` on any other.
|
|
95
|
-
- A left count above `0` (ahead or diverged): inspect before rewriting or pushing, as the
|
|
96
|
-
consumer's git procedure describes. Do not open another pull request for the layer.
|
|
97
|
-
|
|
98
|
-
## Submit and verify the remote stack
|
|
99
|
-
|
|
100
|
-
- A pull request's base branch selects its comparison target. Chaining bases alone does not
|
|
101
|
-
register a native stack. `gh stack init` and `add` record a local plan. Neither local tracking
|
|
102
|
-
nor a successful pull request creation proves GitHub registered the stack.
|
|
103
|
-
- Once an upper layer has committed, reviewable work and its local checks pass, submit the layers
|
|
104
|
-
as drafts with `gh stack submit --auto` while the lower pull request is still open and unqueued.
|
|
105
|
-
- Verify remote registration before asking to merge or enqueue the lower pull request. An open
|
|
106
|
-
pull request already in a merge queue cannot join a new stack. If it was queued externally, stop
|
|
107
|
-
registering and report the blocker. Do not dequeue it without authorization or rewrite it. When
|
|
108
|
-
it leaves the queue, re-read it: retry registration if it is still open and unqueued, or recover
|
|
109
|
-
as below if it merged. If it closed without merging, report the broken dependency.
|
|
110
|
-
- Do not wait for upper-layer CI or ready status to register the dependency. Do not create empty
|
|
111
|
-
placeholder layers, or start work held for approval, only to preserve a stack.
|
|
112
|
-
- After each submission or link, read every intended pull request's `pulls/<N>.stack` and the
|
|
113
|
-
single-stack endpoint. Require the same stack number, the intended bottom-to-top order, and the
|
|
114
|
-
expected bases. Missing preview metadata leaves membership unknown: report that, and do not infer
|
|
115
|
-
success from local tracking.
|
|
116
|
-
- If the lower pull request merges before registration, GitHub can reject linking it. Re-read the
|
|
117
|
-
forge, fetch, and rebase the remaining work onto the updated default branch without replaying
|
|
118
|
-
the merged layer. Keep any upper pull request already created. Register several remaining open
|
|
119
|
-
layers as a stack and verify their bases. For a single survivor, read its remote base, retarget
|
|
120
|
-
it to the default branch if needed, and verify that before shepherding it alone: a head rebase
|
|
121
|
-
does not change a base. Report sequential pull requests when no stack registered. Do not recreate
|
|
122
|
-
the merged bottom or chain bases by hand as a substitute.
|
|
123
|
-
|
|
124
|
-
## Lower-layer review fix
|
|
125
|
-
|
|
126
|
-
Check out the layer that owns the change and commit there. Then run `gh stack rebase --upstack`
|
|
127
|
-
and `gh stack push` once. Do not duplicate the fix in an upper layer.
|
|
128
|
-
|
|
129
|
-
## The forge is the only truth
|
|
130
|
-
|
|
131
|
-
Every fact the procedure branches on (topology, layer state, ownership, head SHA) comes from the
|
|
132
|
-
REST or GraphQL API, never from local gh-stack metadata. A local base ref can go stale after a
|
|
133
|
-
remote relink or rebase and silently replay already-landed commits. `gh stack view --json` also
|
|
134
|
-
errors from a worktree whose current branch is not in the stack, which is normal right after a
|
|
135
|
-
merge retargets it.
|
|
136
|
-
|
|
137
|
-
```bash
|
|
138
|
-
gh api "repos/{owner}/{repo}/pulls/<N>" --jq '{stackPresent: has("stack"), stack: .stack}'
|
|
139
|
-
gh api "repos/{owner}/{repo}/stacks/<n>" # layers bottom to top, with head.sha and author
|
|
140
|
-
gh api --paginate "repos/{owner}/{repo}/stacks" --jq '.[] | select(.open)' # state is null
|
|
141
|
-
# and ?state=open is ignored
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
- Use the single-stack endpoint for one stack's layers. The list form returns each layer's
|
|
145
|
-
`base.ref` as `null`.
|
|
146
|
-
- `.stack` is a preview field. Its absence is not proof a pull request is unstacked: report "stack
|
|
147
|
-
membership unknown" instead of assuming it is unstacked.
|
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: static-analysis-checklist
|
|
3
|
-
description: Place, author, and validate static-analysis invariants.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Static analysis checklist
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/static-analysis-checklist/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use when changing a static-analysis invariant. Read local `AGENTS.md`, analyzer
|
|
13
|
-
documentation, rule inventory, and fixture conventions before selecting an implementation.
|
|
14
|
-
|
|
15
|
-
1. State the invariant and search for an existing analyzer, rule, or guard that owns it. Prefer the
|
|
16
|
-
narrowest established owner over a parallel scanner.
|
|
17
|
-
2. For workflow or action policy, parse YAML instead of text matching. Inspect only intended
|
|
18
|
-
tracked configuration files. A persistent-workspace guard enforces
|
|
19
|
-
[github-actions-checklist](../github-actions-checklist/SKILL.md): reject sparse-checkout inputs
|
|
20
|
-
and unsafe writable workspace mounts, and allow unrelated YAML keys and ordinary read-only
|
|
21
|
-
mounts.
|
|
22
|
-
3. Add meaningful accepted and rejected fixtures before the rule. Cover path routing, parser
|
|
23
|
-
boundaries, equivalent YAML forms, and every allowed exception.
|
|
24
|
-
4. Keep discovery limited to tracked, intended files. Make suppressions and allowlists narrow,
|
|
25
|
-
justified, and mechanically checked for freshness where practical.
|
|
26
|
-
5. Run the focused fixture test and analyzer, then the local aggregate checks. Keep diagnostics
|
|
27
|
-
actionable and deterministic.
|
|
28
|
-
6. Update the local inventory or documentation and delete superseded migration artifacts only when
|
|
29
|
-
the replacement invariant is demonstrably enforced.
|
|
30
|
-
|
|
31
|
-
This skill does not name analyzer roots, fixture locations, commands, suppression syntax, or
|
|
32
|
-
rollout policy. A consumer wrapper or local instruction file provides them.
|
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: storybook-authoring
|
|
3
|
-
description: Author component stories and browser coverage for real states.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Storybook authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/storybook-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Apply [test-authoring](../test-authoring/SKILL.md).
|
|
13
|
-
|
|
14
|
-
- Show a meaningful supported state with realistic args and fixtures.
|
|
15
|
-
- Keep story data local and deterministic.
|
|
16
|
-
- Expose an important visual or interaction variant.
|
|
17
|
-
- Add browser-mode coverage where it catches behavior a unit test cannot see.
|
|
18
|
-
- Do not use a story as end-to-end setup or as production data handling.
|
|
19
|
-
- Read [component coverage](references/component-coverage.md) for direct stories and browser
|
|
20
|
-
isolation.
|
|
21
|
-
|
|
22
|
-
Consumer wrapper owns: Storybook configuration, exclusions, visual baselines, and commands.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# Component coverage
|
|
2
|
-
|
|
3
|
-
Keep a direct story for each supported reusable component state. When a component needs server-only
|
|
4
|
-
modules, request context, or browser-hostile imports, isolate the presentational surface or alias the
|
|
5
|
-
boundary to a deterministic fixture. Test interactive story behavior in browser mode when it owns
|
|
6
|
-
the component contract.
|
|
7
|
-
|
|
8
|
-
Allow story discovery to follow the consumer's module graph and glob configuration. Do not hand
|
|
9
|
-
maintain duplicate registration lists or make module-top-level browser assumptions.
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: swift-test-authoring
|
|
3
|
-
description: Test Swift and SwiftUI state, networking, and view behavior.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Swift test authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/swift-test-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Apply [test-authoring](../test-authoring/SKILL.md).
|
|
13
|
-
|
|
14
|
-
- Test public behavior with deterministic inputs and injected dependencies.
|
|
15
|
-
- For SwiftUI, inspect or interact through the project's supported test approach.
|
|
16
|
-
- For networking, use a protocol-level test double. Keep request and response synchronization
|
|
17
|
-
explicit.
|
|
18
|
-
- Avoid sleeps and global state. Keep fixtures small enough that a failure is readable.
|
|
19
|
-
- Read [network test doubles](references/network-test-doubles.md) for cancellation and shared-state
|
|
20
|
-
safety.
|
|
21
|
-
|
|
22
|
-
Consumer wrapper owns: test targets, coverage thresholds, view-inspection libraries, and fixture
|
|
23
|
-
APIs.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# Network test doubles
|
|
2
|
-
|
|
3
|
-
Delayed URLProtocol callbacks must honor `stopLoading()`: guard delivery with synchronized stopped
|
|
4
|
-
state so cancellation cannot call a released client. Keep shared response and captured-request state
|
|
5
|
-
private behind one synchronization boundary, reset related fields atomically, and expose coherent
|
|
6
|
-
snapshots for assertions.
|
|
7
|
-
|
|
8
|
-
Avoid sleeping to coordinate tests. Inject scheduling or await explicit completion so networking,
|
|
9
|
-
view state, and cancellation remain deterministic under parallel execution.
|
|
@@ -1,27 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: test-authoring
|
|
3
|
-
description: Choose meaningful tests, fixtures, and observable boundaries.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Test authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/test-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use the repository's test conventions and the matching runner skill.
|
|
13
|
-
|
|
14
|
-
- Test observable behavior, boundary failures, and regressions. Do not test implementation details.
|
|
15
|
-
- Build fixtures through public constructors or documented helpers. Keep data minimal, explicit, and
|
|
16
|
-
representative.
|
|
17
|
-
- Add a focused failing test before a behavior change when that behavior can be tested. Then run the
|
|
18
|
-
narrowest relevant test and the required checks.
|
|
19
|
-
- Read [core practice](references/core-practice.md) before choosing a runner-specific approach.
|
|
20
|
-
- Read [tautological tests](references/tautological-tests.md) before finishing a test whose
|
|
21
|
-
assertion
|
|
22
|
-
is not obviously falsifiable by a defect in the code under test.
|
|
23
|
-
- Read [dependency boundaries](references/dependency-boundaries.md) before asserting on anything a
|
|
24
|
-
dependency produces, and whenever a dependency upgrade breaks a test.
|
|
25
|
-
|
|
26
|
-
Consumer wrapper owns: project test commands, coverage targets, mock libraries, and integration
|
|
27
|
-
environments.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
# Core test practice
|
|
2
|
-
|
|
3
|
-
- Choose the lowest realistic boundary that can observe the contract.
|
|
4
|
-
- Mock an external system or uncontrolled infrastructure. Exercise internal module composition where
|
|
5
|
-
that is practical.
|
|
6
|
-
- Test behavior, failure paths, authorization, and security-relevant validation. Do not reach it
|
|
7
|
-
through a private call. Assert what this repository owns, not what its
|
|
8
|
-
[dependencies](dependency-boundaries.md) produce.
|
|
9
|
-
- Start with a failing test when the behavior is testable.
|
|
10
|
-
- Finish only when the production path, its public contract, documentation, and generated artifacts
|
|
11
|
-
move together. Do not leave a placeholder or a test-only production branch.
|
|
12
|
-
- For every acceptance criterion, keep evidence from a focused test, a review, or an explicitly
|
|
13
|
-
justified manual check. Evidence counts only when it is falsifiable. Confirm the assertion is not
|
|
14
|
-
[tautological](tautological-tests.md) before treating it as coverage.
|
|
15
|
-
- For instruction and documentation contracts, test real paths, links, rendered markers, or
|
|
16
|
-
executable behavior. Do not freeze prose wording unless a real consumer parses that exact text.
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
# Dependency boundaries
|
|
2
|
-
|
|
3
|
-
Test the code this repository owns. The dependency's own tests own its algorithms, error messages,
|
|
4
|
-
output formats, internal file layout, exit codes, the URLs and query strings it builds, its
|
|
5
|
-
pagination and retry strategy, and the order or number of calls it makes. An assertion that pins
|
|
6
|
-
any of that fails on a dependency release, not on a regression here.
|
|
7
|
-
|
|
8
|
-
Apply the [tautological tests](tautological-tests.md) check with ownership added. Name a defect in
|
|
9
|
-
this repository that would fail the assertion.
|
|
10
|
-
|
|
11
|
-
- If only a dependency release could fail it, delete it.
|
|
12
|
-
- If it covers owned logic and also pins incidental dependency detail, rewrite it to the owned
|
|
13
|
-
outcome.
|
|
14
|
-
|
|
15
|
-
Owned even when a dependency carries it out: enabled rules, thresholds, scopes, arguments,
|
|
16
|
-
endpoints, parameters, handling of the dependency's exit codes and errors, and any call count or
|
|
17
|
-
order this repository's logic requires. Test those through the dependency's public API.
|
|
18
|
-
|
|
19
|
-
Shapes:
|
|
20
|
-
|
|
21
|
-
- Version-drift guard: a deep import of private files, or a call to internal functions, so the
|
|
22
|
-
suite notices an upstream change. Delete it. When docs rely on dependency behavior, link to the
|
|
23
|
-
dependency's docs.
|
|
24
|
-
- Dependency re-test: fabricated input asserted against what the dependency returns. A wrapper that
|
|
25
|
-
only forwards configuration needs one test that the configuration arrives.
|
|
26
|
-
- Upstream-output pin: an exact dependency-owned message, markdown blob, JSON envelope, or renderer
|
|
27
|
-
markup when the owned contract is narrower. Assert the rule identifier, status, or owned field.
|
|
28
|
-
- Sequence-bound fake: one-shot responses, or a queue consumed in call order, when this repository
|
|
29
|
-
does not own that order. An added request, a pagination change, or a reorder then hands the wrong
|
|
30
|
-
reply to the wrong call. Route the fake by request meaning, such as method and pathname. Assert
|
|
31
|
-
the owned result, not an incidental URL, query string, or call count.
|
|
32
|
-
|
|
33
|
-
When a dependency upgrade breaks a test:
|
|
34
|
-
|
|
35
|
-
- If the test pinned dependency behavior, delete or rewrite it. Do not re-pin the new value. Do not
|
|
36
|
-
add a guard that fails on the next release.
|
|
37
|
-
- If owned code or configuration failed — the dependency rejects arguments this repository passes,
|
|
38
|
-
or returns a result this repository mishandles — fix the owned code.
|
|
@@ -1,47 +0,0 @@
|
|
|
1
|
-
# Tautological tests
|
|
2
|
-
|
|
3
|
-
A test is tautological when no defect in the code under test could make its assertion fail. Name a
|
|
4
|
-
concrete defect the assertion would catch. If none exists, the assertion proves nothing.
|
|
5
|
-
|
|
6
|
-
A test name is part of the assertion. `it('returns 200')` that never reads the status is the
|
|
7
|
-
defect: reviewers trust the name and skim the body.
|
|
8
|
-
|
|
9
|
-
Shapes, most consequential first:
|
|
10
|
-
|
|
11
|
-
- Forced-value: the test transforms the result, then asserts the transformed constant.
|
|
12
|
-
`expect(x.then(() => undefined)).resolves.toBeUndefined()` still depends on `x` fulfilling, but
|
|
13
|
-
every fulfillment value collapses to `undefined`. The assertion must depend on the code's output,
|
|
14
|
-
not only on whether it threw. A test named for returned data that never reads that data asserts
|
|
15
|
-
nothing about it.
|
|
16
|
-
- Literal: `expect(true).toBe(true)`, and the same shape in other runners (`XCTAssertTrue(true)`,
|
|
17
|
-
`Assert.True(true)`).
|
|
18
|
-
- Self-comparison: `expect(x).toBe(x)`.
|
|
19
|
-
- Literal echo: the test asserts a value it just wrote. Input and expectation are the same value,
|
|
20
|
-
with no code path between them.
|
|
21
|
-
- Mock echo: the assertion checks that a mock returns the value the test configured.
|
|
22
|
-
- Re-implementation: the test recomputes the production algorithm and compares the two results, so
|
|
23
|
-
a shared bug cancels out.
|
|
24
|
-
- Vacuous range or shape: `expect(x.length).toBeGreaterThanOrEqual(0)`, or `toBeDefined()` /
|
|
25
|
-
`typeof` on a static import or a value the test just constructed. It holds for every output.
|
|
26
|
-
- No-assert: the test awaits a call and asserts nothing afterward. It fails only when the call
|
|
27
|
-
throws. An `expect-expect` lint rule flags the missing assertion.
|
|
28
|
-
|
|
29
|
-
Coverage pressure is the usual cause: a line must be covered and no assertion is obvious.
|
|
30
|
-
|
|
31
|
-
- When the code returns null or swallows an error for the case under test, assert that exact
|
|
32
|
-
outcome, such as `.toBeNull()` for not-found or a definite non-null shape for found. A
|
|
33
|
-
definedness check still passes if a regression collapses the two paths.
|
|
34
|
-
- Otherwise assert the shape of the returned payload.
|
|
35
|
-
- Only when neither is available, assert completion alone, such as
|
|
36
|
-
`await expect(run()).resolves.not.toBeInstanceOf(Error)`, and name the test for resolving rather
|
|
37
|
-
than for success or a status code.
|
|
38
|
-
- A 403 can execute the same lines as a 200. Do not satisfy a coverage percentage with an
|
|
39
|
-
assertion that cannot fail.
|
|
40
|
-
|
|
41
|
-
Delete a tautological test when removing it does not reduce coverage. When removal drops coverage,
|
|
42
|
-
that test owns those lines: strengthen it in place. A steady coverage number does not show that the
|
|
43
|
-
remaining tests check anything.
|
|
44
|
-
|
|
45
|
-
Consumer repositories may enforce the mechanical shapes above with ast-grep and an `expect-expect`
|
|
46
|
-
rule. This document judges the shapes those tools cannot express: a definedness check that needs
|
|
47
|
-
dataflow analysis, a mock echo, or a re-implementation. Do not contradict the mechanical rules.
|
|
@@ -1,64 +0,0 @@
|
|
|
1
|
-
# Ready and shepherd
|
|
2
|
-
|
|
3
|
-
The loop's own procedure for moving a PR it reviewed to ready and starting one local shepherd. It is
|
|
4
|
-
used by the loop, `triage-sweep`, and `triage-prs`, and by the `/shepherd` handler. It is not a
|
|
5
|
-
general "mark any draft ready" tool: an agent working its own PR runs pr-shepherd itself.
|
|
6
|
-
|
|
7
|
-
Inputs: a PR number, `--repo <owner>/<name>` (pass it on every `gh` command), optional
|
|
8
|
-
`--arm-auto-merge`, and optional `--steer-file <path>`. The adapter supplies the automation label
|
|
9
|
-
and the merge authority per PR category; stop and ask when one is missing.
|
|
10
|
-
|
|
11
|
-
1. **Resolve and light review.** Resolve the PR in `--repo`; reject one from another repository.
|
|
12
|
-
Record `headRefOid`, read the diff and CI state, and decide whether the shepherd needs direction
|
|
13
|
-
(for example "prefer the general fix over a narrow band-aid"). Write steering with a file-writing
|
|
14
|
-
tool, never shell interpolation, and read it back in full.
|
|
15
|
-
2. **Preflight.** Check that a background worker can start. Re-read `headRefOid` before every
|
|
16
|
-
mutation below; if it moved, return for re-review. Skip a PR that `shepherds` already records.
|
|
17
|
-
3. **Steer (optional).** Post the reviewed steering file as an ordinary comment with
|
|
18
|
-
`--body-file` **before** arming. Reject an empty file.
|
|
19
|
-
4. **Mark ready and label.**
|
|
20
|
-
`gh pr view <N> --repo <owner>/<name> --json isDraft --jq .isDraft` (true: `gh pr ready`), then
|
|
21
|
-
`gh pr edit <N> --repo <owner>/<name> --add-label <automation-label>`.
|
|
22
|
-
5. **Request final review and gate on it (only when the adapter turns on the final-review gate;
|
|
23
|
-
otherwise skip this step).** Request a review of the current head with
|
|
24
|
-
`gh api --method POST repos/<owner>/<name>/issues/<N>/labels -f 'labels[]=final-review:requested'`
|
|
25
|
-
(or message the `final-reviewer` session with `<owner>/<name>#<N>`); adding it again requests a
|
|
26
|
-
re-review after new commits. The standing reviewer lives in `vouchington/vouchington-reviewer`.
|
|
27
|
-
Run `pnpm --dir <reviewer-checkout> exec vouchington-reviewer status --repo <owner>/<name> --pr <N>`
|
|
28
|
-
before arming, merging, or re-enqueueing: exit 0 means the newest final review approved the
|
|
29
|
-
current head and the `final approval` label is present. Any other exit code means do not merge:
|
|
30
|
-
when `gh pr view <N> --repo <owner>/<name> --json autoMergeRequest --jq .autoMergeRequest` is
|
|
31
|
-
set (armed earlier), first run `gh pr merge <N> --repo <owner>/<name> --disable-auto`; then
|
|
32
|
-
leave the PR ready and unarmed, report `awaiting-final-review`, and let a later sweep rerun the
|
|
33
|
-
check. Nothing waits on the reviewer. This gate is procedural: GitHub enforces it only through a
|
|
34
|
-
required status check, or branch protection that dismisses stale approvals, which the consuming
|
|
35
|
-
repository's adapter owns.
|
|
36
|
-
6. **Arm auto-merge (only with `--arm-auto-merge`, and, with the final-review gate on, only when
|
|
37
|
-
step 5 exited 0).** Pass the flag
|
|
38
|
-
only for a category the grant covers. Check once per repository per run that
|
|
39
|
-
`gh api repos/<owner>/<name> --jq .allow_auto_merge` is true; when `false`, report `manual merge required` and continue. When the
|
|
40
|
-
REST pull object has a `stack` field, auto-merge is unavailable: report `stacked; needs explicit
|
|
41
|
-
stack-merge authorization`, skip arming, and follow
|
|
42
|
-
[stacked-prs](../../stacked-prs/SKILL.md) under the grant or explicit human approval.
|
|
43
|
-
- **Unsteered:** arm with exactly one bare command:
|
|
44
|
-
`gh pr merge <N> --repo <owner>/<name> --auto --squash`. Arming succeeds on a conflicting
|
|
45
|
-
branch; the shepherd resolves it and the armed merge lands once checks pass.
|
|
46
|
-
- **Steered:** do not arm; arming would race the shepherd before it consumes the steering. Leave
|
|
47
|
-
the PR ready and unarmed and report `manual-verification-required`.
|
|
48
|
-
7. **Start the shepherd.** Never run two shepherds on one PR. Start one background worker in an
|
|
49
|
-
isolated worktree (or a workspace agent the adapter names) that runs
|
|
50
|
-
`pr-shepherd <owner>/<name>#<N> --until-terminal` and reruns it after every result except CANCEL
|
|
51
|
-
and ESCALATE: TRIAGE means fix and rerun; READY or a quota warning means rerun after the printed
|
|
52
|
-
delay; MERGE means the worker never merges, it reports the PR mergeable and stops. For a stack,
|
|
53
|
-
use `pr-shepherd stack`. Record the handoff (PR, head, worker id, time) in `shepherds`. Nothing
|
|
54
|
-
waits on the worker; on ESCALATE it reports back and the loop escalates. Remove the entry when
|
|
55
|
-
the worker stops. Before any push to an armed PR, the worker or loop runs
|
|
56
|
-
`gh pr merge <N> --repo <owner>/<name> --disable-auto` and confirms `autoMergeRequest` is now
|
|
57
|
-
null; if disarming fails, it does not push and reports instead. With the final-review gate on,
|
|
58
|
-
after the push it requests a new final review (the label again, as in step 5), and a later sweep
|
|
59
|
-
re-arms only when `vouchington-reviewer status` exits 0 for the new head.
|
|
60
|
-
8. **Verify and report.** `gh pr view <N> --repo <owner>/<name> --json
|
|
61
|
-
isDraft,autoMergeRequest,state`. Report per PR: ready, steered, auto-merge (armed, no,
|
|
62
|
-
manual-verification-required, awaiting-final-review, unavailable), shepherd (local or no), and the reason for any `no`.
|
|
63
|
-
|
|
64
|
-
The loop never posts `/shepherd` to itself: `/shepherd` is how another agent delegates a PR to it.
|