vouchington-tooling 0.87.1 → 1.0.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 (97) hide show
  1. package/README.md +1 -8
  2. package/dist/agent-blackboard/feedback-journal-audit.mjs +14 -6
  3. package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +4 -2
  4. package/dist/agent-blackboard/feedback-journal-sandbox.mjs +14 -6
  5. package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts +2 -2
  6. package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs +20 -12
  7. package/dist/agent-blackboard/snapshot-partition-cleanup.d.mts +1 -0
  8. package/dist/agent-blackboard/snapshot-partition-cleanup.mjs +3 -0
  9. package/dist/agent-blackboard/snapshot-partitions.mjs +1 -1
  10. package/dist/agent-blackboard/snapshot-types.d.mts +8 -0
  11. package/dist/audit-journal/audit-block.d.mts +2 -0
  12. package/dist/audit-journal/audit-block.mjs +13 -8
  13. package/dist/audit-journal/ci-failures.d.mts +6 -2
  14. package/dist/audit-journal/ci-failures.mjs +12 -6
  15. package/dist/audit-journal/journal.d.mts +2 -0
  16. package/dist/audit-journal/journal.mjs +18 -3
  17. package/dist/audit-journal/scope.d.mts +25 -0
  18. package/dist/audit-journal/scope.mjs +47 -0
  19. package/dist/audit-journal/types.d.mts +3 -0
  20. package/dist/cli/index.mjs +0 -6
  21. package/dist/cli/parse-forwarded-commands.d.mts +1 -1
  22. package/dist/cli/parse-forwarded-commands.mjs +0 -2
  23. package/dist/cli/parse.d.mts +1 -7
  24. package/dist/cli/parse.mjs +0 -1
  25. package/dist/cli/script-paths.mjs +0 -1
  26. package/dist/cli/usage-text.d.mts +1 -1
  27. package/dist/cli/usage-text.mjs +0 -6
  28. package/dist/gh-cli/exec.d.mts +8 -2
  29. package/dist/gh-cli/exec.mjs +3 -3
  30. package/dist/gha-review-payload/index.d.mts +0 -2
  31. package/dist/gha-review-payload/index.mjs +0 -1
  32. package/dist/index.d.mts +2 -8
  33. package/dist/index.mjs +1 -4
  34. package/dist/mcp-server/dispatch.mjs +1 -1
  35. package/dist/mcp-server/handlers-pr.mjs +1 -1
  36. package/dist/mcp-server/handlers-snapshot-cleanup.mjs +8 -0
  37. package/dist/mcp-server/handlers-snapshot-partition.mjs +6 -1
  38. package/dist/mcp-server/install-info.d.mts +2 -2
  39. package/dist/mcp-server/install-info.mjs +10 -6
  40. package/dist/mcp-server/pr-diff-size.d.mts +16 -0
  41. package/dist/mcp-server/pr-diff-size.mjs +49 -0
  42. package/dist/mcp-server/pr-live.d.mts +3 -0
  43. package/dist/mcp-server/pr-live.mjs +8 -2
  44. package/dist/mcp-server/pr-prepare.mjs +20 -12
  45. package/dist/mcp-server/server.mjs +2 -1
  46. package/dist/mcp-server/snapshot-recovery.d.mts +8 -0
  47. package/dist/mcp-server/snapshot-recovery.mjs +76 -0
  48. package/dist/mcp-server/snapshot-registry.d.mts +3 -1
  49. package/dist/mcp-server/snapshot-registry.mjs +3 -1
  50. package/dist/mcp-server/tools-pr.mjs +2 -1
  51. package/dist/mcp-server/tools.mjs +16 -5
  52. package/dist/mcp-server/worktree.mjs +4 -1
  53. package/docs/mcp-server.md +43 -10
  54. package/package.json +1 -16
  55. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  56. package/skills/agent-workflow/SKILL.md +7 -1
  57. package/skills/dependabot/SKILL.md +4 -3
  58. package/skills/final-review/references/orchestrator.md +3 -3
  59. package/skills/manifest.json +25 -33
  60. package/skills/planning/SKILL.md +3 -0
  61. package/skills/retrospective/SKILL.md +2 -1
  62. package/skills/review-ci-logs/SKILL.md +2 -0
  63. package/skills/stacked-prs/SKILL.md +8 -2
  64. package/skills/stacked-prs/references/drain.md +3 -1
  65. package/skills/triage-loop/SKILL.md +125 -21
  66. package/skills/triage-loop/references/shepherd.md +45 -0
  67. package/skills/triage-prs/SKILL.md +15 -18
  68. package/skills/triage-prs/references/rubric.md +2 -2
  69. package/skills/triage-sweep/SKILL.md +40 -12
  70. package/dist/gha-check-run/cli.d.mts +0 -2
  71. package/dist/gha-check-run/cli.mjs +0 -81
  72. package/dist/gha-check-run/github.d.mts +0 -30
  73. package/dist/gha-check-run/github.mjs +0 -63
  74. package/dist/gha-check-run/index.d.mts +0 -2
  75. package/dist/gha-check-run/index.mjs +0 -2
  76. package/dist/gha-claude-post-review/index.d.mts +0 -3
  77. package/dist/gha-claude-post-review/index.mjs +0 -2
  78. package/dist/gha-post-review/claude-token.d.mts +0 -25
  79. package/dist/gha-post-review/claude-token.mjs +0 -109
  80. package/dist/gha-post-review/cli.d.mts +0 -1
  81. package/dist/gha-post-review/cli.mjs +0 -22
  82. package/dist/gha-post-review/github.d.mts +0 -13
  83. package/dist/gha-post-review/github.mjs +0 -58
  84. package/dist/gha-post-review/index.d.mts +0 -13
  85. package/dist/gha-post-review/index.mjs +0 -8
  86. package/dist/gha-post-review/post.d.mts +0 -24
  87. package/dist/gha-post-review/post.mjs +0 -39
  88. package/dist/gha-post-review/pull-io.d.mts +0 -13
  89. package/dist/gha-post-review/pull-io.mjs +0 -88
  90. package/dist/gha-post-review/token.d.mts +0 -9
  91. package/dist/gha-post-review/token.mjs +0 -21
  92. package/dist/gha-review-payload/cli.d.mts +0 -1
  93. package/dist/gha-review-payload/cli.mjs +0 -24
  94. package/dist/gha-review-payload/file.d.mts +0 -7
  95. package/dist/gha-review-payload/file.mjs +0 -62
  96. package/scripts/gha/materialize-pr-context.sh +0 -123
  97. package/skills/ready-and-shepherd/SKILL.md +0 -110
