rcf-lite 0.28.2 → 0.28.4

package/src/query/index.js

@@ -4,6 +4,42 @@
 export { computeCoverage, classifyCoverageScope } from './coverage.js';
 export { computeTrace, kindOf } from './trace.js';
 export { computeImpact, labelFor } from './impact.js';
+// Detection model (REQ-172, proposal 2026-09-22 §2.2 v3). Pure hashes
+// over the parsed tree; every downstream DEFINE gate reads this delta.
+export {
+  canonicaliseJson,
+  hashDocument,
+  computeTreeHash,
+  computeDelta,
+} from './delta.js';
+// DEFINE stage gates (REQ-174; proposal §2.4, §3.2 v3). One check
+// function per stage; foldState + parseAcClass helpers.
+export {
+  STAGE_ORDER,
+  STAGE_GATES,
+  STAGE_SHORT_NAMES,
+  STAGE_ALIASES,
+  INTERFACE_KINDS,
+  stagePolicy,
+  parseAcClass,
+  foldState,
+  runStage,
+  checkD1Brief,
+  checkD2Skeleton,
+  checkD3Shapes,
+  checkD4Stories,
+  checkD5Crosscut,
+  checkD6Consistency,
+  checkD7Decisions,
+  checkD8Freeze,
+} from './gates.js';
+// Readiness composer (REQ-175; proposal §2.4, §6 v3).
+export {
+  computeReadiness,
+  deriveNextAction,
+  shortHash,
+  formatTreeLine,
+} from './readiness.js';
 export { formatTable } from './formatters/table.js';
 export { formatJson } from './formatters/json.js';
 export { formatMermaid } from './formatters/mermaid.js';

package/src/query/readiness.js

