bmad-method 6.6.1-next.9 → 6.7.1-next.0

package/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md

@@ -1,30 +1,135 @@
-# PRD Validation Checklist
+# PRD Quality Rubric
 
-Loaded by the PRD validator subagent. For each item, return `{id, status: pass|fail|warn|n/a, severity: low|medium|high|critical, location, note}`. Skip items not applicable to the agreed stakes. Cite specific PRD locations — never abstract criticism.
+A judgment rubric for the validator subagent. Walk the PRD with these dimensions in mind and write substantive findings — not box-ticking. The goal is a review that tells the user whether this PRD is *good*, not whether it has the right section headers.
 
-## Quality
+Most PRDs do not need every dimension scrutinized equally. Calibrate to the agreed stakes, the PRD's shape (consumer product, internal tool, regulatory update, technical capability spec), and what the PRD itself is trying to do. Be specific — cite locations, quote phrases, name what's missing. Abstract criticism is failure of nerve.
 
-- **Q-1. Information density.** Sentences carry weight. Flag filler, hedging, and conversational padding.
-- **Q-2. Measurability.** Where measurement matters, FRs and Success Metrics are measurable; subjective adjectives flagged. Counter-metrics named when Success Metrics exist.
-- **Q-3. Traceability.** Where the chain matters, FRs name their link to a user journey or success criterion inline.
-- **Q-4. Vision and JTBDs concrete.** Vision is specific and stands alone — not a generic feature list. JTBDs are audience-grounded, not abstract.
-- **Q-5. Non-Goals explicit.** A Non-Goals section is present where it would do real work; inline `[NON-GOAL]` and `[v2]` callouts where omissions would otherwise be silently assumed.
-- **Q-6. Dual-audience and self-contained.** Each section makes sense pulled out alone (cross-references via Glossary terms, not "see above"); the PRD is readable by humans and structured cleanly for downstream source-extraction by UX, architecture, and story-creation workflows.
+## How to use this rubric
 
-## Discipline
+1. Read the full PRD (and addendum.md if present) before writing anything.
+2. For each of the seven dimensions below, form a judgment — *strong / adequate / thin / broken* — backed by specifics from the PRD.
+3. Write findings only where they add information. A `strong` dimension may need no findings; a `broken` one needs concrete, fixable ones.
+4. Severity ranks impact on the PRD's usefulness, not how easy the fix is. A vague Vision statement is *critical* even though it's a one-paragraph fix; a glossary drift might be *low* even though it appears in many places.
+5. The overall verdict is your synthesis — 2–3 sentences that name what holds up and what's at risk. Earn it with the dimension judgments.
 
-- **D-1. Capabilities, not implementation.** FRs describe what users/systems can do, not how. Flag technology names, library choices, architecture decisions.
-- **D-2. Input fidelity.** Requirements from input documents (brief, research, prior PRD) are still in scope or explicitly handled via Non-Goals or `[ASSUMPTION]`.
-- **D-3. Personas grounded.** If personas exist, they are research-grounded or marked `[ILLUSTRATIVE]`. Each persona drives at least one decision.
-- **D-4. No innovation theater.** Novelty claims are real, not invented.
+## Output format
 
-## Structural integrity
+Write findings to `{doc_workspace}/review-rubric.md`:
 
-- **S-1. Glossary integrity.** Every domain noun is defined in the Glossary and used identically throughout. Flag drift (case, plural, synonyms) and candidate missing-term entries.
-- **S-2. ID continuity.** FR / UJ / Story IDs are contiguous, unique, and cross-references resolve.
-- **S-3. Assumptions Index.** Every inline `[ASSUMPTION: ...]` appears in the Assumptions Index and vice versa.
-- **S-4. Open-items density.** Count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]`. Red flag if density is high relative to the agreed stakes.
+```markdown
+# PRD Quality Review — {prd_name}
 
