@ikon85/agent-workflow-kit 0.15.0 → 0.16.1

package/scripts/test_skill_setup_workflow_seeds.py

@@ -17,6 +17,9 @@ Run: python3 scripts/test_skill_setup_workflow_seeds.py
 """
 import json
 import re
+import subprocess
+import tempfile
+import time
 import unittest
 from pathlib import Path
 
@@ -55,6 +58,135 @@ def update_workflow_action(
     return "create" if prerequisites and pull_requests_allowed else "skip"
 
 
+def load_census_setup_effects():
+    """Parse the shipped seed's executable census transition contract."""
+    seed = (SKILL / "census.md").read_text(encoding="utf-8")
+    match = re.search(
+        r"```json census-setup-effects\n(.*?)\n```", seed, re.DOTALL,
+    )
+    if not match:
+        raise AssertionError("census seed has no structured setup-effects contract")
+    rows = json.loads(match.group(1))
+    return {row["state"]: row for row in rows}
+
+
+def resolve_census_state(**inputs):
+    """Ask the shipped #49 API for a state; do not duplicate its state machine."""
+    script = (
+        "import { resolveCensusState } from './scripts/census/index.mjs';"
+        "process.stdout.write(resolveCensusState(JSON.parse(process.argv[1])));"
+    )
+    result = subprocess.run(
+        ["node", "--input-type=module", "-e", script, json.dumps(inputs)],
+        cwd=REPO, check=True, capture_output=True, text=True,
+    )
+    return result.stdout
+
+
+def run_shipped_test(relative_path):
+    """Run a real shipped integration test as proof, without marker files."""
+    subprocess.run(
+        ["node", "--test", relative_path], cwd=REPO, check=True,
+        capture_output=True, text=True,
+    )
+
+
+def apply_census_setup_effect(root, effect, writes):
+    """Reconcile setup-owned files and delegate engine work to #49/#50."""
+    paths = {
+        "choice": root / "docs/agents/census.md",
+        "profile": root / ".census/profile.json",
+        "active": root / ".census/active.json",
+        "scanner": root / ".census/local-scanner.mjs",
+        "scanner-test": root / ".census/local-scanner.test.mjs",
+        "hook": root / ".git/hooks/census-check",
+        "gate": root / ".github/workflows/census-check.yml",
+    }
+    trace = []
+    states = []
+
+    def write_if_changed(path, content):
+        data = content.encode("utf-8")
+        if path.exists() and path.read_bytes() == data:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+        writes.append(path.relative_to(root).as_posix())
+
+    def replace_if_changed(path, content):
+        data = content.encode("utf-8")
+        if path.exists() and path.read_bytes() == data:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        staged = path.with_name(path.name + ".setup-workflow.tmp")
+        staged.write_bytes(data)
+        staged.replace(path)
+        writes.append(path.relative_to(root).as_posix())
+
+    def remove_if_present(path, operation):
+        if path.exists():
+            path.unlink()
+            writes.append(path.relative_to(root).as_posix())
+            trace.append(f"{operation}:removed")
+        else:
+            trace.append(f"{operation}:no-op")
+
+    for operation in effect["operations"]:
+        if operation == "reconcile-choice-doc":
+            choice = effect["choice"]
+            if not paths["choice"].exists():
+                content = (
+                    "<!-- setup-workflow: state=filled -->\n"
+                    f"<!-- census: choice={choice} -->\n\n"
+                    + (SKILL / "census.md").read_text(encoding="utf-8")
+                )
+                write_if_changed(paths["choice"], content)
+            trace.append("reconcile-choice-doc")
+        elif operation == "adopt-choice-doc":
+            if not paths["choice"].exists():
+                raise AssertionError("existing census needs a documented census path")
+            trace.append("adopt-choice-doc")
+        elif operation == "reconcile-minimal-profile":
+            if not paths["profile"].exists():
+                write_if_changed(paths["profile"], json.dumps({
+                    "schemaVersion": 1, "enabled": True,
+                    "decisions": [], "localScanners": [], "overrides": [],
+                }, sort_keys=True) + "\n")
+            trace.append("reconcile-minimal-profile")
+        elif operation == "remove-kit-hook":
+            remove_if_present(paths["hook"], operation)
+        elif operation == "remove-kit-gate":
+            remove_if_present(paths["gate"], operation)
+        elif operation == "update-profile-disabled":
+            profile = json.loads(paths["profile"].read_text(encoding="utf-8"))
+            profile["enabled"] = False
+            replace_if_changed(paths["profile"], json.dumps(profile, sort_keys=True) + "\n")
+            trace.append("update-profile-disabled")
+        elif operation == "derive-state":
+            enabled = False
+            if paths["profile"].exists():
+                enabled = json.loads(paths["profile"].read_text(encoding="utf-8"))["enabled"]
+            states.append(resolve_census_state(
+                enabled=enabled, hasActive=paths["active"].exists(),
+            ))
+            trace.append("derive-state")
+        elif operation == "run-foundation-self-test":
+            run_shipped_test("scripts/census/state.test.mjs")
+            trace.append("run-foundation-self-test")
+        elif operation == "delegate-census-update":
+            skill = (REPO / ".claude/skills/census-update/SKILL.md").read_text(encoding="utf-8")
+            for token in ("activateCensus", "resolveCensusState", "scripts/census/index.mjs"):
+                if token not in skill:
+                    raise AssertionError(f"census-update contract missing {token}")
+            trace.append("delegate-census-update")
+        elif operation == "run-census-update-contract":
+            run_shipped_test("scripts/test_census_update_contract.test.mjs")
+            trace.append("run-census-update-contract")
+        else:
+            raise AssertionError(f"unknown census setup operation: {operation}")
+    return paths, trace, states
+
+
 class IdempotencyRule(unittest.TestCase):
     CASES = [
         # (first_line, is_empty, expected)
@@ -81,6 +213,190 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_census_effect_contract_executes_every_transition_and_repeats_without_writes(self):
+        effects = load_census_setup_effects()
+        self.assertEqual(
+            set(effects),
+            {"missing", "yes", "later", "no", "existing", "explicit-enable", "disable"},
+        )
+        self.assertEqual(effects["explicit-enable"]["actor"], "census-update")
+
+        for state, effect in effects.items():
+            with self.subTest(state=state), tempfile.TemporaryDirectory() as tmp:
+                root = Path(tmp)
+                initial = {}
+                if state in ("existing", "explicit-enable", "disable"):
+                    initial = {
+                        "choice": (
+                            b'<!-- setup-workflow: state=filled -->\n'
+                            b'<!-- census: choice=yes -->\n\nconsumer notes stay exact\n'
+                        ),
+                        "profile": (
+                            b'{"enabled":true,"consumerKey":"keep exactly",'
+                            b'"decisions":["keep"],"overrides":[{"keep":true}]}\n'
+                        ),
+                        "active": b'{"consumerSnapshot":"keep exactly"}\n',
+                        "scanner": b"export const consumerScanner = true;\n",
+                        "scanner-test": b"consumer scanner test\n",
+                    }
+                    if state == "explicit-enable":
+                        initial["profile"] = b'{"enabled":false,"consumerKey":"keep"}\n'
+                        initial.pop("active")
+                    for name, data in initial.items():
+                        path = {
+                            "choice": root / "docs/agents/census.md",
+                            "profile": root / ".census/profile.json",
+                            "active": root / ".census/active.json",
+                            "scanner": root / ".census/local-scanner.mjs",
+                            "scanner-test": root / ".census/local-scanner.test.mjs",
+                        }[name]
+                        path.parent.mkdir(parents=True, exist_ok=True)
+                        path.write_bytes(data)
+                    if state in ("existing", "disable"):
+                        for path in (
+                            root / ".git/hooks/census-check",
+                            root / ".github/workflows/census-check.yml",
+                        ):
+                            path.parent.mkdir(parents=True, exist_ok=True)
+                            path.write_text("kit-owned census enforcement\n", encoding="utf-8")
+
+                writes = []
+                paths, trace, states = apply_census_setup_effect(root, effect, writes)
+
+                if state == "missing":
+                    self.assertEqual(writes, [])
+                if state == "yes":
+                    choice = paths["choice"].read_text(encoding="utf-8")
+                    self.assertTrue(choice.startswith(
+                        "<!-- setup-workflow: state=filled -->\n"
+                        "<!-- census: choice=yes -->\n"
+                    ))
+                    profile = json.loads(paths["profile"].read_text(encoding="utf-8"))
+                    self.assertEqual(profile, {
+                        "schemaVersion": 1, "enabled": True,
+                        "decisions": [], "localScanners": [], "overrides": [],
+                    })
+                    self.assertEqual(states, ["bootstrap"])
+                    self.assertIn("run-foundation-self-test", trace)
+                if state in ("yes", "later", "no"):
+                    self.assertFalse(paths["active"].exists())
+                    self.assertFalse(paths["hook"].exists())
+                    self.assertFalse(paths["gate"].exists())
+                if state in ("later", "no"):
+                    self.assertFalse(paths["profile"].exists())
+                    self.assertIn(
+                        f"<!-- census: choice={state} -->",
+                        paths["choice"].read_text(encoding="utf-8"),
+                    )
+                if state == "existing":
+                    self.assertEqual(writes, [])
+                    for name, expected in initial.items():
+                        self.assertEqual(paths[name].read_bytes(), expected)
+                if state == "explicit-enable":
+                    self.assertEqual(writes, [])
+                    for name, expected in initial.items():
+                        self.assertEqual(paths[name].read_bytes(), expected)
+                    self.assertEqual(
+                        trace,
+                        ["delegate-census-update", "run-census-update-contract"],
+                    )
+                if state == "disable":
+                    profile = json.loads(paths["profile"].read_text(encoding="utf-8"))
+                    self.assertFalse(profile["enabled"])
+                    self.assertEqual(profile["consumerKey"], "keep exactly")
+                    self.assertEqual(profile["decisions"], ["keep"])
+                    self.assertEqual(profile["overrides"], [{"keep": True}])
+                    for name in ("choice", "active", "scanner", "scanner-test"):
+                        self.assertEqual(paths[name].read_bytes(), initial[name])
+                    self.assertFalse(paths["hook"].exists())
+                    self.assertFalse(paths["gate"].exists())
+                    self.assertEqual(states, ["disabled"])
+                    self.assertLess(
+                        next(i for i, value in enumerate(trace) if value.startswith("remove-kit-hook:")),
+                        trace.index("update-profile-disabled"),
+                    )
+                    self.assertLess(
+                        next(i for i, value in enumerate(trace) if value.startswith("remove-kit-gate:")),
+                        trace.index("update-profile-disabled"),
+                    )
+
+                before = {
+                    str(path.relative_to(root)): (path.read_bytes(), path.stat().st_mtime_ns)
+                    for path in root.rglob("*") if path.is_file()
+                }
+                time.sleep(0.01)
+                repeat_writes = []
+                apply_census_setup_effect(root, effect, repeat_writes)
+                after = {
+                    str(path.relative_to(root)): (path.read_bytes(), path.stat().st_mtime_ns)
+                    for path in root.rglob("*") if path.is_file()
+                }
+                self.assertEqual(effect["repeat"], "no-write")
+                self.assertEqual(repeat_writes, [])
+                self.assertEqual(after, before)
+
+    def test_census_seed_covers_the_complete_setup_state_matrix(self):
+        seed = (SKILL / "census.md").read_text(encoding="utf-8")
+        rows = {}
+        for line in seed.splitlines():
+            match = re.match(r"^\| `([^`]+)` \| (.+) \| (.+) \|$", line)
+            if match:
+                rows[match.group(1)] = f"{match.group(2)} {match.group(3)}"
+        for state in (
+            "missing", "yes", "later", "no", "existing",
+            "explicit-enable", "disable",
+        ):
+            self.assertIn(state, rows)
+
+        expected_terms = {
+            "missing": ("ask `yes / later / no`", "do not infer", "no hook or gate"),
+            "yes": ("enabled: true", "active snapshot absent", "self-test", "bootstrap"),
+            "later": ("deferral", "setup rerun is a no-op", "`census-update`"),
+            "no": ("opt-out", "`disabled`", "do not create census files, hooks, or gates"),
+            "existing": ("Adopt", "without replacing", "Preserve every existing byte"),
+            "explicit-enable": ("`census-update`", "without rerunning setup", "no write"),
+            "disable": ("enabled: false", "remove census hooks/gates", "separately approves"),
+        }
+        for state, terms in expected_terms.items():
+            for term in terms:
+                self.assertIn(term, rows[state], f"{state} missing {term!r}")
+
+    def test_census_yes_is_an_honest_bootstrap_not_activation(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        seed = (SKILL / "census.md").read_text(encoding="utf-8")
+
+        self.assertIn("optional census choice", skill.split("---", 2)[1])
+        self.assertIn("Section A3 — Optional project census", skill)
+        self.assertIn("[census.md](./census.md)", skill)
+        for token in (
+            ".census/profile.json", ".census/active.json", "enabled: true",
+            "bootstrap", "not yet meaningful", "self-test",
+            "Setup itself never calls `activateCensus`",
+        ):
+            self.assertIn(token, seed)
+        self.assertIn("must not install pre-commit, pre-push, CI, planning, or", seed)
+
+    def test_census_deferral_adoption_enable_and_disable_are_safe_and_idempotent(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        seed = (SKILL / "census.md").read_text(encoding="utf-8")
+
+        for token in (
+            "retryable deferral", "explicit opt-out", "explicit `census-update`",
+            "consumer-owned", "separate deletion approval", "no write",
+        ):
+            self.assertIn(token, seed)
+        self.assertIn("Repeated runs are no-ops", skill)
+        self.assertIn("setup never deletes consumer-owned files", seed.lower())
+
+    def test_census_setup_surface_is_fully_mirrored_for_codex(self):
+        codex = REPO / ".agents/skills/setup-workflow"
+        for relative in ("SKILL.md", "census.md"):
+            self.assertEqual(
+                (SKILL / relative).read_text(encoding="utf-8"),
+                (codex / relative).read_text(encoding="utf-8"),
+                f"setup-workflow mirror drift in {relative}",
+            )
+
     def test_update_workflow_provider_and_choice_fixtures(self):
         fixtures = [
             ("github", "enable", False, True, True, "create"),