agentic-devtools 0.2.220__tar.gz → 0.2.221__tar.gz

{agentic_devtools-0.2.220 → agentic_devtools-0.2.221}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.220
+Version: 0.2.221
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT
@@ -16,6 +16,7 @@ Requires-Dist: langgraph-checkpoint-sqlite>=3.0.1
 Requires-Dist: langgraph>=0.2.0
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: packaging>=21.0
+Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: requests>=2.28.0
 Requires-Dist: twine>=5.0.0

{agentic_devtools-0.2.220 → agentic_devtools-0.2.221}/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.220'
-__version_tuple__ = version_tuple = (0, 2, 220)
+__version__ = version = '0.2.221'
+__version_tuple__ = version_tuple = (0, 2, 221)
 
 __commit_id__ = commit_id = None

agentic_devtools-0.2.221/agentic_devtools/epic_tree/__init__.py

@@ -0,0 +1,28 @@
+"""Public API for epic-tree schema validation, models, and loading.
+
+This package provides functions and types for validating epic-tree JSON
+documents against the versioned JSON Schema (Draft 2019-09), typed Pydantic
+models for the document structure, and a loader that parses JSON files into
+those models with aggregated validation errors.
+"""
+
+from .errors import EpicTreeLoadError, EpicTreeValidationError, VersionMismatchError
+from .loader import load_epic_tree
+from .models import EpicTree, FeatureNode, IssueNode, SubtaskNode
+from .schema import SCHEMA_PATH, load_schema
+from .validator import check_schema_version, validate_epic_tree
+
+__all__ = [
+    "SCHEMA_PATH",
+    "EpicTree",
+    "EpicTreeLoadError",
+    "EpicTreeValidationError",
+    "FeatureNode",
+    "IssueNode",
+    "SubtaskNode",
+    "VersionMismatchError",
+    "check_schema_version",
+    "load_epic_tree",
+    "load_schema",
+    "validate_epic_tree",
+]

{agentic_devtools-0.2.220 → agentic_devtools-0.2.221}/agentic_devtools/epic_tree/errors.py

@@ -22,6 +22,35 @@ class EpicTreeValidationError:
     property_name: str | None = None
 
 
+class EpicTreeLoadError(Exception):
+    """Raised when loading an epic-tree document fails validation.
+
+    Wraps an aggregated collection of :class:`EpicTreeValidationError` entries
+    so that callers receive all problems at once rather than just the first.
+
+    Attributes:
+        errors: Tuple of all validation errors found in the document.
+    """
+
+    def __init__(self, errors: list[EpicTreeValidationError]) -> None:
+        self._errors = tuple(errors)
+        super().__init__(str(self))
+
+    @property
+    def errors(self) -> tuple[EpicTreeValidationError, ...]:
+        """All validation errors found in the document."""
+        return self._errors
+
+    def __str__(self) -> str:
+        count = len(self._errors)
+        lines = [f"{count} validation error(s) in epic tree:"]
+        for err in self._errors[:5]:
+            lines.append(f"  {err.path}: {err.message}")
+        if count > 5:
+            lines.append(f"  ... and {count - 5} more")
+        return "\n".join(lines)
+
+
 class VersionMismatchError(Exception):
     """Raised when a document's ``schemaVersion`` is not supported.
 

agentic_devtools-0.2.221/agentic_devtools/epic_tree/loader.py

@@ -0,0 +1,53 @@
+"""Loader for epic-tree JSON documents into typed Pydantic models.
+
+Provides :func:`load_epic_tree` which reads, validates, and parses an
+epic-tree JSON file into a fully populated :class:`~.models.EpicTree`
+instance with aggregated validation errors.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .errors import EpicTreeLoadError, EpicTreeValidationError
+from .models import EpicTree
+from .validator import check_schema_version, validate_epic_tree
+
+
+def load_epic_tree(path: Path | str) -> EpicTree:
+    """Load and parse an epic-tree JSON file into an :class:`EpicTree` instance.
+
+    Args:
+        path: File path to the epic-tree JSON document. If a string is passed,
+            it is converted to :class:`~pathlib.Path` internally.
+
+    Returns:
+        A fully populated :class:`EpicTree` model instance.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        json.JSONDecodeError: If the file contains syntactically invalid JSON
+            (propagated unwrapped from :func:`json.loads`).
+        VersionMismatchError: If the document's ``schemaVersion`` is not
+            supported (propagated from :func:`check_schema_version`).
+        EpicTreeLoadError: If the document fails structural or semantic
+            validation (wraps all :class:`EpicTreeValidationError` entries).
+    """
+    path = Path(path)
+    text = path.read_text(encoding="utf-8")
+    document: Any = json.loads(text)
+
+    # Conditional version check — only when document is a dict with a string schemaVersion
+    if isinstance(document, dict) and "schemaVersion" in document and isinstance(document["schemaVersion"], str):
+        try:
+            check_schema_version(document)
+        except ValueError:
+            pass  # Invalid semver deferred to validate_epic_tree
+
+    errors: list[EpicTreeValidationError] = validate_epic_tree(document)
+    if errors:
+        raise EpicTreeLoadError(errors)
+
+    return EpicTree.model_validate(document)

