@ikon85/agent-workflow-kit 0.26.1 → 0.26.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "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/build-kit.mjs

@@ -45,7 +45,8 @@ async function shipBundle(repoRoot, distDir, bundleFiles) {
     const content = await copySource(repoRoot, distDir, file.src, file.dest, file.mode);
     entries.push({
       path: file.dest, kind: file.kind, ownerSkill: file.ownerSkill,
-      surface: file.surface, sha256: sha256(content), mode: file.mode, origin: 'kit',
+      surface: file.surface, installRole: file.installRole,
+      sha256: sha256(content), mode: file.mode, origin: 'kit',
     });
   }
   return entries.sort((a, b) => a.path.localeCompare(b.path));

package/scripts/build-kit.test.mjs

@@ -1,12 +1,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { buildKit } from './build-kit.mjs';
+import { init } from '../src/commands/init.mjs';
+import { CONSUMER_MANIFEST_NAME, readManifest } from '../src/lib/manifest.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PUBLIC_CENSUS_UNIT = JSON.parse(await readFile(
@@ -17,6 +19,7 @@ async function withBuild(fn) {
   try { return await fn(dist, await buildKit({ repoRoot: REPO, distDir: dist })); }
   finally { await rm(dist, { recursive: true, force: true }); }
 }
+const exists = (path) => access(path).then(() => true, () => false);
 
 test('historical v0.9.0 manifest remains an immutable golden fixture', async () => {
   const fixture = await readFile(join(REPO, 'test/fixtures/v0.9.0-agent-workflow-kit.package.json'));
@@ -33,6 +36,46 @@ test('current public SSOT builds deterministically', async () => {
   assert.equal(first, second);
 });
 
+test('current build assigns every file an explicit install role', async () => {
+  await withBuild(async (dist) => {
+    const manifest = JSON.parse(await readFile(join(dist, 'agent-workflow-kit.package.json'), 'utf8'));
+    assert.ok(manifest.files.every(({ installRole }) => ['consumer', 'maintainer'].includes(installRole)));
+    assert.deepEqual(
+      manifest.files.filter(({ installRole }) => installRole === 'maintainer').map(({ path }) => path),
+      [
+        '.agents/skills/kit-release/SKILL.md',
+        '.claude/skills/kit-release/SKILL.md',
+        'scripts/kit-release.mjs',
+        'scripts/release-delta-guard.mjs',
+      ],
+    );
+  });
+});
+
+test('a built kit installs no maintainer-only release surface into a consumer', async () => {
+  await withBuild(async (dist) => {
+    const consumer = await mkdtemp(join(tmpdir(), 'awkit-role-consumer-'));
+    try {
+      await init({ kitRoot: dist, consumerRoot: consumer });
+      const maintainerPaths = [
+        '.agents/skills/kit-release/SKILL.md',
+        '.claude/skills/kit-release/SKILL.md',
+        'scripts/kit-release.mjs',
+        'scripts/release-delta-guard.mjs',
+      ];
+      assert.deepEqual(
+        await Promise.all(maintainerPaths.map((path) => exists(join(consumer, path)))),
+        [false, false, false, false],
+      );
+      const manifest = await readManifest(join(consumer, CONSUMER_MANIFEST_NAME));
+      assert.equal(manifest.installRole, 'consumer');
+      assert.ok(manifest.installed.every(({ installRole }) => installRole === 'consumer'));
+    } finally {
+      await rm(consumer, { recursive: true, force: true });
+    }
+  });
+});
+
 test('current build contains post-tag public files and repository metadata', async () => {
   await withBuild(async (dist) => {
     await readFile(join(dist, '.agents/skills/codex-adapter-sync/SKILL.md'));

package/src/commands/init.mjs

@@ -6,6 +6,8 @@ import { stubSentinel } from '../lib/sentinel.mjs';
 import { STUB_TARGETS } from '../lib/bundle.mjs';
 import {
   readManifest, writeManifest, emptyConsumerManifest,
+  filesForInstallRole, CONSUMER_INSTALL_ROLE,
+  indexByPath,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
 
@@ -25,11 +27,19 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
   if (!pkg) throw new Error('kit package manifest not found');
   const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   const tracked = new Set((prior?.installed ?? []).map((e) => e.path));
+  const packageIdx = indexByPath(pkg, 'files');
 
   const result = { copied: [], skipped: [], seeded: [] };
   const installed = [];
 
-  for (const f of pkg.files) {
+  for (const entry of prior?.installed ?? []) {
+    const packageEntry = packageIdx.get(entry.path);
+    if (packageEntry?.installRole === CONSUMER_INSTALL_ROLE || !packageEntry?.installRole) continue;
+    if (!await exists(join(consumerRoot, entry.path))) continue;
+    installed.push({ ...entry, installRole: packageEntry.installRole });
+  }
+
+  for (const f of filesForInstallRole(pkg)) {
     const dest = join(consumerRoot, f.path);
     if (await exists(dest) && !tracked.has(f.path) && !force) {
       result.skipped.push(f.path); // pre-existing untracked → never-clobber
@@ -39,6 +49,7 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
     installed.push({
       path: f.path, kind: f.kind, ownerSkill: f.ownerSkill, surface: f.surface,
       installedSha256: await sha256File(dest), origin: 'kit',
+      installRole: CONSUMER_INSTALL_ROLE,
     });
     result.copied.push(f.path);
   }

package/src/commands/update.mjs

@@ -94,7 +94,8 @@ function verifyRelease(identities, kitVersion) {
 }
 
 function hasUpstreamDelta(result) {
-  return result.added.length + result.updated.length + result.deleted.length > 0;
+  return result.manifestChanged ||
+    result.added.length + result.updated.length + result.deleted.length > 0;
 }
 
 async function terminal(result, state, history, transition) {

package/src/lib/bundle.mjs

@@ -40,8 +40,8 @@ export const HELPER_FILES = [
   { path: 'scripts/wrapup-land.py', kind: 'script', mode: 0o755 },
   // Deterministic release preparation and its manifest-derived local/CI guard.
   // Both are invoked through package scripts by /kit-release.
-  { path: 'scripts/kit-release.mjs', kind: 'script', mode: 0o644 },
-  { path: 'scripts/release-delta-guard.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/kit-release.mjs', kind: 'script', mode: 0o644, installRole: 'maintainer' },
+  { path: 'scripts/release-delta-guard.mjs', kind: 'script', mode: 0o644, installRole: 'maintainer' },
   // Neutral publish/readback parity and externally reconstructable release state.
   // /kit-release uses these after merge; downstream update/consumer flows reuse
   // the parity primitive rather than growing a second registry/GitHub comparison.
@@ -161,7 +161,7 @@ const SURFACE_DIR = { claude: '.claude/skills', codex: '.agents/skills' };
 export function publishableSkills(manifest) {
   return Object.entries(manifest.skills)
     .filter(([, e]) => e.publish)
-    .map(([name, e]) => ({ name, surfaces: e.surfaces }));
+    .map(([name, e]) => ({ name, surfaces: e.surfaces, installRole: e.installRole ?? 'consumer' }));
 }
 
 async function walk(dir) {
@@ -188,17 +188,23 @@ async function walk(dir) {
  */
 export async function collectBundle(repoRoot, manifest) {
   const files = [];
-  for (const { name, surfaces } of publishableSkills(manifest)) {
+  for (const { name, surfaces, installRole } of publishableSkills(manifest)) {
     for (const surface of surfaces) {
       const base = join(SURFACE_DIR[surface], name);
       for (const abs of await walk(join(repoRoot, base))) {
         const rel = relative(repoRoot, abs);
-        files.push({ src: rel, dest: rel, kind: 'skill', ownerSkill: name, surface, mode: 0o644 });
+        files.push({
+          src: rel, dest: rel, kind: 'skill', ownerSkill: name, surface,
+          installRole, mode: 0o644,
+        });
       }
     }
   }
   for (const h of HELPER_FILES) {
-    files.push({ src: h.path, dest: h.path, kind: h.kind, mode: h.mode });
+    files.push({
+      src: h.path, dest: h.path, kind: h.kind,
+      installRole: h.installRole ?? 'consumer', mode: h.mode,
+    });
   }
   return { files, stubs: STUB_TARGETS };
 }

package/src/lib/manifest.mjs

@@ -4,12 +4,15 @@ import { writeAtomic } from './atomicWrite.mjs';
 // Two manifests (Codex R1#9 / R3#1):
 //  - package manifest (shipped with the kit): the desired-state file list.
 //  - consumer manifest (agent-workflow-kit.json in the target repo root): installed state.
-// Both model every file kind:
+// Package entries model every file kind and install role:
 //   { path, kind: 'skill'|'script'|'hook'|'template'|'doc', ownerSkill?, surface?,
-//     sha256, mode, origin: 'kit' }
+//     installRole: 'consumer'|'maintainer', sha256, mode, origin: 'kit' }
+// Consumer manifests record their top-level installRole and retain the role on
+// every installed entry, including edited legacy maintainer files kept in place.
 
 export const CONSUMER_MANIFEST_NAME = 'agent-workflow-kit.json';
 export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
+export const CONSUMER_INSTALL_ROLE = 'consumer';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -47,7 +50,14 @@ export async function writeManifest(path, obj) {
 }
 
 export function emptyConsumerManifest(kitVersion) {
-  return { kitVersion, installed: [] };
+  return { kitVersion, installRole: CONSUMER_INSTALL_ROLE, installed: [] };
+}
+
+/** Package entries without a role predate role-aware installs and remain consumer-owned. */
+export function filesForInstallRole(manifest, installRole = CONSUMER_INSTALL_ROLE) {
+  return (manifest?.files ?? []).filter(
+    (entry) => (entry.installRole ?? CONSUMER_INSTALL_ROLE) === installRole,
+  );
 }
 
 /** Map a manifest's file list (under `key`) by `path` for quick lookup. */

package/src/lib/updateReconcile.mjs

@@ -5,6 +5,7 @@ import { lineDiff, writeAtomic } from './atomicWrite.mjs';
 import { hookReferenced } from './settings.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
+  CONSUMER_INSTALL_ROLE, filesForInstallRole,
   indexByPath, readManifest, writeManifest,
 } from './manifest.mjs';
 
@@ -18,11 +19,13 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   if (!consumer) throw new Error('not initialised — run `init` first');
 
   const installedIdx = indexByPath(consumer, 'installed');
-  const pkgIdx = indexByPath(pkg, 'files');
+  const packageIdx = indexByPath(pkg, 'files');
+  const installable = filesForInstallRole(pkg);
+  const pkgIdx = indexByPath({ files: installable }, 'files');
   const result = emptyResult();
   const nextInstalled = [];
 
-  for (const file of pkg.files) {
+  for (const file of installable) {
     const dest = join(consumerRoot, file.path);
     const prior = installedIdx.get(file.path);
     const current = (await exists(dest)) ? await sha256File(dest) : null;
@@ -41,12 +44,12 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     } else if (userEdited && upstreamChanged) {
       const incoming = await readFile(join(kitRoot, file.path), 'utf8');
       result.conflicts.push({ path: file.path, diff: lineDiff(await readFile(dest, 'utf8'), incoming) });
-      nextInstalled.push(prior);
+      nextInstalled.push(withInstallRole(prior));
     } else if (userEdited) {
-      nextInstalled.push(prior);
+      nextInstalled.push(withInstallRole(prior));
       result.userModified.push(file.path);
     } else {
-      nextInstalled.push(prior);
+      nextInstalled.push(withInstallRole(prior));
       result.unchanged.push(file.path);
     }
   }
@@ -58,7 +61,11 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     const userEdited = current !== null && current !== prior.installedSha256;
     const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
     if (userEdited || referenced || !(await decide('delete', prior.path))) {
-      nextInstalled.push(prior);
+      const packageEntry = packageIdx.get(prior.path);
+      nextInstalled.push(withInstallRole(
+        prior,
+        packageEntry?.installRole ?? prior.installRole ?? CONSUMER_INSTALL_ROLE,
+      ));
       result.keptDeleted.push(prior.path);
     } else {
       if (!dryRun && current !== null) await rm(dest);
@@ -66,6 +73,9 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     }
   }
 
+  result.manifestChanged = consumer.installRole !== CONSUMER_INSTALL_ROLE ||
+    nextInstalled.some((next) => installedIdx.get(next.path)?.installRole !== next.installRole);
+
   if (!dryRun) {
     await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
       ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
@@ -77,13 +87,17 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], userModified: [],
-    added: [], deleted: [], keptDeleted: [],
+    added: [], deleted: [], keptDeleted: [], manifestChanged: false,
   };
 }
 
 function entry(file, installedSha256) {
   return {
     path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
-    installedSha256, origin: 'kit',
+    installedSha256, origin: 'kit', installRole: CONSUMER_INSTALL_ROLE,
   };
 }
+
+function withInstallRole(installed, installRole = CONSUMER_INSTALL_ROLE) {
+  return { ...installed, installRole };
+}