@@ -74,7 +74,8 @@ export const PR_TOOLS = [
74
74
  'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
75
75
  'Journal preserved; the pull request may be in any state and on any head (the head given to ' +
76
76
  'the policy is its own, and no liveness check applies, unlike pr_update). Returns ' +
77
- '{ body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
77
+ '{ ok, body, errors, warnings }; blocking errors do not fail the tool call, so callers must ' +
78
+ 'check ok (true only when errors is empty) or errors.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
78
79
  tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
79
80
  RENDERING +
80
81
  'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +
@@ -113,10 +113,21 @@ export const TOOLS = [
113
113
  },
114
114
  }, ['cleanupToken', 'sessionIds']),
115
115
  tool('snapshot_cleanup', 'Deletes the snapshot file and the partition directory (from snapshot_partition) that ' +
116
- 'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
117
- 'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
118
- 'worktree that exported, is single-use, and is forgotten when the server restarts (the ' +
119
- 'file is then left for the OS to reap). A failed cleanup keeps the token valid and names ' +
120
- 'any retained tombstone so the same call can retry. Call it as a finally step.', { ...MUTATING, idempotentHint: false }, { cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' } }, ['cleanupToken']),
116
+ 'snapshot_export produced. Pass exactly one of cleanupToken or recoveryDirectory. ' +
117
+ 'cleanupToken is the one snapshot_export returned: the server resolves the paths from its ' +
118
+ 'own record, never from the caller. The token is bound to the sessionId and worktree that ' +
119
+ 'exported, is single-use, and is forgotten when the server restarts. After a restart, pass ' +
120
+ 'recoveryDirectory, the directory snapshot_partition returned: the server deletes it and ' +
121
+ 'its source snapshot only if the signed receipt inside proves it generated them for this ' +
122
+ 'sessionId and worktree in the temp directory. A plain unpartitioned snapshot has no ' +
123
+ 'receipt and cannot be recovered. Recovery is single-use and every rejection is one ' +
124
+ 'message. A failed cleanup keeps the token valid and names any retained tombstone so the ' +
125
+ 'same call can retry. Call it as a finally step.', { ...MUTATING, idempotentHint: false }, {
126
+ cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' },
127
+ recoveryDirectory: {
128
+ type: 'string',
129
+ description: 'After a server restart, the partition directory snapshot_partition returned.',
130
+ },
131
+ }, []),
121
132
  tool('session_archive', 'Marks a session as distilled. Its metadata becomes immutable; entries stay appendable.', MUTATING),
122
133
  ];
