agentic-devtools 0.2.213__tar.gz → 0.2.214__tar.gz

{agentic_devtools-0.2.213 → agentic_devtools-0.2.214}/.gitignore

@@ -126,6 +126,9 @@ specs/*/contracts/*
 !specs/2101-define-epic-tree-json/research.md
 !specs/2101-define-epic-tree-json/data-model.md
 !specs/2101-define-epic-tree-json/quickstart.md
+!specs/1856-implement-github-sub-issues/research.md
+!specs/1856-implement-github-sub-issues/data-model.md
+!specs/1856-implement-github-sub-issues/quickstart.md
 specs/*/checklists/.generation-prompt-*.md
 .specify/memory/agent-file.md
 .markdownlint-debug.log

{agentic_devtools-0.2.213 → agentic_devtools-0.2.214}/PKG-INFO

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

{agentic_devtools-0.2.213 → agentic_devtools-0.2.214}/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.213'
-__version_tuple__ = version_tuple = (0, 2, 213)
+__version__ = version = '0.2.214'
+__version_tuple__ = version_tuple = (0, 2, 214)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.213 → agentic_devtools-0.2.214}/agentic_devtools/cli/azure_devops/file_review_commands.py

@@ -29,6 +29,7 @@ from .helpers import (
 )
 from .mark_reviewed import fetch_reviewer_context, mark_file_reviewed, set_batch_context
 from .marker import build_marker
+from .review_state import REVIEW_STATE_FILENAME, REVIEW_STATE_SUBDIR
 
 if TYPE_CHECKING:
     from .review_state import ReviewState
@@ -130,16 +131,24 @@ def _get_queue_path(pull_request_id: int) -> Path:
 
     Returns the new commit-hash-scoped path
     (``pull-request-review/<dir_name>/queue.json``).  If that file does not yet
-    exist, two backward-compatible fallbacks are tried in order:
+    exist, three backward-compatible / self-healing fallbacks are tried in order:
 
     1. **8-char hash directory** – prior versions used ``commit_hash_short[:8]``
        instead of the current 12-char truncation.  If ``commit_hash_short`` is at
        least 8 characters long, the 8-char prefix directory is checked.
-    2. **Legacy path** – ``pull-request-review/prompts/<pr_id>/queue.json`` from
+    2. **review-state.json recovery** – ``review.commit_hash_short`` can be lost
+       mid-review when a concurrent state write overwrites ``state.json`` and
+       drops the ``review`` namespace.  ``review-state.json`` is a separate file
+       that retains the canonical full ``commitHash``; its first 12 characters
+       are the artifact directory name.  This lets queue resolution self-heal
+       instead of pointing at a non-existent ``PR<id>`` directory (which would
+       make the queue look empty and the review look complete).
+    3. **Legacy path** – ``pull-request-review/prompts/<pr_id>/queue.json`` from
        the original pre-commit-hash layout.
 
