@ikon85/agent-workflow-kit 0.34.3 → 0.34.4

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

@@ -110,3 +110,15 @@ manifest and compares it with both the base and the checked-in manifest. It
 blocks an unbumped shipped delta, a stale manifest, a too-small Semver bump, or
 a dead manifest entry and prints the concrete paths. CI runs the same command;
 there is no separately remembered shipped-file list.
+
+It also blocks a **version bump stacked on an untagged previous release**: if
+the base version carries no matching annotated tag, that release is still
+`awaiting-tag` and never became its own artifact. Tag and publish it first —
+never bury it under the next bump. A repository with no matching tag at all is
+bootstrapping its first release and is not blocked.
+
+A red release run does not prove nothing was published. Reconstruct the real
+state from the registry and the release before reacting; a stale local
+packument cache can answer "not published" for a package that is live, and the
+recovery route is the idempotent reconciler on the existing tag, never a new
+version.

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

@@ -110,3 +110,15 @@ manifest and compares it with both the base and the checked-in manifest. It
 blocks an unbumped shipped delta, a stale manifest, a too-small Semver bump, or
 a dead manifest entry and prints the concrete paths. CI runs the same command;
 there is no separately remembered shipped-file list.
+
+It also blocks a **version bump stacked on an untagged previous release**: if
+the base version carries no matching annotated tag, that release is still
+`awaiting-tag` and never became its own artifact. Tag and publish it first —
+never bury it under the next bump. A repository with no matching tag at all is
+bootstrapping its first release and is not blocked.
+
+A red release run does not prove nothing was published. Reconstruct the real
+state from the registry and the release before reacting; a stale local
+packument cache can answer "not published" for a package that is live, and the
+recovery route is the idempotent reconciler on the existing tag, never a new
+version.

package/README.md

