@ikon85/agent-workflow-kit 0.28.0 → 0.29.0

package/scripts/marker_lib.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Shared exact-value HTML marker lookup for issue identity."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+
+
+MARKER_KINDS = frozenset({
+    "prd-source-id",
+    "program-leaf-source",
+    "program-stub-source",
+    "wave-stub-source",
+})
+
+
+class UnknownMarkerKind(ValueError):
+    """Raised when a caller requests a marker outside the public grammar."""
+
+
+def marker_value(body: str, kind: str) -> str | None:
+    """Return one allowlisted marker value from a body, trimmed exactly once."""
+    if kind not in MARKER_KINDS:
+        raise UnknownMarkerKind(f"unknown marker kind: {kind}")
+    match = re.search(rf"<!--\s*{re.escape(kind)}:\s*([^>]+?)\s*-->", body)
+    return match.group(1).strip() if match else None
+
+
+def first_marker(body: str, kinds: tuple[str, ...]) -> tuple[str, str] | None:
+    """Return the first body-ordered marker among validated allowlisted kinds."""
+    unknown = next((kind for kind in kinds if kind not in MARKER_KINDS), None)
+    if unknown:
+        raise UnknownMarkerKind(f"unknown marker kind: {unknown}")
+    alternatives = "|".join(re.escape(kind) for kind in kinds)
+    match = re.search(rf"<!--\s*({alternatives}):\s*([^>]+?)\s*-->", body)
+    return (match.group(1), match.group(2).strip()) if match else None
+
+
+def _issues_from_pages(raw: str) -> list[dict]:
+    pages = json.loads(raw)
+    if not pages:
+        return []
+    if isinstance(pages[0], dict):
+        return pages
+    return [issue for page in pages for issue in page]
+
+
+def marker_verdict(issues: list[dict]) -> str:
+    """Map exact identity matches onto the four-way consumer decision."""
+    if not issues:
+        return "create"
+    if len(issues) > 1:
+        return "STOP"
+    return "update" if issues[0]["state"] == "open" else "user-decision"
+
+
+def find_by_marker(repo: str, kind: str, slug: str,
+                   gh: Callable[[list[str]], str]) -> dict:
+    """Scan every issue state and return exact marker matches plus a verdict."""
+    marker_value("", kind)  # validate before making a network call
+    raw = gh([
+        "api", "--paginate", "--slurp", "--method", "GET",
+        f"repos/{repo}/issues", "-f", "state=all", "-f", "per_page=100",
+    ])
+    matches = [
+        {"number": issue["number"], "state": issue["state"]}
+        for issue in _issues_from_pages(raw)
+        if "pull_request" not in issue
+        and marker_value(issue.get("body") or "", kind) == slug
+    ]
+    return {
+        "count": len(matches),
+        "issues": matches,
+        "verdict": marker_verdict(matches),
+    }
+
+
+def reconcile_after_create(repo: str, kind: str, slug: str,
+                           created_number: int,
+                           gh: Callable[[list[str]], str]) -> dict:
+    """Re-scan after create and fail closed unless that open issue is unique."""
+    result = find_by_marker(repo, kind, slug, gh)
+    expected = [{"number": created_number, "state": "open"}]
+    if result["issues"] != expected:
+        result["verdict"] = "STOP"
+    return result