-    This ensures in-progress reviews started under either older scheme continue to
-    work transparently after an upgrade.
+    This ensures in-progress reviews started under either older scheme — or
+    whose ``review.commit_hash_short`` state key was lost — continue to work
+    transparently.
     """
     commit_hash_short = get_value("review.commit_hash_short")
     # Suppress warnings here: this function is called many times per review command.
@@ -156,13 +165,70 @@ def _get_queue_path(pull_request_id: int) -> Path:
                 short8_path = state_dir / "pull-request-review" / short8_dir_name / "queue.json"
                 if short8_path.exists():
                     return short8_path
-        # Fallback 2: legacy pre-commit-hash path.
+        # Fallback 2: recover the commit-hash dir from review-state.json's canonical
+        # commitHash when review.commit_hash_short was lost from state mid-review.
+        recovered_path = _recover_queue_path_from_review_state(state_dir, pull_request_id)
+        if recovered_path is not None:
+            return recovered_path
+        # Fallback 3: legacy pre-commit-hash path.
         legacy_path = state_dir / "pull-request-review" / "prompts" / str(pull_request_id) / "queue.json"
         if legacy_path.exists():
             return legacy_path
     return new_path
 
 
+def _recover_queue_path_from_review_state(state_dir: Path, pull_request_id: int) -> Path | None:
+    """Recover the commit-hash-scoped queue path from ``review-state.json``.
+
+    The ``review.commit_hash_short`` state key can be dropped mid-review when a
+    concurrent ``state.json`` write overwrites the file and removes the
+    ``review`` namespace.  ``review-state.json`` is a separate file that retains
+    the canonical full ``commitHash``; its first 12 characters are the artifact
+    directory name used to scope ``queue.json``.
+
+    The ``prId`` field in ``review-state.json`` is validated against
+    ``pull_request_id`` before using ``commitHash``, so a stale
+    ``review-state.json`` left over from a previous review of a different PR
+    in the same worktree cannot accidentally return the wrong queue.
+
+    Args:
+        state_dir: The resolved workflow state directory (same one used to build
+            the primary queue path), so recovery reads the review state that
+            belongs to this exact worktree scope.
+        pull_request_id: The PR being queried.  Must match the ``prId`` field
+            in ``review-state.json`` for recovery to proceed.
+
+    Returns:
+        The recovered ``queue.json`` ``Path`` when ``review-state.json`` yields a
+        valid ``prId`` match, a safe commit-hash directory whose ``queue.json``
+        exists, else ``None``.
+    """
+    review_state_path = state_dir / REVIEW_STATE_SUBDIR / REVIEW_STATE_FILENAME
+    try:
+        if not review_state_path.exists():
+            return None
+        with open(review_state_path, encoding="utf-8") as fh:
+            review_state = json.load(fh)
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if not isinstance(review_state, dict):
+        return None
+    pr_id = review_state.get("prId")
+    if not isinstance(pr_id, int) or pr_id != pull_request_id:
+        return None
+    commit_hash = review_state.get("commitHash")
+    if not isinstance(commit_hash, str):
+        return None
+    stripped = commit_hash.strip()
+    if len(stripped) < 12:
+        return None
+    dir_name = stripped[:12]
+    if not is_safe_dir_segment(dir_name):
+        return None
+    recovered = state_dir / "pull-request-review" / dir_name / "queue.json"
+    return recovered if recovered.exists() else None
+
+
 def trigger_in_progress_for_file(
     pull_request_id: int,
     file_path: str,

agentic_devtools-0.2.214/specs/1856-implement-github-sub-issues/data-model.md

@@ -0,0 +1,124 @@
+# Data Model: GitHub Sub-Issues Hierarchy Detector
+
+## Overview
+
+This document describes the data structures used by the `GitHubHierarchyDetector` implementation.
+The types below are defined in `agentic_devtools/cli/speckit/hierarchy.py` (issue #1855) and
+serve as the stable contract between the detector and its downstream consumers.
+
+---
+
+## Core Types
+
+### `HierarchyLevel`
+
+An enumeration classifying where an issue sits in the three-level hierarchy.
+
+```python
+class HierarchyLevel(Enum):
+    EPIC    = "epic"     # Has children, at least one child has its own children
+    FEATURE = "feature"  # Has children (all leaves), or no children but direct child of an EPIC
+    TASK    = "task"     # No children; standalone or nested at depth ≥ 2
+```
+
+**Classification rules** (applied by `get_level()`):
+
+Primary signal — children-based (evaluated first):
+
+| Has children? | Any child has children? | Level     |
+|---------------|-------------------------|-----------|
+| Yes           | Yes (≥ 1)               | `EPIC`    |
+| Yes           | No                      | `FEATURE` |
+
+Secondary signal — depth-based (applies when the issue has **no children**):
+
+| Has parent? | Depth from root               | Level     |
+|-------------|-------------------------------|-----------|
+| No          | — (standalone)                | `TASK`    |
+| Yes         | 1 (direct child of an EPIC)   | `FEATURE` |
+| Yes         | ≥ 2                           | `TASK`    |
+
+---
+
+### `ChildEntry`
+
+Represents a single direct child of an issue as returned by `get_children()`.
+
+```python
+@dataclass
+class ChildEntry:
+    key:   str  # Issue number as string (e.g. "42"), or qualified ref for cross-repo children (e.g. "owner/repo#42")
+    title: str  # Issue title from GitHub
+    order: int  # Advisory ordering integer from the GitHub sub_issues REST API; derived from list-index in the GraphQL fallback path
+```
+
+Children are returned in creation order (GitHub's default ordering).
+When the GraphQL fallback path is used, `order` is set to the node's 0-based index
+in the returned list to preserve deterministic ordering.
+
+---
+
+### `HierarchyNode`
+
+The root output type returned by `detect_hierarchy()` and `build_hierarchy_tree()`.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class HierarchyNode:
+    title:        str
+    level:        HierarchyLevel
+    parent:       str | None = None    # Parent issue key, e.g. "10", or None
+    children:     list[ChildEntry] = field(default_factory=list)
+    processed_at: datetime | None = None  # UTC timestamp of detection (None if unprocessed)
+```
+
+---
+
+### `HierarchyValidationError`
+
+Raised when hierarchy YAML or issue-derived hierarchy data is invalid, or when the hierarchy
+cannot be determined from available metadata. The current exception docstring covers YAML
+validation, while the `HierarchyDetector.detect_hierarchy` protocol contract also uses this type
+for metadata-based detection failures.
+
+```python
+class HierarchyValidationError(ValueError):
+    ...
+```
+
+---
+
+## Module-Level Public Symbols
+
+| Symbol | Module | Description |
+|--------|--------|-------------|
+| `GitHubHierarchyDetector` | `agentic_devtools.cli.speckit.hierarchy_detector` | Concrete `HierarchyDetector` implementation |
+| `parse_issue_reference` | `agentic_devtools.cli.speckit.hierarchy_detector` | Parses an issue key string into `(owner, repo, number)` |
+| `HierarchyLevel` | `agentic_devtools.cli.speckit.hierarchy` | Enum: `EPIC`, `FEATURE`, `TASK` |
+| `HierarchyNode` | `agentic_devtools.cli.speckit.hierarchy` | Output node returned by the detector |
+| `ChildEntry` | `agentic_devtools.cli.speckit.hierarchy` | Single child entry in a `HierarchyNode` |
+| `HierarchyValidationError` | `agentic_devtools.cli.speckit.hierarchy` | Validation error type also reused when hierarchy detection cannot determine a valid result |
+| `HierarchyDetector` | `agentic_devtools.cli.speckit.hierarchy` | Protocol (runtime-checkable) that `GitHubHierarchyDetector` satisfies |
+
+---
+
+## Serialization
+
+`HierarchyNode` supports YAML round-trip serialization via PyYAML (already a project
+dependency). This is used when persisting detected hierarchy data to disk for downstream
+pipeline steps.
+
+---
+
+## Issue Reference Formats
+
+`parse_issue_reference(issue_key, default_owner, default_repo)` accepts:
+
+| Format | Example | Resolution |
+|--------|---------|------------|
+| Bare number | `"42"` | `(default_owner, default_repo, 42)` |
+| Hash-prefixed number | `"#42"` | `(default_owner, default_repo, 42)` |
+| Qualified reference | `"owner/repo#42"` | `("owner", "repo", 42)` |
+| Invalid | `"not-a-number"` | `ValueError` |

agentic_devtools-0.2.214/specs/1856-implement-github-sub-issues/plan.md

@@ -0,0 +1,396 @@
+# Implementation Plan: GitHub Sub-Issues Hierarchy Detector
+
+## Phase Artifacts in Scope
+
+This Phase 3 plan includes the following artifacts:
+
+- `spec.md` — Clarified feature specification
+- `plan.md` — This implementation plan
+- `checklists/requirements.md` — Requirements checklist
+- `data-model.md` — Data structure reference for `HierarchyNode`, `ChildEntry`, `HierarchyLevel`
+- `quickstart.md` — Usage guide for `GitHubHierarchyDetector`
+- `research.md` — GitHub sub-issues API research notes
+
+## 1. Technical Context
+
+### Technology Stack
+
+- **Language**: Python 3.10+ (match existing `from __future__ import annotations` pattern)
+- **CLI execution**: `gh` CLI via `run_safe()` from `agentic_devtools/cli/subprocess_utils.py`
+- **Data models**: Existing `HierarchyNode`, `ChildEntry`, `HierarchyLevel`, `HierarchyValidationError`
+  from `agentic_devtools/cli/speckit/hierarchy.py`
+- **Protocol**: `HierarchyDetector` protocol (runtime-checkable) from same module
+- **Serialization**: PyYAML (already a project dependency)
+- **Test framework**: pytest with 100% branch coverage enforcement
+
+### Key Dependencies
+
+| Dependency | Source | Purpose |
+|---|---|---|
+| `HierarchyDetector` protocol | `hierarchy.py` (#1855) | Contract to implement |
+| `HierarchyNode`, `ChildEntry`, `HierarchyLevel` | `hierarchy.py` (#1855) | Output data structures |
+| `HierarchyValidationError` | `hierarchy.py` (#1855) | Error type for API/validation failures |
+| `run_safe()` | `subprocess_utils.py` | Safe subprocess execution with `shell=False` |
+| `gh` CLI | System binary | GitHub API authentication and execution |
+
+### Architecture Decisions
+
+- **Single module**: `hierarchy_detector.py` in `agentic_devtools/cli/speckit/` — no subpackage
+- **No new dependencies**: stdlib + `gh` CLI + existing project packages only
+- **`gh api` as transport**: All GitHub API calls go through `run_safe(["gh", "api", ...], shell=False)`
+- **REST-first, GraphQL-fallback**: REST for sub-issue enumeration; GraphQL for parent detection
+  and batched leaf-status checks
+- **Deterministic constructor**: `owner` and `repo` are required parameters — no git-remote inference
+
+## 2. Research Summary
+
+See [spec.md](spec.md) (clarifications section) for detailed decisions. Key choices:
+
+1. **REST for children, GraphQL for parent + leaf-status** — REST `sub_issues` endpoint is simpler
+   for enumeration; GraphQL is required for parent detection and efficient batched leaf-status queries
+2. **Pagination via `gh api --paginate`** — consistent with the existing `_gh_api(..., paginate=True)` + `_parse_paginated_json` pattern
+3. **Paginated JSON parsing inline** — `_parse_paginated_json`-style logic adapted locally in
+  `hierarchy_detector.py`; importing the private helper from `agentic_devtools/cli/ci/github_provider.py`
+  is intentionally avoided to prevent a brittle cross-package dependency on a private symbol
+4. **Rate-limit tracking via response headers** — parsed from `gh api --include` output
+5. **Cycle detection via visited set** — simple `set[str]` accumulator passed through traversal
+
+## 3. Design Overview
+
+### Class Diagram
+
+```text
+┌─────────────────────────────────┐
+│   HierarchyDetector (Protocol)  │
+│  ───────────────────────────    │
+│  detect_hierarchy(issue_key)    │
+│    → HierarchyNode              │
+└──────────────┬──────────────────┘
+               │ implements
+┌──────────────▼──────────────────┐
+│   GitHubHierarchyDetector       │
+│  ───────────────────────────    │
+│  owner: str                     │
+│  repo: str                      │
+│  rate_limit_threshold: int = 10 │
+│  ───────────────────────────    │
+│  detect_hierarchy(issue_key)    │
+│  get_children(owner, repo, num) │
+│  get_parent(owner, repo, num)   │
+│  get_level(owner, repo, num)    │
+│  build_hierarchy_tree(o, r, n)  │
+└─────────────────────────────────┘
+```
+
+### Request Flow
+
+```text
+detect_hierarchy("42")
+  ├─ parse_issue_reference("42", default_owner=owner, default_repo=repo) → (owner, repo, 42)
+  └─ build_hierarchy_tree(owner, repo, 42)
+       ├─ _fetch_issue_title(owner, repo, 42)     [REST]
+       ├─ get_parent(owner, repo, 42)              [GraphQL]
+       ├─ get_children(owner, repo, 42)            [REST → GraphQL fallback]
+       └─ get_level(owner, repo, 42)
+            └─ _batch_check_children_have_children  [GraphQL batched]
+```
+
+### Module-Level Public Symbols
+
+| Symbol | Type | Test File |
+|---|---|---|
+| `GitHubHierarchyDetector` | class | `test_githubhierarchydetector.py` |
+| `parse_issue_reference` | function | `test_parse_issue_reference.py` |
+
+## 4. Implementation Phases
+
+### Phase 1: Module Skeleton & Issue Reference Parsing (Est: 1 hour)
+
+**Deliverables:**
+
+- Create `agentic_devtools/cli/speckit/hierarchy_detector.py` with imports, `__all__`, and class stub
+- Implement `parse_issue_reference(issue_key: str, default_owner: str, default_repo: str) → tuple[str, str, int]`
+  - `default_owner` and `default_repo` are explicit required parameters (callers pass
+    `self.owner` / `self.repo` from the detector instance — no ambient state)
+  - Bare number `"42"` → `(default_owner, default_repo, 42)`
+  - Qualified `"owner/repo#42"` → `("owner", "repo", 42)`
+  - `"#42"` → `(default_owner, default_repo, 42)`
+  - Invalid formats → `ValueError`
+- Create test directory structure with `__init__.py` files
+- Write `test_parse_issue_reference.py` (TDD: write tests first)
+
+**Files created:**
+
+- `agentic_devtools/cli/speckit/hierarchy_detector.py`
+- `tests/unit/cli/speckit/hierarchy_detector/__init__.py`
+- `tests/unit/cli/speckit/hierarchy_detector/test_parse_issue_reference.py`
+
+**Verification:**
+
+```bash
+agdt-test-pattern tests/unit/cli/speckit/hierarchy_detector/test_parse_issue_reference.py -v
+```
+
+---
+
+### Phase 2: REST API — `get_children()` (Est: 2 hours)
+
+**Deliverables:**
+
+- Implement `get_children(owner, repo, issue_number) → list[ChildEntry]`
+- REST call handled via `_run_gh_rest` (see helpers below), which internally runs
+  `gh api ... --include --paginate` and splits the repeated header/body blocks so that
+  rate-limit headers from the final page are available alongside the merged JSON bodies
+- Parse paginated JSON using locally adapted `_parse_paginated_json`-style logic inside
+  `hierarchy_detector.py` (do not import the private CI helper)
+- Map each same-repo item to `ChildEntry(key=str(number), title=title, order=order_value)`,
+  where `order_value` is resolved with explicit `is not None` checks so that a legitimate
+  value of `0` is preserved, and the child's list index is used as the final fallback so
+  ordering remains deterministic when GitHub omits both ordering fields:
+
+  ```python
+  for idx, item in enumerate(raw_items):
+      av = item.get("advisory_order")
+      pv = item.get("position")
+      order_value = av if av is not None else (pv if pv is not None else idx)
+  ```
+
+  (the field name varies across GitHub API versions)
+- Map cross-repo children to `ChildEntry(key=f"{child_owner}/{child_repo}#{number}", title=title, order=order_value)`
+  to preserve repo context as an opaque reference (not traversed)
+- Handle empty results (no sub-issues → empty list)
+- Handle pagination (multiple pages merged)
+
+**Internal helpers created:**
+
+- `_run_gh_rest(endpoint, owner, repo) → tuple[Any, dict[str, str]]` — executes `gh api` with
+  `--include` (and `--paginate` when needed), splits repeated header/body blocks, concatenates
+  only the JSON bodies before parsing, and returns the final page's headers for rate-limit tracking.
+  The first element may be a `list` (e.g. for paginated sub-issues endpoints) or a `dict`, hence `Any`.
+- `_parse_rate_limit_headers(headers) → tuple[int, float]` — extracts remaining + reset timestamp
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_get_children_returns_entries`
+- `test_get_children_empty`
+- `test_get_children_pagination`
+- `test_get_children_api_error_fallback_to_graphql`
+
+**Verification:**
+
+```bash
+agdt-test-pattern tests/unit/cli/speckit/hierarchy_detector/test_githubhierarchydetector.py -v
+```
+
+---
+
+### Phase 3: GraphQL API — `get_parent()` + GraphQL Fallback for Children (Est: 2 hours)
+
+**Deliverables:**
+
+- Implement `get_parent(owner, repo, issue_number) → int | None` (raw integer parent issue number,
+  matching the issue #1856 requirement; `HierarchyNode.__post_init__` normalizes `int` to `str`
+  when constructing the node)
+- GraphQL query for parent:
+
+  ```graphql
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        parent { number }
+      }
+    }
+  }
+  ```
+
+- Implement GraphQL fallback path for `get_children()` when REST fails
+- GraphQL children query uses `subIssues(first: 50) { nodes { number title } }`
+  — this query returns no ordering metadata; `ChildEntry.order` is derived from the
+  node's index in the returned list (0-based) so downstream consumers always get
+  deterministic ordering even in the fallback path
+
+**Internal helpers created:**
+
+- `_run_gh_graphql(query, variables) → tuple[dict, dict[str, str]]` — executes `gh api graphql`
+  with `--field` args and `--include` so response headers are captured alongside the JSON body;
+  returns `(parsed_json, headers)` so callers can update rate-limit state from GraphQL responses
+  the same way `_run_gh_rest` does for REST calls
+- `_get_children_graphql(owner, repo, issue_number) → list[ChildEntry]` — fallback path
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_get_parent_returns_key`
+- `test_get_parent_no_parent`
+- `test_get_parent_api_error`
+- `test_get_children_graphql_fallback`
+
+---
+
+### Phase 4: Level Classification — `get_level()` (Est: 2 hours)
+
+**Deliverables:**
+
+- Implement `get_level(owner, repo, issue_number) → HierarchyLevel`
+- Batched GraphQL query for leaf-status of all children (dynamically constructed with
+  aliased fields per child):
+
+  ```graphql
+  query($owner: String!, $repo: String!) {
+    repository(owner: $owner, name: $repo) {
+      issue_101: issue(number: 101) { subIssues(first: 1) { totalCount } }
+      issue_102: issue(number: 102) { subIssues(first: 1) { totalCount } }
+    }
+  }
+  ```
+
+- Classification rules (primary signal — children-based, takes precedence):
+  - Children, at least one has children → `EPIC`
+  - Children, none have children → `FEATURE`
+  - Batched query failure → `FEATURE` (conservative) + warning to stderr
+- Classification rules (secondary signal — depth-based, applies when issue has no children):
+  - No children, parent at depth 1 from root (direct child of an EPIC) → `FEATURE`
+  - No children, parent at depth ≥ 2 → `TASK`
+  - No children, no parent (standalone) → `TASK`
+
+**Internal helpers created:**
+
+- `_batch_check_children_have_children(owner, repo, child_numbers) → dict[int, bool]` —
+  returns `{issue_number: has_children}` for each child
+- `_build_batch_subissues_query(child_numbers) → str` — constructs the aliased GraphQL query
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_get_level_epic`
+- `test_get_level_feature`
+- `test_get_level_feature_via_depth` (no children, parent at depth 1 → FEATURE)
+- `test_get_level_task`
+- `test_get_level_standalone_task`
+- `test_get_level_batch_query_failure_fallback`
+
+---
+
+### Phase 5: `build_hierarchy_tree()` + `detect_hierarchy()` (Est: 1.5 hours)
+
+**Deliverables:**
+
+- Implement `build_hierarchy_tree(owner, repo, issue_number) → HierarchyNode`
+  - Fetch issue title via REST: `gh api repos/{owner}/{repo}/issues/{issue_number}`
+  - Call `get_parent()`, `get_children()`, `get_level()`
+  - Construct `HierarchyNode(title, level, parent, children, processed_at=now_utc)`
+- Implement `detect_hierarchy(issue_key) → HierarchyNode`
+  - Parse issue key via `parse_issue_reference()`
+  - For bare numbers, use constructor-provided `owner`/`repo`
+  - Delegate to `build_hierarchy_tree()`
+- Verify `isinstance(detector, HierarchyDetector)` passes
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_build_hierarchy_tree_full`
+- `test_build_hierarchy_tree_yaml_roundtrip`
+- `test_detect_hierarchy_bare_number`
+- `test_detect_hierarchy_qualified_reference`
+- `test_detect_hierarchy_protocol_compliance`
+
+---
+
+### Phase 6: Error Handling & Resilience (Est: 2 hours)
+
+**Deliverables:**
+
+- Exponential backoff with retry (1s → 2s → 4s → 8s → 16s, max 5 retries)
+- REST-to-GraphQL fallback on non-2xx REST responses **excluding 404** (404 fails fast — no GraphQL retry)
+- `HierarchyValidationError` for:
+  - HTTP 404 (issue not found — fails fast, does **not** fall back to GraphQL)
+  - Both APIs failing (includes status codes + issue identifier)
+  - Circular references detected
+  - Malformed/unexpected JSON responses
+- Cycle detection: `visited: set[str]` parameter in internal traversal methods
+- Depth capping: 4th-level issues classified as TASK with stderr warning
+- Cross-repo child references: logged as warning, kept as opaque child references (not traversed further)
+- Deleted/transferred issues: skip + warning
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_exponential_backoff`
+- `test_rest_to_graphql_fallback`
+- `test_404_raises_validation_error`
+- `test_both_apis_fail`
+- `test_circular_reference_detection`
+- `test_depth_cap_at_three_levels`
+- `test_cross_repo_child_warning`
+- `test_malformed_json_response`
+
+---
+
+### Phase 7: Rate-Limit Awareness (Est: 1.5 hours)
+
+**Deliverables:**
+
+- Track `X-RateLimit-Remaining` and `X-RateLimit-Reset` from `gh api --include` output
+- Internal `_rate_limit_remaining: int` and `_rate_limit_reset: float` instance state
+- Before each request: check `_rate_limit_remaining < self.rate_limit_threshold`
+- If below threshold: `time.sleep(max(1, min(reset_time - now, 120)))`
+- Thread-safe: not required (single-threaded CLI)
+
+**Test file additions in `test_githubhierarchydetector.py`:**
+
+- `test_rate_limit_pause_when_below_threshold`
+- `test_rate_limit_pause_duration_bounds`
+- `test_rate_limit_no_pause_above_threshold`
+- `test_rate_limit_custom_threshold`
+
+---
+
+### Phase 8: Integration & Final Validation (Est: 1 hour)
+
+**Deliverables:**
+
+- Keep `GitHubHierarchyDetector` and `parse_issue_reference` imported from
+  `agentic_devtools.cli.speckit.hierarchy_detector`; do not widen
+  `agentic_devtools/cli/speckit/__init__.py` beyond Speckit CLI entry-point exports
+- Run full test suite: `agdt-test && agdt-task-wait`
+- Run targeted checks: `bash scripts/targeted-checks.sh`
+- Verify test structure: `python scripts/validate_test_structure.py`
+- Verify 100% branch coverage for the new module (1:1:1 tests live under
+  `tests/unit/cli/speckit/hierarchy_detector/`, so `agdt-test-file` cannot be used here):
+
+  ```bash
+  agdt-test-pattern tests/unit/cli/speckit/hierarchy_detector/ -v
+  bash scripts/targeted-checks.sh   # enforces per-file 100% branch coverage on changed files
+  ```
+
+## 5. Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| GitHub sub-issues REST endpoint not available / beta | Medium | High | GraphQL fallback is always available; REST is tried first but not required |
+| `gh api --include` header parsing differs across `gh` versions | Low | Medium | Parse headers defensively; fall back to no rate-limit tracking if headers missing |
+| Batched GraphQL query hits node limit for issues with many children | Low | Medium | Cap batch to 50 children (matching `first: 50` limit); split into multiple queries if needed |
+| `HierarchyDetector` protocol changes in #1855 before merge | Low | High | Protocol is already merged and stable; pin to current interface |
+| Local `_parse_paginated_json`-style helper drift | Low | Low | Keep the adapted parser local and minimal; if broader reuse is needed later, promote a public shared helper in a separate change |
+
+## 6. Dependencies
+
+### Blocking Dependencies (must be complete before implementation)
+
+| Dependency | Status | Blocked Phases |
+|---|---|---|
+| #1855 — `HierarchyDetector` protocol + data models | ✅ Merged | All phases |
+
+### Downstream Dependents (unblocked by this feature)
+
+| Issue | Feature | Consumes |
+|---|---|---|
+| #1858 | Directory nesting | `build_hierarchy_tree()` → `HierarchyNode.children` |
+| #1860 | Ordering enforcement | `get_children()` → `ChildEntry.order` |
+| #1864 | Cascade triggering | `detect_hierarchy()` → `HierarchyNode.level` |
+
+### External Dependencies
+
+| Dependency | Required Version | Notes |
+|---|---|---|
+| `gh` CLI | 2.x+ | Must support `gh api graphql --field` syntax |
+| GitHub Sub-Issues API | Beta/GA | REST endpoint may require feature flag |
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*