@ikon85/agent-workflow-kit 0.38.0 → 0.40.0

package/src/commands/update.mjs

@@ -14,6 +14,7 @@ import {
 import {
   inspectRoutingProfile, reconcileRoutingProfile,
 } from '../lib/routingProfile.mjs';
+import { evaluateConsumerMigrations } from '../lib/consumerMigrations.mjs';
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
@@ -75,7 +76,14 @@ async function updatePackage(options) {
     if (!decisions.has(key)) decisions.set(key, await decide(action, path));
     return decisions.get(key);
   };
+  // Required consumer migrations are decisions the consumer still owes; `update`
+  // never writes the consumer's project layer, so the pre-apply reading is also
+  // the post-apply state. Detected once, rendered by every surface.
+  const requiredMigrations = await evaluateConsumerMigrations({
+    consumerRoot, kitVersion: pkg.kitVersion,
+  });
   const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, dryRun: true });
+  preview.requiredMigrations = requiredMigrations;
   let previewFailure;
   try {
     Object.assign(preview, await previewReadinessAdoption({
@@ -92,7 +100,7 @@ async function updatePackage(options) {
       failure: { phase: 'staging', consumerState: 'unchanged' },
     };
   }
-  if (dryRun) return { ...preview, state: 'preview', history };
+  if (dryRun) return { ...preview, state: 'preview', history, report: reportOf(preview) };
   if (preview.migrationConflicts?.length) {
     return terminal(preview, 'conflicted', history, transition);
   }
@@ -100,6 +108,7 @@ async function updatePackage(options) {
   const resolvedPreview = await resolvePreview({
     kitRoot, consumerRoot, preview, decisions, decide, transition,
   });
+  resolvedPreview.requiredMigrations = requiredMigrations;
   if (resolvedPreview.collisions.length) {
     return terminal(resolvedPreview, 'conflicted', history, transition);
   }
@@ -266,28 +275,28 @@ function hasUpstreamDelta(result) {
 
 async function terminal(result, state, history, transition) {
   await transition(state);
+  return { ...result, state, history, report: reportOf(result) };
+}
+
+function reportOf(result) {
   return {
-    ...result,
-    state,
-    history,
-    report: {
-      unchanged: result.unchanged.length,
-      added: result.added.length,
-      updated: result.updated.length,
-      deleted: result.deleted.length,
-      localModified: result.userModified.length,
-      conflicts: result.conflicts.length,
-      keptDeleted: result.keptDeleted.length,
-      paths: {
-        added: result.added,
-        updated: result.updated,
-        deleted: result.deleted,
-        localModified: result.userModified,
-        conflicts: result.conflicts.map(({ path }) => path),
-        keptDeleted: result.keptDeleted,
-      },
-      recommendation: updateRecommendation(result),
+    unchanged: result.unchanged.length,
+    added: result.added.length,
+    updated: result.updated.length,
+    deleted: result.deleted.length,
+    localModified: result.userModified.length,
+    conflicts: result.conflicts.length,
+    keptDeleted: result.keptDeleted.length,
+    paths: {
+      added: result.added,
+      updated: result.updated,
+      deleted: result.deleted,
+      localModified: result.userModified,
+      conflicts: result.conflicts.map(({ path }) => path),
+      keptDeleted: result.keptDeleted,
     },
+    recommendation: updateRecommendation(result),
+    requiredMigrations: result.requiredMigrations ?? [],
   };
 }
 

package/src/consumer-migrations.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "migrations": [
+    {
+      "id": "wrapup-landing-artifact-policy",
+      "requiredFrom": "0.38.0",
+      "title": "Explicit landing-artifact policy",
+      "workflow": "setup-workflow",
+      "decision": "wrapup.landingGeneratedArtifactPatterns",
+      "detect": {
+        "type": "json-key",
+        "path": "docs/agents/workflow-capabilities.json",
+        "key": ["wrapup", "landingGeneratedArtifactPatterns"]
+      },
+      "consequence": "wrapup-land fails closed before landing until the decision is committed.",
+      "remediation": "Run setup-workflow, review the wrapup.landingGeneratedArtifactPatterns decision it writes into docs/agents/workflow-capabilities.json, and commit that profile change. kit-update never chooses cleanup patterns for you."
+    }
+  ]
+}

package/src/lib/bundle.mjs

@@ -16,6 +16,10 @@ export const HELPER_FILES = [
   // every board-specific value from docs/agents/board-sync.md through it, so it
   // MUST ship or they are broken-on-arrival. Library (imported, not run) → 0o644.
   { path: 'scripts/board_config.py', kind: 'script', mode: 0o644 },
+  // Offered board provisioning for /setup-workflow Section D: creates the
+  // project + Status/workflow fields, reads the opaque ids back, and writes the
+  // filled profile. Imports board_config (above). Invokable CLI → 0o755.
+  { path: 'scripts/board_bootstrap.py', kind: 'script', mode: 0o755 },
   // Pure Slices-table logic imported by board-sync.py for `anchor-sync` —
   // library (imported, not run) → 0o644. MUST ship or board-sync.py ImportErrors.
   { path: 'scripts/anchor_table.py', kind: 'script', mode: 0o644 },
@@ -127,6 +131,12 @@ export const HELPER_FILES = [
   { path: 'scripts/memory-lifecycle/setup.mjs', kind: 'script', mode: 0o644 },
   { path: 'assets/memory-templates/meta_decision_layer_choice.md', kind: 'template', mode: 0o644 },
   { path: 'assets/memory-templates/meta_memory_lifecycle.md', kind: 'template', mode: 0o644 },
+  // The one repository-relative glob dialect. Both capability cores below load
+  // it, so a consumer profile pattern selects the same paths for an advisory
+  // and for a cleanup decision. Also the reviewable migration check consumers
+  // run after setup or update, so a narrowed or widened pattern is named
+  // instead of silently changing deletion authority. Library + CLI → 0o755.
+  { path: 'scripts/profile_globs.py', kind: 'script', mode: 0o755 },
   // Profile-driven Worktree Lifecycle foundation. The setup adapter imports
   // core.py, while capabilities.json keeps the historical 8/8 denominator
   // explicit until the remaining hook and cleanup adapters are activated.
@@ -137,6 +147,12 @@ export const HELPER_FILES = [
   { path: 'scripts/worktree-lifecycle/session.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/capabilities.json', kind: 'doc', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/README.md', kind: 'doc', mode: 0o644 },
+  // Offered planning-artifact ignore rules for /setup-workflow Section A11.
+  // `.gitignore` is consumer-owned, so only an approved setup step may append
+  // the block — init/update reconciliation never reach this. plan-artifacts.json
+  // is the kit-owned declaration it reads. Invokable CLI → 0o755.
+  { path: 'scripts/worktree-lifecycle/plan-artifacts.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/worktree-lifecycle/ignore_seed.py', kind: 'script', mode: 0o755 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.

package/src/lib/consumerMigrations.mjs

@@ -0,0 +1,161 @@
+import { readFile } from 'node:fs/promises';
+import { validateConsumerFile } from './consumerPath.mjs';
+import { compareSemver, parseSemver } from './semver.mjs';
+
+/**
+ * Required consumer migrations are declarative, versioned data — never prose.
+ * A release that forces the consumer to commit a decision registers it here;
+ * `update` detects and reports the outstanding action but never performs it.
+ */
+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 TEXT_FIELDS = ['id', 'title', 'workflow', 'decision', 'consequence', 'remediation'];
+
+let shipped;
+
+function text(value, field, id) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`consumer migration registry: ${field} must be a non-empty string (${id})`);
+  }
+  return value;
+}
+
+function assertSafeRelativePath(path, id) {
+  if (typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\')
+      || path.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
+    throw new Error(`consumer migration registry: unsafe consumer path ${path} (${id})`);
+  }
+  return path;
+}
+
+function validateDetector(detect, id) {
+  if (!detect || typeof detect !== 'object' || Array.isArray(detect)) {
+    throw new Error(`consumer migration registry: detect is required (${id})`);
+  }
+  if (!DETECTORS.has(detect.type)) {
+    throw new Error(`consumer migration registry: unsupported detector ${detect.type} (${id})`);
+  }
+  if (!Array.isArray(detect.key) || !detect.key.length
+      || detect.key.some((segment) => typeof segment !== 'string' || !segment)) {
+    throw new Error(`consumer migration registry: detect.key must name the decision (${id})`);
+  }
+  return Object.freeze({
+    type: detect.type,
+    path: assertSafeRelativePath(detect.path, id),
+    key: Object.freeze([...detect.key]),
+  });
+}
+
+/** Reject a registry that could not be evaluated deterministically or safely. */
+export function validateConsumerMigrationRegistry(registry) {
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new Error('consumer migration registry: document must be an object');
+  }
+  if (registry.schemaVersion !== CONSUMER_MIGRATION_SCHEMA_VERSION) {
+    throw new Error(
+      `consumer migration registry: unsupported schemaVersion ${registry.schemaVersion}`,
+    );
+  }
+  if (!Array.isArray(registry.migrations)) {
+    throw new Error('consumer migration registry: migrations must be an array');
+  }
+  const seen = new Set();
+  const migrations = registry.migrations.map((entry) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error('consumer migration registry: each migration must be an object');
+    }
+    const id = text(entry.id, 'id', entry.id);
+    if (seen.has(id)) throw new Error(`consumer migration registry: duplicate migration id ${id}`);
+    seen.add(id);
+    parseSemver(entry.requiredFrom);
+    for (const field of TEXT_FIELDS) text(entry[field], field, id);
+    return Object.freeze({
+      id,
+      requiredFrom: entry.requiredFrom,
+      title: entry.title,
+      workflow: entry.workflow,
+      decision: entry.decision,
+      consequence: entry.consequence,
+      remediation: entry.remediation,
+      detect: validateDetector(entry.detect, id),
+    });
+  });
+  return Object.freeze({
+    schemaVersion: registry.schemaVersion,
+    migrations: Object.freeze(migrations),
+  });
+}
+
+/** The registry travels with the kit code that evaluates it, not with the consumer. */
+export async function readShippedConsumerMigrationRegistry() {
+  shipped ??= validateConsumerMigrationRegistry(JSON.parse(await readFile(REGISTRY_URL, 'utf8')));
+  return shipped;
+}
+
+async function readConsumerJson(consumerRoot, path) {
+  let resolved;
+  try {
+    resolved = await validateConsumerFile(consumerRoot, path);
+  } catch (error) {
+    if (error.message.startsWith('unsafe consumer path (not a regular file)')) {
+      return { reason: 'missing-file' };
+    }
+    throw error;
+  }
+  try {
+    return { document: JSON.parse(await readFile(resolved, 'utf8')) };
+  } catch {
+    return { reason: 'unreadable-file' };
+  }
+}
+
+function hasDecision(document, key) {
+  let node = document;
+  for (const segment of key) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)
+        || !Object.prototype.hasOwnProperty.call(node, segment)) return false;
+    node = node[segment];
+  }
+  return true;
+}
+
+async function detect(consumerRoot, migration) {
+  const { document, reason } = await readConsumerJson(consumerRoot, migration.detect.path);
+  if (reason) return reason;
+  return hasDecision(document, migration.detect.key) ? null : 'missing-decision';
+}
+
+/**
+ * Report every registered migration the consumer still owes for `kitVersion`.
+ * Read-only by construction: an outstanding decision is named, never written —
+ * inventing a cleanup pattern would hand the tool deletion authority.
+ */
+export async function evaluateConsumerMigrations({ consumerRoot, kitVersion, registry }) {
+  const source = registry ? validateConsumerMigrationRegistry(registry)
+    : await readShippedConsumerMigrationRegistry();
+  const pending = [];
+  for (const migration of source.migrations) {
+    if (compareSemver(kitVersion, migration.requiredFrom) < 0) continue;
+    const reason = await detect(consumerRoot, migration);
+    if (!reason) continue;
+    pending.push({
+      id: migration.id,
+      state: 'pending',
+      reason,
+      requiredFrom: migration.requiredFrom,
+      title: migration.title,
+      workflow: migration.workflow,
+      path: migration.detect.path,
+      decision: migration.decision,
+      consequence: migration.consequence,
+      remediation: migration.remediation,
+    });
+  }
+  return pending;
+}
+
+/** 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}`;
+}