@ikon85/agent-workflow-kit 0.33.0 → 0.34.1

package/scripts/release-state.mjs

@@ -2,11 +2,18 @@ import { execFile } from 'node:child_process';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { assertReleaseParity, releaseIdentityFromTarball } from './release-parity.mjs';
 
 const exec = promisify(execFile);
+const DEFAULT_VISIBILITY = {
+  attempts: 6,
+  initialDelayMs: 1_000,
+  backoffFactor: 2,
+  sleep,
+};
 
 const assertMatches = (local, remote, label) => assertReleaseParity({
   local,
@@ -28,7 +35,24 @@ export async function inspectRelease(adapter) {
   return { status: 'released', identity };
 }
 
-export async function reconcileRelease(adapter) {
+async function awaitVisibility(read, phase, options = {}) {
+  const policy = { ...DEFAULT_VISIBILITY, ...options };
+  let delay = policy.initialDelayMs;
+  for (let attempt = 1; attempt <= policy.attempts; attempt += 1) {
+    const visible = await read();
+    if (visible) return visible;
+    if (attempt < policy.attempts) {
+      await policy.sleep(delay);
+      delay *= policy.backoffFactor;
+    }
+  }
+  throw new Error(
+    `${phase.operation} succeeded but ${phase.subject} was not visible `
+    + `after ${policy.attempts} ${phase.service} read attempts`,
+  );
+}
+
+export async function reconcileRelease(adapter, { visibility } = {}) {
   const { identity, tarball } = await adapter.local();
   let npm = await adapter.npm(identity);
   let github = await adapter.github(identity);
@@ -36,15 +60,21 @@ export async function reconcileRelease(adapter) {
   if (!npm) {
     if (github) throw new Error('GitHub release exists before npm package');
     await adapter.publishNpm({ identity, tarball });
-    npm = await adapter.npm(identity);
-    if (!npm) throw new Error('npm package missing after publish');
+    npm = await awaitVisibility(() => adapter.npm(identity), {
+      service: 'npm',
+      operation: 'npm publish',
+      subject: 'package',
+    }, visibility);
   }
   assertMatches(identity, npm, 'npm');
 
   if (!github) {
     await adapter.createGithub({ identity, tarball });
-    github = await adapter.github(identity);
-    if (!github) throw new Error('GitHub release missing after create');
+    github = await awaitVisibility(() => adapter.github(identity), {
+      service: 'GitHub',
+      operation: 'GitHub release creation',
+      subject: 'release',
+    }, visibility);
   }
   assertReleaseParity({ local: identity, npm, github });
   return { status: 'released', identity };

package/scripts/release-state.test.mjs

@@ -18,17 +18,62 @@ const identity = {
   tarballIntegrity: 'sha512-example', manifestSha256: 'abc123',
 };
 
-function adapter({ npmPublished = false, githubReleased = false, npmIdentity = identity } = {}) {
+function adapter({
+  npmPublished = false,
+  githubReleased = false,
+  npmIdentity = identity,
+  npmInvisibleReads = 0,
+  githubInvisibleReads = 0,
+  publishNpmError,
+  createGithubError,
+} = {}) {
   const events = [];
   let npmExists = npmPublished;
   let githubExists = githubReleased;
+  let npmReadsUntilVisible = npmInvisibleReads;
+  let githubReadsUntilVisible = githubInvisibleReads;
   return {
     events,
     local: async () => ({ identity, tarball: '/tmp/kit.tgz' }),
-    npm: async () => { events.push('read npm'); return npmExists ? npmIdentity : null; },
-    github: async () => { events.push('read github'); return githubExists ? identity : null; },
-    publishNpm: async () => { events.push('publish npm'); npmExists = true; },
-    createGithub: async () => { events.push('create github'); githubExists = true; },
+    npm: async () => {
+      events.push('read npm');
+      if (!npmExists) return null;
+      if (npmReadsUntilVisible > 0) {
+        npmReadsUntilVisible -= 1;
+        return null;
+      }
+      return npmIdentity;
+    },
+    github: async () => {
+      events.push('read github');
+      if (!githubExists) return null;
+      if (githubReadsUntilVisible > 0) {
+        githubReadsUntilVisible -= 1;
+        return null;
+      }
+      return identity;
+    },
+    publishNpm: async () => {
+      events.push('publish npm');
+      if (publishNpmError) throw publishNpmError;
+      npmExists = true;
+    },
+    createGithub: async () => {
+      events.push('create github');
+      if (createGithubError) throw createGithubError;
+      githubExists = true;
+    },
+  };
+}
+
+function visibilityOptions(attempts, delays = []) {
+  return {
+    visibility: {
+      attempts,
+      initialDelayMs: 10,
+      backoffFactor: 2,
+      sleep: async (delay) => delays.push(delay),
+    },
   };
 }
 
@@ -40,6 +85,72 @@ test('a fresh release publishes npm, verifies registry readback, then creates Gi
   ]);
 });
 
+test('npm visibility is retried with bounded backoff after a successful publish', async () => {
+  const fixture = adapter({ npmInvisibleReads: 2 });
+  const delays = [];
+  assert.deepEqual(
+    await reconcileRelease(fixture, visibilityOptions(4, delays)),
+    { status: 'released', identity },
+  );
+  assert.deepEqual(fixture.events, [
+    'read npm', 'read github', 'publish npm',
+    'read npm', 'read npm', 'read npm',
+    'create github', 'read github',
+  ]);
+  assert.deepEqual(delays, [10, 20]);
+});
+
+test('GitHub visibility is retried with bounded backoff after a successful create', async () => {
+  const fixture = adapter({ npmPublished: true, githubInvisibleReads: 2 });
+  const delays = [];
+  assert.deepEqual(
+    await reconcileRelease(fixture, visibilityOptions(4, delays)),
+    { status: 'released', identity },
+  );
+  assert.deepEqual(fixture.events, [
+    'read npm', 'read github', 'create github', 'read github', 'read github', 'read github',
+  ]);
+  assert.deepEqual(delays, [10, 20]);
+});
+
+test('permanent npm absence fails at the bound with post-publish phase evidence', async () => {
+  const fixture = adapter({ npmInvisibleReads: 4 });
+  const delays = [];
+  await assert.rejects(
+    reconcileRelease(fixture, visibilityOptions(3, delays)),
+    /npm publish succeeded but package was not visible after 3 npm read attempts/,
+  );
+  assert.deepEqual(delays, [10, 20]);
+  assert.equal(fixture.events.filter((event) => event === 'read npm').length, 4);
+  assert.ok(!fixture.events.includes('create github'));
+});
+
+test('permanent GitHub absence fails at the bound with post-create phase evidence', async () => {
+  const fixture = adapter({ npmPublished: true, githubInvisibleReads: 4 });
+  const delays = [];
+  await assert.rejects(
+    reconcileRelease(fixture, visibilityOptions(3, delays)),
+    /GitHub release creation succeeded but release was not visible after 3 GitHub read attempts/,
+  );
+  assert.deepEqual(delays, [10, 20]);
+  assert.equal(fixture.events.filter((event) => event === 'read github').length, 4);
+  assert.ok(!fixture.events.includes('publish npm'));
+});
+
+test('a rejected publish is not reported as a post-publish visibility timeout', async () => {
+  const rejected = new Error('registry rejected publish');
+  const fixture = adapter({ publishNpmError: rejected });
+  await assert.rejects(reconcileRelease(fixture, visibilityOptions(3)), (error) => error === rejected);
+  assert.deepEqual(fixture.events, ['read npm', 'read github', 'publish npm']);
+});
+
+test('a rejected GitHub create is not reported as a post-create visibility timeout', async () => {
+  const rejected = new Error('GitHub rejected release create');
+  const fixture = adapter({ npmPublished: true, createGithubError: rejected });
+  await assert.rejects(reconcileRelease(fixture, visibilityOptions(3)), (error) => error === rejected);
+  assert.deepEqual(fixture.events, ['read npm', 'read github', 'create github']);
+});
+
 test('an npm-published release resumes at GitHub without a second npm publish', async () => {
   const fixture = adapter({ npmPublished: true });
   await reconcileRelease(fixture);
@@ -47,6 +158,12 @@ test('an npm-published release resumes at GitHub without a second npm publish',
   assert.ok(!fixture.events.includes('publish npm'));
 });
 
+test('an already-published release at parity is a read-only no-op', async () => {
+  const fixture = adapter({ npmPublished: true, githubReleased: true });
+  assert.deepEqual(await reconcileRelease(fixture), { status: 'released', identity });
+  assert.deepEqual(fixture.events, ['read npm', 'read github']);
+});
+
 test('post-merge status inspection is read-only and reports the reconstructable phase', async () => {
   const fixture = adapter({ npmPublished: true });
   assert.deepEqual(await inspectRelease(fixture), { status: 'awaiting-github', identity });

package/scripts/test_codex_adapter_sync_contract.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ADAPTER = REPO_ROOT / ".agents/skills/codex-adapter-sync/SKILL.md"
+AGENTS_README = REPO_ROOT / ".codex/agents/README.md"
 _FRONTMATTER_SPEC = importlib.util.spec_from_file_location(
     "skill_frontmatter_lint", REPO_ROOT / "scripts/test_skill_frontmatter_lint.py")
 frontmatter = importlib.util.module_from_spec(_FRONTMATTER_SPEC)
@@ -39,27 +40,24 @@ class AdapterModesContract(unittest.TestCase):
         self.assertNotIn("before inventory or edits", self.body)
 
 
-class AdapterModelContract(unittest.TestCase):
+class AdapterRoutingContract(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         cls.body = ADAPTER.read_text(encoding="utf-8")
 
-    def test_current_models_inherit_by_default_and_route_by_task_shape(self):
-        routing = " ".join(section(self.body, "Model routing").split())
-
-        self.assertIn("inherited parent model configuration", routing)
-        self.assertIn("`gpt-5.6-sol`", routing)
-        self.assertIn("complex, open-ended judgment work", routing)
-        self.assertIn("`gpt-5.6-terra`", routing)
-        self.assertIn("everyday tool-using development", routing)
-        self.assertIn("`gpt-5.6-luna`", routing)
-        self.assertIn("clear, repeatable, high-volume work", routing)
-        self.assertIn("`model_reasoning_effort`", routing)
+    def test_durable_routing_is_provider_neutral_and_resolved_at_dispatch(self):
+        routing = " ".join(section(self.body, "Routing intent").split())
+
+        self.assertIn("`routing-intent`", routing)
+        self.assertIn("`reasoning-intent`", routing)
+        self.assertIn("Evidence catalog", routing)
+        self.assertIn("Access graph", routing)
+        self.assertIn("Routing policy", routing)
+        self.assertIn("dispatch time", routing)
+        self.assertIn("explicit `inherit`", routing)
+        self.assertIn("Dispatch receipt", routing)
         self.assertIn("`default`, `worker`, and `explorer`", routing)
-        self.assertIn("not a fourth concrete variant", routing)
 
-        for stale in ("gpt-5.4-mini", "gpt-5.5"):
-            self.assertNotIn(stale, self.body)
         self.assertNotRegex(self.body, r"(?<!model_)\breasoning_effort\b")
         self.assertNotRegex(self.body, r"\bagent_type\b")
 
@@ -104,6 +102,23 @@ class AdapterAgentContract(unittest.TestCase):
         self.assertIn("Parse every `.codex/agents/*.toml`", agents)
         self.assertIn("Reject a file", agents)
 
+    def test_codex_host_inventory_is_dated_and_does_not_invent_spawn_selectors(self):
+        inventory = " ".join(
+            AGENTS_README.read_text(encoding="utf-8").split()
+        )
+        for fragment in (
+            "2026-07-23",
+            "`task_name`",
+            "`message`",
+            "`fork_turns`",
+            "no per-spawn `model`",
+            "no per-spawn effort selector",
+            "`src/lib/routingAdapters/codex.mjs`",
+            "blocks differentiated AFK",
+            "Dispatch receipt v2",
+        ):
+            self.assertIn(fragment, inventory)
+
 
 class AdapterValidationContract(unittest.TestCase):
     @classmethod

package/scripts/test_orchestrate_wave_contract.py

@@ -34,6 +34,25 @@ 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.
@@ -86,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):
@@ -176,6 +204,47 @@ class OrchestrateWaveContract(unittest.TestCase):
         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 (
@@ -214,6 +283,10 @@ class OrchestrateWaveContract(unittest.TestCase):
             "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)
 

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)."""