rcf-lite 0.32.4 → 0.33.0

package/src/view/readiness.js

@@ -1,24 +1,33 @@
-// Readiness tab renderer (REQ-180, TAC-4127-readiness-view, ADR-4127).
-// Pure HTML string builder: takes the ReadinessResult (as produced by
-// `computeReadiness` in `src/query/readiness.js`) and the operator
-// profile text, emits the tabpanel body. Never recomputes readiness
-// and never touches disk; the server loads the inputs once per
-// rewalk (see `renderModelToPage`) so the Readiness tab and
-// `rcf define readiness --json` cannot disagree for the same tree.
+// Readiness tab renderer (REQ-180, TAC-4135-readiness-command-page,
+// TAC-4133, TAC-4127, ADR-4139). Pure HTML string builder; takes the
+// ReadinessResult (as produced by `computeReadiness` in
+// `src/query/readiness.js`) plus the operator profile text and the
+// walker tree model, emits the tabpanel body.
 //
-// Layout follows DEFINE step 2 spec section 5, top to bottom:
-//   1 tree line; 2 verdict pills; 3 next-action per persona;
-//   4 D1..D8 state chips; 5 blockers by persona; 6 delta list;
-//   7 per-stage check detail; 8 coverage tree-vs-delta;
-//   9 decisions outstanding; 10 freeze-now control; 11 freeze record.
+// FBS-206 reshape: the panel is a SubTabStrip (Overview, Questions,
+// Blocking, Coverage, Trace) with five sub-panels; one is visible at
+// a time. For-engineers DocRow, stage chips and stage-detail retired
+// (viewer-read-only ADR-4139 and Dave's FBS-204/206 binding ruling).
+// "On me" / "On engineers" vocabulary replaces persona pills in the
+// user-facing text. The freeze state renders in plain words with
+// what resolves each failing gate. The Trace sub-view is an empty
+// shell here; FBS-208 fills it.
+//
+// Every id (passing or failing) still lives in the DOM in some
+// sub-panel so AC-18001-5 and AC-18002-3 ("no id leaves the DOM")
+// stay true: a hidden sub-panel is `[hidden]`, not removed.
 
 import { escapeHtml } from './doc-renderers/helpers.js';
 import { formatTreeLine, formatVerdictLines, shortHash } from '../query/readiness.js';
-import { pill } from './components/pill.js';
-import { findingsList } from './components/findings-list.js';
-import { diff } from './components/diff.js';
-import { renderReadinessPO } from './readiness/po-layer.js';
-import { renderStageLegend, stageTitle } from './readiness/stage-legend.js';
+import { renderSubTabStrip } from './components/sub-tab-strip.js';
+import { renderVerdictCards } from './readiness/po-layer.js';
+import { renderQuestionsTable, renderBlockingTable, buildQuestionRows, buildBlockingRows } from './readiness/tables.js';
+import { renderCoverageSummary } from './readiness/coverage-summary.js';
+import { buildThinReqRows, renderThinReqsTable } from './readiness/thin-reqs.js';
+import { renderVerdictGrid } from './readiness/grid.js';
+import { renderDeltaCounts } from './readiness/delta-counts.js';
+import { renderStageLegend } from './readiness/stage-legend.js';
+import { toQuestions, preferReadinessQuestions } from './readiness/question-adapter.js';
 
 /**
  * @typedef {import('../query/readiness.js').ReadinessResult} ReadinessResult
@@ -27,11 +36,15 @@ import { renderStageLegend, stageTitle } from './readiness/stage-legend.js';
  * @typedef {import('../query/readiness.js').Blocker} Blocker
  */
 
