sddflow 2.7.55__tar.gz → 2.7.58__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sddflow
-Version: 2.7.55
+Version: 2.7.58
 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.58}/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.58}/pyproject.toml

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

sddflow-2.7.58/sdd/__init__.py

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

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

@@ -527,7 +527,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):
@@ -932,6 +932,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 +951,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 +962,24 @@ 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:
+                    title = _push_doc_page(doc_key, loc_path, feature_name)
+                    if title:
+                        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 ───────────────────────────────────────────────────────────
 
@@ -1095,7 +1115,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",

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

@@ -2204,6 +2204,108 @@ 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"},
+    },
 ]
 
 

{sddflow-2.7.55 → sddflow-2.7.58}/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.58}/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.58/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")

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

@@ -195,7 +195,9 @@ confluence:
     adr:       "{feature} — Architecture Decisions" # separate plan_mode
     lld:       "{feature} — Low-Level Design"
     runbook:   "Runbook"                            # living — no {feature}, nests under {project}
-    # validate: "{feature} — Validation Report"
+    validate:  "{feature} — Validation Report"
+    analyze:   "{feature} — Analysis Report"
+    clarify:   "{feature} — Clarifications"
     # release:  "{feature} — Release Notes"
 
   # Diagram rendering: Confluence has NO native Mermaid or PlantUML
@@ -266,10 +268,12 @@ confluence:
 # docs/runbook/local-setup.md, and living/service-level documents
 # (data-model, security-design, api-spec, component-library — shared
 # across every feature in this service, see CLAUDE.md "Living
-# Documents") live at .specify/service/. This example only wires up the
-# main spec-phase gate (brd/use-cases/srd/design/lld/tasks/runbook/
-# release) — add entries here for any other document you want a Jira/
-# Confluence review gate on.
+# Documents") live at .specify/service/. This example wires up the main
+# spec-phase gate (brd/use-cases/srd/design), the validate phase
+# (validate/analyze/clarify — each optional individually, see
+# CLAUDE.md "Document Review Gates"), and lld/tasks/runbook/release —
+# add entries here for any other document you want a Jira/Confluence
+# review gate on.
 #
 # confluence_page keeps {feature} in the title for every per-feature entry
 # below, same reasoning as page_map above: `sdd review submit` nests pages
@@ -314,6 +318,33 @@ document_reviews:
     sequence:           4    # cannot submit until SRD approved
     confluence_page:    "{feature} — Design"
 
+  # ── validate phase (Validate → Analyze → Clarify) ─────────────────────────
+  # Runs after the specify phase is fully approved, before planning begins.
+  # Each of these three is optional individually — remove any entry you want
+  # to keep chat-only; only the ones present here get routed through Jira/
+  # Confluence. When present, sequence within this phase is still enforced
+  # the same way as any other phase (validate before analyze before clarify).
+  validate:
+    reviewer_jira_user: "5c7b8a2d0f3e1a4b9d6c8f21"   # PO's Jira accountId (same as brd)
+    reviewer_role:      Product Owner
+    phase:              validate
+    sequence:           1
+    confluence_page:    "{feature} — Validation Report"
+
+  analyze:
+    reviewer_jira_user: "8f0e1d5g3h6c4d7e2f9g1i54"   # Tech Lead's accountId (same as lld)
+    reviewer_role:      Tech Lead
+    phase:              validate
+    sequence:           2    # cannot submit until Validate approved
+    confluence_page:    "{feature} — Analysis Report"
+
+  clarify:
+    reviewer_jira_user: "7e9d0c4f2g5b3c6d1e8f0h43"   # Architect's accountId (same as design)
+    reviewer_role:      Architect
+    phase:              validate
+    sequence:           3    # cannot submit until Analyze approved
+    confluence_page:    "{feature} — Clarifications"
+
   # ── planning phase ────────────────────────────────────────────────────────
   # separate plan_mode only — uncomment these three (and remove design: above).
   # Order matches the prompts: /plan-arch → /plan-hld → /plan-adr → /plan-lld.

{sddflow-2.7.55 → sddflow-2.7.58}/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.55"   # set by sdd init; used by sdd upgrade
+sdd_version: "2.7.58"   # set by sdd init; used by sdd upgrade
 ai_tool: ""             # set by sdd init: claude-code | copilot | cursor | windsurf | other

{sddflow-2.7.55 → sddflow-2.7.58}/sdd/packs/sdd-backend-service/.specify/templates/clarify-template.md

@@ -1,5 +1,5 @@
 # Clarification Report — {Feature Name}
-> Version: {spec version} | Status: OPEN | Date: {date} | Author: {author}
+> Version: {spec version} | Status: Draft | Date: {date} | Author: {author}
 > Fill all answers before PLAN begins
 
 ---
