@ikon85/agent-workflow-kit 0.29.1 → 0.31.0

package/scripts/test_skill_readiness_contract.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Manifest-derived readiness declaration and marker grammar guard."""
+from __future__ import annotations
+
+import json
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+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 = {
+    "to-prd": ["issueTracker", "managedBoard"],
+    "to-issues": ["issueTracker", "managedBoard", "specCompleteness"],
+    "to-waves": ["issueTracker", "managedBoard", "specCompleteness"],
+    "board-to-waves": ["issueTracker", "managedBoard"],
+    "triage": ["issueTracker", "managedBoard", "triageLabels"],
+    "orchestrate-wave": ["issueTracker", "managedBoard"],
+    "local-ci": ["localCiRecipe"],
+    "project-release": ["projectReleaseProfile"],
+    "security-audit": ["securityAuditRunbook"],
+}
+OPTIONAL = {
+    "wrapup": {"deployReport": "prodTarget"},
+    "orchestrate-wave": {"projectRecipe": "orchestrateWaveRecipe"},
+    "spec-self-critique": {"projectEnrichment": "specCritiqueLayer"},
+    "code-review": {"projectEnrichment": "codeReviewLayer"},
+    "verify-spike": {"projectPlacement": "verifySpikeLayer"},
+    "audit-skills": {"projectChecks": "auditSkillsLayer"},
+    "git-worktree-recover": {"projectRecovery": "worktreeRecoveryLayer"},
+}
+
+
+def load_manifest() -> dict:
+    return json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+
+
+def marker_sequence(body: str, declared: set[str]) -> list[str]:
+    sequence: list[str] = []
+    active: str | None = None
+    seen: set[str] = set()
+    for number, line in enumerate(body.splitlines(), 1):
+        match = START.fullmatch(line)
+        if match:
+            block = match.group(1)
+            if active:
+                raise AssertionError(f"nested readiness block at line {number}")
+            if block in seen:
+                raise AssertionError(f"duplicate readiness block {block}")
+            if block not in declared:
+                raise AssertionError(f"unknown readiness block {block}")
+            active = block
+            seen.add(block)
+            sequence.append(block)
+        elif line == END:
+            if not active:
+                raise AssertionError(f"unbalanced readiness end at line {number}")
+            active = None
+        elif "readiness:block" in line or "readiness:end" in line:
+            raise AssertionError(f"invalid readiness marker grammar at line {number}")
+    if active:
+        raise AssertionError(f"unbalanced readiness block {active}")
+    return sequence
+
+
+def validate_surface_sequences(sequences: list[list[str]]) -> None:
+    if any(sequence != sequences[0] for sequence in sequences[1:]):
+        raise AssertionError("cross-surface readiness marker drift")
+
+
+class ReadinessContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.manifest = load_manifest()
+        self.catalog = self.manifest["readiness"]["capabilities"]
+        self.published = {
+            name: entry for name, entry in self.manifest["skills"].items()
+            if entry.get("publish")
+        }
+
+    def test_contract_and_skill_denominator_come_from_publish_manifest(self) -> None:
+        self.assertEqual(self.manifest["readiness"]["contractVersion"], 1)
+        manifest_source = (ROOT / "src/lib/manifest.mjs").read_text(encoding="utf-8")
+        version = re.search(r"READINESS_CONTRACT_VERSION = (\d+);", manifest_source)
+        self.assertIsNotNone(version)
+        self.assertEqual(int(version.group(1)), self.manifest["readiness"]["contractVersion"])
+        self.assertGreater(len(self.published), 0)
+        for name, entry in self.published.items():
+            self.assertTrue(entry.get("surfaces"), name)
+
+    def test_every_declaration_references_the_single_capability_catalog(self) -> None:
+        for skill, entry in self.published.items():
+            declaration = entry.get("readiness", {})
+            references = list(declaration.get("required", []))
+            references += list(declaration.get("optionalBlocks", {}).values())
+            for capability in references:
+                self.assertIn(capability, self.catalog, f"{skill}: {capability}")
+            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_markers_are_balanced_declared_and_surface_equal_when_activated(self) -> None:
+        for skill, entry in self.published.items():
+            declared = set(entry.get("readiness", {}).get("optionalBlocks", {}))
+            sequences: list[tuple[str, list[str]]] = []
+            for surface in entry["surfaces"]:
+                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)
+                sequences.append((surface, sequence))
+            if len(sequences) > 1:
+                validate_surface_sequences([sequence for _, sequence in sequences])
+
+    def test_marker_parser_rejects_each_structural_failure(self) -> None:
+        declared = {"projectEnrichment"}
+        bad = [
+            "<!-- readiness:block projectEnrichment -->\n<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:block projectEnrichment -->\n<!-- readiness:end -->\n<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:end -->",
+            "<!-- readiness:block projectEnrichment -->",
+            "<!-- readiness:block unknownBlock -->\n<!-- readiness:end -->",
+            " <!-- readiness:block projectEnrichment -->",
+        ]
+        for body in bad:
+            with self.subTest(body=body), self.assertRaises(AssertionError):
+                marker_sequence(body, declared)
+        with self.assertRaises(AssertionError):
+            validate_surface_sequences([["projectEnrichment"], []])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_readiness_preflight.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Behavior contract for required-readiness planning preflights."""
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+READINESS = ROOT / "scripts/readiness.mjs"
+MANIFEST = ROOT / ".claude/skills/skill-manifest.json"
+SKILLS = ("to-prd", "to-issues", "to-waves", "board-to-waves")
+SPEC_SKILLS = ("to-issues", "to-waves")
+PREFLIGHT_START = "<!-- readiness:required-preflight:start -->"
+PREFLIGHT_END = "<!-- readiness:required-preflight:end -->"
+
+
+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 configure_issue_tracker(root: Path) -> None:
+    write(
+        root,
+        "docs/agents/issue-tracker.md",
+        "<!-- setup-workflow: state=filled -->\nGitHub Issues.\n",
+    )
+
+
+def configure_board(root: Path) -> None:
+    profile = {
+        "repo": "owner/repo",
+        "project": {"owner": "owner", "number": 1, "nodeId": "project"},
+        "fields": {
+            "status": {
+                "id": "status",
+                "options": {"Todo": "todo"},
+                "roles": {"triaged": "Todo"},
+            },
+            "wave": "wave",
+            "cluster": "cluster",
+        },
+        "labels": {"readyForAgent": "ready-for-agent"},
+    }
+    write(
+        root,
+        "docs/agents/board-sync.md",
+        "<!-- board-sync:profile -->\n```json\n"
+        f"{json.dumps(profile)}\n```\n",
+    )
+
+
+def configure_spec_completeness(root: Path) -> None:
+    write(
+        root,
+        "docs/conventions/spec-completeness.md",
+        "<!-- setup-workflow: state=filled -->\nVertical slice rules.\n",
+    )
+
+
+class PlanningReadinessPreflightTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        write(
+            self.root,
+            ".claude/skills/skill-manifest.json",
+            MANIFEST.read_text(encoding="utf-8"),
+        )
+        write(
+            self.root,
+            "agent-workflow-kit.json",
+            json.dumps({
+                "kitVersion": "0.0.0-test",
+                "readinessContractVersion": 1,
+                "readinessDecisions": {},
+                "installed": [],
+            }),
+        )
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def check(self, skill: str) -> dict:
+        completed = subprocess.run(
+            ["node", str(READINESS), "check", "--skill", skill, "--json", "--root", str(self.root)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return json.loads(completed.stdout)
+
+    def snapshot(self) -> dict[Path, bytes]:
+        return {
+            path.relative_to(self.root): path.read_bytes()
+            for path in self.root.rglob("*") if path.is_file()
+        }
+
+    def test_missing_requirements_block_without_writing_fixture(self) -> None:
+        before = self.snapshot()
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(result["capabilities"]["issueTracker"]["state"], "missing")
+                self.assertEqual(result["capabilities"]["managedBoard"]["state"], "missing")
+        self.assertEqual(self.snapshot(), before)
+
+    def test_invalid_requirement_is_visible_and_check_remains_read_only(self) -> None:
+        configure_board(self.root)
+        configure_spec_completeness(self.root)
+        write(
+            self.root,
+            "docs/agents/issue-tracker.md",
+            "<!-- setup-workflow: state=stub -->\npartial\n",
+        )
+        before = self.snapshot()
+        result = self.check("to-prd")
+        self.assertEqual(result["verdict"], "blocked")
+        self.assertEqual(result["capabilities"]["issueTracker"]["state"], "invalid")
+        self.assertEqual(self.snapshot(), before)
+
+    def test_managed_board_not_applicable_makes_every_board_writer_inapplicable(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_spec_completeness(self.root)
+        manifest = json.loads((self.root / "agent-workflow-kit.json").read_text(encoding="utf-8"))
+        manifest["readinessDecisions"]["managedBoard"] = "not-applicable"
+        write(self.root, "agent-workflow-kit.json", json.dumps(manifest))
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(
+                    result["capabilities"]["managedBoard"]["state"],
+                    "not-applicable",
+                )
+
+    def test_spec_completeness_blocks_only_the_slicing_flows(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_board(self.root)
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                expected = "blocked" if skill in SPEC_SKILLS else "ready"
+                self.assertEqual(result["verdict"], expected)
+                if skill in SPEC_SKILLS:
+                    self.assertEqual(
+                        result["capabilities"]["specCompleteness"]["state"],
+                        "missing",
+                    )
+
+    def test_ready_state_and_skill_prose_share_one_silent_first_step(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_board(self.root)
+        configure_spec_completeness(self.root)
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                self.assertEqual(self.check(skill)["verdict"], "ready")
+                source = (ROOT / ".claude/skills" / skill / "SKILL.md").read_text(encoding="utf-8")
+                mirror = (ROOT / ".agents/skills" / skill / "SKILL.md").read_text(encoding="utf-8")
+                source_block = source.split(PREFLIGHT_START, 1)[1].split(PREFLIGHT_END, 1)[0]
+                mirror_block = mirror.split(PREFLIGHT_START, 1)[1].split(PREFLIGHT_END, 1)[0]
+                self.assertEqual(source_block, mirror_block)
+                self.assertIn(f"node scripts/readiness.mjs check --skill {skill} --json", source_block)
+                self.assertIn("before any remote write", source_block)
+                self.assertIn("Ready is silent", source_block)
+                self.assertIn("Run `/setup-workflow`, then rerun", source_block)
+                first_mutation = min(
+                    position for token in ("board-sync.py create", "gh issue edit")
+                    if (position := source.find(token)) >= 0
+                )
+                self.assertLess(source.find(PREFLIGHT_START), first_mutation)
+
+
+if __name__ == "__main__":
+    unittest.main()

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/init.mjs

@@ -8,6 +8,7 @@ import {
   readManifest, writeManifest, emptyConsumerManifest,
   filesForInstallRole, CONSUMER_INSTALL_ROLE,
   indexByPath,
+  readReadinessContract,
   CONSUMER_ORIGIN,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
@@ -27,6 +28,7 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
   const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
   if (!pkg) throw new Error('kit package manifest not found');
   const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const readiness = await readReadinessContract(kitRoot);
   const tracked = new Set((prior?.installed ?? []).map((e) => e.path));
   const consumerOwned = new Set(
     (prior?.installed ?? []).filter((e) => e.origin === CONSUMER_ORIGIN).map((e) => e.path),
@@ -68,7 +70,7 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
 
   await writeManifest(
     join(consumerRoot, CONSUMER_MANIFEST_NAME),
-    { ...emptyConsumerManifest(pkg.kitVersion), installed }
+    { ...emptyConsumerManifest(pkg.kitVersion, prior, readiness), installed }
   );
 
   for (const stub of STUB_TARGETS) {

package/src/commands/uninstall.mjs

@@ -5,6 +5,7 @@ import { hookReferenced } from '../lib/settings.mjs';
 import {
   writeManifest, readManifest, emptyConsumerManifest,
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN,
+  readReadinessContract,
 } from '../lib/manifest.mjs';
 
 const exists = (p) => access(p).then(() => true, () => false);
@@ -18,6 +19,7 @@ const exists = (p) => access(p).then(() => true, () => false);
 export async function uninstall({ consumerRoot }) {
   const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!consumer) throw new Error('not initialised — nothing to uninstall');
+  const readiness = await readReadinessContract(consumerRoot);
 
   const res = { removed: [], retained: [] };
   const retainedEntries = [];
@@ -42,7 +44,9 @@ export async function uninstall({ consumerRoot }) {
 
   const manifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
   if (retainedEntries.length) {
-    await writeManifest(manifestPath, { ...emptyConsumerManifest(consumer.kitVersion), installed: retainedEntries });
+    await writeManifest(manifestPath, {
+      ...emptyConsumerManifest(consumer.kitVersion, consumer, readiness), installed: retainedEntries,
+    });
   } else {
     await rm(manifestPath, { force: true });
   }