rcf-lite 0.0.1 → 0.7.1

package/src/verify/verdict/index.js

@@ -0,0 +1,246 @@
+// Verdict taxonomy + aggregation (spec §5.1, §5.2). Mirrors the persona
+// programme's PASS/BROKEN/DEGRADED/COSMETIC, plus the structural verdicts
+// NOT-DEPLOYED (§4 refusal), BLOCKED (§6 unprovisionable), and LAUNCH-FAILURE
+// (the verifier agent could not run or its output could not be ingested — a
+// refusal to issue a verdict on the app, never a soft pass; see engine catch).
+//
+// Split verdicts are held split, NEVER averaged (§5.1): a run is BROKEN if
+// ANY finding is BROKEN, regardless of how many ACs passed.
+//
+// 0.7.0 additions:
+//   - MOCK-ONLY-DECLARED (verification-integrity-cluster-spec §5.2): an AC
+//     whose aggregated service attestation resolves to `mocked` for at
+//     least one service. Verify has no live path to make it real-hit; the
+//     verdict is the honest alternative to a false PASS.
+//   - BLOCKED-BY-DECLARATION (verification-integrity-cluster-spec §5.2):
+//     an AC whose aggregated service attestation contains `declaredMockOnly`
+//     for at least one service. The operator declared mock-only at pre-flight;
+//     verify refuses to issue a live verdict and the chain records the
+//     decision.
+//   - UI-BASELINE-UNMET (ui-design-gate §8.7): a UI-bearing AC whose
+//     browser-verification record for a bound FBS came back `block`.
+//   - BROWSER-VERIFICATION-MISSING (ui-design-gate §8.7): a UI-bearing AC
+//     bound to an FBS with no browserVerification[] entry on the manifest.
+//
+// The four new classes are PER-AC verdicts emitted on the report's
+// `perAcVerdicts[]` array. They do NOT replace the top-level `verdict`
+// (which stays BROKEN/DEGRADED/… by finding severity + provisioning
+// blocked); they run alongside so a finalise-gate consumer can refuse
+// `verified` on an AC-level basis even when the run's aggregate is PASS.
+
+import { rcfError } from '#core/errors';
+
+/** Finding severities, low → high. */
+export const FINDING_SEVERITIES = Object.freeze(['PASS', 'COSMETIC', 'DEGRADED', 'BROKEN']);
+
+/** Severity rank for the split-not-averaged max and the severity gate. */
+export const SEVERITY_ORDER = Object.freeze({ PASS: 0, COSMETIC: 1, DEGRADED: 2, BROKEN: 3 });
+
+/**
+ * All overall-verdict classes: findings severities + the three structural
+ * verdicts. The 0.7.0 per-AC verdict classes are NOT in this set — they
+ * ride on `perAcVerdicts[]`, not the run-level `verdict` field. Keeping
+ * them out preserves backward compatibility on `validateReportShape`
+ * (§5.3) for existing consumers that only knew the pre-0.7.0 classes.
+ */
+export const VERDICTS = Object.freeze([...FINDING_SEVERITIES, 'NOT-DEPLOYED', 'BLOCKED', 'LAUNCH-FAILURE']);
+
+/**
+ * Per-AC verdict classes emitted alongside the top-level verdict on
+ * `report.perAcVerdicts[]`. Consumed by `rcf finalise` to refuse promotion
+ * to `verified` on any of these AC-level verdicts (see
+ * `packages/rcf-lite/src/finalise/ingest.js:findMockOnlyDeclaredAcs`).
+ */
+export const PER_AC_VERDICTS = Object.freeze([
+  'MOCK-ONLY-DECLARED',
+  'BLOCKED-BY-DECLARATION',
+  'UI-BASELINE-UNMET',
+  'BROWSER-VERIFICATION-MISSING',
+]);
+
+/**
+ * Required fields on every finding (spec §5.2): the RCF payoff is that every
+ * defect maps to a contract line (acId / chain node), never a free-floating
+ * bug.
+ *
+ * @param {object} finding
+ * @returns {import('#core/errors').RcfError | null} error as data, or null if valid
+ */
+export function validateFinding(finding) {
+  if (!finding || typeof finding !== 'object') {
+    return rcfError({ kind: 'validation', message: 'finding must be an object' });
+  }
+  if (!FINDING_SEVERITIES.includes(finding.severity)) {
+    return rcfError({ kind: 'validation', message: `finding.severity must be one of ${FINDING_SEVERITIES.join('/')}`, field: 'severity' });
+  }
+  if (typeof finding.acId !== 'string' || finding.acId.length === 0) {
+    return rcfError({ kind: 'validation', message: 'finding.acId (chain-node reference) is required', field: 'acId' });
+  }
+  if (typeof finding.journey !== 'string' || finding.journey.length === 0) {
+    return rcfError({ kind: 'validation', message: 'finding.journey is required', field: 'journey' });
+  }
+  if (!Array.isArray(finding.reproSteps)) {
+    return rcfError({ kind: 'validation', message: 'finding.reproSteps must be an array', field: 'reproSteps' });
+  }
+  if (!finding.evidence || typeof finding.evidence !== 'object') {
+    return rcfError({ kind: 'validation', message: 'finding.evidence must be an object', field: 'evidence' });
+  }
+  return null;
+}
+
+/**
+ * The worst (max) severity across findings. Empty → PASS. This is the
+ * split-not-averaged rule: the single worst finding drives the class.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @returns {'PASS'|'COSMETIC'|'DEGRADED'|'BROKEN'}
+ */
+export function aggregateSeverity(findings = []) {
+  let worst = 'PASS';
+  for (const f of findings) {
+    if ((SEVERITY_ORDER[f.severity] ?? -1) > SEVERITY_ORDER[worst]) worst = f.severity;
+  }
+  return worst;
+}
+
+/**
+ * The overall run verdict (spec §5.1). NOT-DEPLOYED and a fully-blocked run
+ * are structural verdicts; otherwise the worst finding severity wins
+ * (split-not-averaged). A run with SOME findings and SOME blocked ACs is a
+ * partial verification: the verdict reflects what WAS exercised, and the
+ * blocked ACs are named separately in the report.
+ *
+ * @param {object} opts
+ * @param {Array<{severity: string}>} [opts.findings]
+ * @param {Array<object>} [opts.blockedAcs]
+ * @param {boolean} [opts.notDeployed]
+ * @returns {string}
+ */
+export function aggregateVerdict({ findings = [], blockedAcs = [], notDeployed = false } = {}) {
+  if (notDeployed) return 'NOT-DEPLOYED';
+  if (findings.length === 0 && blockedAcs.length > 0) return 'BLOCKED';
+  return aggregateSeverity(findings);
+}
+
+/**
+ * Whether the severity gate is tripped → the process exits non-zero
+ * (spec §3 rule 5, §8.2). NOT-DEPLOYED, BLOCKED and LAUNCH-FAILURE always trip
+ * (ship cannot be confirmed); otherwise the worst finding severity is compared
+ * against the gate. With no gate configured, nothing trips — the report is
+ * still written.
+ *
+ * @param {object} opts
+ * @param {string} opts.verdict
+ * @param {Array<{severity: string}>} [opts.findings]
+ * @param {string|null} [opts.gate] - one of FINDING_SEVERITIES, or null/undefined
+ * @returns {boolean}
+ */
+export function gateTripped({ verdict, findings = [], gate }) {
+  if (verdict === 'NOT-DEPLOYED' || verdict === 'BLOCKED' || verdict === 'LAUNCH-FAILURE') return true;
+  if (!gate) return false;
+  const worst = aggregateSeverity(findings);
+  return SEVERITY_ORDER[worst] >= SEVERITY_ORDER[gate];
+}
+
+/**
+ * Resolve the Track A per-AC verdict from an AC's aggregated service
+ * attestations. Priority: `declaredMockOnly` wins over `mocked`, because
+ * a chain that explicitly declared mock-only overrides an implicit mock.
+ * `live` / `sandboxed` / `notShipped` never emit a per-AC verdict here —
+ * they either mean a live path exists (verify's normal findings pipeline
+ * handles them) or the AC does not gate ship at all.
+ *
+ * @param {Array<{serviceId: string, attestationMode: string}>} attestations
+ * @returns {{ verdict: 'MOCK-ONLY-DECLARED'|'BLOCKED-BY-DECLARATION', reason: string } | null}
+ */
+export function attestationPerAcVerdict(attestations = []) {
+  if (!Array.isArray(attestations) || attestations.length === 0) return null;
+  const declared = attestations.find((a) => a && a.attestationMode === 'declaredMockOnly');
+  if (declared) {
+    return {
+      verdict: 'BLOCKED-BY-DECLARATION',
+      reason: `operator declared mock-only at pre-flight for service ${declared.serviceId}; verify refused to issue a live verdict rather than fabricate a PASS.`,
+    };
+  }
+  const mocked = attestations.find((a) => a && a.attestationMode === 'mocked');
+  if (mocked) {
+    return {
+      verdict: 'MOCK-ONLY-DECLARED',
+      reason: `service ${mocked.serviceId} is chain-attested \`mocked\`; verify has no live path to the third party and no observable delivery record on the running app.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve the Track B per-AC UI verdict for an AC. UI verdicts fire only
+ * for `fbsUiBearing: true` ACs (the chain-derived flag from
+ * `packages/rcf-lite/src/verify/chain/index.js`). Priority:
+ *   1. Any bound FBS has NO browserVerification entry → BROWSER-VERIFICATION-MISSING.
+ *   2. Any bound FBS's browserVerification.verdict is `block` → UI-BASELINE-UNMET.
+ *   3. Otherwise no per-AC UI verdict is emitted.
+ *
+ * @param {object} ac - a flattened AC with `fbsUiBearing` and `fbsIds`
+ * @param {object[]} [browserVerification] - manifest.browserVerification[]
+ * @returns {{ verdict: 'UI-BASELINE-UNMET'|'BROWSER-VERIFICATION-MISSING', reason: string } | null}
+ */
+export function uiPerAcVerdict(ac, browserVerification = []) {
+  if (!ac || ac.fbsUiBearing !== true) return null;
+  const fbsIds = Array.isArray(ac.fbsIds) ? ac.fbsIds : [];
+  if (fbsIds.length === 0) return null;
+  const bv = Array.isArray(browserVerification) ? browserVerification : [];
+  const missing = [];
+  const blocked = [];
+  for (const fbsId of fbsIds) {
+    const records = bv.filter((r) => r && r.fbsId === fbsId);
+    if (records.length === 0) {
+      missing.push(fbsId);
+      continue;
+    }
+    // Take the freshest record — records land per-run and the latest verdict
+    // is the one that gates ship. `createdAt` sorts lexicographically for ISO
+    // timestamps; when it is missing fall back to array order (the last
+    // written entry wins).
+    const latest = [...records].sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? '')).pop();
+    if (latest && latest.verdict === 'block') blocked.push({ fbsId, id: latest.id ?? null });
+  }
+  if (missing.length > 0) {
+    return {
+      verdict: 'BROWSER-VERIFICATION-MISSING',
+      reason: `UI-bearing FBS(es) ${missing.join(', ')} have no browserVerification record on the manifest; verify has nothing to read for the baseline check.`,
+    };
+  }
+  if (blocked.length > 0) {
+    const detail = blocked.map((b) => `${b.fbsId}${b.id ? ` (${b.id})` : ''}`).join(', ');
+    return {
+      verdict: 'UI-BASELINE-UNMET',
+      reason: `browserVerification recorded verdict \`block\` for ${detail}; the deployed UI failed at least one baseline invariant.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Emit per-AC verdicts across the whole chain. Combines Track A's service
+ * attestation verdicts with Track B's UI-baseline verdicts. An AC can carry
+ * BOTH a service-attestation verdict AND a UI verdict (a UI-bearing FBS
+ * that also depends on a mocked service produces two per-AC entries — one
+ * per class). This matches the finalise gate contract in
+ * `packages/rcf-lite/src/finalise/ingest.js:findMockOnlyDeclaredAcs`, which
+ * filters on verdict class and does not deduplicate by acId.
+ *
+ * @param {object} opts
+ * @param {Array<object>} opts.acs - flattened ACs from `readChain`
+ * @param {object[]} [opts.browserVerification] - manifest.browserVerification[]
+ * @returns {Array<{ acId: string, verdict: string, reason: string }>}
+ */
+export function derivePerAcVerdicts({ acs = [], browserVerification = [] } = {}) {
+  const out = [];
+  for (const ac of acs) {
+    const attest = attestationPerAcVerdict(ac.serviceAttestations);
+    if (attest) out.push({ acId: ac.acId, verdict: attest.verdict, reason: attest.reason });
+    const ui = uiPerAcVerdict(ac, browserVerification);
+    if (ui) out.push({ acId: ac.acId, verdict: ui.verdict, reason: ui.reason });
+  }
+  return out;
+}

package/src/view/doc-renderers/adr.js

@@ -0,0 +1,44 @@
+// ADR renderer.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLink,
+  docLinkList,
+  escapeHtml,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} adr
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @returns {string}
+ */
+export function renderAdr(adr, ctx) {
+  if (!adr) return '';
+  const anchor = anchorIdFor(adr.adrId ?? 'ADR');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const alts = (adr.alternativesConsidered ?? []).map((a) => `<li><strong>${escapeHtml(a.name ?? '')}</strong> - ${escapeHtml(a.summary ?? '')}<br/><em>Not chosen because:</em> ${escapeHtml(a.reasonNotChosen ?? '')}</li>`).join('');
+  const supersededBy = adr.supersededBy
+    ? `<p><strong>Superseded by:</strong> ${docLink(adr.supersededBy)}</p>`
+    : '';
+  const related = Array.isArray(adr.relatedAdrs) && adr.relatedAdrs.length > 0
+    ? `<p><strong>Related ADRs:</strong> ${docLinkList(adr.relatedAdrs)}</p>`
+    : '';
+  return `
+<article id="${anchor}" class="doc doc-adr">
+  <h3>${escapeHtml(adr.adrId ?? 'ADR')} - ${escapeHtml(adr.title ?? '')}</h3>
+  ${broken}
+  ${fieldPara('Status', adr.status)}
+  ${fieldPara('Context', adr.context)}
+  ${fieldPara('Decision', adr.decision)}
+  ${fieldPara('Consequences', adr.consequences)}
+  ${alts ? `<section class="field-list"><h4>Alternatives considered</h4><ul>${alts}</ul></section>` : ''}
+  ${supersededBy}
+  ${related}
+  ${rawJsonDisclosure(ctx.raw, adr, adr.adrId)}
+</article>`.trim();
+}

package/src/view/doc-renderers/build-sequence.js

@@ -0,0 +1,40 @@
+// Build Sequence renderer. Post-3.7 (D15) the ordered FBS slot list is not
+// read from the removed `bs.fbs[]` array but computed by the caller and
+// passed via `ctx.slots` -- a list of `{ fbsId, buildOrder, executionStatus,
+// title? }` sorted by buildOrder ascending.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLink,
+  escapeHtml,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} bs
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {Array<{ fbsId: string, buildOrder: number, executionStatus?: string, title?: string }>} [ctx.slots]
+ * @returns {string}
+ */
+export function renderBuildSequence(bs, ctx) {
+  if (!bs) return '';
+  const anchor = anchorIdFor(bs.bsId ?? 'BS');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const slots = Array.isArray(ctx.slots)
+    ? [...ctx.slots].sort((a, b) => (a.buildOrder ?? 0) - (b.buildOrder ?? 0))
+    : [];
+  const slotList = slots.map((s) => `<li><strong>${s.buildOrder ?? '?'}.</strong> ${docLink(s.fbsId)} - <span class="status ${escapeHtml(s.executionStatus ?? '')}">${escapeHtml(s.executionStatus ?? 'unknown')}</span>${s.title ? ` - ${escapeHtml(s.title)}` : ''}</li>`).join('');
+  return `
+<article id="${anchor}" class="doc doc-bs">
+  <h3>${escapeHtml(bs.bsId ?? 'BS')} - ${escapeHtml(bs.title ?? 'Build sequence')}</h3>
+  ${broken}
+  ${fieldPara('Build philosophy', bs.buildPhilosophy)}
+  ${fieldPara('Generation strategy', bs.generationStrategy)}
+  <section class="field-list"><h4>FBS slots</h4><ol>${slotList}</ol></section>
+  ${rawJsonDisclosure(ctx.raw, bs, bs.bsId)}
+</article>`.trim();
+}

package/src/view/doc-renderers/fbs.js

@@ -0,0 +1,128 @@
+// FBS renderer. Resolves AC ids into their Given/When/Then text rather
+// than rendering just the id, so an owner reviewing an FBS section can read
+// what each AC requires without jumping back to the User stories area.
+// Phase 3.2: `acIds` are also rendered as clickable pills at the top so the
+// operator can jump directly across into Requirements-tab context (D8).
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLink,
+  docLinkList,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} fbs
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {Map<string, object>} [ctx.usByAcId]
+ * @returns {string}
+ */
+export function renderFbs(fbs, ctx) {
+  if (!fbs) return '';
+  const anchor = anchorIdFor(fbs.fbsId ?? 'FBS');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const acPills = renderAcPills(fbs.acIds ?? []);
+  const acBlocks = (fbs.acIds ?? []).map((acId) => renderResolvedAc(acId, ctx)).join('\n');
+  const ctxReq = fbs.contextRequirements ?? {};
+  const ctxBlocks = renderContextRequirements(ctxReq);
+  const designBlock = renderDesignBlock(fbs);
+  const designSlot = designBlock ? `\n  ${designBlock}` : '';
+  return `
+<article id="${anchor}" class="doc doc-fbs">
+  <h3>${escapeHtml(fbs.fbsId ?? 'FBS')} - ${escapeHtml(fbs.title ?? '')}</h3>
+  ${broken}
+  ${fieldPara('Summary', fbs.summary)}
+  ${fieldPara('Approach', fbs.approach)}
+  ${acPills}
+  <section class="field-list"><h4>Acceptance criteria delivered</h4>${acBlocks}</section>
+  ${ctxBlocks}${designSlot}
+  ${fbs.dependsOnFbsIds?.length ? `<section class="field-list"><h4>Depends on</h4><p>${docLinkList(fbs.dependsOnFbsIds)}</p></section>` : ''}
+  ${fieldPara('Estimated size', fbs.estimatedSize)}
+  ${fieldPara('Estimated hours', fbs.estimatedHours)}
+  ${fieldList('Deliverables', fbs.deliverables)}
+  ${fieldPara('Risk level', fbs.riskLevel)}
+  ${fieldPara('Build order', fbs.buildOrder)}
+  ${fieldPara('Execution status', fbs.executionStatus)}
+  ${fieldPara('Notes', fbs.notes)}
+  ${rawJsonDisclosure(ctx.raw, fbs, fbs.fbsId)}
+</article>`.trim();
+}
+
+/**
+ * Design substage block (Track B, ui-design-gate-0.7.0-spec §5.5
+ * "Honest cost" list: FBS view renderer surfaces designStageComplete +
+ * the designStage artefacts). Renders nothing for non-UI FBS.
+ *
+ * @param {object} fbs
+ * @returns {string}
+ */
+function renderDesignBlock(fbs) {
+  if (fbs?.uiBearing !== true && !fbs?.designStage && fbs?.designStageComplete !== true) return '';
+  const stage = fbs.designStage ?? {};
+  const journeyCount = Array.isArray(stage.journeys) ? stage.journeys.length : 0;
+  const navShape = stage.navModel?.shape ?? '(none)';
+  const routeCount = Array.isArray(stage.navModel?.routes) ? stage.navModel.routes.length : 0;
+  const themeMode = stage.themeAndA11y?.themeMode ?? '(none)';
+  const complete = fbs?.designStageComplete === true;
+  return `<section class="field-list"><h4>Design substage</h4>
+  <p><strong>UI-bearing:</strong> ${escapeHtml(String(fbs?.uiBearing ?? false))}</p>
+  <p><strong>Design stage complete:</strong> ${escapeHtml(String(complete))}</p>
+  <p><strong>Journeys:</strong> ${escapeHtml(String(journeyCount))}</p>
+  <p><strong>Nav model:</strong> ${escapeHtml(String(navShape))} (${escapeHtml(String(routeCount))} route(s))</p>
+  <p><strong>Theme and a11y:</strong> ${escapeHtml(String(themeMode))}</p>
+</section>`;
+}
+
+function renderAcPills(acIds) {
+  if (!Array.isArray(acIds) || acIds.length === 0) return '';
+  const pills = acIds.map((id) => `<a class="ac-pill" href="#${escapeHtml(id)}">${escapeHtml(id)}</a>`).join('');
+  return `<div class="ac-pills">${pills}</div>`;
+}
+
+function renderResolvedAc(acId, ctx) {
+  const us = ctx.usByAcId?.get(acId);
+  const ac = us?.acceptanceCriteria?.find((a) => a.id === acId);
+  if (!ac) {
+    return `<div class="ac-resolved broken"><p><strong>${escapeHtml(acId)}</strong> (unresolved)</p></div>`;
+  }
+  return `
+<div class="ac-resolved">
+  <p><strong>${docLink(acId)}</strong> - ${escapeHtml(ac.description ?? '')}</p>
+  ${ac.given ? `<p><em>Given</em> ${escapeHtml(ac.given)}</p>` : ''}
+  ${ac.when ? `<p><em>When</em> ${escapeHtml(ac.when)}</p>` : ''}
+  ${ac.then ? `<p><em>Then</em> ${escapeHtml(ac.then)}</p>` : ''}
+</div>`.trim();
+}
+
+function renderContextRequirements(ctx) {
+  const parts = [];
+  if (Array.isArray(ctx.tadSections) && ctx.tadSections.length > 0) {
+    parts.push(`<p><strong>TAD sections:</strong> ${ctx.tadSections.map((s) => escapeHtml(s)).join(', ')}</p>`);
+  }
+  if (Array.isArray(ctx.tacIds) && ctx.tacIds.length > 0) {
+    parts.push(`<p><strong>TACs:</strong> ${docLinkList(ctx.tacIds)}</p>`);
+  }
+  if (Array.isArray(ctx.adrIds) && ctx.adrIds.length > 0) {
+    parts.push(`<p><strong>ADRs:</strong> ${docLinkList(ctx.adrIds)}</p>`);
+  }
+  if (Array.isArray(ctx.schemas) && ctx.schemas.length > 0) {
+    parts.push(`<p><strong>Schemas:</strong> ${ctx.schemas.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ')}</p>`);
+  }
+  if (Array.isArray(ctx.externalDocs) && ctx.externalDocs.length > 0) {
+    parts.push(`<p><strong>External docs:</strong> ${ctx.externalDocs.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ')}</p>`);
+  }
+  if (Array.isArray(ctx.existingModules) && ctx.existingModules.length > 0) {
+    parts.push(`<p><strong>Existing modules:</strong> ${ctx.existingModules.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ')}</p>`);
+  }
+  if (Array.isArray(ctx.other) && ctx.other.length > 0) {
+    parts.push(`<p><strong>Other:</strong> ${ctx.other.map((s) => escapeHtml(s)).join(', ')}</p>`);
+  }
+  if (parts.length === 0) return '';
+  return `<section class="field-list"><h4>Context requirements</h4>${parts.join('\n')}</section>`;
+}

package/src/view/doc-renderers/helpers.js

@@ -0,0 +1,159 @@
+// Small helpers shared across the per-document renderers. Vanilla template
+// strings; no template engine.
+
+/**
+ * HTML-escape a string for safe injection between tags.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml(value) {
+  if (value === null || value === undefined) return '';
+  const s = String(value);
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Return the raw document id as an anchor id. Phase 3.2 unified the anchor
+ * convention around the display id (e.g. "REQ-002") so Mermaid click targets
+ * and internal doc links resolve to the same DOM node.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function anchorIdFor(id) {
+  return String(id);
+}
+
+/**
+ * Render an `<a>` link to the section of another document.
+ *
+ * @param {string} id
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function docLink(id, label) {
+  return `<a href="#${anchorIdFor(id)}">${escapeHtml(label ?? id)}</a>`;
+}
+
+/**
+ * Render a list of ids as comma-separated doc links.
+ *
+ * @param {string[] | undefined} ids
+ * @returns {string}
+ */
+export function docLinkList(ids) {
+  if (!Array.isArray(ids) || ids.length === 0) return '<em>none</em>';
+  return ids.map((id) => docLink(id)).join(', ');
+}
+
+/**
+ * Render a paragraph if value is present.
+ *
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function fieldPara(label, value) {
+  if (value === undefined || value === null || value === '') return '';
+  return `<p><strong>${escapeHtml(label)}:</strong> ${escapeHtml(value)}</p>`;
+}
+
+/**
+ * Render an unordered list if items are present.
+ *
+ * @param {string} label
+ * @param {string[] | undefined} items
+ * @returns {string}
+ */
+export function fieldList(label, items) {
+  if (!Array.isArray(items) || items.length === 0) return '';
+  const li = items.map((s) => `<li>${escapeHtml(s)}</li>`).join('');
+  return `<section class="field-list"><h4>${escapeHtml(label)}</h4><ul>${li}</ul></section>`;
+}
+
+/**
+ * Render the "Show raw JSON" disclosure block for a document.
+ *
+ * Phase 3.8 D13b: the raw-JSON disclosure now carries a stable
+ * `data-doc-id="{parentDocId}::raw"` attribute so the live-client can
+ * persist its open state across SSE swaps and page reloads. The main
+ * doc-details already get a `data-doc-id` via `detailsWrap`; this closes
+ * the last state-persistence gap.
+ *
+ * @param {string|undefined} raw
+ * @param {object} doc
+ * @param {string} parentDocId - the enclosing doc's display id (e.g. "REQ-002")
+ * @returns {string}
+ */
+export function rawJsonDisclosure(raw, doc, parentDocId) {
+  const json = raw ?? JSON.stringify(doc, null, 2);
+  const rawId = `${parentDocId ?? 'doc'}::raw`;
+  return `<details class="raw-json" data-doc-id="${escapeHtml(rawId)}"><summary>Show raw JSON</summary><pre>${escapeHtml(json)}</pre></details>`;
+}
+
+/**
+ * Render a broken-document banner above the rest of a document section.
+ *
+ * @param {import('#core/errors').RcfError[]} errors
+ * @returns {string}
+ */
+export function brokenBanner(errors) {
+  if (!errors || errors.length === 0) return '';
+  const items = errors
+    .map((e) => `<li><code>${escapeHtml(e.kind)}</code> ${escapeHtml(e.message)}</li>`)
+    .join('');
+  return `
+<aside class="broken" role="alert">
+  <p><strong>Broken document</strong> - schema validation or reference failure.</p>
+  <ul>${items}</ul>
+</aside>`.trim();
+}
+
+/**
+ * Render a broken-reference placeholder when a referenced id has no file.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function brokenReferenceSection(id) {
+  const anchor = anchorIdFor(id);
+  return `
+<article id="${anchor}" class="doc broken-doc">
+  <h3>${escapeHtml(id)} - broken reference</h3>
+  <aside class="broken" role="alert">
+    <p>Referenced by a parent document but no file was found at the expected path.</p>
+  </aside>
+</article>`.trim();
+}
+
+/**
+ * Wrap a doc's rendered body in a `<details data-doc-id>` so it can be
+ * drilled-in from the tab tree. Closed by default. The `data-doc-id`
+ * attribute is what the hash-routing script targets.
+ *
+ * @param {object} args
+ * @param {string} args.id - display doc id (e.g. "REQ-001")
+ * @param {string} args.summary - short label shown in the summary line
+ * @param {string} args.className - class applied to the details wrapper
+ * @param {string} args.body - the rendered body HTML
+ * @param {string} [args.status] - optional doc status, rendered as a pill
+ * @returns {string}
+ */
+export function detailsWrap({
+  id, summary, className, body, status,
+}) {
+  const statusPill = status
+    ? `<span class="status ${escapeHtml(status)}">${escapeHtml(status)}</span>`
+    : '';
+  return `
+<details class="doc-details ${className}" data-doc-id="${escapeHtml(id)}">
+  <summary><span class="summary-label">${escapeHtml(summary)}</span>${statusPill}</summary>
+  ${body}
+</details>`.trim();
+}

package/src/view/doc-renderers/index.js

@@ -0,0 +1,12 @@
+// Doc renderer index. Re-exports each per-type renderer so html-page.js can
+// import them through a single module.
+
+export { renderPrd } from './prd.js';
+export { renderReq } from './req.js';
+export { renderUserStory } from './user-story.js';
+export { renderTad } from './tad.js';
+export { renderTac } from './tac.js';
+export { renderAdr } from './adr.js';
+export { renderBuildSequence } from './build-sequence.js';
+export { renderFbs } from './fbs.js';
+export { renderTestSuite } from './test-suite.js';

package/src/view/doc-renderers/prd.js

@@ -0,0 +1,45 @@
+// PRD renderer. Curated fields per spec D11. Post-3.7 (D15) the child REQ
+// list is not read from `prd.requirementIds` (removed in 0.2.0) but from
+// the computed `childrenByParent` map on the tree model.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLinkList,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} prd
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {string[]} [ctx.requirementIds] - computed REQ children for this PRD
+ * @returns {string}
+ */
+export function renderPrd(prd, ctx) {
+  if (!prd) return '';
+  const anchor = anchorIdFor(prd.prdId ?? 'PRD');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const requirementIds = ctx.requirementIds ?? [];
+  const sections = [
+    fieldPara('Executive summary', prd.executiveSummary),
+    fieldPara('Problem statement', prd.problemStatement),
+    fieldList('Target users', prd.targetUsers),
+    fieldList('In scope', prd.inScope),
+    fieldList('Out of scope', prd.outOfScope),
+    fieldList('Objectives', prd.objectives),
+    fieldList('Constraints', prd.constraints),
+    `<section class="field-list"><h4>Requirements</h4><p>${docLinkList(requirementIds)}</p></section>`,
+  ].filter(Boolean).join('\n');
+  return `
+<article id="${anchor}" class="doc doc-prd">
+  <h3>${escapeHtml(prd.prdId ?? 'PRD')} - ${escapeHtml(prd.productName ?? '')}</h3>
+  ${broken}
+  ${sections}
+  ${rawJsonDisclosure(ctx.raw, prd, prd.prdId)}
+</article>`.trim();
+}