vouchington-tooling 0.87.1 → 0.88.0

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 (38) hide show
  1. package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts +2 -2
  2. package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs +20 -12
  3. package/dist/agent-blackboard/snapshot-partition-cleanup.d.mts +1 -0
  4. package/dist/agent-blackboard/snapshot-partition-cleanup.mjs +3 -0
  5. package/dist/agent-blackboard/snapshot-partitions.mjs +1 -1
  6. package/dist/agent-blackboard/snapshot-types.d.mts +8 -0
  7. package/dist/mcp-server/dispatch.mjs +1 -1
  8. package/dist/mcp-server/handlers-pr.mjs +1 -1
  9. package/dist/mcp-server/handlers-snapshot-cleanup.mjs +8 -0
  10. package/dist/mcp-server/handlers-snapshot-partition.mjs +6 -1
  11. package/dist/mcp-server/install-info.d.mts +2 -2
  12. package/dist/mcp-server/install-info.mjs +10 -6
  13. package/dist/mcp-server/pr-prepare.mjs +17 -11
  14. package/dist/mcp-server/server.mjs +2 -1
  15. package/dist/mcp-server/snapshot-recovery.d.mts +8 -0
  16. package/dist/mcp-server/snapshot-recovery.mjs +76 -0
  17. package/dist/mcp-server/snapshot-registry.d.mts +3 -1
  18. package/dist/mcp-server/snapshot-registry.mjs +3 -1
  19. package/dist/mcp-server/tools-pr.mjs +2 -1
  20. package/dist/mcp-server/tools.mjs +16 -5
  21. package/dist/mcp-server/worktree.mjs +3 -0
  22. package/docs/mcp-server.md +24 -8
  23. package/package.json +1 -1
  24. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  25. package/skills/agent-workflow/SKILL.md +7 -1
  26. package/skills/dependabot/SKILL.md +4 -3
  27. package/skills/final-review/references/orchestrator.md +3 -3
  28. package/skills/manifest.json +25 -33
  29. package/skills/planning/SKILL.md +3 -0
  30. package/skills/review-ci-logs/SKILL.md +2 -0
  31. package/skills/stacked-prs/SKILL.md +8 -2
  32. package/skills/stacked-prs/references/drain.md +3 -1
  33. package/skills/triage-loop/SKILL.md +125 -21
  34. package/skills/triage-loop/references/shepherd.md +45 -0
  35. package/skills/triage-prs/SKILL.md +15 -18
  36. package/skills/triage-prs/references/rubric.md +2 -2
  37. package/skills/triage-sweep/SKILL.md +40 -12
  38. package/skills/ready-and-shepherd/SKILL.md +0 -110
@@ -10,8 +10,9 @@ Read applicable `AGENTS.md` and their declared adapter alias, otherwise
10
10
  Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
11
 
12
12
  One pass of [triage-loop](../triage-loop/SKILL.md). It uses that skill's adapter, state file, and
13
- grant. Run outside a loop, it still needs an explicit user request, which is the grant for that
14
- one pass. Arguments, both optional: `--dry-run` reports every intended mutation and makes none, and
13
+ grant. It is the fallback and backstop for the loop's `hook-harness` event wait: it re-checks what
14
+ events would have reported. Run outside a loop, it needs an explicit user request, which is the
15
+ grant for that one pass. Arguments, both optional: `--dry-run` reports every intended mutation and makes none, and
15
16
  `--repo <name>` or `--phase <letter>` narrows the pass.
16
17
 
17
18
  ## Rules for every phase
@@ -34,7 +35,7 @@ and `headRefOid`. Skip a PR whose auto-merge is already armed (for example by a
34
35
  auto-merge workflow) while its checks pass or are pending. Arming it again or dispatching a second
35
36
  shepherd would race the merge that is already landing.
36
37
 
37
- Steered handoffs stay unarmed (see [ready-and-shepherd](../ready-and-shepherd/SKILL.md) Step 5)
38
+ Steered handoffs stay unarmed (see [ready and shepherd](../triage-loop/references/shepherd.md) step 5)
38
39
  and are reported as `shepherding, manual-verification-required`. A later sweep arms one only when:
39
40
 
40
41
  - its shepherd is no longer in flight;
@@ -43,16 +44,21 @@ and are reported as `shepherding, manual-verification-required`. A later sweep a
43
44
 
44
45
  Arming then uses one bare `gh pr merge` command, as in the grant.
45
46
 
46
- - **Patch or minor, green:** ready-and-shepherd with `--arm-auto-merge`.
47
+ `dependabot-pr` events from the loop's wait enter this phase for the one PR.
48
+
49
+ - **Patch or minor, green:** [ready and shepherd](../triage-loop/references/shepherd.md) with `--arm-auto-merge`.
47
50
  - **Patch or minor, failing or conflicting:** an implementation-tier subagent reads the failure
48
51
  with [review-ci-logs](../review-ci-logs/SKILL.md) and classifies it as trivial (lockfile,
49
- rebase, type or import rename, a config key) or non-trivial. Trivial: ready-and-shepherd with
52
+ rebase, type or import rename, a config key) or non-trivial. Trivial: ready and shepherd with
50
53
  `--arm-auto-merge`, with steering that names the fix. Non-trivial: escalate.
51
54
  - **Major:** an implementation-tier subagent reads the release notes, changelog, and migration
52
- guide, and searches the repository for affected call sites. It returns `no-migration`,
53
- `small-migration` (mechanical edits, no runtime-behavior change), or `significant-migration`
54
- with evidence. The first two go through ready-and-shepherd with `--arm-auto-merge`, steered for
55
- a small migration. A significant migration is escalated.
55
+ guide, searches the repository for affected call sites, and checks whether tests that ran in CI
56
+ exercise them. It returns `no-migration`, `small-migration` (mechanical edits, no
57
+ runtime-behavior change), or `significant-migration`, with evidence and the coverage finding.
58
+ Merge through ready and shepherd with `--arm-auto-merge` (steered for a small migration) only
59
+ when no migration or a small one is needed and the affected call sites are exercised by CI
60
+ tests. Escalate a significant migration, or affected code without sufficient test coverage, with
61
+ the evidence.
56
62
  - **No open dependency-bot PRs in a repository:** request a fresh update check. GitHub exposes no
57
63
  REST endpoint for this. Use the host browser on the repository's Dependabot updates page
58
64
  (`https://github.com/<owner>/<name>/network/updates`), choose "Check for updates" for each
@@ -75,7 +81,7 @@ carry the adapter's automation label and pass the gate get `--arm-auto-merge`.
75
81
 
76
82
  ## Phase C - Intake queue
77
83
 
78
- Process `intake` from the state file as described in triage-loop Step 3. Remove each report once
84
+ Process `intake` from the state file as described in triage-loop Step 4. Remove each report once
79
85
  its issue exists and its dispatch is recorded.
80
86
 
81
87
  ## Phase D - Issue triage
@@ -117,7 +123,27 @@ root cause through [github-issue](../github-issue/SKILL.md), linking the PR and
117
123
  harvested comment id to `reviewedComments`, and prune ids whose PR has left the window. A comment
118
124
  posted days after merge is still found.
119
125
 
