@ikon85/agent-workflow-kit 0.30.0 → 0.32.0

package/scripts/test_skill_optional_readiness.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Behavior contract for optional review and spike readiness layers."""
+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"
+SURFACES = (".claude/skills", ".agents/skills")
+SKILLS = {
+    "spec-self-critique": {
+        "block": "projectEnrichment",
+        "capability": "specCritiqueLayer",
+        "path": "docs/agents/skills/spec-self-critique.md",
+        "core": ("## The 12-point checklist", "Self-Critique complete"),
+        "enrichment": ("per-point enrichment", "project-specific incidents"),
+    },
+    "code-review": {
+        "block": "projectEnrichment",
+        "capability": "codeReviewLayer",
+        "path": "docs/agents/code-review.md",
+        "core": ("## Axis 1 — Standards", "## Axis 2 — Spec"),
+        "enrichment": ("which sources count", "adjacent tools"),
+    },
+    "verify-spike": {
+        "block": "projectPlacement",
+        "capability": "verifySpikeLayer",
+        "path": "docs/agents/skills/verify-spike.md",
+        "core": ("Frame one falsifiable question", "Delete the harness"),
+        "enrichment": ("harness-placement", "import rules"),
+    },
+}
+PREFLIGHT_START = "<!-- readiness:optional-preflight:start -->"
+PREFLIGHT_END = "<!-- readiness:optional-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")
+
+
+class OptionalReadinessTests(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"),
+        )
+        self.consumer = {
+            "kitVersion": "0.0.0-test",
+            "readinessContractVersion": 1,
+            "readinessDecisions": {},
+            "installed": [],
+        }
+        self.write_consumer()
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def write_consumer(self) -> None:
+        write(self.root, "agent-workflow-kit.json", json.dumps(self.consumer))
+
+    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 test_missing_and_pending_subtract_exactly_one_optional_block(self) -> None:
+        for decision in (None, "pending"):
+            for skill, contract in SKILLS.items():
+                with self.subTest(skill=skill, decision=decision):
+                    self.consumer["readinessDecisions"] = {}
+                    if decision:
+                        self.consumer["readinessDecisions"][contract["capability"]] = decision
+                    self.write_consumer()
+                    result = self.check(skill)
+                    self.assertEqual(result["verdict"], "degraded")
+                    self.assertEqual(
+                        result["capabilities"][contract["capability"]]["state"],
+                        decision or "missing",
+                    )
+                    self.assertEqual(result["inactiveBlocks"], [contract["block"]])
+                    self.assertEqual(result["activeBlocks"], [])
+
+    def test_invalid_enrichment_is_visible_and_never_an_opt_out(self) -> None:
+        for skill, contract in SKILLS.items():
+            with self.subTest(skill=skill):
+                write(
+                    self.root,
+                    contract["path"],
+                    "<!-- setup-workflow: state=stub -->\npartial configuration\n",
+                )
+                self.consumer["readinessDecisions"][contract["capability"]] = "pending"
+                self.write_consumer()
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "degraded")
+                self.assertEqual(
+                    result["capabilities"][contract["capability"]]["state"],
+                    "invalid",
+                )
+                self.assertEqual(result["inactiveBlocks"], [contract["block"]])
+
+    def test_ready_enrichment_activates_the_block(self) -> None:
+        for skill, contract in SKILLS.items():
+            with self.subTest(skill=skill):
+                write(
+                    self.root,
+                    contract["path"],
+                    "<!-- setup-workflow: state=filled -->\nProject guidance.\n",
+                )
+                self.consumer["readinessDecisions"] = {}
+                self.write_consumer()
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "ready")
+                self.assertEqual(result["activeBlocks"], [contract["block"]])
+                self.assertEqual(result["inactiveBlocks"], [])
+
+    def test_preflight_and_exact_subtraction_match_across_both_surfaces(self) -> None:
+        for skill, contract in SKILLS.items():
+            blocks = []
+            preflights = []
+            for surface in SURFACES:
+                body = (ROOT / surface / skill / "SKILL.md").read_text(encoding="utf-8")
+                start = f"<!-- readiness:block {contract['block']} -->"
+                self.assertEqual(body.count(start), 1)
+                self.assertEqual(body.count("<!-- readiness:end -->"), 1)
+                block = body.split(start, 1)[1].split("<!-- readiness:end -->", 1)[0]
+                preflight = body.split(PREFLIGHT_START, 1)[1].split(PREFLIGHT_END, 1)[0]
+                generic = body.replace(start + block + "<!-- readiness:end -->", "")
+                for anchor in contract["core"]:
+                    self.assertIn(anchor, generic)
+                for anchor in contract["enrichment"]:
+                    self.assertIn(anchor, block)
+                self.assertLess(body.index(PREFLIGHT_START), body.index(start))
+                self.assertIn(
+                    f"node scripts/readiness.mjs check --skill {skill} --json",
+                    preflight,
+                )
+                self.assertIn(f"inactive block `{contract['block']}`", preflight)
+                self.assertIn(contract["capability"], preflight)
+                self.assertIn("Ready is silent", preflight)
+                self.assertIn("Invalid is always visible", preflight)
+                blocks.append(block)
+                preflights.append(preflight)
+            self.assertEqual(blocks[0], blocks[1])
+            self.assertEqual(preflights[0], preflights[1])
+
+
+if __name__ == "__main__":
+    unittest.main()

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/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()