rcf-lite 0.32.4 → 0.33.0

package/src/view/readiness/composite-id.js

@@ -0,0 +1,35 @@
+// Composite id splitter for the Readiness blocking table (TAC-4135
+// splitCompositeId, ADR-4139; FBS-204, US-18003 AC-18003-4).
+//
+// Failing items in `stages[].checks[].failing[]` and in
+// `levels.*.blockedBy[].ids[]` sometimes carry a composite id of the
+// shape `<docId>:<fragment>` (for example "AC-060-3:userID" or
+// "TAC-4122-define-gates:checkPersona"). The blocking table needs the
+// document part on its own so the row's link resolves through
+// findByDocId; the fragment stays visible so the row still names the
+// exact failing nib. Split on the first colon so the fragment keeps
+// its own colons (TAD-001:security:foo splits to docId=TAD-001,
+// fragment=security:foo).
+//
+// Pure, no I/O. Returns { docId, fragment } where `fragment` is '' when
+// no colon is present. A null / non-string input yields { docId: '',
+// fragment: '' } so callers can wrap defensively.
+
+/**
+ * @typedef {object} SplitId
+ * @property {string} docId     the resolvable document id (part before the first colon)
+ * @property {string} fragment  the remainder (empty when there was no colon)
+ */
+
+/**
+ * Split a composite failing id on the FIRST colon.
+ *
+ * @param {string | null | undefined} id
+ * @returns {SplitId}
+ */
+export function splitCompositeId(id) {
+  if (typeof id !== 'string' || id.length === 0) return { docId: '', fragment: '' };
+  const i = id.indexOf(':');
+  if (i === -1) return { docId: id, fragment: '' };
+  return { docId: id.slice(0, i), fragment: id.slice(i + 1) };
+}

package/src/view/readiness/coverage-summary.js

