@ikon85/agent-workflow-kit 0.44.1 → 0.44.2

package/README.md

@@ -579,6 +579,13 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.44.2
+
+- changed: `src/cli.mjs`
+- changed: `src/commands/update.mjs`
+- changed: `src/consumer-migrations.json`
+- changed: `src/lib/consumerMigrations.mjs`
+
 ### 0.44.1
 
 - changed: `.claude/skills/skill-manifest.json`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.44.1",
+  "kitVersion": "0.44.2",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.44.1",
+  "version": "0.44.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/src/cli.mjs

@@ -16,7 +16,9 @@ import {
 } from './lib/contributionRouting.mjs';
 import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
 import { nonInteractiveUpdateDecision } from './lib/updateDecisions.mjs';
-import { renderRequiredMigration } from './lib/consumerMigrations.mjs';
+import {
+  renderConsumerAdvisory, renderRequiredMigration,
+} from './lib/consumerMigrations.mjs';
 import { currentAgentSurface } from './lib/agentSurfaceRegistry.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
@@ -242,6 +244,9 @@ function printPlan(r) {
     lines.push(renderRequiredMigration(action));
     lines.push(`  ${action.consequence} ${action.remediation}`);
   }
+  for (const advisory of r.advisories ?? []) {
+    lines.push(renderConsumerAdvisory(advisory));
+  }
   for (const owned of r.ownedDiffs ?? []) {
     lines.push(`${owned.state} ${owned.path}`);
     if (owned.binary) {

package/src/commands/update.mjs

@@ -14,7 +14,9 @@ import {
 import {
   inspectRoutingProfile, reconcileRoutingProfile,
 } from '../lib/routingProfile.mjs';
-import { evaluateConsumerMigrations } from '../lib/consumerMigrations.mjs';
+import {
+  evaluateConsumerAdvisories, evaluateConsumerMigrations,
+} from '../lib/consumerMigrations.mjs';
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
@@ -82,8 +84,12 @@ async function updatePackage(options) {
   const requiredMigrations = await evaluateConsumerMigrations({
     consumerRoot, kitVersion: pkg.kitVersion,
   });
+  const advisories = await evaluateConsumerAdvisories({
+    consumerRoot, kitVersion: pkg.kitVersion,
+  });
   const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, dryRun: true });
   preview.requiredMigrations = requiredMigrations;
+  preview.advisories = advisories;
   let previewFailure;
   try {
     Object.assign(preview, await previewReadinessAdoption({
@@ -109,6 +115,7 @@ async function updatePackage(options) {
     kitRoot, consumerRoot, preview, decisions, decide, transition,
   });
   resolvedPreview.requiredMigrations = requiredMigrations;
+  resolvedPreview.advisories = advisories;
   if (resolvedPreview.collisions.length) {
     return terminal(resolvedPreview, 'conflicted', history, transition);
   }
@@ -297,6 +304,7 @@ function reportOf(result) {
     },
     recommendation: updateRecommendation(result),
     requiredMigrations: result.requiredMigrations ?? [],
+    advisories: result.advisories ?? [],
   };
 }
 

package/src/consumer-migrations.json

@@ -1,4 +1,26 @@
 {
   "schemaVersion": 1,
-  "migrations": []
+  "migrations": [],
+  "advisories": [
+    {
+      "id": "retired-worktree-scratch-patterns",
+      "kind": "retired-key",
+      "retiredIn": "0.44.0",
+      "detect": {
+        "type": "json-key",
+        "path": "docs/agents/workflow-capabilities.json",
+        "key": ["worktreeLifecycle", "scratchPatterns"]
+      }
+    },
+    {
+      "id": "retired-wrapup-generated-artifact-patterns",
+      "kind": "retired-key",
+      "retiredIn": "0.44.0",
+      "detect": {
+        "type": "json-key",
+        "path": "docs/agents/workflow-capabilities.json",
+        "key": ["wrapup", "landingGeneratedArtifactPatterns"]
+      }
+    }
+  ]
 }

package/src/lib/consumerMigrations.mjs

@@ -10,6 +10,7 @@ import { compareSemver, parseSemver } from './semver.mjs';
 export const CONSUMER_MIGRATION_SCHEMA_VERSION = 1;
 const REGISTRY_URL = new URL('../consumer-migrations.json', import.meta.url);
 const DETECTORS = new Set(['json-key']);
+const ADVISORY_KINDS = new Set(['retired-key']);
 const TEXT_FIELDS = ['id', 'title', 'workflow', 'decision', 'consequence', 'remediation'];
 
 let shipped;
@@ -81,9 +82,28 @@ export function validateConsumerMigrationRegistry(registry) {
       detect: validateDetector(entry.detect, id),
     });
   });
+  const advisories = (registry.advisories ?? []).map((entry) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error('consumer migration registry: each advisory must be an object');
+    }
+    const id = text(entry.id, 'id', entry.id);
+    if (seen.has(id)) throw new Error(`consumer migration registry: duplicate entry id ${id}`);
+    seen.add(id);
+    if (!ADVISORY_KINDS.has(entry.kind)) {
+      throw new Error(`consumer migration registry: unsupported advisory kind ${entry.kind} (${id})`);
+    }
+    parseSemver(entry.retiredIn);
+    return Object.freeze({
+      id,
+      kind: entry.kind,
+      retiredIn: entry.retiredIn,
+      detect: validateDetector(entry.detect, id),
+    });
+  });
   return Object.freeze({
     schemaVersion: registry.schemaVersion,
     migrations: Object.freeze(migrations),
+    advisories: Object.freeze(advisories),
   });
 }
 
@@ -126,6 +146,12 @@ async function detect(consumerRoot, migration) {
   return hasDecision(document, migration.detect.key) ? null : 'missing-decision';
 }
 
+async function detectPresent(consumerRoot, advisory) {
+  const { document, reason } = await readConsumerJson(consumerRoot, advisory.detect.path);
+  if (reason) return false;
+  return hasDecision(document, advisory.detect.key);
+}
+
 /**
  * Report every registered migration the consumer still owes for `kitVersion`.
  * Read-only by construction: an outstanding decision is named, never written —
@@ -155,7 +181,36 @@ export async function evaluateConsumerMigrations({ consumerRoot, kitVersion, reg
   return pending;
 }
 
+/**
+ * Report obsolete consumer-owned configuration without mutating it. Advisory
+ * evaluation is fail-open: absent or unreadable project-layer evidence cannot
+ * prove that a retired key is present.
+ */
+export async function evaluateConsumerAdvisories({ consumerRoot, kitVersion, registry }) {
+  const source = registry ? validateConsumerMigrationRegistry(registry)
+    : await readShippedConsumerMigrationRegistry();
+  const advisories = [];
+  for (const advisory of source.advisories) {
+    if (compareSemver(kitVersion, advisory.retiredIn) < 0) continue;
+    if (!(await detectPresent(consumerRoot, advisory))) continue;
+    advisories.push({
+      id: advisory.id,
+      state: 'advisory',
+      kind: advisory.kind,
+      retiredIn: advisory.retiredIn,
+      path: advisory.detect.path,
+      key: advisory.detect.key.join('.'),
+    });
+  }
+  return advisories;
+}
+
 /** One rendering of the shared record, used by every human-facing update surface. */
 export function renderRequiredMigration({ id, workflow, path, decision }) {
   return `required migration: ${id} · ${workflow} · ${path} · ${decision}`;
 }
+
+export function renderConsumerAdvisory({ key, retiredIn }) {
+  return `update advisory: ${key} is no longer read since ${retiredIn}; `
+    + 'the key is consumer-owned and safe to delete.';
+}