agentic-devtools 0.2.332__py3-none-any.whl → 0.2.334__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.334'
+__version_tuple__ = version_tuple = (0, 2, 334)
 
 __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()