@@ -0,0 +1,293 @@
+// Readiness coverage summary (FBS-205, US-18004 under REQ-180,
+// TAC-4135-readiness-command-page, ADR-4139-readiness-tables-read-only-no-commands).
+//
+// Replaces renderCoverage. The old block read `coverage.tree.pass`
+// and `coverage.tree.total`, which never exist on the real compute
+// (coverage.tree carries `totals.{requirements, covered,
+// coveredUnresolved, uncovered}` and `requirements[].coverageClass`
+// plus `unresolvedTestPointers[]`). The result rendered as "pass  /
+// " blanks on every real tree. This module reads the fields that
+// coverage actually produces and prints a stat line, one stacked
+// bar, a family tiles row and (when non-empty) an unresolved-
+// pointers table. Every value renders as either a number or the
+// words "coverage unavailable"; a blank never leaves the page.
+//
+// Pure HTML-string render. No scripts, no commands, no write
+// controls. Tokens stay on --sv-* (contrast-aa.test.js) and no new
+// token is introduced.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+const UNAVAILABLE = 'coverage unavailable';
+
+/**
+ * @typedef {object} CoverageTreeTotals
+ * @property {number} requirements
+ * @property {number} covered
+ * @property {number} coveredUnresolved
+ * @property {number} uncovered
+ */
+
+/**
+ * @typedef {object} CoverageSummary
+ * @property {object} totals - the four totals and percentCovered as strings or UNAVAILABLE
+ * @property {object[]} families - per-family tile data
+ */
+
+/**
+ * Shape the family counts stat tiles from the walker's tree model.
+ * The spec names six families: requirements, stories, criteria,
+ * suites, cases, build specs. Each count is derived without a
+ * separate compute - the walker already carries each list.
+ *
+ * @param {object | null | undefined} tree
+ * @returns {Array<{key: string, label: string, count: number|null}>}
+ */
+export function familyCounts(tree) {
+  if (!tree || typeof tree !== 'object') {
+    return SIX_FAMILIES.map((f) => ({ key: f.key, label: f.label, count: null }));
+  }
+  const reqs = Array.isArray(tree.requirements) ? tree.requirements.length : null;
+  const stories = Array.isArray(tree.userStories) ? tree.userStories.length : null;
+  let criteria = 0;
+  if (Array.isArray(tree.userStories)) {
+    for (const us of tree.userStories) {
+      if (Array.isArray(us && us.acceptanceCriteria)) criteria += us.acceptanceCriteria.length;
+    }
+  } else {
+    criteria = null;
+  }
+  const suites = Array.isArray(tree.testSuites) ? tree.testSuites.length : null;
+  let cases = 0;
+  if (Array.isArray(tree.testSuites)) {
+    for (const ts of tree.testSuites) {
+      if (Array.isArray(ts && ts.testCases)) cases += ts.testCases.length;
+    }
+  } else {
+    cases = null;
+  }
+  const fbsItems = Array.isArray(tree.fbsItems) ? tree.fbsItems.length : null;
+  return [
+    { key: 'requirements', label: 'Requirements', count: reqs },
+    { key: 'stories', label: 'Stories', count: stories },
+    { key: 'criteria', label: 'Criteria', count: criteria },
+    { key: 'suites', label: 'Suites', count: suites },
+    { key: 'cases', label: 'Cases', count: cases },
+    { key: 'buildSpecs', label: 'Build specs', count: fbsItems },
+  ];
+}
+
+const SIX_FAMILIES = [
+  { key: 'requirements', label: 'Requirements' },
+  { key: 'stories', label: 'Stories' },
+  { key: 'criteria', label: 'Criteria' },
+  { key: 'suites', label: 'Suites' },
+  { key: 'cases', label: 'Cases' },
+  { key: 'buildSpecs', label: 'Build specs' },
+];
+
+/**
+ * Compute the four numeric slots + percent as either numbers or the
+ * UNAVAILABLE sentinel. AC-18004-6 and AC-18004-7 bind: no slot ever
+ * renders as a blank; a missing total renders the words
+ * "coverage unavailable".
+ */
+export function computeCoverageSummary(coverageTree) {
+  const t = coverageTree && typeof coverageTree === 'object' ? coverageTree.totals : null;
+  if (!t || typeof t !== 'object') {
+    return {
+      totals: {
+        requirements: UNAVAILABLE,
+        covered: UNAVAILABLE,
+        coveredUnresolved: UNAVAILABLE,
+        uncovered: UNAVAILABLE,
+      },
+      percentCovered: UNAVAILABLE,
+      available: false,
+    };
+  }
+  const reqs = numOrUnavail(t.requirements);
+  const covered = numOrUnavail(t.covered);
+  const coveredUnresolved = numOrUnavail(t.coveredUnresolved);
+  const uncovered = numOrUnavail(t.uncovered);
+  const reqsN = typeof reqs === 'number' ? reqs : null;
+  const coveredN = typeof covered === 'number' ? covered : null;
+  const percent = (reqsN === null || coveredN === null || reqsN === 0)
+    ? (reqsN === 0 ? '0%' : UNAVAILABLE)
+    : `${Math.round((coveredN / reqsN) * 100)}%`;
+  const available = reqs !== UNAVAILABLE && covered !== UNAVAILABLE
+    && coveredUnresolved !== UNAVAILABLE && uncovered !== UNAVAILABLE;
+  return {
+    totals: {
+      requirements: reqs,
+      covered,
+      coveredUnresolved,
+      uncovered,
+    },
+    percentCovered: percent,
+    available,
+  };
+}
+
+function numOrUnavail(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return UNAVAILABLE;
+  return v;
+}
+
+/**
+ * Render the coverage sub-view: a stat line, a stacked bar on
+ * --sv-success / --sv-warning / --sv-danger over --sv-surface, a
+ * family tiles row, and (when non-empty) an unresolved-pointers
+ * table. AC-18004-1/-2/-3/-6/-7.
+ *
+ * @param {object} args
+ * @param {object | null | undefined} args.coverage - readiness.coverage
+ * @param {object | null | undefined} args.tree - the walker tree model
+ * @returns {string}
+ */
+export function renderCoverageSummary(args) {
+  const coverage = args && args.coverage ? args.coverage : null;
+  const tree = args && args.tree ? args.tree : null;
+  const treeCov = coverage ? coverage.tree : null;
+  const summary = computeCoverageSummary(treeCov);
+  const tiles = familyCounts(tree);
+  const totalsText = renderTotals(summary);
+  const bar = renderBar(summary, treeCov);
+  const tilesHtml = renderTiles(tiles);
+  const unresolved = renderUnresolvedPointers(treeCov);
+  const dataAvailable = summary.available ? 'yes' : 'no';
+  return `<section class="rcf-cov-summary" data-rcf-coverage-available="${dataAvailable}" aria-labelledby="rcf-readiness-coverage-heading">
+  <header class="rcf-cov-summary__head"><h3 id="rcf-readiness-coverage-heading">Coverage</h3></header>
+  ${totalsText}
+  ${bar}
+  ${tilesHtml}
+  ${unresolved}
+</section>`;
+}
+
+function renderTotals(summary) {
+  // AC-18004-7: a value the coverage result does not carry renders as
+  // "coverage unavailable", not as a blank. We always render the four
+  // slots; each one shows either its number or the unavailable word.
+  const t = summary.totals;
+  const slot = (name, label) => {
+    const v = t[name];
+    const text = typeof v === 'number' ? String(v) : UNAVAILABLE;
+    const data = typeof v === 'number' ? 'no' : 'yes';
+    return `<span class="rcf-cov-summary__slot" data-rcf-slot="${name}" data-rcf-unavailable="${data}">${escapeHtml(label)}: <strong>${escapeHtml(text)}</strong></span>`;
+  };
+  const unavailAll = summary.available ? '' : ' rcf-cov-summary__totals--unavailable';
+  return `<p class="rcf-cov-summary__totals${unavailAll}">
+    ${slot('requirements', 'Requirements')}
+    ${slot('covered', 'Covered')}
+    ${slot('coveredUnresolved', 'Covered-unresolved')}
+    ${slot('uncovered', 'Uncovered')}
+    <span class="rcf-cov-summary__slot" data-rcf-slot="percentCovered" data-rcf-unavailable="${summary.percentCovered === UNAVAILABLE ? 'yes' : 'no'}">${escapeHtml(summary.percentCovered)}</span>
+  </p>`;
+}
+
+function renderBar(summary, treeCov) {
+  if (!summary.available) {
+    return `<div class="rcf-cov-summary__bar" data-rcf-bar-empty="yes" role="img" aria-label="${escapeHtml(UNAVAILABLE)}"></div>`;
+  }
+  const t = treeCov && treeCov.totals ? treeCov.totals : null;
+  const total = t ? (Number(t.requirements) || 0) : 0;
+  const covered = t ? (Number(t.covered) || 0) : 0;
+  const coveredUnresolved = t ? (Number(t.coveredUnresolved) || 0) : 0;
+  const uncovered = t ? (Number(t.uncovered) || 0) : 0;
+  // Three widths. Over --sv-surface. --sv-success / --sv-warning / --sv-danger.
+  const safeTotal = total > 0 ? total : (covered + coveredUnresolved + uncovered) || 1;
+  const w1 = pct(covered, safeTotal);
+  const w2 = pct(coveredUnresolved, safeTotal);
+  const w3 = pct(uncovered, safeTotal);
+  const label = `covered ${covered}, covered-unresolved ${coveredUnresolved}, uncovered ${uncovered} out of ${total}`;
+  return `<div class="rcf-cov-summary__bar" role="img" aria-label="${escapeHtml(label)}">
+    <span class="rcf-cov-summary__bar-seg rcf-cov-summary__bar-seg--covered" data-rcf-seg="covered" style="width: ${w1};" title="Covered: ${escapeHtml(String(covered))}"></span>
+    <span class="rcf-cov-summary__bar-seg rcf-cov-summary__bar-seg--unresolved" data-rcf-seg="unresolved" style="width: ${w2};" title="Covered-unresolved: ${escapeHtml(String(coveredUnresolved))}"></span>
+    <span class="rcf-cov-summary__bar-seg rcf-cov-summary__bar-seg--uncovered" data-rcf-seg="uncovered" style="width: ${w3};" title="Uncovered: ${escapeHtml(String(uncovered))}"></span>
+  </div>`;
+}
+
+function pct(part, total) {
+  if (!total) return '0%';
+  const n = Math.max(0, Math.min(100, (part / total) * 100));
+  return `${n.toFixed(2)}%`;
+}
+
+function renderTiles(tiles) {
+  const cells = tiles.map((f) => {
+    const value = typeof f.count === 'number' ? String(f.count) : UNAVAILABLE;
+    const unavail = typeof f.count !== 'number';
+    return `<li class="rcf-cov-summary__tile" data-rcf-family="${escapeHtml(f.key)}" data-rcf-unavailable="${unavail ? 'yes' : 'no'}">
+      <span class="rcf-cov-summary__tile-count">${escapeHtml(value)}</span>
+      <span class="rcf-cov-summary__tile-label">${escapeHtml(f.label)}</span>
+    </li>`;
+  }).join('');
+  return `<ul class="rcf-cov-summary__tiles" aria-label="Document counts per family">${cells}</ul>`;
+}
+
+// Each reason word the compute emits for an unresolved pointer has a
+// plain-English resolution: what has to change in the test tree to
+// clear the row. digest-review rule: rows carry id + plain-
+// English ask + chain location + link + what resolved looks like.
+const UNRESOLVED_RESOLVED = {
+  'test-missing': 'resolved by: add a test case in the pointer file whose name matches the testPointer slot',
+  'file-missing': 'resolved by: create the test file at the pointer path and add the matching test case',
+  'pointer-malformed': 'resolved by: fix the testPointer on the TC so it names a file and a case name',
+  'ambiguous': 'resolved by: narrow the testPointer so one and only one test case matches it',
+};
+
+function resolvedForUnresolved(reason) {
+  if (!reason) return 'resolved by: add a resolving test case for this pointer';
+  if (UNRESOLVED_RESOLVED[reason]) return UNRESOLVED_RESOLVED[reason];
+  return `resolved by: fix the pointer so the "${reason}" condition clears`;
+}
+
+function renderUnresolvedPointers(treeCov) {
+  const items = treeCov && Array.isArray(treeCov.unresolvedTestPointers) ? treeCov.unresolvedTestPointers : [];
+  if (items.length === 0) {
+    return '';
+  }
+  const rows = items.map((p) => {
+    const tsId = typeof p.tsId === 'string' ? p.tsId : '';
+    const tcId = typeof p.tcId === 'string' ? p.tcId : '';
+    const pointer = typeof p.testPointer === 'string' && p.testPointer.length > 0 ? p.testPointer : UNAVAILABLE;
+    const reason = typeof p.reason === 'string' && p.reason.length > 0 ? p.reason : UNAVAILABLE;
+    const resolved = resolvedForUnresolved(typeof p.reason === 'string' ? p.reason : '');
+    // `#entity=<TS-id>` without a tab key resolves through the viewer's
+    // bare-entity path (page-init.js resolveHash): it finds the TS node,
+    // activates its owning tab (Architecture) and scrolls to it. The
+    // former `#tab=testing&entity=...` href pointed at a tab that does
+    // not exist (TABS: readiness, overview, requirements, architecture,
+    // build, product-map) and fell through to Readiness, so clicking a
+    // row did not land on its suite.
+    const tsCell = tsId
+      ? `<a href="#entity=${escapeHtml(tsId)}" data-rcf-ts="${escapeHtml(tsId)}">${escapeHtml(tsId)}</a>`
+      : `<em>${escapeHtml(UNAVAILABLE)}</em>`;
+    const tcCell = tcId ? `<code>${escapeHtml(tcId)}</code>` : `<em>${escapeHtml(UNAVAILABLE)}</em>`;
+    // FBS-208 (AC-209-3): the suite id in the row carries a Trace
+    // action that lands on the Trace sub-tab for the id.
+    const traceCell = tsId
+      ? `<a class="rcf-trace-action" data-rcf-trace-for="${escapeHtml(tsId)}" href="#tab=readiness&amp;sub=trace&amp;entity=${encodeURIComponent(tsId)}">Trace</a>`
+      : `<span class="rcf-trace-action rcf-trace-action--na" data-rcf-trace="no" aria-label="No trace available for this item">-</span>`;
+    return `<tr>
+  <td>${tsCell}</td>
+  <td>${tcCell}</td>
+  <td><code>${escapeHtml(pointer)}</code></td>
+  <td>${escapeHtml(reason)}</td>
+  <td class="rcf-cov-summary__unresolved-resolved">${escapeHtml(resolved)}</td>
+  <td>${traceCell}</td>
+</tr>`;
+  }).join('');
+  return `<section class="rcf-cov-summary__unresolved" aria-labelledby="rcf-readiness-coverage-unresolved-heading">
+  <h4 id="rcf-readiness-coverage-unresolved-heading">Unresolved test pointers <span class="rcf-badge rcf-badge--count">${items.length}</span></h4>
+  <table class="rcf-cov-summary__unresolved-table">
+    <thead><tr><th>Suite</th><th>Case</th><th>Pointer</th><th>Reason</th><th>What resolves it</th><th><span class="rcf-sr-only">Trace this id</span></th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</section>`;
+}
+
+export const UNRESOLVED_POINTER_RESOLVED = UNRESOLVED_RESOLVED;
+
+export const COVERAGE_UNAVAILABLE_TEXT = UNAVAILABLE;

