sddflow 2.7.58__tar.gz → 2.7.60__tar.gz

{sddflow-2.7.58 → sddflow-2.7.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sddflow
-Version: 2.7.58
+Version: 2.7.60
 Summary: SDD Framework CLI — initialize and upgrade Spec-Driven Development packs
 Project-URL: Homepage, https://github.com/sunil1983us/universalguide
 Project-URL: Repository, https://github.com/sunil1983us/universalguide

{sddflow-2.7.58 → sddflow-2.7.60}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sddflow"
-version = "2.7.58"
+version = "2.7.60"
 description = "SDD Framework CLI — initialize and upgrade Spec-Driven Development packs"
 readme = "README.md"
 requires-python = ">=3.9"

sddflow-2.7.60/sdd/__init__.py

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

{sddflow-2.7.58 → sddflow-2.7.60}/sdd/commands/dashboard.py

@@ -682,7 +682,7 @@ def _fetch_review_links(feature: str) -> dict:
             try:
                 issue = jira_client.find_by_label(cfg.jira.key_for("review"), f"sdd-doc:{feature}:{doc_key}")
                 if issue:
-                    review_status, comments = _get_review_status(
+                    review_status, comments, _ = _get_review_status(
                         doc_key, jira_client, cfg.jira.key_for("review"), cfg, feature,
                     )
                     entry["jira"] = {

{sddflow-2.7.58 → sddflow-2.7.60}/sdd/commands/review.py

@@ -115,13 +115,40 @@ def _mark_md_approved(md_path: Path) -> bool:
     return True
 
 
-def _push_doc_page(doc: str, md_path: Path, feature_name: str) -> str | None:
-    """Upsert the document's Confluence page so it reflects the approved .md.
+def _jira_status_banner(issue_key: str, issue_url: str, status: str, role: str) -> str:
+    """Confluence storage-format panel summarizing the Jira review ticket's
+    link and current status, prepended to the page body on every push so a
+    reviewer can see review state without leaving Confluence."""
+    macro_type = {"APPROVED": "success", "NEEDS_REVISION": "warning"}.get(status, "info")
+    label = {
+        "APPROVED":       "Approved",
+        "NEEDS_REVISION": "Needs Revision",
+        "PENDING":        "Pending review",
+    }.get(status, status)
+    return (
+        f'<ac:structured-macro ac:name="{macro_type}">'
+        f'<ac:rich-text-body><p>'
+        f'<strong>Jira review:</strong> '
+        f'<a href="{issue_url}">{issue_key}</a> — <strong>{label}</strong>'
+        f' (assigned: {role})'
+        f'</p></ac:rich-text-body>'
+        f'</ac:structured-macro>'
+    )
+
+
+def _push_doc_page(doc: str, md_path: Path, feature_name: str) -> tuple[str, str] | None:
+    """Upsert the document's Confluence page so it reflects the current .md.
 
-    Returns the page title on success, or None when Confluence is not
-    configured. Raises on push errors — callers decide how fatal that is.
-    Page title resolution matches `sdd review submit`: document_reviews entry
-    first, then the confluence page_map, then a sensible default."""
+    Returns (page_title, page_url) on success, or None when Confluence is
+    not configured. Raises on push errors — callers decide how fatal that
+    is. Page title resolution matches `sdd review submit`: document_reviews
+    entry first, then the confluence page_map, then a sensible default.
+
+    When a Jira review ticket already exists for this doc (jira: configured
+    and document_reviews has an entry for it), a status banner linking to
+    that ticket is prepended to the page body -- this is what lets a
+    reviewer see the Jira link + current status directly on Confluence
+    instead of having to check Jira separately."""
     try:
         cfg = load_integrations()
     except FileNotFoundError:
@@ -147,16 +174,33 @@ def _push_doc_page(doc: str, md_path: Path, feature_name: str) -> str | None:
     prof      = load_profile(cfg.profile)
     session   = build_session(prof)
     cf_client = ConfluenceClient(session, prof.base_url)
+
+    banner = ""
+    if cfg.jira and doc in cfg.document_reviews:
+        try:
+            jira_client = JiraClient(session, prof.base_url)
+            status, _, issue = _get_review_status(
+                doc, jira_client, cfg.jira.key_for("review"), cfg, feature_name,
+            )
+            if issue:
+                issue_url = f"{prof.base_url}/browse/{issue['key']}"
+                banner = _jira_status_banner(
+                    issue["key"], issue_url, status, cfg.document_reviews[doc].reviewer_role,
+                )
+        except Exception:
+            pass  # banner is a best-effort addition -- never blocks the page push itself
+
     body_html, attachments, diagram_warnings = md_to_storage(md_path.read_text(), cfg.confluence.diagrams)
     from sdd.commands.confluence import resolve_doc_parent_id, upload_diagram_attachments
     parent_id = resolve_doc_parent_id(cf_client, cfg.confluence, project_name, feature_name, doc)
     page, _created = cf_client.upsert_page(
-        cfg.confluence.space_key, title, body_html, parent_id,
+        cfg.confluence.space_key, title, banner + body_html, parent_id,
     )
     upload_diagram_attachments(cf_client, page["id"], attachments)
     for w in diagram_warnings:
         console.print(f"  [yellow]!  {w}[/yellow]")
-    return title
+    page_url = f"{prof.base_url}/wiki{page.get('_links', {}).get('webui', '')}"
+    return title, page_url
 
 
 # ── Text extraction ────────────────────────────────────────────────────────────
@@ -231,29 +275,32 @@ def _get_review_status(
     project_key: str,
     cfg: IntegrationsConfig,
     feature_name: str,
-) -> tuple[str, list[dict]]:
-    """Return (status, comments).
+) -> tuple[str, list[dict], dict | None]:
+    """Return (status, comments, issue).
     status: APPROVED | NEEDS_REVISION | PENDING | NOT_SUBMITTED
+    issue is the raw Jira issue dict (or None if never submitted) -- callers
+    that also need the issue key/link (e.g. the Confluence status banner)
+    reuse this instead of a second find_by_label lookup.
 
     Label is feature-qualified — must match the label `review_submit` writes,
     or a submitted review would never be found again.
     """
     issue = client.find_by_label(project_key, f"sdd-doc:{feature_name}:{doc_key}")
     if not issue:
-        return "NOT_SUBMITTED", []
+        return "NOT_SUBMITTED", [], None
 
     jira_status = issue.get("fields", {}).get("status", {}).get("name", "")
     comments    = client.get_comments(issue["key"])
 
     if jira_status in cfg.approved_statuses:
-        return "APPROVED", comments
+        return "APPROVED", comments, issue
 
     for c in comments:
         text = _extract_text(c.get("body", "")).lower()
         if any(kw in text for kw in cfg.approved_keywords):
-            return "APPROVED", comments
+            return "APPROVED", comments, issue
 
-    return ("NEEDS_REVISION" if comments else "PENDING"), comments
+    return ("NEEDS_REVISION" if comments else "PENDING"), comments, issue
 
 
 def _check_predecessor(
@@ -275,7 +322,7 @@ def _check_predecessor(
     if not preds:
         return True, None
     pred_key = preds[0]
-    status, _ = _get_review_status(pred_key, client, cfg.jira.key_for("review"), cfg, feature_name)
+    status, _, _ = _get_review_status(pred_key, client, cfg.jira.key_for("review"), cfg, feature_name)
     return (status == "APPROVED"), (None if status == "APPROVED" else pred_key)
 
 
@@ -426,6 +473,129 @@ def _patch_marker(md_path: Path, nnn: str, answer: str) -> bool:
     return True
 
 
+# ── clarify.md's own open items (AMB/GAP/CON/ASM/OQ/R) ─────────────────────────
+# Unlike validate.md's [NEEDS CLARIFICATION-NNN] markers -- which cite OTHER
+# documents (brd/srd/use-cases) via a `{doc}:NC-{NNN}` ID -- clarify.md's own
+# ambiguities/gaps/conflicts/assumptions/open-questions/risks live entirely in
+# clarify.md itself, tracked by its STATUS TABLE (see clarify-template.md)
+# rather than an inline bracketed marker. push-questions/pull-answers only
+# ever understood the NC-NNN scheme, so clarify.md could never be pushed to
+# Jira for answers the way validate.md already could -- this second, parallel
+# parse/patch pair gives it the same workflow.
+
+_CLARIFY_ITEM_CODE = r'(?:AMB|GAP|CON|ASM|OQ|R)-\d+'
+_CLARIFY_STATUS_ROW_RE = re.compile(
+    r'^\|\s*(' + _CLARIFY_ITEM_CODE + r')\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*OPEN\s*\|\s*$',
+    re.MULTILINE | re.IGNORECASE,
+)
+_CLARIFY_ANSWER_LINE_RE = re.compile(
+    r'^\s*clarify:(' + _CLARIFY_ITEM_CODE + r')\s*:\s*(.+?)\s*$',
+    re.MULTILINE | re.IGNORECASE,
+)
+_CLARIFY_FILL_RE = re.compile(r'\{FILL[^}]*\}')
+
+# Terminal STATUS TABLE value per item-type prefix, matching the mapping
+# clarify.prompt.md's own Step 2 uses ("match the item type"). ASM is not
+# listed here -- it's CONFIRMED or CORRECTED depending on the answer itself
+# (the template's own "Correct? Yes / No" framing), handled in
+# _patch_clarify_item rather than a fixed lookup.
+_CLARIFY_TERMINAL_STATUS = {
+    "AMB": "RESOLVED",
+    "GAP": "RESOLVED",
+    "CON": "CORRECTED",
+    "OQ":  "DECIDED",
+    "R":   "RESOLVED",
+}
+
+
+def _clarify_item_block_text(doc_text: str, code: str) -> str | None:
+    """Return the full body of a clarify.md item's own section (from its
+    `### {code}: {Topic}` heading up to the next section break -- either a
+    `---` divider between type-sections or the next `### ` item heading for
+    consecutive same-type items), for posting as the Jira question text.
+    Returns the whole block (Found in / Option A / Option B / etc, not just
+    one field) since the 5 item types each label their key line
+    differently and the reviewer needs full context regardless. None if no
+    such heading exists in doc_text."""
+    heading = re.search(r'^### ' + re.escape(code) + r':.*$', doc_text, re.MULTILINE)
+    if not heading:
+        return None
+    rest = doc_text[heading.end():]
+    end_match = re.search(r'\n---\s*\n|\n### ', rest)
+    body = rest[:end_match.start()] if end_match else rest
+    return (heading.group(0) + "\n" + body).strip()
+
+
+def _parse_clarify_open_items(doc_text: str) -> list[dict]:
+    """Parse clarify.md's STATUS TABLE for OPEN rows into the same
+    {id, locations, question} shape _parse_open_questions returns, so
+    push-questions/pull-answers can handle both marker schemes through the
+    same downstream Jira/Confluence code. Every clarify item lives in
+    clarify.md itself -- "locations" is always just the item's own ID,
+    prefixed "clarify:" to match the {doc}:NC-{NNN} convention every
+    answer-parsing/console-message call site already expects (e.g. the
+    reviewer replies "clarify:AMB-001: <answer>", not "brd:NC-001: ...")."""
+    items: list[dict] = []
+    for m in _CLARIFY_STATUS_ROW_RE.finditer(doc_text):
+        code = m.group(1).strip().upper()
+        full_id = f"clarify:{code}"
+        question = _clarify_item_block_text(doc_text, code) or f"{m.group(2).strip()}: {m.group(3).strip()}"
+        items.append({"id": full_id, "locations": [full_id], "question": question})
+    return items
+
+
+def _parse_clarify_answers(comments: list[dict]) -> dict[str, str]:
+    """Parse every Jira comment for lines like 'clarify:AMB-001: <answer>'.
+    A later comment's answer for the same ID overrides an earlier one."""
+    answers: dict[str, str] = {}
+    for c in comments:
+        text = _extract_text(c.get("body", ""))
+        for m in _CLARIFY_ANSWER_LINE_RE.finditer(text):
+            code, answer = m.group(1).upper(), m.group(2)
+            answers[f"clarify:{code}"] = answer
+    return answers
+
+
+def _patch_clarify_item(md_path: Path, code: str, answer: str) -> bool:
+    """Fill a clarify.md item's `{FILL...}` placeholder with the reviewer's
+    answer and flip its STATUS TABLE row from OPEN to the terminal status
+    for its type. Returns True if the item was found and patched, False
+    otherwise (already resolved, or code doesn't exist in this file)."""
+    if not md_path.exists():
+        return False
+    text = md_path.read_text()
+
+    heading = re.search(r'^### ' + re.escape(code) + r':.*$', text, re.MULTILINE)
+    if not heading:
+        return False
+    rest = text[heading.end():]
+    end_match = re.search(r'\n---\s*\n|\n### ', rest)
+    block_end = heading.end() + (end_match.start() if end_match else len(rest))
+    fill_match = _CLARIFY_FILL_RE.search(text, heading.end(), block_end)
+    if not fill_match:
+        return False  # already answered
+
+    prefix = code.split("-")[0]
+    if prefix == "ASM":
+        status = "CONFIRMED" if answer.strip().lower().startswith("yes") else "CORRECTED"
+    else:
+        status = _CLARIFY_TERMINAL_STATUS.get(prefix, "RESOLVED")
+
+    new_text = text[:fill_match.start()] + answer + text[fill_match.end():]
+
+    status_row_re = re.compile(
+        r'(^\|\s*' + re.escape(code) + r'\s*\|[^|]*\|[^|]*\|)\s*OPEN\s*(\|\s*$)',
+        re.MULTILINE | re.IGNORECASE,
+    )
+    new_text, n = status_row_re.subn(r'\1 ' + status + r' \2', new_text, count=1)
+    if n == 0:
+        return False  # STATUS TABLE row missing/already flipped -- don't half-patch
+
+    new_text = _bump_version_and_log(new_text, f"{code} resolved via Jira/Confluence comment")
+    md_path.write_text(new_text)
+    return True
+
+
 _LEGACY_MARKER_RE = re.compile(r'\[NEEDS CLARIFICATION:\s*')
 
 
@@ -688,6 +858,16 @@ def review_submit(doc, profile, feature):
 
     _record_review_link(doc, story_key)
 
+    # ── Re-push Confluence with the now-existing Jira link/status banner ──────
+    # The first push above (before the ticket existed) couldn't include this --
+    # _push_doc_page's own find-by-label lookup will now find the ticket just
+    # created/updated and prepend a banner showing its link + live status, so
+    # a reviewer sees Jira state without leaving Confluence.
+    try:
+        _push_doc_page(doc, md_path, feature_name)
+    except Exception as e:
+        console.print(f"  [yellow]!  Could not stamp Jira status onto Confluence: {e}[/yellow]")
+
     if epic_key:
         _link_review_story_to_epic(jira_client, story_key, epic_key, cfg.jira)
 
@@ -753,11 +933,14 @@ def review_push_questions(doc, profile, feature):
         console.print(f"  [red]✗  {md_path} not found[/red]")
         raise SystemExit(1)
 
-    items = _parse_open_questions(md_path.read_text())
+    if doc == "clarify":
+        items = _parse_clarify_open_items(md_path.read_text())
+        not_found_msg = "No OPEN items found in clarify.md's STATUS TABLE — nothing to push."
+    else:
+        items = _parse_open_questions(md_path.read_text())
+        not_found_msg = f"No open [NEEDS CLARIFICATION-NNN] items found in {md_path.name} — nothing to push."
     if not items:
-        console.print(
-            f"  [dim]No open [NEEDS CLARIFICATION-NNN] items found in {md_path.name} — nothing to push.[/dim]"
-        )
+        console.print(f"  [dim]{not_found_msg}[/dim]")
         raise SystemExit(0)
 
     try:
@@ -774,7 +957,9 @@ def review_push_questions(doc, profile, feature):
     page_title = None
     if cfg.confluence:
         try:
-            page_title = _push_doc_page(doc, md_path, feature_name)
+            pushed = _push_doc_page(doc, md_path, feature_name)
+            if pushed:
+                page_title, _page_url = pushed
         except Exception as e:
             console.print(f"  [yellow]!  Confluence push failed: {e}[/yellow]")
 
@@ -797,7 +982,7 @@ def review_push_questions(doc, profile, feature):
         f"Answer each item as a comment on THIS ticket, one line per item, "
         f"starting with its ID:\n\n{table_lines}\n\n"
         f"Example: \"{items[0]['id']}: <your answer>\"\n\n"
-        f"Once every item is answered, re-run /validate — it pulls the answers "
+        f"Once every item is answered, re-run /{doc} — it pulls the answers "
         f"automatically, updates the spec, and re-checks."
     )
     fields: dict = {
@@ -841,7 +1026,7 @@ def review_push_questions(doc, profile, feature):
     console.print()
     console.print(f"  [bold]{len(items)} open question(s)[/bold] pushed. Reviewer replies as a comment")
     console.print(f"  starting with the item's ID, e.g. \"{items[0]['id']}: <answer>\".")
-    console.print(f"  Run [cyan]sdd review pull-answers --doc {doc}[/cyan] (or just re-run /validate) once answered.")
+    console.print(f"  Run [cyan]sdd review pull-answers --doc {doc}[/cyan] (or just re-run /{doc}) once answered.")
     console.print()
 
 
@@ -879,31 +1064,38 @@ def review_pull_answers(doc, profile, feature):
     if not md_path.exists():
         raise SystemExit(0)
 
-    items = _parse_open_questions(md_path.read_text())
+    is_clarify = (doc == "clarify")
+    if is_clarify:
+        items = _parse_clarify_open_items(md_path.read_text())
+    else:
+        items = _parse_open_questions(md_path.read_text())
     if not items:
         raise SystemExit(0)
 
-    # Retrofit: a doc that predates NEEDS CLARIFICATION-NNN numbering
-    # still has the old unnumbered [NEEDS CLARIFICATION: ...] form, even
-    # though validate.md's table above already displays synthesized
-    # brd:NC-001-style IDs for it (order-of-appearance, same rule) --
-    # number the source file's markers to match before attempting any
-    # patch, or the exact-ID search below would never find them.
-    referenced_docs = {
-        _normalize_doc_key(loc_id.split(":NC-")[0])
-        for item in items for loc_id in item["locations"]
-    }
-    for doc_key in referenced_docs:
-        try:
-            loc_path = resolve_doc_path(doc_key, feature_name)
-        except ValueError:
-            continue
-        renumbered = _number_legacy_markers(loc_path)
-        if renumbered:
-            console.print(
-                f"  [dim]·  Numbered {renumbered} legacy marker(s) in "
-                f"{loc_path.name} to match validate.md's IDs[/dim]"
-            )
+    if not is_clarify:
+        # Retrofit: a doc that predates NEEDS CLARIFICATION-NNN numbering
+        # still has the old unnumbered [NEEDS CLARIFICATION: ...] form, even
+        # though validate.md's table above already displays synthesized
+        # brd:NC-001-style IDs for it (order-of-appearance, same rule) --
+        # number the source file's markers to match before attempting any
+        # patch, or the exact-ID search below would never find them.
+        # clarify.md's own items have no such legacy/numbering concern --
+        # they're tracked by a STATUS TABLE row, not a bracketed marker.
+        referenced_docs = {
+            _normalize_doc_key(loc_id.split(":NC-")[0])
+            for item in items for loc_id in item["locations"]
+        }
+        for doc_key in referenced_docs:
+            try:
+                loc_path = resolve_doc_path(doc_key, feature_name)
+            except ValueError:
+                continue
+            renumbered = _number_legacy_markers(loc_path)
+            if renumbered:
+                console.print(
+                    f"  [dim]·  Numbered {renumbered} legacy marker(s) in "
+                    f"{loc_path.name} to match validate.md's IDs[/dim]"
+                )
 
     links     = _load_review_links()
     issue_key = (links.get(doc) or {}).get("key")
@@ -927,7 +1119,7 @@ def review_pull_answers(doc, profile, feature):
         console.print(f"  [yellow]!  Could not fetch comments from {issue_key}: {e}[/yellow]")
         raise SystemExit(0)
 
-    answers = _parse_answers(comments)
+    answers = _parse_clarify_answers(comments) if is_clarify else _parse_answers(comments)
     if not answers:
         raise SystemExit(0)
 
@@ -942,6 +1134,13 @@ def review_pull_answers(doc, profile, feature):
         if item["id"] not in answers:
             continue
         answer_text = answers[item["id"]]
+        if is_clarify:
+            code = item["id"].split("clarify:", 1)[1]
+            if _patch_clarify_item(md_path, code, answer_text):
+                patched_docs["clarify"] = patched_docs.get("clarify", 0) + 1
+                patched_paths["clarify"] = md_path
+                console.print(f"  [green]✓[/green]  {item['id']} resolved in {md_path.name}")
+            continue
         for loc_id in item["locations"]:
             doc_key, nnn = loc_id.split(":NC-")
             doc_key = _normalize_doc_key(doc_key)
@@ -973,8 +1172,9 @@ def review_pull_answers(doc, profile, feature):
         if cfg.confluence:
             for doc_key, loc_path in patched_paths.items():
                 try:
-                    title = _push_doc_page(doc_key, loc_path, feature_name)
-                    if title:
+                    pushed = _push_doc_page(doc_key, loc_path, feature_name)
+                    if pushed:
+                        title, _page_url = pushed
                         console.print(f"  [green]✓[/green]  Confluence page refreshed: [cyan]{title}[/cyan]")
                 except Exception as e:
                     console.print(f"  [yellow]!  Could not refresh Confluence page for {doc_key}: {e}[/yellow]")
@@ -1030,10 +1230,22 @@ def review_check(doc, profile, feature):
         raise SystemExit(3)
 
     client  = JiraClient(session, prof.base_url)
-    status, comments = _get_review_status(doc, client, cfg.jira.key_for("review"), cfg, feature_name)
+    status, comments, _ = _get_review_status(doc, client, cfg.jira.key_for("review"), cfg, feature_name)
     doc_cfg = cfg.document_reviews.get(doc)
     role    = doc_cfg.reviewer_role if doc_cfg else "reviewer"
 
+    # ── Refresh the Confluence status banner to match what we just polled ─────
+    # Best-effort: a reviewer who only looks at Confluence (never Jira
+    # directly) should see the same status this command just printed, without
+    # having to wait for the next `sdd review submit`/`apply`/`approve`.
+    if cfg.confluence:
+        try:
+            md_path = resolve_doc_path(doc, feature_name)
+            if md_path.exists():
+                _push_doc_page(doc, md_path, feature_name)
+        except Exception:
+            pass
+
     if status == "APPROVED":
         console.print(f"  [green]✓  {doc.upper()} — APPROVED[/green]")
         console.print()
@@ -1164,8 +1376,9 @@ def review_approve(doc, local, by, note, feature, no_confluence):
             try:
                 manifest     = read_manifest() or {}
                 feature_name = feature or (manifest.get("project") or {}).get("feature", "")
-                title = _push_doc_page(doc, md_path, feature_name)
-                if title:
+                pushed = _push_doc_page(doc, md_path, feature_name)
+                if pushed:
+                    title, _page_url = pushed
                     console.print(f"  [green]✓[/green]  Confluence page updated: [cyan]{title}[/cyan]")
                 else:
                     console.print("  [dim]·  Confluence not configured — page not updated[/dim]")
@@ -1234,31 +1447,21 @@ def review_apply(doc, profile, feature):
         console.print(f"  [red]✗  '{doc}' not found in document_reviews[/red]")
         raise SystemExit(1)
 
-    project_name = proj.get("name", "Project")
-
     jira_client = JiraClient(session, prof.base_url)
-    cf_client   = ConfluenceClient(session, prof.base_url)
 
-    # Re-push updated doc
+    # Re-push updated doc (picks up the Jira link/status banner automatically,
+    # since the review ticket from the original `sdd review submit` already exists)
     try:
         md_path = resolve_doc_path(doc, feature_name)
     except ValueError as e:
         console.print(f"  [red]✗  {e}[/red]")
         raise SystemExit(1)
-    page_url     = ""
+    page_url = ""
     if md_path.exists():
-        page_title = doc_cfg.confluence_page.replace("{project}", project_name).replace("{feature}", feature_name)
-        body_html, attachments, diagram_warnings = md_to_storage(md_path.read_text(), cfg.confluence.diagrams)
-        from sdd.commands.confluence import resolve_doc_parent_id, upload_diagram_attachments
-        parent_id = resolve_doc_parent_id(cf_client, cfg.confluence, project_name, feature_name, doc)
-        page, _    = cf_client.upsert_page(
-            cfg.confluence.space_key, page_title, body_html, parent_id,
-        )
-        upload_diagram_attachments(cf_client, page["id"], attachments)
-        page_url = f"{prof.base_url}/wiki{page.get('_links', {}).get('webui', '')}"
-        console.print(f"  [green]✓[/green]  Confluence updated: [cyan]{page_title}[/cyan]")
-        for w in diagram_warnings:
-            console.print(f"  [yellow]!  {w}[/yellow]")
+        pushed = _push_doc_page(doc, md_path, feature_name)
+        if pushed:
+            page_title, page_url = pushed
+            console.print(f"  [green]✓[/green]  Confluence updated: [cyan]{page_title}[/cyan]")
     else:
         console.print(f"  [dim]·[/dim]  {md_path} not found — skipping Confluence update")
 
@@ -1338,7 +1541,7 @@ def review_status(profile, feature):
                 icon, label, style = "🔒", "Blocked", "dim"
                 all_statuses[key] = "BLOCKED"
             else:
-                st, _ = _get_review_status(key, client, cfg.jira.key_for("review"), cfg, feature_name)
+                st, _, _ = _get_review_status(key, client, cfg.jira.key_for("review"), cfg, feature_name)
                 all_statuses[key] = st
                 if st == "APPROVED":
                     icon, label, style = "✓ ", "Approved",       "green"

{sddflow-2.7.58 → sddflow-2.7.60}/sdd/commands/upgrade.py

@@ -2306,6 +2306,80 @@ MIGRATIONS = [
         ],
         "migrate": lambda m: {**m, "sdd_version": "2.7.58"},
     },
+    {
+        "from":        "2.7.58",
+        "to":          "2.7.59",
+        "description": "Feature: Confluence pages for documents under Jira review now show a live Jira link + status banner, and page_map covers every generated doc type (qa-testcases, tasks, checklist, and the living/service docs) -- no manifest schema changes",
+        "notes": [
+            "User asked why a doc pushed to Jira for review didn't also "
+            "get its Confluence page stamped with the ticket link/status "
+            "so a reviewer could see it without leaving Confluence -- the "
+            "page only ever mirrored the .md content, never the Jira "
+            "state, since the two pushes happened in unrelated code paths",
+            "sdd review submit/check/apply now prepend a small info/"
+            "success/warning panel (via the new _push_doc_page banner) "
+            "showing the ticket key, link, and live status (Pending/"
+            "Needs Revision/Approved) -- refreshed every time the CLI "
+            "touches that document's review state, so it never goes "
+            "stale between submit and the reviewer's eventual decision",
+            "Only applies to doc keys with a document_reviews entry (i.e. "
+            "actually under Jira review) -- docs pushed via the page_map "
+            "fallback alone (no Jira gate configured) get a plain page, "
+            "same as before",
+            "User also asked for a Confluence page for 'QA test case etc "
+            "-- whatever there in local md file' -- page_map in "
+            "integrations.yml.example now also covers qa-testcases, "
+            "tasks, checklist, and the 4 living/service-level docs "
+            "(data-model, security-design, api-spec, component-library), "
+            "so `sdd confluence push --doc <key>` works for all of them, "
+            "not just the phase-gated documents",
+            "6 new tests: banner HTML per status, submit stamps a Pending "
+            "banner once the ticket exists, check refreshes an existing "
+            "page to Approved, and the page_map fallback path (no Jira "
+            "gate) omits the banner entirely",
+            "This migration only bumps sdd_version -- no manifest.yml "
+            "field changes for any pack",
+        ],
+        "migrate": lambda m: {**m, "sdd_version": "2.7.59"},
+    },
+    {
+        "from":        "2.7.59",
+        "to":          "2.7.60",
+        "description": "Feature: clarify.md's own open items (AMB/GAP/CON/ASM/OQ/R) can now be pushed to Jira/Confluence for answers via sdd review push-questions/pull-answers, the same way validate.md's [NEEDS CLARIFICATION-NNN] markers already could -- no manifest schema changes",
+        "notes": [
+            "User pointed out that /validate's open questions could already "
+            "be answered via Jira (push-questions/pull-answers), but /clarify's "
+            "8-item report had no such path -- push-questions silently found "
+            "nothing to push because it only ever recognized the "
+            "'{doc}:NC-{NNN}' bracketed-marker scheme, not clarify.md's own "
+            "STATUS TABLE (AMB/GAP/CON/ASM/OQ/R rows)",
+            "Added a parallel parse/patch path scoped to --doc clarify: "
+            "_parse_clarify_open_items reads OPEN STATUS TABLE rows (posting "
+            "each item's full section as the Jira question text), "
+            "_parse_clarify_answers reads 'clarify:AMB-001: <answer>'-style "
+            "replies, and _patch_clarify_item fills the item's {FILL...} "
+            "placeholder and flips its STATUS TABLE row to the terminal "
+            "status for its type (RESOLVED for AMB/GAP/R, CORRECTED for CON, "
+            "DECIDED for OQ, CONFIRMED/CORRECTED for ASM depending on "
+            "whether the answer starts with 'yes')",
+            "review_push_questions/review_pull_answers now branch on "
+            "doc == 'clarify' for parsing/patching only -- the surrounding "
+            "Jira ticket creation, idempotency-label reuse, and Confluence "
+            "re-push logic is unchanged and fully shared with the existing "
+            "NC-NNN path",
+            "clarify.prompt.md (all 5 packs) documents this under 'Accepted "
+            "reply forms'; review-gates.md's shared block gained a matching "
+            "paragraph, synced into every pack's CLAUDE.md",
+            "16 new tests: STATUS TABLE parsing (including skipping already-"
+            "resolved rows), answer-line parsing, placeholder fill + "
+            "per-type status flip (all 5 terminal statuses, including both "
+            "ASM branches), and end-to-end push-questions/pull-answers CLI "
+            "coverage including the Confluence re-push",
+            "This migration only bumps sdd_version -- no manifest.yml "
+            "field changes for any pack",
+        ],
+        "migrate": lambda m: {**m, "sdd_version": "2.7.60"},
+    },
 ]
 
 

