sddflow 2.7.55__tar.gz → 2.7.59__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sddflow
-Version: 2.7.55
+Version: 2.7.59
 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
@@ -447,7 +447,12 @@ History` row. A question asked in more than one document (the table's
 `Locations` column lists more than one ID, e.g. `brd:NC-003, srd:NC-001`)
 gets the same answer applied everywhere at once. Safe to call
 unconditionally (e.g. at the top of every `/validate` run) — it exits
-quietly whenever there's nothing to do.
+quietly whenever there's nothing to do. If a document predates
+`[NEEDS CLARIFICATION-NNN]` numbering and still has the old unnumbered
+`[NEEDS CLARIFICATION: ...]` form, `pull-answers` retroactively numbers it
+first, in order of appearance, before patching. Each patched document's
+own Confluence page (when `confluence:` is configured) is also re-pushed
+immediately, so it never goes stale relative to the answered `.md`.
 
 ---
 

{sddflow-2.7.55 → sddflow-2.7.59}/README.md

@@ -412,7 +412,12 @@ History` row. A question asked in more than one document (the table's
 `Locations` column lists more than one ID, e.g. `brd:NC-003, srd:NC-001`)
 gets the same answer applied everywhere at once. Safe to call
 unconditionally (e.g. at the top of every `/validate` run) — it exits
-quietly whenever there's nothing to do.
+quietly whenever there's nothing to do. If a document predates
+`[NEEDS CLARIFICATION-NNN]` numbering and still has the old unnumbered
+`[NEEDS CLARIFICATION: ...]` form, `pull-answers` retroactively numbers it
+first, in order of appearance, before patching. Each patched document's
+own Confluence page (when `confluence:` is configured) is also re-pushed
+immediately, so it never goes stale relative to the answered `.md`.
 
 ---
 

{sddflow-2.7.55 → sddflow-2.7.59}/pyproject.toml

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

sddflow-2.7.59/sdd/__init__.py

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

{sddflow-2.7.55 → sddflow-2.7.59}/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.55 → sddflow-2.7.59}/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)
 
 
@@ -527,7 +574,7 @@ def review_command():
 
 @review_command.command("submit")
 @click.option("--doc",     required=True,
-              help="Document key: brd, use-cases, srd, design (unified) / arch, hld, adr (separate), lld, tasks, runbook, release")
+              help="Document key: brd, use-cases, srd, design (unified) / arch, hld, adr (separate), validate, analyze, clarify, lld, tasks, runbook, release")
 @click.option("--profile", default=None)
 @click.option("--feature", default=None)
 def review_submit(doc, profile, feature):
@@ -688,6 +735,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)
 
@@ -774,7 +831,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]")
 
@@ -932,6 +991,7 @@ def review_pull_answers(doc, profile, feature):
         raise SystemExit(0)
 
     patched_docs: dict[str, int] = {}
+    patched_paths: dict[str, Path] = {}
     for item in items:
         # The reviewer only ever cites the row's primary ID (item["id"]) --
         # that single answer must propagate to every location listed for
@@ -950,6 +1010,7 @@ def review_pull_answers(doc, profile, feature):
                 continue
             if _patch_marker(loc_path, nnn, answer_text):
                 patched_docs[doc_key] = patched_docs.get(doc_key, 0) + 1
+                patched_paths[doc_key] = loc_path
                 console.print(f"  [green]✓[/green]  {loc_id} resolved in {loc_path.name}")
 
     if patched_docs:
@@ -960,6 +1021,25 @@ def review_pull_answers(doc, profile, feature):
         )
         console.print()
 
+        # Re-push each patched doc's own Confluence page so it doesn't go
+        # stale relative to the .md file we just edited. Until now,
+        # pull-answers only ever wrote the local file -- BRD/SRD/UC's
+        # Confluence pages (created back at their own /specify-brd ->
+        # `sdd review submit` time) kept showing the pre-answer
+        # [NEEDS CLARIFICATION] markers even after every question was
+        # resolved here. Best-effort per doc: one page's failure doesn't
+        # block the others or the patching that already succeeded.
+        if cfg.confluence:
+            for doc_key, loc_path in patched_paths.items():
+                try:
+                    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]")
+            console.print()
+
 
 # ── sdd review check ───────────────────────────────────────────────────────────
 
@@ -1010,10 +1090,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()
@@ -1095,7 +1187,7 @@ def review_comments(doc, feature, ack):
 
 @review_command.command("approve")
 @click.option("--doc",      required=True,
-              help="Document key: brd, use-cases, srd, design (unified) / arch, hld, adr (separate), lld, ...")
+              help="Document key: brd, use-cases, srd, design (unified) / arch, hld, adr (separate), validate, analyze, clarify, lld, ...")
 @click.option("--local",    is_flag=True, required=True,
               help="Write a local approval record (fallback when Jira is not configured)")
 @click.option("--by",       default="chat",
@@ -1144,8 +1236,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]")
@@ -1214,31 +1307,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")
 
