sddflow 2.7.0__py3-none-any.whl

sdd/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.7.0"

sdd/__main__.py

@@ -0,0 +1,30 @@
+import click
+from sdd import __version__
+from sdd.commands.init import init_command
+from sdd.commands.upgrade import upgrade_command
+from sdd.commands.config import config_command
+from sdd.commands.jira import jira_command
+from sdd.commands.confluence import confluence_command
+from sdd.commands.review import review_command
+from sdd.commands.cr import cr_command
+from sdd.commands.pr import pr_command
+
+
+@click.group()
+@click.version_option(__version__, prog_name="sdd")
+def cli():
+    """SDD Framework CLI — Spec-Driven Development"""
+
+
+cli.add_command(init_command,        name="init")
+cli.add_command(upgrade_command,     name="upgrade")
+cli.add_command(config_command,      name="config")
+cli.add_command(jira_command,        name="jira")
+cli.add_command(confluence_command,  name="confluence")
+cli.add_command(review_command,      name="review")
+cli.add_command(cr_command,          name="cr")
+cli.add_command(pr_command,          name="pr")
+
+
+if __name__ == "__main__":
+    cli()

sdd/commands/config.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+from pathlib import Path
+import yaml
+import click
+import requests
+from rich.console import Console
+
+from sdd.utils.atlassian_auth import load_profile, build_session, save_config, CONFIG_PATH
+from sdd.utils.jira_client import JiraClient
+from sdd.utils.confluence_client import ConfluenceClient
+
+console = Console()
+
+
+@click.group()
+def config_command():
+    """Configure Atlassian credentials and project integration."""
+
+
+@config_command.command("init")
+def config_init():
+    """Interactively create ~/.sdd/config.yml and .specify/integrations.yml."""
+    import questionary
+
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print("  [bold cyan]SDD Config[/bold cyan] — Atlassian setup")
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+    profile_name = questionary.text("Profile name:", default="default").ask()
+    base_url     = questionary.text(
+        "Atlassian base URL:", default="https://myco.atlassian.net"
+    ).ask()
+    auth_mode = questionary.select(
+        "Auth mode:",
+        choices=[
+            questionary.Choice(
+                "basic  — Cloud (email + API token)",  value="basic"),
+            questionary.Choice(
+                "pat    — Server/DC (Personal Access Token)", value="pat"),
+            questionary.Choice(
+                "oauth2 — Cloud CI/CD (OAuth 2.0 Bearer token)", value="oauth2"),
+        ],
+    ).ask()
+
+    profile: dict = {"auth_mode": auth_mode, "base_url": base_url}
+
+    if auth_mode == "basic":
+        email         = questionary.text("Your Atlassian account email:").ask()
+        api_token_env = questionary.text(
+            "Name of env var holding your API token:", default="JIRA_API_TOKEN"
+        ).ask()
+        profile["email"]         = email
+        profile["api_token_env"] = api_token_env
+        console.print(f"\n  [dim]Export [cyan]{api_token_env}[/cyan] before running sdd commands.[/dim]")
+
+    elif auth_mode == "pat":
+        pat_env = questionary.text(
+            "Name of env var holding your PAT:", default="JIRA_PAT"
+        ).ask()
+        profile["pat_env"] = pat_env
+        console.print(f"\n  [dim]Export [cyan]{pat_env}[/cyan] before running sdd commands.[/dim]")
+
+    elif auth_mode == "oauth2":
+        access_token_env = questionary.text(
+            "Name of env var holding your OAuth2 access token:",
+            default="JIRA_ACCESS_TOKEN",
+        ).ask()
+        profile["access_token_env"] = access_token_env
+        console.print(f"\n  [dim]Export [cyan]{access_token_env}[/cyan] before running sdd commands.[/dim]")
+
+    # Merge into existing config
+    if CONFIG_PATH.exists():
+        existing = yaml.safe_load(CONFIG_PATH.read_text()) or {}
+    else:
+        existing = {"version": "1", "profiles": {}}
+
+    existing.setdefault("profiles", {})[profile_name] = profile
+    existing.setdefault("default_profile", profile_name)
+
+    save_config(existing)
+    console.print(f"\n  [green]✓[/green]  Profile [cyan]{profile_name}[/cyan] saved → {CONFIG_PATH}")
+
+    # Optionally scaffold .specify/integrations.yml
+    if questionary.confirm(
+        "\n  Set up .specify/integrations.yml for this project?", default=True
+    ).ask():
+        _scaffold_integrations(profile_name)
+
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print(
+        "  [bold green]Config complete![/bold green]  "
+        "Run [cyan]sdd config test[/cyan] to verify."
+    )
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+
+def _scaffold_integrations(profile_name: str) -> None:
+    import questionary
+    from sdd.utils.manifest import read_manifest
+
+    dest = Path(".specify/integrations.yml")
+    if dest.exists():
+        if not questionary.confirm(
+            f"  {dest} already exists — overwrite?", default=False
+        ).ask():
+            return
+
+    project_key    = questionary.text("Jira project key (e.g. MYPROJ):").ask()
+    space_key      = questionary.text("Confluence space key (e.g. ENG):").ask()
+    parent_page_id = questionary.text(
+        "Confluence parent page ID (blank = root):", default=""
+    ).ask().strip()
+
+    manifest     = read_manifest() or {}
+    project_name = (manifest.get("project") or {}).get("name", "{project}")
+
+    dest.write_text(
+        _integrations_template(profile_name, project_key, space_key,
+                                parent_page_id, project_name)
+    )
+    console.print(f"  [green]✓[/green]  {dest} created")
+    console.print(
+        "  [dim]Edit [cyan]custom_fields[/cyan] to match your Jira instance.  "
+        "Run [cyan]sdd config fields[/cyan] to discover IDs.[/dim]"
+    )
+
+
+@config_command.command("test")
+@click.option("--profile", default=None, help="Profile name from ~/.sdd/config.yml")
+def config_test(profile):
+    """Ping Jira and Confluence to verify credentials."""
+    console.print()
+    try:
+        prof    = load_profile(profile)
+        session = build_session(prof)
+    except Exception as e:
+        console.print(f"  [red]✗  Config error: {e}[/red]")
+        raise SystemExit(1)
+
+    try:
+        me = JiraClient(session, prof.base_url).get_myself()
+        name = me.get("displayName") or me.get("emailAddress", "?")
+        console.print(f"  [green]✓[/green]  Jira       — connected as [cyan]{name}[/cyan]")
+    except requests.HTTPError as e:
+        console.print(f"  [red]✗  Jira       — HTTP {e.response.status_code}: "
+                      f"{e.response.text[:120]}[/red]")
+
+    try:
+        me = ConfluenceClient(session, prof.base_url).get_myself()
+        name = me.get("displayName") or me.get("username", "?")
+        console.print(f"  [green]✓[/green]  Confluence — connected as [cyan]{name}[/cyan]")
+    except requests.HTTPError as e:
+        console.print(f"  [red]✗  Confluence — HTTP {e.response.status_code}: "
+                      f"{e.response.text[:120]}[/red]")
+
+    console.print()
+
+
+@config_command.command("fields")
+@click.option("--profile", default=None)
+@click.option("--project", default=None, help="Jira project key")
+def config_fields(profile, project):
+    """List Jira custom fields to help fill integrations.yml custom_fields."""
+    try:
+        prof    = load_profile(profile)
+        session = build_session(prof)
+    except Exception as e:
+        console.print(f"  [red]✗  {e}[/red]")
+        raise SystemExit(1)
+
+    if project is None:
+        try:
+            from sdd.utils.integrations import load_integrations
+            cfg     = load_integrations()
+            project = cfg.jira.project_key if cfg.jira else None
+        except FileNotFoundError:
+            pass
+    if not project:
+        console.print(
+            "  [red]✗  No project key. Use --project KEY or set it in "
+            ".specify/integrations.yml[/red]"
+        )
+        raise SystemExit(1)
+
+    fields = JiraClient(session, prof.base_url).get_fields()
+    custom = sorted(
+        [f for f in fields if f.get("custom")],
+        key=lambda f: f.get("name", ""),
+    )
+
+    console.print(f"\n  [bold]Custom fields ({len(custom)} found):[/bold]\n")
+    console.print(f"  {'ID':<30} {'Name':<40} Type")
+    console.print(f"  {'─'*30} {'─'*40} {'─'*20}")
+    for f in custom:
+        ftype = (f.get("schema") or {}).get("type", "")
+        console.print(
+            f"  [cyan]{f['id']:<30}[/cyan] {f.get('name',''):<40} [dim]{ftype}[/dim]"
+        )
+    console.print()
+
+
+def _integrations_template(profile: str, project_key: str, space_key: str,
+                             parent_page_id: str, project_name: str) -> str:
+    parent_line = (
+        f'  parent_page_id: "{parent_page_id}"'
+        if parent_page_id
+        else '  # parent_page_id: "123456"   # optional'
+    )
+    return f"""\
+# SDD Integrations — project-level config (no secrets here)
+# Credentials live in ~/.sdd/config.yml as env var names
+profile: {profile}
+
+jira:
+  project_key: {project_key}
+
+  # Jira issue type names — Feature → Story → Task
+  # Use "Epic" instead of "Feature" if your project has no Feature type
+  issue_hierarchy:
+    feature: Feature
+    story: Story
+    task: Task
+
+  # Parent link field:
+  #   "parent"            — Next-gen / team-managed projects
+  #   "customfield_10014" — Classic projects (Epic Link)
+  parent_field: parent
+
+  base_fields:
+    priority_map:
+      must-have:   High
+      should-have: Medium
+      could-have:  Low
+      wont-have:   Lowest
+    labels: [sdd-generated]
+    # fix_version: v1.0   # optional
+
+  # Custom field IDs — run "sdd config fields" to discover yours
+  custom_fields:
+    story_points: customfield_10016    # almost universal on Jira Cloud
+    # acceptance_criteria: customfield_10021
+    # team: customfield_10100
+
+confluence:
+  space_key: {space_key}
+{parent_line}
+
+  # Page title templates — {{project}} replaced with project name from manifest
+  # design applies in unified plan_mode; arch/hld/adr in separate plan_mode
+  page_map:
+    brd:       "{project_name} — Business Requirements"
+    use-cases: "{project_name} — Use Cases"
+    srd:       "{project_name} — System Requirements"
+    design:    "{project_name} — Design"
+    arch:      "{project_name} — Architecture Overview"
+    hld:       "{project_name} — High-Level Design"
+    adr:       "{project_name} — Architecture Decisions"
+    lld:       "{project_name} — Low-Level Design"
+    runbook:   "{project_name} — Runbook"
+
+# For the Jira review workflow (sdd review submit/check/apply), add a
+# document_reviews: section — see .specify/integrations.yml.example for the
+# full plan_mode-aware reference.
+"""

