@ikon85/agent-workflow-kit 0.29.0 → 0.30.0

package/scripts/readiness.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { firstLineState } from '../src/lib/sentinel.mjs';
+import { CONSUMER_MANIFEST_NAME, readManifest, writeManifest } from '../src/lib/manifest.mjs';
+
+const SOURCE_MANIFEST = '.claude/skills/skill-manifest.json';
+const DECISIONS = new Set(['pending', 'not-applicable']);
+
+async function readText(root, path) {
+  try { return await readFile(join(root, path), 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function sentinelVerdict(text, allowLegacy) {
+  if (text === null) return 'absent';
+  const state = firstLineState(text);
+  const content = text.split('\n').slice(1).join('\n').trim();
+  if (state === 'filled') return content ? 'valid' : 'invalid';
+  if (state === null && allowLegacy && text.trim()) return 'valid';
+  return 'invalid';
+}
+
+function nonemptyVerdict(text) {
+  return text === null ? 'absent' : (text.trim() ? 'valid' : 'invalid');
+}
+
+function jsonValue(text, required) {
+  if (text === null) return 'absent';
+  try {
+    let value = JSON.parse(text);
+    for (const key of required ?? []) value = value?.[key];
+    return value === undefined || value === null ? 'invalid' : value;
+  } catch { return 'invalid'; }
+}
+
+function jsonVerdict(text, evidence) {
+  if (evidence.validator === 'project-release') {
+    if (text === null) return 'absent';
+    let profile;
+    try { profile = JSON.parse(text); } catch { return 'invalid'; }
+    const value = profile.schemaVersion === 1 ? profile.projectRelease : null;
+    const files = value?.versionFiles;
+    const tag = value?.tagPrefix;
+    return Array.isArray(files) && files.length > 0
+      && files.every((path) => typeof path === 'string' && path.trim())
+      && (tag === undefined || typeof tag === 'string') ? 'valid' : 'invalid';
+  }
+  const value = jsonValue(text, evidence.required);
+  if (['absent', 'invalid'].includes(value)) return value;
+  if (!(evidence.required?.length) && typeof value === 'object'
+      && !Array.isArray(value) && Object.keys(value).length === 0) return 'invalid';
+  return 'valid';
+}
+
+function fencedJsonAfter(text, marker) {
+  const start = text.indexOf(marker);
+  if (start < 0) return null;
+  const match = /```json\s*([\s\S]*?)```/.exec(text.slice(start + marker.length));
+  if (!match) return 'invalid';
+  try { return JSON.parse(match[1]); } catch { return 'invalid'; }
+}
+
+function boardVerdict(text) {
+  if (text === null) return 'absent';
+  const profile = fencedJsonAfter(text, '<!-- board-sync:profile -->');
+  if (!profile || profile === 'invalid') return 'invalid';
+  const status = profile.fields?.status;
+  const required = [profile.repo, profile.project?.owner, profile.project?.number,
+    profile.project?.nodeId, status?.id, status?.options, status?.roles,
+    profile.fields?.wave, profile.fields?.cluster, profile.labels];
+  return required.every(Boolean) ? 'valid' : 'invalid';
+}
+
+async function runbookVerdict(root, evidence) {
+  const layer = await readText(root, evidence.paths[0]);
+  const layerState = sentinelVerdict(layer, evidence.allowLegacy);
+  if (layerState !== 'valid') return layerState;
+  const paths = [...layer.matchAll(/`([^`\n]+\.md)`/g)].map((match) => match[1]);
+  for (const path of paths) {
+    if (path.includes('template')) continue;
+    const runbook = await readText(root, path);
+    if (runbook?.trim() && !runbook.includes('<placeholder>')) return 'valid';
+  }
+  return 'invalid';
+}
+
+function section(text, heading) {
+  if (text === null) return null;
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^##\s+/.test(line)) break;
+    body.push(line);
+  }
+  return body.join('\n').trim();
+}
+
+async function prodVerdict(root, paths) {
+  const bodies = [];
+  for (const path of paths) {
+    const text = await readText(root, path);
+    if (text === null) continue;
+    const body = section(text, '## Prod');
+    bodies.push(body);
+  }
+  if (!bodies.length) return 'absent';
+  if (bodies.every((body) => body === null)) return 'absent';
+  if (bodies.some((body) => !body)) return 'invalid';
+  return bodies.every((body) => body === bodies[0]) ? 'valid' : 'invalid';
+}
+
+async function evidenceVerdict(root, evidence) {
+  if (evidence.type === 'prod-section') return prodVerdict(root, evidence.paths);
+  if (evidence.type === 'runbook-reference') return runbookVerdict(root, evidence);
+  const verdicts = await Promise.all((evidence.paths ?? []).map(async (path) => {
+    const text = await readText(root, path);
+    if (evidence.type === 'sentinel') return sentinelVerdict(text, evidence.allowLegacy);
+    if (evidence.type === 'json') return jsonVerdict(text, evidence);
+    if (evidence.type === 'board-profile') return boardVerdict(text);
+    return nonemptyVerdict(text);
+  }));
+  if (verdicts.some((value) => value === 'invalid')) return 'invalid';
+  if (verdicts.some((value) => value === 'valid')) return 'valid';
+  return 'absent';
+}
+
+export async function evaluateCapability({ root, capability, decision }) {
+  const evidence = await evidenceVerdict(root, capability.evidence);
+  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false };
+  if (evidence === 'valid') return { state: 'ready', clearDecision: Boolean(decision) };
+  if (decision === 'pending') return { state: 'pending', clearDecision: false };
+  if (decision === 'not-applicable' && capability.allowNotApplicable) {
+    return { state: 'not-applicable', clearDecision: false };
+  }
+  return { state: 'missing', clearDecision: false };
+}
+
+async function loadManifest(root) {
+  const body = await readText(root, SOURCE_MANIFEST);
+  if (body === null) throw new Error(`readiness manifest not found: ${SOURCE_MANIFEST}`);
+  return JSON.parse(body);
+}
+
+export async function checkSkill({ root, skill, manifest }) {
+  manifest ??= await loadManifest(root);
+  const declaration = manifest.skills?.[skill]?.readiness;
+  if (!declaration) throw new Error(`skill has no readiness declaration: ${skill}`);
+  const consumer = await readManifest(join(root, CONSUMER_MANIFEST_NAME));
+  const decisions = consumer?.readinessDecisions ?? {};
+  const names = new Set([
+    ...(declaration.required ?? []), ...Object.values(declaration.optionalBlocks ?? {}),
+  ]);
+  const capabilities = {};
+  for (const name of names) {
+    const catalogEntry = manifest.readiness?.capabilities?.[name];
+    if (!catalogEntry) throw new Error(`unknown readiness capability: ${name}`);
+    capabilities[name] = await evaluateCapability({
+      root, capability: catalogEntry, decision: decisions[name],
+    });
+  }
+  const requiredBlocked = (declaration.required ?? []).some(
+    (name) => capabilities[name].state !== 'ready',
+  );
+  const activeBlocks = [];
+  const inactiveBlocks = [];
+  for (const [block, name] of Object.entries(declaration.optionalBlocks ?? {})) {
+    (capabilities[name].state === 'ready' ? activeBlocks : inactiveBlocks).push(block);
+  }
+  const invalid = Object.values(capabilities).some(({ state }) => state === 'invalid');
+  const verdict = requiredBlocked ? 'blocked' : (inactiveBlocks.length || invalid ? 'degraded' : 'ready');
+  return { contractVersion: manifest.readiness.contractVersion, verdict, capabilities, activeBlocks, inactiveBlocks };
+}
+
+async function changeDecision(root, capability, value) {
+  const path = join(root, CONSUMER_MANIFEST_NAME);
+  const manifest = await readManifest(path);
+  if (!manifest) throw new Error('not initialised — run `init` first');
+  const readiness = (await loadManifest(root)).readiness;
+  const catalog = readiness.capabilities;
+  if (!catalog[capability]) throw new Error(`unknown readiness capability: ${capability}`);
+  if (value && !DECISIONS.has(value)) throw new Error(`invalid readiness decision: ${value}`);
+  if (value === 'not-applicable' && !catalog[capability].allowNotApplicable) {
+    throw new Error(`${capability} does not allow not-applicable`);
+  }
+  const decisions = { ...(manifest.readinessDecisions ?? {}) };
+  if (value) decisions[capability] = value; else delete decisions[capability];
+  await writeManifest(path, {
+    ...manifest, readinessContractVersion: readiness.contractVersion, readinessDecisions: decisions,
+  });
+}
+
+function option(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index < 0 ? fallback : args[index + 1];
+}
+
+async function main(args = process.argv.slice(2)) {
+  const root = resolve(option(args, '--root', process.cwd()));
+  if (args[0] === 'check') {
+    const result = await checkSkill({ root, skill: option(args, '--skill') });
+    console.log(JSON.stringify(result, null, args.includes('--json') ? 2 : 0));
+    return;
+  }
+  if (args[0] === 'decision' && args[1] === 'set') return changeDecision(root, args[2], args[3]);
+  if (args[0] === 'decision' && args[1] === 'clear') return changeDecision(root, args[2], null);
+  throw new Error('usage: readiness check --skill <name> [--json] [--root <path>] | decision <set|clear> <capability> [value]');
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(`readiness: ${error.message}`); process.exitCode = 1; });
+}

package/scripts/release-state.test.mjs

@@ -1,7 +1,10 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import {
   createCommandAdapter, githubReleaseArgs, inspectRelease, isMissingRelease,
@@ -50,6 +53,55 @@ test('post-merge status inspection is read-only and reports the reconstructable
   assert.deepEqual(fixture.events, ['read npm', 'read github']);
 });
 
+test('local Claude overrides cannot change the packed release identity or enter the tarball', async () => {
+  const fixture = await mkdtemp(join(tmpdir(), 'awkit-local-overrides-'));
+  await mkdir(join(fixture, '.claude'), { recursive: true });
+  await Promise.all([
+    ['package.json', 'package.json'],
+    ['agent-workflow-kit.package.json', 'agent-workflow-kit.package.json'],
+    ['.claude/.npmignore', '.claude/.npmignore'],
+  ].map(([source, destination]) => copyFile(join(REPO, source), join(fixture, destination))));
+  await writeFile(join(fixture, '.claude/shipped.json'), '{"shipped":true}\n');
+
+  const overrides = [
+    ['.claude/settings.local.json', randomUUID()],
+    ['.claude/settings.local.json.backup', randomUUID()],
+  ];
+
+  const clean = await createCommandAdapter({ repoRoot: fixture });
+  const local = await createCommandAdapter({ repoRoot: fixture });
+  try {
+    const { identity: publishedIdentity } = await clean.local();
+    for (const [path, canary] of overrides) {
+      await writeFile(join(fixture, path), `${canary}\n`);
+    }
+
+    const { identity, tarball } = await local.local();
+    assert.deepEqual(identity, publishedIdentity);
+    assert.deepEqual(await inspectRelease({
+      local: async () => ({ identity, tarball }),
+      npm: async () => publishedIdentity,
+      github: async () => publishedIdentity,
+    }), { status: 'released', identity: publishedIdentity });
+
+    const paths = new Set(
+      execFileSync('tar', ['-tzf', tarball], { encoding: 'utf8' })
+        .trim().split('\n').map((path) => path.replace(/^package\//, '')),
+    );
+    assert.ok(paths.has('.claude/shipped.json'));
+    const contents = execFileSync('tar', ['-xOzf', tarball], {
+      encoding: 'utf8', maxBuffer: 16 * 1024 * 1024,
+    });
+    for (const [path, canary] of overrides) {
+      assert.ok(!paths.has(path), `packed local override: ${path}`);
+      assert.doesNotMatch(contents, new RegExp(canary));
+    }
+  } finally {
+    await Promise.all([clean.dispose(), local.dispose()]);
+    await rm(fixture, { recursive: true, force: true });
+  }
+});
+
 test('an unpublished npm version is reconstructable when npm reports ETARGET', () => {
   assert.equal(isMissingRelease({
     stderr: 'npm error code ETARGET\nnpm error notarget No matching version found',

package/scripts/test_codex_adapter_sync_contract.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Regression contract for the Codex-only adapter audit skill."""
+
+import importlib.util
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ADAPTER = REPO_ROOT / ".agents/skills/codex-adapter-sync/SKILL.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)
+_FRONTMATTER_SPEC.loader.exec_module(frontmatter)
+
+
+def section(body: str, heading: str) -> str:
+    """Return one second-level Markdown section, excluding the next one."""
+    marker = f"## {heading}\n"
+    start = body.index(marker) + len(marker)
+    end = body.find("\n## ", start)
+    return body[start:] if end == -1 else body[start:end]
+
+
+class AdapterModesContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_audit_is_read_only_and_apply_is_worktree_gated(self):
+        audit = " ".join(section(self.body, "Audit mode (default)").split())
+        apply = " ".join(section(self.body, "Apply mode").split())
+
+        self.assertIn("current checkout", audit)
+        self.assertIn("read-only", audit)
+        self.assertIn("Do not create or switch branches or worktrees", audit)
+        self.assertIn("before the first edit", apply)
+        self.assertIn("Never apply adapter changes on `main`", apply)
+        self.assertNotIn("before inventory or edits", self.body)
+
+
+class AdapterModelContract(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)
+        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")
+
+
+class AdapterInventoryContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_nested_instructions_configs_and_hooks_are_inventoried(self):
+        inventory = section(self.body, "Inventory")
+
+        for surface in (
+            "`**/CLAUDE.md`",
+            "`**/AGENTS.md`",
+            "`**/AGENTS.override.md`",
+            "`**/.codex/config.toml`",
+            "`.claude/settings*.json`",
+            "`.claude/hooks/**`",
+            "`.codex/hooks.json`",
+            "inline `[hooks]`",
+        ):
+            self.assertIn(surface, inventory)
+        self.assertIn("trusted project layers", inventory)
+        self.assertIn("Codex-adapted", inventory)
+        self.assertIn("intentionally Claude-only", inventory)
+        self.assertNotIn("`frontend/CLAUDE.md`", self.body)
+        self.assertNotIn("`backend/CLAUDE.md`", self.body)
+
+
+class AdapterAgentContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_custom_agent_toml_uses_the_current_schema(self):
+        agents = " ".join(section(self.body, "Custom-agent validation").split())
+
+        self.assertIn(
+            "required `name`, `description`, and `developer_instructions`", agents)
+        self.assertIn("optional `model` and `model_reasoning_effort`", agents)
+        self.assertIn("Parse every `.codex/agents/*.toml`", agents)
+        self.assertIn("Reject a file", agents)
+
+
+class AdapterValidationContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.body = ADAPTER.read_text(encoding="utf-8")
+
+    def test_validation_covers_every_current_adapter_surface(self):
+        validation = " ".join(section(self.body, "Validation").split())
+
+        for proof in (
+            "`codex --strict-config --version`",
+            "skill-frontmatter guard",
+            "skill metadata and loading",
+            "custom-agent TOML",
+            "`git check-ignore",
+            "references, assets, scripts",
+            "mirror-parity guard",
+            "X of Y",
+        ):
+            self.assertIn(proof, validation)
+        for maintainer_only_path in (
+            "scripts/test_skill_frontmatter_lint.py",
+            "scripts/test_skill_portability_lint.py",
+        ):
+            self.assertNotIn(maintainer_only_path, self.body)
+
+    def test_description_cap_is_an_enforced_repository_safeguard(self):
+        validation = " ".join(section(self.body, "Validation").split())
+        self.assertIn("1024-character description cap", validation)
+        self.assertIn("repository safeguard", validation)
+        self.assertIn("not a Codex product limit", validation)
+
+        problems = []
+        for skill in (REPO_ROOT / ".agents/skills").glob("*/SKILL.md"):
+            data = frontmatter.parse_frontmatter(
+                frontmatter.extract_frontmatter(skill.read_text(encoding="utf-8")))
+            description = data.get("description")
+            if isinstance(description, str) and len(description) > 1024:
+                problems.append(f"{skill.relative_to(REPO_ROOT)}: {len(description)}")
+        self.assertEqual(
+            problems,
+            [],
+            "skill descriptions over 1024 characters:\n" + "\n".join(problems),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_portability_lint.py

@@ -23,8 +23,8 @@ A line carrying `portability-lint: ok` is exempt — line-scoped, for deliberate
 doc counterexamples.
 
 This file also asserts mirror parity:
-- every dual-surface skill has the same set of distributed `*.md` files in both
-  trees (catches a forgotten mirror file);
+- every dual-surface skill has the same set of distributed files in both trees
+  (catches a forgotten mirror support file of any type);
 - generic/vendored dual-surface skill bodies match after stripping paired
   `mirror-xform` regions. The paired marker convention lets codex-adapter-sync
   keep legitimate Codex body translations local instead of maintaining a central
@@ -220,12 +220,36 @@ def enforced_skills() -> set[str]:
             if e["class"] in ENFORCED_CLASSES}
 
 
-def skill_md_set(tree: str, name: str) -> set[str]:
-    """Relative posix paths of every distributed *.md under one tree's skill dir."""
-    d = REPO_ROOT / tree / name
-    if not d.is_dir():
+def distributed_file_set(skill_dir: Path) -> set[str]:
+    """Relative paths of every distributed file under one skill directory."""
+    if not skill_dir.is_dir():
         return set()
-    return {p.relative_to(d).as_posix() for p in d.rglob("*.md")}
+    return {
+        p.relative_to(skill_dir).as_posix()
+        for p in skill_dir.rglob("*")
+        if p.is_file()
+    }
+
+
+def skill_file_set(tree: str, name: str) -> set[str]:
+    return distributed_file_set(REPO_ROOT / tree / name)
+
+
+def skill_md_set(tree: str, name: str) -> set[str]:
+    """Markdown subset used by the body and structure parity checks."""
+    return {p for p in skill_file_set(tree, name) if p.endswith(".md")}
+
+
+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"
+        for rel in sorted(claude - codex)
+    ]
+    problems.extend(
+        f"{name}: .agents/skills/{name}/{rel} has no claude source"
+        for rel in sorted(codex - claude)
+    )
+    return problems
 
 
 def dual_surface_skills() -> list[str]:
@@ -486,21 +510,16 @@ class ProfileValueLiteralNegativeFixture(unittest.TestCase):
 
 class MirrorPresenceParity(unittest.TestCase):
     """LEAN mirror parity: a dual-surface skill has the SAME set of distributed
-    *.md files in both trees. Presence/file-set only — not content (codex-adapter-sync
-    legitimately translates body model-dispatch; full content parity is a follow-up).
+    files in both trees. Presence/file-set only; Markdown content parity is handled
+    separately because codex-adapter-sync legitimately translates body model-dispatch.
     Catches a forgotten / orphaned mirror file (Codex R1#11 first half)."""
 
-    def test_dual_surface_md_filesets_match(self):
+    def test_dual_surface_distributed_filesets_match(self):
         problems = []
         for name in sorted(dual_surface_skills()):
-            claude = skill_md_set(".claude/skills", name)
-            codex = skill_md_set(".agents/skills", name)
-            only_claude = claude - codex
-            only_codex = codex - claude
-            for f in sorted(only_claude):
-                problems.append(f"{name}: .claude/skills/{name}/{f} has no codex mirror")
-            for f in sorted(only_codex):
-                problems.append(f"{name}: .agents/skills/{name}/{f} has no claude source")
+            claude = skill_file_set(".claude/skills", name)
+            codex = skill_file_set(".agents/skills", name)
+            problems.extend(mirror_presence_drift(name, claude, codex))
         self.assertEqual(
             problems, [],
             "mirror file-set drift — run codex-adapter-sync to add/remove the mirror "
@@ -540,6 +559,26 @@ class MirrorContentParity(unittest.TestCase):
 class MirrorParityFixture(unittest.TestCase):
     """The file-set comparison catches an orphaned mirror file (regression guard)."""
 
+    def test_non_markdown_support_file_is_detected(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as d:
+            claude = Path(d) / "claude"
+            codex = Path(d) / "codex"
+            (claude / "assets").mkdir(parents=True)
+            codex.mkdir()
+            (claude / "SKILL.md").write_text("# Example\n", encoding="utf-8")
+            (codex / "SKILL.md").write_text("# Example\n", encoding="utf-8")
+            (claude / "assets/example.yml").write_text("enabled: true\n", encoding="utf-8")
+
+            self.assertEqual(
+                mirror_presence_drift(
+                    "example",
+                    distributed_file_set(claude),
+                    distributed_file_set(codex),
+                ),
+                ["example: .claude/skills/example/assets/example.yml has no codex mirror"],
+            )
+
     def test_extra_mirror_file_is_detected(self):
         claude = {"SKILL.md", "tests.md"}
         codex = {"SKILL.md"}