@ikon85/agent-workflow-kit 0.31.0 → 0.32.1

package/.claude/skills/setup-workflow/census.md

@@ -66,13 +66,20 @@ delegates this route to the shipped `census-update` contract and its focused
 `scripts/test_census_update_contract.test.mjs` proof; it does not reproduce
 activation, snapshots, or enforcement. Setup itself never calls `activateCensus`.
 
-Disable follows the ordered contract: remove the kit-owned hook, remove the
-kit-owned gate, then atomically replace only the profile's `enabled` value with
-`false`, preserving unknown keys, and verify `disabled` through
-`resolveCensusState`. Enforcement removal must finish before any profile
-mutation. Treat the choice document, local scanners, their tests, the profile,
-and the active snapshot as consumer-owned evidence. List those files and ask
-for separate deletion approval; without that approval, retain them.
+Activation owns durable enforcement: every focused test declared by the active
+profile must remain transitively reachable through one shared project-local
+census check entry point from both local CI and pre-push. `census-update`
+reconciles that narrow kit-owned census wiring idempotently and requires an
+executable wiring proof before it can report `current`; setup does not pre-wire
+the optional bootstrap state.
+
+Disable follows the ordered contract: remove only the kit-owned census wiring
+(including the kit-owned hook and gate block), then atomically replace only the
+profile's `enabled` value with `false`, preserving unknown keys, and verify
+`disabled` through `resolveCensusState`. Enforcement removal must finish before
+any profile mutation. Treat the choice document, local scanners, their tests,
+the profile, and the active snapshot as consumer-owned evidence. List those
+files and ask for separate deletion approval; without that approval, retain them.
 Setup never deletes consumer-owned files as part of disable.
 
 ## Setup report

package/README.md

@@ -305,7 +305,10 @@ any language works — map each role once, rename an option with one profile edi
 `init` records a sha256 of every file it installs. That's the line between the
 two: **edit any skill or script freely** — `update` detects your edits and backs
 them up rather than clobbering them. Your **project layer** (`docs/agents/*`, the
-board profile, `CLAUDE.md`) is created once and never touched by `update`.
+board profile, `CLAUDE.md`, `AGENTS.md`) remains consumer-owned. `update` may
+only apply a previewed, schema-driven, idempotent compatibility migration that
+fills missing evidence without rewriting an existing value; it verifies and
+rolls that migration back with the rest of the candidate.
 
 ## Updating & removing
 
@@ -348,6 +351,25 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 
 ## Release notes
 
+### 0.32.1
+
+- changed: `.agents/skills/census-update/SKILL.md`
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/census.md`
+- changed: `.claude/skills/census-update/SKILL.md`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/setup-workflow/census.md`
+- changed: `scripts/readiness.mjs`
+
+### 0.32.0
+
+- changed: `.agents/skills/audit-skills/SKILL.md`
+- changed: `.agents/skills/git-worktree-recover/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/audit-skills/SKILL.md`
+- changed: `.claude/skills/git-worktree-recover/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+
 ### 0.31.0
 
 - changed: `.agents/skills/board-to-waves/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.31.0",
+  "kitVersion": "0.32.1",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -27,7 +27,7 @@
       "ownerSkill": "audit-skills",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "f99bfc88bf23ad8279583653bdd7b63dcdcff010227258e4adf9e8df69384f7f",
+      "sha256": "662c4dec0c03716c468f202f73f52140ceba84e092873e6619692dde6d7ed0f2",
       "mode": 420,
       "origin": "kit"
     },
@@ -47,7 +47,7 @@
       "ownerSkill": "census-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "sha256": "b122fe2eb46c070696e38660b021411458b455b7a4e977174f943f2ce4c00819",
       "mode": 420,
       "origin": "kit"
     },
@@ -197,7 +197,7 @@
       "ownerSkill": "git-worktree-recover",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "71e043456586a59ddb83fb3fb1f98c8c269cd7575ade8616238bdb7e07fba4ba",
+      "sha256": "1628f47a5b5f71b7596ec070c8f038a3ce98abe007fce1b7f5c21ea40858124d",
       "mode": 420,
       "origin": "kit"
     },