@@ -0,0 +1,333 @@
+// Readiness compute (REQ-175; proposal 2026-09-22 §2.4, §6 v3).
+//
+// One pure composer over the DEFINE detection primitives:
+//   1. `computeDelta` (slice 1) -> changed / added / removed / briefSince
+//   2. `computeImpact` per id in changed union added -> fan-out
+//   3. Eight gate check functions from `./gates.js` -> stage[]
+//   4. `computeCoverage` tree-wide plus per REQ ancestor of the delta
+//   5. Open decisions from the decisions ledger
+//   6. Fold to `freezeable` (every stage passed / acknowledged /
+//      notApplicable) and `nextAction` (first failing stage + check)
+//
+// Return shape mirrors proposal §2.4 exactly. The CLI (rcf define
+// readiness) and the viewer's Readiness tab (slice 5) render the same
+// object; the freeze verb (slice 3) refuses on any failing stage.
+
+import { computeQueue } from '../build/queue.js';
+import { computeCoverage } from './coverage.js';
+import { computeDelta } from './delta.js';
+import { computeImpact } from './impact.js';
+import {
+  STAGE_GATES,
+  STAGE_ORDER,
+  STAGE_SHORT_NAMES,
+  checkD1Brief,
+  checkD2Skeleton,
+  checkD3Shapes,
+  checkD4Stories,
+  checkD5Crosscut,
+  checkD6Consistency,
+  checkD7Decisions,
+  checkD8Freeze,
+} from './gates.js';
+
+/**
+ * @typedef {object} ReadinessTree
+ * @property {boolean} frozen
+ * @property {string | null} frozenAt
+ * @property {string | null} treeHash
+ * @property {string} currentTreeHash
+ * @property {string | null} buildAt   fbsId at the queue head, or null
+ * @property {number} fbsTotal
+ */
+
+/**
+ * @typedef {object} ReadinessDelta
+ * @property {string[]} changed
+ * @property {string[]} added
+ * @property {string[]} removed
+ * @property {number[]} briefSince
+ * @property {import('./impact.js').ImpactNode[]} impacted
+ * @property {string[]} impactedFbs
+ */
+
+/**
+ * @typedef {object} StageResult
+ * @property {string} stage
+ * @property {string} gate
+ * @property {'passed'|'failing'|'acknowledged'|'notApplicable'} state
+ * @property {Array<{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }> }>} checks
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {object} NextAction
+ * @property {string} stage
+ * @property {string} check
+ * @property {string[]} ids
+ * @property {string} command
+ */
+
+/**
+ * @typedef {object} ReadinessResult
+ * @property {ReadinessTree} tree
+ * @property {ReadinessDelta} delta
+ * @property {StageResult[]} stages
+ * @property {NextAction | null} nextAction
+ * @property {{ tree: import('./coverage.js').CoverageResult, delta: import('./coverage.js').CoverageResult[] }} coverage
+ * @property {Array<Record<string, unknown>>} decisions
+ * @property {boolean} freezeable
+ */
+
+/**
+ * Compute the readiness object.
+ *
+ * Pure over its inputs. Callers supply the ledgers bundle, freeze
+ * record, testPointers map (resolveTestPointers output) and optional
+ * profile switches; nothing else touches the filesystem.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} args
+ * @param {import('./delta.js').FreezeRecord | null | undefined} [args.freeze]
+ * @param {import('./delta.js').LedgerBundle | undefined} [args.ledgers]
+ * @param {{ skipReviewFor?: string } | undefined} [args.profile]
+ * @param {string | null | undefined} [args.profileText]  rcf/.identity/profile.md contents
+ * @param {Map<string, unknown> | undefined} [args.testPointers]
+ * @param {Array<unknown> | undefined} [args.validateErrors]  tree-wide validate + walker errors
+ * @returns {ReadinessResult}
+ */
+export function computeReadiness(tree, args = {}) {
+  const {
+    freeze = null,
+    ledgers = {},
+    profile = undefined,
+    profileText = null,
+    testPointers = undefined,
+    validateErrors = [],
+  } = args;
+
+  // 1. Delta.
+  const delta = computeDelta(tree, freeze, ledgers);
+
+  // 2. Fan-out via computeImpact per id in changed union added.
+  // Standalone-document ids only; ledger:<name> entries have no fan-out.
+  const pivotIds = [
+    ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+    ...delta.added.filter((id) => !id.startsWith('ledger:')),
+  ];
+  const pivotSet = new Set(pivotIds);
+  /** @type {import('./impact.js').ImpactNode[]} */
+  const impactedNodes = [];
+  const impactedSeen = new Set();
+  const impactedFbsSeen = new Set();
+  // Skip fan-out when the tree is unfrozen: the delta IS the whole tree
+  // (proposal §2.2 "before the first freeze the delta is the whole
+  // tree"), so a per-id fan-out is quadratic for no signal.
+  const runFanOut = delta.frozen === true;
+  if (runFanOut) {
+    for (const id of pivotIds) {
+      const impact = computeImpact(tree, { id });
+      if (!impact.found || !Array.isArray(impact.nodes)) continue;
+      for (const node of impact.nodes) {
+        if (node.role === 'pivot') continue;
+        if (pivotSet.has(node.id)) continue;
+        if (!impactedSeen.has(node.id)) {
+          impactedSeen.add(node.id);
+          impactedNodes.push(node);
+        }
+        if (node.kind === 'fbs' && node.actionNeeded === 're-execute') {
+          impactedFbsSeen.add(node.id);
+        }
+      }
+    }
+  }
+  const impactedFbs = [...impactedFbsSeen].sort();
+
+  // 3. Compose scope = changed union added union impacted (dedup, sort).
+  const scopeSet = new Set([
+    ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+    ...delta.added.filter((id) => !id.startsWith('ledger:')),
+    ...impactedSeen,
+  ]);
+
+  // 4. Coverage: tree-wide plus per REQ ancestor of the delta.
+  const coverageTree = computeCoverage(tree, { testPointers, strict: true });
+  const deltaReqIds = collectDeltaReqAncestors(tree, pivotIds);
+  const coverageDelta = [];
+  for (const reqId of deltaReqIds) {
+    coverageDelta.push(computeCoverage(tree, { testPointers, strict: true, scopeId: reqId }));
+  }
+
+  // 5. Run the eight gate check functions in order. D8 reads the
+  // prior stage states, so compose sequentially.
+  /** @type {StageResult[]} */
+  const stages = [];
+  const currentTreeHash = delta.currentTreeHash;
+  /** @type {import('./gates.js').StageContext} */
+  const ctx = {
+    tree,
+    ledgers,
+    delta,
+    freeze,
+    scope: scopeSet,
+    validateErrors,
+    // Prefer the caller-supplied probe count when it is passed; falls
+    // back to the ledger scan inside checkD6Consistency.
+    probeOpenCount: undefined,
+    coverageTree,
+    profileText,
+    profile,
+    currentTreeHash,
+    priorStages: undefined,
+  };
+  stages.push(checkD1Brief(ctx));
+  stages.push(checkD2Skeleton(ctx));
+  stages.push(checkD3Shapes(ctx));
+  stages.push(checkD4Stories(ctx));
+  stages.push(checkD5Crosscut(ctx));
+  stages.push(checkD6Consistency(ctx));
+  stages.push(checkD7Decisions(ctx));
+  stages.push(checkD8Freeze({ ...ctx, priorStages: stages.map((s) => ({ stage: s.stage, state: s.state })) }));
+
+  // 6. Open decisions in the #241 format for the surface consumer.
+  const decisions = /** @type {any} */ (ledgers?.decisions);
+  const decisionEntries = Array.isArray(decisions?.decisions) ? decisions.decisions : [];
+  const openDecisions = decisionEntries.filter((d) => d?.status === 'open');
+
+  // 7. Fold freezeable + nextAction.
+  const freezeable = stages.every((s) => s.state === 'passed' || s.state === 'acknowledged' || s.state === 'notApplicable');
+  const nextAction = freezeable ? null : deriveNextAction(stages);
+
+  // 8. Build the tree summary line inputs.
+  const queue = computeQueue(tree);
+  const fbsTotal = (tree.fbsItems ?? []).length;
+
+  /** @type {ReadinessResult} */
+  return {
+    tree: {
+      frozen: delta.frozen,
+      frozenAt: delta.frozenAt,
+      treeHash: delta.treeHash,
+      currentTreeHash: delta.currentTreeHash,
+      buildAt: queue.nextActionable ?? null,
+      fbsTotal,
+    },
+    delta: {
+      changed: delta.changed,
+      added: delta.added,
+      removed: delta.removed,
+      briefSince: delta.briefSince,
+      impacted: impactedNodes,
+      impactedFbs,
+    },
+    stages,
+    nextAction,
+    coverage: { tree: coverageTree, delta: coverageDelta },
+    decisions: openDecisions,
+    freezeable,
+  };
+}
+
+/**
+ * Walk back from every delta pivot to its REQ ancestor and collect
+ * the unique REQ ids. The walker records parent-child edges under
+ * `parentByChild`; the walk terminates at the first REQ hit.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {string[]} pivotIds
+ * @returns {string[]}
+ */
+function collectDeltaReqAncestors(tree, pivotIds) {
+  const seen = new Set();
+  for (const id of pivotIds) {
+    let cursor = id;
+    let hops = 0;
+    while (cursor && hops < 32) {
+      hops += 1;
+      const kind = tree.kindById?.get(cursor);
+      if (kind === 'req') {
+        seen.add(cursor);
+        break;
+      }
+      // Some kinds carry an explicit reqId; use that when the parent
+      // chain skips the REQ (e.g. a TC leaf whose parent is a TS).
+      const doc = tree.byId?.get(cursor);
+      if (doc && typeof doc === 'object' && typeof /** @type {any} */ (doc).reqId === 'string') {
+        seen.add(/** @type {any} */ (doc).reqId);
+        break;
+      }
+      const parent = tree.parentByChild?.get(cursor);
+      if (!parent) break;
+      cursor = parent;
+    }
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Pick the first failing stage in D1..D8 order and the first failing
+ * check inside it, then compose a `NextAction`.
+ *
+ * @param {StageResult[]} stages
+ * @returns {NextAction | null}
+ */
+export function deriveNextAction(stages) {
+  const byStage = new Map(stages.map((s) => [s.stage, s]));
+  for (const stageId of STAGE_ORDER) {
+    const s = byStage.get(stageId);
+    if (!s || s.state !== 'failing') continue;
+    // First failing check; tie-break by the largest failing list so
+    // the operator sees the most impactful gap first.
+    const failing = s.checks.filter((c) => !c.ok);
+    if (failing.length === 0) continue;
+    const check = failing.reduce((a, b) => (b.failing.length > a.failing.length ? b : a), failing[0]);
+    const ids = [...new Set(check.failing.map((f) => f.id))].slice(0, 20);
+    const shortName = STAGE_SHORT_NAMES[stageId] ?? stageId;
+    return {
+      stage: stageId,
+      check: check.name,
+      ids,
+      command: `rcf define readiness --check ${shortName}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Short 8-character prefix of a `sha256:<hex>` string, or '(none)' when
+ * absent. Kept exported so text formatters share one convention.
+ *
+ * @param {string | null | undefined} hash
+ * @returns {string}
+ */
+export function shortHash(hash) {
+  if (typeof hash !== 'string' || !hash.startsWith('sha256:')) return '(none)';
+  return hash.slice('sha256:'.length, 'sha256:'.length + 8);
+}
+
+/**
+ * One-line tree summary matching proposal §6.2:
+ *   "Frozen at 9f3a2c on 2026-09-20. 4 documents changed since, 11
+ *    impacted. Build at FBS-031 of 41; 2 FBS impacted."
+ *   "Unfrozen. 30 documents; the whole tree is the delta."
+ *
+ * @param {ReadinessResult} result
+ * @returns {string}
+ */
+export function formatTreeLine(result) {
+  const t = result.tree;
+  const d = result.delta;
+  if (!t.frozen) {
+    const total = d.added.length + d.changed.length;
+    return `Unfrozen. ${total} document${total === 1 ? '' : 's'}; the whole tree is the delta.`;
+  }
+  const changedCount = d.changed.length + d.added.length + d.removed.length;
+  const impactedCount = d.impacted.length;
+  const buildAt = t.buildAt ?? '(none)';
+  const impactedFbs = d.impactedFbs.length;
+  const at = t.frozenAt ? t.frozenAt.split('T')[0] : '(no timestamp)';
+  return `Frozen at ${shortHash(t.treeHash)} on ${at}. ${changedCount} document${changedCount === 1 ? '' : 's'} changed since, ${impactedCount} impacted. Build at ${buildAt} of ${t.fbsTotal}; ${impactedFbs} FBS impacted.`;
+}
+
+// Re-export for CLI convenience.
+export { STAGE_GATES, STAGE_ORDER, STAGE_SHORT_NAMES };

package/src/server/index.js

@@ -11,6 +11,7 @@
 // on top; the server itself does not `process.exit`.
 
 import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
@@ -42,6 +43,25 @@ import { createSseHub } from './sse.js';
  *   rewalk: () => Promise<void>,
  * }>}
  */
+
+/**
+ * Issue #248 (0.28.3): read a shipped static asset once and return
+ * `{ buffer, size, contentType }`. Any read failure surfaces here so
+ * `startServer` can fail fast with an ioFailure before it binds.
+ *
+ * @param {string} path
+ * @param {string} contentType
+ */
+async function loadStaticAsset(path, contentType) {
+  // Codex P2-1: derive size from the actual captured buffer, not from
+  // a parallel stat that could snapshot a different revision if the
+  // file is being replaced concurrently. A wrong content-length header
+  // would cause truncation or mis-alignment for the entire server
+  // lifetime because we cache both values together.
+  const buffer = await readFile(path);
+  return { buffer, size: buffer.length, contentType };
+}
+
 export async function startServer(args) {
   const projectRoot = args.projectRoot;
   const port = typeof args.port === 'number' ? args.port : 4373;
@@ -76,6 +96,7 @@ export async function startServer(args) {
           fullPageHtml: result.fullPageHtml,
           contentHtml: result.contentHtml,
           errors: result.errors,
+          pmPartials: result.pmPartials,
         };
         sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
         if (result.errors && result.errors.length > 0) {
@@ -97,10 +118,26 @@ export async function startServer(args) {
   // and the first SSE connect gets a real payload.
   await rewalk();
 
+  // Issue #248 (0.28.3): snapshot the shipped static assets at startup
+  // so a checkout branch switch during the server's lifetime cannot
+  // change what gets served. The tree walker is the only path that
+  // re-reads disk on rcf/ change; every other asset is fixed at boot.
+  const [styleAsset, mermaidAsset, liveClientAsset] = await Promise.all([
+    loadStaticAsset(STYLE_CSS_PATH, 'text/css; charset=utf-8'),
+    loadStaticAsset(VENDORED_MERMAID_PATH, 'application/javascript; charset=utf-8'),
+    loadStaticAsset(LIVE_CLIENT_PATH, 'application/javascript; charset=utf-8'),
+  ]);
+
   const scopeHandler = createScopeHandler({ projectRoot });
   const router = createRouter({
     currentState: () => state,
     sse,
+    // Snapshotted assets take precedence; the legacy path props are
+    // still passed so tests that mount the router directly with a
+    // path (no asset load) keep working.
+    styleAsset,
+    mermaidAsset,
+    liveClientAsset,
     stylePath: STYLE_CSS_PATH,
     mermaidPath: VENDORED_MERMAID_PATH,
     liveClientPath: LIVE_CLIENT_PATH,

package/src/server/routes.js

@@ -12,6 +12,22 @@
 
 import { readFile, stat } from 'node:fs/promises';
 
+// Issue #248 (0.28.3): the shipped static assets (style.css,
+// mermaid.min.js, live-client.js) MUST be resolved once at server
+// startup, not read from disk on every HTTP request. If the checkout
+// switches branches or the file mutates while the server runs, per-
+// request reads return the new bytes even though the HTML that
+// references them was rendered from a walk taken at startup. The
+// asymmetry produced the 2026-09-22 Product Map "unstyled preview"
+// regression: HTML from the store walker was old, style.css was
+// current, and the browser combined them.
+//
+// `deps.styleAsset`, `deps.mermaidAsset` and `deps.liveClientAsset`
+// carry `{ buffer, size, contentType }` snapshotted at startup. The
+// legacy `stylePath`/`mermaidPath`/`liveClientPath` props are kept
+// for backwards compatibility with tests that pass a path; the
+// router reads on-demand in that fallback path.
+
 const MIME = {
   html: 'text/html; charset=utf-8',
   css: 'text/css; charset=utf-8',
@@ -68,15 +84,33 @@ export function createRouter(deps) {
       return;
     }
     if (path === '/style.css') {
-      serveFile(res, deps.stylePath, MIME.css).catch((err) => fail(res, err));
+      serveAsset(res, deps.styleAsset, deps.stylePath, MIME.css).catch((err) => fail(res, err));
       return;
     }
     if (path === '/mermaid.min.js') {
-      serveFile(res, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
+      serveAsset(res, deps.mermaidAsset, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
       return;
     }
     if (path === '/live-client.js') {
-      serveFile(res, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      serveAsset(res, deps.liveClientAsset, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+    if (path.startsWith('/product-map/')) {
+      const state = deps.currentState();
+      if (!state || !state.pmPartials) {
+        res.writeHead(503, { 'content-type': MIME.txt });
+        res.end('view server initialising\n');
+        return;
+      }
+      const group = path.slice('/product-map/'.length);
+      const html = state.pmPartials[group];
+      if (typeof html !== 'string') {
+        res.writeHead(404, { 'content-type': MIME.txt });
+        res.end('unknown grouping\n');
+        return;
+      }
+      res.writeHead(200, { 'content-type': MIME.html, 'cache-control': 'no-store' });
+      res.end(html);
       return;
     }
     if (path === '/scope.json') {
@@ -94,6 +128,34 @@ export function createRouter(deps) {
   };
 }
 
+/**
+ * Issue #248 (0.28.3): serve a snapshotted asset when the server has
+ * one, otherwise fall through to the legacy per-request read. The
+ * happy path never touches the filesystem after startup, so a checkout
+ * switch during the server's lifetime cannot change what gets served.
+ *
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ buffer: Buffer, size: number, contentType?: string } | undefined | null} asset
+ * @param {string | undefined} fallbackPath
+ * @param {string} contentType
+ */
+async function serveAsset(res, asset, fallbackPath, contentType) {
+  if (asset && asset.buffer) {
+    res.writeHead(200, {
+      'content-type': asset.contentType ?? contentType,
+      'content-length': String(asset.size),
+    });
+    res.end(asset.buffer);
+    return;
+  }
+  if (fallbackPath) {
+    await serveFile(res, fallbackPath, contentType);
+    return;
+  }
+  res.writeHead(404, { 'content-type': MIME.txt });
+  res.end('not found\n');
+}
+
 async function serveFile(res, path, contentType) {
   let body;
   let size;

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

@@ -128,9 +128,9 @@ export function fieldObjectTable(label, rows, columns) {
  * @param {string} parentDocId - the enclosing doc's display id (e.g. "REQ-002")
  * @returns {string}
  */
-export function rawJsonDisclosure(raw, doc, parentDocId) {
+export function rawJsonDisclosure(raw, doc, parentDocId, idPrefix) {
   const json = raw ?? JSON.stringify(doc, null, 2);
-  const rawId = `${parentDocId ?? 'doc'}::raw`;
+  const rawId = `${idPrefix ?? ''}${parentDocId ?? 'doc'}::raw`;
   return `<details class="raw-json" data-doc-id="${escapeHtml(rawId)}"><summary>Show raw JSON</summary><pre>${escapeHtml(json)}</pre></details>`;
 }
 

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

@@ -18,11 +18,19 @@ import {
  * @param {string|undefined} ctx.raw
  * @param {import('#core/errors').RcfError[]} [ctx.errors]
  * @param {string|undefined} [ctx.subdiagram]
+ * @param {string|undefined} [ctx.idPrefix] - prefix prepended to every emitted
+ *   id/anchor so the same REQ can be rendered under multiple Product Map
+ *   buckets without duplicating ids. Empty when rendered from the
+ *   Requirements tab so its anchors stay canonical.
+ * @param {boolean} [ctx.suppressRawJson] - when true, the raw-JSON disclosure
+ *   is not emitted (Product Map compact cards; the disclosure stays on
+ *   the Requirements tab). AC-17007-1 payload weight.
  * @returns {string}
  */
 export function renderReq(req, ctx) {
   if (!req) return '';
-  const anchor = anchorIdFor(req.reqId ?? 'REQ');
+  const prefix = ctx.idPrefix ?? '';
+  const anchor = `${prefix}${anchorIdFor(req.reqId ?? 'REQ')}`;
   const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
   const subdiagram = ctx.subdiagram
     ? `<section class="subdiagram"><h4>Slice diagram</h4><pre class="mermaid">${escapeHtml(ctx.subdiagram)}</pre></section>`
@@ -38,6 +46,6 @@ export function renderReq(req, ctx) {
   ${fieldPara('Rationale', req.rationale)}
   ${fieldList('Tags', req.tags)}
   ${subdiagram}
-  ${rawJsonDisclosure(ctx.raw, req, req.reqId)}
+  ${ctx.suppressRawJson ? '' : rawJsonDisclosure(ctx.raw, req, req.reqId, prefix)}
 </article>`.trim();
 }

package/src/view/doc-renderers/user-story.js

@@ -18,13 +18,18 @@ import {
  * @param {string|undefined} ctx.raw
  * @param {import('#core/errors').RcfError[]} [ctx.errors]
  * @param {Map<string, object[]>} [ctx.fbsByAcId]
+ * @param {string|undefined} [ctx.idPrefix] - prefix prepended to every emitted
+ *   id/anchor (article, AC li items, raw-JSON disclosure) so a US rendered
+ *   under multiple Product Map buckets does not collide with the canonical
+ *   Requirements-tab anchors. Empty from the Requirements tab.
  * @returns {string}
  */
 export function renderUserStory(us, ctx) {
   if (!us) return '';
-  const anchor = anchorIdFor(us.usId ?? 'US');
+  const prefix = ctx.idPrefix ?? '';
+  const anchor = `${prefix}${anchorIdFor(us.usId ?? 'US')}`;
   const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
-  const acItems = (us.acceptanceCriteria ?? []).map((ac) => renderAcItem(ac, ctx)).join('\n');
+  const acItems = (us.acceptanceCriteria ?? []).map((ac) => renderAcItem(ac, ctx, prefix)).join('\n');
   return `
 <article id="${anchor}" class="doc doc-us">
   <h3>${escapeHtml(us.usId ?? 'US')} - ${escapeHtml(us.title ?? '')}</h3>
@@ -40,13 +45,13 @@ export function renderUserStory(us, ctx) {
       ${acItems}
     </ul>
   </section>
-  ${rawJsonDisclosure(ctx.raw, us, us.usId)}
+  ${ctx.suppressRawJson ? '' : rawJsonDisclosure(ctx.raw, us, us.usId, prefix)}
 </article>`.trim();
 }
 
-function renderAcItem(ac, ctx) {
+function renderAcItem(ac, ctx, prefix) {
   const acId = ac.id ?? 'AC';
-  const acAnchor = anchorIdFor(acId);
+  const acAnchor = `${prefix ?? ''}${anchorIdFor(acId)}`;
   const fbsList = ctx.fbsByAcId?.get(acId) ?? [];
   const coveredBy = fbsList.length === 0
     ? '<em>not yet delivered by any FBS</em>'