agentic_devtools-0.2.221/agentic_devtools/epic_tree/models.py

@@ -0,0 +1,59 @@
+"""Pydantic v2 models for the epic-tree document structure.
+
+Provides typed, immutable models that mirror the epic-tree JSON Schema:
+- :class:`IssueNode` — shared base with common fields
+- :class:`SubtaskNode` — leaf-level work item (no children)
+- :class:`FeatureNode` — mid-level node with subtasks
+- :class:`EpicTree` — root node with schema version and features
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class IssueNode(BaseModel):
+    """Shared base model for all epic-tree node types.
+
+    Provides the common fields present at every level of the tree:
+    ref, title, body, labels, issueType, and optional order/blockedBy/blocks.
+    """
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True, extra="forbid")
+
+    ref: str
+    title: str
+    body: str
+    labels: tuple[str, ...]
+    issueType: str
+    order: int | None = None
+    blockedBy: tuple[str, ...] = ()
+    blocks: tuple[str, ...] = ()
+
+
+class SubtaskNode(IssueNode):
+    """Leaf-level model representing an atomic unit of work.
+
+    Inherits all fields from :class:`IssueNode` with no additional
+    child collection fields.
+    """
+
+
+class FeatureNode(IssueNode):
+    """Mid-level model representing a capability or deliverable within an epic.
+
+    Inherits from :class:`IssueNode` and adds an ordered tuple of subtasks.
+    """
+
+    subtasks: tuple[SubtaskNode, ...]
+
+
+class EpicTree(IssueNode):
+    """Root model representing the top-level epic node of an epic-tree document.
+
+    Inherits from :class:`IssueNode` and adds the schema version string
+    and an ordered tuple of features.
+    """
+
+    schemaVersion: str
+    features: tuple[FeatureNode, ...]

{agentic_devtools-0.2.220 → agentic_devtools-0.2.221}/agentic_devtools/epic_tree/validator.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+from typing import Any
 
 from jsonschema import Draft201909Validator
 
@@ -26,7 +27,7 @@ def _to_json_pointer(path_parts: list) -> str:
     return "/" + "/".join(escaped)
 
 
-def validate_epic_tree(document: dict) -> list[EpicTreeValidationError]:
+def validate_epic_tree(document: Any) -> list[EpicTreeValidationError]:
     """Validate an epic-tree document against the schema and semantic rules.
 
     Performs two passes:

{agentic_devtools-0.2.220 → agentic_devtools-0.2.221}/pyproject.toml

@@ -24,6 +24,7 @@ dependencies = [
     "langgraph-checkpoint-sqlite>=3.0.1",
     "mcp>=1.0.0",
     "jsonschema>=4.20.0",
+    "pydantic>=2.0,<3",
     "packaging>=21.0",
     "github-copilot-sdk>=1.0.0,<2.0.0",
 ]

agentic_devtools-0.2.221/specs/1862-ordering-determinism-via-hierarchy/spec.md

