agentic-devtools 0.2.332__py3-none-any.whl → 0.2.333__py3-none-any.whl

agentic_devtools/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.332'
-__version_tuple__ = version_tuple = (0, 2, 332)
+__version__ = version = '0.2.333'
+__version_tuple__ = version_tuple = (0, 2, 333)
 
 __commit_id__ = commit_id = None

agentic_devtools/adapters/__init__.py

@@ -31,6 +31,7 @@ from agentic_devtools.adapters.base import (
 from agentic_devtools.adapters.exceptions import AdapterError, AdapterValidationError
 from agentic_devtools.adapters.factory import get_issue_provider
 from agentic_devtools.adapters.github_adapter import GitHubIssuesAdapter
+from agentic_devtools.adapters.idempotency_query_provider import IdempotencyQueryProvider
 from agentic_devtools.adapters.issue_provider import (
     VALID_ISSUE_TYPES,
     InMemoryIssueProvider,
@@ -50,7 +51,9 @@ from agentic_devtools.adapters.issue_type_mapping import (
 )
 from agentic_devtools.adapters.jira_adapter import JiraAdapter
 from agentic_devtools.adapters.markdown_adapter import MarkdownAdapter
+from agentic_devtools.adapters.operation_plan import OperationDescriptor, OperationPlan
 from agentic_devtools.adapters.orchestration_key import generate_orchestration_key
+from agentic_devtools.adapters.plan_manifest import execute_manifest, plan_manifest
 from agentic_devtools.config import load_platform_config
 from agentic_devtools.tools.jira import JiraConfig
 
@@ -61,6 +64,7 @@ __all__ = [
     "CommentResult",
     "GitHubIssuesAdapter",
     "GitHubMappingResult",
+    "IdempotencyQueryProvider",
     "InMemoryIssueProvider",
     "IssueAdapter",
     "IssueDetail",
@@ -75,11 +79,14 @@ __all__ = [
     "JiraMappingResult",
     "MarkdownAdapter",
     "NormalizedIssue",
+    "OperationDescriptor",
+    "OperationPlan",
     "PropertySchema",
     "ProviderIssueResult",
     "ProviderLinkResult",
     "TypeMapping",
     "VALID_ISSUE_TYPES",
+    "execute_manifest",
     "generate_orchestration_key",
     "get_adapter",
     "get_issue_provider",
@@ -87,6 +94,7 @@ __all__ = [
     "load_jira_type_mapping",
     "map_issue_type_to_github_labels",
     "map_issue_type_to_jira",
+    "plan_manifest",
 ]
 
 

agentic_devtools/adapters/idempotency_query_provider.py

@@ -0,0 +1,64 @@
+"""IdempotencyQueryProvider protocol for adapter-level existence queries.
+
+Separated from ``IssueProvider`` (which has exactly 8 methods) to avoid
+a breaking change to the mutation protocol.  Used by the orchestrator
+when ``dry_run=True`` and ``check_existing=True``.
+
+All ``*_provider_id`` parameters accept provider-native string identifiers
+(e.g., ``"42"`` for GitHub, ``"PROJ-123"`` for Jira).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from agentic_devtools.adapters.issue_provider import ProviderIssueResult, ProviderLinkResult
+
+
+@runtime_checkable
+class IdempotencyQueryProvider(Protocol):
+    """Companion protocol for adapter-level idempotency queries.
+
+    Separated from IssueProvider (which has exactly 8 methods) to avoid
+    a breaking change to the mutation protocol. Used by the orchestrator
+    when dry_run=True and check_existing=True.
+
+    All *_provider_id parameters accept provider-native string identifiers
+    (e.g., "42" for GitHub, "PROJ-123" for Jira).
+    """
+
+    def find_existing_issue(
+        self,
+        orchestration_key: str,
+    ) -> ProviderIssueResult | None:
+        """Find an issue by its embedded orchestration key.
+
+        Returns ProviderIssueResult with status="existing" if found,
+        None if not found. Raises ValueError if multiple matches found
+        (ambiguous state — FR-008).
+        """
+        ...  # pragma: no cover
+
+    def find_existing_link(
+        self,
+        parent_provider_id: str,
+        child_provider_id: str,
+    ) -> ProviderLinkResult | None:
+        """Check if a parent-child link already exists.
+
+        Returns ProviderLinkResult with status="already-linked" if found,
+        None if not found.
+        """
+        ...  # pragma: no cover
+
+    def find_existing_dependency(
+        self,
+        issue_provider_id: str,
+        blocked_by_provider_id: str,
+    ) -> ProviderLinkResult | None:
+        """Check if a blocking dependency already exists.
+
+        Returns ProviderLinkResult with status="already-linked" if found,
+        None if not found.
+        """
+        ...  # pragma: no cover

agentic_devtools/adapters/issue_provider.py

@@ -703,3 +703,68 @@ class InMemoryIssueProvider:
                 return f"#{identifier}"
             return identifier
         return identifier
+
+    # -- IdempotencyQueryProvider methods --
+
+    def find_existing_issue(self, orchestration_key: str) -> ProviderIssueResult | None:
+        """Find issue by orchestration key embedded in body.
+
+        Searches all stored issues for a body containing the given key.
+        Also checks the idempotency_keys mapping.
+
+        Raises:
+            ValueError: If multiple issues match (ambiguous state — FR-008).
+        """
+        from agentic_devtools.adapters.orchestration_key import extract_orchestration_key
+
+        matches: list[str] = []
+        for identifier, data in self._issues.items():
+            body_val = data.get("body")
+            key = extract_orchestration_key(body_val if isinstance(body_val, str) else "")
+            if key == orchestration_key:
+                matches.append(identifier)
+        if len(matches) > 1:
+            raise ValueError(f"Ambiguous: key {orchestration_key!r} matched {len(matches)} issues: {matches}")
+        if not matches:
+            # Check idempotency_keys mapping as fallback
+            ident = self._idempotency_keys.get(orchestration_key)
+            if ident is not None:
+                matches.append(ident)
+        if not matches:
+            return None
+        ident = matches[0]
+        return ProviderIssueResult(
+            identifier=ident,
+            url=f"https://fake.test/issues/{ident}",
+            status="existing",
+        )
+
+    def find_existing_link(self, parent_provider_id: str, child_provider_id: str) -> ProviderLinkResult | None:
+        """Check if a parent-child link already exists.
+
+        Returns ProviderLinkResult with status="already-linked" if found,
+        None if not found.
+        """
+        if (parent_provider_id, child_provider_id) in self._parent_child:
+            return ProviderLinkResult(
+                source_id=parent_provider_id,
+                target_id=child_provider_id,
+                status="already-linked",
+            )
+        return None
+
+    def find_existing_dependency(
+        self, issue_provider_id: str, blocked_by_provider_id: str
+    ) -> ProviderLinkResult | None:
+        """Check if a blocking dependency already exists.
+
+        Returns ProviderLinkResult with status="already-linked" if found,
+        None if not found.
+        """
+        if (issue_provider_id, blocked_by_provider_id) in self._blocked_by:
+            return ProviderLinkResult(
+                source_id=blocked_by_provider_id,
+                target_id=issue_provider_id,
+                status="already-linked",
+            )
+        return None

agentic_devtools/adapters/jira_provider.py

@@ -550,33 +550,12 @@ class JiraProvider:
             )
 
         # Resolve the epic-link custom field once (cached after first call).
-        epic_field = self._get_epic_link_field()
-
-        # Idempotency check: GET child issue to see if the parent is already set,
-        # either via the epic-link field or the standard parent field.
-        get_url = self._api_url(f"/issue/{child_id}?fields={epic_field},parent")
-        get_resp = self._request("GET", get_url)
-        if get_resp.status_code == 404:
-            raise ValueError(f"Issue '{child_id}' not found.")
-        get_resp.raise_for_status()
-        get_data = get_resp.json()
-        if isinstance(get_data, dict):
-            _fields_raw = get_data.get("fields")
-            get_fields = _fields_raw if isinstance(_fields_raw, dict) else {}
-            if get_fields.get(epic_field) == parent_id:
-                return ProviderLinkResult(
-                    source_id=parent_id,
-                    target_id=child_id,
-                    status="already-linked",
-                )
-            parent_field_val = get_fields.get("parent")
-            if isinstance(parent_field_val, dict) and parent_field_val.get("key") == parent_id:
-                return ProviderLinkResult(
-                    source_id=parent_id,
-                    target_id=child_id,
-                    status="already-linked",
-                )
+        # Idempotency check via find_existing_link (FR-003)
+        existing = self.find_existing_link(parent_id, child_id)
+        if existing is not None:
+            return existing
 
+        epic_field = self._get_epic_link_field()
         url = self._api_url(f"/issue/{child_id}")
         payload = {"fields": {epic_field: parent_id}}
         epic_resp = self._request("PUT", url, json=payload)
@@ -646,35 +625,10 @@ class JiraProvider:
             )
 
         url = self._api_url("/issueLink")
-        # Check for an existing "Blocks" link before creating (idempotency).
-        get_url = self._api_url(f"/issue/{issue_id}?fields=issuelinks")
-        get_resp = self._request("GET", get_url)
-        if get_resp.status_code == 404:
-            raise ValueError(f"Cannot check existing links because issue '{issue_id}' was not found.")
-        get_resp.raise_for_status()
-        get_data = get_resp.json()
-        if isinstance(get_data, dict):
-            _fields_raw = get_data.get("fields")
-            fields = _fields_raw if isinstance(_fields_raw, dict) else {}
-            existing_links = fields.get("issuelinks") or []
-            for link in existing_links:
-                if not isinstance(link, dict):
-                    continue
-                link_type = link.get("type")
-                if not isinstance(link_type, dict):
-                    continue
-                if (link_type.get("name") or "").lower() == "blocks":
-                    _raw_outward = link.get("outwardIssue")
-                    outward = _raw_outward if isinstance(_raw_outward, dict) else {}
-                    # Only the outward direction means "blocked_by_id blocks issue_id".
-                    # inwardIssue=blocked_by_id would mean the opposite edge (issue_id
-                    # blocks blocked_by_id) and must NOT short-circuit idempotency.
-                    if outward.get("key") == blocked_by_id:
-                        return ProviderLinkResult(
-                            source_id=blocked_by_id,
-                            target_id=issue_id,
-                            status="already-linked",
-                        )
+        # Idempotency check via find_existing_dependency (FR-004)
+        existing = self.find_existing_dependency(issue_id, blocked_by_id)
+        if existing is not None:
+            return existing
 
         payload = {
             "type": {"name": "Blocks"},
@@ -811,29 +765,140 @@ class JiraProvider:
         return self._effective_type_map[type_lower]
 
     def _find_by_orchestration_key(self, orch_key: str) -> ProviderIssueResult | None:
-        """Search for an existing issue via JQL with orchestration key."""
-        jql = f'project = "{self._project_key}" AND description ~ "agdt-orch-key:{orch_key}"'
+        """Search for an existing issue via JQL with orchestration key.
+
+        Internal helper that delegates to :meth:`find_existing_issue`.
+        """
+        return self.find_existing_issue(orch_key)
+
+    # ------------------------------------------------------------------
+    # IdempotencyQueryProvider methods
+    # ------------------------------------------------------------------
+
+    def find_existing_issue(self, orchestration_key: str) -> ProviderIssueResult | None:
+        """Find an issue by its embedded orchestration key via JQL search.
+
+        Raises ValueError if multiple issues match (ambiguous state — FR-008).
+        Propagates network/provider errors (FR-009).
+        """
+        jql = f'project = "{self._project_key}" AND description ~ "agdt-orch-key:{orchestration_key}"'
         url = self._api_url("/search")
-        params = {"jql": jql, "maxResults": "1", "fields": "key,summary"}
+        params = {"jql": jql, "maxResults": "10", "fields": "key,summary"}
 
-        try:
-            resp = self._request("GET", url, params=params)
-            resp.raise_for_status()
-            data = resp.json()
-            issues = data.get("issues", [])
-            if issues:
-                issue = issues[0]
-                issue_key = issue.get("key", "")
-                return ProviderIssueResult(
-                    identifier=issue_key,
-                    url=f"{self._base_url}/browse/{issue_key}",
-                    status="existing",
-                    metadata={"id": issue.get("id", "")},
+        resp = self._request("GET", url, params=params)
+        resp.raise_for_status()
+        data = resp.json()
+        if not isinstance(data, dict):
+            raise ValueError(f"find_existing_issue: expected a JSON object from Jira search, got {type(data).__name__}")
+        issues = data.get("issues", [])
+        if not isinstance(issues, list):
+            raise ValueError(f"find_existing_issue: expected 'issues' to be a list, got {type(issues).__name__}")
+        if len(issues) > 1:
+            ids = [issue.get("key", "") if isinstance(issue, dict) else repr(issue) for issue in issues]
+            raise ValueError(
+                f"Ambiguous state: orchestration key {orchestration_key!r} "
+                f"matched {len(issues)} issues: {ids}. "
+                f"Resolve manually before re-running."
+            )
+        if issues:
+            issue = issues[0]
+            if not isinstance(issue, dict):
+                raise ValueError(
+                    f"find_existing_issue: expected issue entry to be a JSON object, got {type(issue).__name__}"
+                )
+            issue_key = issue.get("key", "")
+            if not isinstance(issue_key, str) or not issue_key.strip():
+                raise ValueError(
+                    f"find_existing_issue: expected issue 'key' to be a non-empty string, got {issue_key!r}"
                 )
-        except TransientError:
-            raise
-        except Exception:
-            pass
+            return ProviderIssueResult(
+                identifier=issue_key,
+                url=f"{self._base_url}/browse/{issue_key}",
+                status="existing",
+                metadata={"id": issue.get("id", "")},
+            )
+        return None
+
+    def find_existing_link(self, parent_provider_id: str, child_provider_id: str) -> ProviderLinkResult | None:
+        """Check if a parent-child link already exists (FR-003).
+
+        GETs the child issue and inspects epic-link and parent fields.
+        Returns ProviderLinkResult with status="already-linked" if found,
+        None if not found. Propagates network errors (FR-009).
+        """
+        epic_field = self._get_epic_link_field()
+        get_url = self._api_url(f"/issue/{child_provider_id}?fields={epic_field},parent")
+        get_resp = self._request("GET", get_url)
+        if get_resp.status_code == 404:
+            return None
+        get_resp.raise_for_status()
+        get_data = get_resp.json()
+        if not isinstance(get_data, dict):
+            raise ValueError(f"find_existing_link: expected a JSON object from Jira, got {type(get_data).__name__}")
+        _fields_raw = get_data.get("fields")
+        get_fields = _fields_raw if isinstance(_fields_raw, dict) else {}
+        if get_fields.get(epic_field) == parent_provider_id:
+            return ProviderLinkResult(
+                source_id=parent_provider_id,
+                target_id=child_provider_id,
+                status="already-linked",
+            )
+        parent_field_val = get_fields.get("parent")
+        if isinstance(parent_field_val, dict) and parent_field_val.get("key") == parent_provider_id:
+            return ProviderLinkResult(
+                source_id=parent_provider_id,
+                target_id=child_provider_id,
+                status="already-linked",
+            )
+        return None
+
+    def find_existing_dependency(
+        self, issue_provider_id: str, blocked_by_provider_id: str
+    ) -> ProviderLinkResult | None:
+        """Check if a blocking dependency already exists (FR-004).
+
+        GETs the issue's links and checks for a "Blocks" outward link
+        to blocked_by_provider_id. Returns ProviderLinkResult with
+        status="already-linked" if found, None if not found.
+        Propagates network errors (FR-009).
+        """
+        get_url = self._api_url(f"/issue/{issue_provider_id}?fields=issuelinks")
+        get_resp = self._request("GET", get_url)
+        if get_resp.status_code == 404:
+            return None
+        get_resp.raise_for_status()
+        get_data = get_resp.json()
+        if not isinstance(get_data, dict):
+            raise ValueError(
+                f"find_existing_dependency: expected a JSON object from Jira, got {type(get_data).__name__}"
+            )
+        _fields_raw = get_data.get("fields")
+        fields = _fields_raw if isinstance(_fields_raw, dict) else {}
+        existing_links_raw = fields.get("issuelinks")
+        if existing_links_raw is None:
+            existing_links: list[Any] = []
+        elif isinstance(existing_links_raw, list):
+            existing_links = existing_links_raw
+        else:
+            raise ValueError(
+                "find_existing_dependency: expected fields.issuelinks to be a list when present, "
+                f"got {type(existing_links_raw).__name__}"
+            )
+        for link in existing_links:
+            if not isinstance(link, dict):
+                continue
+            link_type = link.get("type")
+            if not isinstance(link_type, dict):
+                continue
+            if (link_type.get("name") or "").lower() == "blocks":
+                _raw_outward = link.get("outwardIssue")
+                outward = _raw_outward if isinstance(_raw_outward, dict) else {}
+                if outward.get("key") == blocked_by_provider_id:
+                    return ProviderLinkResult(
+                        source_id=blocked_by_provider_id,
+                        target_id=issue_provider_id,
+                        status="already-linked",
+                    )
         return None
 
     # ------------------------------------------------------------------

agentic_devtools/adapters/operation_plan.py

@@ -0,0 +1,111 @@
+"""Operation plan data model for dry-run and execution tracking (FR-006).
+
+Defines ``OperationDescriptor`` (a single planned/executed operation) and
+``OperationPlan`` (an ordered collection of descriptors).  Both are frozen
+dataclasses — strictly in-memory, not designed for disk persistence.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentic_devtools.adapters.issue_provider import ProviderIssueResult, ProviderLinkResult
+
+
+@dataclass(frozen=True)
+class OperationDescriptor:
+    """A single planned or executed operation.
+
+    Attributes:
+        operation_type: One of "create_issue", "link_subissue", or "add_blocked_by".
+        orchestration_key: 64-char hex SHA-256 key for this operation.
+        refs: Manifest refs used in key derivation, in canonical order.
+        status: Operation outcome — "dry-run", "existing", "already-linked",
+            "created", or "linked".
+        provider_params: Provider-facing operation inputs captured in the
+            plan (for example title/issue_type/labels, plus ref-based
+            relationship fields such as parent_ref/child_ref/blocked_by_ref
+            used during planning before provider identifiers are resolved).
+        result: The adapter result object, or None for planning-only dry-run.
+    """
+
+    operation_type: str
+    orchestration_key: str
+    refs: tuple[str, ...]
+    status: str
+    provider_params: dict[str, Any] = field(default_factory=dict)
+    result: ProviderIssueResult | ProviderLinkResult | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dictionary representation."""
+        result_dict: dict[str, Any] | None = None
+        if self.result is not None:
+            result_dict = self.result.to_dict()
+        return {
+            "operation_type": self.operation_type,
+            "orchestration_key": self.orchestration_key,
+            "refs": list(self.refs),
+            "status": self.status,
+            "provider_params": copy.deepcopy(self.provider_params),
+            "result": result_dict,
+        }
+
+    @property
+    def is_dry_run(self) -> bool:
+        """Return True if this descriptor represents a dry-run operation."""
+        return self.status == "dry-run"
+
+    @property
+    def is_existing(self) -> bool:
+        """Return True if this descriptor represents an already-existing entity."""
+        return self.status in ("existing", "already-linked")
+
+
+@dataclass(frozen=True)
+class OperationPlan:
+    """An ordered collection of operation descriptors.
+
+    Strictly in-memory — not designed for serialization to disk for
+    cross-run resumption. The orchestrator re-derives the plan from the
+    manifest on each invocation.
+
+    Attributes:
+        operations: Dependency-safe ordered tuple of descriptors.
+        dry_run: Whether this plan was generated in dry-run mode.
+        check_existing: Whether existence checks were performed.
+    """
+
+    operations: tuple[OperationDescriptor, ...]
+    dry_run: bool
+    check_existing: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dictionary representation."""
+        return {
+            "operations": [op.to_dict() for op in self.operations],
+            "dry_run": self.dry_run,
+            "check_existing": self.check_existing,
+            "summary": {
+                "total": len(self.operations),
+                "creates": len(self.create_operations),
+                "links": len(self.link_operations),
+                "dependencies": len(self.dependency_operations),
+            },
+        }
+
+    @property
+    def create_operations(self) -> tuple[OperationDescriptor, ...]:
+        """Return only create_issue operations."""
+        return tuple(op for op in self.operations if op.operation_type == "create_issue")
+
+    @property
+    def link_operations(self) -> tuple[OperationDescriptor, ...]:
+        """Return only link_subissue operations."""
+        return tuple(op for op in self.operations if op.operation_type == "link_subissue")
+
+    @property
+    def dependency_operations(self) -> tuple[OperationDescriptor, ...]:
+        """Return only add_blocked_by operations."""
+        return tuple(op for op in self.operations if op.operation_type == "add_blocked_by")

agentic_devtools/adapters/orchestration_key.py

@@ -1,15 +1,23 @@
 """Orchestration key generation and embedding utilities.
 
-An orchestration key is a SHA-256 hash derived from:
-  - source_issue_key: The originating issue identifier (e.g., "#2108")
-  - structural_position: Dot-notation path in the hierarchy (e.g., "epic.features[0]")
-  - content_hash: Hash of the issue title/body content for uniqueness
+An orchestration key is a deterministic SHA-256 hash derived from:
+  - operation_type: The operation name (e.g., "create_issue", "link_subissue")
+  - refs: One or more ref values in canonical order matching the IssueProvider
+    method signature for the given operation
+
+Algorithm: SHA-256 of the UTF-8 encoding of the NUL-separated (``\\x00``)
+concatenation of ``operation_type`` followed by all ref values in signature order.
 
 The key is embedded in issue bodies as an HTML comment:
   ``<!-- agdt-orch-key:SHA256_HEX -->``
 
 This enables idempotent find-before-create semantics — the provider can search
 for an existing issue bearing the same orchestration key before creating a new one.
+
+Compatibility: The pre-#2114 algorithm (colon-separated ``source:position:content_hash``)
+is explicitly **not** backward-compatible. Orchestration keys generated with the prior
+algorithm will not match keys from this implementation. The embedding format
+(``<!-- agdt-orch-key:<64hex> -->``) remains unchanged (NFR-002).
 """
 
 from __future__ import annotations
@@ -21,22 +29,38 @@ import re
 _ORCH_KEY_PATTERN = re.compile(r"<!-- agdt-orch-key:([a-f0-9]{64}) -->", re.IGNORECASE)
 
 
-def generate_orchestration_key(
-    source_issue_key: str,
-    structural_position: str,
-    content_hash: str,
-) -> str:
-    """Generate a SHA-256 orchestration key.
+def generate_orchestration_key(operation_type: str, *refs: str) -> str:
+    """Generate a deterministic SHA-256 orchestration key.
+
+    Algorithm: SHA-256 of UTF-8 encoding of the NUL-separated concatenation
+    of operation_type followed by all ref values in signature order.
 
     Args:
-        source_issue_key: The originating issue identifier.
-        structural_position: Dot-notation path in the hierarchy.
-        content_hash: Hash or fingerprint of the issue content.
+        operation_type: The operation name (e.g., "create_issue").
+        *refs: Ref values in the canonical order matching the IssueProvider
+            method signature for this operation.
 
     Returns:
-        A 64-character lowercase hex SHA-256 hash.
+        A 64-character lowercase hex SHA-256 digest.
+
+    Raises:
+        ValueError: If operation_type is not a string, empty/whitespace-only,
+            or if operation_type or any ref contains a NUL byte (``\\x00``).
+            If any ref is not a string.
     """
-    payload = f"{source_issue_key}:{structural_position}:{content_hash}"
+    if not isinstance(operation_type, str):
+        raise ValueError(f"operation_type must be a string, got {type(operation_type).__name__}")
+    if not operation_type or not operation_type.strip():
+        raise ValueError("operation_type must be a non-empty string")
+    if "\x00" in operation_type:
+        raise ValueError("operation_type must not contain NUL bytes")
+    for ref in refs:
+        if not isinstance(ref, str):
+            raise ValueError(f"each ref must be a string, got {type(ref).__name__}")
+        if "\x00" in ref:
+            raise ValueError("refs must not contain NUL bytes")
+
+    payload = "\x00".join((operation_type, *refs))
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
 
 

agentic_devtools/adapters/plan_manifest.py

@@ -0,0 +1,437 @@
+"""Manifest planning and execution for dry-run and idempotent issue creation.
+
+Provides ``plan_manifest()`` for assembling a dependency-safe ``OperationPlan``
+from a JSON manifest, and ``execute_manifest()`` as a convenience wrapper for
+real execution mode.
+
+The manifest describes a tree of issues with parent-child and blocking
+relationships. The orchestrator traverses the manifest in topological order,
+computes orchestration keys for each operation, and either previews (dry-run)
+or executes (real) the operations through an ``IssueProvider``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentic_devtools.adapters.cycle_detection import CycleDetectedError, detect_cycles
+from agentic_devtools.adapters.idempotency_query_provider import IdempotencyQueryProvider
+from agentic_devtools.adapters.issue_provider import VALID_ISSUE_TYPES, IssueProvider
+from agentic_devtools.adapters.operation_plan import OperationDescriptor, OperationPlan
+from agentic_devtools.adapters.orchestration_key import embed_orchestration_key, generate_orchestration_key
+
+
+def plan_manifest(
+    manifest: dict[str, Any],
+    provider: IssueProvider,
+    *,
+    dry_run: bool = True,
+    check_existing: bool = False,
+    query_provider: IdempotencyQueryProvider | None = None,
+) -> OperationPlan:
+    """Assemble a dependency-safe operation plan from a manifest.
+
+    Args:
+        manifest: JSON manifest with "nodes" list. Each node has "ref",
+            "title", "body", "issue_type", and optionally "parent_ref"
+            and "blocked_by" (list of refs).
+        provider: IssueProvider for dry-run param extraction / real execution.
+        dry_run: When True, no mutations. When False, execute operations.
+        check_existing: When True (dry-run only), query provider for
+            existing entities. Requires query_provider.
+        query_provider: IdempotencyQueryProvider for existence checks.
+            Required when check_existing=True.
+
+    Returns:
+        OperationPlan with ordered OperationDescriptor entries.
+
+    Raises:
+        ValueError: If check_existing=True but query_provider is None.
+        ValueError: If check_existing=True but dry_run=False.
+        ValueError: If check_existing=True but query_provider does not implement
+            the IdempotencyQueryProvider protocol.
+        ValueError: If manifest is not a dict, manifest['nodes'] is not a list,
+            any node is not a dict, a node is missing a required key
+            ('ref', 'title', 'issue_type'), a required key value is not a
+            non-empty string after trimming, issue_type is unsupported,
+            'body' is present but is neither a string nor null,
+            'blocked_by' or 'labels' is present but not a list,
+            or duplicate refs are detected.
+        ValueError: If a circular dependency is detected among manifest nodes.
+        ValueError: If a node's parent_ref or blocked_by ref cannot be resolved during real execution.
+        Any provider error: Propagated from adapter calls (FR-009).
+    """
+    if check_existing and query_provider is None:
+        raise ValueError("check_existing=True requires a query_provider")
+    if check_existing and not dry_run:
+        raise ValueError("check_existing=True is only valid with dry_run=True")
+    if check_existing and not isinstance(query_provider, IdempotencyQueryProvider):
+        raise ValueError(
+            f"query_provider must implement the IdempotencyQueryProvider protocol, got {type(query_provider).__name__}"
+        )
+
+    if not isinstance(manifest, dict):
+        raise ValueError(f"manifest must be a dict, got {type(manifest).__name__}")
+
+    nodes = manifest.get("nodes", [])
+
+    # Validate manifest structure up front for deterministic, actionable errors.
+    if not isinstance(nodes, list):
+        raise ValueError(f"manifest['nodes'] must be a list, got {type(nodes).__name__}")
+    validated_nodes: list[dict[str, Any]] = []
+    seen_refs: set[str] = set()
+    for i, node in enumerate(nodes):
+        if not isinstance(node, dict):
+            raise ValueError(f"manifest['nodes'][{i}] must be a dict, got {type(node).__name__}")
+        normalized_node = dict(node)
+        for key in ("ref", "title", "issue_type"):
+            if key not in node:
+                raise ValueError(f"manifest['nodes'][{i}] missing required key {key!r}")
+            value = node[key]
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(
+                    f"manifest['nodes'][{i}][{key!r}] must be a non-empty string, got {type(value).__name__!r}"
+                )
+            if key == "issue_type":
+                normalized_value = value.strip().lower()
+                if normalized_value not in VALID_ISSUE_TYPES:
+                    raise ValueError(
+                        f"Unsupported issue_type {normalized_value!r}. Valid types: {sorted(VALID_ISSUE_TYPES)}"
+                    )
+            else:
+                normalized_value = value.strip()
+            normalized_node[key] = normalized_value
+        if "body" in node and node["body"] is not None and not isinstance(node["body"], str):
+            raise ValueError(
+                f"manifest['nodes'][{i}]['body'] must be a string or null, got {type(node['body']).__name__!r}"
+            )
+        if "parent_ref" in node:
+            parent_ref_val = node["parent_ref"]
+            if not isinstance(parent_ref_val, str) or not parent_ref_val.strip():
+                raise ValueError(
+                    f"manifest['nodes'][{i}]['parent_ref'] must be a non-empty string, "
+                    f"got {type(parent_ref_val).__name__!r}"
+                )
+            normalized_node["parent_ref"] = parent_ref_val.strip()
+        for list_key in ("blocked_by", "labels"):
+            if list_key not in node:
+                continue
+            value = node[list_key]
+            if not isinstance(value, list):
+                raise ValueError(f"manifest['nodes'][{i}][{list_key!r}] must be a list, got {type(value).__name__!r}")
+            normalized_elems: list[str] = []
+            for j, elem in enumerate(value):
+                if not isinstance(elem, str) or not elem.strip():
+                    raise ValueError(
+                        f"manifest['nodes'][{i}][{list_key!r}][{j}] must be a non-empty string, "
+                        f"got {type(elem).__name__!r}"
+                    )
+                normalized_elems.append(elem.strip())
+            normalized_node[list_key] = normalized_elems
+        node_ref = normalized_node["ref"]
+        if node_ref in seen_refs:
+            raise ValueError(f"Duplicate ref {node_ref!r} in manifest['nodes']")
+        seen_refs.add(node_ref)
+        validated_nodes.append(normalized_node)
+
+    # Build node lookup and edges for topological sort
+    node_map: dict[str, dict[str, Any]] = {}
+    for node in validated_nodes:
+        node_map[node["ref"]] = node
+
+    # Determine topological order based on blocked_by relationships
+    edges: list[tuple[str, str]] = []
+    for node in validated_nodes:
+        for blocker_ref in node.get("blocked_by", []):
+            # blocker must be created before this node
+            edges.append((blocker_ref, node["ref"]))
+
+    # Also ensure parents are created before children
+    for node in validated_nodes:
+        parent_ref = node.get("parent_ref")
+        if parent_ref:
+            edges.append((parent_ref, node["ref"]))
+
+    if edges:
+        try:
+            sorted_refs = detect_cycles(edges)
+        except CycleDetectedError as exc:
+            raise ValueError(str(exc)) from exc
+        # Include any nodes not in the edge graph (isolated nodes)
+        sorted_refs_set = set(sorted_refs)
+        remaining = [r for r in node_map if r not in sorted_refs_set]
+        sorted_refs = sorted_refs + remaining
+    else:
+        sorted_refs = list(node_map.keys())
+
+    # In real execution, validate all cross-node references before any mutation.
+    if not dry_run:
+        for ref in sorted_refs:
+            if ref not in node_map:
+                continue
+            node = node_map[ref]
+            parent_ref = node.get("parent_ref")
+            if parent_ref and parent_ref not in node_map:
+                raise ValueError(f"parent_ref {parent_ref!r} for manifest ref {ref!r} could not be resolved")
+            for blocker_ref in node.get("blocked_by", []):
+                if blocker_ref not in node_map:
+                    raise ValueError(f"blocked_by ref {blocker_ref!r} for manifest ref {ref!r} could not be resolved")
+
+    # Phase 1: Generate create operations in topological order
+    descriptors: list[OperationDescriptor] = []
+    ref_bindings: dict[str, str] = {}  # manifest ref → provider identifier
+
+    for ref in sorted_refs:
+        if ref not in node_map:
+            continue
+        node = node_map[ref]
+        orch_key = generate_orchestration_key("create_issue", ref)
+        body = node.get("body", "")
+        if body is None:
+            body = ""
+        body_with_key = embed_orchestration_key(body, orch_key)
+
+        provider_params: dict[str, Any] = {
+            "title": node["title"],
+            "body": body_with_key,
+            "issue_type": node["issue_type"],
+        }
+        if node.get("parent_ref"):
+            provider_params["parent_ref"] = node["parent_ref"]
+        if node.get("labels"):
+            provider_params["labels"] = node["labels"]
+
+        if dry_run and not check_existing:
+            # Mode 1: planning-only dry-run — assemble descriptors only.
+            descriptors.append(
+                OperationDescriptor(
+                    operation_type="create_issue",
+                    orchestration_key=orch_key,
+                    refs=(ref,),
+                    status="dry-run",
+                    provider_params=provider_params,
+                )
+            )
+        elif dry_run and check_existing:
+            # Mode 2: dry-run with existence checks
+            assert query_provider is not None
+            existing = query_provider.find_existing_issue(orch_key)
+            if existing is not None:
+                ref_bindings[ref] = existing.identifier
+                descriptors.append(
+                    OperationDescriptor(
+                        operation_type="create_issue",
+                        orchestration_key=orch_key,
+                        refs=(ref,),
+                        status="existing",
+                        provider_params=provider_params,
+                        result=existing,
+                    )
+                )
+            else:
+                descriptors.append(
+                    OperationDescriptor(
+                        operation_type="create_issue",
+                        orchestration_key=orch_key,
+                        refs=(ref,),
+                        status="dry-run",
+                        provider_params=provider_params,
+                    )
+                )
+        else:
+            # Mode 3: real execution
+            parent_id: str | None = None
+            if node.get("parent_ref"):
+                parent_id = ref_bindings[node["parent_ref"]]
+
+            result = provider.create_issue(
+                title=node["title"],
+                body=body_with_key,
+                issue_type=node["issue_type"],
+                parent_id=parent_id,
+                labels=node.get("labels"),
+                idempotency_key=orch_key,
+                dry_run=False,
+            )
+            ref_bindings[ref] = result.identifier
+            descriptors.append(
+                OperationDescriptor(
+                    operation_type="create_issue",
+                    orchestration_key=orch_key,
+                    refs=(ref,),
+                    status=result.status,
+                    provider_params=provider_params,
+                    result=result,
+                )
+            )
+
+    # Phase 2: Generate link_subissue operations
+    for ref in sorted_refs:
+        if ref not in node_map:
+            continue
+        node = node_map[ref]
+        parent_ref = node.get("parent_ref")
+        if not parent_ref:
+            continue
+
+        orch_key = generate_orchestration_key("link_subissue", parent_ref, ref)
+        provider_params = {"parent_ref": parent_ref, "child_ref": ref}
+
+        if dry_run and not check_existing:
+            descriptors.append(
+                OperationDescriptor(
+                    operation_type="link_subissue",
+                    orchestration_key=orch_key,
+                    refs=(parent_ref, ref),
+                    status="dry-run",
+                    provider_params=provider_params,
+                )
+            )
+        elif dry_run and check_existing:
+            assert query_provider is not None
+            parent_id = ref_bindings.get(parent_ref)
+            child_id = ref_bindings.get(ref)
+            if parent_id and child_id:
+                link_existing = query_provider.find_existing_link(parent_id, child_id)
+                if link_existing is not None:
+                    descriptors.append(
+                        OperationDescriptor(
+                            operation_type="link_subissue",
+                            orchestration_key=orch_key,
+                            refs=(parent_ref, ref),
+                            status="already-linked",
+                            provider_params=provider_params,
+                            result=link_existing,
+                        )
+                    )
+                else:
+                    descriptors.append(
+                        OperationDescriptor(
+                            operation_type="link_subissue",
+                            orchestration_key=orch_key,
+                            refs=(parent_ref, ref),
+                            status="dry-run",
+                            provider_params=provider_params,
+                        )
+                    )
+            else:
+                descriptors.append(
+                    OperationDescriptor(
+                        operation_type="link_subissue",
+                        orchestration_key=orch_key,
+                        refs=(parent_ref, ref),
+                        status="dry-run",
+                        provider_params=provider_params,
+                    )
+                )
+        else:
+            # Real execution
+            parent_id = ref_bindings[parent_ref]
+            child_id = ref_bindings[ref]
+            link_result = provider.link_subissue(parent_id, child_id, dry_run=False)
+            descriptors.append(
+                OperationDescriptor(
+                    operation_type="link_subissue",
+                    orchestration_key=orch_key,
+                    refs=(parent_ref, ref),
+                    status=link_result.status,
+                    provider_params=provider_params,
+                    result=link_result,
+                )
+            )
+
+    # Phase 3: Generate add_blocked_by operations
+    for ref in sorted_refs:
+        if ref not in node_map:
+            continue
+        node = node_map[ref]
+        for blocker_ref in node.get("blocked_by", []):
+            orch_key = generate_orchestration_key("add_blocked_by", ref, blocker_ref)
+            provider_params = {"issue_ref": ref, "blocked_by_ref": blocker_ref}
+
+            if dry_run and not check_existing:
+                descriptors.append(
+                    OperationDescriptor(
+                        operation_type="add_blocked_by",
+                        orchestration_key=orch_key,
+                        refs=(ref, blocker_ref),
+                        status="dry-run",
+                        provider_params=provider_params,
+                    )
+                )
+            elif dry_run and check_existing:
+                assert query_provider is not None
+                issue_id = ref_bindings.get(ref)
+                blocker_id = ref_bindings.get(blocker_ref)
+                if issue_id and blocker_id:
+                    dep_existing = query_provider.find_existing_dependency(issue_id, blocker_id)
+                    if dep_existing is not None:
+                        descriptors.append(
+                            OperationDescriptor(
+                                operation_type="add_blocked_by",
+                                orchestration_key=orch_key,
+                                refs=(ref, blocker_ref),
+                                status="already-linked",
+                                provider_params=provider_params,
+                                result=dep_existing,
+                            )
+                        )
+                    else:
+                        descriptors.append(
+                            OperationDescriptor(
+                                operation_type="add_blocked_by",
+                                orchestration_key=orch_key,
+                                refs=(ref, blocker_ref),
+                                status="dry-run",
+                                provider_params=provider_params,
+                            )
+                        )
+                else:
+                    descriptors.append(
+                        OperationDescriptor(
+                            operation_type="add_blocked_by",
+                            orchestration_key=orch_key,
+                            refs=(ref, blocker_ref),
+                            status="dry-run",
+                            provider_params=provider_params,
+                        )
+                    )
+            else:
+                # Real execution
+                issue_id = ref_bindings[ref]
+                blocker_id = ref_bindings[blocker_ref]
+                dep_result = provider.add_blocked_by(issue_id, blocker_id, dry_run=False)
+                descriptors.append(
+                    OperationDescriptor(
+                        operation_type="add_blocked_by",
+                        orchestration_key=orch_key,
+                        refs=(ref, blocker_ref),
+                        status=dep_result.status,
+                        provider_params=provider_params,
+                        result=dep_result,
+                    )
+                )
+
+    return OperationPlan(
+        operations=tuple(descriptors),
+        dry_run=dry_run,
+        check_existing=check_existing,
+    )
+
+
+def execute_manifest(
+    manifest: dict[str, Any],
+    provider: IssueProvider,
+) -> OperationPlan:
+    """Execute a manifest against a provider (real mutations).
+
+    Convenience wrapper for ``plan_manifest(dry_run=False)``.
+
+    Args:
+        manifest: JSON manifest with nodes and edges.
+        provider: IssueProvider for real execution.
+
+    Returns:
+        OperationPlan with results from the executed operations.
+    """
+    return plan_manifest(manifest, provider, dry_run=False)

{agentic_devtools-0.2.332.dist-info → agentic_devtools-0.2.333.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.332
+Version: 0.2.333
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT

{agentic_devtools-0.2.332.dist-info → agentic_devtools-0.2.333.dist-info}/RECORD

@@ -1,5 +1,5 @@
 agentic_devtools/__init__.py,sha256=J_Zw_vWKghk-cLmqI83hXQmSiS8zMhGIHM5WPLDkZuo,242
-agentic_devtools/_version.py,sha256=W05wKAPL9NTr_eL2ykSOaNckhAZGNqg5k74bBouriC0,524
+agentic_devtools/_version.py,sha256=4iHxOBCshxxKQXkmD0BI3AmeulSZMr_G5ZVpaxUKYT0,524
 agentic_devtools/agdt_gitignore.py,sha256=aBPBQe7M0GLH8NIp1NsyN9ZiO80fNGOi46IcT5A4SK4,1569
 agentic_devtools/background_tasks.py,sha256=IVC1XJKQzPBP8wCRNCZX_iZCg9FJY_GBUzddSJj7xqw,17473
 agentic_devtools/config.py,sha256=DEVxTVZhsQbVQwO9qdB_1h19aBpjMzF6xJY_ePYLGLs,15629
@@ -15,7 +15,7 @@ agentic_devtools/_bundled_skills/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRk
 agentic_devtools/_bundled_skills/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agentic_devtools/_bundled_skills/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agentic_devtools/_bundled_skills/workflow-analysis/SKILL.md,sha256=imOFULtiGqsFEljGx0ly7_ntnZAmLWuYAF0HL82MIVA,21153
-agentic_devtools/adapters/__init__.py,sha256=PDsuodDPaGL6wPcaW3lKQNfRmW10A9Gw8J1avTit1w4,7774
+agentic_devtools/adapters/__init__.py,sha256=BVj0rIs6WIPee2_hxm2yj-WSdNi-PfrHFw33GK2yJho,8161
 agentic_devtools/adapters/base.py,sha256=7UIx89av0QOO01eqOFx9hQZC4HNhUPNe1myFBmL0NgY,6104
 agentic_devtools/adapters/copilot-instructions.md,sha256=xkz-aVd7cc2v_tPN9CzV67O0GbKZNmkmHXSwN_ULK_8,29223
 agentic_devtools/adapters/cycle_detection.py,sha256=93y3Yb1v2ungYeTJKxL8ztQltm8OFvsnLP67ZFVmoAQ,2350
@@ -25,12 +25,15 @@ agentic_devtools/adapters/factory.py,sha256=Z32q3wcZ196jWRlRcphRRDBqYMbTCRlz13EU
 agentic_devtools/adapters/github_adapter.py,sha256=ltdJveOCHs95zzJMERDZp9T66FCYgvRR6slzKBBkJxY,22324
 agentic_devtools/adapters/github_provider.py,sha256=6hvoaOFP-uOZQKGl2_XU8o9uR5xUzAWFFMHul3aKZuw,19992
 agentic_devtools/adapters/github_schema.py,sha256=V793iZqst3Dj_piX6CkSbn379nvItECs7PattF95WqU,6869
-agentic_devtools/adapters/issue_provider.py,sha256=rEGApNOP2F_rpZCindBQcJpTDU5p64TLNRBA6RsfacI,26205
+agentic_devtools/adapters/idempotency_query_provider.py,sha256=vJ9hi2bKQIQsIxhnIqFWXKV38DmS9W3T1pVRtIZ908A,2135
+agentic_devtools/adapters/issue_provider.py,sha256=E4QNTtKC2JGZEax9cF5bCVa-FybTN0FbWlMrGzgkyt0,28775
 agentic_devtools/adapters/issue_type_mapping.py,sha256=-Mh4fmr6Zd10CEGkDaFHVYiOJHUXFIWItAec5jmKu5c,14193
 agentic_devtools/adapters/jira_adapter.py,sha256=Fhkdm6YaTNW6wVKf1KSXlrT18XL-qRezBD1j9TMt03k,22525
-agentic_devtools/adapters/jira_provider.py,sha256=JIzU7IqStsUI50FvDGn2HpAHnLQ4YDwklY93e-Lx5kw,34234
+agentic_devtools/adapters/jira_provider.py,sha256=mC-oP9-06B2xCczOXrzLbJRvk0HRzgYak7ZgYpK9wb8,37204
 agentic_devtools/adapters/markdown_adapter.py,sha256=ej6Je7yGtj8igtHiiG_7ZbTedGyN0G1HLloLuQoWGkM,25942
-agentic_devtools/adapters/orchestration_key.py,sha256=KmBQX3g6Fa9jbVrOr9IKT9Bj_K4wj3GBpoJRAO0qq30,2684
+agentic_devtools/adapters/operation_plan.py,sha256=Lp46YSI3hz9UeZ253tlCzDufDZr9x4Jgk4LGwRq57Xc,4315
+agentic_devtools/adapters/orchestration_key.py,sha256=-v2lM1HGSa6IIeeLy6vDZzxeeAN7O0ETkycuvLWRwIA,4059
+agentic_devtools/adapters/plan_manifest.py,sha256=QozGmmQCFH5Z7HDYx3eMeI21M3PMuM_DW2qWFnQeCv0,18831
 agentic_devtools/adapters/retry.py,sha256=CsueXIs-sLgkCVgp_hspzNnQKi_Ty-FyVN-066WncRc,3736
 agentic_devtools/adapters/types.py,sha256=gqN2fq0i0gtMzCY1dCweZRlq3taAQNQEEHdqak5pbjI,8853
 agentic_devtools/cli/__init__.py,sha256=VgHQrGk0NuMaGMdvooFwz3nGY1NzVi6kX5Fr7wF-Tdw,40
@@ -889,8 +892,8 @@ agentic_devtools/_bundled_skills/prompts/speckit.plan.prompt.md,sha256=IJja5r2Sd
 agentic_devtools/_bundled_skills/prompts/speckit.specify.prompt.md,sha256=eyzE3GRi2hyW30a6xPYOU7q6MJf0skrD-baEGURYqpg,31
 agentic_devtools/_bundled_skills/prompts/speckit.tasks.prompt.md,sha256=iPxXwon5nV6dNcJV8-JoP3PssKUVXctNiG-C9SsRhB8,29
 agentic_devtools/_bundled_skills/prompts/speckit.taskstoissues.prompt.md,sha256=L5Y21PMSoUcPAAdHy2Jnf-wGVdi04jV_pPvyOJZfpm0,37
-agentic_devtools-0.2.332.dist-info/METADATA,sha256=2BJ-K1TYEWIAepVS_EtES8e15vcoX5DWhAWiTDoQOKU,29796
-agentic_devtools-0.2.332.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-agentic_devtools-0.2.332.dist-info/entry_points.txt,sha256=Xs0VhRkREzs61FdX63Ed1qa1-WDeBppn7BvMdRIYYZ4,11395
-agentic_devtools-0.2.332.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
-agentic_devtools-0.2.332.dist-info/RECORD,,
+agentic_devtools-0.2.333.dist-info/METADATA,sha256=67rnAlB09DjBFo7jRBoAQkswMf2MhNe58ciIOZephbM,29796
+agentic_devtools-0.2.333.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agentic_devtools-0.2.333.dist-info/entry_points.txt,sha256=Xs0VhRkREzs61FdX63Ed1qa1-WDeBppn7BvMdRIYYZ4,11395
+agentic_devtools-0.2.333.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
+agentic_devtools-0.2.333.dist-info/RECORD,,