sddflow 2.7.59__tar.gz → 2.7.60__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sddflow
-Version: 2.7.59
+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.59 → sddflow-2.7.60}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sddflow"
-version = "2.7.59"
+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.59 → sddflow-2.7.60}/sdd/commands/review.py

@@ -473,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*')
 
 
@@ -810,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:
@@ -856,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 = {
@@ -900,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()
 
 
@@ -938,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")
@@ -986,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)
 
@@ -1001,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)

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

@@ -2342,6 +2342,44 @@ MIGRATIONS = [
         ],
         "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.59 → 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.59 → sddflow-2.7.60}/sdd/packs/sdd-backend-service/.specify/manifest.yml

@@ -43,5 +43,5 @@ testing_style: "paired"
 # If using sdd-universal instead, set project_type: "backend-service" in its manifest.yml
 # project_type: "backend-service"
 
-sdd_version: "2.7.59"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.60"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-backend-service/CLAUDE.md

@@ -368,6 +368,15 @@ reads reviewer replies (a comment starting with the item's ID, e.g.
 source document, bumping that document's version, and re-pushes that
 document's own Confluence page immediately so it never goes stale.
 
+**`clarify.md`'s own items (AMB/GAP/CON/ASM/OQ/R) work the same way**, via
+the same two commands and the same doc key (`--doc clarify`) — even though
+they're tracked by a STATUS TABLE row rather than a bracketed marker.
+Reviewer replies as `clarify:AMB-001: <answer>`; pulling answers fills the
+item's `{FILL...}` placeholder and flips its STATUS TABLE row to the
+correct terminal status for its type (RESOLVED / CONFIRMED / DECIDED /
+CORRECTED), then re-pushes clarify.md's own Confluence page. See
+`clarify.prompt.md`'s "Accepted reply forms."
+
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —
 increment the document's `Version:` header and append a row to its

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-backend-service/HOW-TO-USE.md

@@ -757,6 +757,16 @@ that document's own Confluence page immediately so it never goes stale.
 Safe to call `pull-answers` unconditionally (e.g. every time you re-run
 `/validate`) — it's a no-op when there's nothing new.
 
+`clarify.md`'s own open items (AMB/GAP/CON/ASM/OQ/R) work the same way, even though they're tracked by a STATUS TABLE row instead of a `[NEEDS CLARIFICATION-NNN]` marker:
+```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 — keep both fields
+sdd review pull-answers --doc clarify     # fills {FILL...}, flips each STATUS
+                                           # TABLE row (RESOLVED/CONFIRMED/DECIDED/
+                                           # CORRECTED per item type), re-pushes Confluence
+```
+
 ---
 
 ## Scope Presets

{sddflow-2.7.59/sdd/packs/sdd-fullstack → sddflow-2.7.60/sdd/packs/sdd-frontend-spa}/.github/prompts/clarify.prompt.md

@@ -41,6 +41,17 @@ Do NOT proceed to PLAN until all items resolved (by human or best guess).
 - 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.59 → sddflow-2.7.60}/sdd/packs/sdd-frontend-spa/.specify/manifest.yml

@@ -32,5 +32,5 @@ testing_style: "paired"
 # If using sdd-universal instead, set project_type: "frontend-spa" in its manifest.yml
 # project_type: "frontend-spa"
 
-sdd_version: "2.7.59"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.60"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-frontend-spa/CLAUDE.md

