methodology-framework 0.1.0__py3-none-any.whl

methodology_framework/sync_stories_to_jira.py

@@ -0,0 +1,1087 @@
+#!/usr/bin/env python3
+"""Sync story .md files from docs/stories/ to Jira tickets.
+
+One-way sync: repo -> Jira. Creates or updates Jira tickets based on
+story frontmatter and body content. Writes back assigned jira_key to
+the story file's frontmatter on first sync.
+
+Usage:
+    python scripts/sync_stories_to_jira.py --dry-run --since-ref HEAD~1
+    python scripts/sync_stories_to_jira.py --since-ref HEAD~3
+    python scripts/sync_stories_to_jira.py --all
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import frontmatter
+import requests
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+STORIES_DIR = REPO_ROOT / "docs" / "stories"
+GITHUB_REPO_URL = "https://github.com/whiteout59/centralized-pipeline-ui"
+
+# Jira custom field IDs (discovered from the SCRUM project)
+CF_REQUIREMENT_IDS = "customfield_10141"
+CF_STORY_FILE = "customfield_10073"
+CF_AGENT_ESTIMATE = "customfield_10074"
+
+# Jira issue link type for "Blocks" (inward = "is blocked by")
+LINK_TYPE_BLOCKS = "10000"
+
+# Jira transition IDs (from the SCRUM workflow)
+TRANSITION_TO_DO = "11"
+TRANSITION_READY_FOR_AGENT = "2"
+TRANSITION_BLOCKED = "3"
+TRANSITION_WONT_DO = "4"
+TRANSITION_WAITING = "5"
+
+# Jira status IDs
+STATUS_DONE = "10003"
+STATUS_WONT_DO = "10104"
+STATUS_WAITING = "10137"
+STATUS_BLOCKED = "10103"
+
+# Statuses the sync must NOT auto-transition out of. Done / Won't Do are
+# truly terminal. Blocked is non-terminal in the workflow sense but is
+# the "human attention required" lane (ambiguity escalations, file-overlap
+# halts, security review pending, etc.) — auto-resolving Blocked back to
+# Ready would defeat the lifecycle-status-hygiene design that distinguishes
+# Waiting (dep-block, safe to auto-resolve) from Blocked (manual gate).
+PROTECTED_STATUSES = {STATUS_DONE, STATUS_WONT_DO, STATUS_BLOCKED}
+TERMINAL_STATUSES = PROTECTED_STATUSES  # backward-compat alias
+
+# Jira issue type IDs
+ISSUE_TYPE_STORY = "10004"
+ISSUE_TYPE_SUBTASK = "10002"
+
+PROJECT_KEY = "SCRUM"
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StoryMeta:
+    """Parsed frontmatter + rendered body of a story .md file."""
+
+    slug: str
+    path: Path
+    title: str
+    story_type: str
+    labels: list[str]
+    requirements: list[str]
+    depends_on: list[str]
+    parent: str | None
+    tasks: list[str]
+    estimate: str
+    jira_key: str | None
+    body: str
+    is_canceled: bool = False
+
+
+@dataclass
+class SyncAction:
+    """A planned create/update/transition operation."""
+
+    action: str  # "create", "update", "transition", "link", "cancel"
+    slug: str
+    jira_key: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_story_file(path: Path) -> StoryMeta:
+    """Parse a story .md file and return structured metadata."""
+    post = frontmatter.load(str(path))
+    meta = post.metadata
+
+    slug = path.stem
+    is_canceled = slug.startswith("_")
+    if is_canceled:
+        slug = slug.lstrip("_")
+
+    title_raw = meta.get("title", "")
+    if not title_raw:
+        raise ValueError(f"Missing required 'title' in frontmatter: {path}")
+    title = str(title_raw)
+
+    story_type = str(meta.get("type", "task"))
+
+    labels_raw = meta.get("labels", [])
+    labels: list[str] = (
+        [str(x) for x in labels_raw] if isinstance(labels_raw, list) else [str(labels_raw)]
+    )
+
+    requirements_raw = meta.get("requirements", [])
+    requirements: list[str] = (
+        [str(x) for x in requirements_raw]
+        if isinstance(requirements_raw, list)
+        else [str(requirements_raw)]
+    )
+
+    depends_on_raw = meta.get("depends_on", [])
+    depends_on: list[str] = (
+        [str(x) for x in depends_on_raw]
+        if isinstance(depends_on_raw, list)
+        else [str(depends_on_raw)]
+    )
+
+    parent_raw = meta.get("parent")
+    parent: str | None = None
+    if parent_raw is not None:
+        parent_str = str(parent_raw)
+        if parent_str.lower() != "null" and parent_str != "":
+            parent = parent_str
+
+    tasks_raw = meta.get("tasks", [])
+    tasks: list[str] = (
+        [str(x) for x in tasks_raw] if isinstance(tasks_raw, list) else [str(tasks_raw)]
+    )
+
+    estimate = str(meta.get("estimate", "0h"))
+    jira_key_raw = meta.get("jira_key")
+    jira_key: str | None = None
+    if jira_key_raw is not None and str(jira_key_raw).lower() != "null":
+        jira_key = str(jira_key_raw)
+
+    body = render_body(post.content)
+
+    return StoryMeta(
+        slug=slug,
+        path=path,
+        title=title,
+        story_type=story_type,
+        labels=labels,
+        requirements=requirements,
+        depends_on=depends_on,
+        parent=parent,
+        tasks=tasks,
+        estimate=estimate,
+        jira_key=jira_key,
+        body=body,
+        is_canceled=is_canceled,
+    )
+
+
+def render_body(content: str) -> str:
+    """Render the story body for Jira.
+
+    - Strips HTML comments (<!-- ... -->)
+    - Converts AC bullets to markdown checkboxes
+    """
+    # Strip HTML comments (single-line and multi-line)
+    rendered = re.sub(r"<!--.*?-->", "", content, flags=re.DOTALL)
+
+    # Convert AC section bullets to checkboxes
+    rendered = _convert_ac_to_checkboxes(rendered)
+
+    # Clean up excessive blank lines
+    rendered = re.sub(r"\n{3,}", "\n\n", rendered)
+
+    return rendered.strip()
+
+
+def _convert_ac_to_checkboxes(content: str) -> str:
+    """Convert bullets under '## Acceptance criteria' to markdown checkboxes."""
+    lines = content.split("\n")
+    result: list[str] = []
+    in_ac_section = False
+
+    for line in lines:
+        stripped = line.strip()
+
+        # Detect AC section start
+        if re.match(r"^##\s+Acceptance\s+criteria", stripped, re.IGNORECASE):
+            in_ac_section = True
+            result.append(line)
+            continue
+
+        # Detect next section (exits AC)
+        if in_ac_section and re.match(r"^##\s+", stripped):
+            in_ac_section = False
+
+        # Convert bullets to checkboxes inside AC section
+        if in_ac_section and re.match(r"^-\s+(?!\[[ x]\])", stripped):
+            line = re.sub(r"^(\s*)-\s+", r"\1- [ ] ", line)
+
+        result.append(line)
+
+    return "\n".join(result)
+
+
+def parse_estimate_hours(estimate: str) -> float | None:
+    """Parse an estimate string like '8h' or '24h' into a float."""
+    match = re.match(r"^(\d+(?:\.\d+)?)\s*h$", estimate.strip(), re.IGNORECASE)
+    if match:
+        return float(match.group(1))
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+
+def get_changed_story_files(since_ref: str) -> list[Path]:
+    """Get story .md files changed since the given git ref."""
+    result = subprocess.run(
+        ["git", "diff", "--name-only", "--diff-filter=ACDMR", since_ref, "HEAD"],
+        capture_output=True,
+        text=True,
+        cwd=str(REPO_ROOT),
+        check=True,
+    )
+    changed: list[Path] = []
+    for line in result.stdout.strip().split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("docs/stories/") and line.endswith(".md"):
+            full_path = REPO_ROOT / line
+            # File might have been deleted (rename to _ prefix)
+            if full_path.exists() or line.split("/")[-1].startswith("_"):
+                changed.append(full_path)
+    return changed
+
+
+def get_all_story_files() -> list[Path]:
+    """Get all story .md files under docs/stories/."""
+    files: list[Path] = []
+    for md_file in sorted(STORIES_DIR.rglob("*.md")):
+        if md_file.name == "README.md":
+            continue
+        files.append(md_file)
+    return files
+
+
+def get_renamed_files(since_ref: str) -> dict[str, str]:
+    """Detect renames (old path -> new path) for underscore-prefix detection."""
+    result = subprocess.run(
+        ["git", "diff", "--name-status", "--diff-filter=R", "-M", since_ref, "HEAD"],
+        capture_output=True,
+        text=True,
+        cwd=str(REPO_ROOT),
+        check=True,
+    )
+    renames: dict[str, str] = {}
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) >= 3 and parts[0].startswith("R"):
+            old_path = parts[1]
+            new_path = parts[2]
+            if old_path.startswith("docs/stories/") and old_path.endswith(".md"):
+                renames[old_path] = new_path
+    return renames
+
+
+# ---------------------------------------------------------------------------
+# Jira API client
+# ---------------------------------------------------------------------------
+
+
+class JiraClient:
+    """Thin wrapper around the Jira REST API v3."""
+
+    def __init__(
+        self,
+        base_url: str,
+        email: str,
+        api_token: str,
+        project_key: str = PROJECT_KEY,
+        dry_run: bool = False,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.project_key = project_key
+        self.dry_run = dry_run
+        self.session = requests.Session()
+        self.session.auth = (email, api_token)
+        self.session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/rest/api/3{path}"
+
+    def _get(self, path: str, params: dict[str, str] | None = None) -> dict[str, Any]:
+        resp = self.session.get(self._url(path), params=params)
+        if not resp.ok:
+            logger.error("Jira %s %s returned %d: %s", "GET", path, resp.status_code, resp.text)
+        resp.raise_for_status()
+        data: dict[str, Any] = resp.json()
+        return data
+
+    def _post(self, path: str, json_data: dict[str, Any]) -> dict[str, Any]:
+        if self.dry_run:
+            logger.info("[DRY RUN] POST %s: %s", path, json_data)
+            return {}
+        resp = self.session.post(self._url(path), json=json_data)
+        if not resp.ok:
+            logger.error(
+                "Jira %s %s returned %d: %s\nRequest payload: %s",
+                "POST",
+                path,
+                resp.status_code,
+                resp.text,
+                json_data,
+            )
+        resp.raise_for_status()
+        if resp.content:
+            data: dict[str, Any] = resp.json()
+            return data
+        return {}
+
+    def _put(self, path: str, json_data: dict[str, Any]) -> dict[str, Any]:
+        if self.dry_run:
+            logger.info("[DRY RUN] PUT %s: %s", path, json_data)
+            return {}
+        resp = self.session.put(self._url(path), json=json_data)
+        resp.raise_for_status()
+        if resp.content:
+            data: dict[str, Any] = resp.json()
+            return data
+        return {}
+
+    def create_issue(self, fields: dict[str, Any]) -> dict[str, Any]:
+        """Create a new Jira issue. Returns the created issue data."""
+        payload: dict[str, Any] = {"fields": fields}
+        return self._post("/issue", payload)
+
+    def update_issue(self, key: str, fields: dict[str, Any]) -> None:
+        """Update an existing Jira issue's fields."""
+        payload: dict[str, Any] = {"fields": fields}
+        self._put(f"/issue/{key}", payload)
+
+    def transition_issue(self, key: str, transition_id: str) -> None:
+        """Transition an issue to a new status."""
+        payload: dict[str, Any] = {"transition": {"id": transition_id}}
+        self._post(f"/issue/{key}/transitions", payload)
+
+    def add_comment(self, key: str, body: str) -> None:
+        """Add a comment to an issue."""
+        payload: dict[str, Any] = {
+            "body": {
+                "version": 1,
+                "type": "doc",
+                "content": [
+                    {
+                        "type": "paragraph",
+                        "content": [{"type": "text", "text": body}],
+                    }
+                ],
+            }
+        }
+        self._post(f"/issue/{key}/comment", payload)
+
+    def create_issue_link(
+        self,
+        inward_key: str,
+        outward_key: str,
+        link_type_id: str = LINK_TYPE_BLOCKS,
+    ) -> None:
+        """Create an issue link (inward 'is blocked by' outward)."""
+        payload: dict[str, Any] = {
+            "type": {"id": link_type_id},
+            "inwardIssue": {"key": inward_key},
+            "outwardIssue": {"key": outward_key},
+        }
+        self._post("/issueLink", payload)
+
+    def get_issue(self, key: str) -> dict[str, Any]:
+        """Get full issue data."""
+        return self._get(f"/issue/{key}")
+
+    def get_issue_status(self, key: str) -> str:
+        """Get the status ID of an issue."""
+        issue = self._get(f"/issue/{key}", params={"fields": "status"})
+        return str(issue["fields"]["status"]["id"])
+
+    def get_existing_links(self, key: str) -> list[dict[str, Any]]:
+        """Get existing issue links for an issue."""
+        issue = self._get(f"/issue/{key}", params={"fields": "issuelinks"})
+        return list(issue["fields"].get("issuelinks", []))
+
+    def get_transitions(self, key: str) -> list[dict[str, Any]]:
+        """Get available transitions for an issue."""
+        data = self._get(f"/issue/{key}/transitions")
+        return list(data.get("transitions", []))
+
+    def search_by_story_file_url(self, url: str) -> str | None:
+        """Search for an existing issue by its Story file URL custom field.
+
+        Returns the issue key if found, None otherwise. Used to dedupe
+        against tickets created manually before the sync existed.
+        """
+        if self.dry_run:
+            logger.info("[DRY RUN] Would search JQL: %s ~ %r", CF_STORY_FILE, url)
+            return None
+        jql = f'{CF_STORY_FILE} = "{url}" AND project = {self.project_key}'
+        # Atlassian deprecated /rest/api/3/search (GET) — returns 410 Gone after May 2025.
+        # Replacement: /rest/api/3/search/jql (POST with JSON body).
+        # Docs: https://developer.atlassian.com/cloud/jira/platform/changelog/
+        data = self._post("/search/jql", {"jql": jql, "fields": ["key"], "maxResults": 1})
+        issues: list[dict[str, Any]] = data.get("issues", [])
+        if issues:
+            found_key = str(issues[0]["key"])
+            logger.info(
+                "Found existing ticket %s for story file URL %s",
+                found_key,
+                url,
+            )
+            return found_key
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Sync logic
+# ---------------------------------------------------------------------------
+
+
+def build_story_file_url(story: StoryMeta) -> str:
+    """Build the GitHub URL for a story file."""
+    rel_path = story.path.relative_to(REPO_ROOT)
+    return f"{GITHUB_REPO_URL}/blob/main/{rel_path}"
+
+
+def derive_phase(story: StoryMeta) -> str | None:
+    """Derive the phase from the story file's directory path."""
+    rel = story.path.relative_to(STORIES_DIR)
+    parts = rel.parts
+    if parts:
+        return parts[0]  # e.g. "phase1", "phase2"
+    return None
+
+
+def build_jira_fields(
+    story: StoryMeta,
+    all_stories: dict[str, StoryMeta] | None = None,
+) -> dict[str, Any]:
+    """Build the Jira fields dict from a StoryMeta."""
+    # Determine issue type
+    is_subtask = story.parent is not None
+    issue_type_id = ISSUE_TYPE_SUBTASK if is_subtask else ISSUE_TYPE_STORY
+
+    # Parse estimate
+    estimate_hours = parse_estimate_hours(story.estimate)
+
+    # Build labels: include story labels + phase label
+    jira_labels = list(story.labels)
+    phase = derive_phase(story)
+    if phase and phase not in jira_labels:
+        jira_labels.append(phase)
+
+    story_file_url = build_story_file_url(story)
+    # Belt-and-suspenders: strip leading/trailing underscores from the URL.
+    # Investigation (SCRUM-26): the '__...__' wrapping reported in the first
+    # backfill run was traced to a GH Actions log rendering artifact — the
+    # Python dict repr logged by _post() was displayed in a markdown-aware
+    # context (Actions log viewer or the Jira ticket where it was pasted),
+    # causing surrounding text to appear italic-wrapped.  No code path in
+    # build_story_file_url() or build_jira_fields() adds underscores; the
+    # value sent to Jira was always clean.  The strip is kept as defense
+    # against any future upstream change that might introduce markers.
+    story_file_url = story_file_url.strip("_")
+
+    fields: dict[str, Any] = {
+        "project": {"key": PROJECT_KEY},
+        "summary": story.title,
+        "description": _text_to_adf(story.body),
+        "issuetype": {"id": issue_type_id},
+        "labels": jira_labels,
+        CF_REQUIREMENT_IDS: ", ".join(story.requirements) if story.requirements else None,
+        CF_STORY_FILE: story_file_url,
+    }
+
+    if estimate_hours is not None:
+        fields[CF_AGENT_ESTIMATE] = estimate_hours
+
+    # Include parent reference at create time for sub-tasks
+    if is_subtask and story.parent and all_stories is not None:
+        parent_key = resolve_slug_to_key(story.parent, all_stories)
+        if parent_key:
+            fields["parent"] = {"key": parent_key}
+
+    return fields
+
+
+def _text_to_adf(text: str) -> dict[str, Any]:
+    """Convert plain markdown text to Atlassian Document Format.
+
+    Uses a simple paragraph-per-block approach. Jira renders markdown
+    within ADF text nodes for basic formatting.
+    """
+    paragraphs: list[dict[str, Any]] = []
+    for block in text.split("\n\n"):
+        block = block.strip()
+        if not block:
+            continue
+        paragraphs.append(
+            {
+                "type": "paragraph",
+                "content": [{"type": "text", "text": block}],
+            }
+        )
+
+    if not paragraphs:
+        paragraphs.append(
+            {
+                "type": "paragraph",
+                "content": [{"type": "text", "text": " "}],
+            }
+        )
+
+    return {
+        "version": 1,
+        "type": "doc",
+        "content": paragraphs,
+    }
+
+
+def resolve_slug_to_key(slug: str, all_stories: dict[str, StoryMeta]) -> str | None:
+    """Resolve a story slug to its jira_key (if known)."""
+    story = all_stories.get(slug)
+    if story and story.jira_key:
+        return story.jira_key
+    return None
+
+
+def determine_transition(
+    story: StoryMeta,
+    all_stories: dict[str, StoryMeta],
+    client: JiraClient | None,
+) -> str | None:
+    """Determine the target transition for a story.
+
+    Returns the transition ID based on depends_on resolution and manual-gate,
+    or None if the ticket is already in a terminal state (DONE / Won't Do).
+    """
+    # Terminal-state guard: never re-transition a ticket that is already
+    # in DONE or WON'T DO.
+    if story.jira_key and client:
+        if client.dry_run:
+            logger.info(
+                "[DRY RUN] Would check terminal status for %s (%s)",
+                story.jira_key,
+                story.slug,
+            )
+        else:
+            current_status = client.get_issue_status(story.jira_key)
+            if current_status in PROTECTED_STATUSES:
+                status_name = {
+                    STATUS_DONE: "DONE",
+                    STATUS_WONT_DO: "WON'T DO",
+                    STATUS_BLOCKED: "BLOCKED",
+                }.get(current_status, current_status)
+                logger.info(
+                    "Skipping transition for %s — current status is "
+                    "protected (%s); only human action can move it.",
+                    story.jira_key,
+                    status_name,
+                )
+                return None
+
+    has_manual_gate = "manual-gate" in story.labels
+
+    # If manual-gate, land in Backlog (To Do)
+    if has_manual_gate:
+        return TRANSITION_TO_DO
+
+    # Check depends_on resolution
+    if story.depends_on:
+        all_resolved = True
+        for dep_slug in story.depends_on:
+            dep_key = resolve_slug_to_key(dep_slug, all_stories)
+            if not dep_key:
+                all_resolved = False
+                break
+            if client and not client.dry_run:
+                dep_status = client.get_issue_status(dep_key)
+                if dep_status != STATUS_DONE:
+                    all_resolved = False
+                    break
+            else:
+                # In dry-run, assume not resolved unless we can check
+                all_resolved = False
+                break
+
+        if not all_resolved:
+            return TRANSITION_WAITING
+
+    return TRANSITION_READY_FOR_AGENT
+
+
+def write_jira_key_to_frontmatter(path: Path, jira_key: str) -> None:
+    """Write the jira_key back to the story file's frontmatter."""
+    post = frontmatter.load(str(path))
+    post.metadata["jira_key"] = jira_key
+    frontmatter.dump(post, str(path))
+
+
+def sync_story(
+    story: StoryMeta,
+    all_stories: dict[str, StoryMeta],
+    client: JiraClient,
+    actions: list[SyncAction],
+) -> str | None:
+    """Sync a single story to Jira. Returns the jira_key if created/updated."""
+    # Handle canceled stories (underscore-prefix rename)
+    if story.is_canceled:
+        if story.jira_key:
+            actions.append(
+                SyncAction(
+                    action="cancel",
+                    slug=story.slug,
+                    jira_key=story.jira_key,
+                    details={"transition": "Won't Do"},
+                )
+            )
+            if not client.dry_run:
+                client.transition_issue(story.jira_key, TRANSITION_WONT_DO)
+                client.add_comment(
+                    story.jira_key,
+                    "Story canceled: file renamed with underscore prefix. "
+                    "See git history for details.",
+                )
+            return story.jira_key
+        return None
+
+    fields = build_jira_fields(story, all_stories)
+
+    if story.jira_key:
+        # Update existing ticket
+        update_fields = {k: v for k, v in fields.items() if k != "project" and k != "issuetype"}
+        actions.append(
+            SyncAction(
+                action="update",
+                slug=story.slug,
+                jira_key=story.jira_key,
+                details={"fields": update_fields},
+            )
+        )
+        if not client.dry_run:
+            try:
+                client.update_issue(story.jira_key, update_fields)
+            except requests.HTTPError as exc:
+                # Stale-or-inaccessible-ticket guard: under --all sync mode the
+                # script walks every story file, and any story whose jira_key
+                # frontmatter references a ticket the current sync auth context
+                # cannot edit (deleted, archived, or permission-scoped out)
+                # would otherwise halt the entire sync run. Log loud, record a
+                # skip action, and continue with remaining stories. Operator
+                # investigates the named key separately — either restore
+                # permissions, rotate auth, or clear the stale frontmatter.
+                if exc.response is not None and exc.response.status_code == 404:
+                    logger.warning(
+                        "Skipping update for %s — Jira returned 404. The "
+                        "issue is either deleted/archived or the sync auth "
+                        "context (JIRA_USER_EMAIL) lacks edit permission on "
+                        "it. Continuing with remaining stories. Action: "
+                        "verify the issue exists and the sync user has "
+                        "EDIT_ISSUES permission, OR clear the jira_key "
+                        "frontmatter on the story file.",
+                        story.jira_key,
+                    )
+                    actions.append(
+                        SyncAction(
+                            action="update_skipped",
+                            slug=story.slug,
+                            jira_key=story.jira_key,
+                            details={
+                                "reason": "http_404_not_accessible",
+                                "remediation": "verify_permissions_or_clear_frontmatter",
+                            },
+                        )
+                    )
+                    # Don't attempt the transition either — same auth issue
+                    # would just re-trip. Return the (stale) key so caller
+                    # state stays consistent.
+                    return story.jira_key
+                raise
+
+        # Re-evaluate transition
+        transition_id = determine_transition(story, all_stories, client)
+        if transition_id is None:
+            actions.append(
+                SyncAction(
+                    action="transition_skipped",
+                    slug=story.slug,
+                    jira_key=story.jira_key,
+                    details={"reason": "terminal_state"},
+                )
+            )
+        else:
+            actions.append(
+                SyncAction(
+                    action="transition",
+                    slug=story.slug,
+                    jira_key=story.jira_key,
+                    details={"transition_id": transition_id},
+                )
+            )
+            if not client.dry_run:
+                client.transition_issue(story.jira_key, transition_id)
+
+        return story.jira_key
+    else:
+        # Before creating, check if a ticket already exists (dedupe)
+        story_file_url = build_story_file_url(story)
+        existing_key = client.search_by_story_file_url(story_file_url)
+        if existing_key:
+            logger.info(
+                "Dedupe: found existing ticket %s for %s via JQL lookup",
+                existing_key,
+                story.slug,
+            )
+            story.jira_key = existing_key
+            write_jira_key_to_frontmatter(story.path, existing_key)
+            # Treat as update from here on
+            update_fields = {
+                k: v for k, v in fields.items() if k != "project" and k != "issuetype"
+            }
+            actions.append(
+                SyncAction(
+                    action="update",
+                    slug=story.slug,
+                    jira_key=existing_key,
+                    details={"fields": update_fields, "dedupe": True},
+                )
+            )
+            if not client.dry_run:
+                client.update_issue(existing_key, update_fields)
+                transition_id = determine_transition(story, all_stories, client)
+                if transition_id is None:
+                    actions.append(
+                        SyncAction(
+                            action="transition_skipped",
+                            slug=story.slug,
+                            jira_key=existing_key,
+                            details={"reason": "terminal_state"},
+                        )
+                    )
+                else:
+                    actions.append(
+                        SyncAction(
+                            action="transition",
+                            slug=story.slug,
+                            jira_key=existing_key,
+                            details={"transition_id": transition_id},
+                        )
+                    )
+                    client.transition_issue(existing_key, transition_id)
+            return existing_key
+
+        # Create new ticket
+        actions.append(
+            SyncAction(
+                action="create",
+                slug=story.slug,
+                details={"fields": fields},
+            )
+        )
+        jira_key: str | None = None
+        if not client.dry_run:
+            result = client.create_issue(fields)
+            jira_key = result.get("key")
+            if jira_key:
+                story.jira_key = jira_key
+                # Propagate the freshly-assigned key into all_stories so any
+                # later-processed child story whose parent is THIS story can
+                # resolve the parent reference via resolve_slug_to_key().
+                # Without this, target_stories and all_stories hold different
+                # StoryMeta instances (target_stories is re-parsed from disk
+                # in main()), so the mutation on `story.jira_key` above does
+                # not reach the dict the child lookup consults — and sub-task
+                # creation 400s with "parent issue key or id not specified."
+                all_stories[story.slug] = story
+                # Write key back to frontmatter
+                write_jira_key_to_frontmatter(story.path, jira_key)
+                logger.info("Created %s for %s", jira_key, story.slug)
+        else:
+            jira_key = f"DRY-RUN-{story.slug}"
+            logger.info("[DRY RUN] Would create ticket for %s", story.slug)
+
+        # Transition the new ticket
+        if jira_key and not client.dry_run:
+            transition_id = determine_transition(story, all_stories, client)
+            if transition_id is None:
+                actions.append(
+                    SyncAction(
+                        action="transition_skipped",
+                        slug=story.slug,
+                        jira_key=jira_key,
+                        details={"reason": "terminal_state"},
+                    )
+                )
+            else:
+                actions.append(
+                    SyncAction(
+                        action="transition",
+                        slug=story.slug,
+                        jira_key=jira_key,
+                        details={"transition_id": transition_id},
+                    )
+                )
+                client.transition_issue(jira_key, transition_id)
+
+        # Create depends_on links
+        if story.depends_on and jira_key:
+            for dep_slug in story.depends_on:
+                dep_key = resolve_slug_to_key(dep_slug, all_stories)
+                if dep_key:
+                    actions.append(
+                        SyncAction(
+                            action="link",
+                            slug=story.slug,
+                            jira_key=jira_key,
+                            details={
+                                "link_type": "is blocked by",
+                                "target_key": dep_key,
+                            },
+                        )
+                    )
+                    if not client.dry_run:
+                        client.create_issue_link(jira_key, dep_key)
+
+        return jira_key
+
+
+def sort_stories_for_processing(stories: list[StoryMeta]) -> list[StoryMeta]:
+    """Sort stories so parents are processed before their children.
+
+    Returns a new list with parent stories (parent is None) first,
+    then children grouped by parent slug. Within each group the
+    original relative order is preserved.
+    """
+    parents: list[StoryMeta] = []
+    children: list[StoryMeta] = []
+    for story in stories:
+        if story.parent is None:
+            parents.append(story)
+        else:
+            children.append(story)
+    return parents + children
+
+
+def load_all_stories() -> dict[str, StoryMeta]:
+    """Load all story files and return a slug -> StoryMeta mapping."""
+    stories: dict[str, StoryMeta] = {}
+    for path in get_all_story_files():
+        try:
+            story = parse_story_file(path)
+            # Use the non-canceled slug for lookup
+            slug = story.slug
+            stories[slug] = story
+        except Exception:
+            logger.warning("Failed to parse story file: %s", path, exc_info=True)
+    return stories
+
+
+def print_actions(actions: list[SyncAction]) -> None:
+    """Print planned sync actions in a human-readable format."""
+    if not actions:
+        print("No sync actions to perform.")
+        return
+
+    print(f"\n{'=' * 60}")
+    print(f"Sync plan: {len(actions)} action(s)")
+    print(f"{'=' * 60}\n")
+
+    for i, action in enumerate(actions, 1):
+        print(f"  [{i}] {action.action.upper()}: {action.slug}")
+        if action.jira_key:
+            print(f"      Jira key: {action.jira_key}")
+        for k, v in action.details.items():
+            if k == "fields":
+                print(f"      Fields: {list(v.keys())}")
+            else:
+                print(f"      {k}: {v}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Sync story .md files to Jira tickets.")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print planned actions without making Jira API calls.",
+    )
+    parser.add_argument(
+        "--since-ref",
+        type=str,
+        help="Git ref to diff against (e.g. HEAD~1, main~3).",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Sync all story files, not just changed ones.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging.",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s: %(message)s",
+    )
+
+    if not args.all and not args.since_ref:
+        parser.error("Either --all or --since-ref is required.")
+
+    # Load Jira credentials from environment
+    jira_base_url = os.environ.get("JIRA_BASE_URL", "")
+    jira_email = os.environ.get("JIRA_USER_EMAIL", "")
+    jira_token = os.environ.get("JIRA_API_TOKEN", "")
+
+    if not args.dry_run and (not jira_base_url or not jira_email or not jira_token):
+        logger.error("JIRA_BASE_URL, JIRA_USER_EMAIL, and JIRA_API_TOKEN must be set.")
+        return 1
+
+    # Initialize Jira client
+    client = JiraClient(
+        base_url=jira_base_url or "https://example.atlassian.net",
+        email=jira_email or "noop@example.com",
+        api_token=jira_token or "noop",
+        dry_run=args.dry_run,
+    )
+
+    # Load all stories for slug -> key resolution
+    all_stories = load_all_stories()
+    logger.info("Loaded %d story files.", len(all_stories))
+
+    # Scale guard: the --all sync mode (used on every push by the default
+    # workflow) issues one Jira GET per story for the terminal-state guard
+    # plus one per dep for determine_transition(). At ~250 stories this
+    # starts pressing Jira rate limits and pushing single-run latency
+    # past ~2 minutes. The durable fix is documented in
+    # methodology/followups.md § "Dep reconciliation skips unchanged
+    # stories — JQL-prefetch is the durable fix at scale": replace
+    # per-story GETs with one JQL pre-fetch of the relevant project
+    # tickets, then walk stories against the in-memory state map.
+    # Until that lands, fail loudly rather than degrade silently.
+    MAX_STORY_CORPUS = 250
+    if len(all_stories) > MAX_STORY_CORPUS:
+        logger.error(
+            "Story corpus has %d files, exceeding the %d-story threshold "
+            "at which the current --all sync strategy starts hitting "
+            "Jira rate limits. Apply the durable fix documented in "
+            "methodology/followups.md § 'Dep reconciliation skips "
+            "unchanged stories — JQL-prefetch is the durable fix at "
+            "scale' (bulk-read Jira ticket states via one JQL query, "
+            "then walk stories locally against the in-memory state map) "
+            "before this workflow can complete.",
+            len(all_stories),
+            MAX_STORY_CORPUS,
+        )
+        return 2
+
+    # Determine which files to sync
+    if args.all:
+        target_files = get_all_story_files()
+    else:
+        target_files = get_changed_story_files(args.since_ref)
+
+    if not target_files:
+        logger.info("No story files to sync.")
+        return 0
+
+    logger.info("Syncing %d story file(s).", len(target_files))
+
+    # Parse target stories
+    target_stories: list[StoryMeta] = []
+    for path in target_files:
+        if not path.exists():
+            # Check if this was a rename to underscore prefix
+            continue
+        try:
+            story = parse_story_file(path)
+            target_stories.append(story)
+        except Exception:
+            logger.error("Failed to parse %s", path, exc_info=True)
+            return 1
+
+    # Also check for renamed (canceled) files
+    if args.since_ref:
+        renames = get_renamed_files(args.since_ref)
+        for old_path, new_path in renames.items():
+            new_name = Path(new_path).name
+            if new_name.startswith("_"):
+                full_new = REPO_ROOT / new_path
+                if full_new.exists():
+                    try:
+                        story = parse_story_file(full_new)
+                        # Only add if not already in target list
+                        if not any(s.slug == story.slug for s in target_stories):
+                            target_stories.append(story)
+                    except Exception:
+                        logger.error(
+                            "Failed to parse renamed file %s",
+                            full_new,
+                            exc_info=True,
+                        )
+                        return 1
+
+    # Sort stories so parents are processed before children
+    target_stories = sort_stories_for_processing(target_stories)
+
+    # Execute sync
+    actions: list[SyncAction] = []
+    writeback_paths: list[tuple[Path, str]] = []
+
+    for story in target_stories:
+        jira_key = sync_story(story, all_stories, client, actions)
+        # Track files that need jira_key writeback
+        if jira_key and not story.is_canceled:
+            # Check if the key was newly assigned (was None before sync)
+            original = all_stories.get(story.slug)
+            if original and original.jira_key is None and jira_key:
+                writeback_paths.append((story.path, jira_key))
+
+    print_actions(actions)
+
+    if writeback_paths and not args.dry_run:
+        logger.info(
+            "jira_key writeback needed for %d file(s): %s",
+            len(writeback_paths),
+            [str(p) for p, _ in writeback_paths],
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())