120
- ## Phase G - Report and escalate
126
+ ## Phase G - Queue ejections and default-branch failures
127
+
128
+ The backstop for `ejection` and `main-failure` events, run on `gap: true`, on a failed wait, and
129
+ each full sweep. A mechanical-tier subagent per repository lists PRs removed from the merge queue
130
+ in the last 24 hours (keeping failure-driven removals, dropping user-requested ones and PRs
131
+ currently queued) and failed default-branch workflow runs, paginating fully. Handle each as the
132
+ loop's [Failures](../triage-loop/SKILL.md#failures) section describes: dedupe against fixes in
133
+ flight, diagnose, re-enqueue an in-grant PR whose head is unchanged only after a flake or infra diagnosis, and file or delegate flakes. Skip run ids already in `handledFailures`, and record each one handled.
134
+ Fix PRs follow the same merge rule: only a test-only diff merges.
135
+
136
+ ## Phase G2 - Command comments
137
+
138
+ The backstop for `/shepherd`, `/plan`, and `/fix` events, run on `gap: true`, on a failed wait, and
139
+ each full sweep. A mechanical-tier subagent per repository lists those comments on issues and PRs
140
+ posted since `lastSweepAt` by the adapter's trusted logins (never trust `authorAssociation`),
141
+ paginating fully, and keeps those with no `eyes` reaction from the loop and no `shepherds` entry
142
+ for the PR. This covers commands missed while the loop was down. The loop handles each as the
143
+ [Comment commands](../triage-loop/SKILL.md#comment-commands) section describes, including the
144
+ acknowledgement.
145
+
146
+ ## Phase H - Report and escalate
121
147
 
122
148
  For each new escalation (dedupe on `escalations` in the state file):
123
149
 
@@ -130,7 +156,9 @@ actions:
130
156
 
131
157
  - merged
132
158
  - armed
133
- - shepherding (local or comment)
159
+ - re-enqueued
160
+ - fix PR opened
161
+ - shepherding
134
162
  - escalated
135
163
  - issue filed
136
164
  - assigned
@@ -1,110 +0,0 @@
1
- ---
2
- name: ready-and-shepherd
3
- description: Move an authorized, triaged PR to ready, steer it, arm auto-merge, and hand it to a shepherd.
4
- ---
5
-
6
- # Ready and shepherd
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/ready-and-shepherd/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
- Internal mechanics for batch triage callers (`triage-prs`, `triage-sweep`, or a consumer's
13
- security-triage adapter). It moves a PR
14
- those callers already reviewed to ready and hands it to a shepherd. It is not a general "mark any
15
- draft ready" tool: a session working its own single PR runs pr-shepherd directly under the
16
- CANCEL/ESCALATE contract and lets pr-shepherd own the draft-to-ready transition.
17
-
18
- Arguments: a PR number or URL, `--repo <owner>/<name>`, optional `--arm-auto-merge`, and optional
19
- `--steer-file <path>`. Pass `--repo` on every `gh` command.
20
-
21
- ## Adapter parameters
22
-
23
- Resolve these before Step 1 and stop to ask when one this run needs is missing; never guess.
24
-
25
- - **Shepherd mode:** `comment` (post an exact trigger comment that starts a CI-dispatched
26
- shepherd, fire-and-forget) or `local` (the caller runs pr-shepherd in a background worker until
27
- CANCEL/ESCALATE). Repositories without a CI shepherd workflow use `local`.
28
- - **Trigger comment and activation gates** (`comment` mode only): the exact trigger body and the
29
- repository variables that must all read `true` before any mutation.
30
- - **Automation label:** applied idempotently to every PR this skill readies.
31
- - **Merge authority:** who authorizes `--arm-auto-merge` for which PR categories.
32
-
33
- ## Step 1 - Resolve and light review
34
-
35
- Resolve the PR in `--repo`; reject one from another repository. Record `headRefOid`, read the diff
36
- and CI state, and decide whether the shepherd needs direction (for example "prefer the general fix
37
- over a narrow band-aid"). Write steering with a file-writing tool, never shell interpolation, and
38
- read it back in full. With `--steer-file`, use that file instead.
39
-
40
- ## Step 2 - Activation preflight (fail closed)
41
-
42
- Before any GitHub mutation, in `comment` mode read every adapter activation gate. An unset,
43
- unreadable, empty, or non-`true` gate is disabled: stop before Step 3 and report
44
- `activation disabled - unchanged`. Do not post steering, mark ready, add labels, arm, or trigger.
45
- `local` mode has no gates; its preflight is that the caller can start a background worker.
46
-
47
- Re-read `headRefOid` before every mutation below; if it moved, return to the caller for re-review.
48
-
49
- ## Step 3 - Steer (optional)
50
-
51
- Post the reviewed steering file as an ordinary comment with `--body-file`, **before** arming or
52
- triggering. Reject an empty file or one whose whole trimmed content equals the trigger comment.
53
-
54
- ## Step 4 - Mark ready and label
55
-
56
- ```bash
57
- gh pr view <N> --repo <owner>/<name> --json isDraft --jq .isDraft # true -> gh pr ready
58
- gh pr edit <N> --repo <owner>/<name> --add-label <automation-label>
59
- ```
60
-
61
- ## Step 5 - Arm auto-merge (only with `--arm-auto-merge`)
62
-
63
- Without the flag, skip this step; merge stays a human decision. Pass the flag only when the caller
64
- holds merge authority for this PR's category under the adapter.
65
-
66
- Check once per repository per run that auto-merge is allowed
67
- (`gh api repos/<owner>/<name> --jq .allow_auto_merge`). When it is `false`, report
68
- `manual merge required` and continue to Step 6. When the REST pull object has a `stack` field,
69
- auto-merge is unavailable: report `stacked; needs explicit stack-merge authorization`, skip Steps 6
70
- and 7, and follow [stacked-prs](../stacked-prs/SKILL.md) only under explicit human approval.
71
-
72
- - **Unsteered:** arm now with exactly one bare command, never wrapped or compounded:
73
- `gh pr merge <N> --repo <owner>/<name> --auto --squash`. Arming succeeds on a conflicting branch;
74
- the shepherd resolves the conflict and the armed merge lands once checks pass.
75
- - **Steered:** do not arm. Arming would race the shepherd before it consumes the steering. Leave the
76
- PR ready and unarmed; report `manual-verification-required`.
77
-
78
- ## Step 6 - Hand off to the shepherd
79
-
80
- Never run two shepherds on one PR. Before any handoff, skip the PR and report
81
- `shepherd: already in flight` when either of these holds:
82
-
83
- - **`comment` mode:** a trigger comment exists that is newer than the PR's latest commit.
84
- - **`local` mode:** the caller's state lists an active worker for this PR.
85
-
86
- Record every handoff (PR, head, mode, trigger comment id or worker id, time) in the caller's state
87
- so the next pass sees it.
88
-
89
- - **`comment` mode:** if the PR is still `OPEN`, post exactly the trigger body with
90
- `gh api -X POST repos/<owner>/<name>/issues/<N>/comments -f body=<trigger> --jq .id` and record
91
- the comment id. Dispatch is fire-and-forget: a `running` checkpoint proves acceptance, not
92
- success. Never poll the dispatch workflow or arm later from a `queued` or `running` state.
93
- - **`local` mode:** return `shepherd: local` to the caller, which starts one background worker in
94
- an isolated worktree. The worker reruns `pr-shepherd <owner>/<name>#<N> --until-terminal` after
95
- every result except CANCEL and ESCALATE:
96
- - TRIAGE: fix the items, then rerun.
97
- - READY or a quota warning: rerun after the delay the output names.
98
- - MERGE: the worker never merges. It reports the PR as mergeable to the caller and stops.
99
-
100
- On ESCALATE, it reports back to the caller, which escalates. Remove the worker from the caller's
101
- state when it stops.
102
-
103
- ## Step 7 - Verify and report
104
-
105
- `gh pr view <N> --repo <owner>/<name> --json isDraft,autoMergeRequest,state`. Report per PR:
106
- `ready`, `steered`, `auto-merge armed` (yes, no, manual-verification-required, unavailable),
107
- `shepherd` (comment id, local, or no), and the reason for any `no`.
108
-
109
- Consumer wrapper owns: shepherd mode, trigger body and activation gates, the automation label, merge
110
- authority by PR category, and any provider-specific handoff variants.