@ikon85/agent-workflow-kit 0.43.0 → 0.44.0

package/scripts/test_issue_claim_contract.py

@@ -1,169 +0,0 @@
-#!/usr/bin/env python3
-"""Issue-claim-on-pickup contract (#231).
-
-A skill that ACCEPTS a tracked issue for building must leave a claim on the
-issue itself before it builds — the local worktree/branch/PR guard only sees
-the same machine, and only until someone pushes. The claim is what a second
-session, a second machine, or a cloud agent can actually see.
-
-Enforced here:
-
-- `implement` and `diagnose` carry one byte-identical claim block on both
-  surfaces, and it sits before their first build instruction.
-- The block covers all three legs: check for a foreign claim (STOP), plant a
-  claim naming branch + worktree, release it.
-- `orchestrate-wave` claims each slice issue at builder-launch time and
-  releases only its own slice claims.
-- Every tracker seed and this repo's own tracker layer document the concrete
-  claim / check / release operations, so the tracker-neutral skill prose
-  resolves to real commands.
-
-Run: python3 scripts/test_issue_claim_contract.py
-"""
-from __future__ import annotations
-
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-SURFACES = (".claude/skills", ".agents/skills")
-PICKUP_SKILLS = ("implement", "diagnose")
-START = "<!-- issue-claim:start -->"
-END = "<!-- issue-claim:end -->"
-MARKER = "<!-- agent-claim:"
-TRACKER_DOC = "docs/agents/issue-tracker.md"
-TRACKER_SEEDS = (
-    "setup-workflow/issue-tracker-github.md",
-    "setup-workflow/issue-tracker-gitlab.md",
-    "setup-workflow/issue-tracker-local.md",
-)
-# The first instruction that already assumes the build has started.
-FIRST_BUILD_ANCHOR = {
-    "implement": "Use /tdd where possible",
-    "diagnose": "## Phase 1 — Build a feedback loop",
-}
-
-
-def skill_body(surface: str, skill: str) -> str:
-    return (ROOT / surface / skill / "SKILL.md").read_text(encoding="utf-8")
-
-
-def claim_block(body: str) -> str:
-    return body.split(START, 1)[1].split(END, 1)[0]
-
-
-def section(body: str, heading: str) -> str:
-    """Return one second-level Markdown section, excluding the next one."""
-    start = body.index(heading) + len(heading)
-    end = body.find("\n## ", start)
-    return body[start:] if end == -1 else body[start:end]
-
-
-class ClaimBlockContract(unittest.TestCase):
-    def test_pickup_skills_carry_exactly_one_claim_block_on_both_surfaces(self):
-        for skill in PICKUP_SKILLS:
-            for surface in SURFACES:
-                with self.subTest(skill=skill, surface=surface):
-                    body = skill_body(surface, skill)
-                    self.assertEqual(body.count(START), 1)
-                    self.assertEqual(body.count(END), 1)
-                    self.assertLess(body.index(START), body.index(END))
-
-    def test_claim_block_is_byte_identical_across_skills_and_surfaces(self):
-        blocks = {
-            (skill, surface): claim_block(skill_body(surface, skill))
-            for skill in PICKUP_SKILLS
-            for surface in SURFACES
-        }
-        first = blocks[(PICKUP_SKILLS[0], SURFACES[0])]
-        for key, block in blocks.items():
-            with self.subTest(key=key):
-                self.assertEqual(block, first)
-
-    def test_claim_block_covers_check_plant_and_release(self):
-        block = claim_block(skill_body(SURFACES[0], PICKUP_SKILLS[0]))
-        # Check leg — a foreign claim stops the pickup, and is never removed.
-        self.assertIn("foreign claim", block)
-        self.assertIn("STOP", block)
-        self.assertIn("never delete a foreign claim", block)
-        # Plant leg — the marker must carry branch AND worktree, or a colliding
-        # session cannot find the work in progress.
-        self.assertIn(MARKER, block)
-        self.assertIn("branch=", block)
-        self.assertIn("worktree=", block)
-        # Release leg — the PR supersedes it; an abandoned claim is removed.
-        self.assertIn("supersedes", block)
-        self.assertIn("abandon", block)
-
-    def test_claim_block_resolves_through_the_tracker_layer_with_a_fallback(self):
-        block = claim_block(skill_body(SURFACES[0], PICKUP_SKILLS[0]))
-        self.assertIn(TRACKER_DOC, block)
-        self.assertIn("fall back", block)
-
-    def test_claim_is_planted_before_the_first_build_instruction(self):
-        for skill in PICKUP_SKILLS:
-            for surface in SURFACES:
-                with self.subTest(skill=skill, surface=surface):
-                    body = skill_body(surface, skill)
-                    self.assertLess(
-                        body.index(END), body.index(FIRST_BUILD_ANCHOR[skill])
-                    )
-
-
-class OrchestrateWaveSliceClaimContract(unittest.TestCase):
-    def test_dispatch_claims_each_slice_issue_at_builder_launch(self):
-        for surface in SURFACES:
-            with self.subTest(surface=surface):
-                dispatch = section(
-                    skill_body(surface, "orchestrate-wave"),
-                    "## Phase 2 — Dispatch one wave in parallel",
-                )
-                self.assertIn(MARKER, dispatch)
-                self.assertIn("slice issue", dispatch)
-                self.assertIn("branch=", dispatch)
-                self.assertIn("worktree=", dispatch)
-
-    def test_wave_claim_is_not_treated_as_a_slice_claim(self):
-        for surface in SURFACES:
-            with self.subTest(surface=surface):
-                dispatch = section(
-                    skill_body(surface, "orchestrate-wave"),
-                    "## Phase 2 — Dispatch one wave in parallel",
-                )
-                self.assertIn("wave claim", dispatch)
-
-    def test_cleanup_releases_only_this_runs_slice_claims(self):
-        for surface in SURFACES:
-            with self.subTest(surface=surface):
-                cleanup = section(
-                    skill_body(surface, "orchestrate-wave"),
-                    "## Phase 6 — Cleanup + close",
-                )
-                self.assertIn("slice claim", cleanup)
-                self.assertIn("this run", cleanup)
-
-
-class TrackerLayerClaimOperations(unittest.TestCase):
-    def documents(self) -> dict[str, str]:
-        docs = {TRACKER_DOC: (ROOT / TRACKER_DOC).read_text(encoding="utf-8")}
-        for surface in SURFACES:
-            for seed in TRACKER_SEEDS:
-                path = ROOT / surface / seed
-                docs[str(path.relative_to(ROOT))] = path.read_text(encoding="utf-8")
-        return docs
-
-    def test_every_tracker_layer_defines_claim_check_and_release(self):
-        for name, body in self.documents().items():
-            with self.subTest(document=name):
-                self.assertIn("## Pickup claim", body)
-                claim = section(body, "## Pickup claim")
-                self.assertIn(MARKER, claim)
-                self.assertIn("branch=", claim)
-                self.assertIn("worktree=", claim)
-                # a read side (detect a foreign claim) and a release side
-                self.assertIn("Check", claim)
-                self.assertIn("Release", claim)
-
-
-if __name__ == "__main__":
-    unittest.main()