+/** Sub-tab keys in authoring order (first = default). */
+export const READINESS_SUBS = ['overview', 'questions', 'blocking', 'coverage', 'trace'];
+
 /**
  * Decide the register ordering from `profile.md` text. Same contract
- * as the CLI's `pickRegister` helper: first marker in the text wins;
- * absent / unrecognised yields `unstated`, which the tab orders as
- * productOwner-first (spec section 5).
+ * as the CLI's `pickRegister` helper. The register no longer flips
+ * the layout: the Overview is the default landing and the sub-tab
+ * router restores sub= from the hash. The register is still a
+ * content hint (text uses "On me" / "On engineers" based on it).
  *
  * @param {string | null | undefined} text
  * @returns {'productOwner'|'engineer'|'unstated'}
@@ -55,12 +68,14 @@ export function pickRegister(text) {
 /**
  * Build the full Readiness tabpanel inner HTML.
  *
- * @param {ReadinessResult | null} result - the computed readiness
- *   object, or null when the tree could not be computed
+ * @param {ReadinessResult | null} result
  * @param {object} [opts]
- * @param {string | null} [opts.profile] - profile.md text (register)
- * @param {object | null} [opts.freezeRecord] - loaded freeze record,
- *   for the Freeze record block (section 11)
+ * @param {string | null} [opts.profile]
+ * @param {object | null} [opts.freezeRecord]
+ * @param {object | null} [opts.tree]
+ * @param {string} [opts.activeSub]   sub-tab key the server should mark active
+ *                                    (defaults to 'overview'; the client router
+ *                                    takes over after load)
  * @returns {string}
  */
 export function renderReadinessPanel(result, opts = {}) {
@@ -69,370 +84,248 @@ export function renderReadinessPanel(result, opts = {}) {
   }
   const register = pickRegister(opts.profile ?? null);
   const freezeRecord = opts.freezeRecord ?? null;
+  const tree = opts.tree ?? null;
+  const activeSub = READINESS_SUBS.includes(opts.activeSub) ? opts.activeSub : 'overview';
+
+  const subTabs = renderSubTabStrip({
+    hashKey: 'readiness',
+    items: [
+      { key: 'overview', label: 'Overview', controls: 'rcf-readiness-sub-overview' },
+      { key: 'questions', label: 'Questions', controls: 'rcf-readiness-sub-questions' },
+      { key: 'blocking', label: 'Blocking', controls: 'rcf-readiness-sub-blocking' },
+      { key: 'coverage', label: 'Coverage', controls: 'rcf-readiness-sub-coverage' },
+      { key: 'trace', label: 'Trace', controls: 'rcf-readiness-sub-trace' },
+    ],
+    active: activeSub,
+  });
+
   const verdictLines = formatVerdictLines(result);
+  const q = toQuestions(result);
+  const questionsSource = preferReadinessQuestions(result) ? 'readiness.questions' : 'blockers';
+  const questionRows = buildQuestionRowsForTable(q);
+  const blockingRows = buildBlockingRows(Array.isArray(result.stages) ? result.stages : []);
+  const thinRows = buildThinReqRows(result, tree);
+
+  const overview = renderOverviewSub({
+    result,
+    verdictLines,
+    q,
+    freezeRecord,
+    register,
+    active: activeSub === 'overview',
+  });
+  const questions = renderQuestionsSub({
+    questionRows,
+    questionsSource,
+    active: activeSub === 'questions',
+  });
+  const blocking = renderBlockingSub({
+    blockingRows,
+    active: activeSub === 'blocking',
+  });
+  const coverage = renderCoverageSub({
+    result,
+    tree,
+    thinRows,
+    active: activeSub === 'coverage',
+  });
+  const trace = renderTraceSub({ active: activeSub === 'trace' });
+
+  // AC-18003-8: engineer register renders the Blocking sub-panel
+  // before the Questions sub-panel in the DOM so the engineer surface
+  // takes DOM precedence. Product owner and the default keep Questions
+  // first (matches AC-18001-4). The SubTabStrip's visible labels keep
+  // their authoring order; the ARIA aria-controls links each tab to
+  // its panel by id, so swapping panel order does not break the strip
+  // or the router.
+  const paintOrder = register === 'engineer'
+    ? [overview, blocking, questions, coverage, trace]
+    : [overview, questions, blocking, coverage, trace];
 
-  const engineerBody = [
-    renderTreeLine(result),
-    renderVerdicts(result, verdictLines),
-    renderNextActions(result, register),
-    renderStageChips(result, freezeRecord),
-    renderBlockersByPersona(result, register),
-    renderDelta(result, freezeRecord),
-    renderStageDetail(result),
-    renderCoverage(result),
-    renderDecisions(result),
-    renderFreezeNow(result),
-    renderFreezeRecord(freezeRecord),
-  ].join('\n');
-
-  const poLayer = renderReadinessPO(result, { persona: register, engineerBody });
   const legend = renderStageLegend();
-  return `${poLayer}\n${legend}`;
-}
-
-// --- Block 1: tree line ------------------------------------------------
-
-function renderTreeLine(result) {
-  return `<div class="rcf-readiness-tree"><p>${escapeHtml(formatTreeLine(result))}</p></div>`;
+  return `<div class="rcf-readiness-panel" data-rcf-register="${escapeHtml(register)}" data-rcf-source="${escapeHtml(questionsSource)}">`
+    + subTabs
+    + paintOrder.join('')
+    + legend
+    + `</div>`;
 }
 