@@ -360,6 +360,15 @@ reads reviewer replies (a comment starting with the item's ID, e.g.
 source document, bumping that document's version, and re-pushes that
 document's own Confluence page immediately so it never goes stale.
 
+**`clarify.md`'s own items (AMB/GAP/CON/ASM/OQ/R) work the same way**, via
+the same two commands and the same doc key (`--doc clarify`) — even though
+they're tracked by a STATUS TABLE row rather than a bracketed marker.
+Reviewer replies as `clarify:AMB-001: <answer>`; pulling answers fills the
+item's `{FILL...}` placeholder and flips its STATUS TABLE row to the
+correct terminal status for its type (RESOLVED / CONFIRMED / DECIDED /
+CORRECTED), then re-pushes clarify.md's own Confluence page. See
+`clarify.prompt.md`'s "Accepted reply forms."
+
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —
 increment the document's `Version:` header and append a row to its

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-frontend-spa/HOW-TO-USE.md

@@ -761,6 +761,16 @@ that document's own Confluence page immediately so it never goes stale.
 Safe to call `pull-answers` unconditionally (e.g. every time you re-run
 `/validate`) — it's a no-op when there's nothing new.
 
+`clarify.md`'s own open items (AMB/GAP/CON/ASM/OQ/R) work the same way, even though they're tracked by a STATUS TABLE row instead of a `[NEEDS CLARIFICATION-NNN]` marker:
+```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 — keep both fields
+sdd review pull-answers --doc clarify     # fills {FILL...}, flips each STATUS
+                                           # TABLE row (RESOLVED/CONFIRMED/DECIDED/
+                                           # CORRECTED per item type), re-pushes Confluence
+```
+
 ---
 
 ## Scope Presets

{sddflow-2.7.59/sdd/packs/sdd-frontend-spa → sddflow-2.7.60/sdd/packs/sdd-fullstack}/.github/prompts/clarify.prompt.md

@@ -41,6 +41,17 @@ Do NOT proceed to PLAN until all items resolved (by human or best guess).
 - 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.59 → sddflow-2.7.60}/sdd/packs/sdd-fullstack/.specify/manifest.yml

@@ -32,5 +32,5 @@ testing_style: "paired"
 # If using sdd-universal instead, set project_type: "fullstack" in its manifest.yml
 # project_type: "fullstack"
 
-sdd_version: "2.7.59"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.60"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-fullstack/CLAUDE.md

@@ -386,6 +386,15 @@ reads reviewer replies (a comment starting with the item's ID, e.g.
 source document, bumping that document's version, and re-pushes that
 document's own Confluence page immediately so it never goes stale.
 
+**`clarify.md`'s own items (AMB/GAP/CON/ASM/OQ/R) work the same way**, via
+the same two commands and the same doc key (`--doc clarify`) — even though
+they're tracked by a STATUS TABLE row rather than a bracketed marker.
+Reviewer replies as `clarify:AMB-001: <answer>`; pulling answers fills the
+item's `{FILL...}` placeholder and flips its STATUS TABLE row to the
+correct terminal status for its type (RESOLVED / CONFIRMED / DECIDED /
+CORRECTED), then re-pushes clarify.md's own Confluence page. See
+`clarify.prompt.md`'s "Accepted reply forms."
+
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —
 increment the document's `Version:` header and append a row to its

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-fullstack/HOW-TO-USE.md

@@ -763,6 +763,16 @@ that document's own Confluence page immediately so it never goes stale.
 Safe to call `pull-answers` unconditionally (e.g. every time you re-run
 `/validate`) — it's a no-op when there's nothing new.
 
+`clarify.md`'s own open items (AMB/GAP/CON/ASM/OQ/R) work the same way, even though they're tracked by a STATUS TABLE row instead of a `[NEEDS CLARIFICATION-NNN]` marker:
+```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 — keep both fields
+sdd review pull-answers --doc clarify     # fills {FILL...}, flips each STATUS
+                                           # TABLE row (RESOLVED/CONFIRMED/DECIDED/
+                                           # CORRECTED per item type), re-pushes Confluence
+```
+
 ---
 
 ## Scope Presets

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-mobile/.github/prompts/clarify.prompt.md

@@ -41,6 +41,17 @@ Do NOT proceed to PLAN until all items resolved (by human or best guess).
 - 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.59 → sddflow-2.7.60}/sdd/packs/sdd-mobile/.specify/manifest.yml

@@ -32,5 +32,5 @@ testing_style: "paired"
 # If using sdd-universal instead, set project_type: "mobile" in its manifest.yml
 # project_type: "mobile"
 