package/scripts/test_kit_docs_language_census.py

@@ -1,178 +0,0 @@
-#!/usr/bin/env python3
-"""dist-kit doc language census (#1953) — a coarse net over EVERY shipped
-`.md` file (docs/templates, README, SKILL.md bodies alike), not just
-`publish: true` skill bodies (that zero-tolerance census already exists in
-`test_skill_language_census.py`). This guard is a percentage smoke test: a
-kit doc is red once ≥10% of its lines carry German prose, so an
-English-speaking consumer never again silently gets a majority-German
-template the way `docs/agents/wave-anchor-template.md` shipped before this
-slice (23/100 lines German — the census #1953 was written to catch).
-
-Reuses `test_skill_language_census.py`'s wordlist + line-classification
-helpers (`_line_hits`, `strip_frontmatter`, the bilingual
-`<user-story-example lang="de">` block skip) rather than a parallel
-heuristic — same STRONG/WEAK wordlist, same allowlist exemptions (contract
-literals, `Welle <N>` title format, the inline `language-census: ok`
-marker).
-
-Two test classes:
-  - `RatioFixtures` — pure-function unit tests, no build. Proves the ratio
-    computation goes RED on an artificially-German fixture and GREEN on an
-    all-English one, independent of the real dist-kit build.
-  - `DistKitDocsCensus` — builds the REAL dist-kit (subprocess, like
-    `test_dist_kit_smoke.py`) and asserts every shipped `.md` file is under
-    the threshold.
-
-Run: python3 scripts/test_kit_docs_language_census.py
-"""
-import subprocess
-import sys
-import unittest
-from pathlib import Path
-
-from test_skill_language_census import (
-    BILINGUAL_BLOCK_END,
-    BILINGUAL_BLOCK_START,
-    _line_hits,
-    strip_frontmatter,
-)
-
-REPO = Path(__file__).resolve().parent.parent
-DIST = REPO / "dist-kit"
-
-GERMAN_LINE_THRESHOLD_PCT = 10.0
-
-
-def german_line_ratio(text: str) -> tuple[int, int]:
-    """(german_hit_lines, total_lines) for a doc body — frontmatter stripped,
-    bilingual `<user-story-example lang="de">...</user-story-example>` blocks
-    skipped (same exemptions as the publish:true skill census)."""
-    body = strip_frontmatter(text)
-    lines = body.splitlines()
-    total = len(lines)
-    hits = 0
-    in_bilingual_de_block = False
-    for line in lines:
-        if BILINGUAL_BLOCK_START.search(line):
-            in_bilingual_de_block = True
-        if in_bilingual_de_block:
-            if BILINGUAL_BLOCK_END.search(line):
-                in_bilingual_de_block = False
-            continue
-        if _line_hits(line):
-            hits += 1
-    return hits, total
-
-
-def is_below_threshold(text: str) -> tuple[bool, float]:
-    """(clean, pct) — clean is False once pct >= GERMAN_LINE_THRESHOLD_PCT."""
-    hits, total = german_line_ratio(text)
-    if total == 0:
-        return True, 0.0
-    pct = hits / total * 100
-    return pct < GERMAN_LINE_THRESHOLD_PCT, pct
-
-
-class RatioFixtures(unittest.TestCase):
-    """Pure-function proof: the census heuristic actually catches German
-    prose (RED) and does not false-positive on clean English (GREEN) —
-    independent of whether dist-kit can be built in this environment."""
-
-    def test_mostly_german_doc_is_red(self):
-        # Mirrors the pre-translation wave-anchor-template.md shape: a title
-        # line + a handful of English structural lines + a majority of dense
-        # German prose paragraphs — comfortably over the 10% line threshold.
-        german_doc = "\n".join(
-            ["# Title", "", "## Section", ""]
-            + ["Diese Zeile beschreibt eine Änderung und ist auf Deutsch geschrieben."] * 3
-            + ["Der Anker wird für die Wellen-Planung genutzt und muss gepflegt werden."] * 3
-            + [""] * 14  # padding so German lines are a clear >10% share, not 100%
-        )
-        clean, pct = is_below_threshold(german_doc)
-        self.assertFalse(clean, f"expected RED (>= {GERMAN_LINE_THRESHOLD_PCT}%), got {pct:.1f}%")
-        self.assertGreaterEqual(pct, GERMAN_LINE_THRESHOLD_PCT)
-
-    def test_all_english_doc_is_green(self):
-        english_doc = "\n".join(
-            ["# Title", "", "## Section", "",
-             "This line describes a change and is written in English.",
-             "The anchor is used for wave planning and must be maintained.",
-             ""]
-        )
-        clean, pct = is_below_threshold(english_doc)
-        self.assertTrue(clean, f"expected GREEN (< {GERMAN_LINE_THRESHOLD_PCT}%), got {pct:.1f}%")
-
-    def test_frontmatter_excluded_from_ratio(self):
-        # A German `description:` inside frontmatter (legitimate — quotes a
-        # German trigger phrase) must not count toward the body ratio.
-        text = (
-            "---\n"
-            "name: x\n"
-            'description: Use when "lass uns das Board durchgehen und die Wellen planen".\n'
-            "---\n\n"
-            "This body is English only, nothing else in here at all.\n"
-        )
-        clean, pct = is_below_threshold(text)
-        self.assertTrue(clean, f"frontmatter leaked into ratio: {pct:.1f}%")
-
-    def test_exempt_marker_line_does_not_count_as_a_hit(self):
-        text = "\n".join(
-            ["# Title", "Dies ist deutsch und bleibt es.  <!-- language-census: ok -->"]
-            + ["English line."] * 10
-        )
-        clean, pct = is_below_threshold(text)
-        self.assertTrue(clean, f"exempt marker line still counted: {pct:.1f}%")
-
-
-def _build_dist_kit():
-    """Run the real build (subprocess), mirroring test_dist_kit_smoke.py.
-    Returns (CompletedProcess, skip_reason); skip_reason set only when node
-    itself is unavailable in this environment."""
-    build = REPO / "scripts/build-kit.mjs"
-    try:
-        r = subprocess.run(["node", str(build)], cwd=REPO,
-                            capture_output=True, text=True, timeout=120)
-    except (FileNotFoundError, subprocess.TimeoutExpired) as e:
-        return None, str(e)
-    return r, None
-
-
-class DistKitDocsCensus(unittest.TestCase):
-    """Smoke test over the actually-shipped dist-kit/**/*.md — the ONLY
-    thing a consumer ever reads, so this is what must stay clean."""
-
-    @classmethod
-    def setUpClass(cls):
-        r, skip_reason = _build_dist_kit()
-        if skip_reason:
-            raise unittest.SkipTest(f"node/build unavailable: {skip_reason}")
-        if r.returncode != 0:
-            raise AssertionError(f"build-kit.mjs failed: {r.stderr}")
-        if not DIST.is_dir():
-            raise AssertionError("dist-kit/ missing after build")
-
-    def test_every_shipped_doc_is_under_the_german_line_threshold(self):
-        violations = []
-        checked = 0
-        for path in sorted(DIST.rglob("*.md")):
-            if not path.is_file():
-                continue
-            checked += 1
-            text = path.read_text(encoding="utf-8", errors="ignore")
-            clean, pct = is_below_threshold(text)
-            if not clean:
-                violations.append((str(path.relative_to(DIST)), pct))
-
-        self.assertGreater(checked, 0, "no dist-kit/**/*.md found — build produced nothing?")
-        msg = "\n".join(f"  {p}: {pct:.1f}% German lines" for p, pct in violations)
-        self.assertEqual(
-            violations, [],
-            f"Census: {checked - len(violations)} of {checked} shipped docs under "
-            f"{GERMAN_LINE_THRESHOLD_PCT}% German lines.\n\n"
-            "Translate the residual German prose (or, for a genuine intentional "
-            "literal, mark the line `<!-- language-census: ok -->`):\n" + msg,
-        )
-
-
-if __name__ == "__main__":
-    unittest.main(verbosity=2)