@@ -13,7 +13,7 @@ export function isolatedGitEnv() {
13
13
  const { LANGUAGE: _language, ...env } = gitEnv();
14
14
  return { ...env, LC_ALL: 'C' };
15
15
  }
16
- export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: isolatedGitEnv() }));
16
+ export const runIsolatedGit = createCommandRunner('git', (command, args, options) => execFileAsync(command, args, { ...options, env: isolatedGitEnv() }));
17
17
  async function canonical(path) {
18
18
  try {
19
19
  return await realpath(path);
@@ -89,6 +89,9 @@ export async function resolveWorktree(input) {
89
89
  if (!isAbsolute(path))
90
90
  throw new Error('worktree must be an absolute path to a git worktree');
91
91
  const target = await canonical(path);
92
+ if (requested === undefined && target === undefined)
93
+ throw new Error(`the launch worktree ${path} no longer exists, so there is no default to fall back to: ` +
94
+ 'pass worktree as the absolute path of an existing worktree');
92
95
  if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target) {
93
96
  if (launchRoot === undefined || (await repositoryWorktrees(launchRoot, runGit)).has(target))
94
97
  return target;
@@ -62,7 +62,8 @@ the Node version first: on Node older than 24 they print one line to stderr, suc
62
62
  The command takes no arguments and may be launched with any working directory, including one outside
63
63
  every git repository (for example `~`). When the working directory is inside a git worktree, that
64
64
  worktree's top level is the default for tools called without `worktree`. Otherwise those calls fail
65
- with a tool error asking for an explicit `worktree`. stdout carries only protocol frames, and
65
+ with a tool error asking for an explicit `worktree`. If the launch worktree is later removed, those
66
+ calls fail naming the removed path and asking for an explicit `worktree`. stdout carries only protocol frames, and
66
67
  diagnostics go to stderr.
67
68
 
68
69
  ## Tools
@@ -83,7 +84,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
83
84
  | `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
84
85
  | `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
85
86
  | `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
86
- | `snapshot_cleanup` | `cleanupToken` | `sessionId`, `cleaned: true` |
87
+ | `snapshot_cleanup` | one of `cleanupToken` or `recoveryDirectory` | `sessionId`, `cleaned: true` |
87
88
  | `session_archive` | none | `sessionId`, `archived: true` |
88
89
 
89
90
  `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
@@ -206,10 +207,22 @@ failure.
206
207
  the owner's token. If the cleanup itself fails, the token stays valid and the error carries the
207
208
  reason, including the retained tombstone path when a partition directory was half removed, so the
208
209
  same call can retry. A file that is already gone counts as cleaned.
209
- - **Server restart.** Bindings are in memory only. After a restart every earlier token is unknown, so
210
- the file is left for the operating system to reap from its temp directory; run the distill pass
211
- again to export a fresh snapshot. The registry also remembers at most 256 exports and forgets the
212
- oldest first.
210
+ - **Server restart.** Bindings are in memory only, so after a restart every earlier token is
211
+ unknown. Instead of persisting client capabilities, `recoveryDirectory` (the directory
212
+ `snapshot_partition` returned, used in place of `cleanupToken`) lets the server prove it generated
213
+ the output. The directory must be a non-symlink child of the OS temp directory with the generated
214
+ name; the `.agent-blackboard-cleanup-receipt.json` marker inside must carry a valid HMAC signature
215
+ under the server's persistent owner-only key; and the signed `owner` (`sessionId`, `worktree`, and
216
+ the source snapshot path, all signed into the receipt) must equal the caller's. Deletion then
217
+ reuses the receipt cleanup's checks (directory identity, partition checksums, no unexpected
218
+ content). The source snapshot is removed with it. Recovery is single use (the directory is gone
219
+ afterward, and a concurrent call is refused) and every rejection is one message that deletes
220
+ nothing.
221
+ - **Not recoverable.** A plain unpartitioned export file has no receipt, so after a restart it is
222
+ left for the operating system to reap. So are directories partitioned by a newer client that
223
+ keeps its own ownership marker (its capability is never persisted), and directories whose
224
+ receipt predates the signed `owner` field. Run the distill pass again to export a fresh snapshot.
225
+ The registry remembers at most 256 exports and forgets the oldest first.
213
226
 
214
227
  The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
215
228
  Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
@@ -283,7 +296,11 @@ sessionId>` when that would exceed 256 bytes. Re-saving identical content return
283
296
  stored receipt and timestamp. Changed content under the same `sourceEventId` is an
284
297
  `event-conflict`; a revision needs a new `sourceEventId`. `compose` regenerates the document from
285
298
  the live journal and repository, so repeating a `compose` call is not a retry: when an interactive
286
- save is retained in the outbox, deliver it with `outbox_flush`.
299
+ save is retained in the outbox, deliver it with `outbox_flush`. The CI Failures and Sandbox &
300
+ Permission Audit sections use only the journal entries created after the session's newest earlier
301
+ retrospective (by the blackboard's `createdAt`), and each section with excluded blocks adds an
302
+ `Excluded: N blocks from before retrospective <sourceEventId>` line; a revision keeps its own
303
+ blocks because the boundary is the newest retrospective older than the newest block.
287
304
 
288
305
  ### Policy module
289
306
 
@@ -309,7 +326,7 @@ whole process group is killed, so nothing it started outlives the call. The runn
309
326
  | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
310
327
  | `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }` | 30 s |
311
328
  | `pullRequestDefaults` | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create` | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s |
