@ikon85/agent-workflow-kit 0.32.1 → 0.34.0

package/scripts/test_orchestrate_wave_contract.py

@@ -21,6 +21,38 @@ CLAUDE_BUILDER = (
 CODEX_BUILDER = (
     REPO / ".agents/skills/orchestrate-wave/references/builder-contract.md"
 )
+CLAUDE_WORKFLOW = (
+    REPO / ".claude/skills/orchestrate-wave/references/dispatch-workflow.md"
+)
+CODEX_WORKFLOW = (
+    REPO / ".agents/skills/orchestrate-wave/references/dispatch-workflow.md"
+)
+CLAUDE_SUBAGENTS = (
+    REPO / ".claude/skills/orchestrate-wave/references/dispatch-subagents.md"
+)
+CODEX_SUBAGENTS = (
+    REPO / ".agents/skills/orchestrate-wave/references/dispatch-subagents.md"
+)
+CODEX_SURFACE = REPO / ".agents/skills/orchestrate-wave"
+EXPECTED_DIRECT_SPAWN_CONTRACTS = (
+    "audit-skills/SKILL.md",
+    "code-review/SKILL.md",
+    "codebase-design/DESIGN-IT-TWICE.md",
+    "improve-codebase-architecture/INTERFACE-DESIGN.md",
+    "improve-codebase-architecture/SKILL.md",
+    "research/SKILL.md",
+)
+DIRECT_SPAWN_PATTERN = re.compile(
+    r"Run \*\*one read-only research subagent|"
+    r"Run both axes as \*\*parallel sub-agents|"
+    r"Spawn 3\+ sub-agents|"
+    r"spawn 3\+ sub-agents|"
+    r"make 3\+ parallel\s+`spawn_agent` calls|"
+    r"Then use the Agent tool|"
+    r"use `spawn_agent` with `agent_type: explorer`|"
+    r"use `spawn_agent` with only|"
+    r"Spin up a \*\*background agent",
+)
 
 
 # Outcome -> fragments whose conjunction proves that portable behavior.
@@ -32,10 +64,17 @@ BEHAVIORAL_PARITY = {
         "LOCAL annotated tag",
         "never push",
     ),
+    "compare-and-set claim protocol": (
+        "src/lib/waveClaim.mjs",
+        "claimWave",
+        "compare-and-set",
+        "acquired",
+    ),
     "owner-safe abort cleanup": (
         "this run planted",
         "On ANY wave STOP/abort",
         "Never delete a claim marker observed during a preflight collision",
+        "releaseWaveClaim",
     ),
     "dependency-aware retirement": (
         "topological",
@@ -66,6 +105,15 @@ def markdown_body(text: str) -> str:
     return text.split("\n---\n", 1)[1]
 
 
+def direct_spawn_contracts(surface: str) -> tuple[str, ...]:
+    root = REPO / surface
+    return tuple(sorted(
+        str(path.relative_to(root))
+        for path in root.rglob("*.md")
+        if DIRECT_SPAWN_PATTERN.search(path.read_text(encoding="utf-8"))
+    ))
+
+
 class OrchestrateWaveContract(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
@@ -91,6 +139,18 @@ class OrchestrateWaveContract(unittest.TestCase):
         ):
             self.assertIn(" ".join(fragment.split()), prose)
 
+    def test_builder_report_contract_is_identical_on_every_path(self):
+        """One report contract, whichever mechanic dispatched the builder."""
+        prose = " ".join(self.builder.split())
+        for fragment in (
+            "identical on every orchestration path",
+            "references/report-contracts.md",
+            "exactly ONE JSON object",
+            "src/lib/reportValidator.mjs",
+            "semanticVerify",
+        ):
+            self.assertIn(" ".join(fragment.split()), prose)
+
     def test_current_portable_contracts_survive_the_port(self):
         for fragment in (
             "project layer",
@@ -101,6 +161,155 @@ class OrchestrateWaveContract(unittest.TestCase):
         ):
             self.assertIn(fragment, self.skill)
 
+    def test_capability_selector_routes_exactly_one_orchestration_mechanic(self):
+        for fragment in (
+            "## Orchestration mechanics",
+            "literal `Workflow`",
+            "do not emulate",
+            "returns exactly one",
+            "references/dispatch-workflow.md",
+            "references/dispatch-subagents.md",
+            "Path C",
+            "Phase 1 uses the selected orchestration mechanics",
+            "Phase 2 uses the selected orchestration mechanics",
+        ):
+            self.assertIn(fragment, self.skill)
+
+        self.assertLessEqual(len(self.skill.splitlines()), 345)
+
+    def test_registry_ownership_distinguishes_safe_from_eager_registries(self):
+        prose = " ".join(self.skill.split())
+        for fragment in (
+            "declaration-only registries",
+            "may be predeclared by one hub",
+            "eager/validated registries",
+            "each appending only its own existing artifact after creation",
+            "dependency edges",
+        ):
+            self.assertIn(fragment, prose)
+
+        phase_one = prose.split("## Phase 1", 1)[1].split("## Phase 2", 1)[0]
+        done = phase_one.split("**Done when:**", 1)[1]
+        for fragment in (
+            "either one declaration-only owner",
+            "verbatim consume-only dependents",
+            "or an explicit serialized owner sequence",
+            "each owner appends only its own existing artifact",
+        ):
+            self.assertIn(fragment, done)
+
+    def test_phase_two_keeps_per_slice_routing_decisions(self):
+        prose = " ".join(self.skill.split())
+        self.assertIn("(a) inline vs delegate", prose)
+        self.assertIn("(b) tier + effort", prose)
+        self.assertIn("Standing rules", prose)
+
+    def test_every_surface_dispatch_crosses_resolver_and_spawn_guard(self):
+        prose = " ".join(self.skill.split())
+        for fragment in (
+            "provider-neutral Routing intent",
+            "shared resolver",
+            "spawn guard",
+            "Claude or Codex adapter",
+            "routingAdapters/codex.mjs",
+            "Dispatch receipt",
+            "requested and applied route",
+            "environment precedence",
+            "detected transport is not authorization",
+            "AFK",
+        ):
+            self.assertIn(fragment, prose)
+
+    def test_every_direct_spawn_contract_routes_through_the_shared_guard(self):
+        required = (
+            "provider-neutral Routing intent",
+            "routeDispatcher.mjs",
+            "shared spawn guard",
+            "Dispatch receipt",
+        )
+        claude_actual = direct_spawn_contracts(".claude/skills")
+        codex_actual = direct_spawn_contracts(".agents/skills")
+        self.assertEqual(claude_actual, EXPECTED_DIRECT_SPAWN_CONTRACTS)
+        self.assertEqual(codex_actual, EXPECTED_DIRECT_SPAWN_CONTRACTS)
+        for relative in claude_actual:
+            claude = " ".join(
+                (REPO / ".claude/skills" / relative).read_text(encoding="utf-8").split()
+            )
+            codex = " ".join(
+                (REPO / ".agents/skills" / relative).read_text(encoding="utf-8").split()
+            )
+            with self.subTest(contract=relative):
+                for fragment in required:
+                    self.assertIn(fragment, claude)
+                    self.assertIn(fragment, codex)
+                for unsupported in ("Agent tool", "subagent_type", "agent_type"):
+                    self.assertNotIn(unsupported, codex)
+
+    def test_path_a_reference_locks_the_two_run_dispatch_contract(self):
+        workflow = CLAUDE_WORKFLOW.read_text(encoding="utf-8")
+        for fragment in (
+            "meta.phases",
+            "one `agent()` call per slice",
+            "model`, `effort`, and `phase`",
+            "inline schema literal",
+            "Recon run",
+            "reconcileReconReports",
+            "Build run",
+            "resumeFromRunId",
+            "exactly once",
+            "journal.jsonl",
+            "timestamps through `args`",
+            "Date.now()",
+            "Math.random()",
+            "Every orchestration path",
+        ):
+            self.assertIn(fragment, workflow)
+
+        self.assertEqual(workflow, CODEX_WORKFLOW.read_text(encoding="utf-8"))
+
+    def test_path_b_reference_locks_the_native_subagent_contract(self):
+        subagents = CLAUDE_SUBAGENTS.read_text(encoding="utf-8")
+        prose = " ".join(subagents.split())
+        for fragment in (
+            "one read-only explorer per slice",
+            "one builder per slice",
+            "explicit wait",
+            "exactly ONE JSON object",
+            "reportValidator.mjs",
+            "reconcileReconReports",
+            "main thread",
+            "is not a PASS",
+            "waveClaim",
+            "spawn_agents_on_csv",
+            "output_schema",
+            "dormant",
+            "task_name`, `message`, and `fork_turns",
+            "no model or effort selector",
+            "blocks differentiated AFK",
+            "routingAdapters/codex.mjs",
+        ):
+            self.assertIn(" ".join(fragment.split()), prose)
+
+        self.assertEqual(subagents, CODEX_SUBAGENTS.read_text(encoding="utf-8"))
+
+    def test_codex_surface_carries_no_path_a_primitive_outside_its_pointer_target(self):
+        """B-surface prose must not require Workflow-only primitives."""
+        offenders = {}
+        for path in sorted(CODEX_SURFACE.rglob("*.md")):
+            if path.name == "dispatch-workflow.md":
+                continue
+            body = path.read_text(encoding="utf-8")
+            hits = [term for term in ("journal.jsonl", "resumeFromRunId") if term in body]
+            # The literal tool name is admissible ONLY inside the capability gate.
+            if "`Workflow`" in body:
+                gate = body.split("## Orchestration mechanics", 1)
+                remainder = gate[0] + (gate[1].split("\n## ", 1)[1] if len(gate) > 1 and "\n## " in gate[1] else "")
+                if "`Workflow`" in remainder:
+                    hits.append("`Workflow`")
+            if hits:
+                offenders[str(path.relative_to(REPO))] = hits
+        self.assertEqual(offenders, {})
+
     def test_claude_and_codex_surfaces_match(self):
         self.assertEqual(
             markdown_body(self.skill),

package/scripts/test_program_planning_contract.py

@@ -11,6 +11,76 @@ class ProgramPlanningContractTest(unittest.TestCase):
     def skill(self, name: str) -> str:
         return (ROOT / ".claude" / "skills" / name / "SKILL.md").read_text()
 
+    def file(self, path: str) -> str:
+        return (ROOT / path).read_text()
+
+    def test_to_issues_is_the_public_planning_facade(self):
+        text = self.skill("to-issues")
+        self.assertIn("single public Planning facade", text)
+        self.assertIn("planning-mode=feature", text)
+        self.assertIn("planning-mode=program", text)
+        self.assertIn("Missing or contradictory identity", text)
+        self.assertIn("Size, prose, and model judgment never select the mode", text)
+
+    def test_program_identity_delegates_to_the_internal_graph_engine(self):
+        issues = self.skill("to-issues")
+        waves = self.skill("to-waves")
+        self.assertIn("delegate to the internal", issues)
+        self.assertIn("`to-waves` graph engine", issues)
+        self.assertIn("complete Program preview", issues)
+        self.assertIn("Internal Program graph engine", waves)
+        self.assertIn("compatibility entrypoint", waves)
+        self.assertIn("carries both", waves)
+        self.assertIn("never infer Program mode", waves)
+
+    def test_feature_identity_keeps_the_existing_decomposition_path(self):
+        text = self.skill("to-issues")
+        self.assertIn("Feature identity", text)
+        self.assertIn("PROMOTE", text)
+        self.assertIn("ATOMIC", text)
+
+    def test_normal_routes_name_only_the_planning_facade(self):
+        route_files = (
+            ".claude/skills/ask-matt/SKILL.md",
+            ".claude/skills/scale-check/SKILL.md",
+            ".claude/skills/setup-workflow/workflow-overview.md",
+            ".claude/skills/board-to-waves/SKILL.md",
+            "CLAUDE.md",
+            "README.md",
+            "docs/workflow.html",
+            "docs/methodology.html",
+            "docs/methodology.svg",
+        )
+        for path in route_files:
+            with self.subTest(path=path):
+                text = self.file(path)
+                self.assertIn("to-issues", text)
+                self.assertNotIn("→ `to-waves`", text)
+                self.assertNotIn("→ to-waves", text)
+
+    def test_dual_surface_planning_skills_are_coherent(self):
+        skill_snippets = (
+            ("to-issues", "single public Planning facade"),
+            ("to-waves", "Internal Program graph engine"),
+            ("ask-matt", "the user never chooses that engine"),
+            ("scale-check", "explicit Program identity selects the internal graph path"),
+            ("setup-workflow", "explicit Program identity"),
+            ("board-to-waves", "not directly to a hidden engine"),
+        )
+        for skill, snippet in skill_snippets:
+            with self.subTest(skill=skill):
+                claude = self.file(f".claude/skills/{skill}/SKILL.md")
+                codex = self.file(f".agents/skills/{skill}/SKILL.md")
+                self.assertIn(snippet, claude)
+                self.assertIn(snippet, codex)
+
+        support_files = ("workflow-overview.md", "board-sync.md")
+        for name in support_files:
+            with self.subTest(support=name):
+                claude = self.file(f".claude/skills/setup-workflow/{name}")
+                codex = self.file(f".agents/skills/setup-workflow/{name}")
+                self.assertEqual(claude, codex)
+
     def test_to_waves_finishes_with_every_wave_execute_ready_by_default(self):
         text = self.skill("to-waves")
         self.assertIn("## 7. Program completion contract", text)

package/scripts/test_skill_portability_lint.py

@@ -55,6 +55,17 @@ ENFORCED_CLASSES = {"generic", "vendored"}
 EXEMPT = "portability-lint: ok"
 MIRROR_XFORM_START = re.compile(r"^\s*<!--\s*mirror-xform:start(?:\s+([^>]*?))?\s*-->\s*$")
 MIRROR_XFORM_END = re.compile(r"^\s*<!--\s*mirror-xform:end\s*-->\s*$")
+DIRECT_SPAWN_PATTERN = re.compile(
+    r"Run \*\*one read-only research subagent|"
+    r"Run both axes as \*\*parallel sub-agents|"
+    r"Spawn 3\+ sub-agents|"
+    r"spawn 3\+ sub-agents|"
+    r"make 3\+ parallel\s+`spawn_agent` calls|"
+    r"Then use the Agent tool|"
+    r"use `spawn_agent` with `agent_type: explorer`|"
+    r"use `spawn_agent` with only|"
+    r"Spin up a \*\*background agent",
+)
 
 # Opaque, project-coupled board constants — meaningless in a foreign repo.
 CONSTANT_PATTERNS = [
@@ -240,6 +251,15 @@ def skill_md_set(tree: str, name: str) -> set[str]:
     return {p for p in skill_file_set(tree, name) if p.endswith(".md")}
 
 
+def direct_spawn_contracts(tree: str) -> dict[str, str]:
+    root = REPO_ROOT / tree
+    return {
+        path.relative_to(root).as_posix(): path.read_text(encoding="utf-8")
+        for path in root.rglob("*.md")
+        if DIRECT_SPAWN_PATTERN.search(path.read_text(encoding="utf-8"))
+    }
+
+
 def mirror_presence_drift(name: str, claude: set[str], codex: set[str]) -> list[str]:
     problems = [
         f"{name}: .claude/skills/{name}/{rel} has no codex mirror"
@@ -555,6 +575,40 @@ class MirrorContentParity(unittest.TestCase):
             "`<!-- mirror-xform:start <reason> -->` / `<!-- mirror-xform:end -->` "
             "regions:\n" + "\n".join(problems))
 
+    def test_every_codex_direct_spawn_contract_uses_the_shared_guard(self):
+        claude = direct_spawn_contracts(".claude/skills")
+        codex = direct_spawn_contracts(".agents/skills")
+        self.assertTrue(claude, "direct-spawn census unexpectedly empty")
+        self.assertEqual(set(codex), set(claude))
+
+        problems = []
+        required = (
+            "provider-neutral Routing intent",
+            "routeDispatcher.mjs",
+            "shared spawn guard",
+            "Dispatch receipt",
+        )
+        for relative, body in codex.items():
+            prose = " ".join(body.split())
+            missing = [fragment for fragment in required if fragment not in prose]
+            if missing:
+                problems.append(f"{relative}: missing {', '.join(missing)}")
+            unsupported = [
+                token for token in ("Agent tool", "subagent_type", "agent_type")
+                if token in prose
+            ]
+            if unsupported:
+                problems.append(
+                    f"{relative}: unsupported Codex spawn syntax "
+                    f"{', '.join(unsupported)}"
+                )
+        self.assertEqual(
+            problems,
+            [],
+            f"Codex direct-spawn guard coverage drift ({len(codex)} of "
+            f"{len(claude)}):\n" + "\n".join(problems),
+        )
+
 
 class MirrorParityFixture(unittest.TestCase):
     """The file-set comparison catches an orphaned mirror file (regression guard)."""

package/scripts/test_worktree_setup_base_guard.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Worktree reuse must refuse a stale base on BOTH reuse paths.
+
+`setup.py create()` can reach an existing worktree two ways: the target is
+already a registered worktree, or only its branch exists locally and
+`git worktree add <target> <branch>` silently ignores `--base`. Reuse is safe
+only when the reused HEAD is AT the base or cleanly behind it (fast-forwardable);
+anything ahead or diverged builds the slice on a stale base and must STOP.
+"""
+
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from argparse import Namespace
+from contextlib import contextmanager
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+LIFECYCLE = REPO / "scripts/worktree-lifecycle"
+
+PROFILE = """{
+  "worktreeLifecycle": {
+    "enabled": true,
+    "worktreeRoot": ".worktrees",
+    "branchTemplate": "{type}/{issue}-{slug}",
+    "pathTemplate": "{issue}-{slug}",
+    "setupSteps": []
+  }
+}
+"""
+
+
+def load_setup():
+    sys.path.insert(0, str(LIFECYCLE))
+    try:
+        spec = importlib.util.spec_from_file_location(
+            "worktree_setup_base_guard", LIFECYCLE / "setup.py"
+        )
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+    finally:
+        sys.path.remove(str(LIFECYCLE))
+
+
+def git(repo: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", *args], cwd=repo, capture_output=True, text=True, check=True
+    )
+    return result.stdout.strip()
+
+
+@contextmanager
+def fixture():
+    """A repo whose `main` carries two commits: base_first, then head."""
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = Path(tmp).resolve() / "repo"
+        repo.mkdir()
+        git(repo, "init", "--initial-branch=main")
+        git(repo, "config", "user.email", "test@example.invalid")
+        git(repo, "config", "user.name", "Test User")
+        profile = repo / "docs/agents/workflow-capabilities.json"
+        profile.parent.mkdir(parents=True)
+        profile.write_text(PROFILE, encoding="utf-8")
+        (repo / "README.md").write_text("# fixture\n", encoding="utf-8")
+        git(repo, "add", "-A")
+        git(repo, "commit", "-m", "first")
+        first = git(repo, "rev-parse", "HEAD")
+        (repo / "README.md").write_text("# fixture 2\n", encoding="utf-8")
+        git(repo, "commit", "-am", "second")
+        second = git(repo, "rev-parse", "HEAD")
+        yield repo, first, second
+
+
+@contextmanager
+def chdir(path: Path):
+    previous = Path.cwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(previous)
+
+
+def args_for(base: str) -> Namespace:
+    return Namespace(
+        profile="docs/agents/workflow-capabilities.json",
+        base=base,
+        issue="173",
+        slug="wave-safety",
+        branch_type="feat",
+    )
+
+
+class WorktreeReuseBaseGuard(unittest.TestCase):
+    def test_registered_worktree_reuse_stops_when_head_is_not_at_base(self):
+        setup = load_setup()
+        with fixture() as (repo, first, second):
+            target = repo / ".worktrees/173-wave-safety"
+            git(repo, "worktree", "add", "-b", "feat/173-wave-safety", str(target), second)
+            # base is the OLDER commit -> the registered worktree is ahead of it.
+            with chdir(repo):
+                with self.assertRaises(setup.LifecycleError) as stopped:
+                    setup.create(args_for(first))
+        self.assertIn("stale", str(stopped.exception).lower())
+
+    def test_existing_branch_reuse_stops_when_branch_is_not_at_base(self):
+        setup = load_setup()
+        with fixture() as (repo, first, second):
+            git(repo, "branch", "feat/173-wave-safety", second)
+            target = repo / ".worktrees/173-wave-safety"
+            with chdir(repo):
+                with self.assertRaises(setup.LifecycleError) as stopped:
+                    setup.create(args_for(first))
+        self.assertIn("stale", str(stopped.exception).lower())
+        self.assertFalse(target.exists(), "no worktree may be created on a stale base")
+
+    def test_registered_worktree_reuse_allows_head_at_base(self):
+        setup = load_setup()
+        with fixture() as (repo, _first, second):
+            target = repo / ".worktrees/173-wave-safety"
+            git(repo, "worktree", "add", "-b", "feat/173-wave-safety", str(target), second)
+            with chdir(repo):
+                self.assertEqual(setup.create(args_for(second)).resolve(), target.resolve())
+
+    def test_existing_branch_reuse_allows_a_branch_cleanly_behind_base(self):
+        setup = load_setup()
+        with fixture() as (repo, first, second):
+            git(repo, "branch", "feat/173-wave-safety", first)
+            target = repo / ".worktrees/173-wave-safety"
+            with chdir(repo):
+                self.assertEqual(setup.create(args_for(second)).resolve(), target.resolve())
+            self.assertTrue(target.is_dir())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/worktree-lifecycle/setup.py

@@ -84,6 +84,39 @@ def execute_step(
     raise LifecycleError(f"unsupported setup step kind: {kind!r}")
 
 
+def commit_oid(repo: Path, rev: str) -> str | None:
+    result = run(["git", "rev-parse", "--verify", f"{rev}^{{commit}}"], cwd=repo, check=False)
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def ensure_reusable_base(main: Path, *, repo: Path, rev: str, base: str, label: str) -> None:
+    """Reuse is safe only AT the base or cleanly behind it; anything else is stale.
+
+    Both reuse paths skip `git worktree add`'s base argument, so without this
+    guard a slice silently builds on whatever the old branch/worktree pointed at.
+    """
+    base_oid = commit_oid(main, base)
+    if base_oid is None:
+        raise LifecycleError(f"base {base!r} is not resolvable")
+    current = commit_oid(repo, rev)
+    if current is None:
+        raise LifecycleError(f"{label}: HEAD is not resolvable")
+    if current == base_oid:
+        return
+    behind = run(
+        ["git", "merge-base", "--is-ancestor", current, base_oid],
+        cwd=main,
+        check=False,
+    )
+    if behind.returncode == 0:
+        return
+    raise LifecycleError(
+        f"{label}: HEAD {current[:7]} is stale against base {base} ({base_oid[:7]}) — "
+        "it is ahead of or diverged from the base. Land or rebase that work, or remove "
+        "the worktree/branch, before reusing it."
+    )
+
+
 def remove_failed_worktree(main: Path, target: Path, branch: str, created_branch: bool) -> None:
     run(["git", "worktree", "remove", "--force", str(target)], cwd=main, check=False)
     if created_branch:
@@ -101,10 +134,17 @@ def create(args: argparse.Namespace) -> Path:
     target = (main / profile.relative_path(args.issue, args.slug, args.branch_type)).resolve()
 
     if target in registered_worktrees(main):
+        ensure_reusable_base(
+            main, repo=target, rev="HEAD", base=args.base, label=f"worktree {target}"
+        )
         print(f"Worktree already exists: {target} ({branch})")
         return target
 
     branch_existed = local_branch_exists(main, branch)
+    if branch_existed:
+        ensure_reusable_base(
+            main, repo=main, rev=branch, base=args.base, label=f"branch {branch}"
+        )
     command = ["git", "worktree", "add", str(target)]
     command += [branch] if branch_existed else ["-b", branch, args.base]
     run(command, cwd=main)