sdd/commands/confluence.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+import click
+from rich.console import Console
+
+from sdd.utils.atlassian_auth import load_profile, build_session
+from sdd.utils.integrations import load_integrations
+from sdd.utils.confluence_client import ConfluenceClient
+from sdd.utils.md_to_cf import md_to_storage
+from sdd.utils.cf_to_md import cf_to_md
+from sdd.utils.manifest import read_manifest
+
+console = Console()
+
+_DRAFTS_FILE = Path(".specify") / ".confluence-drafts.json"
+
+_CONTEXT_PAGE_TITLE = "{project} — Context: {feature}"
+
+
+def _load_drafts() -> dict:
+    if _DRAFTS_FILE.exists():
+        return json.loads(_DRAFTS_FILE.read_text())
+    return {}
+
+
+def _save_drafts(drafts: dict) -> None:
+    _DRAFTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _DRAFTS_FILE.write_text(json.dumps(drafts, indent=2))
+
+
+def _resolve_doc_path(doc: str, feature: str) -> Path:
+    """Return local file path for a doc key."""
+    if doc == "context":
+        return Path(".specify") / "contexts" / f"{feature}.md"
+    return Path(".specify") / "features" / feature / f"{doc}.md"
+
+
+def _resolve_page_title(doc: str, project_name: str, feature: str,
+                         page_map: dict) -> str:
+    if doc == "context":
+        return _CONTEXT_PAGE_TITLE.replace("{project}", project_name).replace("{feature}", feature)
+    template = page_map.get(doc, f"{{project}} — {doc.upper()}")
+    return template.replace("{project}", project_name)
+
+
+@click.group()
+def confluence_command():
+    """Push SDD documents to Confluence."""
+
+
+@confluence_command.command("push")
+@click.option("--profile", default=None)
+@click.option("--feature", default=None, help="Feature name (default: from manifest.yml)")
+@click.option("--doc",     default=None,
+              help="Push a single doc only (e.g. hld, brd, arch, runbook)")
+@click.option("--dry-run", is_flag=True, help="Print page titles without calling the API")
+def confluence_push(profile, feature, doc, dry_run):
+    """Publish SDD documents to Confluence pages (create or update)."""
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    label = "  [bold cyan]SDD → Confluence[/bold cyan]"
+    if dry_run:
+        label += "  [yellow](dry run)[/yellow]"
+    console.print(label)
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+    try:
+        cfg = load_integrations()
+    except FileNotFoundError as e:
+        console.print(f"  [red]✗  {e}[/red]")
+        raise SystemExit(1)
+
+    if not cfg.confluence:
+        console.print(
+            "  [red]✗  No confluence: section in .specify/integrations.yml[/red]"
+        )
+        raise SystemExit(1)
+
+    cf_cfg       = cfg.confluence
+    manifest     = read_manifest() or {}
+    proj         = manifest.get("project") or {}
+    project_name = proj.get("name", "Project")
+    feature_name = feature or proj.get("feature", "")
+
+    features_dir = Path(".specify") / "features" / feature_name
+    if not features_dir.exists():
+        console.print(f"  [red]✗  Feature directory not found: {features_dir}[/red]")
+        raise SystemExit(1)
+
+    # Resolve which docs to push
+    page_map    = cf_cfg.page_map
+    keys_to_try = [doc] if doc else list(page_map.keys())
+
+    available: list[tuple[str, Path, str]] = []
+    for key in keys_to_try:
+        md_path = features_dir / f"{key}.md"
+        if not md_path.exists():
+            console.print(f"  [dim]·[/dim]  {key}.md not found — skipped")
+            continue
+        title = page_map.get(key, f"{project_name} — {key.upper()}")
+        title = title.replace("{project}", project_name)
+        available.append((key, md_path, title))
+
+    if not available:
+        console.print("  [yellow]  No documents found to push.[/yellow]")
+        console.print()
+        return
+
+    console.print(f"  Space    : [cyan]{cf_cfg.space_key}[/cyan]")
+    console.print(f"  Parent   : [cyan]{cf_cfg.parent_page_id or 'root'}[/cyan]")
+    console.print(f"  Docs     : [cyan]{len(available)}[/cyan]")
+    console.print()
+
+    if dry_run:
+        for key, md_path, title in available:
+            console.print(f"  [dim]would push[/dim]  [cyan]{title}[/cyan]  ← {md_path}")
+        console.print()
+        return
+
+    try:
+        prof    = load_profile(profile or cfg.profile)
+        session = build_session(prof)
+    except Exception as e:
+        console.print(f"  [red]✗  Auth error: {e}[/red]")
+        raise SystemExit(1)
+
+    client = ConfluenceClient(session, prof.base_url)
+
+    for key, md_path, title in available:
+        body = md_to_storage(md_path.read_text())
+        try:
+            page, created = client.upsert_page(
+                cf_cfg.space_key, title, body, cf_cfg.parent_page_id
+            )
+            action = "[green]created[/green]" if created else "[dim]updated[/dim]"
+            console.print(f"  {action}  [cyan]{title}[/cyan]")
+            if created:
+                web_ui = page.get("_links", {}).get("webui", "")
+                if web_ui:
+                    console.print(f"          {prof.base_url}/wiki{web_ui}")
+        except Exception as e:
+            console.print(f"  [red]✗  {title} — {e}[/red]")
+
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print("  [bold green]Confluence push complete![/bold green]")
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+
+@confluence_command.command("draft")
+@click.option("--doc", required=True,
+              help="Document type: context, brd, uc, srd, design, lld, security, ...")
+@click.option("--profile", default=None)
+@click.option("--feature", default=None, help="Feature name (default: from manifest.yml)")
+@click.option("--dry-run", is_flag=True, help="Print title and path without calling the API")
+def confluence_draft(doc, profile, feature, dry_run):
+    """Push a draft SDD document to Confluence and print the edit URL.
+
+    The page URL is printed so the user can open it, fill in any
+    [MISSING] sections or questions, then run `sdd confluence pull`
+    to fetch the updated version back.
+    """
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    label = "  [bold cyan]SDD → Confluence Draft[/bold cyan]"
+    if dry_run:
+        label += "  [yellow](dry run)[/yellow]"
+    console.print(label)
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+    try:
+        cfg = load_integrations()
+    except FileNotFoundError as e:
+        console.print(f"  [red]✗  {e}[/red]")
+        raise SystemExit(1)
+
+    if not cfg.confluence:
+        console.print("  [red]✗  No confluence: section in .specify/integrations.yml[/red]")
+        raise SystemExit(1)
+
+    cf_cfg = cfg.confluence
+    manifest = read_manifest() or {}
+    proj = manifest.get("project") or {}
+    project_name = proj.get("name", "Project")
+    feature_name = feature or proj.get("feature", "")
+
+    doc_path = _resolve_doc_path(doc, feature_name)
+    if not doc_path.exists():
+        console.print(f"  [red]✗  File not found: {doc_path}[/red]")
+        console.print("  [dim]Generate the document first, then run this command.[/dim]")
+        raise SystemExit(1)
+
+    title = _resolve_page_title(doc, project_name, feature_name, cf_cfg.page_map)
+
+    console.print(f"  Doc      : [cyan]{doc}[/cyan]  ({doc_path})")
+    console.print(f"  Title    : [cyan]{title}[/cyan]")
+    console.print(f"  Space    : [cyan]{cf_cfg.space_key}[/cyan]")
+    console.print()
+
+    if dry_run:
+        console.print("  [dim]would push draft page to Confluence[/dim]")
+        console.print()
+        return
+
+    try:
+        prof = load_profile(profile or cfg.profile)
+        session = build_session(prof)
+    except Exception as e:
+        console.print(f"  [red]✗  Auth error: {e}[/red]")
+        raise SystemExit(1)
+
+    client = ConfluenceClient(session, prof.base_url)
+    body = md_to_storage(doc_path.read_text())
+
+    try:
+        page, created = client.upsert_page(
+            cf_cfg.space_key, title, body, cf_cfg.parent_page_id
+        )
+    except Exception as e:
+        console.print(f"  [red]✗  Confluence error: {e}[/red]")
+        raise SystemExit(1)
+
+    page_id = page.get("id", "")
+    web_ui = page.get("_links", {}).get("webui", "")
+    edit_url = f"{prof.base_url}/wiki{web_ui}" if web_ui else ""
+
+    # Persist page_id so `sdd confluence pull` can find it later
+    drafts = _load_drafts()
+    drafts[doc] = {"page_id": page_id, "title": title}
+    _save_drafts(drafts)
+
+    action = "[green]created[/green]" if created else "[dim]updated[/dim]"
+    console.print(f"  {action}  [bold]{title}[/bold]")
+    if edit_url:
+        console.print(f"  URL      : [underline cyan]{edit_url}[/underline cyan]")
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print("  [bold green]Draft pushed![/bold green]  Open the URL above, fill in any")
+    console.print("  [MISSING] sections or answer the questions, then run:")
+    console.print()
+    console.print(f"      [bold]sdd confluence pull --doc {doc}[/bold]")
+    console.print()
+    console.print("  to pull your edits back into the local file.")
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+
+@confluence_command.command("pull")
+@click.option("--doc", required=True,
+              help="Document type: context, brd, uc, srd, design, lld, security, ...")
+@click.option("--profile", default=None)
+@click.option("--feature", default=None, help="Feature name (default: from manifest.yml)")
+@click.option("--page-id", default=None, help="Confluence page ID (overrides saved value)")
+def confluence_pull(doc, profile, feature, page_id):
+    """Pull the latest Confluence page content back to the local SDD file.
+
+    Run this after editing the draft page in Confluence to pull your
+    changes back so the AI can continue the workflow from the updated doc.
+    """
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print("  [bold cyan]Confluence → SDD Pull[/bold cyan]")
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()
+
+    try:
+        cfg = load_integrations()
+    except FileNotFoundError as e:
+        console.print(f"  [red]✗  {e}[/red]")
+        raise SystemExit(1)
+
+    if not cfg.confluence:
+        console.print("  [red]✗  No confluence: section in .specify/integrations.yml[/red]")
+        raise SystemExit(1)
+
+    manifest = read_manifest() or {}
+    proj = manifest.get("project") or {}
+    feature_name = feature or proj.get("feature", "")
+
+    # Resolve page ID: explicit flag > saved drafts file
+    resolved_page_id = page_id
+    if not resolved_page_id:
+        drafts = _load_drafts()
+        entry = drafts.get(doc)
+        if entry:
+            resolved_page_id = entry.get("page_id")
+    if not resolved_page_id:
+        console.print(
+            f"  [red]✗  No page ID for '{doc}'.[/red]\n"
+            "  Run [bold]sdd confluence draft --doc {doc}[/bold] first, "
+            "or pass [bold]--page-id[/bold] directly."
+        )
+        raise SystemExit(1)
+
+    try:
+        prof = load_profile(profile or cfg.profile)
+        session = build_session(prof)
+    except Exception as e:
+        console.print(f"  [red]✗  Auth error: {e}[/red]")
+        raise SystemExit(1)
+
+    client = ConfluenceClient(session, prof.base_url)
+
+    console.print(f"  Fetching page [cyan]{resolved_page_id}[/cyan] from Confluence...")
+    try:
+        page = client.get_page_with_body(resolved_page_id)
+    except Exception as e:
+        console.print(f"  [red]✗  Confluence error: {e}[/red]")
+        raise SystemExit(1)
+
+    storage_body = (
+        page.get("body", {}).get("storage", {}).get("value", "")
+    )
+    if not storage_body:
+        console.print("  [red]✗  Page body is empty.[/red]")
+        raise SystemExit(1)
+
+    markdown = cf_to_md(storage_body)
+
+    # Fetch comments (footer + inline) and append as a section the AI can read
+    console.print("  Fetching comments...")
+    try:
+        footer_comments  = client.get_page_comments(resolved_page_id)
+        inline_comments  = client.get_inline_comments(resolved_page_id)
+        all_comments     = footer_comments + inline_comments
+    except Exception:
+        all_comments = []
+
+    if all_comments:
+        lines = [
+            "",
+            "---",
+            "",
+            "## Confluence Comments",
+            "",
+            "> These comments were added in Confluence by reviewers or stakeholders.",
+            "> The AI will incorporate them into the document — do not edit this section manually.",
+            "",
+        ]
+        for i, c in enumerate(all_comments, 1):
+            kind = "inline" if c["type"] == "inline" else "comment"
+            lines.append(f"### {kind.capitalize()} {i} — {c['author']} ({c['created']})")
+            lines.append("")
+            lines.append(c["text"])
+            lines.append("")
+        markdown = markdown + "\n" + "\n".join(lines)
+
+    doc_path = _resolve_doc_path(doc, feature_name)
+    doc_path.parent.mkdir(parents=True, exist_ok=True)
+
+    old_text = doc_path.read_text() if doc_path.exists() else ""
+    doc_path.write_text(markdown + "\n")
+
+    body_lines   = len(cf_to_md(storage_body).splitlines())
+    comment_count = len(all_comments)
+    console.print(f"  [green]✓[/green]  Saved to [bold]{doc_path}[/bold]")
+    console.print(f"  Body     : {body_lines} lines")
+    if comment_count:
+        console.print(f"  Comments : [yellow]{comment_count}[/yellow] (included for AI review)")
+    console.print()
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print("  [bold green]Pull complete![/bold green]  The local file is now up to date.")
+    if comment_count:
+        console.print(f"  [yellow]{comment_count} Confluence comment(s)[/yellow] included —")
+        console.print("  tell the AI 'done' and it will incorporate them.")
+    if doc == "context":
+        console.print("  Say [bold]'done'[/bold] in chat — the AI will read the updates")
+        console.print("  and comments, then continue.")
+    else:
+        console.print(f"  Say [bold]'done'[/bold] in chat to resume the SDD workflow.")
+    console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
+    console.print()