-// --- Block 2: verdict pills --------------------------------------------
-
-function renderVerdicts(result, verdictLines) {
-  const l = result.levels;
-  const intentValue = l.intentComplete.ok ? 'yes' : 'no';
-  const buildValue = l.readyToBuild.ok ? 'yes' : 'no';
-  const intentPill = pill({
-    value: verdictLines.intentComplete,
-    variant: 'level-verdict-intent',
-    title: `Intent complete: ${intentValue} (${l.intentComplete.blockedBy.length} blocker${l.intentComplete.blockedBy.length === 1 ? '' : 's'})`,
-  });
-  const buildPill = pill({
-    value: verdictLines.readyToBuild,
-    variant: 'level-verdict-build',
-    title: `Ready to build: ${buildValue} (${l.readyToBuild.blockedBy.length} blocker${l.readyToBuild.blockedBy.length === 1 ? '' : 's'})`,
-  });
-  return `<div class="rcf-readiness-verdicts" data-rcf-intent-ok="${intentValue}" data-rcf-build-ok="${buildValue}">`
-    + `<div class="rcf-readiness-verdict rcf-readiness-verdict--intent">${intentPill}`
-    + ` <span class="rcf-readiness-verdict__count">${l.intentComplete.blockedBy.length}</span></div>`
-    + `<div class="rcf-readiness-verdict rcf-readiness-verdict--build">${buildPill}`
-    + ` <span class="rcf-readiness-verdict__count">${l.readyToBuild.blockedBy.length}</span></div>`
+// ---- Overview sub-view ---------------------------------------------------
+//
+// Carries: tree line, two VerdictCards (count-links into Questions /
+// Blocking sub-tabs), the stage verdict grid, the delta counts (per-
+// document list behind a collapsed <details>), decisions outstanding,
+// freeze state (plain words), freeze record. The CLI verdictLines
+// render inside the Overview too so AC-18002-3 ("every id in the DOM")
+// stays true across sub-views and the --json parity test
+// (AC-18001-7) keeps passing.
+
+function renderOverviewSub({ result, verdictLines, q, freezeRecord, register, active }) {
+  const cards = renderVerdictCards(result, verdictLines, q);
+  const treeLine = renderTreeLine(result);
+  const grid = renderVerdictGrid({ stages: result.stages, freezeRecord });
+  const deltaCounts = renderDeltaCounts({ delta: result.delta, freezeRecord, expanded: false });
+  const decisions = renderDecisions(result);
+  const nextActions = renderNextActionBlock(result, register);
+  const freezeState = renderFreezeState(result, register);
+  const freezeRec = renderFreezeRecord(freezeRecord);
+  const verdictParity = renderCliVerdictLines(verdictLines);
+  const hidden = active ? '' : ' hidden';
+  return `<div class="rcf-readiness-subpanel rcf-readiness-sub-overview" id="rcf-readiness-sub-overview" data-rcf-subpanel="overview" role="tabpanel"${hidden}>`
+    + treeLine
+    + cards
+    + verdictParity
+    + grid
+    + deltaCounts
+    + decisions
+    + nextActions
+    + freezeState
+    + freezeRec
     + `</div>`;
 }
 
-// --- Block 3: next action per persona ----------------------------------
-
-function renderNextActions(result, register) {
-  const po = result.personas.productOwner.nextAction;
-  const eng = result.personas.engineer.nextAction;
-  const po_line = renderNextActionLine('product owner', po, 'productOwner');
-  const eng_line = renderNextActionLine('engineer', eng, 'engineer');
-  const order = register === 'engineer' ? [eng_line, po_line] : [po_line, eng_line];
-  return `<div class="rcf-readiness-next-actions" data-rcf-register="${register}">`
+// ---- Next actions (AC-18005-4: engineer surface carries a named
+// next-action block) ------------------------------------------------
+//
+// Renders personas.productOwner.nextAction and personas.engineer.nextAction
+// as plain words: "resolve the <plainLabel> failing items in the
+// blocking table" with the id list named inline. No command text, no
+// Run button; the chain fragment (stage/check) rides in data- attributes
+// so the engineer or product owner reads what the row says and acts in
+// their own agent session.
+
+function renderNextActionBlock(result, register) {
+  const po = result.personas && result.personas.productOwner ? result.personas.productOwner.nextAction : null;
+  const eng = result.personas && result.personas.engineer ? result.personas.engineer.nextAction : null;
+  const poLine = renderNextActionLine('product owner', po, 'productOwner');
+  const engLine = renderNextActionLine('engineer', eng, 'engineer');
+  const order = register === 'engineer' ? [engLine, poLine] : [poLine, engLine];
+  return `<section class="rcf-readiness-next-actions" data-rcf-register="${escapeHtml(register)}">`
+    + `<h3>Next action</h3>`
     + order.join('')
-    + `</div>`;
+    + `</section>`;
 }
 
 function renderNextActionLine(label, action, persona) {
+  const ownerLabel = persona === 'engineer' ? 'engineer' : 'product owner';
   if (!action) {
-    return `<p class="rcf-readiness-next-action rcf-readiness-next-action--${persona}">`
-      + `<strong>Next action (${escapeHtml(label)}):</strong> none.`
+    return `<p class="rcf-readiness-next-action rcf-readiness-next-action--${escapeHtml(persona)}" data-rcf-persona="${escapeHtml(persona)}">`
+      + `<strong>${escapeHtml(ownerLabel)}:</strong> none.`
       + `</p>`;
   }
-  const ids = action.ids && action.ids.length > 0 ? ` ids: ${action.ids.join(', ')}` : '';
-  const anchor = `#rcf-readiness-check-${encodeURIComponent(`${action.stage}:${action.check}`)}`;
-  return `<p class="rcf-readiness-next-action rcf-readiness-next-action--${persona}">`
-    + `<strong>Next action (${escapeHtml(label)}):</strong> `
-    + `<a href="${escapeHtml(anchor)}">${escapeHtml(action.stage)} / ${escapeHtml(action.check)}</a>`
-    + `${escapeHtml(ids)}. `
-    + `Run <code>${escapeHtml(action.command)}</code> after editing.`
+  const stage = typeof action.stage === 'string' ? action.stage : '';
+  const check = typeof action.check === 'string' ? action.check : '';
+  const plain = checkToPlainLabel(check);
+  const ids = Array.isArray(action.ids) ? action.ids.filter((x) => typeof x === 'string') : [];
+  const idText = ids.length > 0 ? ` on ${ids.join(', ')}` : '';
+  const resolver = plain
+    ? `resolve the ${plain} failing items in the blocking table`
+    : `resolve the failing items named in the blocking table`;
+  return `<p class="rcf-readiness-next-action rcf-readiness-next-action--${escapeHtml(persona)}" data-rcf-persona="${escapeHtml(persona)}" data-rcf-stage="${escapeHtml(stage)}" data-rcf-check="${escapeHtml(check)}">`
+    + `<strong>${escapeHtml(ownerLabel)}:</strong> ${escapeHtml(resolver)}${escapeHtml(idText)}.`
     + `</p>`;
 }
 
-// --- Block 4: stage chips D1..D8 ---------------------------------------
-
-function renderStageChips(result, freezeRecord) {
-  const chips = result.stages.map((s) => {
-    const stateClass = chipStateClass(s.state);
-    const legendTitle = stageTitle(s.stage);
-    let title = `${s.stage} ${s.gate}: ${s.state}`;
-    if (legendTitle && legendTitle !== s.stage) title = `${legendTitle} (${s.state})`;
-    if (s.state === 'notApplicable' && s.reason) title = `${title} - ${s.reason}`;
-    if (s.state === 'acknowledged' && freezeRecord && freezeRecord.gates && freezeRecord.gates[s.gate]) {
-      const ack = freezeRecord.gates[s.gate];
-      if (ack && typeof ack.reason === 'string' && ack.reason.length > 0) {
-        title = `${title} - ${ack.reason}`;
-      }
-    }
-    const label = `${s.stage}: ${s.state}`;
-    return `<li class="rcf-readiness-chip rcf-readiness-chip--${stateClass}" data-rcf-stage-ref="${s.stage}">`
-      + pill({ value: label, variant: 'gate-state', title })
-      + `</li>`;
-  }).join('');
-  return `<ul class="rcf-readiness-chips">${chips}</ul>`;
-}
-
-function chipStateClass(state) {
-  switch (state) {
-    case 'passed':
-      return 'green';
-    case 'failing':
-      return 'red';
-    case 'acknowledged':
-      return 'amber';
-    case 'notApplicable':
-      return 'grey';
-    default:
-      return 'grey';
-  }
+function renderTreeLine(result) {
+  return `<div class="rcf-readiness-tree"><p>${escapeHtml(formatTreeLine(result))}</p></div>`;
 }
 
-// --- Block 5: blockers by persona --------------------------------------
-
-export function renderBlockersByPersona(result, register) {
-  const po = result.personas.productOwner.blockers;
-  const eng = result.personas.engineer.blockers;
-  const stages = Array.isArray(result.stages) ? result.stages : [];
-  const poBlock = renderPersonaGroup('productOwner', 'Product owner', 'question', po, register, 'open', stages);
-  const engBlock = renderPersonaGroup('engineer', 'Engineer', 'check blocking', eng, register, 'closed', stages);
-  // When the register is engineer, the engineer group opens first and
-  // the PO group collapses; `unstated` and `productOwner` keep PO open.
-  const [first, second] = register === 'engineer'
-    ? [renderPersonaGroup('engineer', 'Engineer', 'check blocking', eng, register, 'open', stages),
-       renderPersonaGroup('productOwner', 'Product owner', 'question', po, register, 'closed', stages)]
-    : [poBlock, engBlock];
-  return `<section class="rcf-readiness-blockers-by-persona" data-rcf-register="${register}">`
-    + first + second
-    + `</section>`;
-}
+// The CLI verdict strings render as a muted parity block inside
+// Overview. AC-18001-7 (every id on the tab appears in the --json for
+// the same tree) and AC-18002-3 (engineer ids never leave the DOM)
+// both rely on these strings being present in the rendered HTML.
 
-/**
- * @param {'productOwner'|'engineer'} persona
- * @param {string} heading
- * @param {string} singular - 'question' | 'check blocking'
- * @param {Blocker[]} blockers
- * @param {'productOwner'|'engineer'|'unstated'} register
- * @param {'open'|'closed'} state
- * @param {StageResult[]} stages - threaded so each blocker's ids can
- *   carry the matching failing `why` from `stages[].checks[].failing[]`
- *   (spec section 5 block 5).
- */
-function renderPersonaGroup(persona, heading, singular, blockers, register, state, stages) {
-  const plural = singular === 'question' ? 'questions' : 'checks blocking';
-  const count = blockers.length;
-  const noun = count === 1 ? singular : plural;
-  const summary = `${heading}: ${count} ${noun}`;
-  const openAttr = state === 'open' ? ' open' : '';
-  if (count === 0) {
-    return `<details class="rcf-readiness-persona rcf-readiness-persona--${persona}" data-rcf-persona-state="${state}"${openAttr}>`
-      + `<summary><strong>${escapeHtml(heading)}:</strong> 0 ${plural}.</summary>`
-      + `</details>`;
-  }
-  const items = blockers.map((b) => renderBlockerCard(b, stages)).join('');
-  return `<details class="rcf-readiness-persona rcf-readiness-persona--${persona}" data-rcf-persona-state="${state}"${openAttr}>`
-    + `<summary><strong>${escapeHtml(summary)}</strong></summary>`
-    + items
-    + `</details>`;
+function renderCliVerdictLines(verdictLines) {
+  return `<p class="rcf-readiness-cli-verdict muted small" data-rcf-verdict="parity">`
+    + `<code>${escapeHtml(verdictLines.intentComplete)}</code> `
+    + `<code>${escapeHtml(verdictLines.readyToBuild)}</code>`
+    + `</p>`;
 }
 
-/**
- * Build an id→why map for a blocker by looking up the matching
- * `stages[].checks[].failing[]` entries. Ids missing a `why` map to
- * the empty string so the findings-list renders the id alone.
- *
- * @param {Blocker} b
- * @param {StageResult[]} stages
- * @returns {Record<string, string>}
- */
-function buildIdWhyMap(b, stages) {
-  /** @type {Record<string, string>} */
-  const map = {};
-  const stage = Array.isArray(stages) ? stages.find((s) => s && s.stage === b.stage) : null;
-  if (!stage || !Array.isArray(stage.checks)) return map;
-  const check = stage.checks.find((c) => c && c.name === b.check);
-  if (!check || !Array.isArray(check.failing)) return map;
-  for (const f of check.failing) {
-    if (!f || typeof f !== 'object') continue;
-    const id = typeof f.id === 'string' ? f.id : null;
-    if (!id) continue;
-    map[id] = typeof f.why === 'string' ? f.why : '';
-  }
-  return map;
-}
+// ---- Questions sub-view --------------------------------------------------
 
-/**
- * @param {Blocker} b
- * @param {StageResult[]} stages
- */
-function renderBlockerCard(b, stages) {
-  // Each id is a document id; the hash routing in html-page.js resolves
-  // `#<id>` to the right tab. The `why` per id lives on the matching
-  // `stages[].checks[].failing[]` entry — spec section 5 block 5.
-  const whyById = buildIdWhyMap(b, stages);
-  const items = (b.ids ?? []).slice(0, 20).map((id) => ({
-    id,
-    why: whyById[id] ?? '',
-    href: `#${id}`,
-  }));
-  return `<div class="rcf-readiness-blocker" data-rcf-stage="${escapeHtml(b.stage)}" data-rcf-check="${escapeHtml(b.check)}" data-rcf-persona="${escapeHtml(b.persona)}">`
-    + `<div class="rcf-readiness-blocker__meta">`
-    + `<span class="rcf-readiness-blocker__stage">${escapeHtml(b.stage)}</span> `
-    + `<span class="rcf-readiness-blocker__check">${escapeHtml(b.check)}</span> `
-    + pill({ value: b.persona === 'productOwner' ? 'PO' : 'eng', variant: 'persona', title: b.persona })
-    + ` <span class="rcf-readiness-blocker__over">over ${escapeHtml(b.over)}</span>`
-    + `</div>`
-    + findingsList({ heading: b.question, count: b.failingCount, items })
+function renderQuestionsSub({ questionRows, questionsSource, active }) {
+  const hidden = active ? '' : ' hidden';
+  const table = renderQuestionsTable({ rows: questionRows });
+  return `<div class="rcf-readiness-subpanel rcf-readiness-sub-questions" id="rcf-readiness-sub-questions" data-rcf-subpanel="questions" data-rcf-source="${escapeHtml(questionsSource)}" role="tabpanel"${hidden}>`
+    + table
     + `</div>`;
 }
 
-// --- Block 6: delta list -----------------------------------------------
-
-function renderDelta(result, freezeRecord) {
-  const d = result.delta;
-  const briefCount = Array.isArray(d.briefSince) ? d.briefSince.length : 0;
-  const changedCount = (d.changed?.length ?? 0) + (d.added?.length ?? 0) + (d.removed?.length ?? 0);
-  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 briefBlock = briefCount > 0
-    ? `<section class="rcf-readiness-delta__group rcf-readiness-delta__group--brief">`
-      + `<h4>Brief statements since freeze <span class="rcf-readiness-delta__count">${briefCount}</span></h4>`
-      + `<ul>${d.briefSince.map((n) => `<li>#${escapeHtml(String(n))}</li>`).join('')}</ul>`
-      + `</section>`
-    : '';
-  const changedBlock = changedCount > 0
-    ? `<section class="rcf-readiness-delta__group rcf-readiness-delta__group--documents">`
-      + `<h4>Documents changed <span class="rcf-readiness-delta__count">${changedCount}</span></h4>`
-      + `<ul>`
-      + (d.added ?? []).map((id) => `<li><a href="#${escapeHtml(id)}">${escapeHtml(id)}</a> <em>added</em>${renderDocDiff(id, frozenHashes, currentHashes, 'added')}</li>`).join('')
-      + (d.changed ?? []).map((id) => `<li><a href="#${escapeHtml(id)}">${escapeHtml(id)}</a> <em>changed</em>${renderDocDiff(id, frozenHashes, currentHashes, 'changed')}</li>`).join('')
-      + (d.removed ?? []).map((id) => `<li>${escapeHtml(id)} <em>removed</em>${renderDocDiff(id, frozenHashes, currentHashes, 'removed')}</li>`).join('')
-      + `</ul>`
-      + `</section>`
-    : '';
-  if (!briefBlock && !changedBlock) {
-    return `<section class="rcf-readiness-delta"><p><em>No delta since the last freeze.</em></p></section>`;
+function buildQuestionRowsForTable(adapterResult) {
+  const groups = Array.isArray(adapterResult?.groups) ? adapterResult.groups : [];
+  const optional = adapterResult?.optional ?? null;
+  const synthetic = [];
+  for (const g of groups) {
+    const items = Array.isArray(g?.items) ? g.items : [];
+    for (const it of items) {
+      synthetic.push({
+        itemId: it.itemId ?? it.id ?? '',
+        ask: it.ask,
+        hint: it.hint,
+        sourceSpanLabel: g.label,
+        checkId: it.checkId,
+        optional: Boolean(it.optional),
+      });
+    }
   }
-  return `<section class="rcf-readiness-delta">${briefBlock}${changedBlock}</section>`;
-}
-
-/**
- * Document-level hash diff for one changed / added / removed id.
- * Spec section 5 block 6 pins a real `diff` component here; section 10
- * decision 1 scopes 0.29.0 to document-level only (criterion-level
- * deferred). The freeze record does not persist document bodies in
- * 0.29.0 (freeze-record.js schema: `docHashes` only — no `docs` /
- * `snapshot` section), so this ships the hash-only variant: both
- * columns show the short-hash subtitle and the frozen side carries
- * a muted note stating the body was not captured. NOTES in the brief.
- */
-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 0.29.0';
-  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)}`;
+  if (optional && Array.isArray(optional.items)) {
+    for (const it of optional.items) {
+      synthetic.push({
+        itemId: it.itemId ?? '',
+        ask: it.ask,
+        hint: it.hint,
+        sourceSpanLabel: optional.label,
+        checkId: it.checkId,
+        optional: true,
+      });
+    }
+  }
+  return buildQuestionRows(synthetic);
 }
 
-// --- Block 7: per-stage check detail -----------------------------------
+// ---- Blocking sub-view ---------------------------------------------------
 
-function renderStageDetail(result) {
-  const stageBlocks = result.stages.map((s) => renderStage(s)).join('');
-  return `<section class="rcf-readiness-stage-detail">`
-    + `<h3>Stage detail</h3>`
-    + stageBlocks
-    + `</section>`;
+function renderBlockingSub({ blockingRows, active }) {
+  const hidden = active ? '' : ' hidden';
+  const table = renderBlockingTable({ rows: blockingRows });
+  return `<div class="rcf-readiness-subpanel rcf-readiness-sub-blocking" id="rcf-readiness-sub-blocking" data-rcf-subpanel="blocking" role="tabpanel"${hidden}>`
+    + table
+    + `</div>`;
 }
 
-/**
- * @param {StageResult} s
- */
-function renderStage(s) {
-  const chip = pill({ value: s.state, variant: 'gate-state', title: `${s.stage} ${s.gate}` });
-  const checks = s.checks.map((c) => renderCheck(s, c)).join('');
-  return `<section class="rcf-readiness-stage" id="rcf-readiness-stage-${escapeHtml(s.stage)}">`
-    + `<h4>${escapeHtml(s.stage)} <code>${escapeHtml(s.gate)}</code> ${chip}</h4>`
-    + checks
-    + `</section>`;
-}
+// ---- Coverage sub-view ---------------------------------------------------
 
-/**
- * @param {StageResult} s
- * @param {CheckResult} c
- */
-function renderCheck(s, c) {
-  const checkId = `rcf-readiness-check-${encodeURIComponent(`${s.stage}:${c.name}`)}`;
-  const personaPill = pill({
-    value: c.persona === 'productOwner' ? 'PO' : 'eng',
-    variant: 'persona',
-    title: c.persona,
-  });
-  const statusLabel = c.ok ? 'ok' : 'fail';
-  const items = c.ok
-    ? ''
-    : findingsList({
-      heading: c.question,
-      count: c.failing.length,
-      items: c.failing.map((f) => ({ id: f.id, why: f.why, href: `#${f.id}` })),
-    });
-  return `<div class="rcf-readiness-check" id="${escapeHtml(checkId)}" data-rcf-check-ok="${c.ok ? 'yes' : 'no'}">`
-    + `<div class="rcf-readiness-check__meta">`
-    + `<strong>${escapeHtml(c.name)}</strong> ${personaPill} `
-    + `<span class="rcf-readiness-check__over">over ${escapeHtml(c.over)}</span> `
-    + `<span class="rcf-readiness-check__counts">${c.pass}/${c.total}</span> `
-    + `<span class="rcf-readiness-check__status rcf-readiness-check__status--${statusLabel}">${statusLabel}</span>`
-    + `</div>`
-    + items
+function renderCoverageSub({ result, tree, thinRows, active }) {
+  const hidden = active ? '' : ' hidden';
+  const summary = renderCoverageSummary({ coverage: result.coverage, tree });
+  const thin = renderThinReqsTable({ rows: thinRows });
+  return `<div class="rcf-readiness-subpanel rcf-readiness-sub-coverage" id="rcf-readiness-sub-coverage" data-rcf-subpanel="coverage" role="tabpanel"${hidden}>`
+    + summary
+    + thin
     + `</div>`;
 }
 
-// --- Block 8: coverage tree-vs-delta -----------------------------------
-
-function renderCoverage(result) {
-  const t = result.coverage?.tree ?? null;
-  const d = result.coverage?.delta ?? [];
-  const impactedCount = result.delta?.impacted?.length ?? 0;
-  const impactedFbsCount = result.delta?.impactedFbs?.length ?? 0;
-  const treeCol = t
-    ? `<pre class="rcf-readiness-coverage__tree">pass ${escapeHtml(String(t.pass ?? ''))} / ${escapeHtml(String(t.total ?? ''))}</pre>`
-    : `<p><em>No tree-wide coverage result.</em></p>`;
-  // Filter rows where every meaningful field is nullish / empty — a
-  // coverage shim with no reqId/scope and no pass/total totals produces
-  // "delta: / " markup otherwise (P2 polish; spec §5 block 8).
-  const liveDelta = Array.isArray(d) ? d.filter(isMeaningfulCoverageRow) : [];
-  const deltaRows = liveDelta.length > 0
-    ? `<ul>${liveDelta.map((cv) => `<li>${escapeHtml(cv.reqId ?? cv.scope ?? 'delta')}: ${escapeHtml(String(cv.pass ?? ''))} / ${escapeHtml(String(cv.total ?? ''))}</li>`).join('')}</ul>`
-    : `<p><em>No per-REQ delta coverage.</em></p>`;
-  return `<section class="rcf-readiness-coverage">`
-    + `<h3>Coverage</h3>`
-    + `<div class="rcf-readiness-coverage__cols">`
-    + `<div class="rcf-readiness-coverage__col rcf-readiness-coverage__col--tree"><h4>Tree</h4>${treeCol}</div>`
-    + `<div class="rcf-readiness-coverage__col rcf-readiness-coverage__col--delta"><h4>Delta</h4>${deltaRows}</div>`
+// ---- Trace sub-view (FBS-208, US-209, TAC-4136, ADR-4140) ----------------
+
+function renderTraceSub({ active }) {
+  const hidden = active ? '' : ' hidden';
+  // Initial markup: the empty-state renderer (no pivot yet). The
+  // page-init.js `wireTraceMatrix` fetches `./trace.json` and
+  // `./coverage.json` and re-renders the inner `[data-rcf-trace-root]`
+  // when the hash carries `#tab=readiness&sub=trace&entity=<id>`.
+  return `<div class="rcf-readiness-subpanel rcf-readiness-sub-trace" id="rcf-readiness-sub-trace" data-rcf-subpanel="trace" role="tabpanel"${hidden}>`
+    + `<div data-rcf-trace-root="yes">`
+    + `<section class="rcf-trace-matrix rcf-trace-matrix--empty" data-rcf-trace-matrix="empty" data-rcf-trace-reason="no-pivot" aria-labelledby="rcf-readiness-trace-heading">`
+    + `<header class="rcf-trace-matrix__head"><h3 id="rcf-readiness-trace-heading">Pick an id to trace</h3></header>`
+    + `<p>Pick a requirement, story or criterion through the Trace action on any readiness row, or open the lookup to search by id.</p>`
+    + `<p><button type="button" class="rcf-trace-matrix__lookup" data-rcf-trace-open-lookup="yes">Open the lookup</button></p>`
+    + `</section>`
     + `</div>`
-    + `<p class="rcf-readiness-coverage__counts">`
-    + `re-verify: ${impactedCount} &middot; re-execute: ${impactedFbsCount}`
-    + `</p>`
-    + `</section>`;
-}
-
-function isMeaningfulCoverageRow(cv) {
-  if (!cv || typeof cv !== 'object') return false;
-  const hasLabel = (typeof cv.reqId === 'string' && cv.reqId.length > 0)
-    || (typeof cv.scope === 'string' && cv.scope.length > 0);
-  const passSet = cv.pass !== null && cv.pass !== undefined && cv.pass !== '';
-  const totalSet = cv.total !== null && cv.total !== undefined && cv.total !== '';
-  return hasLabel || passSet || totalSet;
+    + `</div>`;
 }
 
-// --- Block 9: decisions outstanding ------------------------------------
+// ---- Decisions outstanding -----------------------------------------------
 
 function renderDecisions(result) {
   const items = Array.isArray(result.decisions) ? result.decisions : [];
@@ -451,31 +344,122 @@ function renderDecisions(result) {
   return `<section class="rcf-readiness-decisions"><h3>Decisions outstanding</h3><ol>${list}</ol></section>`;
 }
 
-// --- Block 10: freeze now ----------------------------------------------
+// ---- Freeze state (plain words, no command, no control) -----------------
+//
+// AC-18005-5: readyToBuild=no names each failing gate with what
+// resolves it; readyToBuild=yes states that the tree can be frozen
+// and what a freeze would record. "On me" / "On engineers" vocab
+// replaces persona pills.
 
-function renderFreezeNow(result) {
+function renderFreezeState(result, register) {
   const ok = result.levels.readyToBuild.ok;
-  const disabledAttr = ok ? '' : ' disabled';
-  const failingGates = ok
-    ? []
-    : [...new Set(result.levels.readyToBuild.blockedBy.map((b) => b.gate))].sort();
-  const failingList = failingGates.length > 0
-    ? ` <span class="rcf-readiness-freeze-now__failing">Failing gates: ${failingGates.map((g) => escapeHtml(g)).join(', ')}</span>`
-    : '';
-  const cmd = `rcf define freeze`;
-  const willRecord = ok
-    ? `<p>Will record: tree hash <code>${escapeHtml(shortHash(result.tree.currentTreeHash))}</code>, timestamp, note, counts and acknowledged gates with reasons.</p>`
-    : '';
-  return `<section class="rcf-readiness-freeze-now" data-rcf-freezeable="${ok ? 'yes' : 'no'}">`
-    + `<h3>Freeze now</h3>`
-    + `<button type="button" class="rcf-readiness-freeze-now__btn"${disabledAttr}>Freeze</button>`
-    + ` <code>${escapeHtml(cmd)}</code>`
-    + failingList
-    + willRecord
+  const freezeableAttr = ok ? 'yes' : 'no';
+  if (ok) {
+    const shortCurrent = escapeHtml(shortHash(result.tree.currentTreeHash));
+    return `<section class="rcf-readiness-freeze-state" data-rcf-freezeable="${freezeableAttr}">`
+      + `<h3>Freeze state</h3>`
+      + `<p>Ready to freeze. A freeze would record the current tree hash <code>${shortCurrent}</code>, the timestamp, the note, the counts and the acknowledged gates with their reasons.</p>`
+      + `</section>`;
+  }
+  const blockers = Array.isArray(result.levels.readyToBuild.blockedBy) ? result.levels.readyToBuild.blockedBy : [];
+  const grouped = groupBlockersByGate(blockers);
+  if (grouped.length === 0) {
+    return `<section class="rcf-readiness-freeze-state" data-rcf-freezeable="${freezeableAttr}">`
+      + `<h3>Freeze state</h3>`
+      + `<p>Not ready to freeze.</p>`
+      + `</section>`;
+  }
+  const items = grouped.map((g) => {
+    const owner = g.ownerLabel;
+    const resolver = resolverSentence(g.gate, g.checks);
+    const stageWord = gateToPlainStage(g.gate);
+    const lead = stageWord
+      ? `the ${stageWord} stage is held`
+      : 'this stage is held';
+    // Each item leads with a plain-English sentence naming the stage
+    // and what resolves it (AC-18005-5). The chain gate id follows
+    // in <code> so an engineer scanning the block can jump into the
+    // chain (AC-18001-6 pins this locator).
+    return `<li data-rcf-gate="${escapeHtml(g.gate)}" data-rcf-owner="${escapeHtml(g.owner)}">`
+      + `<span class="muted small">(${escapeHtml(owner)})</span> ${escapeHtml(lead)}: ${escapeHtml(resolver)} `
+      + `<code>${escapeHtml(g.gate)}</code>`
+      + `</li>`;
+  }).join('');
+  // The gate labels are fixed: 'On me' names the product owner's
+  // own gates, 'On engineers' names the gates handed over. The lead
+  // sentence states that invariant verbatim for both registers so
+  // the vocabulary never flips when the engineer surface renders.
+  const lead = 'The build is held by these gates. "On me" names the product owner\'s own gates, "On engineers" names the ones handed over.';
+  return `<section class="rcf-readiness-freeze-state" data-rcf-freezeable="${freezeableAttr}">`
+    + `<h3>Freeze state</h3>`
+    + `<p>Not ready to freeze. ${escapeHtml(lead)}</p>`
+    + `<ul class="rcf-readiness-freeze-state__gates">${items}</ul>`
     + `</section>`;
 }
 
-// --- Block 11: freeze record -------------------------------------------
+/** Group blockers by gate, folding owner (persona) to the shared label. */
+function groupBlockersByGate(blockers) {
+  const byGate = new Map();
+  for (const b of blockers) {
+    if (!b || typeof b !== 'object') continue;
+    const gate = typeof b.gate === 'string' ? b.gate : '';
+    if (!gate) continue;
+    const slot = byGate.get(gate) || { gate, owners: new Set(), checks: new Set() };
+    if (b.persona === 'productOwner' || b.persona === 'engineer') slot.owners.add(b.persona);
+    if (typeof b.check === 'string') slot.checks.add(b.check);
+    byGate.set(gate, slot);
+  }
+  const rows = [];
+  for (const slot of byGate.values()) {
+    const owners = Array.from(slot.owners);
+    const owner = owners.length === 1 ? owners[0] : (owners.includes('productOwner') ? 'productOwner' : 'engineer');
+    rows.push({
+      gate: slot.gate,
+      owner,
+      ownerLabel: owner === 'productOwner' ? 'On me' : 'On engineers',
+      checks: Array.from(slot.checks).sort(),
+    });
+  }
+  rows.sort((a, b) => a.gate.localeCompare(b.gate));
+  return rows;
+}
+
+/**
+ * Plain-English sentence naming what resolves the gate, derived from
+ * its failing checks. Keeps the viewer command-free: the engineer or
+ * product owner reads what the row says and acts in their own agent
+ * session.
+ */
+function resolverSentence(gate, checks) {
+  if (checks.length === 0) return `the ${gate} gate still has failing items in the blocking table.`;
+  const labels = checks.map(checkToPlainLabel).filter(Boolean);
+  const uniq = Array.from(new Set(labels));
+  if (uniq.length === 0) return `resolve the failing items for ${gate} named in the blocking table.`;
+  if (uniq.length === 1) return `resolve the ${uniq[0]} failing items in the blocking table.`;
+  const last = uniq.pop();
+  return `resolve the ${uniq.join(', ')} and ${last} failing items in the blocking table.`;
+}
+
+function checkToPlainLabel(check) {
+  if (typeof check !== 'string' || check.length === 0) return '';
+  // e.g. "brief:sinceFreeze" -> "brief", "stories:usFloors" -> "stories",
+  // "crosscut:securityArchitecture" -> "crosscut".
+  const idx = check.indexOf(':');
+  return idx === -1 ? check : check.slice(0, idx);
+}
+
+// Map a gate id ("define.brief", "define.stories", "define.crosscut",
+// "define.probe", "define.freeze", ...) to a short plain-English stage
+// word for the freeze-state items. Returns the second segment lowercased
+// (or the full id when there is no separator) so the user-facing text
+// reads "the brief stage is held" rather than citing a chain id.
+function gateToPlainStage(gate) {
+  if (typeof gate !== 'string' || gate.length === 0) return '';
+  const idx = gate.indexOf('.');
+  return idx === -1 ? gate : gate.slice(idx + 1);
+}
+
+// ---- Freeze record -------------------------------------------------------
 
 function renderFreezeRecord(freezeRecord) {
   if (!freezeRecord) {
@@ -491,7 +475,12 @@ function renderFreezeRecord(freezeRecord) {
     : '';
   const gates = freezeRecord.gates && typeof freezeRecord.gates === 'object'
     ? Object.entries(freezeRecord.gates)
-      .map(([k, v]) => `<li><code>${escapeHtml(k)}</code>: ${escapeHtml(v && typeof v === 'object' && typeof v.reason === 'string' ? v.reason : String(v ?? ''))}</li>`)
+      .map(([k, v]) => {
+        const atReason = v && typeof v === 'object' && v.at && typeof v.at === 'object' && typeof v.at.reason === 'string' ? v.at.reason : null;
+        const flatReason = v && typeof v === 'object' && typeof v.reason === 'string' ? v.reason : null;
+        const reason = atReason !== null && atReason.length > 0 ? atReason : (flatReason !== null && flatReason.length > 0 ? flatReason : String(v ?? ''));
+        return `<li><code>${escapeHtml(k)}</code>: ${escapeHtml(reason)}</li>`;
+      })
       .join('')
     : '';
   return `<section class="rcf-readiness-freeze-record">`