neo-agent-skills 0.1.39 → 0.1.40

package/.agents/skills/pr-review/references/merge-hold-tokens.md

@@ -1,12 +1,18 @@
 <!-- trigger: you approved a PR and now want to stop or suspend its merge -> read this before commenting -->
 
-# Withdrawing an approval — the merge-hold tokens
+# Withdrawing an approval
 
-An approval you have already submitted stays `APPROVED` on GitHub forever. `reviewDecision` is a
-flattened snapshot with no notion of supersession, so **saying "do not merge" in a comment does not
-retract it** — the PR keeps reporting merge-ready, and a human trusting that surface merges past you.
+An approval you have already submitted stays `APPROVED` on GitHub until you submit a newer review.
+**Saying "do not merge" in a comment does not retract it**: the PR keeps reporting merge-ready, and a
+human trusting that surface merges past you.
 
-To withdraw or suspend an approval, open the comment with one of these tokens on its own line
+**Withdraw with a review** when you have Required Actions and your family's round is unspent: submit
+`CHANGES_REQUESTED` naming them. It replaces your approval in GitHub's own `reviewDecision`, counts
+as your family's round (guide §6.3), and the clearing review is an ordinary Round 2 that
+dispositions those actions.
+
+**A token when no round is justified:** your round is spent, or no defect is established yet (the
+head moved and you have not re-read it). Open a comment with one of these tokens on its own line
 (the heading form is fine — `` ## `[MERGE_HOLD]` ``):
 
 | Token | Means |
@@ -14,18 +20,12 @@ To withdraw or suspend an approval, open the comment with one of these tokens on
 | `[MERGE_HOLD]` | Do not merge at this head. A prior approval is not a current authorization. |
 | `[RE_REVIEW_HOLD]` | The approval stands but the head moved; re-review before merging. |
 
-`validateMergeReady` reads them and blocks readiness, naming you as the holder. Two rules follow
-from that and both matter to you:
+`validateMergeReady` reads them and blocks readiness, naming you as the holder:
 
-- **Only a NEWER submitted review from you clears your hold.** A follow-up comment does not — not
-  even yours — so post a review when you are satisfied rather than replying "looks good now".
+- **Only a NEWER submitted review from you clears your hold.** A follow-up comment does not, not even
+  yours. A hold is not a round, so that review takes the full template.
 - **No other peer can clear it.** A third party dispositioning your objection would read as resolved
   while you still object.
 
 Matching is structural, not lexical: the token must open a line. Writing *"no reason to
-`[MERGE_HOLD]` this"* mid-sentence does **not** hold the PR, so you can discuss holds without
-issuing one. An unrecognised token is not a hold — use the two above or the gate will not see you.
-
-Dismissing the approval through GitHub's UI also works and is the stronger signal; the tokens exist
-because remembering to dismiss was load-bearing and nothing prompted it.
-
+`[MERGE_HOLD]` this"* mid-sentence does **not** hold the PR. An unrecognised token is not a hold.

package/.agents/skills/pr-review/references/pr-review-guide.md

@@ -324,8 +324,8 @@ After `[REJECTED_WITH_RATIONALE]` (`review-response-protocol.md §4`), re-escala
 
 ### 9.2 Withdrawing an approval
 
-A comment saying "do not merge" does **not** retract a submitted approval; open it with
-`[MERGE_HOLD]` or `[RE_REVIEW_HOLD]`: [`merge-hold-tokens.md`](./merge-hold-tokens.md).
+A "do not merge" comment does not retract an approval: use `CHANGES_REQUESTED` if a round is
+justified, else a hold token ([`merge-hold-tokens.md`](./merge-hold-tokens.md)).
 
 ## 10. A2A Comment-ID Hand-off (warm-cache review cycles)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-agent-skills",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Install the workflow substrate a cross-model AI team actually runs on: ticket intake, PR review gates, lane coordination and guards, versioned as a package. The skills Neo.mjs maintainers load every session — materialized into your repo, not copied.",
   "type": "module",
   "license": "MIT",