@ikon85/agent-workflow-kit 0.34.5 → 0.34.6

package/.agents/skills/kit-release/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: kit-release
-description: "Prepare and integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
+description: "Prepare, integrate and publish a verified agent-workflow-kit release: one confirmed Semver authorizes the annotated version tag, then monitor npm/GitHub parity to released."
 ---
 
 # Kit Release
 
 Prepare a release deterministically. This skill owns the shipped-delta decision,
-metadata preparation, verification, and the separate post-merge publication
-gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
-never publishes to a registry or creates a GitHub release directly.
+metadata preparation, verification, and the post-merge publication intent. It
+delegates commit, branch push, PR, merge, and cleanup to wrapup. It never
+publishes to a registry or creates a GitHub release by hand — it records intent
+with the annotated tag and lets the trusted workflow publish.
+
+The release has **one** human gate: the confirmed Semver in step 2. Everything
+after it — merge, tag, publish, parity check — is the agent's to carry out.
 
 ## Workflow
 
@@ -33,8 +37,8 @@ never publishes to a registry or creates a GitHub release directly.
      Do not turn a narrower build-only or single-action request into this
      authority.
 
-   Both routes authorize one prepared target only. Neither authorizes
-   publication.
+   Either route authorizes exactly one target — and that authorization carries
+   through to its tag and publish. This is the release's single human gate.
 
 3. Prepare that authorized exact version:
 
@@ -52,21 +56,25 @@ never publishes to a registry or creates a GitHub release directly.
    `scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
    and cleanup. Do not reproduce those operations here.
 
-5. After merge, report the exact integrated version and commit as
-   `awaiting-tag`. Merging integrates the prepared release; it cannot start
-   publication. Creating and pushing the annotated `v<version>` tag requires a
-   **separate explicit confirmation** to publish that exact version. The
-   earlier Semver confirmation or AFK preparation mandate authorized metadata
-   preparation, not publication.
-
-6. After that confirmation, verify that the package version on current
-   `origin/main` is exactly `<version>`. Create a matching annotated
-   `v<version>` tag on that commit and push only that tag. A lightweight tag,
-   mismatching version, or commit outside canonical `main` is invalid release
-   intent. Never infer a tag target, move an existing tag, or tag an unmerged
-   commit.
-
-7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
+5. Publish. Merging integrates the prepared release; only the annotated tag
+   starts publication. Verify that the package version on current `origin/main`
+   is exactly `<version>`, then create and push the matching annotated
+   `v<version>` tag — **the confirmed Semver authorizes the whole release,
+   through tag and publish, so do this without asking again**. The target was
+   chosen once, at step 2; nothing between there and here produces information
+   a second gate could act on. Report the integrated commit as you tag it, not
+   as a question.
+
+   Publication is **irreversible** — npm versions cannot be reused, and the
+   unpublish window is narrow and breaks consumers. The safety lives in gates
+   that already ran, not in a prompt: `release:guard`, `kit:staleness`, the full
+   suite and `npm pack --dry-run` before merge, then the workflow's own tag
+   identity, package version, main ancestry and artifact checks after it. A
+   lightweight tag, a mismatching version, or a commit outside canonical `main`
+   is invalid release intent. Never infer a tag target, move an existing tag, or
+   tag an unmerged commit.
+
+6. Monitor the tag-triggered `release.yml` workflow and inspect its externally
    reconstructable state:
 
    ```sh

package/.claude/skills/kit-release/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: kit-release
-description: "Prepare and integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
+description: "Prepare, integrate and publish a verified agent-workflow-kit release: one confirmed Semver authorizes the annotated version tag, then monitor npm/GitHub parity to released."
 ---
 
 # Kit Release
 
 Prepare a release deterministically. This skill owns the shipped-delta decision,
-metadata preparation, verification, and the separate post-merge publication
-gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
-never publishes to a registry or creates a GitHub release directly.
+metadata preparation, verification, and the post-merge publication intent. It
+delegates commit, branch push, PR, merge, and cleanup to wrapup. It never
+publishes to a registry or creates a GitHub release by hand — it records intent
+with the annotated tag and lets the trusted workflow publish.
+
+The release has **one** human gate: the confirmed Semver in step 2. Everything
+after it — merge, tag, publish, parity check — is the agent's to carry out.
 
 ## Workflow
 
@@ -33,8 +37,8 @@ never publishes to a registry or creates a GitHub release directly.
      Do not turn a narrower build-only or single-action request into this
      authority.
 
-   Both routes authorize one prepared target only. Neither authorizes
-   publication.
+   Either route authorizes exactly one target — and that authorization carries
+   through to its tag and publish. This is the release's single human gate.
 
 3. Prepare that authorized exact version:
 
