neo-agent-skills 0.1.39 → 0.1.41

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/.agents/skills/release-notes/references/release-notes-workflow.md

@@ -80,11 +80,11 @@ The authoring surface is **`.github/RELEASE_NOTES/v{version}.md`** in the engine
 
 1. **Pre-flight requires it** (`publish.mjs` §1): the release ERRORS if the file is absent. The version comes from `package.json` (bumped manually before the cut).
 2. The file is **committed and iterated on dev** ahead of the cut (§1) — the v13.0 lineage precedent, formalized.
-3. At cut time publish.mjs appends the **atomic-changelog-hash line** (post squash-to-main), parses the file — frontmatter stripped, first H1 extracted as the release title — and runs `gh release create` (cascades to npm).
+3. `publish.mjs finish` releases the merged note (frontmatter stripped, first H1 = title) with the **atomic-changelog-hash line** in the release body, via `gh release create` on the merge commit (cascades to npm).
 4. **publish.mjs keeps the file**: the authored note is the archive, and nothing re-materializes it. The SECOND runbook command, `npm run ai:post-release-sync` (fail-closed preflight; publish prints it), uploads the Knowledge Base and writes nothing into the engine. The corpus picks the release up from GitHub Releases.
 5. **Its guards:** `PublishReleaseNoteOrphan.spec.mjs` pins the authored path, the kept file and the flat layout; the release-note link scan in `Generate.spec.mjs` refuses mutable GitHub links.
 6. Known observation (epic-tracked): `buildScripts/docs/index/release.mjs` scans flat files recursively, so a committed staging note surfaces its version in `releases.json` when the docs index regenerates pre-cut.
-7. **The cut itself is human-only** (`§critical_gates`): agents prepare (notes, `prepare.mjs` validation, checklist) and hand off; `publish.mjs` execution and the dev→main release line belong to the operator.
+7. **The cut's one human step is merging the release PR** (`§critical_gates`): agents run `publish.mjs prepare --ticket <prep leaf> --body-file <body>` to open it, then `finish`. Re-runs resume; the cut record stays open until npm and the Portal verify.
 
 ## §7 Cut-readiness checklist — `MACHINE-ENFORCEABLE-CANDIDATE`
 
@@ -95,7 +95,7 @@ The notes epic's final iteration passes when:
 - [ ] Scope numbers regenerated at the cut boundary (§2 re-run) and reconciled in-document
 - [ ] Every claim anchor-verified (§4); the numbers-verify sweep (the `#14327` class, "sequence LAST") has run against the final text
 - [ ] The staging note is `.github/RELEASE_NOTES/v{version}.md`, matching `package.json`'s bump
-- [ ] The operator publish-handoff comment is posted on the cut-mechanics leaf (checklist + explicit "publish is yours")
+- [ ] `publish.mjs prepare --rehearse --ticket <prep leaf> --body-file <body>` passes
 
 ## Lifecycle position
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-agent-skills",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "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",