vouchington-tooling 0.51.0 → 0.52.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.51.0",
+  "version": "0.52.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": [
         "blackboard",
@@ -24,7 +24,7 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "blackboard/SKILL.md"
     },
     {
@@ -36,7 +36,7 @@
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -50,26 +50,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -82,26 +82,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -133,53 +133,53 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -206,7 +206,7 @@
     {
       "name": "triage-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.13.0",
+      "pluginVersion": "0.13.1",
       "path": "triage-prs/SKILL.md",
       "prerequisites": [
         "pr-description",

package/skills/stacked-prs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacked-prs
-description: Work native GitHub stacks bottom-up and merge the ready prefix in one command; a ready lower layer does not freeze later work.
+description: Work native GitHub stacks bottom-up and prefer merging the whole stack in one command; drain the ready lower layers first only when the upper layers will clearly take longer.
 ---
 
 # Stacked pull requests
@@ -44,7 +44,8 @@ a stack, and who may authorize a merge.
   a ready-delay, or green CI.
 - On each shepherd result, act on the lowest owned layer that is not ready before any higher
   layer. Put each fix on the lowest layer that owns it. A bottom layer that reaches ready early
-  frees the ready prefix above it to merge in one command.
+  waits for the rest of the stack unless the layers above will clearly take longer; keep readying
+  them.
 - Before a command that adds layers to a stack, such as `gh stack add` or `gh stack link`, add the
   forge's open-layer count, plus every locally tracked layer not yet submitted, to every layer the
   command would add. `gh stack add` creates only a local branch, so repeated adds before a submit
@@ -54,20 +55,25 @@ a stack, and who may authorize a merge.
 - A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
   layer. Keep readying every other owned layer.
 
-## Merge the ready prefix
+## Merge the whole stack
 
-- Do not merge one layer at a time, and do not wait for the whole stack. Layers accumulate rebase
-  surface, CI cost, and review context, and drift against the default branch.
-- The ready prefix is the bottom-most open layer plus every consecutive layer above it that is
-  also ready and inside the human's approval. As soon as the bottom layer is ready, merge the ready
-  prefix with one command whose target is the prefix's top layer. When every layer is ready and
-  approved, the target is the top of the stack.
+- Prefer merging the whole stack at once: when every layer is ready and inside the human's
+  approval, merge it with one command whose target is the top layer. Never merge one layer at a
+  time, and never merge only the lower layers when every layer is ready.
+- Ready every layer in parallel so the stack reaches ready together. A ready lower layer waits
+  while the layers above are close behind (a poll or a ready-delay away).
+- Drain bottom-up only when the layers above will clearly take longer: a requested change or
+  `FIX_CODE` still open, a pending human review, a blocker, or CI far longer than the wait so far.
+  Then merge the ready lower layers in one command whose target is the highest ready layer, state
+  why in the report, and merge the rest together when it is ready.
+- Re-read every layer's readiness immediately before merging. If the whole stack is ready and
+  approved, the target is the top layer; never retarget past the approval.
 - Nothing in the stack merges on its own. Run the merge checks in
-  [Drain and keep track](references/drain.md#merge-the-ready-prefix) before each merge.
-- After a merge, GitHub retargets the next unmerged layer onto the default branch. That layer is
-  the new bottom.
+  [Drain and keep track](references/drain.md#merge-the-whole-stack) before each merge.
+- After a bottom-up drain, GitHub retargets the next unmerged layer onto the default branch. That
+  layer is the new bottom.
 - On a stall, or when a layer closes without merging, stop if the bottom layers are otherwise
-  ready. Report every layer and ask before merging that ready prefix.
+  ready. Report every layer and ask before draining them.
 - A stall blocks only layers that depend on it. Ready the others. Pause the whole drain only when
   nothing further can be readied without the blocked layer.
 

package/skills/stacked-prs/references/drain.md

@@ -1,8 +1,8 @@
 # Drain and keep track
 
 Shepherding a layer to ready and merging are different acts. The first covers every pull request
-the worker owns in the stack at once. The second lands the ready prefix in one command, and it is
-never the agent's own decision.
+the worker owns in the stack at once. The second lands the whole stack in one command once every
+layer is ready, and it is never the agent's own decision.
 
 ## Establish scope
 
@@ -89,48 +89,55 @@ When the owned set settles, present the stack bottom to top: each layer's number
 and whether it is ready or blocked and why. Never leave a ready bottom layer under a blocked upper
 layer without saying so.
 
-## Merge the ready prefix
+## Merge the whole stack
 
-The ready prefix is the bottom-most open layer plus every consecutive layer above it that is also
-ready and inside the approval. Its top layer is the merge target. A shepherd that prints a merge
-of its highest ready layer may name a layer above the approved range. Target the highest approved
-layer of the prefix instead; that is still one command.
+Prefer one merge of the whole stack: when every open layer is ready and inside the approval, the
+target is the top layer, and one command lands it and every layer below it. A shepherd that prints
+a merge for a lower layer does not change that; when the whole stack is ready, target the top.
+
+Drain bottom-up only when the layers above will clearly take longer than the ready lower layers:
+an open requested change or `FIX_CODE`, a pending human review, a blocker, or CI far longer than
+the wait so far. A layer a poll or a ready-delay away is not a reason. Then the target is the
+highest layer of the ready, approved run from the bottom, still one command, and the report says
+why the upper layers were left.
 
 Merge only on explicit human approval. The approval names what it covers: one layer, a range, or
-the whole stack. Approving the whole stack also covers the next ready prefix after an earlier
-merge. It does not cover a layer added after the approval. Ask before merging any layer outside
-it.
+the whole stack. Approving the whole stack also covers a bottom-up drain under the rule above. It
+does not cover a layer added after the approval. Ask before merging any layer outside it.
 
-Immediately before each approved merge, run these checks in order:
+Immediately before the approved merge, run these checks in order:
 
 1. `gh api repos/{owner}/{repo}/stacks/<target>` must return 404. `gh stack merge` resolves a bare
    number as a stack number first, then a pull request number. A 200 response means `--yes` would
    merge every layer of that stack. Stop and ask.
 2. Re-read topology. Confirm every layer from the bottom-most open layer up to the target is open,
-   ready, and inside the approval, with nothing broken below.
-3. For every layer in the prefix, capture `pulls/<N>.head.sha` before the final poll and after it.
+   ready, and inside the approval, with nothing broken below. Re-read every layer above the
+   target too. If those layers are all ready now and the approval covers them, retarget to the
+   highest of them and restart these checks from step 1 for the new target. Never retarget past
+   the approval; report the ready layers above it and ask.
+3. For every layer being merged, capture `pulls/<N>.head.sha` before the final poll and after it.
    They must match. A mismatch means a push landed inside the evaluation window: discard the
    verdict and poll again.
 4. `gh stack merge <target> --yes` with the repository's merge strategy. It lands the target and
-   every open layer below it, which is the ready prefix.
+   every open layer below it.
 5. Do not `gh stack sync` here. Return to step 2 of [Establish scope](#establish-scope) and
    re-read topology remotely: rebasing right after a merge can replay already-landed commits from
-   a stale local base ref. Keep shepherding the layers above. When the new bottom is ready, merge
-   the next ready prefix the same way. Before any local edit, rebase, or push on a remaining
-   layer, rerun the fetch and ahead/behind check in
+   a stale local base ref. After a bottom-up drain, keep shepherding the layers above and merge
+   the rest the same way, preferring the whole remainder at once. Before any local edit, rebase, or push
+   on a remaining layer, rerun the fetch and ahead/behind check in
    [Import a stack](gh-stack.md#import-a-stack-before-acting-on-it): GitHub rebases the next
    layer remotely, so local upper branches are stale until fast-forwarded. The drain is complete when no unmerged owned layer remains.
 
 The window between the last head read and the merge cannot be closed, because `gh stack merge`
 has no head-SHA pin. Branch protection and rulesets are evaluated when the merge runs, and stacks
 cannot bypass merge requirements. If the merge is rejected, re-read topology instead of retrying
-blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the prefix queues
+blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the layers queue
 together, and a failing layer is ejected along with the layers above it. The next topology
 re-read handles that.
 
 When you stop or are blocked (an unresolved escalation, an interrupt or pause, repeated fixes with
 no progress, or an external blocker), report each layer's number and state. If the bottom layers
-are ready, ask whether to merge that ready prefix before continuing.
+are ready, ask whether to drain them before continuing.
 
 ## Keep track: derive the ledger
 

package/skills/triage-prs/SKILL.md

@@ -137,11 +137,11 @@ Classify the outcome:
 - **Repository auto-merge disabled:** dispatch the shepherd, report that a manual merge is
   required, and leave auto-merge unchanged.
 - **Native GitHub stack:** shepherd the owned layers per
-  [stacked-prs](../stacked-prs/SKILL.md#ownership-and-workers) and merge the ready prefix per
-  [Merge the ready prefix](../stacked-prs/SKILL.md#merge-the-ready-prefix), within explicit human
+  [stacked-prs](../stacked-prs/SKILL.md#ownership-and-workers) and merge the whole stack per
+  [Merge the whole stack](../stacked-prs/SKILL.md#merge-the-whole-stack), within explicit human
   approval and only as far as this run's decisions cover. Resolve the full stack against the Step 1
-  scope and Step 3 decisions first. End the ready prefix below the first layer that is out of scope
-  or not `MERGE`; never shepherd or merge a layer this run did not review. GitHub has no
+  scope and Step 3 decisions first. A bottom-up drain ends below the first layer that is out of
+  scope or not `MERGE`; never shepherd or merge a layer this run did not review. GitHub has no
   auto-merge for stacks, and an armed auto-merge does not authorize the drain on its own.
 
 Do not add a second pass that polls the dispatch workflow. It ends once the session is accepted or