package/scripts/test_marker_lib.py

@@ -1,162 +0,0 @@
-#!/usr/bin/env python3
-"""Behavior tests for marker identity lookup and reconciliation."""
-
-from __future__ import annotations
-
-import json
-import importlib.util
-import io
-import subprocess
-import unittest
-from contextlib import redirect_stderr, redirect_stdout
-from pathlib import Path
-from unittest.mock import patch
-
-from scripts.marker_lib import find_by_marker, reconcile_after_create
-
-
-CLI_SPEC = importlib.util.spec_from_file_location(
-    "find_by_marker_cli_test", Path(__file__).with_name("find-by-marker.py"))
-cli = importlib.util.module_from_spec(CLI_SPEC)
-assert CLI_SPEC.loader is not None
-CLI_SPEC.loader.exec_module(cli)
-
-
-class MarkerLookupTest(unittest.TestCase):
-    def test_pagination_joins_all_pages(self):
-        calls: list[list[str]] = []
-
-        def fake_gh(args: list[str]) -> str:
-            calls.append(args)
-            return json.dumps([
-                [{"number": 11, "state": "open", "body":
-                  "<!-- prd-source-id: alpha -->"}],
-                [{"number": 12, "state": "closed", "body":
-                  "<!-- prd-source-id: alpha -->"}],
-            ])
-
-        result = find_by_marker("example/repo", "prd-source-id", "alpha", fake_gh)
-
-        self.assertEqual(result["count"], 2)
-        self.assertEqual(result["issues"], [
-            {"number": 11, "state": "open"},
-            {"number": 12, "state": "closed"},
-        ])
-        self.assertIn("--paginate", calls[0])
-        self.assertIn("state=all", calls[0])
-
-    def test_pull_requests_are_discarded_before_matching(self):
-        marker = "<!-- wave-stub-source: same -->"
-        payload = [[
-            {"number": 21, "state": "open", "body": marker,
-             "pull_request": {"url": "https://api.example/pr/21"}},
-            {"number": 22, "state": "open", "body": marker},
-        ]]
-
-        result = find_by_marker(
-            "example/repo", "wave-stub-source", "same",
-            lambda _args: json.dumps(payload),
-        )
-
-        self.assertEqual(result["issues"], [{"number": 22, "state": "open"}])
-
-    def test_closed_only_match_requires_user_decision(self):
-        payload = [[{"number": 31, "state": "closed", "body":
-                     "<!-- prd-source-id: retired -->"}]]
-
-        result = find_by_marker(
-            "example/repo", "prd-source-id", "retired",
-            lambda _args: json.dumps(payload),
-        )
-
-        self.assertEqual(result["verdict"], "user-decision")
-
-    def test_marker_value_is_exact_not_a_prefix_match(self):
-        payload = [[
-            {"number": 41, "state": "open", "body":
-             "<!-- prd-source-id: alpha-long -->"},
-            {"number": 42, "state": "open", "body":
-             "<!-- prd-source-id: alpha -->"},
-        ]]
-
-        result = find_by_marker(
-            "example/repo", "prd-source-id", "alpha",
-            lambda _args: json.dumps(payload),
-        )
-
-        self.assertEqual(result["issues"], [{"number": 42, "state": "open"}])
-        self.assertEqual(result["verdict"], "update")
-
-    def test_post_create_rescan_stops_and_reports_both_duplicate_numbers(self):
-        marker = "<!-- program-leaf-source: program-x/1a -->"
-        responses = iter([
-            [[]],
-            [[
-                {"number": 101, "state": "open", "body": marker},
-                {"number": 102, "state": "open", "body": marker},
-            ]],
-        ])
-        calls: list[list[str]] = []
-
-        def fake_gh(args: list[str]) -> str:
-            calls.append(args)
-            return json.dumps(next(responses))
-
-        before = find_by_marker(
-            "example/repo", "program-leaf-source", "program-x/1a",
-            fake_gh,
-        )
-        after = reconcile_after_create(
-            "example/repo", "program-leaf-source", "program-x/1a", 101,
-            fake_gh,
-        )
-
-        self.assertEqual(before["verdict"], "create")
-        self.assertEqual(after["verdict"], "STOP")
-        self.assertEqual([issue["number"] for issue in after["issues"]], [101, 102])
-        self.assertEqual(len(calls), 2)
-
-    def test_post_create_rescan_rejects_a_different_single_issue(self):
-        payload = [[{"number": 102, "state": "open", "body":
-                     "<!-- prd-source-id: alpha -->"}]]
-
-        result = reconcile_after_create(
-            "example/repo", "prd-source-id", "alpha", 101,
-            lambda _args: json.dumps(payload),
-        )
-
-        self.assertEqual(result["verdict"], "STOP")
-        self.assertEqual(result["issues"], [{"number": 102, "state": "open"}])
-
-    def test_unknown_marker_kind_has_distinct_cli_error(self):
-        out, err = io.StringIO(), io.StringIO()
-        with redirect_stdout(out), redirect_stderr(err):
-            code = cli.main(
-                ["--kind", "unknown-source", "--slug", "x"],
-                repo="example/repo",
-                gh=lambda _args: self.fail("unknown kinds must fail before scanning"),
-            )
-
-        self.assertEqual(code, 2)
-        self.assertEqual(out.getvalue(), "")
-        self.assertIn("unknown marker kind", err.getvalue())
-
-    def test_cli_bounds_a_hanging_github_call(self):
-        with patch.object(
-            cli.subprocess, "run",
-            side_effect=subprocess.TimeoutExpired("gh", 30),
-        ):
-            with self.assertRaisesRegex(RuntimeError, "timed out after 30s"):
-                cli._gh(["api", "--paginate", "repos/example/repo/issues"])
-
-    def test_cli_classifies_a_missing_github_binary(self):
-        with patch.object(
-            cli.subprocess, "run",
-            side_effect=FileNotFoundError(2, "No such file or directory", "gh"),
-        ):
-            with self.assertRaisesRegex(RuntimeError, "gh CLI unavailable"):
-                cli._gh(["api", "--paginate", "repos/example/repo/issues"])
-
-
-if __name__ == "__main__":
-    unittest.main()