@ikon85/agent-workflow-kit 0.36.3 → 0.36.5

package/README.md

@@ -445,6 +445,19 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.36.5
+
+- changed: `src/lib/updateCandidate.mjs`
+- changed: `src/lib/updateReconcile.mjs`
+- changed: `src/lib/verifyUpdateCandidate.mjs`
+- changed: `src/lib/verifyUpdateCandidateTransaction.mjs`
+
+### 0.36.4
+
+- changed: `scripts/release-delta-guard.mjs`
+- changed: `scripts/release-delta-guard.test.mjs`
+- changed: `src/lib/updateReconcile.mjs`
+
 ### 0.36.3
 
 - Metadata-only release.

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.36.3",
+  "kitVersion": "0.36.5",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -2683,7 +2683,7 @@
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
       "installRole": "maintainer",
-      "sha256": "1d2aab5f15bca25167b166b37232139916cf814e94de873fa74a653ecf9a4619",
+      "sha256": "566d7bae5526af2f8863d7a06dfa3016c9383b241b616cd43757eb7b46555895",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.36.3",
+  "version": "0.36.5",
   "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

@@ -1,6 +1,6 @@
 /** Block shipped changes whose version or checked manifest does not match a fresh build. */
 import { execFileSync } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -24,6 +24,12 @@ const describe = (delta) => ['added', 'removed', 'changed']
   .filter((kind) => delta[kind].length)
   .map((kind) => `${kind}: ${delta[kind].join(', ')}`).join('; ');
 
+function mergeDeltas(...deltas) {
+  return Object.fromEntries(['added', 'removed', 'changed'].map((kind) => [
+    kind, [...new Set(deltas.flatMap((delta) => delta[kind]))].sort(),
+  ]));
+}
+
 export function recommendBump(delta) {
   if (delta.removed.length) return 'major';
   if (delta.added.length) return 'minor';
@@ -40,7 +46,11 @@ function bumpKind(before, after) {
 }
 
 export function assessRelease(input) {
-  const delta = manifestDelta(input.baseManifest, input.builtManifest);
+  const bundleDelta = manifestDelta(input.baseManifest, input.builtManifest);
+  const packageDelta = input.basePackagePayload && input.currentPackagePayload
+    ? manifestDelta(input.basePackagePayload, input.currentPackagePayload)
+    : { added: [], removed: [], changed: [] };
+  const delta = mergeDeltas(bundleDelta, packageDelta);
   const checkedDrift = manifestDelta(input.checkedManifest, input.builtManifest);
   const payloadDrift = manifestDelta(input.builtManifest, input.payloadManifest);
   const errors = [];
@@ -99,6 +109,18 @@ export function resolveBaseTag({ repoRoot, baseVersion, tagPrefix = 'v' }) {
 }
 
 export async function packedPayloadManifest({ repoRoot, manifest }) {
+  const payload = await packedPackagePayload({ repoRoot });
+  const indexed = byPath(payload);
+  return {
+    kitVersion: manifest.kitVersion,
+    files: manifest.files.map((entry) => ({
+      ...entry,
+      sha256: indexed.get(entry.path),
+    })),
+  };
+}
+
+export async function packedPackagePayload({ repoRoot }) {
   const tempRoot = await mkdtemp(join(tmpdir(), 'awkit-package-payload-'));
   try {
     const packOutput = execFileSync(
@@ -110,17 +132,38 @@ export async function packedPayloadManifest({ repoRoot, manifest }) {
     await mkdir(unpackDir);
     execFileSync('tar', ['-xzf', join(tempRoot, filename), '-C', unpackDir]);
     return {
-      kitVersion: manifest.kitVersion,
-      files: await Promise.all(manifest.files.map(async (entry) => ({
-        ...entry,
-        sha256: sha256(await readFile(join(unpackDir, 'package', entry.path))),
-      }))),
+      files: await packageFiles(join(unpackDir, 'package')),
     };
   } finally {
     await rm(tempRoot, { recursive: true, force: true });
   }
 }
 
+async function packageFiles(root, relative = '') {
+  const files = [];
+  for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...await packageFiles(root, path));
+    else if (entry.isFile()) {
+      files.push({ path, sha256: sha256(await readFile(join(root, path))) });
+    }
+  }
+  return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+async function packagePayloadAtRef(repoRoot, ref) {
+  const archiveRoot = await mkdtemp(join(tmpdir(), 'awkit-package-base-'));
+  try {
+    const archive = execFileSync('git', ['archive', '--format=tar', ref], {
+      cwd: repoRoot, maxBuffer: 50 * 1024 * 1024,
+    });
+    execFileSync('tar', ['-xf', '-', '-C', archiveRoot], { input: archive });
+    return await packedPackagePayload({ repoRoot: archiveRoot });
+  } finally {
+    await rm(archiveRoot, { recursive: true, force: true });
+  }
+}
+
 export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } = {}) {
   repoRoot ??= join(dirname(fileURLToPath(import.meta.url)), '..');
   const distDir = await mkdtemp(join(tmpdir(), 'awkit-release-guard-'));
@@ -129,6 +172,7 @@ export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } =
     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;
+    const currentPackagePayload = await packedPackagePayload({ repoRoot });
     return assessRelease({
       baseVersion,
       baseTag: resolveBaseTag({ repoRoot, baseVersion }),
@@ -136,7 +180,15 @@ export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } =
       baseManifest: gitShowJson(repoRoot, baseRef, 'agent-workflow-kit.package.json'),
       checkedManifest: JSON.parse(await readFile(join(repoRoot, 'agent-workflow-kit.package.json'), 'utf8')),
       builtManifest,
-      payloadManifest: await packedPayloadManifest({ repoRoot, manifest: builtManifest }),
+      payloadManifest: {
+        kitVersion: builtManifest.kitVersion,
+        files: builtManifest.files.map((entry) => ({
+          ...entry,
+          sha256: byPath(currentPackagePayload).get(entry.path),
+        })),
+      },
+      basePackagePayload: await packagePayloadAtRef(repoRoot, baseRef),
+      currentPackagePayload,
     });
   } finally { await rm(distDir, { recursive: true, force: true }); }
 }

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

