npm - @zeyue0329/xiaoma-cli - Versions diffs - 1.12.0 → 1.15.0 - Mend

@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (675) hide show

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/assets/validation-report-template.html ADDED Viewed

@@ -0,0 +1,325 @@
+<!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: TEMPLATE_PRD_NAME</title>
+<style>
+  :root {
+    --bg: #fafaf9;
+    --surface: #ffffff;
+    --border: #e7e5e4;
+    --text: #1c1917;
+    --muted: #78716c;
+    --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;
+    --grade-poor: #dc2626;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, system-ui, sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    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: flex-start;
+    justify-content: space-between;
+    gap: 24px;
+    padding-bottom: 16px;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 24px;
+  }
+  .title h1 { margin: 0; font-size: 22px; font-weight: 600; letter-spacing: -0.01em; }
+  .title .subtitle { color: var(--muted); font-size: 13px; margin-top: 4px; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+  .grade {
+    padding: 10px 18px;
+    border-radius: 8px;
+    font-weight: 600;
+    color: white;
+    font-size: 15px;
+    white-space: nowrap;
+  }
+  .grade-excellent { background: var(--grade-exc); }
+  .grade-good { background: var(--grade-good); }
+  .grade-fair { background: var(--grade-fair); }
+  .grade-poor { background: var(--grade-poor); }
+  .synthesis {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-left: 3px solid var(--muted);
+    border-radius: 8px;
+    padding: 18px 22px;
+    margin-bottom: 24px;
+    font-size: 15.5px;
+  }
+  .synthesis p { margin: 0 0 10px; }
+  .synthesis p:last-child { margin-bottom: 0; }
+  .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: 12px 14px;
+  }
+  .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 summary {
+    padding: 14px 20px;
+    cursor: pointer;
+    user-select: none;
+    list-style: none;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+  section summary::-webkit-details-marker { display: none; }
+  section summary::before {
+    content: "▸";
+    display: inline-block;
+    color: var(--muted);
+    transition: transform 0.15s ease;
+  }
+  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; }
+  .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: 6px;
+  }
+  .badge {
+    font-size: 10.5px;
+    padding: 3px 8px;
+    border-radius: 4px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    line-height: 1.4;
+  }
+  .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-title { margin: 0; font-size: 15px; font-weight: 500; flex: 1; min-width: 200px; }
+  .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;
+    padding-top: 16px;
+    border-top: 1px solid var(--border);
+    font-size: 12px;
+    color: var(--muted);
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  }
+  footer .meta { display: flex; gap: 24px; flex-wrap: wrap; }
+</style>
+</head>
+<body>
+  <div class="container">
+    <!-- TEMPLATE: header. Fill prd name, prd path, grade text & class. -->
+    <header class="report-header">
+      <div class="title">
+        <h1>TEMPLATE_PRD_NAME — Validation Report</h1>
+        <div class="subtitle">TEMPLATE_PRD_PATH</div>
+      </div>
+      <div class="grade TEMPLATE_GRADE_CLASS">TEMPLATE_GRADE</div>
+    </header>
+    <!-- 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>
+    <!-- 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 assessed rubric dimension -->
+    </div>
+    <!-- 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>Rubric: TEMPLATE_RUBRIC_PATH</span>
+        <span>Generated: TEMPLATE_TIMESTAMP</span>
+      </div>
+    </footer>
+  </div>
+</body>
+</html>

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/customize.toml ADDED Viewed