312
- | `validatePullRequest` | `title`, `body`, `base`, `head`, the trusted `mode`, `noSourceIssue` when given, and `pr` when set | `{ errors: string[], warnings?: string[] }` | 120 s |
329
+ | `validatePullRequest` | `title`, `body`, `base`, `head`, the trusted `mode`, `noSourceIssue` when given, `pr` when set, and `diff` (see below) | `{ errors: string[], warnings?: string[] }` | 120 s |
313
330
 
314
331
  Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
315
332
  `policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
@@ -354,6 +371,19 @@ that launched the server: `CODEX_THREAD_ID` (codex), `CLAUDECODE=1` or `CLAUDE_C
354
371
  is derivable the line says `unknown`. Making `agent` optional is compatible with existing callers,
355
372
  which may keep sending it.
356
373
 
374
+ ### Change size for the validator
375
+
376
+ `validatePullRequest` receives `diff`, so a policy can bound the size of a change. It is
377
+ `{ additions, deletions, changedFiles, source }` or `{ unavailable: reason }`. With a live pull
378
+ request (`pr_update`, and `pr_validate` with `pr`) the counts are GitHub's own for that pull
379
+ request, read in the same `gh pr view` as the body (`source: 'github'`), so they are right even
380
+ when the worktree is on another commit; a live count that is not a non-negative integer rejects the
381
+ call. Without one (`pr_create`, and `pr_validate` without `pr`) the server runs
382
+ `git diff --numstat --no-ext-diff origin/<base>...HEAD --` in the worktree and sums it
383
+ (`source: 'git'`; a binary file counts as a file with no lines). That git call is limited to 30 s and
384
+ 1 MiB of output; when it fails, times out, overflows, or `origin/<base>` is not fetched, `diff` is
385
+ `{ unavailable }` and the call still succeeds.
386
+
357
387
  ### Pull requests with no source issue
358
388
 
359
389
  Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`, or with a
@@ -401,14 +431,17 @@ The provenance lines are collapsed because they serve audits, not reviewers; eac
401
431
  own line, so a policy can match them with line-anchored patterns.
402
432
 
403
433
  The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
404
- request's head, which may equal `base` for a fork); otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
434
+ request's head, which may equal `base` for a fork). `pr_update` also accepts a detached HEAD whose
435
+ commit is the live pull request's head commit and then uses the live head name; a detached HEAD at
436
+ another commit is rejected naming both commits. Otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
405
437
  so a consumer policy may reject any `base` other than the default branch; create stacked layers
406
438
  with the repository's stack tooling instead.
407
439
 
408
440
  ### Tools
409
441
 
410
442
  - `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
411
- base, head, mode, noSourceIssue?, pr? })` export and returns `{ body, errors, warnings }`. With
443
+ base, head, mode, noSourceIssue?, pr?, diff })` export and returns `{ ok, body, errors, warnings }`. Blocking errors do not fail the tool call: callers must
444
+ check `ok` (true only when `errors` is empty) or `errors`. With
412
445
  `pr`, the live body is read (never written) so its Shepherd Journal is preserved as in