@@ -39,6 +39,25 @@ test('an unbumped shipped change is blocked with its concrete delta', () => {
   assert.match(result.errors.join('\n'), /version remains 1\.2\.3/);
 });
 
+test('an npm runtime change outside the Consumer manifest still requires a release', () => {
+  const consumer = { kitVersion: '1.2.3', files: [file('skill.md', 'same')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3',
+    currentVersion: '1.2.3',
+    baseManifest: consumer,
+    builtManifest: consumer,
+    checkedManifest: consumer,
+    payloadManifest: consumer,
+    basePackagePayload: { files: [file('src/cli.mjs', 'old')] },
+    currentPackagePayload: { files: [file('src/cli.mjs', 'new')] },
+  });
+
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.delta.changed, ['src/cli.mjs']);
+  assert.equal(result.recommendedBump, 'patch');
+  assert.match(result.errors.join('\n'), /version remains 1\.2\.3/);
+});
+
 test('dead checked-manifest entries are rejected', () => {
   const result = assessRelease({
     baseVersion: '1.2.3', currentVersion: '1.3.0',

package/src/lib/updateCandidate.mjs

@@ -351,6 +351,14 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
       throw new Error(`consumer changed during verification: ${path}`);
     }
   }
+  for (const snapshot of preview.userModifiedSnapshots ?? []) {
+    const target = join(consumerRoot, snapshot.path);
+    const current = await exists(target) ? await sha256File(target) : null;
+    const mode = current === null ? null : (await lstat(target)).mode & 0o777;
+    if (current !== snapshot.sha256 || mode !== snapshot.mode) {
+      throw new Error(`consumer changed during verification: ${snapshot.path}`);
+    }
+  }
 }
 
 /** Seed only newly declared, decision-free project-layer stubs in a staged candidate. */

package/src/lib/updateReconcile.mjs

@@ -143,7 +143,8 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     const userEdited = current !== prior.installedSha256;
     const currentMode = (await lstat(dest)).mode & 0o777;
     const upstreamChanged = file.sha256 !== prior.installedSha256
-      || currentMode !== file.mode;
+      || currentMode !== file.mode
+      || packageMetadataChanged(file, prior);
     if (!userEdited && upstreamChanged) {
       if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
       nextInstalled.push(entry(file, file.sha256));
@@ -155,6 +156,11 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     } else if (userEdited) {
       nextInstalled.push(withInstallRole(prior));
       result.userModified.push(file.path);
+      result.userModifiedSnapshots.push({
+        path: file.path,
+        sha256: current,
+        mode: currentMode,
+      });
     } else {
       nextInstalled.push(withInstallRole(prior));
       result.unchanged.push(file.path);
@@ -185,7 +191,8 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     }
   }
 
-  result.manifestChanged = consumer.installRole !== CONSUMER_INSTALL_ROLE ||
+  result.manifestChanged = consumer.kitVersion !== pkg.kitVersion ||
+    consumer.installRole !== CONSUMER_INSTALL_ROLE ||
     result.bridgeRetired.length > 0 ||
     nextInstalled.some((next) => installedIdx.get(next.path)?.installRole !== next.installRole);
 