@@ -52,21 +56,25 @@ never publishes to a registry or creates a GitHub release directly.
    `scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
    and cleanup. Do not reproduce those operations here.
 
-5. After merge, report the exact integrated version and commit as
-   `awaiting-tag`. Merging integrates the prepared release; it cannot start
-   publication. Creating and pushing the annotated `v<version>` tag requires a
-   **separate explicit confirmation** to publish that exact version. The
-   earlier Semver confirmation or AFK preparation mandate authorized metadata
-   preparation, not publication.
-
-6. After that confirmation, verify that the package version on current
-   `origin/main` is exactly `<version>`. Create a matching annotated
-   `v<version>` tag on that commit and push only that tag. A lightweight tag,
-   mismatching version, or commit outside canonical `main` is invalid release
-   intent. Never infer a tag target, move an existing tag, or tag an unmerged
-   commit.
-
-7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
+5. Publish. Merging integrates the prepared release; only the annotated tag
+   starts publication. Verify that the package version on current `origin/main`
+   is exactly `<version>`, then create and push the matching annotated
+   `v<version>` tag — **the confirmed Semver authorizes the whole release,
+   through tag and publish, so do this without asking again**. The target was
+   chosen once, at step 2; nothing between there and here produces information
+   a second gate could act on. Report the integrated commit as you tag it, not
+   as a question.
+
+   Publication is **irreversible** — npm versions cannot be reused, and the
+   unpublish window is narrow and breaks consumers. The safety lives in gates
+   that already ran, not in a prompt: `release:guard`, `kit:staleness`, the full
+   suite and `npm pack --dry-run` before merge, then the workflow's own tag
+   identity, package version, main ancestry and artifact checks after it. A
+   lightweight tag, a mismatching version, or a commit outside canonical `main`
+   is invalid release intent. Never infer a tag target, move an existing tag, or
+   tag an unmerged commit.
+
+6. Monitor the tag-triggered `release.yml` workflow and inspect its externally
    reconstructable state:
 
    ```sh

package/README.md