@@ -0,0 +1,147 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-prd.
+#
+# Override files (not edited here):
+#   {project-root}/_xiaoma/custom/xiaoma-prd.toml         (team)
+#   {project-root}/_xiaoma/custom/xiaoma-prd.user.toml    (personal)
+[workflow]
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays: append
+# Steps to run before the standard activation (config load, greet).
+# Use for pre-flight loads, compliance checks, etc.
+activation_steps_prepend = []
+# Steps to run after greet but before the workflow begins.
+# Use for context-heavy setup that should happen once the user has been acknowledged.
+activation_steps_append = []
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob
+# whose contents are loaded as facts.
+#
+# Default loads project-context.md if xiaoma-generate-project-context has produced one — this gives
+# the facilitator persistent awareness of the project's tech, domain, and constraints without
+# re-asking. Common opt-ins (set in team/user override TOML):
+#   "skill:acme-co:terms-and-conditions"                                      # a skill that contains some relevant info
+#   "Investor PRDs must include a market sizing section."                    # generic agent instruction
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+# Executed when the workflow completes (after the user has been told the
+# PRD is ready). Accepts either a string scalar (single instruction)
+# or an array of instructions executed in order. Empty for none.
+on_complete = ""
+# Default PRD structure. Treated as a starting point — the LLM adapts it
+# to the product, project type, and domain. Override the path in team/user TOML
+# to enforce a different structure (e.g. regulated-industry, internal-tool, investor-input).
+prd_template = "assets/prd-template.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 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 `{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
+# findings before the user sees the draft. Encodes standards, not options.
+#
+# Examples:
+#   "skill:xiaoma-editorial-review-prose"
+#   "file:{project-root}/_xiaoma/style-guides/company-voice.md"
+#   "Convert all dates to ISO 8601 format."
+#
+# Suggested order (broader passes first, narrower last):
+#   1. Structural (cuts, reorganization, section sizing)
+#   2. Content/voice/conventions (org standards, tone, terminology, compliance)
+#   3. Prose mechanics (grammar, clarity, typos)
+#
+# Override the array in team/user TOML to add additional standards. Append-only:
+# base entries cannot be removed or replaced (resolver has no removal mechanism).
+doc_standards = [
+  "skill:xiaoma-editorial-review-structure",
+  "skill:xiaoma-editorial-review-prose",
+]
+# External-source registry. Natural-language directives describing knowledge
+# bases, MCP tools, or internal systems the LLM may consult during the workflow
+# when a relevant need surfaces. The LLM does NOT query these preemptively —
+# it consults them on demand (during Discovery, validation, drafting, etc.).
+# Each entry names the tool, the conditions for using it, and any fields the
+# 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}."
+#   "When validating domain-compliance claims, cross-check against corp:hipaa_reference for healthcare or corp:pci_reference for fintech."
+external_sources = []
+# External-handoff routing. Natural-language directives the LLM applies at
+# Finalize to route outputs beyond local files (Confluence, Notion, Google
+# Drive, ticket systems, etc.). Each entry names the MCP tool, the destination,
+# and the fields the tool needs. Handoffs run after the artifact is polished
+# and before the final user-facing message. URLs or IDs returned by the
+# destination are captured and surfaced to the user. If a named tool is
+# unavailable at runtime, the handoff is skipped and flagged in the JSON
+# 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 XiaoMa 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/xmc-skills/2-plan-workflows/xiaoma-prd/references/headless.md ADDED Viewed

@@ -0,0 +1,39 @@
+# Headless Mode
+Load this file when xiaoma-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 user/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 user 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 `status: "blocked"` and a `reason` field — do not prompt. Do not greet.
+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.
+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.** 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 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.

package/src/xmc-skills/2-plan-workflows/xiaoma-prd/references/validate.md ADDED Viewed

