@ikon85/agent-workflow-kit 0.29.0 → 0.30.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/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 });
   }

package/src/lib/bundle.mjs

@@ -4,6 +4,13 @@ import { join, relative } from 'node:path';
 // The planning skills are not usable without their helper ecosystem (Codex R2#1).
 // These ship alongside the skills. Paths are relative to the bundle/consumer root.
 export const HELPER_FILES = [
+  // Readiness declarations and their deterministic consumer-side command ship
+  // together; the manifest remains the only capability/dependency registry.
+  { path: '.claude/skills/skill-manifest.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/readiness.mjs', kind: 'script', mode: 0o755 },
+  { path: 'src/lib/sentinel.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/manifest.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/atomicWrite.mjs', kind: 'script', mode: 0o644 },
   // Shared profile loader imported by the three planning scripts — they read
   // every board-specific value from docs/agents/board-sync.md through it, so it
   // MUST ship or they are broken-on-arrival. Library (imported, not run) → 0o644.

package/src/lib/manifest.mjs

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 
 // Two manifests (Codex R1#9 / R3#1):
@@ -15,6 +16,8 @@ export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
 export const CONSUMER_INSTALL_ROLE = 'consumer';
 export const KIT_ORIGIN = 'kit';
 export const CONSUMER_ORIGIN = 'consumer';
+export const READINESS_CONTRACT_VERSION = 1;
+export const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -51,8 +54,29 @@ export async function writeManifest(path, obj) {
   await writeAtomic(path, JSON.stringify(obj, null, 2) + '\n');
 }
 
-export function emptyConsumerManifest(kitVersion) {
-  return { kitVersion, installRole: CONSUMER_INSTALL_ROLE, installed: [] };
+export async function readReadinessContract(root) {
+  const manifest = await readManifest(join(root, READINESS_MANIFEST_PATH));
+  return manifest?.readiness ?? null;
+}
+
+function retainedDecisions(prior, readiness) {
+  const allowed = readiness?.capabilities ? new Set(Object.keys(readiness.capabilities)) : null;
+  return Object.fromEntries(Object.entries(prior.readinessDecisions ?? {}).filter(
+    ([name, value]) => (!allowed || allowed.has(name)) && (value === 'pending'
+      || (value === 'not-applicable' && readiness?.capabilities?.[name]?.allowNotApplicable)),
+  ));
+}
+
+export function emptyConsumerManifest(kitVersion, prior = {}, readiness = null) {
+  prior ??= {};
+  return {
+    ...prior,
+    kitVersion,
+    installRole: CONSUMER_INSTALL_ROLE,
+    readinessContractVersion: readiness?.contractVersion ?? READINESS_CONTRACT_VERSION,
+    readinessDecisions: retainedDecisions(prior, readiness),
+    installed: [],
+  };
 }
 
 /** Package entries without a role predate role-aware installs and remain consumer-owned. */

package/src/lib/updateReconcile.mjs

@@ -8,6 +8,7 @@ import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
   CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN, filesForInstallRole,
   indexByPath, readManifest, writeManifest,
+  readReadinessContract,
 } from './manifest.mjs';
 
 const exists = (path) => access(path).then(() => true, () => false);
@@ -18,6 +19,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   if (!pkg) throw new Error('kit package manifest not found');
   const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!consumer) throw new Error('not initialised — run `init` first');
+  const readiness = await readReadinessContract(kitRoot);
 
   const installedIdx = indexByPath(consumer, 'installed');
   const packageIdx = indexByPath(pkg, 'files');
@@ -117,7 +119,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 
   if (!dryRun) {
     await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
-      ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
+      ...emptyConsumerManifest(pkg.kitVersion, consumer, readiness), installed: nextInstalled,
     });
   }
   return result;