@@ -387,6 +387,11 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.34.6
+
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+
 ### 0.34.5
 
 - changed: `.agents/skills/kit-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.5",
+  "kitVersion": "0.34.6",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
+      "sha256": "38a3df1f9d4b5573180dc67daba85eb3fd143ae3b60ca6dbfed3297d6a0855cd",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
+      "sha256": "38a3df1f9d4b5573180dc67daba85eb3fd143ae3b60ca6dbfed3297d6a0855cd",
       "mode": 420,
       "origin": "kit"
     },

package/docs/adr/0004-release-intent-is-a-version-tag.md

@@ -6,6 +6,17 @@ Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
 authorize deterministic reversible release preparation, but never the
 publication tag itself.
 
+Amended 2026-07-25 by issue #257: the confirmed Semver authorizes the whole
+release, through tag and publish. The separation of integration and publication
+below is unchanged — merging still cannot publish, and only an annotated tag
+records release intent — but that intent no longer waits for a second human
+confirmation. The maintainer chooses the version once; the agent then merges,
+tags, and monitors to `released`. The second gate had proven worse than no gate:
+it left prepared versions sitting in `awaiting-tag` until someone returned,
+which is how 0.34.2 was skipped and buried under 0.34.3 (#243). Safety stays in
+the gates that run regardless of who is watching — guard, staleness, suite,
+pack, and the workflow's own tag/version/ancestry validation.
+
 The release workflow currently publishes whenever a merge to `main` changes
 `package.json`. That keeps the canonical branch and npm close together, but it
 also makes an ordinary merge an irreversible public action whose consequence is
@@ -39,11 +50,13 @@ We decided that integration and publication are separate transitions:
 
 ## Consequences
 
-- A prepared version may temporarily exist on `main` in an `awaiting-tag` state.
-- An explicit AFK Wave/Program mandate may cover the deterministic reversible
-  metadata preparation and landing that it names. It never by itself authorizes
-  creating or pushing the publication tag; that irreversible action requires a
-  separate explicit confirmation.
+- A prepared version exists on `main` in an `awaiting-tag` state only for as
+  long as the agent needs to tag it — not until a human returns (amended by
+  #257).
+- The authorizing act is the confirmed Semver. An explicit AFK Wave/Program
+  mandate that names release preparation carries the same weight, and either
+  route reaches through tag and publish for that one target. A narrower
+  build-only or single-action request never becomes this authority.
 - A single-Wave mandate does not authorize the next Program Wave. A later
   explicit whole-Program mandate does authorize all planned Waves and remains in
   force across their boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.5",
+  "version": "0.34.6",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/kit-release.test.mjs

@@ -184,15 +184,21 @@ test('both release skill surfaces name only the owned scoped npm package', async
   }
 });
 
-test('an explicit AFK scope can authorize reversible preparation but never publication', async () => {
+// Amended by #257: one gate, at the Semver. The previous contract required a
+// second confirmation before the tag; that gate left prepared versions stranded
+// in `awaiting-tag` and is gone. What must survive is the narrowing rule — a
+// build-only request never becomes release authority.
+test('one confirmed Semver authorizes the release through tag and publish', async () => {
   const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
   const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
-  assert.equal(codex, claude);
+  assert.equal(codex.split('\n---\n')[1], claude.split('\n---\n')[1]);
   for (const body of [claude, codex]) {
     assert.match(body, /explicit AFK end-to-end mandate/i);
     assert.match(body, /deterministic recommendation/i);
-    assert.match(body, /reversible metadata preparation/i);
-    assert.match(body, /annotated `v<version>` tag[\s\S]*separate explicit confirmation/i);
+    assert.match(body, /annotated\s+`v<version>` tag/i);
+    assert.match(body, /confirmed Semver authorizes[\s\S]*without asking again/i);
+    assert.match(body, /narrower build-only or single-action request/i);
+    assert.doesNotMatch(body, /separate explicit confirmation/i);
   }
 });
 

package/scripts/test_release_authorization_contract.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Release-authorization contract (#257).
+
+The confirmed Semver authorizes the whole release, through tag and publish.
+One human gate at version choice, not two — the second gate stalled every
+release at `awaiting-tag` until someone returned, which is how 0.34.2 was
+skipped and buried under 0.34.3 (#243).
+
+What this pins:
+
+- Both `kit-release` surfaces carry the carried-through authorization, and
+  neither demands a separate confirmation before tagging.
+- The safety framing survives the change: irreversibility and the pre-tag
+  gates stay named, so autonomy never reads as "tag whatever".
+- `CLAUDE.md`, `AGENTS.md` and ADR-0004 agree with the skill.
+
+Run: python3 scripts/test_release_authorization_contract.py
+"""
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude/skills/kit-release/SKILL.md", ".agents/skills/kit-release/SKILL.md")
+ADR = "docs/adr/0004-release-intent-is-a-version-tag.md"
+DOCTRINE_FILES = ("CLAUDE.md", "AGENTS.md")
+# Wording that would reinstate the second gate anywhere in the release surface.
+SECOND_GATE = (
+    "separate explicit confirmation",
+    "separately confirmed publication intent",
+    "obtain a separate",
+    "After that confirmation",
+)
+
+
+def read(relative: str) -> str:
+    return (ROOT / relative).read_text(encoding="utf-8")
+
+
+def normalized(relative: str) -> str:
+    return " ".join(read(relative).split())
+
+
+class SkillSurfaceContract(unittest.TestCase):
+    def test_both_surfaces_carry_the_authorization_through_to_the_tag(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("confirmed Semver authorizes", prose)
+                self.assertIn("tag and publish", prose)
+                self.assertIn("without asking again", prose)
+
+    def test_no_surface_reinstates_a_second_confirmation_gate(self):
+        for surface in SURFACES:
+            for phrase in SECOND_GATE:
+                with self.subTest(surface=surface, phrase=phrase):
+                    self.assertNotIn(phrase, normalized(surface))
+
+    def test_autonomy_never_drops_the_safety_framing(self):
+        """Tagging stays irreversible and gated — the gates just move earlier."""
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("irreversible", prose)
+                self.assertIn("cannot be reused", prose)
+                for gate in ("release:guard", "kit:staleness", "npm pack"):
+                    self.assertIn(gate, prose)
+
+    def test_the_tag_remains_the_sole_publication_intent(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("Merging integrates", prose)
+                self.assertIn("annotated", prose)
+
+    def test_both_surfaces_stay_mirrored_below_the_frontmatter(self):
+        bodies = [read(surface).split("\n---\n", 1)[1] for surface in SURFACES]
+        self.assertEqual(bodies[0], bodies[1])
+
+
+class ProjectDoctrineContract(unittest.TestCase):
+    def test_root_convention_files_agree_with_the_skill(self):
+        for name in DOCTRINE_FILES:
+            with self.subTest(document=name):
+                prose = normalized(name)
+                self.assertIn("confirmed Semver authorizes", prose)
+                for phrase in SECOND_GATE:
+                    self.assertNotIn(phrase, prose)
+
+    def test_the_adr_records_an_amendment_instead_of_a_silent_rewrite(self):
+        prose = normalized(ADR)
+        self.assertIn("Amended", prose)
+        self.assertIn("2026-07-25", prose)
+        self.assertIn("confirmed Semver authorizes", prose)
+        # The original decision must remain readable, not be overwritten.
+        self.assertIn("version tag", prose)
+
+
+if __name__ == "__main__":
+    unittest.main()