{sddflow-2.7.58 → sddflow-2.7.60}/sdd/packs/sdd-backend-service/.github/prompts/clarify.prompt.md

@@ -43,6 +43,17 @@ Rules:
 - User edits `clarify.md` directly, then says "done" in chat
 - **"best guess"** / **"continue with best guess"** / **"continue"** — AI applies its best judgment for every unanswered item
 
+**Items can also be answered via Jira/Confluence instead of chat (if `document_reviews.clarify` is configured in `.specify/integrations.yml`), the same way validate.md's `[NEEDS CLARIFICATION-NNN]` markers already can:**
+```bash
+sdd review push-questions --doc clarify   # push all OPEN items to Jira + Confluence
+# reviewer replies as a comment, one line per item:
+#   clarify:AMB-001: Intentional split — clearing_ref is the JSON field, clearingRef is the DB column
+sdd review pull-answers --doc clarify     # pull replies, fill {FILL...} placeholders,
+                                           # flip each STATUS TABLE row (Step 2's mapping),
+                                           # then continue at Step 3
+```
+Same idempotent-ticket behavior as validate.md: `push-questions` creates one Jira ticket reusing the label `sdd review submit` will later find, so it evolves in place at Step 6 instead of duplicating.
+
 ## After Human Fills Answers
 
 ### Step 1 — Read the FULL clarify.md

{sddflow-2.7.58/sdd/packs/sdd-frontend-spa → sddflow-2.7.60/sdd/packs/sdd-backend-service}/.specify/integrations.yml.example

@@ -198,6 +198,13 @@ confluence:
     validate:  "{feature} — Validation Report"
     analyze:   "{feature} — Analysis Report"
     clarify:   "{feature} — Clarifications"
+    tasks:     "{feature} — Tasks"
+    checklist: "{feature} — QA Checklist"
+    qa-testcases: "{feature} — QA Test Cases"
+    data-model:        "Data Model"          # living — no {feature}, nests under {project}
+    security-design:   "Security Design"     # living — no {feature}, nests under {project}
+    api-spec:          "API Specification"   # living — no {feature}, nests under {project}
+    component-library: "Component Library"   # living — no {feature}, nests under {project}
     # release:  "{feature} — Release Notes"
 
   # Diagram rendering: Confluence has NO native Mermaid or PlantUML