@@ -387,6 +387,13 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.34.4
+
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+- changed: `scripts/release-delta-guard.mjs`
+- changed: `scripts/release-state.mjs`
+
 ### 0.34.3
 
 - changed: `.agents/skills/diagnose/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.3",
+  "kitVersion": "0.34.4",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
+      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
+      "sha256": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
       "mode": 420,
       "origin": "kit"
     },
@@ -2655,7 +2655,7 @@
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
       "installRole": "maintainer",
-      "sha256": "a51f30e7261e4efb0b5c5002f39353ef8e8be18a2bd39ad7139f1ce7a2e7e18d",
+      "sha256": "1d2aab5f15bca25167b166b37232139916cf814e94de873fa74a653ecf9a4619",
       "mode": 420,
       "origin": "kit"
     },
@@ -2671,7 +2671,7 @@
       "path": "scripts/release-state.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "23b4ffc77e9b499587fa563d067b1df9ae81b87a654d636281c7d139e5842687",
+      "sha256": "fd9f7f86e26ab3faba819e0c46e5e87c2dd3a84dc9a6111b4eceb4ebe6a3a344",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.3",
+  "version": "0.34.4",
   "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/release-delta-guard.mjs

@@ -57,6 +57,18 @@ export function assessRelease(input) {
   if (hasDelta(payloadDrift)) {
     errors.push(`npm package payload does not match built manifest (${describe(payloadDrift)})`);
   }
+  // Merging integrates a prepared version; only its annotated tag publishes it.
+  // Nothing else notices when that tag never arrives, so the next release PR
+  // would silently stack on top and the skipped version would never exist as
+  // its own artifact. Block that here, where a human is present anyway. A
+  // repository without any matching tag is bootstrapping, not stacking.
+  const { baseTag } = input;
+  if (baseTag?.repoHasTags && !baseTag.exists && input.currentVersion !== input.baseVersion) {
+    errors.push(
+      `previous release ${input.baseVersion} is still awaiting-tag (no ${baseTag.name} tag); `
+      + `tag and publish it before preparing ${input.currentVersion}`,
+    );
+  }
   const recommendedBump = recommendBump(delta);
   const actual = bumpKind(input.baseVersion, input.currentVersion);
   const rank = { patch: 1, minor: 2, major: 3 };
@@ -73,6 +85,19 @@ function gitShowJson(repoRoot, ref, path) {
   return JSON.parse(execFileSync('git', ['show', `${ref}:${path}`], { cwd: repoRoot, encoding: 'utf8' }));
 }
 
+function git(repoRoot, args) {
+  return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' }).trim();
+}
+
+export function resolveBaseTag({ repoRoot, baseVersion, tagPrefix = 'v' }) {
+  const name = `${tagPrefix}${baseVersion}`;
+  let exists = true;
+  try {
+    git(repoRoot, ['rev-parse', '-q', '--verify', `refs/tags/${name}`]);
+  } catch { exists = false; }
+  return { name, exists, repoHasTags: git(repoRoot, ['tag', '-l', `${tagPrefix}*`]) !== '' };
+}
+
 export async function packedPayloadManifest({ repoRoot, manifest }) {
   const tempRoot = await mkdtemp(join(tmpdir(), 'awkit-package-payload-'));
   try {
@@ -103,8 +128,10 @@ export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } =
     await buildKit({ repoRoot, distDir });
     const currentPackage = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
     const builtManifest = JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8'));
+    const baseVersion = gitShowJson(repoRoot, baseRef, 'package.json').version;
     return assessRelease({
-      baseVersion: gitShowJson(repoRoot, baseRef, 'package.json').version,
+      baseVersion,
+      baseTag: resolveBaseTag({ repoRoot, baseVersion }),
       currentVersion: currentPackage.version,
       baseManifest: gitShowJson(repoRoot, baseRef, 'agent-workflow-kit.package.json'),
       checkedManifest: JSON.parse(await readFile(join(repoRoot, 'agent-workflow-kit.package.json'), 'utf8')),

package/scripts/release-delta-guard.test.mjs

@@ -75,6 +75,51 @@ test('shipped content rejects downgrade and malformed version transitions', () =
   }
 });
 
+test('a bump on top of an untagged previous release is blocked', () => {
+  const current = { kitVersion: '1.3.0', files: [file('new.md', 'one')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.3.0',
+    baseManifest: { kitVersion: '1.2.3', files: [] }, builtManifest: current,
+    checkedManifest: current, payloadManifest: current,
+    baseTag: { name: 'v1.2.3', exists: false, repoHasTags: true },
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.errors.join('\n'), /1\.2\.3 is still awaiting-tag/);
+  assert.match(result.errors.join('\n'), /v1\.2\.3/);
+});
+
+test('a bump passes once the previous release carries its tag', () => {
+  const current = { kitVersion: '1.3.0', files: [file('new.md', 'one')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.3.0',
+    baseManifest: { kitVersion: '1.2.3', files: [] }, builtManifest: current,
+    checkedManifest: current, payloadManifest: current,
+    baseTag: { name: 'v1.2.3', exists: true, repoHasTags: true },
+  });
+  assert.equal(result.ok, true);
+});
+
+test('a never-tagged repository is not blocked from its first release', () => {
+  const current = { kitVersion: '0.1.0', files: [file('new.md', 'one')] };
+  const result = assessRelease({
+    baseVersion: '0.0.0', currentVersion: '0.1.0',
+    baseManifest: { kitVersion: '0.0.0', files: [] }, builtManifest: current,
+    checkedManifest: current, payloadManifest: current,
+    baseTag: { name: 'v0.0.0', exists: false, repoHasTags: false },
+  });
+  assert.equal(result.ok, true);
+});
+
+test('an untagged base blocks nothing while the version stays put', () => {
+  const same = { kitVersion: '1.2.3', files: [file('skill.md', 'one')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.2.3',
+    baseManifest: same, builtManifest: same, checkedManifest: same, payloadManifest: same,
+    baseTag: { name: 'v1.2.3', exists: false, repoHasTags: true },
+  });
+  assert.equal(result.ok, true);
+});
+
 test('actual npm payload drift is blocked even when checked and built manifests match', () => {
   const scrubbed = { kitVersion: '1.2.3', files: [file('skill.md', 'scrubbed')] };
   const result = assessRelease({

package/scripts/release-state.mjs

@@ -99,9 +99,13 @@ export function npmTarballFilename(name, version) {
   return `${name.replace(/^@/, '').replaceAll('/', '-')}-${version}.tgz`;
 }
 
-async function packedTarball(run, spec, directory, repoRoot) {
+async function packedTarball(run, spec, directory, repoRoot, { preferOnline = false } = {}) {
+  // A stale local packument answers ETARGET for a version that IS published.
+  // Read through it for registry specs: the status would otherwise report
+  // `awaiting-npm` for a released package and invite a second publish.
+  const cachePolicy = preferOnline ? ['--prefer-online'] : [];
   const { stdout } = await run(
-    'npm', ['pack', spec, '--json', '--pack-destination', directory], { cwd: repoRoot },
+    'npm', ['pack', spec, '--json', '--pack-destination', directory, ...cachePolicy], { cwd: repoRoot },
   );
   const result = JSON.parse(stdout);
   if (!Array.isArray(result) || result.length !== 1 || !result[0].filename) {
@@ -120,7 +124,7 @@ function releaseReaders(context) {
   async function npm(identity) {
     try {
       state.npmTarball = await packedTarball(
-        run, `${identity.name}@${identity.version}`, scratch, repoRoot,
+        run, `${identity.name}@${identity.version}`, scratch, repoRoot, { preferOnline: true },
       );
       return await releaseIdentityFromTarball(state.npmTarball);
     } catch (error) {

package/scripts/release-state.test.mjs

@@ -170,6 +170,28 @@ test('post-merge status inspection is read-only and reports the reconstructable
   assert.deepEqual(fixture.events, ['read npm', 'read github']);
 });
 
+test('the registry read bypasses the local packument cache, the local pack does not', async () => {
+  const calls = [];
+  const run = async (command, args) => {
+    calls.push({ command, args });
+    throw Object.assign(new Error('stubbed pack'), { stderr: 'stubbed pack' });
+  };
+  const probe = await createCommandAdapter({ repoRoot: REPO, run });
+  try {
+    await assert.rejects(() => probe.local());
+    await assert.rejects(() => probe.npm(identity));
+  } finally { await probe.dispose(); }
+
+  const [localPack, registryPack] = calls;
+  // A stale packument makes `npm pack <name>@<version>` answer ETARGET for a
+  // version that IS published — the status would then claim awaiting-npm and
+  // invite a second publish. The local pack must NOT reach for the registry.
+  assert.ok(registryPack.args.includes('--prefer-online'), 'registry read must bypass the cache');
+  assert.ok(registryPack.args.includes(`${identity.name}@${identity.version}`));
+  assert.ok(!localPack.args.includes('--prefer-online'), 'local pack must stay offline');
+  assert.ok(localPack.args.includes('.'));
+});
+
 test('local Claude overrides cannot change the packed release identity or enter the tarball', async () => {
   const fixture = await mkdtemp(join(tmpdir(), 'awkit-local-overrides-'));
   await mkdir(join(fixture, '.claude'), { recursive: true });