@@ -85,7 +85,7 @@ All items must be resolved before PLAN begins.
 ## Approvals
 | Role | Status | Date |
 |---|---|---|
-| {Reviewer — see this command's Review: gate in CLAUDE.md} | Pending | |
+| Architect (accountable) | Pending | |
 
 ## Version History
 

{sddflow-2.7.55 → sddflow-2.7.58}/sdd/packs/sdd-backend-service/CLAUDE.md

@@ -333,6 +333,7 @@ filenames: `design` exists in unified mode; `arch`/`hld`/`adr` in separate mode.
 | Phase | Sequence (unified) | Sequence (separate) | Reviewer |
 |---|---|---|---|
 | specify | BRD → Use Cases → SRD → Design | BRD → Use Cases → SRD | PO → BA → BA → Architect |
+| validate | Validate → Analyze → Clarify | Validate → Analyze → Clarify | PO → Tech Lead → Architect |
 | planning | LLD (mvp+) | Arch → HLD → ADR (mvp+) → LLD (mvp+) | Tech Lead / Architect |
 | tasks | Tasks | Tasks | Scrum Master |
 | release | Runbook → Release | Runbook → Release | DevOps → Release Manager |
@@ -348,6 +349,13 @@ When `sdd review check` exits 1 (NEEDS REVISION): read reviewer comments, update
 the document, then run `sdd review apply` and ask reviewer to re-review.
 Configure reviewers in `.specify/integrations.yml` — see `integrations.yml.example`.
 
+**The `validate` phase is optional per-document.** Unlike the `specify`/
+`planning`/`tasks`/`release` phases, `validate`/`analyze`/`clarify` fall back
+to chat approval individually if their own `document_reviews` entry is
+missing — add `document_reviews.validate` (and/or `.analyze`, `.clarify`) to
+`integrations.yml` only for the ones you want routed through Jira/Confluence;
+the rest stay chat-only.
+
 **Blocked documents can still collect answers via Jira/Confluence.** A
 document like `validate.md` can be blocked on `[NEEDS CLARIFICATION-NNN]`
 markers in its source docs before it's ever submitted for review — see
@@ -357,7 +365,8 @@ reviewer/ticket `sdd review submit` will use once unblocked — the ticket
 evolves in place, no duplicate). `sdd review pull-answers --doc {doc}`
 reads reviewer replies (a comment starting with the item's ID, e.g.
 `brd:NC-002: 90 days`) and patches the answered marker directly into its
-source document, bumping that document's version.
+source document, bumping that document's version, and re-pushes that
+document's own Confluence page immediately so it never goes stale.
 
 **Every review-driven edit bumps the version.** Whichever mode surfaced the
 feedback — a Jira comment, a dashboard comment, or direct chat feedback —

{sddflow-2.7.55 → sddflow-2.7.58}/sdd/packs/sdd-backend-service/HOW-TO-USE.md

@@ -353,6 +353,8 @@ blank one — see "Living Documents" in `CLAUDE.md`.
 
 **Reviewer:** Product Owner + Business Analyst
 
+**Jira/Confluence:** optional — see "Document Review Workflow" below (also covers `push-questions`/`pull-answers` for collecting answers to blocking `[NEEDS CLARIFICATION-NNN]` items before the document is even submitted for review).
+
 ---
 
 ### Phase 3 — ANALYZE
@@ -379,6 +381,8 @@ blank one — see "Living Documents" in `CLAUDE.md`.
 
 **Reviewer:** Tech Lead (accountable), Architect + Security Officer (consulted)
 
+**Jira/Confluence:** optional — see "Document Review Workflow" below.
+
 ---
 
 ### Phase 4 — CLARIFY
@@ -405,6 +409,8 @@ blank one — see "Living Documents" in `CLAUDE.md`.
 
 **Reviewer:** Product Owner (accountable), Business Analyst (consulted)
 
+**Jira/Confluence:** optional — see "Document Review Workflow" below.
+
 ---
 
 ### Phase 5 — PLAN