@@ -0,0 +1,97 @@
+# Validate
+The Validate intent playbook. Standalone — this intent critiques an existing PRD without changing it and ends after the user has seen the report; it does not run Finalize. The synthesis pipeline below is also reused for mid-session report requests during Create/Update.
+## Orient
+Source-extract against `.decision-log.md`, any original inputs, and the PRD/addendum themselves. Delegate to subagents per PRD Discipline → "Extract, don't ingest" (in SKILL.md); the parent assembles from extracts.
+## Run the Reviewer Gate
+Run the Reviewer Gate (see SKILL.md) against `prd.md` (and `addendum.md` if present). The rubric walker is the default entry in the gate menu; under Validate intent it additionally runs the synthesis pipeline below. The Finalize discipline pass during Create/Update does NOT render a report — findings stay in-conversation.
+## Rubric-walker pipeline
+The rubric walker is the primary review entry. Spawn it as a subagent with this prompt:
+> You are validating a PRD against the quality rubric at `{workflow.validation_checklist_template}`. Read the full rubric first, then read `prd.md` (and `addendum.md` if present). Form a judgment per dimension — *strong / adequate / thin / broken* — and write findings only where they add information. Cite specific PRD locations and quote phrases. Severity ranks impact on the PRD's usefulness, not how easy the fix is. Write your review to `{doc_workspace}/review-rubric.md` in the format the rubric specifies. Return ONLY a compact summary (overall verdict, dimension verdicts, finding counts by severity, file path).
+The Reviewer Gate may also dispatch additional reviewers from `{workflow.finalize_reviewers}` (adversarial-general by default) and any ad-hoc reviewers the parent judges warranted. Each writes its review to `{doc_workspace}/review-{slug}.md` and returns a compact summary. Run in parallel.
+## Synthesis pipeline
+Once every selected reviewer has returned, the parent synthesizes one consolidated report. **Do not skip this step under Validate intent** — it produces the persistent artifact the user opens.
+### Inputs
+- `{doc_workspace}/review-rubric.md` — primary, structured by the rubric dimensions
+- Zero or more `{doc_workspace}/review-{slug}.md` files — extra reviewers (adversarial, etc.)
+- `{workflow.validation_report_template}` — the HTML skeleton
+### What the synthesis pass does
+1. Read every reviewer file in `{doc_workspace}/review-*.md`.
+2. Fill the HTML skeleton:
+   - **Header.** PRD name, path. Grade derived from the rubric verdicts and severity counts: *Excellent* = all dimensions strong/adequate, no high/critical findings · *Good* = ≤1 thin dimension, no critical findings · *Fair* = multiple thin dimensions or any high finding · *Poor* = any broken dimension or any critical finding. Set the matching `grade-excellent | grade-good | grade-fair | grade-poor` class.
+   - **Synthesis block.** Lift the rubric's *Overall verdict* paragraph as the lead; if adversarial or ad-hoc reviewers materially shift the picture, add a second paragraph that names what they surfaced.
+   - **Dimension summary cards.** One per dimension that was assessed. Colored verdict text. Skip dimensions the rubric marked n/a for this PRD (e.g. downstream usability for a standalone PRD).
+   - **Dimension sections.** One `<section class="dimension">` per assessed dimension, in rubric order. `<details open>` for *thin* and *broken*; closed for *strong* and *adequate*. Each contains the dimension judgment (the prose from review-rubric.md) and the findings list.
+   - **Reviewer sections.** One `<section class="reviewer-section">` per extra reviewer that ran. The source file path goes in the `<span class="reviewer-source">`. Closed by default. Adversarial findings keep their adversarial voice — do not soften.
+   - **Mechanical notes.** Bullet list from the rubric's "Mechanical notes" section. Skip the block if empty.
+   - **Footer.** Rubric path, ISO timestamp.
+3. Write the filled HTML to `{doc_workspace}/validation-report.html`.
+4. Write the markdown twin to `{doc_workspace}/validation-report.md` (same content, grouped by severity rather than by dimension — see format below; this is the canonical form for downstream re-reading).
+5. Open the HTML in the default browser:
+   ```bash
+   open {doc_workspace}/validation-report.html in your browser (skip in headless)
+   ```
+   Skip the open step in headless mode (see `references/headless.md`).
+### Markdown twin format
+```markdown
+# Validation Report — {prd_name}
+- **PRD:** `{prd_path}`
+- **Rubric:** `{rubric_path}`
+- **Run at:** {ISO timestamp}
+- **Grade:** {Excellent | Good | Fair | Poor}
+## Overall verdict
+{synthesis paragraphs}
+## Dimension verdicts
+- Decision-readiness — {verdict}
+- Substance over theater — {verdict}
+- (etc. for each assessed dimension)
+## Findings by severity
+### Critical (n)
+**[Dimension or Reviewer]** — Title (§ location)
+{Note}
+Fix: {suggested fix}
+### High (n)
+...
+### Medium (n)
+...
+### Low (n)
+...
+## Mechanical notes
+- {bullet}
+## Reviewer files
+- `review-rubric.md`
+- `review-adversarial-general.md` (if present)
+- (etc.)
+```
+Re-running validation overwrites the consolidated report in place. The individual `review-*.md` files are preserved so the user can drill in.
+## Close
+Surface artifact paths; the rendered HTML/markdown is the persistent artifact. Always offer to roll findings into an Update.