@ikon85/agent-workflow-kit 0.30.0 → 0.32.0

package/scripts/test_skill_required_readiness.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Focused contract tests for required operational-skill readiness gates."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILLS = {
+    "triage": ("issueTracker", "managedBoard", "triageLabels"),
+    "local-ci": ("localCiRecipe",),
+    "project-release": ("projectReleaseProfile",),
+    "security-audit": ("securityAuditRunbook",),
+}
+
+
+def write(root: Path, relative: str, body: str) -> None:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+
+
+def snapshot(root: Path) -> dict[str, bytes]:
+    return {
+        str(path.relative_to(root)): path.read_bytes()
+        for path in root.rglob("*")
+        if path.is_file()
+    }
+
+
+def check(root: Path, skill: str) -> dict:
+    run = subprocess.run(
+        [
+            "node",
+            str(ROOT / "scripts/readiness.mjs"),
+            "check",
+            "--skill",
+            skill,
+            "--json",
+            "--root",
+            str(root),
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(run.stdout)
+
+
+def seed_manifest(root: Path, decisions: dict[str, str] | None = None) -> None:
+    write(
+        root,
+        ".claude/skills/skill-manifest.json",
+        (ROOT / ".claude/skills/skill-manifest.json").read_text(encoding="utf-8"),
+    )
+    write(
+        root,
+        "agent-workflow-kit.json",
+        json.dumps(
+            {
+                "kitVersion": "fixture",
+                "readinessContractVersion": 1,
+                "readinessDecisions": decisions or {},
+                "installed": [],
+            }
+        ),
+    )
+
+
+def seed_valid_evidence(root: Path) -> None:
+    sentinel = "<!-- setup-workflow: state=filled -->\nconfigured\n"
+    write(root, "docs/agents/issue-tracker.md", sentinel)
+    write(root, "docs/agents/triage-labels.md", sentinel)
+    board = {
+        "repo": "owner/repo",
+        "project": {"owner": "owner", "number": 1, "nodeId": "project"},
+        "fields": {
+            "status": {
+                "id": "status",
+                "options": {"Done": "done"},
+                "roles": {"done": "Done"},
+            },
+            "wave": "wave",
+            "cluster": "cluster",
+        },
+        "labels": {"readyForAgent": "ready-for-agent"},
+    }
+    write(
+        root,
+        "docs/agents/board-sync.md",
+        f"<!-- board-sync:profile -->\n```json\n{json.dumps(board)}\n```\n",
+    )
+    write(root, "docs/agents/skills/local-ci.md", sentinel)
+    write(
+        root,
+        "docs/agents/workflow-capabilities.json",
+        json.dumps(
+            {
+                "schemaVersion": 1,
+                "projectRelease": {
+                    "versionFiles": ["package.json"],
+                    "tagPrefix": "v",
+                },
+            }
+        ),
+    )
+    write(
+        root,
+        "docs/agents/skills/security-audit.md",
+        "<!-- setup-workflow: state=filled -->\n"
+        "Use `docs/security/audit-runbook.md`.\n",
+    )
+    write(root, "docs/security/audit-runbook.md", "# Audit\nConcrete checks.\n")
+
+
+def readiness_section(body: str) -> str:
+    match = re.search(
+        r"^## Required readiness preflight\n[\s\S]*?(?=^## |\Z)", body, re.MULTILINE
+    )
+    if not match:
+        raise AssertionError("required readiness preflight section is missing")
+    return match.group(0).strip()
+
+
+class RequiredReadinessSkillTests(unittest.TestCase):
+    def test_every_operational_skill_gates_before_mutation(self) -> None:
+        first_mutation = {
+            "triage": "## Triage a specific issue",
+            "local-ci": "## The two profiles",
+            "project-release": "## Workflow",
+            "security-audit": "## Workflow — two-model run",
+        }
+        for skill, capabilities in SKILLS.items():
+            with self.subTest(skill=skill):
+                body = (ROOT / ".claude/skills" / skill / "SKILL.md").read_text(
+                    encoding="utf-8"
+                )
+                heading = "## Required readiness preflight"
+                self.assertIn(heading, body)
+                self.assertLess(body.index(heading), body.index(first_mutation[skill]))
+                self.assertIn(
+                    f"node scripts/readiness.mjs check --skill {skill} --json", body
+                )
+                for capability in capabilities:
+                    self.assertIn(f"`{capability}`", body)
+                for state in ("missing", "pending", "not-applicable", "invalid"):
+                    self.assertIn(f"`{state}`", body)
+                self.assertIn("verdict is silent", body)
+                self.assertIn("Never ", body)
+                mirror = (ROOT / ".agents/skills" / skill / "SKILL.md").read_text(
+                    encoding="utf-8"
+                )
+                self.assertEqual(readiness_section(mirror), readiness_section(body))
+
+        project_release = (
+            ROOT / ".claude/skills/project-release/SKILL.md"
+        ).read_text(encoding="utf-8")
+        preflight = project_release.index(
+            "node scripts/readiness.mjs check --skill project-release --json"
+        )
+        helper = project_release.index("node scripts/project-release.mjs preview")
+        self.assertLess(preflight, helper)
+        self.assertIn("helper remains the authority", project_release)
+
+    def test_helper_blocks_missing_prerequisites_without_side_effects(self) -> None:
+        for skill, capabilities in SKILLS.items():
+            with self.subTest(skill=skill), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                before = snapshot(root)
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(
+                    {name: result["capabilities"][name]["state"] for name in capabilities},
+                    {name: "missing" for name in capabilities},
+                )
+                self.assertEqual(snapshot(root), before)
+
+    def test_helper_distinguishes_pending_not_applicable_invalid_and_ready(self) -> None:
+        invalid_evidence = {
+            "triage": ("docs/agents/issue-tracker.md", "<!-- setup-workflow: state=stub -->\n"),
+            "local-ci": ("docs/agents/skills/local-ci.md", "<!-- setup-workflow: state=stub -->\n"),
+            "project-release": ("docs/agents/workflow-capabilities.json", "{}\n"),
+            "security-audit": (
+                "docs/agents/skills/security-audit.md",
+                "<!-- setup-workflow: state=filled -->\nno project runbook\n",
+            ),
+        }
+        for skill, capabilities in SKILLS.items():
+            capability = capabilities[0]
+            with self.subTest(skill=skill, state="pending"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root, {capability: "pending"})
+                self.assertEqual(check(root, skill)["capabilities"][capability]["state"], "pending")
+
+            with self.subTest(skill=skill, state="invalid"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                seed_valid_evidence(root)
+                write(root, *invalid_evidence[skill])
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(result["capabilities"][capability]["state"], "invalid")
+
+            with self.subTest(skill=skill, state="ready"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                seed_valid_evidence(root)
+                before = snapshot(root)
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "ready")
+                self.assertTrue(
+                    all(item["state"] == "ready" for item in result["capabilities"].values())
+                )
+                self.assertEqual(snapshot(root), before)
+
+        with self.subTest(skill="triage", state="not-applicable"), tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            seed_manifest(root, {"managedBoard": "not-applicable"})
+            seed_valid_evidence(root)
+            (root / "docs/agents/board-sync.md").unlink()
+            result = check(root, "triage")
+            self.assertEqual(result["verdict"], "blocked")
+            self.assertEqual(result["capabilities"]["managedBoard"]["state"], "not-applicable")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_setup_workflow_seeds.py

@@ -213,6 +213,28 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_prod_readiness_choice_and_transaction_contract_is_complete(self):
+        for surface in (".claude", ".agents"):
+            text = (REPO / surface / "skills/setup-workflow/SKILL.md").read_text(
+                encoding="utf-8"
+            )
+            for token in (
+                "Configure now", "Configure later",
+                "decision set prodTarget pending",
+                "wrapup.deployReport omitted (prodTarget pending)",
+                "`prodTarget` does not permit this choice",
+                "Preview the exact local `## Prod` replacement",
+                "external mutation retains its own separate",
+                "activeBlocks` must be exactly `[\"deployReport\"]`",
+            ):
+                self.assertIn(token, text, f"{surface} missing {token!r}")
+            preserve = re.search(
+                r"Preserve each file's\s+`## Workflow` and `## Agent skills` "
+                r"blocks byte-for-byte",
+                text,
+            )
+            self.assertIsNotNone(preserve, surface)
+
     def test_census_effect_contract_executes_every_transition_and_repeats_without_writes(self):
         effects = load_census_setup_effects()
         self.assertEqual(

package/src/cli.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import * as p from '@clack/prompts';
 import { init } from './commands/init.mjs';
-import { update } from './commands/update.mjs';
+import { renderUpdateFailure, update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { setOwnership } from './commands/own.mjs';
@@ -49,7 +49,7 @@ try {
     });
     printPlan(r);
     for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
-    if (r.state === 'failed') throw new Error(`candidate update failed: ${r.error}`);
+    if (r.state === 'failed') throw new Error(renderUpdateFailure(r));
     if (r.state === 'conflicted') {
       p.note(r.report.recommendation, 'recommendation');
       p.outro(`not applied · conflicts ${r.conflicts.length}`);
@@ -86,6 +86,14 @@ function printPlan(r) {
   ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
+  if (r.availability) {
+    for (const [key, label] of [
+      ['newlyAvailable', 'newly available'], ['newlyDegraded', 'newly degraded'],
+      ['newlyBlocked', 'newly blocked'], ['stillUnresolved', 'still unresolved'],
+    ]) {
+      lines.push(`${label}: ${r.availability[key].join(', ') || 'none'}`);
+    }
+  }
   for (const owned of r.ownedDiffs ?? []) {
     lines.push(`${owned.state} ${owned.path}`);
     if (owned.binary) {

package/src/commands/update.mjs

@@ -1,7 +1,9 @@
 import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
-import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
+import {
+  activateCandidate, adoptReadinessCandidate, readReadinessManifest, stageConsumer, verifyCandidate,
+} from '../lib/updateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
@@ -9,6 +11,12 @@ import {
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
+export function renderUpdateFailure(result) {
+  const failure = result.failure ?? { phase: 'unknown', consumerState: 'unknown' };
+  return `candidate update failed · phase: ${failure.phase} · ` +
+    `consumerState: ${failure.consumerState} · ${result.error}`;
+}
+
 /**
  * Transactionally reconcile a consumer with a parity-proven kit release.
  * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
@@ -16,7 +24,8 @@ const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 export async function update(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
-    releaseIdentities, verify = verifyCandidate, signal, onState = () => {}, resumeFrom,
+    releaseIdentities, verify = verifyCandidate, activate = activateCandidate,
+    signal, onState = () => {}, resumeFrom,
   } = options;
   const history = [];
   const transition = async (state) => { history.push(state); await onState(state); };
@@ -30,6 +39,8 @@ export async function update(options) {
     throw new Error('not initialised — run `init` first');
   }
   const consumerManifestBefore = await readFile(consumerManifestPath);
+  const priorReadinessManifest = await readReadinessManifest(consumerRoot);
+  const nextReadinessManifest = await readReadinessManifest(kitRoot);
 
   const decisions = new Map();
   const choosePreview = async (action, path) => {
@@ -39,7 +50,21 @@ export async function update(options) {
     return decisions.get(key);
   };
   const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, dryRun: true });
+  let previewFailure;
+  try {
+    Object.assign(preview, await previewReadinessAdoption({
+      kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
+    }));
+  } catch (error) {
+    previewFailure = error;
+  }
   await transition('preview');
+  if (previewFailure) {
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: previewFailure.message,
+      failure: { phase: 'staging', consumerState: 'unchanged' },
+    };
+  }
   if (dryRun) return { ...preview, state: 'preview', history };
   if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
   const resolvedPreview = await resolvePreview({
@@ -52,11 +77,28 @@ export async function update(options) {
     return { ...await terminal(resolvedPreview, 'applied', history, transition), status: 'current' };
   }
   return applyTransaction({
-    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   });
 }
 
+async function previewReadinessAdoption(context) {
+  const { kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest } = context;
+  const candidateRoot = await stageConsumer(consumerRoot);
+  try {
+    await reconcile({
+      kitRoot, consumerRoot: candidateRoot,
+      decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
+    });
+    return await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+  } finally {
+    await rm(candidateRoot, { recursive: true, force: true });
+  }
+}
+
 async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decide, transition }) {
   if (preview.deleted.length || preview.keptDeleted.length || preview.collisions.length) {
     await transition('awaiting_decision');
@@ -73,11 +115,12 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
 
 async function applyTransaction(context) {
   const {
-    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   } = context;
   let candidateRoot = resumeFrom;
   let keepCandidate = false;
+  let phase = 'staging';
   try {
     await transition('staging');
     if (candidateRoot && preview.collisionResolutions.length) {
@@ -90,6 +133,16 @@ async function applyTransaction(context) {
         decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
+    const readiness = await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+    preview.generated = readiness.generated;
+    preview.availability = readiness.availability;
+    if (readiness.incompatible.length) {
+      throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
+    }
+    phase = 'verification';
     await transition('verifying');
     const abort = async () => {
       keepCandidate = true;
@@ -98,12 +151,16 @@ async function applyTransaction(context) {
     if (signal?.aborted) return abort();
     await verify(candidateRoot);
     if (signal?.aborted) return abort();
-    await activateCandidate({
+    phase = 'activation';
+    await activate({
       candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
     });
     return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
   } catch (error) {
-    return { ...await terminal(preview, 'failed', history, transition), error: error.message };
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: error.message,
+      failure: { phase, consumerState: error.consumerState ?? 'unchanged' },
+    };
   } finally {
     if (candidateRoot && !keepCandidate) await rm(candidateRoot, { recursive: true, force: true });
   }

package/src/lib/updateCandidate.mjs

@@ -6,7 +6,13 @@ import { promisify } from 'node:util';
 import { writeAtomic } from './atomicWrite.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
 import { sha256File } from './hash.mjs';
-import { CONSUMER_MANIFEST_NAME, indexByPath, readManifest } from './manifest.mjs';
+import { stubSentinel } from './sentinel.mjs';
+import { STUB_TARGETS } from './bundle.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
+  indexByPath, readManifest, writeManifest,
+} from './manifest.mjs';
+import { checkSkill, evaluateCapability } from '../../scripts/readiness.mjs';
 
 const run = promisify(execFile);
 const exists = (path) => access(path).then(() => true, () => false);
@@ -30,9 +36,11 @@ export async function stageConsumer(consumerRoot) {
 /** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
 export async function activateCandidate({
   candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+  afterGenerated = async () => {},
 }) {
   const changed = [...preview.added, ...preview.updated];
-  const touched = [...changed, ...preview.deleted, CONSUMER_MANIFEST_NAME];
+  const generated = preview.generated ?? [];
+  const touched = [...changed, ...generated, ...preview.deleted, CONSUMER_MANIFEST_NAME];
   const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!currentManifest.equals(consumerManifestBefore)) {
     throw new Error('consumer manifest changed during verification');
@@ -43,6 +51,13 @@ export async function activateCandidate({
       throw new Error(`candidate hash mismatch: ${path}`);
     }
   }
+  const candidateManifest = await readManifest(join(candidateRoot, CONSUMER_MANIFEST_NAME));
+  const candidateInstalled = indexByPath(candidateManifest, 'installed');
+  for (const path of generated) {
+    if (await sha256File(join(candidateRoot, path)) !== candidateInstalled.get(path)?.installedSha256) {
+      throw new Error(`generated candidate hash mismatch: ${path}`);
+    }
+  }
   await assertConsumerStillMatchesPreview(consumerRoot, preview);
   const rollback = new Map();
   for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
@@ -50,6 +65,10 @@ export async function activateCandidate({
     for (const path of changed) {
       await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
     }
+    for (const path of generated) {
+      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+    }
+    await afterGenerated();
     for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
     await writeAtomic(
       join(consumerRoot, CONSUMER_MANIFEST_NAME),
@@ -57,6 +76,7 @@ export async function activateCandidate({
     );
   } catch (error) {
     for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
+    error.consumerState = 'rolled-back';
     throw error;
   }
 }
@@ -80,6 +100,11 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
     if (replacements.has(path)) continue;
     if (await exists(join(consumerRoot, path))) throw new Error(`consumer changed during verification: ${path}`);
   }
+  for (const path of preview.generated ?? []) {
+    if (await exists(join(consumerRoot, path))) {
+      throw new Error(`consumer changed during verification: ${path}`);
+    }
+  }
   for (const path of [...preview.updated, ...preview.deleted]) {
     const prior = installed.get(path);
     const current = await exists(join(consumerRoot, path))
@@ -90,6 +115,95 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
   }
 }
 
+/** Seed only newly declared, decision-free project-layer stubs in a staged candidate. */
+export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, priorManifest, nextManifest }) {
+  const priorPaths = readinessStubPaths(priorManifest);
+  const manifestPath = join(candidateRoot, CONSUMER_MANIFEST_NAME);
+  const manifest = await readManifest(manifestPath);
+  const candidateInstalled = indexByPath(manifest, 'installed');
+  const generated = [];
+  for (const path of readinessStubPaths(nextManifest)) {
+    if (priorPaths.has(path)) continue;
+    if (await exists(join(candidateRoot, path))) {
+      if (candidateInstalled.get(path)?.origin === CONSUMER_ORIGIN
+          && !await exists(join(consumerRoot, path))) generated.push(path);
+      continue;
+    }
+    if (await exists(join(consumerRoot, path))) continue;
+    await writeAtomic(join(candidateRoot, path), `${stubSentinel()}\n`);
+    generated.push(path);
+  }
+  if (generated.length) {
+    const installed = [...manifest.installed];
+    for (const generatedPath of generated) {
+      if (candidateInstalled.has(generatedPath)) continue;
+      installed.push({
+        path: generatedPath, kind: 'doc', installedSha256: await sha256File(join(candidateRoot, generatedPath)),
+        origin: CONSUMER_ORIGIN, installRole: 'consumer',
+      });
+    }
+    await writeManifest(manifestPath, { ...manifest, installed });
+  }
+  const before = await readinessSnapshot(consumerRoot, priorManifest);
+  const after = await readinessSnapshot(candidateRoot, nextManifest);
+  const incompatible = Object.entries(after.skills)
+    .filter(([skill, current]) => before.skills[skill]?.verdict !== 'blocked'
+      && before.skills[skill] && current.verdict === 'blocked')
+    .map(([skill]) => skill)
+    .sort();
+  return { generated, availability: readinessDiff(before, after), incompatible };
+}
+
+function readinessStubPaths(manifest) {
+  const safe = new Set(STUB_TARGETS);
+  return new Set(Object.values(manifest?.readiness?.capabilities ?? {}).flatMap((capability) => {
+    if (capability.evidence?.type !== 'sentinel') return [];
+    return (capability.evidence.paths ?? []).filter((path) => safe.has(path));
+  }));
+}
+
+async function readinessSnapshot(root, manifest) {
+  const skills = {};
+  for (const [name, declaration] of Object.entries(manifest?.skills ?? {})) {
+    if (!declaration.readiness) continue;
+    skills[name] = await checkSkill({ root, skill: name, manifest });
+  }
+  const consumer = await readManifest(join(root, CONSUMER_MANIFEST_NAME));
+  const capabilities = {};
+  for (const [name, capability] of Object.entries(manifest?.readiness?.capabilities ?? {})) {
+    capabilities[name] = await evaluateCapability({
+      root, capability, decision: consumer?.readinessDecisions?.[name],
+    });
+  }
+  return { skills, capabilities };
+}
+
+function readinessDiff(before, after) {
+  const newlyAvailable = [];
+  const newlyDegraded = [];
+  const newlyBlocked = [];
+  const unresolved = new Set();
+  for (const [skill, current] of Object.entries(after.skills)) {
+    const prior = before.skills[skill];
+    if (current.verdict === 'blocked' && prior?.verdict !== 'blocked') newlyBlocked.push(skill);
+    if (current.verdict !== 'blocked' && (!prior || prior.verdict === 'blocked')) newlyAvailable.push(skill);
+    for (const block of current.inactiveBlocks) {
+      if (!prior || !prior.inactiveBlocks.includes(block)) newlyDegraded.push(`${skill}.${block}`);
+    }
+  }
+  for (const [capability, result] of Object.entries(after.capabilities)) {
+    if (result.state !== 'ready') unresolved.add(`${capability}:${result.state}`);
+  }
+  return {
+    newlyAvailable: newlyAvailable.sort(), newlyDegraded: newlyDegraded.sort(),
+    newlyBlocked: newlyBlocked.sort(), stillUnresolved: [...unresolved].sort(),
+  };
+}
+
+export async function readReadinessManifest(root) {
+  return readManifest(join(root, READINESS_MANIFEST_PATH));
+}
+
 async function snapshot(path) {
   if (!await exists(path)) return null;
   const info = await stat(path);