@@ -673,7 +679,7 @@ sdd confluence push --all        # push all documents listed in integrations.yml
 ```
 Page titles come from `integrations.yml → confluence.page_map`. Re-running updates the existing page.
 
-**On a multi-feature project — living docs get ONE page, per-feature docs get one page each.** Living/service-level documents (`data-model`, `security-design`, `api-spec`, `component-library`) always resolve to a single shared page regardless of which feature is active — that's correct, since the underlying document itself is shared. Per-feature documents (`brd`, `use-cases`, `srd`, `design`/`arch`/`hld`/`adr`, `lld`, `validate`, `release`) need `{feature}` in their `page_map` title template to get a separate page per feature — the shipped `integrations.yml.example` already includes it. If your `integrations.yml` predates this and its titles don't have `{feature}`, every feature pushing the same doc type will silently overwrite the same page — add `{feature}` to those entries to fix it.
+**On a multi-feature project — living docs get ONE page, per-feature docs get one page each.** Living/service-level documents (`data-model`, `security-design`, `api-spec`, `component-library`) always resolve to a single shared page regardless of which feature is active — that's correct, since the underlying document itself is shared. Per-feature documents (`brd`, `use-cases`, `srd`, `design`/`arch`/`hld`/`adr`, `lld`, `validate`, `analyze`, `clarify`, `release`) need `{feature}` in their `page_map` title template to get a separate page per feature — the shipped `integrations.yml.example` already includes it. If your `integrations.yml` predates this and its titles don't have `{feature}`, every feature pushing the same doc type will silently overwrite the same page — add `{feature}` to those entries to fix it.
 
 ---
 
@@ -717,6 +723,36 @@ usage per feature, plus Approve/comment buttons that update the same
 
 Configure reviewers (Jira accountId per document) in `.specify/integrations.yml`. Run `sdd config init` to generate this file interactively, or copy `.specify/integrations.yml.example` and edit it.
 
+**`/validate`, `/analyze`, and `/clarify` can go through this same jira-mode
+flow — each is optional individually.** Add `document_reviews.validate`
+(and/or `.analyze`, `.clarify`) to `integrations.yml` for whichever of the
+three you want routed through Jira/Confluence — they form their own
+`validate` phase (Validate → Analyze → Clarify), sequence-gated the same
+way BRD → Use Cases → SRD is. Leave any of the three out and it stays
+chat-only, no config change needed elsewhere.
+
+**A document can collect answers via Jira/Confluence before it's even
+submitted for review.** `validate.md` (and any doc with the same
+`[NEEDS CLARIFICATION-NNN]` marker pattern) can be *blocked* on open
+questions in its source docs — `/validate`'s own scan lists them. Rather
+than waiting for a formal review round, push those specific questions out
+now:
+```bash
+sdd review push-questions --doc validate   # push open items to Jira + Confluence
+# reviewer replies as a comment, one line per item:
+#   brd:NC-002: 90 days, per data retention policy DR-014
+sdd review pull-answers --doc validate     # pull replies, patch the answered markers
+```
+`push-questions` creates (or updates, if one already exists) **one** Jira
+ticket — reusing the same reviewer/ticket `sdd review submit` will use
+once the document unblocks, so it evolves in place rather than duplicating.
+`pull-answers` reads back replies matching `{doc}:NC-{NNN}: {answer}`,
+patches each answered marker directly into its source document (bumping
+that document's version), and — if `confluence:` is configured — re-pushes
+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.
+
 ---
 
 ## Scope Presets

{sddflow-2.7.55 → sddflow-2.7.58}/sdd/packs/sdd-backend-service/PROMPT-GUIDE.md

@@ -556,7 +556,12 @@ Produce:
      business owner to confirm or reject.
   3a. NEEDS CLARIFICATION SCAN — scan brd/use-cases/srd for [NEEDS
       CLARIFICATION] markers; these are BLOCKING — must be resolved
-      before sign-off.
+      before sign-off. If document_reviews.validate is configured, run
+      `sdd review pull-answers --doc validate` first (patches any new
+      Jira/Confluence replies into the source docs), then
+      `sdd review push-questions --doc validate` for whatever's still
+      open — lets the reviewer answer via a Jira/Confluence comment
+      before validate.md is even submitted for formal review.
   4. SCOPE CONFIRMATION — in-scope / out-of-scope items from brd.md.
   4a. SECURITY DESIGN SIGN-OFF (mvp+) — if security-design.md exists and
       is not yet signed off, block /analyze until the Security Officer
@@ -567,6 +572,9 @@ Produce:
      Approved / Changes Requested.
 
 Save: validate.md + validate.summary.md
+Stakeholder review (Confluence/Jira submit if document_reviews.validate
+configured, else chat approval → Status: Approved + Approvals table +
+Version History).
 Present report. WAIT for sign-off.
 
 If approved:
@@ -613,6 +621,8 @@ Produce:
     Suggested approach, items for /clarify, tasks likely needing SPLIT
 
 Save: analyze.md + analyze.summary.md
+Stakeholder review (Confluence/Jira submit if document_reviews.analyze
+configured, else chat approval — same Confluence/Jira/chat flow as BRD).
 Wait for review before /clarify.
 ```
 
@@ -654,6 +664,8 @@ Read clarify.md with answers
 Update affected spec docs → mark: <!-- Clarified: {ID} -->
 Regenerate .summary.md for each updated doc
 Write clarify.summary.md — all items RESOLVED
+Stakeholder review (Confluence/Jira submit if document_reviews.clarify
+configured, else chat approval — same Confluence/Jira/chat flow as BRD).
 State: "CLARIFY complete — ready for the PLAN phase"
 ```