@@ -1318,7 +1401,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.55 → sddflow-2.7.59}/sdd/commands/upgrade.py

@@ -2204,6 +2204,144 @@ MIGRATIONS = [
         ],
         "migrate": lambda m: {**m, "sdd_version": "2.7.55"},
     },
+    {
+        "from":        "2.7.55",
+        "to":          "2.7.56",
+        "description": "Fix: sdd review pull-answers patched BRD/SRD/UC locally but never refreshed their existing Confluence pages, leaving them showing stale pre-answer [NEEDS CLARIFICATION] markers -- no manifest schema changes",
+        "notes": [
+            "User-reported: after /validate's push-questions/pull-answers "
+            "round-trip resolved every open question, brd.md/srd.md/"
+            "use-cases.md were updated on disk and their versions bumped, "
+            "but their Confluence pages (created back at their own "
+            "/specify-brd -> sdd review submit time) still showed the old "
+            "unresolved markers -- only validate.md's own page was ever "
+            "touched by push-questions/pull-answers",
+            "review_pull_answers now tracks the on-disk path of every doc "
+            "it successfully patches, and after the patch loop, re-pushes "
+            "each one's Confluence page via the same _push_doc_page() "
+            "helper sdd review approve already uses -- best-effort per "
+            "doc, so one page's failure never blocks the others or the "
+            "patching that already succeeded",
+            "Only runs when confluence: is configured in integrations.yml; "
+            "silently skipped otherwise, matching the rest of "
+            "pull-answers' safe-to-call-unconditionally contract",
+            "1 new test: push-questions -> answer -> pull-answers, "
+            "confirming both patched docs' Confluence pages are created/"
+            "updated with the expected page-map titles",
+            "This migration only bumps sdd_version -- no manifest.yml "
+            "field changes for any pack",
+        ],
+        "migrate": lambda m: {**m, "sdd_version": "2.7.56"},
+    },
+    {
+        "from":        "2.7.56",
+        "to":          "2.7.57",
+        "description": "Guardrail: validate.prompt.md Step C no longer lets a document-level approval auto-check per-item §1-§4 confirmation checkboxes -- no manifest schema changes",
+        "notes": [
+            "User-reported (from a live project's /analyze run): a prior "
+            "agent session, chasing the analyze.prompt.md verify gate's "
+            "literal 'VALIDATE complete' string, bulk-checked every "
+            "unchecked box in validate.md's §1 (Reviewer Confirms), §2 "
+            "(BA/PO Confirms), §3 (assumption Correct?), §3a (UC Business "
+            "Scenario Correct?), and §4 (Scope Confirmation) -- inferring "
+            "itemized per-line business sign-off purely from the "
+            "document's overall Jira ticket having been closed after a "
+            "Q&A comment thread, which is not the same as a named "
+            "reviewer actually addressing that specific item",
+            "validate.prompt.md's own Step C only ever specified updating "
+            "the header (Status: Draft -> Approved) and the §5 Approvals "
+            "table -- the agent's bulk-check of §1-§4 was not something "
+            "the prompt told it to do; this migration tightens the "
+            "wording to explicitly forbid it and to say what to do "
+            "instead (leave unchecked with a note, or point to the "
+            "specific reviewer statement that confirmed that exact item)",
+            "This matters most for regulated/financial-transfer features "
+            "where §1-§4's checkboxes are meant to be a traceable, "
+            "defensible audit trail of actual line-item business review "
+            "-- not a formality that gets rubber-stamped to satisfy a "
+            "downstream gate's string match",
+            "Applied identically to validate.prompt.md in all 5 packs "
+            "(not a shared/blocks file -- each pack's copy edited "
+            "individually, same wording)",
+            "This migration only bumps sdd_version -- no manifest.yml "
+            "field changes for any pack",
+        ],
+        "migrate": lambda m: {**m, "sdd_version": "2.7.57"},
+    },
+    {
+        "from":        "2.7.57",
+        "to":          "2.7.58",
+        "description": "Feature: analyze.md and clarify.md can now go through the same Jira/Confluence review-gate flow as brd/srd/etc (a new 'validate' phase) -- no manifest schema changes",
+        "notes": [
+            "User asked why /analyze and /clarify never got pushed to "
+            "Confluence/Jira the way /validate does -- by design they "
+            "were chat-only working documents, but nothing in "
+            "resolve_doc_path/review_submit/review_approve actually "
+            "required that; they're fully generic by doc key",
+            "Added document_reviews.validate/.analyze/.clarify entries "
+            "to integrations.yml.example (phase: validate, sequence "
+            "1/2/3 -- validate before analyze before clarify, enforced "
+            "by the same predecessor-sequence gate every other phase "
+            "already uses), plus matching page_map entries",
+            "analyze.prompt.md and clarify.prompt.md (all 5 packs) gained "
+            "the same Stakeholder Review and Approval Step B/C section "
+            "validate.prompt.md already has -- sdd review submit/check/"
+            "approve, same approval-signal handling, same guardrail "
+            "against inferring per-section findings as individually "
+            "confirmed by a document-level approval",
+            "Fixed clarify-template.md's header, which said "
+            "'Status: OPEN' instead of 'Status: Draft' -- "
+            "_mark_md_approved's regex only recognizes Draft/Proposed, "
+            "so the approval flip would have silently never updated the "
+            "header for clarify.md without this fix",
+            "Each of validate/analyze/clarify is optional individually -- "
+            "add only the ones you want routed through Jira/Confluence; "
+            "the rest stay chat-only, per review-gates.md",
+            "4 new tests: generic submit works for analyze/clarify doc "
+            "keys, the validate-phase sequence gate blocks analyze until "
+            "validate is approved, and the clarify.md header fix is "
+            "confirmed to make the approval flow work end-to-end",
+            "This migration only bumps sdd_version -- no manifest.yml "
+            "field changes for any pack",
+        ],
+        "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"},
+    },
 ]
 
 