@@ -377,7 +377,7 @@
       "ownerSkill": "kit-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "880766b7aef88760f6d79dd31c3333356eef060623fc053fc61f5d5611765bb8",
+      "sha256": "249a45761bcb95148b1567d1bc4d1b622b9b8c41519de4e67b1ef4e33c9ee9fd",
       "mode": 420,
       "origin": "kit"
     },
@@ -417,7 +417,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "39c0dd4d6f7663ab9a3602aab2869a881497604ca12f53f6ba0ca7debb0a4157",
+      "sha256": "7a94293b7db49f42497d34e6ae0fe9992ab1c770ae0766557618818d6d671c50",
       "mode": 420,
       "origin": "kit"
     },
@@ -567,7 +567,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "sha256": "d495758ae52bebd11c81bbe28fc5a1f9b614f972afdba55d1b728630d12cfee8",
       "mode": 420,
       "origin": "kit"
     },
@@ -1189,7 +1189,7 @@
       "ownerSkill": "audit-skills",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "80ab0f1910914f4bcb375bf63aa66a1297a0b873082d7cc4f386d0d931e6015f",
+      "sha256": "dce7c13e9b9c2eb6fe9028f69fe2fe2d48ad50546327c9d9c1232191425f1b7c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1209,7 +1209,7 @@
       "ownerSkill": "census-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "sha256": "b122fe2eb46c070696e38660b021411458b455b7a4e977174f943f2ce4c00819",
       "mode": 420,
       "origin": "kit"
     },
@@ -1419,7 +1419,7 @@
       "ownerSkill": "git-worktree-recover",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "435c3a32a0c31dbefc774d8f6caa30cae9f23026930292ea0c364d2115ed3e52",
+      "sha256": "3251c8db671286330e48748719e05ee3fdc0555d93d61d7fee3fc0e0d2868e92",
       "mode": 420,
       "origin": "kit"
     },
@@ -1659,7 +1659,7 @@
       "ownerSkill": "kit-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "880766b7aef88760f6d79dd31c3333356eef060623fc053fc61f5d5611765bb8",
+      "sha256": "249a45761bcb95148b1567d1bc4d1b622b9b8c41519de4e67b1ef4e33c9ee9fd",
       "mode": 420,
       "origin": "kit"
     },
@@ -1699,7 +1699,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "20a972d7c13f059b1fda4daaeb77da777c898620bf9ec6bf6dd19c31b7e41d90",
+      "sha256": "9690ec772a99131c225037dd4bca884e899c133a8e460c36b26a25d6c6c797e1",
       "mode": 420,
       "origin": "kit"
     },
@@ -1869,7 +1869,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "sha256": "d495758ae52bebd11c81bbe28fc5a1f9b614f972afdba55d1b728630d12cfee8",
       "mode": 420,
       "origin": "kit"
     },
@@ -2587,7 +2587,7 @@
       "path": "scripts/readiness.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "f5e8bc2e724f72d1aa9f94c4f8d87b8f4d3f9843797cd6ae59f48e563dc7c7fb",
+      "sha256": "9e7a9c6882e372f38383fe92d98ff2f818bae0be61a62301b7e9a6a2842dd21b",
       "mode": 493,
       "origin": "kit"
     },

package/package.json

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

@@ -99,22 +99,53 @@ function section(text, heading) {
   return body.join('\n').trim();
 }
 