package/scripts/render-anchor.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Pure rendering for a lean Tier-2 anchor and its full PRD archive."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+from marker_lib import marker_value
+
+
+PLAN_REVISION_RE = re.compile(
+    r"^\s*\*\*plan_revision:\*\*\s*(r\d+)\s*$"
+)
+PLAN_REVISION_LOOKALIKE_RE = re.compile(r"^\s*\*\*plan_revision:\*\*.*$")
+HTML_MARKER_RE = re.compile(
+    r"^\s*<!--\s*(prd-source-id|prd-content-fp|prd):\s*([^>\r\n]+?)\s*-->\s*$"
+)
+HTML_COMMENT_RE = re.compile(r"^\s*<!--.*-->\s*$")
+
+
+class RenderedDocuments(NamedTuple):
+    """The two byte-stable documents produced by one render."""
+
+    anchor_body: str
+    archive_body: str
+
+
+def _canonical_marker(line: str) -> tuple[str, str] | None:
+    revision = PLAN_REVISION_RE.fullmatch(line)
+    if revision:
+        return ("plan_revision", revision.group(1))
+    marker = HTML_MARKER_RE.fullmatch(line)
+    if not marker:
+        return None
+    kind = marker.group(1)
+    if kind == "prd-source-id":
+        value = marker_value(line, kind)
+        return (kind, value) if value is not None else None
+    return (kind, "")
+
+
+def _strip_head_markers(source: str) -> tuple[list[str], str]:
+    revisions: list[str] = []
+    end = 0
+    kept: list[str] = []
+    for line in source.splitlines(keepends=True):
+        bare = line.rstrip("\r\n")
+        marker = _canonical_marker(bare)
+        if (
+            not bare.strip()
+            or marker
+            or HTML_COMMENT_RE.fullmatch(bare)
+            or PLAN_REVISION_LOOKALIKE_RE.fullmatch(bare)
+        ):
+            end += len(line)
+            if marker:
+                if marker[0] == "plan_revision":
+                    revisions.append(marker[1])
+            else:
+                kept.append(line)
+            continue
+        break
+    if not any(line.strip() for line in kept):
+        kept = []
+    while kept and not kept[0].strip():
+        kept.pop(0)
+    return revisions, "".join(kept) + source[end:]
+
+
+def render_documents(anchor_template: str, prd_body: str) -> RenderedDocuments:
+    """Return the filled anchor template and marker-free PRD archive."""
+    revisions, archive_source = _strip_head_markers(prd_body)
+    if len(revisions) != 1:
+        raise ValueError("source PRD head must have exactly one canonical plan_revision")
+    revision = revisions[0]
+    archive_header = (
+        f"📄 Full PRD (archive, {revision}) — "
+        "the body carries navigation/decisions only\n\n"
+    )
+    return RenderedDocuments(anchor_template, archive_header + archive_source)
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Render one filled Tier-2 anchor or its marker-free PRD archive."
+    )
+    parser.add_argument("--template", type=Path, required=True)
+    parser.add_argument("--prd", type=Path, required=True)
+    parser.add_argument("--document", choices=("anchor", "archive"), required=True)
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    rendered = render_documents(
+        args.template.read_bytes().decode("utf-8"),
+        args.prd.read_bytes().decode("utf-8"),
+    )
+    output = (
+        rendered.anchor_body if args.document == "anchor" else rendered.archive_body
+    )
+    sys.stdout.buffer.write(output.encode("utf-8"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/test_marker_lib.py

@@ -0,0 +1,154 @@
+#!/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"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_render_anchor.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Behavior tests for the pure Tier-2 anchor renderer."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPTS = Path(__file__).resolve().parent
+REPO = SCRIPTS.parent
+SKILLS = (
+    REPO / ".claude/skills/to-issues/SKILL.md",
+    REPO / ".agents/skills/to-issues/SKILL.md",
+)
+sys.path.insert(0, str(SCRIPTS))
+SPEC = importlib.util.spec_from_file_location(
+    "render_anchor", SCRIPTS / "render-anchor.py"
+)
+render_anchor = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(render_anchor)
+
+
+class RenderDocumentsGoldenTest(unittest.TestCase):
+    def test_filled_template_and_prd_render_both_documents(self):
+        template = "**Welle 12 — Safer publish.**\n\n## Slices\n| K1 |\n"
+        prd = (
+            "<!-- prd-source-id: safer-publish -->\n"
+            "<!-- prd-content-fp: abc123 -->\n"
+            "**plan_revision:** r4\n"
+            "<!-- prd: awaiting-decomposition -->\n\n"
+            "# Safer publish\n\nFull rationale.\n"
+        )
+
+        rendered = render_anchor.render_documents(template, prd)
+
+        self.assertEqual(rendered.anchor_body, template)
+        self.assertEqual(
+            rendered.archive_body,
+            "📄 Full PRD (archive, r4) — the body carries navigation/decisions only\n\n"
+            "# Safer publish\n\nFull rationale.\n",
+        )
+
+    def test_only_canonical_markers_in_the_head_block_are_stripped(self):
+        template = "Lean anchor\n"
+        prd = (
+            "<!-- wave-stub-source: safer-publish -->\n"
+            "<!-- prd-source-id: safer-publish -->\n"
+            "**plan_revision:** r5\n"
+            "<!-- prd: awaiting-decomposition -->\n\n"
+            "# PRD\n\n"
+            "```md\n**plan_revision:** fake\n"
+            "<!-- prd-source-id: quoted-example -->\n```\n\n"
+            "> **plan_revision:** quoted-fake\n"
+        )
+
+        rendered = render_anchor.render_documents(template, prd)
+
+        self.assertEqual(
+            rendered.archive_body,
+            "📄 Full PRD (archive, r5) — the body carries navigation/decisions only\n\n"
+            "<!-- wave-stub-source: safer-publish -->\n\n# PRD\n\n"
+            "```md\n**plan_revision:** fake\n"
+            "<!-- prd-source-id: quoted-example -->\n```\n\n"
+            "> **plan_revision:** quoted-fake\n",
+        )
+
+    def test_duplicate_plan_revisions_fail_closed(self):
+        for revisions in (("r5", "r5"), ("r5", "r6")):
+            with self.subTest(revisions=revisions):
+                prd = (
+                    f"**plan_revision:** {revisions[0]}\n"
+                    f"**plan_revision:** {revisions[1]}\n\n# PRD\n"
+                )
+                with self.assertRaisesRegex(
+                    ValueError, "exactly one canonical plan_revision"
+                ):
+                    render_anchor.render_documents("Lean anchor\n", prd)
+
+    def test_plan_revision_requires_numeric_canonical_value(self):
+        for lookalike in ("rfoo", "r5!"):
+            with self.subTest(lookalike=lookalike, valid_revision=True):
+                malformed = f"**plan_revision:** {lookalike}"
+                prd = f"{malformed}\n**plan_revision:** r5\n\n# PRD\n"
+                rendered = render_anchor.render_documents("Lean anchor\n", prd)
+                self.assertIn(malformed, rendered.archive_body)
+
+            with self.subTest(lookalike=lookalike, valid_revision=False):
+                with self.assertRaisesRegex(
+                    ValueError, "exactly one canonical plan_revision"
+                ):
+                    render_anchor.render_documents(
+                        "Lean anchor\n", f"**plan_revision:** {lookalike}\n# PRD\n"
+                    )
+
+    def test_malformed_marker_lookalikes_are_preserved(self):
+        lookalikes = (
+            "<!-- prd-source-id: alpha --> trailing -->",
+            "<!-- prd-content-fp: abc > trailing -->",
+            "<!-- prd: program > trailing -->",
+        )
+        for lookalike in lookalikes:
+            with self.subTest(lookalike=lookalike):
+                prd = (
+                    f"{lookalike}\n"
+                    "<!-- prd-source-id: canonical -->\n"
+                    "<!-- prd-content-fp: abc123 -->\n"
+                    "**plan_revision:** r5\n"
+                    "<!-- prd: awaiting-decomposition -->\n\n# PRD\n"
+                )
+
+                rendered = render_anchor.render_documents("Lean anchor\n", prd)
+
+                self.assertIn(lookalike, rendered.archive_body)
+                self.assertNotIn(
+                    "<!-- prd-source-id: canonical -->", rendered.archive_body
+                )
+                self.assertNotIn(
+                    "<!-- prd-content-fp: abc123 -->", rendered.archive_body
+                )
+                self.assertNotIn(
+                    "<!-- prd: awaiting-decomposition -->", rendered.archive_body
+                )
+
+    def test_cli_emits_each_document_without_mutating_inputs(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            template = root / "anchor.md"
+            prd = root / "prd.md"
+            template.write_text("Lean anchor\n", encoding="utf-8")
+            prd.write_text(
+                "**plan_revision:** r2\n\n# Full PRD\n", encoding="utf-8"
+            )
+            original = (template.read_bytes(), prd.read_bytes())
+
+            first = self._run_cli(template, prd, "archive")
+            second = self._run_cli(template, prd, "archive")
+            anchor = self._run_cli(template, prd, "anchor")
+
+            self.assertEqual(first.stdout, second.stdout)
+            self.assertEqual(anchor.stdout, b"Lean anchor\n")
+            self.assertEqual((template.read_bytes(), prd.read_bytes()), original)
+
+    def test_cli_archive_is_utf8_when_python_io_encoding_is_ascii(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            template = root / "anchor.md"
+            prd = root / "prd.md"
+            template.write_text("Lean anchor\n", encoding="utf-8")
+            prd.write_text("**plan_revision:** r2\n\n# PRD\n", encoding="utf-8")
+
+            result = self._run_cli(
+                template,
+                prd,
+                "archive",
+                env={**os.environ, "PYTHONIOENCODING": "ascii"},
+            )
+
+            self.assertTrue(result.stdout.startswith("📄".encode("utf-8")))
+
+    def _run_cli(
+        self, template: Path, prd: Path, document: str, env: dict | None = None
+    ):
+        return subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPTS / "render-anchor.py"),
+                "--template",
+                str(template),
+                "--prd",
+                str(prd),
+                "--document",
+                document,
+            ],
+            check=True,
+            capture_output=True,
+            env=env,
+        )
+
+
+class PromotionStateTableTest(unittest.TestCase):
+    EXPECTED_ROWS = {
+        "initial": (
+            "`S=yes`, `B=no`, `C=0`, `P=absent`",
+            "render + write body",
+        ),
+        "body-written": (
+            "`S=n/a`, `B=yes`, `C=0`, `P=absent`",
+            "reconcile + write archive comment",
+        ),
+        "comment-written": (
+            "`S=n/a`, `B=yes`, `C=exact-1`, `P=absent`",
+            "promote board state",
+        ),
+        "promoted": (
+            "`S=n/a`, `B=yes`, `C=exact-1`, `P=complete`",
+            "no-op; continue publish audit",
+        ),
+    }
+    EXPECTED_BOARD_OBSERVATIONS = {
+        "ordinary-prestate": "absent",
+        "stufe-1p-prestate": "absent",
+        "promoted": "complete",
+        "cluster-only": "partial",
+        "wrong-wave": "partial",
+    }
+
+    def test_all_four_observable_states_have_one_resume_action(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            start = text.index("<!-- promotion-state-table:start -->")
+            end = text.index("<!-- promotion-state-table:end -->", start)
+            rows = {}
+            for line in text[start:end].splitlines():
+                if line.startswith("| `"):
+                    cells = [cell.strip() for cell in line.strip("|").split("|")]
+                    rows[cells[0].strip("`")] = (cells[1], cells[2])
+            self.assertEqual(rows, self.EXPECTED_ROWS, str(path))
+
+    def test_corrupt_comments_and_partial_board_writes_are_drift(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertIn("`C=wrong-1`", text, str(path))
+            self.assertIn("`C=duplicates(<ids>)`", text, str(path))
+            self.assertIn("`P=partial`", text, str(path))
+            self.assertIn("drift and enters repair", text, str(path))
+
+    def test_stufe_1p_prestamp_is_not_partial_promotion(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            start = text.index("<!-- promotion-board-observation-table:start -->")
+            end = text.index("<!-- promotion-board-observation-table:end -->", start)
+            rows = {}
+            for line in text[start:end].splitlines():
+                if line.startswith("| `"):
+                    cells = [cell.strip() for cell in line.strip("|").split("|")]
+                    rows[cells[0].strip("`")] = cells[2].strip("`")
+            self.assertEqual(rows, self.EXPECTED_BOARD_OBSERVATIONS, str(path))
+
+    def test_post_initial_body_drift_requires_an_operator_decision(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertIn("outside the valid `initial` tuple", text, str(path))
+            self.assertIn("report the body diff", text, str(path))
+            self.assertRegex(text, r"explicit\s+operator decision", str(path))
+            self.assertNotIn(
+                "wrong/missing `B` → rerender and rewrite the body", text, str(path)
+            )
+
+    def test_stale_source_snapshot_stops_before_body_write(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertRegex(text, r"Pre:\s+`S=yes`, `B=no`", str(path))
+            self.assertRegex(text, r"Post:\s+`S=n/a`, `B=yes`", str(path))
+            self.assertIn("`S=no`", text, str(path))
+            self.assertIn("re-fetch the remote body", text, str(path))
+            self.assertRegex(text, r"never\s+write the\s+stale render", str(path))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_retro_wrapup_contract.py

@@ -77,6 +77,12 @@ class WrapupChainingContract(unittest.TestCase):
                 for phrase in required:
                     self.assertIn(phrase, text)
 
+    def test_wrapup_does_not_forbid_its_affirmative_retro_chain(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                self.assertNotIn("never run by this skill", text.lower())
+
     def test_only_model_invocable_non_deploying_workflows_chain(self):
         required = (
             "model-invocable",