@@ -200,6 +207,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], collisions: [], collisionResolutions: [], userModified: [],
+    userModifiedSnapshots: [],
     ownershipStates: [],
     bridgeRetired: [],
     added: [], deleted: [], keptDeleted: [], consumerOwned: [], manifestChanged: false,
@@ -227,6 +235,12 @@ function withInstallRole(installed, installRole = CONSUMER_INSTALL_ROLE) {
   return { ...installed, installRole };
 }
 
+function packageMetadataChanged(file, installed) {
+  return ['kind', 'ownerSkill', 'surface'].some(
+    (key) => (file[key] ?? null) !== (installed[key] ?? null),
+  );
+}
+
 async function projectExtensionEvidence(consumerRoot, path) {
   const match = /^docs\/agents\/skills\/([a-z0-9-]+)\.md$/.exec(path);
   if (!match) return null;

package/src/lib/verifyUpdateCandidate.mjs

@@ -61,11 +61,14 @@ export async function verifyCandidateMetadata(candidateRoot, context) {
     if (!state.isFile()) {
       throw new Error(`candidate invariant artifact: not a regular file ${entry.path}`);
     }
-    if (tracked.origin === KIT_ORIGIN && (state.mode & 0o777) !== entry.mode) {
+    const localSnapshot = (context.preview.userModifiedSnapshots ?? [])
+      .find(({ path }) => path === entry.path);
+    const expectedMode = localSnapshot?.mode ?? entry.mode;
+    if (tracked.origin === KIT_ORIGIN && (state.mode & 0o777) !== expectedMode) {
       throw new Error(`candidate invariant artifact: mode mismatch ${entry.path}`);
     }
-    const expectedHash = tracked.origin === CONSUMER_ORIGIN
-      ? tracked.installedSha256 : entry.sha256;
+    const expectedHash = localSnapshot?.sha256 ?? (tracked.origin === CONSUMER_ORIGIN
+      ? tracked.installedSha256 : entry.sha256);
     if (await sha256File(join(candidateRoot, entry.path)) !== expectedHash) {
       throw new Error(`candidate invariant artifact: hash mismatch ${entry.path}`);
     }

package/src/lib/verifyUpdateCandidateTransaction.mjs

@@ -44,7 +44,7 @@ export function verifyTransactionPreview(preview, installable, installed) {
   const installablePaths = new Set(installable.map(({ path }) => path));
   const owners = new Map();
   const actionSets = new Map();
-  for (const key of ['added', 'updated', 'deleted', 'generated', 'keptDeleted']) {
+  for (const key of ['added', 'updated', 'deleted', 'generated', 'keptDeleted', 'userModified']) {
     if (!Array.isArray(preview[key] ?? [])) {
       throw new Error(`candidate invariant transaction: ${key} must be an array`);
     }
@@ -54,12 +54,34 @@ export function verifyTransactionPreview(preview, installable, installed) {
       if (['added', 'updated'].includes(key) && !installablePaths.has(path)) {
         throw new Error(`candidate invariant transaction: unmanaged ${key} path ${path}`);
       }
+      if (key === 'userModified' && !installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: unmanaged userModified path ${path}`);
+      }
       if (key === 'deleted' && installablePaths.has(path)) {
         throw new Error(`candidate invariant transaction: deletes current package path ${path}`);
       }
     }
     actionSets.set(key, local);
   }
+  if (!Array.isArray(preview.userModifiedSnapshots ?? [])) {
+    throw new Error('candidate invariant transaction: userModifiedSnapshots must be an array');
+  }
+  const modified = actionSets.get('userModified');
+  const snapshots = new Set();
+  for (const snapshot of preview.userModifiedSnapshots ?? []) {
+    const path = snapshot?.path;
+    claimTransactionPath(path, 'userModifiedSnapshots', snapshots);
+    if (!modified.has(path)
+        || !HASH.test(snapshot.sha256 ?? '')
+        || !Number.isInteger(snapshot.mode)
+        || snapshot.mode < 0
+        || snapshot.mode > 0o777) {
+      throw new Error(`candidate invariant transaction: invalid local snapshot ${path}`);
+    }
+  }
+  if (snapshots.size !== modified.size) {
+    throw new Error('candidate invariant transaction: missing local snapshot');
+  }
   if (!Array.isArray(preview.bridgeRetired ?? [])) {
     throw new Error('candidate invariant transaction: bridgeRetired must be an array');
   }