413
446
  `pr_update`. The liveness checks of `pr_update` do not apply: any state (merged or closed
414
447
  included) and any head are accepted, and the policy sees the pull request's own head and base.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.87.1",
3
+ "version": "1.0.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -256,21 +256,6 @@
256
256
  "import": "./dist/gha-review-payload/index.mjs",
257
257
  "default": "./dist/gha-review-payload/index.mjs"
258
258
  },
259
- "./gha-post-review": {
260
- "types": "./dist/gha-post-review/index.d.mts",
261
- "import": "./dist/gha-post-review/index.mjs",
262
- "default": "./dist/gha-post-review/index.mjs"
263
- },
264
- "./gha-claude-post-review": {
265
- "types": "./dist/gha-claude-post-review/index.d.mts",
266
- "import": "./dist/gha-claude-post-review/index.mjs",
267
- "default": "./dist/gha-claude-post-review/index.mjs"
268
- },
269
- "./gha-check-run": {
270
- "types": "./dist/gha-check-run/index.d.mts",
271
- "import": "./dist/gha-check-run/index.mjs",
272
- "default": "./dist/gha-check-run/index.mjs"
273
- },
274
259
  "./provider-replay": {
275
260
  "types": "./dist/provider-replay/index.d.mts",
276
261
  "import": "./dist/provider-replay/index.mjs",
@@ -32,9 +32,15 @@ blocker or follow-up does not authorize widening the task.
32
32
  This section is the single home for the hand-off retrospective and merge-note rules.
33
33
 
34
34
  - Report actual validation, open pull requests, and remaining blockers.
35
+ - **Shepherding.** The agent that authored a pull request shepherds it itself with pr-shepherd.
36
+ When the session must end or the owner asks, delegate instead: mark the pull request ready, post
37
+ the fixed literal comment `/shepherd` once (`gh pr comment <N> --body '/shepherd'`), and stop. The
38
+ triage loop then owns the pull request (one `/shepherd` on the top pull request of a stack). Do
39
+ not post it again on re-runs. No other agent merges.
35
40
  - **Hand-off retrospective.** When you hand a pull request to the human as ready, write one
36
41
  [retrospective](../retrospective/SKILL.md) from the session that did the work, which reads that
37
- session's transcripts and journal. A native stack gets one retrospective when the stack is handed
42
+ session's transcripts and journal. Write it before you stop, including when you delegate with
43
+ `/shepherd`. A native stack gets one retrospective when the stack is handed
38
44
  off, covering every layer; never one per layer or for an intermediate commit.
39
45
  - Give each hand-off its own `sourceEventId`, such as `handoff-pr<number>` (a stack uses its top
40
46
  pull request's number), on both `retrospective_check` and `retrospective_save`. The default ID
@@ -59,8 +59,8 @@ groups:
59
59
  - Do not add generic groups such as `other-minor-and-patch`, `minor-and-patch`,
60
60
  `security-minor-and-patch`, or `security-updates`. Do not use `patterns: ['*']` to force every
61
61
  update into a group. Narrow family wildcards are expected. Leave unrelated packages ungrouped.
62
- - Omit `update-types` so a family receives major, minor, and patch updates. Major updates stay
63
- human-reviewed. Leaving majors out of the group splits the release train.
62
+ - Omit `update-types` so a family receives major, minor, and patch updates. Major updates are never
63
+ auto-merged by the workflow. Leaving majors out of the group splits the release train.
64
64
  - Groups default to `applies-to: version-updates`. When the same family is also safe to upgrade
65
65
  together for security fixes, add a separate group such as `react-security` with the same patterns
66
66
  and `applies-to: security-updates`. Do not combine unrelated vulnerability fixes into one group.
@@ -91,7 +91,8 @@ groups:
91
91
  per local policy.
92
92
  - Auto-merge only a verified semver patch, or a stable minor whose old and new majors are both at
93
93
  least 1. Majors, pre-1.0 minors, prereleases, downgrades, malformed or inconsistent metadata, and
94
- consumer-declared manual ecosystems need a human.
94
+ consumer-declared manual ecosystems need a human. The workflow never merges majors; the triage
95
+ loop may merge them under its grant, as triage-sweep Phase A describes.
95
96
  - Enable platform auto-merge. Do not auto-approve. Required checks and branch rules remain the gate.
96
97
  - Store `DEPENDABOT_AUTOMERGE_TOKEN` as a Dependabot secret, not only as an Actions secret. Grant
97
98
  only the Contents and Pull requests access needed to enable or disable auto-merge. Fail an
@@ -27,9 +27,9 @@ compaction, rebuild the queue from pending requests and the status of the pull r
27
27
 
28
28
  ## Hand-back
29
29
 
30
- Posting the review is the hand-back: the requesting agent's pull-request shepherd sees the review
31
- and its inline comments. Also reply to the requester with the verdict and the review link. Merge
32
- authority is separate: the human or the original agent merges, never the final reviewer.
30
+ Posting the review is the hand-back: the PR's active shepherd (usually the triage loop's) sees
31
+ the review and its inline comments. Also reply to the requester with the verdict and the review link. Merge
32
+ authority is separate: the human, or the triage loop within its grant, merges, never the final reviewer.
33
33
 
34
34
  ## Presenting to the human
35
35
 
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "agent-workflow",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.16.1",
7
+ "pluginVersion": "0.17.0",
8
8
  "path": "agent-workflow/SKILL.md",
9
9
  "prerequisites": [
10
10
  "blackboard",
@@ -24,7 +24,7 @@
24
24
  {
25
25
  "name": "blackboard",
26
26
  "plugin": "vouchington-workflow",
27
- "pluginVersion": "0.16.1",
27
+ "pluginVersion": "0.17.0",
28
28
  "path": "blackboard/SKILL.md"
29
29
  },
30
30
  {
@@ -36,7 +36,7 @@
36
36
  {
37
37
  "name": "dependabot",
38
38
  "plugin": "vouchington-workflow",
39
- "pluginVersion": "0.16.1",
39
+ "pluginVersion": "0.17.0",
40
40
  "path": "dependabot/SKILL.md",
41
41
  "prerequisites": ["github-actions-checklist"]
42
42
  },
@@ -50,32 +50,32 @@
50
50
  {
51
51
  "name": "final-review",
52
52
  "plugin": "vouchington-workflow",
53
- "pluginVersion": "0.16.1",
53
+ "pluginVersion": "0.17.0",
54
54
  "path": "final-review/SKILL.md"
55
55
  },
56
56
  {
57
57
  "name": "git-commit-checklist",
58
58
  "plugin": "vouchington-workflow",
59
- "pluginVersion": "0.16.1",
59
+ "pluginVersion": "0.17.0",
60
60
  "path": "git-commit-checklist/SKILL.md"
61
61
  },
62
62
  {
63
63
  "name": "github-actions-authoring",
64
64
  "plugin": "vouchington-workflow",
65
- "pluginVersion": "0.16.1",
65
+ "pluginVersion": "0.17.0",
66
66
  "path": "github-actions-authoring/SKILL.md",
67
67
  "prerequisites": ["github-actions-checklist"]
68
68
  },
69
69
  {
70
70
  "name": "github-actions-checklist",
71
71
  "plugin": "vouchington-workflow",
72
- "pluginVersion": "0.16.1",
72
+ "pluginVersion": "0.17.0",
73
73
  "path": "github-actions-checklist/SKILL.md"
74
74
  },
75
75
  {
76
76
  "name": "github-issue",
77
77
  "plugin": "vouchington-workflow",
78
- "pluginVersion": "0.16.1",
78
+ "pluginVersion": "0.17.0",
79
79
  "path": "github-issue/SKILL.md"
80
80
  },
81
81
  {
@@ -94,26 +94,26 @@
94
94
  {
95
95
  "name": "npm-publishing",
96
96
  "plugin": "vouchington-workflow",
97
- "pluginVersion": "0.16.1",
97
+ "pluginVersion": "0.17.0",
98
98
  "path": "npm-publishing/SKILL.md"
99
99
  },
100
100
  {
101
101
  "name": "organize-github-issues",
102
102
  "plugin": "vouchington-workflow",
103
- "pluginVersion": "0.16.1",
103
+ "pluginVersion": "0.17.0",
104
104
  "path": "organize-github-issues/SKILL.md",
105
105
  "prerequisites": ["github-issue"]
106
106
  },
107
107
  {
108
108
  "name": "package-json-checklist",
109
109
  "plugin": "vouchington-workflow",
110
- "pluginVersion": "0.16.1",
110
+ "pluginVersion": "0.17.0",
111
111
  "path": "package-json-checklist/SKILL.md"
112
112
  },
113
113
  {
114
114
  "name": "planning",
115
115
  "plugin": "vouchington-workflow",
116
- "pluginVersion": "0.16.1",
116
+ "pluginVersion": "0.17.0",
117
117
  "path": "planning/SKILL.md",
118
118
  "prerequisites": ["github-issue"]
119
119
  },
@@ -145,60 +145,53 @@
145
145
  {
146
146
  "name": "pr-description",
147
147
  "plugin": "vouchington-workflow",
148
- "pluginVersion": "0.16.1",
148
+ "pluginVersion": "0.17.0",
149
149
  "path": "pr-description/SKILL.md"
150
150
  },
151
- {
152
- "name": "ready-and-shepherd",
153
- "plugin": "vouchington-workflow",
154
- "pluginVersion": "0.16.1",
155
- "path": "ready-and-shepherd/SKILL.md",
156
- "prerequisites": ["stacked-prs"]
157
- },
158
151
  {
159
152
  "name": "retrospective",
160
153
  "plugin": "vouchington-workflow",
161
- "pluginVersion": "0.16.1",
154
+ "pluginVersion": "0.17.0",
162
155
  "path": "retrospective/SKILL.md"
163
156
  },
164
157
  {
165
158
  "name": "retrospective-distill",
166
159
  "plugin": "vouchington-workflow",
167
- "pluginVersion": "0.16.1",
160
+ "pluginVersion": "0.17.0",
168
161
  "path": "retrospective-distill/SKILL.md",
169
162
  "prerequisites": ["github-issue"]
170
163
  },
171
164
  {
172
165
  "name": "review-ci-logs",
173
166
  "plugin": "vouchington-workflow",
174
- "pluginVersion": "0.16.1",
167
+ "pluginVersion": "0.17.0",
175
168
  "path": "review-ci-logs/SKILL.md",
176
169
  "prerequisites": ["github-actions-checklist", "pr-description"]
177
170
  },
178
171
  {
179
172
  "name": "review-github-issue-taxonomy",
180
173
  "plugin": "vouchington-workflow",
181
- "pluginVersion": "0.16.1",
174
+ "pluginVersion": "0.17.0",
182
175
  "path": "review-github-issue-taxonomy/SKILL.md",
183
176
  "prerequisites": ["github-issue"]
184
177
  },
185
178
  {
186
179
  "name": "revisit-followups",
187
180
  "plugin": "vouchington-workflow",
188
- "pluginVersion": "0.16.1",
181
+ "pluginVersion": "0.17.0",
189
182
  "path": "revisit-followups/SKILL.md",
190
183
  "prerequisites": ["github-issue"]
191
184
  },
192
185
  {
193
186
  "name": "stacked-prs",
194
187
  "plugin": "vouchington-workflow",
195
- "pluginVersion": "0.16.1",
188
+ "pluginVersion": "0.17.0",
196
189
  "path": "stacked-prs/SKILL.md"
197
190
  },
198
191
  {
199
192
  "name": "static-analysis-checklist",
200
193
  "plugin": "vouchington-workflow",
201
- "pluginVersion": "0.16.1",
194
+ "pluginVersion": "0.17.0",
202
195
  "path": "static-analysis-checklist/SKILL.md",
203
196
  "prerequisites": ["github-actions-checklist"]
204
197
  },
@@ -225,28 +218,27 @@
225
218
  {
226
219
  "name": "triage-loop",
227
220
  "plugin": "vouchington-workflow",
228
- "pluginVersion": "0.16.1",
221
+ "pluginVersion": "0.17.0",
229
222
  "path": "triage-loop/SKILL.md",
230
- "prerequisites": ["ready-and-shepherd", "github-issue"]
223
+ "prerequisites": ["github-issue", "stacked-prs"]
231
224
  },
232
225
  {
233
226
  "name": "triage-prs",
234
227
  "plugin": "vouchington-workflow",
235
- "pluginVersion": "0.16.1",
228
+ "pluginVersion": "0.17.0",
236
229
  "path": "triage-prs/SKILL.md",
237
230
  "prerequisites": [
238
231
  "pr-description",
239
232
  "retrospective",
240
233
  "review-ci-logs",
241
234
  "github-issue",
242
- "stacked-prs",
243
- "ready-and-shepherd"
235
+ "stacked-prs"
244
236
  ]
245
237
  },
246
238
  {
247
239
  "name": "triage-sweep",
248
240
  "plugin": "vouchington-workflow",
249
- "pluginVersion": "0.16.1",
241
+ "pluginVersion": "0.17.0",
250
242
  "path": "triage-sweep/SKILL.md",
251
243
  "prerequisites": [
252
244
  "triage-loop",
@@ -31,4 +31,7 @@ diagram, independent reviewer, or separate issue are required by this skill.
31
31
  For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
32
32
  tests or concluding that a surface has no dependents.
33
33
 
34
+ On a `/plan` comment, the triage loop's subagent drafts the plan, the loop asks the human its
35
+ open questions, then posts the plan on the source issue or PR as the durable record.
36
+
34
37
  Consumer wrapper owns: durable plan storage, repository, taxonomy, discovery tools, and approval.
@@ -28,7 +28,8 @@ answer is `unknown — no journal`, never a guess.
28
28
  `feedbackCoverage`, and `repositories`. Pass `compose.transcript.harnessSessionId` whenever the
29
29
  harness session id differs from the call's `sessionId`. The composer builds the CI failures and
30
30
  sandbox audit sections from the session's hosted journal entries alone, so do not rerun
31
- collectors to fill them. A session unknown to the journal reports both as unavailable, not as
31
+ collectors to fill them. Both sections cover only journal entries created after the session's
32
+ newest earlier retrospective and say how many earlier blocks were excluded. A session unknown to the journal reports both as unavailable, not as
32
33
  none observed. Put sensitive values only in
33
34
  `compose.knownSensitiveValues`, or `knownSensitiveValues` for a markdown save. Keep exact factual
34
35
  section markers generated, preserve unavailable counts, and never replace missing evidence with
@@ -38,5 +38,7 @@ Use when investigating a CI failure, repeated workflow noise, or misleading diag
38
38
  follow-up. Keep the distinction between omitted and locally passed checks explicit, and retain
39
39
  confirmed gap records after CI turns green. Classify CI-only and unknown coverage separately.
40
40
 
41
+ The triage loop's failure handling uses this skill to diagnose ejections and default-branch failures.
42
+
41
43
  Consumer wrapper owns: workflow names, log retention, the CI provider command, retry policy, and
42
44
  scheduled automation.
@@ -38,7 +38,8 @@ a stack, and who may authorize a merge.
38
38
  - Work bottom-up. Write layers in stack order, and never start a layer before the one below it is
39
39
  in decent shape.
40
40
  - A lower layer is in decent shape when it is committed, its local checks have passed, its pull
41
- request is open with an updated body, and shepherding has started. Decent shape does not mean
41
+ request is open with an updated body, and shepherding has started (the worker's own pr-shepherd
42
+ poll, or a delegation to the triage loop). Decent shape does not mean
42
43
  green CI, ready for review, or merged.
43
44
  - Start the next dependent layer once the lower layer is in decent shape. Do not wait for merge,
44
45
  a ready-delay, or green CI.
@@ -83,10 +84,15 @@ a stack, and who may authorize a merge.
83
84
  - One worker per native stack implements that stack and runs its shepherd poll. The parent does
84
85
  not poll. It reconciles stacks, starts a worker, and carries merge questions to the human.
85
86
  - Start shepherding when the first owned pull request exists.
87
+ - The worker may instead delegate the stack to the triage loop: once every owned layer is ready it
88
+ posts the fixed literal comment `/shepherd` once, on the top pull request, and stops. The loop
89
+ then shepherds the whole stack with `pr-shepherd stack` and owns it. Never post `/shepherd` on a
90
+ lower layer.
86
91
  - Independent stacks run at the same time, one worker each. Dependent unmerged work is another
87
92
  layer of the same stack, not a second stack whose base is an unmerged head.
88
93
  - At most one poll process per stack. The parent does not run a second poll for the same stack.
89
- - This skill does not grant a merge. Merge authorization stays with the consumer.
94
+ - This skill does not grant a merge. Merging stays human-approved, or within the triage loop's
95
+ grant once it owns the stack. Merge authorization stays with the consumer.
90
96
 
91
97
  Consumer wrapper owns: default branch, stacking tool and commands, merge-selector syntax, layer cap,
92
98
  pull request description tool, ownership stamp format, and merge authorization.
@@ -17,7 +17,9 @@ layer is ready, and it is never the agent's own decision.
17
17
  3. Partition by ownership, using that topology read plus each member's body from `pulls/<N>` (the
18
18
  stack response has no bodies). Shepherd only owned pull requests. Never
19
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.
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.
21
23
  - The opened-by-me half is a durable remote fact when the repository's pull request description
22
24
  tool stamps each body with the authoring harness and session id. Compare the stamp with the
23
25
  current session id.