agentic-devtools 0.2.231__tar.gz → 0.2.232__tar.gz

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/.gitignore

@@ -139,6 +139,9 @@ specs/*/contracts/*
 !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/1885-map-event-driven-workflow/research.md
+!specs/1885-map-event-driven-workflow/data-model.md
+!specs/1885-map-event-driven-workflow/quickstart.md
 specs/*/checklists/.generation-prompt-*.md
 .specify/memory/agent-file.md
 .markdownlint-debug.log

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/PKG-INFO

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

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/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.231'
-__version_tuple__ = version_tuple = (0, 2, 231)
+__version__ = version = '0.2.232'
+__version_tuple__ = version_tuple = (0, 2, 232)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/agentic_devtools/cli/speckit/hierarchy.py

@@ -29,6 +29,9 @@ __all__ = [
     "HierarchyLevel",
     "HierarchyNode",
     "HierarchyValidationError",
+    "get_child_position",
+    "get_first_child",
+    "get_next_child",
     "load_hierarchy",
     "save_hierarchy",
 ]
@@ -94,12 +97,12 @@ class ChildEntry:
     Attributes:
         key: Child issue identifier (normalized to string).
         title: Human-readable issue title.
-        order: Advisory integer for intended position.
+        order: Advisory integer for intended position (None if unset).
     """
 
     key: str
     title: str
-    order: int
+    order: int | None
 
     def __post_init__(self) -> None:
         """Validate fields and normalize key to string."""
@@ -109,8 +112,8 @@ class ChildEntry:
             raise HierarchyValidationError("key", "Expected string or integer issue identifier")
         if not isinstance(self.title, str) or not self.title:
             raise HierarchyValidationError("title", "Expected non-empty string")
-        if isinstance(self.order, bool) or not isinstance(self.order, int):
-            raise HierarchyValidationError("order", "Expected integer")
+        if self.order is not None and (isinstance(self.order, bool) or not isinstance(self.order, int)):
+            raise HierarchyValidationError("order", "Expected integer or None")
         self.key = str(self.key)
 
     def to_dict(self) -> dict[str, Any]:
@@ -212,7 +215,7 @@ HIERARCHY_SCHEMA: dict[str, Any] = {
             "description": "Ordered list of child entries.",
             "items": {
                 "type": "object",
-                "required": ["key", "title", "order"],
+                "required": ["key", "title"],
                 "properties": {
                     "key": {
                         "description": "Child issue identifier.",
@@ -226,7 +229,7 @@ HIERARCHY_SCHEMA: dict[str, Any] = {
                         "minLength": 1,
                     },
                     "order": {
-                        "type": "integer",
+                        "type": ["integer", "null"],
                     },
                 },
                 "additionalProperties": False,
@@ -437,7 +440,7 @@ def load_hierarchy(path: Path) -> HierarchyNode:
     for index, child_data in enumerate(children_raw):
         if not isinstance(child_data, dict):
             raise HierarchyValidationError(f"children.{index}", "Expected mapping")
-        for required in ("key", "title", "order"):
+        for required in ("key", "title"):
             if required not in child_data:
                 raise HierarchyValidationError(
                     f"children.{index}.{required}",
@@ -458,13 +461,14 @@ def load_hierarchy(path: Path) -> HierarchyNode:
             raise HierarchyValidationError(f"children.{index}.key", "Expected string or integer")
         if not isinstance(child_data["title"], str) or not child_data["title"]:
             raise HierarchyValidationError(f"children.{index}.title", "Expected non-empty string")
-        if not isinstance(child_data["order"], int) or isinstance(child_data["order"], bool):
-            raise HierarchyValidationError(f"children.{index}.order", "Expected integer")
+        order_raw = child_data.get("order")
+        if order_raw is not None and (not isinstance(order_raw, int) or isinstance(order_raw, bool)):
+            raise HierarchyValidationError(f"children.{index}.order", "Expected integer or null")
         children.append(
             ChildEntry(
                 key=str(child_data["key"]),
                 title=child_data["title"],
-                order=child_data["order"],
+                order=order_raw,
             )
         )
 
@@ -503,3 +507,95 @@ def save_hierarchy(node: HierarchyNode, path: Path) -> None:
         allow_unicode=True,
     )
     path.write_text(content, encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Ordering helpers
+# ---------------------------------------------------------------------------
+
+
+def _child_sort_key(child: ChildEntry, effective_order_for_none: int) -> tuple[int, int, int, str]:
+    """Return a composite sort key for deterministic child ordering.
+
+    The tuple components are:
+      1. Effective order (explicit value, or *effective_order_for_none* for None)
+      2. Numeric parsability flag (0 = numeric key, 1 = non-numeric key)
+      3. Numeric value of key (0 for non-numeric)
+      4. Lexicographic string key (final tiebreaker)
+    """
+    order = child.order if child.order is not None else effective_order_for_none
+    try:
+        numeric_value = int(child.key)
+        return (order, 0, numeric_value, child.key)
+    except (ValueError, TypeError):
+        return (order, 1, 0, child.key)
+
+
+def _sorted_children(children: list[ChildEntry]) -> list[ChildEntry]:
+    """Return children sorted by composite key (no mutation of input list).
+
+    Children with explicit order values are sorted by those values first.
+    Children with ``None`` order are placed after all explicitly-ordered
+    children, using ``max_existing_order + 1`` as their effective order.
+    Ties are broken by numeric key value, then lexicographic string key.
+    """
+    # Compute max existing explicit order (0 when none exist)
+    explicit_orders = [c.order for c in children if c.order is not None]
+    max_existing_order = max(explicit_orders) if explicit_orders else 0
+    effective_order_for_none = max_existing_order + 1
+
+    return sorted(children, key=lambda c: _child_sort_key(c, effective_order_for_none))
+
+
+def get_first_child(hierarchy: HierarchyNode) -> str | None:
+    """Return the key of the child with the lowest order value.
+
+    Returns None if the node has no children.
+    """
+    if not hierarchy.children:
+        return None
+    sorted_kids = _sorted_children(hierarchy.children)
+    return sorted_kids[0].key
+
+
+def get_next_child(hierarchy: HierarchyNode, current_key: str | int) -> str | None:
+    """Return the key of the next child after *current_key* in sorted order.
+
+    Args:
+        hierarchy: The parent node.
+        current_key: The key of the current child (int or str, normalized).
+
+    Returns:
+        The next child's key, or None if *current_key* is the last child
+        or not found in the children list.
+    """
+    normalized_key = str(current_key)
+    sorted_kids = _sorted_children(hierarchy.children)
+    for i, child in enumerate(sorted_kids):
+        if child.key == normalized_key:
+            if i + 1 < len(sorted_kids):
+                return sorted_kids[i + 1].key
+            return None
+    return None
+
+
+def get_child_position(hierarchy: HierarchyNode, key: str | int) -> tuple[int, int]:
+    """Return the 1-indexed position and total children count for *key*.
+
+    Args:
+        hierarchy: The parent node.
+        key: The child key to locate (int or str, normalized).
+
+    Returns:
+        A tuple of (position, total) where position is 1-indexed.
+
+    Raises:
+        ValueError: If *key* is not found among the children.
+    """
+    normalized_key = str(key)
+    sorted_kids = _sorted_children(hierarchy.children)
+    for i, child in enumerate(sorted_kids):
+        if child.key == normalized_key:
+            return (i + 1, len(sorted_kids))
+    available_keys = [c.key for c in sorted_kids]
+    raise ValueError(f"Key {normalized_key!r} not found in children. Available keys: {available_keys}")

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/agentic_devtools/cli/speckit/hierarchy_detector.py

@@ -526,10 +526,8 @@ class GitHubHierarchyDetector:
 
             title = _normalize_issue_title(item.get("title"), child_number)
 
-            # Determine order: advisory_order > position > index fallback
-            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)
+            # Assign 1-based order by position in response list (FR-007)
+            order_value = idx + 1
 
             # Check for cross-repo children
             child_repo_info = item.get("repository")
@@ -609,7 +607,7 @@ class GitHubHierarchyDetector:
             if number is None:
                 continue
             title = _normalize_issue_title(node.get("title"), number)
-            children.append(ChildEntry(key=str(number), title=title, order=idx))
+            children.append(ChildEntry(key=str(number), title=title, order=idx + 1))
 
         return children
 

agentic_devtools-0.2.232/specs/1858-update-create-new-feature/analysis-report.md

@@ -0,0 +1,90 @@
+# Cross-Artifact Consistency and Quality Analysis Report
+
+## Findings Table
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A-01 | Duplication | LOW | FR-001, FR-004 | Stub title format `"Issue {N}"` fallback is specified redundantly in FR-001 and FR-004 with slightly different phrasing | Consolidate into FR-004 as the canonical definition; FR-001 can reference FR-004 |
+| A-02 | Duplication | LOW | FR-005, NFR-003 | Cross-process advisory locking on `.hierarchy.yml.lock` with 5s timeout is fully specified in both FR-005 and NFR-003 | Keep NFR-003 as the quality attribute; FR-005 can reference NFR-003 for locking details |
+| B-01 | Ambiguity | MEDIUM | NFR-001 | "normal network conditions" is undefined — no baseline latency/bandwidth specified for the 10s timeout | Define expected network conditions (e.g., <500ms API RTT) or state timeout is absolute regardless of conditions |
+| B-02 | Ambiguity | MEDIUM | SC-008 | "normal network conditions" repeated in SC-008's 15s completion criterion without measurable definition | Specify as unconditional wall-clock measurement or define network baseline |
+| C-01 | Underspecification | MEDIUM | FR-002 | Ancestry resolution for missing parent directories mentions "hierarchy detection, existing `hierarchy.yml` metadata, or an equivalent ancestry lookup" — the "equivalent ancestry lookup" is undefined | Specify concrete mechanisms or remove the vague alternative |
+| C-02 | Underspecification | MEDIUM | Plan Phase 5 | "atomic write-back (write to a temp file then rename)" — unclear whether this applies to the Bash script directly or delegates to Python `save_hierarchy()` | Clarify: if Bash, specify temp file location/naming; if Python, state which wrapper is invoked |
+| C-03 | Underspecification | MEDIUM | Plan Phase 2 | `detect_parent_cli.py` output format described as "line-oriented" but exact field names, order, and delimiter not formally specified | Define a concrete output contract (e.g., `PARENT\tLEVEL\tTITLE\tSTATUS` or one-per-line with labels) |
+| D-01 | Constitution Alignment | LOW | Spec | No explicit "Out of Scope" section — while not strictly mandated, helps prevent scope creep during implementation | Add a brief "Out of Scope" section listing what this feature intentionally does NOT address |
+| E-01 | Coverage Gaps | MEDIUM | NFR-004 | NFR-004 (stderr diagnostic format with `[specify]` prefix) has no dedicated test task verifying the prefix convention across all error paths | Add a test task or expand T019/T022 to explicitly verify `[specify]` prefix in stderr output |
+| F-01 | Inconsistency | MEDIUM | Plan Phase 1 vs FR-007 | Plan Phase 1 says "Validate `--parent` is positive integer when `--flat` absent" but also adds a rule about `--issue` absent + `--parent` present that is not in FR-007 — it's in a separate [RESOLVED] open question | The `--issue` absent + `--parent` validation rule should be promoted to a numbered FR or added to FR-007 explicitly |
+| F-02 | Inconsistency | LOW | Plan Phase 5 vs FR-005 | Plan says "flock path... if `.hierarchy.yml.lock` already exists as a directory... poll/retry" but FR-005 only specifies "5-second timeout before failing" without mentioning cross-strategy interop polling | Align: either add cross-strategy interop to FR-005 or note it as implementation detail only |
+| F-03 | Inconsistency | LOW | Task T020 vs Plan Phase 1 | T020 names function `parse_parent_flag()` but Plan Phase 1 calls it `validate_parent_flag()` | Standardize function name across plan and tasks |
+| G-01 | Task Deduplication | HIGH | T006, T007 | Both create integration tests for nested child creation covering FR-003, FR-004, FR-005 — T006 with existing parent, T007 with missing parent. Same file paths likely targeted, different scenarios but significant overlap in test infrastructure | See structured findings below |
+| G-02 | Task Deduplication | HIGH | T036, T012 | T036 writes max-depth enforcement integration test; T012 implements `compute_nesting_depth()` including "enforce max depth 3 with flat fallback and `[specify]` warning" — T012's test verification overlaps with T036's dedicated test | See structured findings below |
+| G-03 | Task Deduplication | HIGH | T039, T040 | Both are full-suite validation runs covering all FRs — T039 runs `agdt-test`, T040 runs `targeted-checks.sh`; while different tools, both verify no regressions across the same scope | See structured findings below |
+
+## Coverage Summary Table
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|----------------|-----------|----------|-------|
+| FR-001 | ✅ | T001, T002, T006, T008, T009, T010, T021, T035, T037, T039, T040 | Well covered |
+| FR-002 | ✅ | T001, T002, T005, T007, T011, T015, T035, T039, T040 | Well covered |
+| FR-003 | ✅ | T001, T002, T006, T007, T013, T035, T039, T040 | Well covered |
+| FR-004 | ✅ | T001, T002, T006, T007, T013, T035, T039, T040 | Well covered |
+| FR-005 | ✅ | T001, T002, T006, T007, T014, T016, T035, T039, T040 | Well covered |
+| FR-006 | ✅ | T017, T018, T039, T040 | Covered |
+| FR-007 | ✅ | T019, T020, T021, T022, T039, T040 | Covered |
+| FR-008 | ✅ | T023, T024, T038, T039, T040 | Covered |
+| FR-009 | ✅ | T023, T025, T038, T039, T040 | Covered |
+| FR-010 | ✅ | T026–T034, T039, T040 | Covered |
+| FR-011 | ✅ | T012, T036, T039, T040 | Covered |
+| NFR-001 | ✅ | T008, T010, T037 | Covered via timeout tests |
+| NFR-002 | ✅ | T005, T034, T035 | Covered |
+| NFR-003 | ✅ | T014, T016 | Covered via locking tests |
+| NFR-004 | ⚠️ | (implicit in T019, T022) | No dedicated task for `[specify]` prefix validation |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total Requirements | 15 (11 FR + 4 NFR) |
+| Total Tasks | 40 |
+| FR Coverage % | 100% (11/11 FRs covered) |
+| NFR Coverage % | 75% (3/4 NFRs fully covered; NFR-004 partial — no dedicated task) |
+| Ambiguity Count | 2 (B-01, B-02) |
+| Requirement Duplication Count (Category A) | 2 |
+| Critical Issues Count | 0 |
+| Task Deduplication Finding Count | 3 |
+| Task Deduplication by Type | 0 duplicate / 3 overlapping / 0 conflicting |
+| Multi-Task Group Count | 0 |
+
+### Category G Structured Findings
+
+```json
+[
+  {
+    "id": "G-01",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T006", "T007"],
+    "dimensions": ["description"],
+    "rationale": "Both tasks write integration tests for nested child creation covering FR-003/FR-004/FR-005. They differ by precondition (existing vs missing parent) but share substantial test infrastructure, likely same test file directory, and similar assertion patterns. Only description dimension matches strongly — different scenarios justify separate tasks but overlap is notable."
+  },
+  {
+    "id": "G-02",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T012", "T036"],
+    "dimensions": ["description"],
+    "rationale": "T012 implements compute_nesting_depth() with max-depth-3 enforcement and flat fallback with warning. T036 writes an integration test specifically for max-depth enforcement verifying the same flat fallback and warning. While one is implementation and one is test, T012's description includes the enforcement behavior that T036 tests — creating potential for duplicated verification logic within T012 itself."
+  },
+  {
+    "id": "G-03",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T039", "T040"],
+    "dimensions": ["description"],
+    "rationale": "T039 runs full test suite (agdt-test) and T040 runs targeted-checks.sh — both validate no regressions across all FRs. Different tooling but same validation goal (ensure nothing is broken). Single-dimension overlap (description/intent) caps at HIGH."
+  }
+]
+```
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.232/specs/1858-update-create-new-feature/plan.md

@@ -0,0 +1,320 @@
+# Implementation Plan: Update create-new-feature.sh for Nested Filesystem Layout
+
+## 1. Technical Context
+
+### Technology Stack
+
+- **Shell scripts**: `create-new-feature.sh` (Bash), `create-new-feature.ps1` (PowerShell)
+- **Python modules**: `agentic_devtools/cli/speckit/hierarchy.py` (schema/models), `agentic_devtools/cli/speckit/hierarchy_detector.py` (GitHub API detection)
+- **Data format**: YAML (`hierarchy.yml`) with JSON Schema validation
+- **Shared helpers**: `.specify/extensions/agdt-workflows/scripts/bash/common.sh` (`find_feature_dir_by_prefix`)
+- **CLI tooling**: `gh` CLI for GitHub API calls via `run_safe()`
+
+### Architecture Decisions
+
+- The hierarchy detector (`GitHubHierarchyDetector`) already exists with parent/child detection
+- `HierarchyNode`, `ChildEntry`, `HierarchyLevel` data models are defined and tested
+- `load_hierarchy()` / `save_hierarchy()` provide validated YAML I/O
+- `find_feature_dir_by_prefix` in `common.sh` currently does **top-level only** matching — must be updated for nested-aware resolution (NFR-002)
+
+## 2. Research Summary
+
+See [spec.md](spec.md) (Clarifications and requirements) for detailed analysis context. Key decisions:
+
+| Decision | Choice |
+|----------|--------|
+| Locking mechanism | `flock` on `.hierarchy.yml.lock` (5s timeout); `mkdir` fallback uses the same path as a lock directory; on release: `flock` path releases the lock by closing the file descriptor (the lock file itself persists and is **not** deleted); `mkdir` fallback removes the lock directory on release |
+| Detector invocation | Python subprocess with 10s timeout enforced in Python (no shell `timeout` dependency) |
+| Depth enforcement | Count path components from `specs/` root (max 3) |
+| Parent directory scan | `find` with `-not -type l` (no symlink following) |
+| Stub title format | `"Issue {N}"` when detector/CLI description unavailable; if the current detector fallback yields `"Issue #{N}"`, the wrapper/scripts must normalize it before emitting the final title |
+
+## 3. Design Overview
+
+### High-Level Flow
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│ create-new-feature.sh                                    │
+│                                                          │
+│  1. Parse args: --issue, --flat, --parent, description   │
+│  2. Validate --parent (positive int when no --flat)      │
+│  3. If --flat → flat creation (existing behavior)        │
+│  4. Invoke hierarchy detector (10s timeout)              │
+│  5. Resolve parent dir (recursive scan, no symlinks)     │
+│  6. Enforce max depth (3 levels)                         │
+│  7. Create child dir with spec.md + hierarchy.yml        │
+│  8. Update parent hierarchy.yml (under flock)            │
+│  9. Output PARENT_SPEC_DIR + HIERARCHY_LEVEL             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Key Functions to Add (Bash)
+
+| Function | Responsibility |
+|----------|----------------|
+| `invoke_hierarchy_detector()` | Call Python detector with timeout and parse a data-only line-oriented payload |
+| `find_parent_dir()` | Recursive scan of `specs/` for parent directory (no symlinks) |
+| `compute_nesting_depth()` | Count directory depth from `specs/` root |
+| `create_hierarchy_yml()` | Generate child's `hierarchy.yml` |
+| `update_parent_hierarchy_yml()` | Lock + read + append child + write parent `hierarchy.yml` |
+| `validate_parent_flag()` | Validate `--parent` is positive integer |
+
+### Updated `find_feature_dir_by_prefix` (common.sh)
+
+Must be updated to scan recursively (`specs/**/{prefix}` and `specs/**/{prefix}-*`) for NFR-002 compliance.
+
+## 4. Implementation Phases
+
+### Phase 1: CLI Argument Parsing & Validation (FR-006, FR-007)
+
+**Deliverables:**
+
+- Add `--flat` flag parsing to both scripts
+- Add `--parent N` option parsing to both scripts
+- Validate `--parent` is positive integer when `--flat` absent
+- Exit code 1 with `[specify]`-prefixed stderr diagnostic for invalid values
+- When `--flat` present, skip `--parent` validation entirely (FR-007 — `--parent` is ignored when `--flat` is set)
+- When `--issue` is absent (legacy auto-increment mode) **and `--flat` is also absent**: if `--parent` is
+  provided, exit code 1 with a `[specify]`-prefixed diagnostic (hierarchy nesting requires `--issue`;
+  per NFR-002, the legacy path must remain unchanged). This hard-fail does not apply when `--flat` is
+  present because `--parent` is already ignored in that branch.
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+- `.specify/extensions/agdt-workflows/scripts/powershell/create-new-feature.ps1`
+
+### Phase 2: Hierarchy Detector Integration (FR-001, NFR-001)
+
+**Deliverables:**
+
+- Add `invoke_hierarchy_detector()` function that calls the Python detector with a portable 10s timeout (enforced in Python wrapper/process control, not GNU `timeout`)
+- Parse output without a `jq` runtime dependency: have the Python wrapper (or a thin inline `python3 -c "..."` snippet)
+  emit a minimal data-only line-oriented payload that Bash reads with `read -r`/field splitting (for example,
+  tab-delimited or one-field-per-line output); do not `source`/`eval` detector output and do not introduce a `jq`
+  dependency
+- When `--parent` provided: ignore detector's parent, use only level + title
+- When detector fails/timeouts without `--parent`: fall back to flat creation with `[specify]`-prefixed warning to stderr
+- When detector fails/timeouts with `--parent`: continue nested with `HIERARCHY_LEVEL=null`
+- Emit stub title `"Issue {N}"` when neither detector nor description provides title; if the
+  detector's current internal fallback yields `"Issue #{N}"`, normalize it in the wrapper/scripts
+  before writing any final output so the emitted title always matches the spec
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+**New file (optional helper):**
+
+- A thin Python CLI wrapper: `agentic_devtools/cli/speckit/detect_parent_cli.py` — invoked by the shell script as `python -m agentic_devtools.cli.speckit.detect_parent_cli --issue N --repo owner/repo`
+- Resolve `owner/repo` inside `create-new-feature.sh` without adding a new user-facing flag: prefer
+  `gh repo view --json nameWithOwner` when available, otherwise parse the local git remote
+  (`origin`) URL; if neither strategy can resolve the repository, treat that the same as a
+  detector failure so the existing Phase 2 fallback path applies per NFR-001
+
+### Phase 3: Parent Directory Resolution (FR-002)
+
+**Deliverables:**
+
+- Implement recursive `specs/` scan for parent directory
+  - Match basename `== {parent_key}` or starts with `{parent_key}-`
+  - Real directories only (`-not -type l`)
+- Handle ambiguous matches (>1): exit code 1, `[specify]`-prefixed diagnostic to stderr
+- Handle missing parent: auto-create at correct depth
+  - Top-level (depth 1): `{key}-{slug}/` when the parent title can be resolved; otherwise `{key}/`
+  - Nested (depth 2+): `{key}/` (key-only)
+  - Parent title source for slugging (when depth 1): resolved parent title only
+    (for example detector/API output for the parent key); do not derive the parent
+    folder slug from the child's CLI description, and reserve the stub
+    `"Issue {N}"` for `hierarchy.yml` content when no parent title can be resolved
+  - Decide depth 1 vs depth 2+ by resolving whether the parent itself has a
+    parent (if yes, place parent under its own resolved parent path and use
+    key-only folder naming); when ancestry cannot be resolved (cyclic or invalid
+    chain), emit a `[specify]`-prefixed warning to stderr and fall back to
+    creating the missing parent at depth 1 under `specs/`
+  - If an ancestor in that chain is also missing, recursively materialize
+    missing ancestors bottom-up until an existing directory is found or
+    depth-1 is reached; use detector/description/stub title resolution per
+    created level
+  - Create with `spec.md` (from template or stub)
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+### Phase 4: Child Directory Creation (FR-003, FR-004)
+
+**Deliverables:**
+
+- Create `specs/{parent-dir}/{N}/` (issue-key-only naming for nested children)
+- Generate `spec.md` from template or empty stub
+- Generate `hierarchy.yml` with:
+  - `title`: from detector/description/stub
+  - `level`: from detector (authoritative) or depth-based inference
+  - `parent`: parent issue key as string
+  - `children`: empty list
+  - `processed_at`: null
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+### Phase 5: Parent hierarchy.yml Update with Locking (FR-005, NFR-003)
+
+**Deliverables:**
+
+- Implement cross-process advisory lock on `.hierarchy.yml.lock` located adjacent to the parent
+  `hierarchy.yml` being updated, using `flock` with portable fallback (`mkdir` lock dir) when
+  `flock` is unavailable
+- 5-second timeout for either lock strategy; exit code 1 with a `[specify]`-prefixed diagnostic to stderr (per NFR-004) if lock not acquired within the timeout
+- Fallback lock details: use the same path `.hierarchy.yml.lock` as the fallback lock directory
+  (consistent with FR-005; `flock` uses it as a file, `mkdir` uses it as a directory — same path,
+  different node type); on
+  successful acquisition ensure cleanup on process exit (including interrupted
+  exits), and do not auto-delete pre-existing lock dirs on timeout (treat as
+  active contention)
+- Cross-strategy interop: if the `flock` path finds `.hierarchy.yml.lock` already exists **as a
+  directory** (left by a prior `mkdir`-fallback run), `flock` cannot open a directory as a file
+  descriptor and must not immediately fail — instead, treat it as active lock contention: poll/retry
+  the acquisition attempt at short intervals until the 5-second timeout elapses, then exit with
+  code 1 and a `[specify]`-prefixed diagnostic; remove the directory only when you successfully
+  take ownership (i.e., the directory disappears between polls — do not forcefully delete it)
+- Under lock: read parent `hierarchy.yml`, or create a schema-valid file first if missing
+  - Populate at least `title`, `level`, and `children`, with `parent` / `processed_at` included as applicable for that directory
+  - Use the resolved parent title when available; otherwise set `title` to stub `"Issue {P}"`
+  - Derive `level` from detector output when available, otherwise from the parent's nesting depth so the file is valid before appending the child entry
+- Check idempotency: skip if child entry already present (match by key)
+- Append child entry with deterministic advisory ordering:
+  `{key: "N", title: "...", order: N}` where `N` is the child issue number
+- Write back the updated `hierarchy.yml` atomically (write to a temp file then rename); note that
+  the existing `save_hierarchy()` helper writes directly — implement atomic replace either by
+  extending `save_hierarchy()` to use `tempfile` + `os.replace()`, or by performing the
+  write-then-rename directly in the shell script/Python wrapper invoked under the held lock
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+### Phase 6: Depth Enforcement (FR-011)
+
+**Deliverables:**
+
+- Count nesting depth from `specs/` root before creating child
+- If depth would exceed 3: fall back to flat creation with `[specify]`-prefixed warning to stderr
+- Depth calculation: `specs/` = root, `specs/100-epic/` = depth 1, `specs/100-epic/200/` = depth 2, child at depth 3 is the max
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+### Phase 7: Output Augmentation (FR-008, FR-009)
+
+**Deliverables:**
+
+- JSON mode: add `PARENT_SPEC_DIR` and `HIERARCHY_LEVEL` fields
+- Human-readable mode: add `PARENT_SPEC_DIR:` and `HIERARCHY_LEVEL:` lines
+- Values: absolute path (same format as `SPEC_FILE`) or `null`; in human-readable
+  `KEY: value` output, represent null as literal `null` (not blank)
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/create-new-feature.sh`
+
+### Phase 8: Update `find_feature_dir_by_prefix` (NFR-002)
+
+**Deliverables:**
+
+- Update `common.sh` to scan recursively for spec directories
+- Match pattern: `specs/**/{prefix}` and `specs/**/{prefix}-*`
+- Maintain backward compatibility: top-level matches still work
+- Handle ambiguous matches (multiple at different depths): **fail hard** — exit code 1 with a
+  `[specify]`-prefixed error to stderr; as part of this phase, update the existing
+  `find_feature_dir_by_prefix` ambiguity path from its current `ERROR:`-prefixed message format to
+  the required `[specify]` prefix so recursive-scan failures match NFR-004. Emitting only a
+  warning would leave callers proceeding non-deterministically, risking the wrong spec directory
+  being selected
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/bash/common.sh`
+
+### Phase 9: PowerShell Parity (FR-010)
+
+**Deliverables:**
+
+- Port all Bash changes to PowerShell equivalents
+- `-Parent` parameter (positive integer, validated)
+- `-Flat` switch
+- Same detector invocation (Python subprocess, 10s timeout)
+- Same directory resolution, creation, locking (using `[System.IO.File]::Open` with exclusive
+  lock on `.hierarchy.yml.lock` located adjacent to the parent `hierarchy.yml` — the same lock
+  target as the Bash implementation — with a 5-second acquisition timeout matching
+  FR-005/NFR-003; exit code 1 with a `[specify]`-prefixed diagnostic to stderr if the lock
+  cannot be acquired within the timeout)
+- Same output augmentation: add `PARENT_SPEC_DIR` and `HIERARCHY_LEVEL` fields (JSON and human-readable); preserve the existing `HAS_GIT` field — output changes are strictly additive
+- Update `common.ps1` (`Get-FeatureDir` / `Get-FeaturePathsEnv`) to resolve nested spec directories by
+  numeric prefix, analogous to the updated `find_feature_dir_by_prefix` in Bash — so that `setup-plan.ps1`,
+  `update-agent-context.ps1`, and other callers can locate key-only nested directories
+- Update `Test-FeatureBranch` in `common.ps1` to accept issue-number prefixes of any length (not only 3-digit),
+  matching the Bash `common.sh` behavior — required so that `setup-plan.ps1`, `update-agent-context.ps1`,
+  and other callers that invoke `Test-FeatureBranch` can run on `1858-*`-style branches without failing early
+
+**Files modified:**
+
+- `.specify/extensions/agdt-workflows/scripts/powershell/create-new-feature.ps1`
+- `.specify/extensions/agdt-workflows/scripts/powershell/common.ps1`
+
+### Phase 10: Tests
+
+**Deliverables:**
+
+- Unit tests for new Python CLI wrapper (if created)
+- Integration tests (agdt-test/`agdt-test-pattern`-driven, executing scripts via `subprocess` in a temporary workspace) for:
+  - Nested creation with existing parent
+  - Nested creation with auto-created parent
+  - `--flat` override
+  - `--parent` explicit override
+  - Invalid `--parent` validation
+  - Detector timeout fallback
+  - Ambiguous parent directories
+  - Max depth enforcement
+  - Concurrent child creation (idempotency)
+  - JSON output fields
+- Update existing tests that depend on flat-only layout
+
+## 5. Risk Assessment
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| Detector Python dependency unavailable in some environments | Medium | Low | Graceful fallback to flat creation with clear warning |
+| `flock` not available on all platforms (macOS, Alpine) | Medium | Medium | Use `flock` with fallback to `mkdir`-based lock for portability |
+| Breaking existing CI pipelines that parse script output | High | Medium | New fields are additive only; existing fields unchanged |
+| Race condition in parent directory creation | Low | Low | Lock acquisition covers both read and write; idempotent design |
+| Deep nesting causes path-length issues on Windows | Low | Low | Max depth of 3 keeps paths short |
+
+## 6. Dependencies
+
+### External
+
+- `gh` CLI (for hierarchy detector API calls)
+- Python 3.x with `agentic_devtools` installed (for detector invocation)
+- `flock` command (Linux; optional — `mkdir`-based lock is the fallback when `flock` is unavailable,
+  e.g., macOS or Alpine)
+- No `yq` runtime dependency; perform YAML updates through Python (`load_hierarchy()` / `save_hierarchy()`) or an equivalent Python helper wrapper
+
+### Internal
+
+- `agentic_devtools/cli/speckit/hierarchy.py` — `HierarchyNode`, `ChildEntry`, `save_hierarchy`, `load_hierarchy`
+- `agentic_devtools/cli/speckit/hierarchy_detector.py` — `GitHubHierarchyDetector`, `get_hierarchy_detector`
+- `.specify/extensions/agdt-workflows/scripts/bash/common.sh` — `find_feature_dir_by_prefix`
+- Spec template at `.specify/presets/agdt-templates/templates/spec-template.md`
+
+### Sibling Issues
+
+- #1855 — `hierarchy.yml` schema (already implemented)
+- #1856 — Hierarchy detector (already implemented)
+- #1858 — This feature (current)
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

{agentic_devtools-0.2.231 → agentic_devtools-0.2.232}/specs/1858-update-create-new-feature/spec.md

@@ -466,5 +466,12 @@ uses the stub format `"Issue {N}"` to ensure it is never empty or null. (See FR-
 locking on a `.hierarchy.yml.lock` file adjacent to the target, with a 5-second timeout
 and platform-appropriate lock implementation. (See FR-005, NFR-003.)
 
+[RESOLVED]: When `--issue` / `-Issue` is omitted (legacy auto-increment mode) and `--parent`
+is provided without `--flat`, the script MUST exit with code 1 and emit a `[specify]`-prefixed
+diagnostic to stderr. Hierarchy nesting requires a known issue number (FR-002 parent
+directory scan, FR-005 `hierarchy.yml` writes are keyed off the issue number), and the legacy
+auto-increment path must remain unchanged per NFR-002. This rule does not apply when `--flat`
+is also present, because `--parent` is silently ignored in flat mode per FR-006/FR-007.
+
 ---
 *Generated by Copilot SDK (claude-opus-4.6)*