package/src/view/readiness/delta-counts.js

@@ -0,0 +1,156 @@
+// Readiness delta counts (FBS-206, TAC-4135-readiness-command-page,
+// ADR-4139). Pure HTML string renderer: emits six count numbers
+// (changed, added, removed, briefSince, impacted, impactedFbs) and
+// hides the per-document list and its diff widgets inside a
+// collapsed <details> so a thousand-document delta no longer buries
+// the failing ids.
+//
+// AC-18005-3 pins the expanded contract: when the reader opens the
+// <details>, the per-document list renders (changed with the diff
+// component, added, removed, impacted ACs and FBS as links); when
+// closed, only the six counts are visible.
+//
+// No command text, no write affordance.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+import { diff } from '../components/diff.js';
+
+/**
+ * @typedef {object} DeltaCounts
+ * @property {number} changed
+ * @property {number} added
+ * @property {number} removed
+ * @property {number} briefSince
+ * @property {number} impacted
+ * @property {number} impactedFbs
+ * @property {boolean} expanded     renderer-side flag mirroring the <details open> state
+ */
+
+/**
+ * Fold the six counts from a ReadinessDelta.
+ *
+ * @param {import('../../query/readiness.js').ReadinessDelta | null | undefined} d
+ * @returns {Omit<DeltaCounts, 'expanded'>}
+ */
+export function foldCounts(d) {
+  if (!d || typeof d !== 'object') {
+    return { changed: 0, added: 0, removed: 0, briefSince: 0, impacted: 0, impactedFbs: 0 };
+  }
+  return {
+    changed: Array.isArray(d.changed) ? d.changed.length : 0,
+    added: Array.isArray(d.added) ? d.added.length : 0,
+    removed: Array.isArray(d.removed) ? d.removed.length : 0,
+    briefSince: Array.isArray(d.briefSince) ? d.briefSince.length : 0,
+    impacted: Array.isArray(d.impacted) ? d.impacted.length : 0,
+    impactedFbs: Array.isArray(d.impactedFbs) ? d.impactedFbs.length : 0,
+  };
+}
+
+/**
+ * Build the delta-counts block (overview sub-view). The six count
+ * tiles are always visible; the per-document list sits inside a
+ * collapsed <details>.
+ *
+ * @param {object} args
+ * @param {import('../../query/readiness.js').ReadinessDelta | null | undefined} args.delta
+ * @param {object | null | undefined} [args.freezeRecord]
+ * @param {boolean} [args.expanded]   default false
+ * @returns {string}
+ */
+export function renderDeltaCounts({ delta, freezeRecord, expanded }) {
+  const counts = foldCounts(delta);
+  const totalTouched = counts.changed + counts.added + counts.removed;
+  const empty = totalTouched === 0 && counts.briefSince === 0 && counts.impacted === 0 && counts.impactedFbs === 0;
+  if (empty) {
+    return `<section class="rcf-readiness-delta-counts" data-rcf-expanded="${expanded ? 'yes' : 'no'}">`
+      + `<h3>Delta since freeze</h3>`
+      + `<p><em>No delta since the last freeze.</em></p>`
+      + `</section>`;
+  }
+  const tiles = [
+    tile('changed', counts.changed, 'Documents changed'),
+    tile('added', counts.added, 'Documents added'),
+    tile('removed', counts.removed, 'Documents removed'),
+    tile('briefSince', counts.briefSince, 'Brief statements since freeze'),
+    tile('impacted', counts.impacted, 'ACs to re-verify'),
+    tile('impactedFbs', counts.impactedFbs, 'FBS to re-execute'),
+  ].join('');
+  const open = expanded ? ' open' : '';
+  const docsList = renderDocsList(delta, freezeRecord);
+  return `<section class="rcf-readiness-delta-counts" data-rcf-expanded="${expanded ? 'yes' : 'no'}">`
+    + `<h3>Delta since freeze</h3>`
+    + `<div class="rcf-readiness-delta-counts__tiles" role="group" aria-label="Delta counts">${tiles}</div>`
+    + `<details class="rcf-readiness-delta-counts__details"${open}>`
+    + `<summary>Show per-document changes</summary>`
+    + docsList
+    + `</details>`
+    + `</section>`;
+}
+
+function tile(key, n, label) {
+  const empty = n === 0 ? ' rcf-readiness-delta-counts__tile--empty' : '';
+  return `<div class="rcf-readiness-delta-counts__tile${empty}" data-rcf-count="${escapeHtml(key)}" data-rcf-count-value="${n}">`
+    + `<span class="rcf-readiness-delta-counts__n">${n}</span>`
+    + `<span class="rcf-readiness-delta-counts__label">${escapeHtml(label)}</span>`
+    + `</div>`;
+}
+
+function renderDocsList(delta, freezeRecord) {
+  const d = delta && typeof delta === 'object' ? delta : null;
+  if (!d) return '';
+  const frozenHashes = (freezeRecord && typeof freezeRecord === 'object' && freezeRecord.docHashes && typeof freezeRecord.docHashes === 'object')
+    ? freezeRecord.docHashes
+    : {};
+  const currentHashes = (d && typeof d.currentDocHashes === 'object' && d.currentDocHashes !== null)
+    ? d.currentDocHashes
+    : {};
+  const added = Array.isArray(d.added) ? d.added : [];
+  const changed = Array.isArray(d.changed) ? d.changed : [];
+  const removed = Array.isArray(d.removed) ? d.removed : [];
+  const brief = Array.isArray(d.briefSince) ? d.briefSince : [];
+  const impactedAc = Array.isArray(d.impacted) ? d.impacted : [];
+  const impactedFbs = Array.isArray(d.impactedFbs) ? d.impactedFbs : [];
+  const docsBlock = (added.length + changed.length + removed.length) > 0
+    ? `<section class="rcf-readiness-delta-counts__docs">`
+      + `<h4>Documents (${added.length + changed.length + removed.length})</h4>`
+      + `<ul>`
+      + added.map((id) => `<li><a href="#${escapeHtml(String(id))}">${escapeHtml(String(id))}</a> <em>added</em>${renderDocDiff(id, frozenHashes, currentHashes, 'added')}</li>`).join('')
+      + changed.map((id) => `<li><a href="#${escapeHtml(String(id))}">${escapeHtml(String(id))}</a> <em>changed</em>${renderDocDiff(id, frozenHashes, currentHashes, 'changed')}</li>`).join('')
+      + removed.map((id) => `<li>${escapeHtml(String(id))} <em>removed</em>${renderDocDiff(id, frozenHashes, currentHashes, 'removed')}</li>`).join('')
+      + `</ul>`
+      + `</section>`
+    : '';
+  const briefBlock = brief.length > 0
+    ? `<section class="rcf-readiness-delta-counts__brief">`
+      + `<h4>Brief statements since freeze (${brief.length})</h4>`
+      + `<ul>${brief.map((n) => `<li>#${escapeHtml(String(n))}</li>`).join('')}</ul>`
+      + `</section>`
+    : '';
+  const impactedBlock = (impactedAc.length + impactedFbs.length) > 0
+    ? `<section class="rcf-readiness-delta-counts__impacted" data-rcf-impacted-ac="${impactedAc.length}" data-rcf-impacted-fbs="${impactedFbs.length}">`
+      + `<h4>Impacted by delta (${impactedAc.length} AC, ${impactedFbs.length} FBS)</h4>`
+      + (impactedAc.length > 0
+        ? `<p class="muted small">To re-verify (${impactedAc.length}):</p>`
+          + `<ul class="rcf-readiness-delta-counts__impacted-ac">${impactedAc.map((n) => `<li><a href="#${escapeHtml(String(n))}">${escapeHtml(String(n))}</a></li>`).join('')}</ul>`
+        : '')
+      + (impactedFbs.length > 0
+        ? `<p class="muted small">To re-execute (${impactedFbs.length}):</p>`
+          + `<ul class="rcf-readiness-delta-counts__impacted-fbs">${impactedFbs.map((id) => `<li><a href="#${escapeHtml(String(id))}">${escapeHtml(String(id))}</a></li>`).join('')}</ul>`
+        : '')
+      + `</section>`
+    : '';
+  return docsBlock + briefBlock + impactedBlock;
+}
+
+function renderDocDiff(id, frozenHashes, currentHashes, kind) {
+  const frozenHash = typeof frozenHashes?.[id] === 'string' ? frozenHashes[id] : null;
+  const currentHash = typeof currentHashes?.[id] === 'string' ? currentHashes[id] : null;
+  const beforeNote = 'frozen body not captured in freeze record';
+  const before = kind === 'added'
+    ? { note: 'not in the frozen tree' }
+    : { hash: frozenHash ?? '', note: beforeNote };
+  const after = kind === 'removed'
+    ? { note: 'removed from the live tree' }
+    : { hash: currentHash ?? '', note: 'current body available on the document tab' };
+  return ` ${diff(before, after)}`;
+}