-async function prodVerdict(root, paths) {
-  const bodies = [];
+export async function inspectProdSections(root, paths) {
+  const sections = [];
   for (const path of paths) {
     const text = await readText(root, path);
-    if (text === null) continue;
     const body = section(text, '## Prod');
-    bodies.push(body);
+    const problem = text === null ? 'missing-file'
+      : (body === null ? 'missing-section' : (body ? null : 'empty-section'));
+    sections.push({
+      path,
+      state: body === null ? 'missing' : (body ? 'valid' : 'invalid'),
+      body,
+      problem,
+    });
+  }
+  return sections;
+}
+
+async function prodEvidence(root, paths) {
+  const sections = await inspectProdSections(root, paths);
+  const present = sections.filter(({ problem }) => problem !== 'missing-file');
+  const valid = present.filter(({ state }) => state === 'valid');
+  const empty = present.filter(({ problem }) => problem === 'empty-section');
+  if (!valid.length && !empty.length) {
+    return {
+      verdict: 'absent',
+      diagnostics: sections.map(({ path, problem }) => ({ path, problem })),
+    };
+  }
+  const malformed = present.filter(({ state }) => state !== 'valid');
+  if (malformed.length) {
+    return {
+      verdict: 'invalid',
+      diagnostics: malformed.map(({ path, problem }) => ({ path, problem })),
+    };
+  }
+  const bodies = [...new Set(present.map(({ body }) => body))];
+  if (bodies.length > 1) {
+    return {
+      verdict: 'invalid',
+      diagnostics: present.map(({ path }) => ({ path, problem: 'divergent-section' })),
+    };
   }
-  if (!bodies.length) return 'absent';
-  if (bodies.every((body) => body === null)) return 'absent';
-  if (bodies.some((body) => !body)) return 'invalid';
-  return bodies.every((body) => body === bodies[0]) ? 'valid' : 'invalid';
+  return { verdict: 'valid', diagnostics: [] };
 }
 
 async function evidenceVerdict(root, evidence) {
-  if (evidence.type === 'prod-section') return prodVerdict(root, evidence.paths);
+  if (evidence.type === 'prod-section') return (await prodEvidence(root, evidence.paths)).verdict;
   if (evidence.type === 'runbook-reference') return runbookVerdict(root, evidence);
   const verdicts = await Promise.all((evidence.paths ?? []).map(async (path) => {
     const text = await readText(root, path);
@@ -129,14 +160,17 @@ async function evidenceVerdict(root, evidence) {
 }
 
 export async function evaluateCapability({ root, capability, decision }) {
-  const evidence = await evidenceVerdict(root, capability.evidence);
-  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false };
+  const prod = capability.evidence.type === 'prod-section'
+    ? await prodEvidence(root, capability.evidence.paths) : null;
+  const evidence = prod?.verdict ?? await evidenceVerdict(root, capability.evidence);
+  const diagnostics = prod?.diagnostics?.length ? { diagnostics: prod.diagnostics } : {};
+  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false, ...diagnostics };
   if (evidence === 'valid') return { state: 'ready', clearDecision: Boolean(decision) };
-  if (decision === 'pending') return { state: 'pending', clearDecision: false };
+  if (decision === 'pending') return { state: 'pending', clearDecision: false, ...diagnostics };
   if (decision === 'not-applicable' && capability.allowNotApplicable) {
-    return { state: 'not-applicable', clearDecision: false };
+    return { state: 'not-applicable', clearDecision: false, ...diagnostics };
   }
-  return { state: 'missing', clearDecision: false };
+  return { state: 'missing', clearDecision: false, ...diagnostics };
 }
 
 async function loadManifest(root) {

package/scripts/test_census_update_contract.test.mjs

@@ -169,6 +169,20 @@ test('census-update coordinates the stable foundation API without a second engin
   assert.match(skill, /\.census\/profile\.json/);
   assert.match(skill, /\.census\/active\.json/);
   assert.match(skill, /schemaVersion/);
+  assert.match(skill, /every `localScanners\[\]\.test`/);
+  assert.match(skill, /shared project-local census check entry point/i);
+  assert.match(
+    skill,
+    /It must execute every declared focused test,\s+and both local CI and pre-push must transitively reach that same entry point\./i,
+  );
+  assert.match(skill, /executable wiring test/i);
+  assert.match(skill, /missing or partial[\s\S]*failed/i);
+  assert.match(skill, /previous active\s+census bytes are unchanged/i);
+  assert.match(skill, /idempotent/i);
+
+  const setupCensus = await text('.claude/skills/setup-workflow/census.md');
+  assert.match(setupCensus, /activation[\s\S]*durable[\s\S]*local CI[\s\S]*pre-push/i);
+  assert.match(setupCensus, /remove only[\s\S]*kit-owned census wiring/i);
 });
 
 test('brownfield bootstrap activates real surface coverage with a separate behavior overview', async () => {

package/scripts/test_skill_readiness_contract.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import re
+import subprocess
 import unittest
 from pathlib import Path
 
@@ -12,7 +13,8 @@ MANIFEST_PATH = ROOT / ".claude/skills/skill-manifest.json"
 START = re.compile(r"^<!-- readiness:block ([a-z][A-Za-z0-9]*) -->$")
 END = "<!-- readiness:end -->"
 SURFACE = {"claude": ".claude/skills", "codex": ".agents/skills"}
-REQUIRED = {
+FIXTURES = ROOT / "test/fixtures/readiness"
+REQUIRED_V1 = {
     "to-prd": ["issueTracker", "managedBoard"],
     "to-issues": ["issueTracker", "managedBoard", "specCompleteness"],
     "to-waves": ["issueTracker", "managedBoard", "specCompleteness"],
@@ -23,7 +25,7 @@ REQUIRED = {
     "project-release": ["projectReleaseProfile"],
     "security-audit": ["securityAuditRunbook"],
 }
-OPTIONAL = {
+OPTIONAL_V1 = {
     "wrapup": {"deployReport": "prodTarget"},
     "orchestrate-wave": {"projectRecipe": "orchestrateWaveRecipe"},
     "spec-self-critique": {"projectEnrichment": "specCritiqueLayer"},
@@ -32,6 +34,74 @@ OPTIONAL = {
     "audit-skills": {"projectChecks": "auditSkillsLayer"},
     "git-worktree-recover": {"projectRecovery": "worktreeRecoveryLayer"},
 }
+COMPAT_UPDATE_SCRIPT = r"""
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [repo, fixturePath] = process.argv.slice(-2);
+const load = async (path) => import(pathToFileURL(join(repo, path)));
+const { init } = await load('src/commands/init.mjs');
+const { update } = await load('src/commands/update.mjs');
+const { checkSkill } = await load('scripts/readiness.mjs');
+const { makeKit, makeEmptyDir, cleanup } = await load('test/helpers.mjs');
+const { PACKAGE_MANIFEST_NAME, readManifest, writeManifest } = await load('src/lib/manifest.mjs');
+const { sha256 } = await load('src/lib/hash.mjs');
+const readinessPath = '.claude/skills/skill-manifest.json';
+const fixture = JSON.parse(await readFile(fixturePath, 'utf8'));
+const current = JSON.parse(await readFile(join(repo, readinessPath), 'utf8'));
+const previous = structuredClone(current);
+for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+  previous.skills[skill].readiness = {};
+}
+const kit = await makeKit({ '.claude/skills/to-prd/SKILL.md': 'fixture\n' });
+const consumer = await makeEmptyDir();
+async function setKitReadiness(manifest) {
+  const content = `${JSON.stringify(manifest, null, 2)}\n`;
+  const path = join(kit, readinessPath);
+  await mkdir(join(kit, '.claude/skills'), { recursive: true });
+  await writeFile(path, content);
+  const pkg = await readManifest(join(kit, PACKAGE_MANIFEST_NAME));
+  const entry = pkg.files.find(({ path: candidate }) => candidate === readinessPath);
+  if (entry) entry.sha256 = sha256(content);
+  else pkg.files.push({ path: readinessPath, kind: 'doc', sha256: sha256(content), mode: 0o644, origin: 'kit' });
+  await writeManifest(join(kit, PACKAGE_MANIFEST_NAME), pkg);
+}
+try {
+  await setKitReadiness(previous);
+  await init({ kitRoot: kit, consumerRoot: consumer });
+  for (const [relative, body] of Object.entries(fixture.readinessFixture.evidence)) {
+    const path = join(consumer, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, body);
+  }
+  const manifestPath = join(consumer, 'agent-workflow-kit.json');
+  const installed = await readManifest(manifestPath);
+  await writeManifest(manifestPath, {
+    ...installed,
+    readinessDecisions: fixture.readinessDecisions ?? {},
+    readinessFixture: fixture.readinessFixture,
+  });
+  const before = {};
+  for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+    before[skill] = await checkSkill({ root: consumer, skill, manifest: previous });
+  }
+  await setKitReadiness(current);
+  const identity = { name: '@ikon85/agent-workflow-kit', version: '0.1.0', tarballIntegrity: 'sha512-fixture', manifestSha256: 'fixture-manifest' };
+  const result = await update({
+    kitRoot: kit, consumerRoot: consumer,
+    releaseIdentities: { installed: { name: identity.name, version: identity.version, manifestSha256: identity.manifestSha256 }, npm: identity, github: identity },
+    verify: async () => {},
+  });
+  const afterManifest = await readManifest(manifestPath);
+  const after = {};
+  for (const skill of Object.keys(fixture.readinessFixture.skills)) {
+    after[skill] = await checkSkill({ root: consumer, skill, manifest: current });
+  }
+  console.log(JSON.stringify({ before, result, afterManifest, after }));
+} finally {
+  await cleanup(kit, consumer);
+}
+"""
 
 
 def load_manifest() -> dict:
@@ -100,11 +170,32 @@ class ReadinessContractTests(unittest.TestCase):
             blocks = list(declaration.get("optionalBlocks", {}))
             self.assertEqual(len(blocks), len(set(blocks)), skill)
 
-    def test_initial_enforcement_mapping_is_exact(self) -> None:
-        for skill, required in REQUIRED.items():
-            self.assertEqual(self.published[skill]["readiness"]["required"], required)
-        for skill, blocks in OPTIONAL.items():
-            self.assertEqual(self.published[skill]["readiness"]["optionalBlocks"], blocks)
+    def test_locked_v1_policy_cannot_disappear_from_the_manifest(self) -> None:
+        actual_required = {
+            skill: entry["readiness"]["required"]
+            for skill, entry in self.published.items()
+            if entry.get("readiness", {}).get("required")
+        }
+        actual_optional = {
+            skill: entry["readiness"]["optionalBlocks"]
+            for skill, entry in self.published.items()
+            if entry.get("readiness", {}).get("optionalBlocks")
+        }
+        self.assertEqual(actual_required, REQUIRED_V1)
+        self.assertEqual(actual_optional, OPTIONAL_V1)
+
+    def test_every_declared_consumer_has_the_standard_preflight(self) -> None:
+        consumers = {
+            skill: entry for skill, entry in self.published.items()
+            if entry.get("readiness")
+        }
+        self.assertGreater(len(consumers), 0)
+        for skill, entry in consumers.items():
+            expected = f"node scripts/readiness.mjs check --skill {skill} --json"
+            for surface in entry["surfaces"]:
+                path = ROOT / SURFACE[surface] / skill / "SKILL.md"
+                body = path.read_text(encoding="utf-8")
+                self.assertEqual(body.count(expected), 1, f"{surface}:{skill}")
 
     def test_markers_are_balanced_declared_and_surface_equal_when_activated(self) -> None:
         for skill, entry in self.published.items():
@@ -114,6 +205,7 @@ class ReadinessContractTests(unittest.TestCase):
                 path = ROOT / SURFACE[surface] / skill / "SKILL.md"
                 self.assertTrue(path.is_file(), f"missing published surface: {path}")
                 sequence = marker_sequence(path.read_text(encoding="utf-8"), declared)
+                self.assertEqual(set(sequence), declared, f"undeclared marker coverage: {surface}:{skill}")
                 sequences.append((surface, sequence))
             if len(sequences) > 1:
                 validate_surface_sequences([sequence for _, sequence in sequences])
@@ -134,6 +226,34 @@ class ReadinessContractTests(unittest.TestCase):
         with self.assertRaises(AssertionError):
             validate_surface_sequences([["projectEnrichment"], []])
 
+    def test_legacy_and_current_consumers_keep_previously_ready_skill_cores(self) -> None:
+        fixtures = sorted(FIXTURES.glob("*/agent-workflow-kit.json"))
+        self.assertEqual([path.parent.name for path in fixtures], ["current", "legacy"])
+        for fixture_path in fixtures:
+            fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+            scenario = fixture["readinessFixture"]
+            with self.subTest(fixture=fixture_path.parent.name):
+                run = subprocess.run(
+                    ["node", "--input-type=module", "-e", COMPAT_UPDATE_SCRIPT,
+                     str(ROOT), str(fixture_path)],
+                    check=True, capture_output=True, text=True,
+                )
+                proof = json.loads(run.stdout)
+                self.assertEqual(proof["result"]["state"], "applied")
+                self.assertEqual(proof["result"]["availability"]["newlyBlocked"], [])
+                for skill, expected in scenario["skills"].items():
+                    self.assertEqual(proof["before"][skill]["verdict"], "ready", skill)
+                    verdict = proof["after"][skill]
+                    self.assertNotEqual(verdict["verdict"], "blocked", skill)
+                    self.assertEqual(verdict["verdict"], expected["verdict"], skill)
+                    self.assertEqual(verdict["inactiveBlocks"], expected["inactiveBlocks"], skill)
+                self.assertEqual(
+                    proof["afterManifest"].get("readinessDecisions", {}),
+                    scenario["expectedDecisions"],
+                    "unavailable behavior must not manufacture a decision",
+                )
+                self.assertEqual(proof["afterManifest"]["readinessFixture"], scenario)
+
 
 if __name__ == "__main__":
     unittest.main()

package/src/cli.mjs

@@ -57,7 +57,7 @@ try {
     } else if (r.status === 'current') {
       p.outro(`aktuell · unchanged ${r.unchanged.length} · local modifications ${r.userModified.length}`);
     } else {
-      p.outro(`updated ${r.updated.length} · added ${r.added.length} · deleted ${r.deleted.length}`);
+      p.outro(`updated ${r.updated.length} · added ${r.added.length} · migrated ${r.migrated?.length ?? 0} · deleted ${r.deleted.length}`);
     }
   } else if (cmd === 'uninstall') {
     const ok = yes || (await p.confirm({ message: 'Remove kit-installed files?' })) === true;
@@ -82,7 +82,7 @@ function printPlan(r) {
   const lines = [];
   for (const k of [
     'added', 'updated', 'userModified', 'consumerOwned', 'unchanged',
-    'deleted', 'keptDeleted', 'collisions',
+    'deleted', 'keptDeleted', 'collisions', 'migrated',
   ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);

package/src/commands/update.mjs

@@ -55,6 +55,11 @@ export async function update(options) {
     Object.assign(preview, await previewReadinessAdoption({
       kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
     }));
+    preview.conflicts.push(...(preview.migrationConflicts ?? []).map((path) => ({
+      path,
+      kind: 'prod-section',
+      diff: 'Prod section differs from the other instruction surface or is malformed.',
+    })));
   } catch (error) {
     previewFailure = error;
   }
@@ -66,6 +71,9 @@ export async function update(options) {
     };
   }
   if (dryRun) return { ...preview, state: 'preview', history };
+  if (preview.migrationConflicts?.length) {
+    return terminal(preview, 'conflicted', history, transition);
+  }
   if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
   const resolvedPreview = await resolvePreview({
     kitRoot, consumerRoot, preview, decisions, decide, transition,
@@ -138,7 +146,13 @@ async function applyTransaction(context) {
       nextManifest: nextReadinessManifest,
     });
     preview.generated = readiness.generated;
+    preview.migrations = readiness.migrations;
+    preview.migrated = readiness.migrated;
+    preview.migrationConflicts = readiness.migrationConflicts;
     preview.availability = readiness.availability;
+    if (readiness.migrationConflicts.length) {
+      throw new Error(`Prod section migration conflict: ${readiness.migrationConflicts.join(', ')}`);
+    }
     if (readiness.incompatible.length) {
       throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
     }
@@ -180,6 +194,7 @@ function verifyRelease(identities, kitVersion) {
 
 function hasUpstreamDelta(result) {
   return result.manifestChanged ||
+    (result.migrations?.length ?? 0) > 0 ||
     result.added.length + result.updated.length + result.deleted.length > 0;
 }
 
@@ -205,9 +220,12 @@ async function terminal(result, state, history, transition) {
         conflicts: result.conflicts.map(({ path }) => path),
         keptDeleted: result.keptDeleted,
       },
-      recommendation: result.conflicts.length
-        ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
-        : null,
+      recommendation: result.migrationConflicts?.length
+        ? `Prod sections differ or are malformed in: ${result.migrationConflicts.join(', ')}. ` +
+          'Resolve them manually; no consumer file was changed.'
+        : (result.conflicts.length
+          ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
+          : null),
     },
   };
 }