-## Stakes-gated
+## Overall verdict
+[2–3 sentences. What holds up, what's at risk. Earned by the dimension judgments below.]
 
-- **STK-1. Required sections.** The PRD includes the sections the agreed stakes and product type warrant.
+## Decision-readiness — [strong | adequate | thin | broken]
+[1–3 paragraphs of judgment with specific PRD locations.]
+
+### Findings
+- **[critical|high|medium|low]** [Title] (§ location) — [Note]. *Fix:* [suggested fix].
+
+## Substance over theater — [verdict]
+...
+
+(repeat for each dimension)
+
+## Mechanical notes
+[Glossary drift, ID continuity, broken cross-refs, Assumptions Index roundtrip. Lighter weight — these matter for downstream but don't drive the overall verdict.]
+```
+
+## The seven dimensions
+
+### 1. Decision-readiness
+
+Can a decision-maker act on this PRD? Are the trade-offs surfaced honestly, or has the PRD smoothed everything to neutral? Would someone pushing back find their objection acknowledged or dodged?
+
+Look for:
+- Decisions that are stated as decisions, not buried as "considerations."
+- Trade-offs named with what was given up, not just what was chosen.
+- Open Questions that are actually open — not rhetorical questions with an answer in the next sentence.
+- `[NOTE FOR PM]` callouts at real tensions, not at safe checkpoints.
+
+Red flag: a PRD where every choice "balances" everything, every NFR is "important," every persona "values" the product.
+
+### 2. Substance over theater
+
+Is the content earned, or is it furniture? Distinguish:
+
+- **Persona theater** — Personas that don't drive a single decision in the PRD. More than four personas. Personas whose only function is to make the PRD look thorough.
+- **Innovation theater** — claimed novelty that isn't novel. Differentiation sections written because the template had one, not because Discovery surfaced something.
+- **NFR theater** — copied boilerplate ("system must be scalable / secure / reliable") without product-specific thresholds.
+- **Vision theater** — a Vision statement that could swap into any PRD in this category without change.
+
+Flag what reads like furniture, even if it's well-written furniture.
+
+### 3. Strategic coherence
+
+Does the PRD have a thesis? Do the features serve a unified arc, or is it a list of capabilities someone wanted?
+
+Look for:
+- A stated thesis the PRD bets on (problem framing, user insight, market move).
+- Feature prioritization that follows from the thesis — not from "what's easy first."
+- Success Metrics that validate the thesis, not metrics that just measure activity (DAU/MAU when the thesis is about engagement quality is a tell).
+- Counter-metrics named when SMs exist.
+- Coherent MVP scope kind — problem-solving, experience, platform, or revenue — with scope logic that matches.
+
+Red flag: a PRD that reads as a backlog with section headings.
+
+### 4. Done-ness clarity
+
+Would an engineer reading this PRD know what "done" looks like for each FR?
+
+Look for:
+- FRs with at least one testable consequence per FR — verifiable condition, measurable outcome.
+- "System handles X gracefully," "reasonable performance," "user-friendly" — flag every one.
+- Acceptance criteria implied or explicit. Sometimes the FR's consequences carry this; sometimes the PRD genuinely needs an Acceptance section.
+- For non-functional sections (UX, performance, security): bounds, not adjectives.
+
+This is the dimension downstream story creation will lean on hardest. Be unforgiving here.
+
+### 5. Scope honesty
+
+Are omissions explicit, or is the reader meant to infer them?
+
+Look for:
+- A Non-Goals section where it would do real work — and `[NON-GOAL for MVP]` callouts where omissions could be silently assumed.
+- `[ASSUMPTION: …]` tags on inferences the user didn't directly confirm, indexed at the end.
+- `[NOTE FOR PM]` callouts at deferred decisions and unresolved tensions.
+- De-scoping proposed honestly, not done silently.
+
+Open-items density: count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]` callouts relative to stakes. High counts on a low-stakes PRD is fine; high counts on a green-light-to-build PRD is a blocker.
+
+### 6. Downstream usability
+
+If this PRD feeds UX, architecture, or story creation, can those workflows source-extract from it cleanly?
+
+Look for:
+- Glossary present; every domain noun used identically across FRs, UJs, SM definitions.
+- FR / UJ / SM IDs contiguous, unique, and cross-references that resolve.
+- Each section makes sense pulled out alone — cross-references via Glossary terms, not "see above."
+- UJs each name a persona from §2 by exact label; no floating UJs.
+
+For standalone PRDs (no downstream), this dimension matters less — say so.
+
+### 7. Shape fit
+
+Has the PRD been forced into a shape that doesn't match the product?
+
+- Consumer product / multi-stakeholder B2B / meaningful UX → UJs and personas are load-bearing.
+- Internal tool, single-operator role → capability spec shape; UJs may be overhead; SMs may be operational rather than user-facing.
+- Regulatory or compliance update → constraint traceability is non-negotiable; UJs may be irrelevant.
+- Hobby / solo → rigor light, substance bar still applies.
+- Brownfield → existing-code references must be accurate; new UJs and existing UJs must be distinguished.
+- Chain-top (feeds UX → architecture → stories) → downstream usability matters more; standalone PRDs can be lighter on traceability.
+
+Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no personas or UJs).
+
+## Mechanical notes
+
+Cover these as a tail section, not a primary dimension. They matter for downstream but don't drive the verdict on whether the PRD is good.
+
+- Glossary drift (case, plural, synonyms across the PRD).
+- ID continuity (gaps, duplicates, unresolved cross-references).
+- Assumptions Index roundtrip (every inline `[ASSUMPTION]` indexed; index entries all appear inline).
+- UJ persona linkage (each UJ names a defined persona by exact label).
+- Required sections present for the agreed stakes and product type.

package/src/bmm-skills/2-plan-workflows/bmad-prd/assets/validation-report-template.html

@@ -1,8 +1,30 @@
 <!DOCTYPE html>
+<!--
+  PRD Validation Report — skeleton template.
+
+  This file is a starter the synthesis pass fills in directly. There is no
+  substitution engine. The LLM:
+    1. Reads {doc_workspace}/review-rubric.md and every review-{slug}.md from
+       additional reviewers.
+    2. Copies this skeleton.
+    3. Replaces the placeholder content (everything between TEMPLATE markers)
+       with the consolidated review, preserving the structure and CSS.
+    4. Writes the result to {doc_workspace}/validation-report.html.
+    5. Writes a markdown twin to {doc_workspace}/validation-report.md.
+
+  Visual rules the LLM must preserve:
+    - The container width, the color tokens, the typography.
+    - One dimension = one collapsible <section class="dimension">.
+    - Verdict pill uses the verdict-* class matching its judgment.
+    - Severity badge uses the sev-* class matching its level.
+    - Each extra reviewer (adversarial, etc.) gets its own collapsible section
+      below the rubric dimensions.
+    - The footer always shows the artifact paths and timestamp.
+-->
 <html lang="en">
 <head>
 <meta charset="utf-8">
-<title>PRD Validation: $prd_name</title>
+<title>PRD Validation: TEMPLATE_PRD_NAME</title>
 <style>
   :root {
     --bg: #fafaf9;
@@ -10,14 +32,17 @@
     --border: #e7e5e4;
     --text: #1c1917;
     --muted: #78716c;
-    --pass: #22c55e;
-    --warn: #eab308;
-    --fail: #ef4444;
-    --na: #94a3b8;
+
+    --verdict-strong: #16a34a;
+    --verdict-adequate: #65a30d;
+    --verdict-thin: #d97706;
+    --verdict-broken: #dc2626;
+
     --sev-low: #64748b;
     --sev-medium: #ca8a04;
     --sev-high: #ea580c;
     --sev-critical: #dc2626;
+
     --grade-exc: #16a34a;
     --grade-good: #65a30d;
     --grade-fair: #d97706;
@@ -29,14 +54,14 @@
     font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, system-ui, sans-serif;
     background: var(--bg);
     color: var(--text);
-    line-height: 1.55;
+    line-height: 1.6;
     font-size: 15px;
   }
   .container { max-width: 960px; margin: 0 auto; padding: 32px 24px 64px; }
 
   header.report-header {
     display: flex;
-    align-items: center;
+    align-items: flex-start;
     justify-content: space-between;
     gap: 24px;
     padding-bottom: 16px;
@@ -63,63 +88,90 @@
     border: 1px solid var(--border);
     border-left: 3px solid var(--muted);
     border-radius: 8px;
-    padding: 16px 20px;
+    padding: 18px 22px;
     margin-bottom: 24px;
-    color: var(--text);
-    font-size: 15px;
+    font-size: 15.5px;
   }
-  .synthesis:empty { display: none; }
+  .synthesis p { margin: 0 0 10px; }
+  .synthesis p:last-child { margin-bottom: 0; }
 
-  .scoreboard {
+  .dimension-summary {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+    gap: 10px;
+    margin-bottom: 24px;
+  }
+  .dim-card {
     background: var(--surface);
     border: 1px solid var(--border);
     border-radius: 8px;
-    padding: 18px 20px;
-    margin-bottom: 24px;
+    padding: 12px 14px;
   }
-  .score-bar { margin: 0 0 14px; line-height: 0; }
-  .score-stats { display: flex; gap: 22px; font-size: 14px; flex-wrap: wrap; }
-  .score-stats span { display: inline-flex; align-items: center; gap: 6px; }
-  .score-stats .dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
-  .dot-pass { background: var(--pass); }
-  .dot-warn { background: var(--warn); }
-  .dot-fail { background: var(--fail); }
-  .dot-na { background: var(--na); }
-  .total-count { margin-left: auto; color: var(--muted); }
-
-  section.category { margin-bottom: 16px; }
-  section.category details {
+  .dim-card .dim-name { font-size: 13px; color: var(--muted); margin-bottom: 6px; }
+  .dim-card .dim-verdict { font-size: 14px; font-weight: 600; }
+
+  section.dimension, section.reviewer-section { margin-bottom: 14px; }
+  section.dimension details, section.reviewer-section details {
     background: var(--surface);
     border: 1px solid var(--border);
     border-radius: 8px;
     overflow: hidden;
   }
-  section.category summary {
+  section summary {
     padding: 14px 20px;
     cursor: pointer;
     user-select: none;
     list-style: none;
+    display: flex;
+    align-items: center;
+    gap: 12px;
   }
-  section.category summary::-webkit-details-marker { display: none; }
-  section.category summary::before {
+  section summary::-webkit-details-marker { display: none; }
+  section summary::before {
     content: "▸";
     display: inline-block;
-    margin-right: 10px;
     color: var(--muted);
     transition: transform 0.15s ease;
   }
-  section.category details[open] summary::before { transform: rotate(90deg); }
-  section.category summary h2 { display: inline; margin: 0; font-size: 16px; font-weight: 600; letter-spacing: -0.005em; }
-  section.category .count { color: var(--muted); font-weight: 400; margin-left: 6px; font-size: 14px; }
+  section details[open] summary::before { transform: rotate(90deg); }
+  section summary h2 {
+    display: inline;
+    margin: 0;
+    font-size: 16px;
+    font-weight: 600;
+    letter-spacing: -0.005em;
+    flex: 1;
+  }
+  .verdict-pill {
+    font-size: 11px;
+    padding: 3px 10px;
+    border-radius: 999px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: white;
+  }
+  .verdict-strong { background: var(--verdict-strong); }
+  .verdict-adequate { background: var(--verdict-adequate); }
+  .verdict-thin { background: var(--verdict-thin); }
+  .verdict-broken { background: var(--verdict-broken); }
+
+  .dim-body { padding: 4px 20px 18px; }
+  .dim-judgment { color: var(--text); font-size: 14.5px; }
+  .dim-judgment p { margin: 0 0 10px; }
 
-  article.finding { padding: 16px 20px; border-top: 1px solid var(--border); }
-  article.finding-fail { background: rgba(239, 68, 68, 0.025); }
+  .findings-list { padding: 0 20px 4px; }
+  article.finding {
+    padding: 14px 0;
+    border-top: 1px solid var(--border);
+  }
+  article.finding:first-child { border-top: none; }
   article.finding header {
     display: flex;
     align-items: center;
     gap: 10px;
     flex-wrap: wrap;
-    margin-bottom: 8px;
+    margin-bottom: 6px;
   }
   .badge {
     font-size: 10.5px;
@@ -130,18 +182,32 @@
     letter-spacing: 0.04em;
     line-height: 1.4;
   }
-  .badge-pass { background: rgba(34, 197, 94, 0.12); color: #15803d; }
-  .badge-warn { background: rgba(234, 179, 8, 0.14); color: #854d0e; }
-  .badge-fail { background: rgba(239, 68, 68, 0.12); color: #b91c1c; }
-  .badge-na { background: rgba(148, 163, 184, 0.16); color: #475569; }
   .badge-sev-low { background: rgba(100, 116, 139, 0.12); color: var(--sev-low); }
   .badge-sev-medium { background: rgba(202, 138, 4, 0.14); color: var(--sev-medium); }
   .badge-sev-high { background: rgba(234, 88, 12, 0.14); color: var(--sev-high); }
   .badge-sev-critical { background: rgba(220, 38, 38, 0.14); color: var(--sev-critical); }
-  .finding-id { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 12px; color: var(--muted); }
   .finding-title { margin: 0; font-size: 15px; font-weight: 500; flex: 1; min-width: 200px; }
-  .finding-location, .finding-note, .finding-fix { margin-top: 6px; font-size: 14px; color: var(--text); }
-  .finding-location strong, .finding-fix strong { color: var(--muted); font-weight: 500; }
+  .finding-location { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 12.5px; color: var(--muted); }
+  .finding-note, .finding-fix { margin-top: 6px; font-size: 14px; }
+  .finding-fix strong { color: var(--muted); font-weight: 500; }
+
+  .reviewer-source {
+    font-size: 12px;
+    color: var(--muted);
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  }
+
+  .mechanical {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 16px 20px;
+    margin-top: 24px;
+    font-size: 14px;
+  }
+  .mechanical h3 { margin: 0 0 10px; font-size: 14px; font-weight: 600; color: var(--muted); text-transform: uppercase; letter-spacing: 0.04em; }
+  .mechanical ul { margin: 0; padding-left: 20px; }
+  .mechanical li { margin-bottom: 4px; color: var(--text); }
 
   footer.report-footer {
     margin-top: 40px;
@@ -156,33 +222,102 @@
 </head>
 <body>
   <div class="container">
+
+    <!-- TEMPLATE: header. Fill prd name, prd path, grade text & class. -->
     <header class="report-header">
       <div class="title">
-        <h1>$prd_name — Validation Report</h1>
-        <div class="subtitle">$prd_path</div>
+        <h1>TEMPLATE_PRD_NAME — Validation Report</h1>
+        <div class="subtitle">TEMPLATE_PRD_PATH</div>
       </div>
-      <div class="grade $grade_class">$grade</div>
+      <div class="grade TEMPLATE_GRADE_CLASS">TEMPLATE_GRADE</div>
     </header>
 
-    <div class="synthesis">$overall_synthesis</div>
+    <!-- TEMPLATE: overall synthesis paragraphs. Lift directly from
+         review-rubric.md "Overall verdict" section; expand if extra reviewers
+         materially shift the picture. Wrap each paragraph in <p>. -->
+    <div class="synthesis">
+      <p>TEMPLATE_SYNTHESIS_PARAGRAPH</p>
+    </div>
 
-    <div class="scoreboard">
-      <div class="score-bar">$score_svg</div>
-      <div class="score-stats">
-        <span><span class="dot dot-pass"></span>$passed pass</span>
-        <span><span class="dot dot-warn"></span>$warned warn</span>
-        <span><span class="dot dot-fail"></span>$failed fail</span>
-        <span><span class="dot dot-na"></span>$na n/a</span>
-        <span class="total-count">$total items checked</span>
+    <!-- TEMPLATE: dimension summary cards. One per rubric dimension. The
+         dim-verdict text uses one of: strong | adequate | thin | broken. -->
+    <div class="dimension-summary">
+      <div class="dim-card">
+        <div class="dim-name">Decision-readiness</div>
+        <div class="dim-verdict" style="color: var(--verdict-TEMPLATE_VERDICT)">TEMPLATE_VERDICT_TEXT</div>
       </div>
+      <!-- repeat for each of the seven dimensions -->
     </div>
 
-    $categories_html
+    <!-- TEMPLATE: one section per rubric dimension. Skip a dimension entirely
+         if the rubric review marked it n/a for this PRD (e.g. downstream
+         usability for a standalone PRD). Open the section by default if
+         verdict is thin or broken. -->
+    <section class="dimension">
+      <details open>
+        <summary>
+          <h2>Decision-readiness</h2>
+          <span class="verdict-pill verdict-TEMPLATE_VERDICT">TEMPLATE_VERDICT_TEXT</span>
+        </summary>
+        <div class="dim-body">
+          <div class="dim-judgment">
+            <p>TEMPLATE_DIMENSION_JUDGMENT</p>
+          </div>
+        </div>
+        <div class="findings-list">
+          <!-- TEMPLATE: zero or more findings -->
+          <article class="finding">
+            <header>
+              <span class="badge badge-sev-TEMPLATE_SEVERITY">TEMPLATE_SEVERITY</span>
+              <h3 class="finding-title">TEMPLATE_FINDING_TITLE</h3>
+              <span class="finding-location">TEMPLATE_LOCATION</span>
+            </header>
+            <div class="finding-note">TEMPLATE_FINDING_NOTE</div>
+            <div class="finding-fix"><strong>Fix:</strong> TEMPLATE_SUGGESTED_FIX</div>
+          </article>
+        </div>
+      </details>
+    </section>
+
+    <!-- TEMPLATE: one section per extra reviewer that ran (adversarial, etc.).
+         Skip this block entirely if only the rubric walker ran. -->
+    <section class="reviewer-section">
+      <details>
+        <summary>
+          <h2>Adversarial review</h2>
+          <span class="reviewer-source">TEMPLATE_REVIEWER_SOURCE_FILE</span>
+        </summary>
+        <div class="dim-body">
+          <div class="dim-judgment">
+            <p>TEMPLATE_REVIEWER_PREAMBLE</p>
+          </div>
+        </div>
+        <div class="findings-list">
+          <article class="finding">
+            <header>
+              <span class="badge badge-sev-TEMPLATE_SEVERITY">TEMPLATE_SEVERITY</span>
+              <h3 class="finding-title">TEMPLATE_FINDING_TITLE</h3>
+              <span class="finding-location">TEMPLATE_LOCATION</span>
+            </header>
+            <div class="finding-note">TEMPLATE_FINDING_NOTE</div>
+            <div class="finding-fix"><strong>Fix:</strong> TEMPLATE_SUGGESTED_FIX</div>
+          </article>
+        </div>
+      </details>
+    </section>
+
+    <!-- TEMPLATE: mechanical notes — short, bulleted. Skip if there are none. -->
+    <div class="mechanical">
+      <h3>Mechanical notes</h3>
+      <ul>
+        <li>TEMPLATE_MECHANICAL_NOTE</li>
+      </ul>
+    </div>
 
     <footer class="report-footer">
       <div class="meta">
-        <span>Checklist: $checklist_path</span>
-        <span>Generated: $timestamp</span>
+        <span>Rubric: TEMPLATE_RUBRIC_PATH</span>
+        <span>Generated: TEMPLATE_TIMESTAMP</span>
       </div>
     </footer>
   </div>

package/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml

@@ -43,23 +43,28 @@ on_complete = ""
 # to enforce a different structure (e.g. regulated-industry, internal-tool, investor-input).
 prd_template = "assets/prd-template.md"
 
-# Validation checklist used at the Validate intent and at Finalize step 3.
-# A subagent walks the checklist against prd.md and returns structured findings.
-# Override the path in team/user TOML to enforce an org-specific checklist
-# (regulated-industry compliance, investor-pitch standards, etc.).
-validation_checklist = "assets/prd-validation-checklist.md"
+# PRD quality rubric used at the Validate intent and at Finalize step 3.
+# A subagent walks the rubric against prd.md and writes a substantive review
+# organized by quality dimensions (decision-readiness, substance, strategic
+# coherence, etc.). Override the path in team/user TOML to enforce an
+# org-specific rubric (regulated-industry compliance, investor-pitch standards,
+# etc.). The filename "checklist" is retained for back-compat with override
+# files; the content is a judgment rubric, not a boolean checklist.
+validation_checklist_template = "assets/prd-validation-checklist.md"
 
-# HTML template used to render validation findings into a styled, scannable
-# report. The renderer (scripts/render-validation-html.py) substitutes
-# structured findings + summary stats into this template; the template is
-# fully overridable to match org branding. The default uses inline CSS, no
-# external dependencies, and native HTML <details> for collapse — no JS.
+# HTML skeleton the synthesis pass fills directly when consolidating reviewer
+# outputs into a validation report. No substitution engine — the parent LLM
+# reads every {doc_workspace}/review-*.md, fills the skeleton's TEMPLATE_*
+# placeholders, and writes the result. Fully overridable to match org branding.
+# Uses inline CSS, no external dependencies, and native HTML <details> for
+# collapse — no JS.
 validation_report_template = "assets/validation-report-template.html"
 
 # Run folder location. The PRD, optional addendum, decision log, and optional
-# validation report all land inside `{output_dir}/{output_folder_name}/`.
-output_dir = "{planning_artifacts}/prds"
-output_folder_name = "prd-{project_name}-{date}"
+# validation report all land inside `{prd_output_path}/{run_folder_pattern}/`.
+# Resume-check scans `{prd_output_path}` for prior unfinished runs.
+prd_output_path = "{planning_artifacts}/prds"
+run_folder_pattern = "prd-{project_name}-{date}"
 
 # Document standards applied to human-consumed docs at finalize. Each entry is
 # a `skill:`, `file:`, or plain-text directive; the parent LLM applies the
@@ -90,6 +95,11 @@ doc_standards = [
 # tool needs. If a named MCP tool is unavailable at runtime, the LLM falls
 # back to standard behavior and notes the gap. Empty by default.
 #
+# Lifecycle note: distinct from persistent_facts. persistent_facts are loaded
+# once at activation and kept in mind for the whole run; external_sources are
+# a registry consulted on demand and only when the conversation surfaces a
+# matching need.
+#
 # Examples (set in team/user override TOML):
 #   "When researching internal product context, consult corp:kb_search (database='product-docs') before web search."
 #   "For competitive landscape during Discovery, query corp:competitive_db with category={project_name}."
@@ -106,8 +116,32 @@ external_sources = []
 # status; local files always exist regardless. Fires automatically — users
 # can opt out in their prompt for a specific run. Empty by default.
 #
+# Lifecycle note: distinct from persistent_facts and external_sources.
+# Fired once at Finalize step 6, never during Discovery or drafting.
+#
 # Examples (set in team/user override TOML):
 #   "After finalize, upload prd.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name})."
 #   "Mirror the PRD to Notion via notion:create_page (database_id='abc123', title='PRD: '+{project_name})."
 #   "When the PRD references a parent initiative, link via corp:jira_link on the epic key in frontmatter."
 external_handoffs = []
+
+# --- Finalize reviewers ---
+# Reviewers spawned at Finalize step 3 (and at the Validate intent) alongside
+# the structural checklist validator. The authoring skill assembles the gate
+# menu (validator + these reviewers + any ad-hoc reviewers it judges warranted
+# by the artifact content) and lets the user pick all, a subset, or skip. Gate
+# UX is stakes-calibrated: hobby/solo scope may run defaults quietly or skip;
+# higher stakes get the explicit menu.
+#
+# Entries follow the standard prefix convention (same as persistent_facts and
+# doc_standards):
+#   "skill:NAME"   invoke the named review skill as a subagent against prd.md
+#   "file:PATH"    load the file as a review prompt; spawn an adversarial
+#                  subagent applying that prompt to prd.md
+#   plain text     use the text directly as the subagent's review prompt
+#
+# Override TOML may append additional reviewers. Arrays append per BMad rules.
+#
+# Resolved on-demand by the authoring skill (not pulled at activation): only
+# when entering the Validate intent or assembling the gate at Finalize step 3.
+finalize_reviewers = []

package/src/bmm-skills/2-plan-workflows/bmad-prd/references/headless.md

@@ -2,23 +2,38 @@
 
 Load this file when bmad-prd is invoked headless (no interactive user). Follow it for the whole run.
 
+## Detection
+
+Headless mode is in effect when any of the following is true:
+
+- the invoking caller sets a `headless: true` flag (or equivalent argument the harness exposes),
+- the invocation is from another skill or a non-interactive runner (no TTY, no user message stream),
+- `{workflow.activation_steps_prepend}` includes an entry that explicitly declares headless,
+- the first message comes from an automation context that pre-supplies all inputs and asks for an artifact path back.
+
+When ambiguous, default to interactive.
+
+## Inputs the caller is expected to provide
+
+The caller passes inputs in their first message (free-form structured payload; no fixed schema, but every field below should be present when applicable):
+
+- `intent` — `"create"`, `"update"`, or `"validate"`. If absent, infer from the artifact set.
+- For **Create**: a brief or product spec the LLM works from (plain text, file path, or URL), plus any persona/scope notes; `doc_workspace` if a specific run folder is required (otherwise the workflow binds the default).
+- For **Update**: the existing `prd.md` path (or a workspace path that contains one), and a change signal (the request: what to change and why).
+- For **Validate**: the existing `prd.md` path (or workspace path), and optionally a checklist override path. Workspace defaults to the PRD's containing directory.
+
+Anything the caller does not provide is either inferred from inputs/workspace or recorded as `assumptions[]` / `open_questions[]` in the JSON status. Do not invent persona detail, success metrics, or scope decisions to fill gaps — record them.
+
 ## General
 
-Do not ask. Complete the intent using what is provided, what exists in `{doc_workspace}`, or what you can discover yourself. If intent remains ambiguous after inference, halt with a `blocked` JSON status and a `reason` field — do not prompt. Do not greet.
+Do not ask. Complete the intent using what is provided, what exists in `{doc_workspace}`, or what you can discover yourself. If intent remains ambiguous after inference, halt with `status: "blocked"` and a `reason` field — do not prompt. Do not greet.
 
-End with a JSON response listing status, intent, and artifact paths. The `intent` field must match the detected intent: `"create"`, `"update"`, or `"validate"`. Omit keys for artifacts not produced. Full schemas with examples for each intent are in `assets/headless-schemas.md`. Minimal shape:
+Populate `assumptions[]` with every value you inferred without direct caller confirmation; populate `open_questions[]` with every gap that needs a human decision. Use `status: "partial"` when the artifact was produced but `open_questions[]` is non-empty or critical inputs were inferred (Create with no brief; Update with a vague signal acted on best-effort; Validate that could not load the checklist). `complete` = stands on its own; `partial` = caller should review before downstream use; `blocked` = no artifact produced.
 
-```json
-{
-  "status": "complete",
-  "intent": "validate",
-  "validation_report": "{doc_workspace}/validation-report.md",
-  "offer_to_update": true
-}
-```
+End with the JSON response (full schemas with examples in `assets/headless-schemas.md`). The `intent` field must match the detected intent. Omit keys for artifacts not produced.
 
 ## Mode-specific overrides
 
-**Update.** Log the reversal to `decision-log.md`, then apply. Halt `blocked` if intent is ambiguous.
+**Update.** Apply the change, log to `.decision-log.md` with rationale, and surface any conflict-with-prior-decision in `conflicts_with_prior_decisions[]` in the JSON status. Halt `blocked` if intent is ambiguous.
 
-**Validate.** Always write `validation-report.md` to `{doc_workspace}` regardless of finding count. Always include `"offer_to_update": true` in the JSON status block.
+**Validate.** Always write both `validation-report.html` and `validation-report.md` to `{doc_workspace}` regardless of finding count. Always include `"offer_to_update": true` in the JSON status. Skip the browser-open step in `references/validate.md` — write the artifacts and return.