{sddflow-2.7.55 → sddflow-2.7.59}/sdd/packs/sdd-backend-service/.github/prompts/analyze.prompt.md

@@ -79,6 +79,54 @@ CF-NNN IDs. Include in analyze.summary.md:
 
 - Save to: .specify/features/{manifest.project.feature}/analyze.md
 - Save summary to: analyze.summary.md (max SUMMARY_MAX_LINES)
+- Present the report.
+
+### Stakeholder Review and Approval
+
+**Step B — Formal submission**
+
+If `.specify/integrations.yml` has `document_reviews.analyze` configured:
+```bash
+sdd review submit --doc analyze
+```
+If the command succeeds, tell the user:
+> "Analysis report submitted for Jira review. Reply **'approved'** (or 'yes', 'LGTM', 'looks good') once the Tech Lead approves."
+
+If the CLI fails or is not configured, present the document and ask:
+> "Analysis report generated. Review §1–§9 above and reply **'approved'** (or 'yes', 'LGTM', 'looks good') to continue, or provide feedback:"
+
+**Step C — On approval (any path: Jira or chat)**
+
+When the user replies with any approval signal — **'approved'**, **'approve'**, **'yes'**, **'LGTM'**, **'looks good'**, **'go ahead'**, **'confirmed'**, or any similar affirmative (case-insensitive):
+1. Run `sdd review check --doc analyze` to verify:
+   - Exit 0 → confirmed. Proceed.
+   - Non-0 and CLI is configured → warn: "Jira shows not yet approved. Confirm you want to proceed? (yes/no)" — wait for response.
+   - CLI not available → skip check and proceed.
+2. Update `analyze.md`:
+   - Header: `Status: Draft` → `Status: Approved`, date → today.
+   - Approvals table: all Pending rows → `Approved` + today's date.
+   - Version History: append a row using the document's **current**
+     version (a pure approval doesn't bump it):
+     `| {current version} | {today} | {jira or chat} | Approved | — |`
+   - **Never** use this document-level approval signal to also check any
+     of the per-item risk/dependency/complexity findings in §1–§9 as
+     resolved — approval here means "the analysis is sound and complete
+     enough to proceed," not that every CF-NNN finding or R-NNN risk has
+     been individually addressed. Those are tracked to closure by
+     /clarify and /task, not by this approval.
+3. Re-save `analyze.md` and regenerate `analyze.summary.md`.
+4. Ask once: "Recording the approval — approver name/role and an optional comment?"
+   (defaults: the accountable role for this gate in roles.yml; "approved in chat")
+5. Record locally and sync Confluence:
+```bash
+sdd review approve --doc analyze --local --by "{approver}" --note "{comment}"
+```
+This also updates the document's existing Confluence page when a `confluence:`
+section exists in `.specify/integrations.yml`.
+If the command fails or the CLI is not installed, note: "Analyze approved ✓
+(Confluence page not updated)" and continue — the `Status: Approved` header is
+the authoritative gate.
+
 <!-- shared:token-usage-log-step:start -->
 ## Token Usage Logging (this command)
 Check now, with a fresh file read — not a memory of whether
@@ -93,4 +141,4 @@ update its Running Totals table. If the file still doesn't exist, skip
 this silently — do not create it and do not mention it.
 <!-- shared:token-usage-log-step:end -->
 
-- Wait for review before CLARIFY.
+- Do NOT proceed to /clarify until the approval above is recorded.

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

@@ -81,6 +81,53 @@ For each spec document with content affected by a resolved item:
 
 Write `.specify/features/{manifest.project.feature}/clarify.summary.md` — confirm all items RESOLVED. If any items were resolved by best guess, list them so the Plan-Design reviewer is aware.
 
+### Step 6 — Stakeholder Review and Approval
+
+**Step B — Formal submission**
+
+If `.specify/integrations.yml` has `document_reviews.clarify` configured:
+```bash
+sdd review submit --doc clarify
+```
+If the command succeeds, tell the user:
+> "Clarification report submitted for Jira review. Reply **'approved'** (or 'yes', 'LGTM', 'looks good') once the Architect approves."
+
+If the CLI fails or is not configured, present the document and ask:
+> "Clarification report generated — all items resolved. Review the answers above and reply **'approved'** (or 'yes', 'LGTM', 'looks good') to continue, or provide feedback:"
+
+**Step C — On approval (any path: Jira or chat)**
+
+When the user replies with any approval signal — **'approved'**, **'approve'**, **'yes'**, **'LGTM'**, **'looks good'**, **'go ahead'**, **'confirmed'**, or any similar affirmative (case-insensitive):
+1. Run `sdd review check --doc clarify` to verify:
+   - Exit 0 → confirmed. Proceed.
+   - Non-0 and CLI is configured → warn: "Jira shows not yet approved. Confirm you want to proceed? (yes/no)" — wait for response.
+   - CLI not available → skip check and proceed.
+2. Update `clarify.md`:
+   - Header: `Status: Draft` → `Status: Approved`, date → today.
+   - Approvals table: all Pending rows → `Approved` + today's date.
+   - Version History: append a row using the document's **current**
+     version (a pure approval doesn't bump it — Step 3 above already
+     bumped it when the items were resolved):
+     `| {current version} | {today} | {jira or chat} | Approved | — |`
+   - This approval confirms the Architect has reviewed the resolved
+     answers (including any best-guess items) and is satisfied to
+     proceed to /plan-design — it does not re-open, and must not be
+     used to silently overwrite, the per-item RESOLVED/CONFIRMED/
+     DECIDED/CORRECTED status already recorded in the STATUS TABLE at
+     Step 3.
+3. Re-save `clarify.md` and regenerate `clarify.summary.md`.
+4. Ask once: "Recording the approval — approver name/role and an optional comment?"
+   (defaults: the accountable role for this gate in roles.yml; "approved in chat")
+5. Record locally and sync Confluence:
+```bash
+sdd review approve --doc clarify --local --by "{approver}" --note "{comment}"
+```
+This also updates the document's existing Confluence page when a `confluence:`
+section exists in `.specify/integrations.yml`.
+If the command fails or the CLI is not installed, note: "Clarify approved ✓
+(Confluence page not updated)" and continue — the `Status: Approved` header is
+the authoritative gate.
+
 <!-- shared:token-usage-log-step:start -->
 ## Token Usage Logging (this command)
 Check now, with a fresh file read — not a memory of whether

{sddflow-2.7.55/sdd/packs/sdd-universal → sddflow-2.7.59/sdd/packs/sdd-backend-service}/.github/prompts/validate.prompt.md

@@ -155,6 +155,19 @@ When the user replies with any approval signal — **'approved'**, **'approve'**
      version (a pure approval doesn't bump it — only an assumption
      correction in §3 above does):
      `| {current version} | {today} | {jira or chat} | Approved | — |`
+   - **Never** use this document-level approval signal to also check any
+     of the per-item confirmation checkboxes in §1 (Reviewer Confirms),
+     §2 (BA Confirms / PO Confirms), §3 (Correct?), §3a (Business
+     Scenario Correct?), or §4 (Scope Confirmation). Those require the
+     named reviewer to have actually addressed that *specific* item —
+     a blanket "approved" reply, a Jira status flip to Done/Closed, or a
+     comment thread that only answered NEEDS CLARIFICATION questions is
+     not itemized evidence for them. If any of those boxes are still
+     `[ ]` when the header flips to Approved, leave them `[ ]` and add a
+     note under §5: "Approved as a whole document; items in §1–§4 were
+     not itemized during review." Only check a specific box when you can
+     point to the actual reviewer statement that confirmed that exact
+     item.
 3. Re-save `validate.md` and regenerate `validate.summary.md`.
 4. Ask once: "Recording the approval — approver name/role and an optional comment?"
    (defaults: the accountable role for this gate in roles.yml; "approved in chat")