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.
Files changed (68) hide show
  1. package/package.json +2 -2
  2. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  3. package/skills/manifest.json +15 -202
  4. package/skills/organize-github-issues/SKILL.md +20 -3
  5. package/skills/pr-description/SKILL.md +9 -65
  6. package/skills/retrospective/SKILL.md +16 -1
  7. package/skills/retrospective-distill/SKILL.md +1 -1
  8. package/skills/retrospective-distill/references/issue-body.md +6 -1
  9. package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
  10. package/skills/triage-loop/SKILL.md +111 -34
  11. package/skills/triage-prs/SKILL.md +26 -28
  12. package/skills/triage-prs/references/feedback.md +14 -2
  13. package/skills/triage-prs/references/rubric.md +4 -4
  14. package/skills/triage-sweep/SKILL.md +26 -23
  15. package/skills/agent-workflow/SKILL.md +0 -72
  16. package/skills/agent-workflow/references/evidence-sweep.md +0 -12
  17. package/skills/agent-workflow/references/four-refs.md +0 -74
  18. package/skills/agent-workflow/references/implementation-and-review.md +0 -4
  19. package/skills/agent-workflow/references/implementation.md +0 -20
  20. package/skills/agent-workflow/references/review-response.md +0 -49
  21. package/skills/agent-workflow/references/review.md +0 -10
  22. package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
  23. package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
  24. package/skills/bounded-iteration/SKILL.md +0 -92
  25. package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
  26. package/skills/dependabot/SKILL.md +0 -117
  27. package/skills/dotnet-test-authoring/SKILL.md +0 -24
  28. package/skills/git-commit-checklist/SKILL.md +0 -29
  29. package/skills/github-actions-authoring/SKILL.md +0 -63
  30. package/skills/github-actions-checklist/SKILL.md +0 -118
  31. package/skills/github-issue/SKILL.md +0 -121
  32. package/skills/glide-mq/SKILL.md +0 -52
  33. package/skills/glide-mq/references/lease-patterns.md +0 -44
  34. package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
  35. package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
  36. package/skills/npm-publishing/SKILL.md +0 -72
  37. package/skills/package-json-checklist/SKILL.md +0 -31
  38. package/skills/planning/SKILL.md +0 -37
  39. package/skills/planning/references/impact-discovery.md +0 -11
  40. package/skills/playwright-authoring/SKILL.md +0 -23
  41. package/skills/playwright-authoring/references/browser-reliability.md +0 -9
  42. package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
  43. package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
  44. package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
  45. package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
  46. package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
  47. package/skills/postgres-schema-design/SKILL.md +0 -31
  48. package/skills/postgres-schema-design/references/naming.md +0 -34
  49. package/skills/postgres-schema-design/references/relations.md +0 -66
  50. package/skills/postgres-schema-design/references/table-shapes.md +0 -78
  51. package/skills/pr-description/references/examples.md +0 -189
  52. package/skills/review-ci-logs/SKILL.md +0 -44
  53. package/skills/revisit-followups/SKILL.md +0 -47
  54. package/skills/stacked-prs/SKILL.md +0 -98
  55. package/skills/stacked-prs/references/drain.md +0 -177
  56. package/skills/stacked-prs/references/gh-stack.md +0 -147
  57. package/skills/static-analysis-checklist/SKILL.md +0 -32
  58. package/skills/storybook-authoring/SKILL.md +0 -22
  59. package/skills/storybook-authoring/references/component-coverage.md +0 -9
  60. package/skills/swift-test-authoring/SKILL.md +0 -23
  61. package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
  62. package/skills/test-authoring/SKILL.md +0 -27
  63. package/skills/test-authoring/references/core-practice.md +0 -16
  64. package/skills/test-authoring/references/dependency-boundaries.md +0 -38
  65. package/skills/test-authoring/references/tautological-tests.md +0 -47
  66. package/skills/triage-loop/references/shepherd.md +0 -64
  67. package/skills/vitest-test-authoring/SKILL.md +0 -22
  68. 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.