-sdd_version: "2.7.59"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.60"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-mobile/CLAUDE.md

@@ -359,6 +359,15 @@ reads reviewer replies (a comment starting with the item's ID, e.g.
 source document, bumping that document's version, and re-pushes that
 document's own Confluence page immediately so it never goes stale.
 
+**`clarify.md`'s own items (AMB/GAP/CON/ASM/OQ/R) work the same way**, via
+the same two commands and the same doc key (`--doc clarify`) — even though
+they're tracked by a STATUS TABLE row rather than a bracketed marker.
+Reviewer replies as `clarify:AMB-001: <answer>`; pulling answers fills the
+item's `{FILL...}` placeholder and flips its STATUS TABLE row to the
+correct terminal status for its type (RESOLVED / CONFIRMED / DECIDED /
+CORRECTED), then re-pushes clarify.md's own Confluence page. See
+`clarify.prompt.md`'s "Accepted reply forms."
+
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —
 increment the document's `Version:` header and append a row to its

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-mobile/HOW-TO-USE.md

@@ -761,6 +761,16 @@ that document's own Confluence page immediately so it never goes stale.
 Safe to call `pull-answers` unconditionally (e.g. every time you re-run
 `/validate`) — it's a no-op when there's nothing new.
 
+`clarify.md`'s own open items (AMB/GAP/CON/ASM/OQ/R) work the same way, even though they're tracked by a STATUS TABLE row instead of a `[NEEDS CLARIFICATION-NNN]` marker:
+```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 — keep both fields
+sdd review pull-answers --doc clarify     # fills {FILL...}, flips each STATUS
+                                           # TABLE row (RESOLVED/CONFIRMED/DECIDED/
+                                           # CORRECTED per item type), re-pushes Confluence
+```
+
 ---
 
 ## Scope Presets

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-universal/.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.59 → sddflow-2.7.60}/sdd/packs/sdd-universal/.specify/manifest.yml

@@ -38,5 +38,5 @@ plan_mode: "unified"
 #   bdd:    Given/When/Then specs drive tests, written before implementation
 testing_style: "paired"
 
-sdd_version: "2.7.59"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.60"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-universal/CLAUDE.md

@@ -354,6 +354,15 @@ reads reviewer replies (a comment starting with the item's ID, e.g.
 source document, bumping that document's version, and re-pushes that
 document's own Confluence page immediately so it never goes stale.
 
+**`clarify.md`'s own items (AMB/GAP/CON/ASM/OQ/R) work the same way**, via
+the same two commands and the same doc key (`--doc clarify`) — even though
+they're tracked by a STATUS TABLE row rather than a bracketed marker.
+Reviewer replies as `clarify:AMB-001: <answer>`; pulling answers fills the
+item's `{FILL...}` placeholder and flips its STATUS TABLE row to the
+correct terminal status for its type (RESOLVED / CONFIRMED / DECIDED /
+CORRECTED), then re-pushes clarify.md's own Confluence page. See
+`clarify.prompt.md`'s "Accepted reply forms."
+
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —
 increment the document's `Version:` header and append a row to its

{sddflow-2.7.59 → sddflow-2.7.60}/sdd/packs/sdd-universal/HOW-TO-USE.md

@@ -770,6 +770,16 @@ that document's own Confluence page immediately so it never goes stale.
 Safe to call `pull-answers` unconditionally (e.g. every time you re-run
 `/validate`) — it's a no-op when there's nothing new.
 
+`clarify.md`'s own open items (AMB/GAP/CON/ASM/OQ/R) work the same way, even though they're tracked by a STATUS TABLE row instead of a `[NEEDS CLARIFICATION-NNN]` marker:
+```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 — keep both fields
+sdd review pull-answers --doc clarify     # fills {FILL...}, flips each STATUS
+                                           # TABLE row (RESOLVED/CONFIRMED/DECIDED/
+                                           # CORRECTED per item type), re-pushes Confluence
+```
+
 ---
 
 ## Scope Presets

sddflow-2.7.59/sdd/__init__.py

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