@@ -0,0 +1,309 @@
+# Feature Specification: Ordering Determinism via `hierarchy.yml` Order Field
+
+**Feature Branch**: `speckit/1862/phase-1-specify`
+**Created**: 2026-06-20
+**Status**: Draft
+**Input**: GitHub Issue #1862 — Add ordering determinism via hierarchy.yml order field
+**Source Issue**: #1862 (<https://github.com/swai-factory/agentic-devtools/issues/1862>)
+
+## Problem Statement
+
+The SpecKit hierarchy system introduces a three-level Epic → Feature → Task structure where parent issues contain ordered lists of child issues. Each child entry in `hierarchy.yml` carries an `order`
+field — an integer that declares the intended execution position of that child relative to its siblings. However, while the data model (established by subtask #1855) stores this field and round-trip
+tests confirm it survives serialization, no logic currently exists to interpret the `order` field semantically. The children list preserves YAML declaration order, but there is no function to answer
+questions like "which child comes first?", "which child follows this one?", or "where does this child sit in the sequence?"
+
+This gap matters because the cascade trigger system (subtask #1861) needs to traverse children in a deterministic, explicitly controlled sequence. When an AI agent finishes work on one child issue and
+the cascade system must decide which sibling to trigger next, it needs an authoritative answer derived from the `order` field — not from arbitrary API response ordering or file declaration position.
+Without ordering helpers, the cascade system would either need to implement its own ad-hoc sorting (violating separation of concerns) or rely on list position in the YAML file, which is fragile and
+non-obvious to users who expect the `order` field to govern sequencing.
+
+Additionally, real-world hierarchies exhibit imperfect ordering. Users may manually edit `hierarchy.yml` to reorder children, creating gaps in the sequence (e.g., 1, 2, 5, 8). Automated tooling may
+assign duplicate `order` values when merging hierarchies from different sources. Some children may lack an `order` field entirely if they were appended by older tooling or manual edits before
+validation was enforced. The ordering helpers must handle all of these edge cases deterministically, producing consistent results regardless of input imperfections, so that cascade triggers behave
+predictably and progress reporting (e.g., "Task 3 of 7") is always accurate.
+
+## Visual Overview
+
+```mermaid
+flowchart TD
+    START([Feature Specified]) --> GFC
+
+    subgraph DATA["Data Model"]
+        direction TB
+        HN["HierarchyNode\n(children: list[ChildEntry])"]
+        CE["ChildEntry\nkey: str · order: int | None"]
+        HN --> CE
+    end
+
+    subgraph SORT["Deterministic Sort Order (applied by all functions)"]
+        direction TB
+        S1["① Effective order\n(missing → max+1, FR-005)"]
+        S2["② Numeric key tiebreaker\n(FR-004)"]
+        S3["③ Lexicographic tiebreaker\n(FR-004)"]
+        S1 --> S2 --> S3
+    end
+
+    GFC["get_first_child(node)\n→ key of lowest-order child"]
+    GNC["get_next_child(node, current_key)\n→ key of next child, or None"]
+    GCP["get_child_position(node, key)\n→ (position, total)"]
+
+    GFC -->|"first child key"| PROCESS
+    GFC -->|"None — no children"| END_EMPTY([End: nothing to trigger])
+
+    PROCESS["Cascade Trigger\nprocesses child issue"]
+
+    PROCESS --> GCP
+    GCP -->|"e.g. (3, 7) → 'Task 3 of 7'"| REPORT["Progress Reporting\n(Jira comment / PR description)"]
+
+    PROCESS --> GNC
+    GNC -->|"next sibling key"| PROCESS
+    GNC -->|"None — last child"| END_DONE([Cascade propagates\nup to parent])
+
+    DATA -.->|"input"| GFC
+    DATA -.->|"input"| GNC
+    DATA -.->|"input"| GCP
+    SORT -.->|"governs"| GFC
+    SORT -.->|"governs"| GNC
+    SORT -.->|"governs"| GCP
+```
+
+## User Scenarios & Testing
+
+### User Story 1 — Cascade Trigger Determines Next Sibling (Priority: P1)
+
+The cascade trigger system is the primary consumer of ordering helpers. When an AI agent completes work on a child issue, the cascade system must determine which sibling to trigger next. This is the
+foundational use case that drives the entire feature: without it, cascade triggers cannot advance through a feature's task list in the correct order.
+
+Consider a feature with five tasks ordered 1 through 5. An agent finishes task 3. The cascade system calls `get_next_child` with the current task's key and receives the key of task 4. If task 5 were
+the current task, the function returns `None`, signaling that all siblings are complete and the cascade should propagate upward to the parent. This deterministic traversal ensures that no task is
+skipped or triggered out of sequence, regardless of when issues were created in GitHub or how the API returns them.
+
+**Why this priority**: This is the core capability that unblocks the cascade trigger system (subtask #1861). Without reliable next-sibling resolution, cascading cannot function correctly.
+
+**Independent Test**: Can be fully tested by constructing a `HierarchyNode` with ordered children and verifying that `get_next_child` returns the correct successor for every position in the sequence,
+including the terminal case returning `None`.
+
+**Acceptance Scenarios**:
+
+1. **Given** a hierarchy node with children
+   `[{key: "A", order: 1}, {key: "B", order: 2}, {key: "C", order: 3}, {key: "D", order: 4}, {key: "E", order: 5}]`,
+   **When** `get_next_child` is called with `current_key="B"`, **Then** `"C"` is returned.
+2. **Given** a hierarchy node with children
+   `[{key: "A", order: 1}, {key: "B", order: 2}, {key: "C", order: 3}]`,
+   **When** `get_next_child` is called with `current_key="C"` (the last child), **Then** `None` is returned.
+3. **Given** a hierarchy node with no children, **When** `get_next_child` is called with any key, **Then** `None` is returned.
+4. **Given** a hierarchy node with children `[{key: "A", order: 1}, {key: "B", order: 2}, {key: "C", order: 3}]`, **When** `get_next_child` is called with `current_key="missing"`, **Then** `None` is returned.
+
+---
+
+### User Story 2 — Cascade Trigger Identifies First Child to Start (Priority: P1)
+
+When a parent issue's spec is processed and the cascade system needs to initiate work on its first child, it must identify which child has the lowest `order` value. This is the entry point for any
+cascade sequence — without it, the system cannot begin traversal.
+
+A feature issue has just been specified, and the cascade trigger needs to kick off work on the first task. The system calls `get_first_child` on the feature's hierarchy node and receives the key of
+the child with the lowest order value. If the feature has no children (perhaps it is a leaf node miscategorized as a feature), the function returns `None`, and the cascade system knows there is
+nothing to trigger.
+
+**Why this priority**: Equally critical as next-sibling resolution — cascade sequences must have a defined starting point. This is co-P1 because `get_first_child` and `get_next_child` together form
+the minimal traversal API.
+
+**Independent Test**: Can be tested by constructing hierarchy nodes with various child configurations (empty, single child, multiple children with non-sequential order values) and verifying the
+correct first child is returned.
+
+**Acceptance Scenarios**:
+
+1. **Given** a hierarchy node with children `[{key: "A", order: 3}, {key: "B", order: 1}, {key: "C", order: 5}, {key: "D", order: 2}]`, **When** `get_first_child` is called, **Then** `"B"` is returned.
+2. **Given** a hierarchy node with an empty children list, **When** `get_first_child` is called, **Then** `None` is returned.
+3. **Given** a hierarchy node with a single child, **When** `get_first_child` is called, **Then** that child's key is returned.
+
+---
+
+### User Story 3 — Progress Reporting Shows Current Position (Priority: P2)
+
+When an AI agent or human reviewer wants to understand how far along a feature's task list has progressed, the system should report the current child's position relative to the total number of
+siblings. This enables progress messages like "Task 3 of 7" in Jira comments, PR descriptions, and agent output, giving stakeholders visibility into cascade progress without requiring them to inspect
+the hierarchy file directly.
+
+An agent is working on the third task of a seven-task feature. The workflow prompt or Jira comment template calls `get_child_position` with the current task's key and receives `(3, 7)`. This tuple is
+formatted into a human-readable progress indicator. If the key is not found among the children, the function must raise a `ValueError` (with diagnostic detail per NFR-003) so callers can handle the
+error explicitly.
+
+**Why this priority**: Progress reporting is valuable for user experience and transparency but is not required for the cascade system to function correctly. The cascade can operate using only
+`get_first_child` and `get_next_child`. Position reporting enhances observability and is therefore P2.
+
+**Independent Test**: Can be tested by constructing hierarchy nodes with known children counts and verifying that the returned tuple accurately reflects the child's ordinal position (1-indexed) and
+the total count.
+
+**Acceptance Scenarios**:
+
+1. **Given** a hierarchy node with children
+   `[{key: "A", order: 1}, {key: "B", order: 2}, {key: "C", order: 3}, {key: "D", order: 4}, {key: "E", order: 5}]`,
+   **When** `get_child_position` is called with `key="C"`, **Then** `(3, 5)` is returned.
+2. **Given** a hierarchy node with children
+   `[{key: "A", order: 10}, {key: "B", order: 20}, {key: "C", order: 30}]`,
+   **When** `get_child_position` is called with `key="B"`, **Then** `(2, 3)` is returned, reflecting
+   the child's sorted position regardless of absolute order values.
+3. **Given** a hierarchy node with children, **When** `get_child_position` is called with a key not present in the children list, **Then** a `ValueError` is raised indicating the key was not found.
+
+---
+
+### User Story 4 — Deterministic Handling of Duplicate Order Values (Priority: P2)
+
+In practice, duplicate `order` values can arise when hierarchies are merged from multiple sources, when tooling assigns orders concurrently, or when users manually edit `hierarchy.yml` without
+checking for conflicts. The ordering helpers must resolve duplicates deterministically so that two different systems processing the same `hierarchy.yml` always produce identical traversal sequences.
+
+Two children both have `order: 3`. Rather than producing undefined behavior or raising an error (which would block cascade processing), the system uses the child's normalized string key as a
+deterministic tiebreaker: keys that can be parsed as integers sort by ascending numeric value; when two distinct string keys parse to the same integer value (e.g., `"12"` and `"012"`), they are
+further resolved by ascending lexicographic comparison of the normalized string; keys that cannot be parsed as integers sort after numeric keys using ascending lexicographic comparison. This
+three-level tiebreak ensures that the resolution is predictable, stable, and does not depend on YAML declaration position.
+
+**Why this priority**: Duplicate orders are an edge case that real hierarchies will encounter. While not part of the happy path, deterministic resolution is essential for the reliability guarantee
+that cascade triggers depend on. It is P2 because the primary ordering logic (P1) must exist first.
+
+**Independent Test**: Can be tested by constructing a hierarchy with two or more children sharing the same order value and verifying that traversal order matches ascending key order within the tied
+group.
+
+**Acceptance Scenarios**:
+
+1. **Given** children `[{key: "10", order: 3}, {key: "7", order: 3}, {key: "12", order: 1}]`, **When** sorted for traversal, **Then** the sequence is key "12" (order 1), key "7" (order 3), key "10"
+   (order 3) — ties broken by ascending numeric key.
+2. **Given** a hierarchy with duplicate orders resolved by key, **When** `get_next_child` is called on the first tied child, **Then** the second tied child (by key) is returned.
+
+---
+
+### User Story 5 — Graceful Handling of Missing Order Fields (Priority: P2)
+
+Although the current JSON Schema requires the `order` field on every child entry, the ordering helpers should be resilient to children that lack an order value. This defensive posture protects against
+legacy or manually edited `hierarchy.yml` files, schema evolution, or data migrations where some children may not yet have been assigned an order. Children without an explicit order are treated as if
+they have the highest order value, placing them at the end of the traversal sequence.
+
+**Why this priority**: This is a defensive edge case. Supporting it requires more than the ordering helpers themselves: the schema and/or load-time normalization path must also permit legacy or
+manually edited child entries with missing or `None` orders to be represented without failing validation first. That extra resilience prevents brittle failures when older or partially migrated
+hierarchies are encountered.
+
+**Independent Test**: Can be tested by exercising the loader/normalization path with legacy child payloads that omit `order`, then verifying the resulting ordering helpers sort a mix of ordered and
+unordered entries correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** children `[{key: "A", order: 1}, {key: "B", order: 2}, {key: "C"}]`, **When** sorted for traversal, **Then** key `"C"` appears after keys `"A"` and `"B"`.
+2. **Given** children `[{key: "2"}, {key: "10"}]` where both children are missing order values, **When** sorted for traversal, **Then** they are ordered relative to each other by the deterministic
+   key-ordering rule from FR-004, both appearing
+   after all children with explicit orders.
+
+---
+
+### Edge Cases
+
+The following edge cases must be handled deterministically:
+
+- What happens when `get_next_child` is called with a key that matches no child in the hierarchy? The function should return `None` rather than raising an exception, since a missing key may indicate
+  the child was removed from the hierarchy after the cascade was initiated.
+
+- What happens when `get_child_position` is called with a key that matches no child in the hierarchy? The function should raise `ValueError` and include the requested key plus available keys in the
+  message, so callers can diagnose mismatches quickly.
+
+- How does the system handle order values with large gaps (e.g., 1, 100, 200)? Gaps are treated as valid. The sort is purely numeric — absolute values do not matter, only relative ordering.
+  `get_next_child` for the child at order 1 returns the child at order 100.
+
+- What happens when a hierarchy node has exactly one child? `get_first_child` returns that child's key. `get_next_child` called with that child's key returns `None`. `get_child_position` returns `(1,
+  1)`.
+
+- How are non-numeric string keys handled as tiebreakers? `ChildEntry.key` is a normalized string identifier. When breaking ties, keys that can be parsed as integers are compared numerically first; if
+  two keys have equal numeric value (for example `"12"` and `"012"`), compare their normalized string values lexicographically; keys that cannot be parsed as integers sort after numeric keys using
+  lexicographic comparison of the normalized string.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: The system MUST provide a `get_first_child(hierarchy: HierarchyNode) -> str | None` function that returns the normalized string issue key of the first child in the deterministic traversal
+  sequence (primary sort by effective `order` per FR-005, tie-break by normalized key per FR-004), or `None` if the children list is empty. This function is the entry point for cascade traversal and must
+  operate in O(n log n) time or better relative to the number of children (consistent with NFR-001).
+
+- **FR-002**: The system MUST provide a `get_next_child(hierarchy: HierarchyNode, current_key: str | int) -> str | None` function that returns the normalized string issue key of the next child in the
+  deterministic sorted traversal sequence after the child identified by `current_key`, or `None` if `current_key` identifies the last child in that sequence. Implementations MUST normalize caller-supplied
+  integer and string keys to the same comparison form used by `ChildEntry.key`. If `current_key` does not match any child in the hierarchy, the function MUST return `None`.
+
+- **FR-003**: The system MUST provide a `get_child_position(hierarchy: HierarchyNode, key: str | int) -> tuple[int, int]` function that returns a tuple of `(current_position, total_children)` where
+  `current_position` is the 1-indexed ordinal position of the child identified by `key` when children are sorted by the ordering rules, and `total_children` is the total number of children.
+  Implementations MUST normalize caller-supplied integer and string keys to the same comparison form used by `ChildEntry.key`. If `key` does not match any child, the function MUST raise a `ValueError`.
+
+- **FR-004**: When two or more children share the same `order` value, the system MUST resolve the tie deterministically by sorting tied children by normalized key using this rule: keys parseable as
+  integers sort first by ascending numeric value; when parseable keys have equal numeric value (for example `"12"` and `"012"`), compare their normalized string values lexicographically; keys that are
+  not parseable as integers sort after numeric keys by ascending lexicographic comparison. This ensures that any system processing the same `hierarchy.yml` produces an identical traversal sequence.
+
+- **FR-005**: When a child entry lacks an explicit `order` value (or the value is `None`), the system MUST treat that child as having an order value of `max_existing_order + 1` for sorting purposes,
+  where `max_existing_order` is the highest explicit non-`None` order value among the node's children, or `0` when no child has an explicit order. This effectively places missing-order children at
+  the end of the traversal sequence while still defining behavior for all-missing-order inputs. Multiple children without order values MUST be sorted among themselves by the deterministic
+  key-ordering rule from FR-004. The implementation MUST update hierarchy schema, loading, or normalization behavior as needed so legacy or manually edited children with missing/`None` `order`
+  values can reach the ordering helpers without failing validation first.
+
+- **FR-006**: The system MUST treat gaps in order sequences (e.g., 1, 2, 5, 8) as valid input. Sorting MUST be purely numeric by the `order` field value — gaps do not affect traversal correctness.
+
+- **FR-007**: When `hierarchy.yml` is generated by automated tooling (e.g., during hierarchy detection), the system MUST auto-assign `order` values starting from 1, incrementing by 1, using the order
+  in which children appear in the source data (typically GitHub API creation order) as the default sequence. Note: legacy `hierarchy.yml` files generated by earlier tooling versions may contain 0-based
+  `order` values (assigned via `enumerate()` starting at 0) or other arbitrary integer sequences — these remain valid input. The ordering helpers sort by relative value only; absolute `order` integers
+  are not required to start at any particular value or be contiguous.
+
+- **FR-008**: All three ordering functions (`get_first_child`, `get_next_child`, `get_child_position`) MUST be pure functions with no side effects — they read from the `HierarchyNode` data structure
+  and return values without modifying the hierarchy, writing to disk, or interacting with external services.
+
+### Non-Functional Requirements
+
+- **NFR-001**: All ordering functions MUST execute in O(n log n) time or better relative to the number of children, where the dominant cost is sorting. For typical hierarchy sizes (fewer than 50
+  children), execution time MUST be imperceptible (under 1 millisecond).
+
+- **NFR-002**: Ordering functions MUST produce identical results for identical inputs across Python versions 3.10+ and across operating systems (Linux, macOS, Windows). Implementations MUST sort by the
+  defined composite ordering key (`order` with missing values appended to the end, then the FR-004 normalized-key tiebreaker) and MUST NOT rely on YAML declaration order or platform-dependent
+  iteration behavior.
+
+- **NFR-003**: Error messages from `get_child_position` when a key is not found MUST include the requested key and the list of available keys, enabling rapid diagnosis without requiring the caller to
+  inspect the hierarchy separately.
+
+- **NFR-004**: The ordering functions MUST be importable from `agentic_devtools.cli.speckit.hierarchy` alongside the existing `HierarchyNode`, `ChildEntry`, `load_hierarchy`, and `save_hierarchy`
+  symbols, maintaining the module's role as the single entry point for hierarchy operations.
+
+### Key Entities
+
+- **`ChildEntry`**: Represents a single child issue within a hierarchy node. Key attributes for ordering are `key` (string-normalized issue identifier, used as tiebreaker) and `order` (integer declaring
+  intended position). Already defined by subtask #1855; this feature consumes the field semantically.
+
+- **`HierarchyNode`**: Represents a single level in the hierarchy tree, containing a `children: list[ChildEntry]` that the ordering functions operate on. The ordering functions treat `HierarchyNode`
+  as read-only input.
+
+- **Sorted children sequence**: The conceptual ordered list produced by sorting `children` by `(order, normalized_key_tiebreaker)` where the tiebreaker follows FR-004's numeric-first, then
+  lexicographic rule. This sequence is not persisted — it is computed on demand by the ordering functions. The `hierarchy.yml` file retains its original declaration order; the ordering functions
+  interpret the `order` field without mutating the source list.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `get_first_child` correctly returns the child with the lowest `order` value in 100% of test cases, including edge cases with single children, gaps in order values, and duplicate orders
+  resolved by key.
+
+- **SC-002**: `get_next_child` correctly returns the next child in the deterministic traversal sequence
+  (effective `order` per FR-005 + key tie-break per FR-004) in 100% of test cases, returns `None` for
+  the last child, and returns `None` for non-existent keys — with zero false positives or missed
+  successors across all edge-case permutations.
+
+- **SC-003**: `get_child_position` returns accurate `(position, total)` tuples for every child in a hierarchy, with the position matching the child's rank in the sorted sequence. 100% of position
+  values must be 1-indexed and satisfy `1 ≤ position ≤ total`.
+
+- **SC-004**: All three ordering functions achieve 100% branch coverage in unit tests, consistent with the repository's per-file coverage requirement enforced by CI.
+
+- **SC-005**: When two or more children share the same `order` value, the traversal sequence produced by repeated `get_next_child` calls matches the full FR-004 deterministic tie-break rule (numeric-first
+  key ordering, then lexicographic comparison for numeric-equal or non-numeric keys) in 100% of cases — verified across at least 3 distinct duplicate-order scenarios.
+
+- **SC-006**: Ordering functions operate without I/O and run in O(n log n) time or better for `n` children.
+  No timing assertions are made; the algorithmic constraint is verified by confirming the implementation uses only in-memory
+  sorting (no file reads, network calls, or external state) and that the sort comparator is free of side effects.
+
+- **SC-007**: The ordering module introduces zero breaking changes to existing `load_hierarchy` and `save_hierarchy` behavior — verified by all pre-existing hierarchy tests continuing to pass without
+  modification.
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.221/specs/2102-implement-pydantic-models-and/.markdownlint.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
+  "extends": "../../.markdownlint.json",
+  "MD041": true
+}

agentic_devtools-0.2.221/specs/2102-implement-pydantic-models-and/analysis-report.md

@@ -0,0 +1,83 @@
+# Cross-Artifact Consistency and Quality Analysis Report
+
+## Findings Table
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| B-01 | Ambiguity | MEDIUM | NFR-001, T017 | "standard CI hardware" is undefined — no CPU/RAM/OS baseline specified for the 500ms performance target | Define reference hardware (e.g., "GitHub Actions ubuntu-latest 2-core runner") or make the threshold configurable-only without a hard CI gate |
+| C-01 | Underspecification | MEDIUM | FR-005, Plan Phase 3 | Loader reads file with `encoding="utf-8"` but spec doesn't specify encoding behavior for non-UTF-8 files — unclear if `UnicodeDecodeError` should propagate or be wrapped | Add explicit statement: "If the file is not valid UTF-8, `UnicodeDecodeError` propagates unwrapped" |
+| C-02 | Underspecification | LOW | FR-008, User Story 4 scenario 1 | FR-008 enumerates `labels`, `blockedBy`, and `blocks` as the tuple fields that MUST serialize as lists, but does not explicitly mention the `features` and `subtasks` child-collection tuples — it is unclear whether FR-008's tuple→list serialization guidance covers these child collections | Clarify FR-008 to explicitly include `features` and `subtasks` in the tuple→list serialization guarantee (both are required fields per FR-001/FR-002; the gap is serialization coverage, not field optionality) |
+| F-01 | Clarification | MEDIUM | Plan §2 vs FR-004/FR-008 | Research summary states "no `Field(alias=...)` required" because Python attributes use camelCase directly, but FR-004 mandates `populate_by_name=True` (which is effectively a no-op unless aliases exist) — the rationale for this setting is unclear | Clarify in the plan that `populate_by_name=True` is harmless today and intended for forward-compatibility if aliases are added later; document this explicitly |
+| F-02 | Inconsistency | LOW | Plan Phase 3 code | Plan code sets `_errors` before calling `super().__init__(str(self))` — this ordering is required because `EpicTreeLoadError.__str__` (introduced by the plan's sample implementation) references `self._errors`; if `super().__init__(str(self))` ran first, `__str__` would execute before `_errors` is set. FR-006 only specifies external behavior (error count + sample paths) and does not mandate an internal `_errors` field; the ordering dependency is an implementation detail of the plan, not a spec requirement | Note: plan code is correct (sets `_errors` before `super().__init__(str(self))`); no action needed but worth a comment in implementation |
+| F-03 | Inconsistency | MEDIUM | Spec "Edge Cases" vs FR-007 | Edge cases say version check should "raise `VersionMismatchError` before calling `validate_epic_tree()`" but FR-007 specifies ignoring `ValueError` from `check_schema_version` — the edge cases section doesn't mention the `ValueError` ignore path | Add `ValueError` handling to edge cases narrative for completeness |
+| F-04 | Inconsistency | MEDIUM | Plan Phase 3 vs T009 | Plan Phase 3 creates `EpicTreeLoadError` inside `agentic_devtools/epic_tree/loader.py`; T009 explicitly states it should be implemented in `agentic_devtools/epic_tree/errors.py` alongside other exception types — plan and tasks disagree on the home module for this exception | Resolve by updating the plan to place `EpicTreeLoadError` in `errors.py`, consistent with T009 |
+| G-01 | Task Deduplication | HIGH | T012, T021 | T012 tests IssueNode construction/defaults/immutability; T021 tests polymorphic access on IssueNode from all 3 types — both in same file `test_issuenode.py`, both verify shared field access | See structured findings below |
+| G-02 | Task Deduplication | HIGH | T015, T016 | T015 tests EpicTree model construction from fixture JSON via `model_validate`; T016 tests `load_epic_tree` loading `valid-epic.json` and verifying fields match — significant description overlap (verify fixture content matches) though different code paths | See structured findings below |
+| G-03 | Task Deduplication | HIGH | T022, T023 | T022 tests round-trip serialization in `test_epictree.py`; T023 tests same serialization behavior in `test_featurenode.py` and `test_subtasknode.py` — same intent (verify `model_dump` camelCase keys + list serialization) across different files | See structured findings below |
+
+## Category G Structured Findings
+
+```json
+[
+  {
+    "id": "G-01",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T012", "T021"],
+    "dimensions": ["file_path"],
+    "rationale": "Both target tests/unit/epic_tree/models/test_issuenode.py. T012 tests IssueNode construction including all shared fields; T021 tests polymorphic access to the same shared fields from all concrete types. Different intent (unit vs polymorphic contract) but same file and partially overlapping assertions on field accessibility."
+  },
+  {
+    "id": "G-02",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T015", "T016"],
+    "dimensions": ["description"],
+    "rationale": "Both verify that a valid epic-tree fixture produces correct EpicTree fields, feature/subtask counts, and declaration order. T015 uses model_validate directly; T016 uses load_epic_tree. Different code paths but substantially similar acceptance assertions on the same fixture data."
+  },
+  {
+    "id": "G-03",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T022", "T023"],
+    "dimensions": ["description"],
+    "rationale": "Both verify model_dump(by_alias=True, mode='json') produces camelCase keys and list serialization. T022 covers EpicTree (all 3 levels); T023 covers FeatureNode and SubtaskNode individually. The 'at all 3 levels' scope in T022 materially overlaps T023's per-node verification."
+  }
+]
+```
+
+## Coverage Summary Table
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|----------------|-----------|----------|-------|
+| FR-001 | Yes | T008, T015, T016 | Covered |
+| FR-002 | Yes | T007, T014, T016 | Covered |
+| FR-003 | Yes | T006, T013, T016 | Covered |
+| FR-004 | Yes | T005, T012, T013, T014, T015, T021 | Covered |
+| FR-005 | Yes | T010, T016, T017, T019, T020 | Covered |
+| FR-006 | Yes | T009, T018, T019, T020 | Covered |
+| FR-007 | Yes | T010, T016, T019 | Covered |
+| FR-008 | Yes | T022, T023 | Covered |
+| FR-009 | Yes | T005, T012, T013, T014, T015 | Covered |
+| FR-010 | Yes | T011, T016 | Covered |
+| NFR-001 | Yes | T017 | Covered (configurable threshold) |
+| NFR-002 | Yes | T009, T018 | Covered |
+| NFR-003 | Yes | T001, T002 | Covered |
+| NFR-004 | Yes | T027, T028, T029, T030 | Covered |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total Requirements | 14 (10 FR + 4 NFR) |
+| Total Tasks | 30 |
+| Coverage % | 100% |
+| Ambiguity Count | 1 |
+| Requirement Duplication Count (Category A) | 0 |
+| Critical Issues Count | 0 |
+| Task Deduplication Finding Count | 3 |
+| Task Deduplication by Type | duplicate: 0 / overlapping: 3 / conflicting: 0 |
+| Multi-Task Group Count | 0 |
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*