package/src/view/readiness/grid.js

@@ -0,0 +1,175 @@
+// Readiness stage grid (FBS-206, TAC-4135-readiness-command-page,
+// ADR-4139). Pure HTML string renderer: emits a two-column table
+// (tree, delta) with one row per stage. Each VerdictGridCell carries
+// pass/total/state and a failing-count link into the blocking table
+// filtered to that stage.
+//
+// Viewer read-only (Dave constraint F7, ADR-4139): no command text,
+// no write affordance. The failing count is a hash link
+// (#tab=readiness&sub=blocking&stage=<D>) picked up by the blocking
+// FilterBar wire (page-init.js).
+//
+// Acknowledgement source (AC-18005-6): stages[].state is the single
+// source for the cell state ("acknowledged" when the pass-fold set
+// it via a D8 freeze match). The reason reads from stages[].reason
+// (notApplicable) or, for acknowledgements, from freezeRecord.gates
+// via one helper (reasonForCell) so the grid never reads
+// freezeRecord.gates directly from its row renderer.
+//
+// Node 24 ESM; no dependencies.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+import { stageTitle } from './stage-legend.js';
+
+/**
+ * @typedef {object} VerdictGridCell
+ * @property {number} pass
+ * @property {number} total
+ * @property {'passed'|'failing'|'acknowledged'|'notApplicable'} state
+ * @property {number} failing       count of failing ids in that stage x scope
+ * @property {string} [reason]      hover title (notApplicable or acknowledged)
+ * @property {string} [href]        link target when failing>0
+ */
+
+/**
+ * Build the cell shape for one (stage, scope) pair.
+ *
+ * @param {import('../../query/readiness.js').StageResult} s
+ * @param {'tree'|'delta'} scope
+ * @param {object | null | undefined} freezeRecord
+ * @returns {VerdictGridCell}
+ */
+export function buildCell(s, scope, freezeRecord) {
+  const checks = Array.isArray(s.checks) ? s.checks.filter((c) => c && c.over === scope) : [];
+  let pass = 0;
+  let total = 0;
+  let failing = 0;
+  for (const c of checks) {
+    pass += Number.isFinite(c.pass) ? c.pass : 0;
+    total += Number.isFinite(c.total) ? c.total : 0;
+    if (!c.ok && Array.isArray(c.failing)) failing += c.failing.length;
+  }
+  const state = cellStateFromStage(s, checks);
+  const reason = reasonForCell(s, state, freezeRecord);
+  const cell = { pass, total, state, failing };
+  if (reason) cell.reason = reason;
+  if (failing > 0) {
+    cell.href = `#tab=readiness&sub=blocking&stage=${encodeURIComponent(s.stage)}`;
+  }
+  return cell;
+}
+
+/**
+ * Fold the per-scope cell state from stages[].state and the scope's
+ * own checks. The stage-level state is authoritative for passed /
+ * acknowledged / notApplicable (D8 and the acknowledge-sweep set it);
+ * if the scope has no checks at all the cell is notApplicable; a
+ * failing check in the scope flips the cell to failing even when the
+ * other scope passed (so delta failures surface on their own column).
+ *
+ * @param {import('../../query/readiness.js').StageResult} s
+ * @param {import('../../query/readiness.js').CheckResult[]} scopeChecks
+ */
+function cellStateFromStage(s, scopeChecks) {
+  if (scopeChecks.length === 0) return 'notApplicable';
+  // Stage-level acknowledgement wins over scope-specific failures:
+  // foldState only sets state='acknowledged' when there is a failing
+  // check and the gate is acked at the current tree hash, so the
+  // acknowledged envelope is the authoritative verdict for both the
+  // tree and delta columns.
+  if (s.state === 'acknowledged') return 'acknowledged';
+  if (scopeChecks.some((c) => !c.ok)) return 'failing';
+  if (s.state === 'notApplicable') return 'notApplicable';
+  return 'passed';
+}
+
+/**
+ * Reason-helper: the hover title for a cell. notApplicable rows read
+ * from stages[].reason; acknowledged rows read the ack-reason from
+ * freezeRecord.gates[gate] (via this one function, not from the row
+ * renderer); failing / passed rows return undefined (the stage-title
+ * tooltip still fires at the <th> level).
+ *
+ * @param {import('../../query/readiness.js').StageResult} s
+ * @param {VerdictGridCell['state']} state
+ * @param {object | null | undefined} freezeRecord
+ * @returns {string | undefined}
+ */
+export function reasonForCell(s, state, freezeRecord) {
+  if (state === 'notApplicable') {
+    return typeof s.reason === 'string' && s.reason.length > 0 ? s.reason : undefined;
+  }
+  if (state === 'acknowledged') {
+    const gates = freezeRecord && typeof freezeRecord === 'object' ? freezeRecord.gates : null;
+    const ack = gates && typeof gates === 'object' ? gates[s.gate] : null;
+    // The freeze record writes the reason at gates[g].at.reason (see
+    // src/cli/freeze.js buildGatesEntry / mergeAckedGates); the legacy
+    // flat gates[g].reason is accepted as a fallback for older files.
+    const at = ack && typeof ack === 'object' ? ack.at : null;
+    if (at && typeof at === 'object' && typeof at.reason === 'string' && at.reason.length > 0) {
+      return at.reason;
+    }
+    if (ack && typeof ack === 'object' && typeof ack.reason === 'string' && ack.reason.length > 0) {
+      return ack.reason;
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Build the full stage-grid HTML (overview sub-view block).
+ *
+ * @param {object} args
+ * @param {import('../../query/readiness.js').StageResult[]} args.stages
+ * @param {object | null | undefined} [args.freezeRecord]
+ * @returns {string}
+ */
+export function renderVerdictGrid({ stages, freezeRecord }) {
+  const rows = Array.isArray(stages) ? stages : [];
+  if (rows.length === 0) {
+    return `<section class="rcf-readiness-grid" data-rcf-grid="verdict">`
+      + `<p><em>No stages to render.</em></p>`
+      + `</section>`;
+  }
+  const header = `<thead><tr>`
+    + `<th scope="col">Stage</th>`
+    + `<th scope="col" data-scope="tree">Tree</th>`
+    + `<th scope="col" data-scope="delta">Delta</th>`
+    + `</tr></thead>`;
+  const body = rows.map((s) => {
+    const title = stageTitle(s.stage) || s.stage;
+    const tree = buildCell(s, 'tree', freezeRecord);
+    const delta = buildCell(s, 'delta', freezeRecord);
+    const stageCell = `<th scope="row" data-rcf-stage-ref="${escapeHtml(s.stage)}" title="${escapeHtml(title)}">`
+      + `<span class="rcf-readiness-grid__stage-id">${escapeHtml(s.stage)}</span> `
+      + `<code class="muted">${escapeHtml(s.gate)}</code>`
+      + `</th>`;
+    return `<tr data-rcf-stage="${escapeHtml(s.stage)}">`
+      + stageCell
+      + renderCellTd(s, 'tree', tree)
+      + renderCellTd(s, 'delta', delta)
+      + `</tr>`;
+  }).join('\n');
+  return `<section class="rcf-readiness-grid" data-rcf-grid="verdict">`
+    + `<table class="rcf-readiness-grid__table rcf-cmd-table" data-rcf-table="verdict-grid">`
+    + header
+    + `<tbody>${body}</tbody>`
+    + `</table>`
+    + `</section>`;
+}
+
+function renderCellTd(s, scope, cell) {
+  const stateClass = `rcf-readiness-grid__cell--${escapeHtml(cell.state)}`;
+  const title = cell.reason ? ` title="${escapeHtml(cell.reason)}"` : '';
+  const countsText = `${cell.pass}/${cell.total}`;
+  const failingText = cell.failing > 0
+    ? (cell.href
+      ? ` <a class="rcf-readiness-grid__failing" href="${escapeHtml(cell.href)}" data-rcf-link="blocking-filtered" data-rcf-filter-stage="${escapeHtml(s.stage)}">${cell.failing} failing</a>`
+      : ` <span class="rcf-readiness-grid__failing">${cell.failing} failing</span>`)
+    : '';
+  return `<td class="rcf-readiness-grid__cell ${stateClass}" data-rcf-cell-state="${escapeHtml(cell.state)}" data-rcf-cell-scope="${escapeHtml(scope)}" data-rcf-cell-pass="${cell.pass}" data-rcf-cell-total="${cell.total}" data-rcf-cell-failing="${cell.failing}"${title}>`
+    + `<span class="rcf-readiness-grid__counts">${countsText}</span>`
+    + failingText
+    + `</td>`;
+}