fix: address PR review feedback

Author: bma-d

scripts/run-smoke-automator.py

@@ -86,6 +86,10 @@ def __init__(self, *, root: Path, workspace: Path, project: Path, story_id: str)
         self.env = deterministic_smoke_env(project)
         self.helper = project / HELPER
 
+    def close(self) -> None:
+        return None
+
+
     def run(self, *, reset_artifacts: bool) -> dict[str, Any]:
         self._assert_prepared()
         if reset_artifacts:

scripts/run-smoke-dev-loop.py

@@ -86,6 +86,10 @@ def __init__(self, *, root: Path, workspace: Path, project: Path, story_ids: lis
         self.env = deterministic_smoke_env(project)
         self.helper = project / HELPER
 
+    def close(self) -> None:
+        return None
+
+
     def run(self, *, reset_artifacts: bool) -> dict[str, Any]:
         self._assert_prepared()
         if reset_artifacts:

scripts/run-smoke-finish-loop.py

@@ -214,11 +214,19 @@ def _persist_diagnostics(self, state: Path, commit_repo: Path) -> dict[str, obje
         state_dest.write_text(state.read_text(encoding="utf-8"), encoding="utf-8")
         log = self._git("log", "--oneline", "-5", cwd=commit_repo).stdout
         (dest / "git-log.txt").write_text(log, encoding="utf-8")
+        learnings = self.output / "learnings.md"
+        persisted_learnings = None
+        if learnings.exists():
+            persisted_learnings = dest / learnings.name
+            persisted_learnings.write_text(learnings.read_text(encoding="utf-8"), encoding="utf-8")
+            if "wrapup" in self.results:
+                self.results["wrapup"]["learnings"] = str(persisted_learnings)
         return {
             "folder": str(dest),
             "stateFile": str(state_dest),
             "gitLog": str(dest / "git-log.txt"),
             "gitLogRepo": self._repo_descriptor(commit_repo),
+            **({"learnings": str(persisted_learnings)} if persisted_learnings else {}),
         }
 
     def _ephemeral_project_descriptor(self) -> dict[str, object]:
@@ -322,7 +330,13 @@ def _call(self, fn, args: list[str]) -> tuple[int, str]:
 
     def _json(self, code: int, raw: str) -> dict[str, object]:
         self._expect(code in {0, 1}, f"unexpected exit {code}: {raw}")
-        return json.loads(raw)
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise FinishSmokeError(f"helper returned invalid JSON: {raw}") from exc
+        if not isinstance(payload, dict):
+            raise FinishSmokeError(f"helper returned non-object JSON: {raw}")
+        return payload
 
     def _expect(self, condition: bool, message: str) -> None:
         if not condition:

skills/bmad-story-automator/src/story_automator/commands/orchestrator_epic_agents.py

@@ -98,7 +98,7 @@ def check_blocking_action(args: list[str]) -> int:
         if norm is None:
             print_json({"ok": False, "error": "could_not_normalize_key", "input": args[0]})
             return 1
-        epic = norm.id.split(".", 1)[0]
+        epic = norm.id.rsplit(".", 1)[0]
         epic_file = find_epic_file(epic)
         if not epic_file:
             print_json({"ok": True, "blocking": True, "story": norm.id, "epic": epic, "dependents": [], "reason": "epic_file_not_found", "source": "unknown"})
@@ -310,7 +310,7 @@ def _story_key_rank(story: str, norm: StoryKey | None) -> int:
 
 def _line_references_story(project_root: str, epic: str, target: StoryKey, requested_story: str, line: str) -> bool:
     requested_full_key = _is_explicit_full_key(requested_story, target)
-    for match in re.finditer(r"\b(?:\d+\.\d+|\d+-\d+(?:-[\w]+)*|[A-Za-z][\w-]*(?:\.\d+|-\d+(?:-[\w]+)*))\b", line):
+    for match in re.finditer(r"\b(?:\d+(?:\.\d+)+|\d+-\d+(?:-[\w]+)*|[A-Za-z][\w-]*(?:\.\d+|-\d+(?:-[\w]+)*))\b", line):
         token = match.group(0)
         norm = normalize_story_key_for_epic(project_root, epic, token)
         if norm is not None and norm.id == target.id:

skills/bmad-story-automator/src/story_automator/core/epic_parser.py

@@ -9,8 +9,8 @@
 from .story_keys import normalize_story_key, normalize_story_key_for_epic
 
 
-STORY_HEADER_RE = re.compile(r"^###\s+(?:(?:Story\s+)?(\d+\.\d+)|Story\s+([^:]+)):\s*(.*)$", re.IGNORECASE)
-EPIC_HEADER_RE = re.compile(r"^##\s+Epic\s+([A-Za-z][\w-]*|\d+):\s*(.*)$", re.IGNORECASE)
+STORY_HEADER_RE = re.compile(r"^###\s+(?:(?:Story\s+)?(\d+(?:\.\d+)+)|Story\s+([^:]+)):\s*(.*)$", re.IGNORECASE)
+EPIC_HEADER_RE = re.compile(r"^##\s+Epic\s+([A-Za-z][\w-]*|\d+(?:\.\d+)*):\s*(.*)$", re.IGNORECASE)
 
 
 def parse_epic_file(epic_file: str | Path) -> dict[str, Any]:
@@ -74,7 +74,11 @@ def parse_story(epic_file: str | Path, story_id: str, rules_file: str | Path) ->
             story_key = _normalize_header_story(project_root, current_epic, raw_story.strip())
             if story_key is None:
                 continue
-            if target_id not in {raw_story.strip(), story_key.id, story_key.prefix, story_key.key}:
+            target_aliases = {raw_story.strip(), story_key.id, story_key.prefix, story_key.key}
+            title_slug = _slugify_title(raw_title)
+            if title_slug and not _is_explicit_header_story(raw_story.strip(), story_key.id):
+                target_aliases.add(f"{story_key.prefix}-{title_slug}")
+            if target_id not in target_aliases:
                 continue
             start_index = index
             target_id = story_key.id
@@ -170,7 +174,7 @@ def _normalize_header_story(project_root: str, current_epic: str, raw_story: str
     story_key = normalize_story_key_for_epic(project_root, current_epic, raw_story)
     if story_key is None:
         return None
-    if story_key.id.rsplit(".", 1)[0] != current_epic:
+    if story_key.id != current_epic and not story_key.id.startswith(f"{current_epic}."):
         return None
     return story_key
 
@@ -202,6 +206,8 @@ def parse_story_range(user_input: str, total: int, ids_csv: str = "") -> dict[st
                     end = id_index[end_raw]
                     low, high = sorted((start, end))
                     selected.update(range(low, high + 1))
+                else:
+                    raise ValueError(f"invalid_story_range:{part}")
             elif part.isdigit():
                 selected.add(int(part))
     indices = sorted(index for index in selected if 1 <= index <= total)
@@ -238,8 +244,7 @@ def _story_aliases(story: dict[str, str]) -> set[str]:
     if story_key:
         aliases.add(story_key)
     if not _is_explicit_header_story(header_story, story_id):
-        epic, _, story_num = story_id.rpartition(".")
-        prefix = f"{epic}-{story_num}"
+        prefix = story_id.replace(".", "-")
         aliases.add(prefix)
         title_slug = _slugify_title(story.get("title", ""))
         if title_slug:
@@ -250,16 +255,15 @@ def _story_aliases(story: dict[str, str]) -> set[str]:
 def _is_explicit_header_story(header_story: str, story_id: str) -> bool:
     if not header_story:
         return False
-    epic, _, story_num = story_id.rpartition(".")
-    return header_story not in {story_id, f"{epic}-{story_num}"}
+    return header_story not in {story_id, story_id.replace(".", "-")}
 
 
 def _slugify_title(title: str) -> str:
     return "-".join(part for part in re.split(r"[^A-Za-z0-9]+", title.lower()) if part)
 
 
-def _story_sort_key(value: str) -> tuple[int, int, str, int, str]:
+def _story_sort_key(value: str) -> tuple[int, tuple[int, ...], str, int, str]:
     epic, _, story_num = value.rpartition(".")
-    if epic.isdigit():
-        return (0, int(epic), "", int(story_num) if story_num.isdigit() else 0, value)
-    return (1, 0, epic, int(story_num) if story_num.isdigit() else 0, value)
+    if all(part.isdigit() for part in value.split(".")):
+        return (0, tuple(int(part) for part in value.split(".")), "", 0, value)
+    return (1, (), epic, int(story_num) if story_num.isdigit() else 0, value)

skills/bmad-story-automator/src/story_automator/core/story_keys.py

@@ -20,17 +20,17 @@ def sprint_status_file(project_root: str) -> str:
 
 
 def normalize_story_key(project_root: str, value: str) -> StoryKey | None:
-    if re.fullmatch(r"\d+\.\d+", value):
+    if re.fullmatch(r"\d+(?:\.\d+)+", value):
         story_id = value
         prefix = value.replace(".", "-")
         key = ""
-    elif re.fullmatch(r"\d+-\d+", value):
+    elif re.fullmatch(r"\d+(?:-\d+)+", value):
         prefix = value
         story_id = value.replace("-", ".")
         key = ""
-    elif re.fullmatch(r"\d+-\d+-.+", value):
+    elif re.fullmatch(r"\d+(?:-\d+)+-.+", value):
         key = value
-        prefix = "-".join(value.split("-", 2)[:2])
+        prefix = _numeric_full_key_prefix(value)
         story_id = prefix.replace("-", ".")
     elif re.fullmatch(r"[A-Za-z][\w-]*\.\d+", value):
         story_id = value
@@ -63,6 +63,11 @@ def normalize_story_key_for_epic(project_root: str, epic: str, value: str) -> St
             return None
         return norm
 
+    nested_numeric = _nested_numeric_story_for_epic(epic, value)
+    if nested_numeric is not None:
+        story_id, prefix, key = nested_numeric
+        return _complete_story_key(project_root, story_id, prefix, key)
+
     dotted = re.fullmatch(rf"{re.escape(epic)}\.(\d+)", value)
     if dotted:
         story_num = dotted.group(1)
@@ -139,6 +144,36 @@ def _status_keys(content: str) -> list[str]:
     return keys
 
 
+def _numeric_full_key_prefix(value: str) -> str:
+    parts = value.split("-")
+    if len(parts) >= 4 and all(part.isdigit() for part in parts[:3]):
+        nested_prefix = "-".join(parts[:3])
+        if not _numeric_title_segment(parts):
+            return nested_prefix
+    return "-".join(parts[:2])
+
+
+def _nested_numeric_story_for_epic(epic: str, value: str) -> tuple[str, str, str] | None:
+    if not all(part.isdigit() for part in epic.split(".")):
+        return None
+    epic_prefix = epic.replace(".", "-")
+    match = re.fullmatch(rf"{re.escape(epic_prefix)}-(\d+)(?:-.+)?", value)
+    if not match:
+        return None
+    parts = value.split("-")
+    if len(parts) >= 4 and _numeric_title_segment(parts):
+        return None
+    prefix = f"{epic_prefix}-{match.group(1)}"
+    key = value if value != prefix else ""
+    return f"{epic}.{match.group(1)}", prefix, key
+
+
+def _numeric_title_segment(parts: list[str]) -> bool:
+    if len(parts[2]) == 4:
+        return True
+    return len(parts[2]) == 2 and len(parts) >= 4 and parts[3] in {"release"}
+
+
 def _full_key_matches_story(project_root: str, key: str, story_id: str, *, allow_ambiguous_same_id: bool) -> bool:
     norm = normalize_story_key(project_root, key)
     if norm is not None:

skills/bmad-story-automator/src/story_automator/core/success_verifiers.py

@@ -289,7 +289,7 @@ def _epic_identifier(project_root: str, story_key: str) -> str:
         return story_key
     norm = normalize_story_key(project_root, story_key)
     if norm is not None:
-        return norm.id.split(".", 1)[0]
+        return norm.id.rsplit(".", 1)[0]
     if re.fullmatch(r"[A-Za-z][\w-]*", story_key) and sprint_status_epic(project_root, story_key)[0]:
         return story_key
     return ""

tests/test_epic_parser.py

@@ -4,7 +4,7 @@
 import unittest
 from pathlib import Path
 
-from story_automator.core.epic_parser import epic_complete, parse_epic_file, parse_story
+from story_automator.core.epic_parser import epic_complete, parse_epic_file, parse_story, parse_story_range
 
 
 class EpicParserTests(unittest.TestCase):
@@ -77,6 +77,19 @@ def test_parse_story_accepts_canonical_id_for_full_key_header(self) -> None:
         self.assertEqual(payload["storyId"], "multi-leg.3")
         self.assertEqual(payload["title"], "Old")
 
+    def test_parse_story_rejects_missing_explicit_full_key_sibling(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+## Epic 1.2: Nested Epic
+### Story 1-2-3-old: New
+Acceptance Criteria
+- Works
+""",
+            encoding="utf-8",
+        )
+        with self.assertRaisesRegex(ValueError, "story_not_found"):
+            parse_story(self.epic_file, "1-2-3-new", self.rules_file)
+
     def test_epic_complete_accepts_non_numeric_story_ids(self) -> None:
         self.epic_file.write_text(
             """# Epic Multi Leg
@@ -144,6 +157,87 @@ def test_epic_complete_sorts_numeric_epics_numerically(self) -> None:
         self.assertFalse(payload["epicComplete"])
         self.assertEqual(payload["maxEpicStory"], "10.1")
 
+    def test_parse_epic_file_accepts_three_level_numeric_story_ids(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+### 1.1.1: Nested
+""",
+            encoding="utf-8",
+        )
+        payload = parse_epic_file(self.epic_file)
+        self.assertTrue(payload["ok"])
+        self.assertEqual(payload["stories"][0]["storyId"], "1.1.1")
+        self.assertEqual(payload["stories"][0]["epicNum"], "1.1")
+        self.assertEqual(payload["stories"][0]["storyNum"], "1")
+
+    def test_parse_epic_file_accepts_nested_numeric_story_under_numeric_epic(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+## Epic 1.1: Nested Epic
+### 1.1.1: Nested
+""",
+            encoding="utf-8",
+        )
+        payload = parse_epic_file(self.epic_file)
+        self.assertTrue(payload["ok"])
+        self.assertEqual(payload["stories"][0]["storyId"], "1.1.1")
+        self.assertEqual(payload["stories"][0]["epicTitle"], "Nested Epic")
+
+    def test_epic_complete_sorts_nested_numeric_story_ids_numerically(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+### 1.9.1: Old
+### 1.10.1: New
+""",
+            encoding="utf-8",
+        )
+        payload = epic_complete(self.epic_file, "1.9.1")
+        self.assertTrue(payload["ok"])
+        self.assertFalse(payload["epicComplete"])
+        self.assertEqual(payload["maxEpicStory"], "1.10.1")
+
+    def test_nested_numeric_story_accepts_canonical_dashed_full_key_alias(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+## Epic 1.2: Nested Epic
+### 1.2.3: Nested
+Acceptance Criteria
+- Works
+""",
+            encoding="utf-8",
+        )
+        story = parse_story(self.epic_file, "1-2-3-nested", self.rules_file)
+        self.assertEqual(story["storyId"], "1.2.3")
+        complete = epic_complete(self.epic_file, "1-2-3-nested")
+        self.assertTrue(complete["ok"])
+        self.assertTrue(complete["epicComplete"])
+
+    def test_nested_numeric_story_accepts_multi_digit_dashed_full_key_under_epic(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+## Epic 1.2: Nested Epic
+### Story 1-2-21-nested: Nested
+""",
+            encoding="utf-8",
+        )
+        payload = parse_epic_file(self.epic_file)
+        self.assertEqual(payload["stories"][0]["storyId"], "1.2.21")
+
+    def test_nested_numeric_epic_preserves_title_like_numeric_segments(self) -> None:
+        self.epic_file.write_text(
+            """# Epic Numeric
+## Epic 1.2: Nested Epic
+### Story 1-2-2026-release: Release
+""",
+            encoding="utf-8",
+        )
+        payload = parse_epic_file(self.epic_file)
+        self.assertEqual(payload["stories"][0]["storyId"], "1.2")
+
+    def test_parse_story_range_rejects_unknown_hyphenated_story_id(self) -> None:
+        with self.assertRaisesRegex(ValueError, "invalid_story_range:multi-leg-3x"):
+            parse_story_range("multi-leg-3x", 2, "multi-leg-3,multi-leg-4")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_normalize_story_key.py

@@ -44,6 +44,52 @@ def test_numeric_full_key(self) -> None:
         self.assertEqual(result.prefix, "1-2")
         self.assertEqual(result.key, "1-2-user-authentication")
 
+    def test_numeric_full_key_with_numeric_title_segment(self) -> None:
+        result = normalize_story_key(str(self.project_root), "1-2-2026-release")
+        assert result is not None
+        self.assertEqual(result.id, "1.2")
+        self.assertEqual(result.prefix, "1-2")
+        self.assertEqual(result.key, "1-2-2026-release")
+
+    def test_numeric_full_key_with_two_digit_numeric_title_segment(self) -> None:
+        result = normalize_story_key(str(self.project_root), "1-2-42-release")
+        assert result is not None
+        self.assertEqual(result.id, "1.2")
+        self.assertEqual(result.prefix, "1-2")
+        self.assertEqual(result.key, "1-2-42-release")
+
+    def test_nested_numeric_full_key(self) -> None:
+        result = normalize_story_key(str(self.project_root), "1-2-3-nested")
+        assert result is not None
+        self.assertEqual(result.id, "1.2.3")
+        self.assertEqual(result.prefix, "1-2-3")
+        self.assertEqual(result.key, "1-2-3-nested")
+
+    def test_nested_numeric_full_key_with_multi_digit_story_number(self) -> None:
+        result = normalize_story_key(str(self.project_root), "1-2-10-nested")
+        assert result is not None
+        self.assertEqual(result.id, "1.2.10")
+        self.assertEqual(result.prefix, "1-2-10")
+        self.assertEqual(result.key, "1-2-10-nested")
+
+    def test_nested_numeric_full_key_above_twenty(self) -> None:
+        result = normalize_story_key(str(self.project_root), "1-2-21-nested")
+        assert result is not None
+        self.assertEqual(result.id, "1.2.21")
+        self.assertEqual(result.prefix, "1-2-21")
+        self.assertEqual(result.key, "1-2-21-nested")
+
+    def test_epic_hint_preserves_numeric_title_segments(self) -> None:
+        year = normalize_story_key_for_epic(str(self.project_root), "1.2", "1-2-2026-release")
+        assert year is not None
+        self.assertEqual(year.id, "1.2")
+        self.assertEqual(year.prefix, "1-2")
+
+        release = normalize_story_key_for_epic(str(self.project_root), "1.2", "1-2-42-release")
+        assert release is not None
+        self.assertEqual(release.id, "1.2")
+        self.assertEqual(release.prefix, "1-2")
+
     # --- Non-numeric epic keys (the regression this patch restores) ---
 
     def test_non_numeric_dotted_id(self) -> None: