rcf-lite 0.28.2 → 0.29.0

package/src/view/readiness/question-adapter.js

@@ -0,0 +1,329 @@
+// Readiness PO question adapter (viewer UI refresh PR 8, TAC-4133,
+// ADR-4135). One pure module that returns the question groups the PO
+// layer renders. Today it reads `personas.productOwner.blockers` and
+// fills asks from the phrasebook. When DEFINE step 3 PR 2 ships
+// `readiness.questions`, `preferReadinessQuestions(readiness)` flips
+// the source: the call site in the tab reads only this module's
+// output so no downstream edit is needed.
+//
+// Grouping follows design doc section 8: one group per source span.
+// Brief checks group by `brief:<n>` on the failing item's `why`; the
+// resolvedBy and reqIntent checks group by the REQ ancestor named on
+// the failing item (REQ-N); stories:reqHasUs groups under
+// "Requirements without a story yet". A conservative default groups
+// by stage when no better key is available.
+//
+// Decisions-with-a-default (the phrasebook `optional` flag) sit in a
+// dashed optional card and never hold up the hand-over.
+
+import { phrasebookEntry } from './phrasebook.js';
+
+/**
+ * @typedef {object} AdapterItem
+ * @property {string} heading
+ * @property {string} ask
+ * @property {string} hint
+ * @property {string} detail       engineer-style one-line detail for the Show detail inner block
+ * @property {string} checkId      stage/check for the hover title
+ * @property {string} [itemId]     the failing item id when known
+ * @property {boolean} [optional]
+ */
+
+/**
+ * @typedef {object} AdapterGroup
+ * @property {string} label        the source span heading, in plain words
+ * @property {AdapterItem[]} items
+ * @property {boolean} [optional]
+ */
+
+/**
+ * Feature detect for DEFINE step 3 PR 2's `questions[]` shape on the
+ * readiness result. When the compute lands, the adapter reads from
+ * `readiness.questions` instead of from blockers.
+ *
+ * @param {object | null | undefined} readiness
+ * @returns {boolean}
+ */
+export function preferReadinessQuestions(readiness) {
+  if (!readiness || typeof readiness !== 'object') return false;
+  const q = /** @type {{ questions?: unknown }} */ (readiness).questions;
+  return Array.isArray(q);
+}
+
+/**
+ * Pure projection of the readiness object into question groups for
+ * the PO layer. Does not read disk, does not render HTML.
+ *
+ * @param {object | null | undefined} readiness
+ * @returns {{ groups: AdapterGroup[], optional: AdapterGroup | null }}
+ */
+export function toQuestions(readiness) {
+  if (!readiness || typeof readiness !== 'object') {
+    return { groups: [], optional: null };
+  }
+  const base = preferReadinessQuestions(readiness)
+    ? fromReadinessQuestions(readiness)
+    : fromBlockers(readiness);
+  // Thread `readiness.questionOptional` (the raw `computeQuestions`
+  // open-decisions list, carried onto readiness in view/index.js) into
+  // the dashed optional group so DEFINE open decisions with a default
+  // reach the PO layer even when they are not among `questions[]`.
+  const extra = buildOptionalFromRaw(readiness);
+  if (!extra || extra.items.length === 0) return base;
+  if (!base.optional) {
+    return { groups: base.groups, optional: extra };
+  }
+  const seen = new Set(base.optional.items.map((it) => it.itemId ?? it.heading));
+  const merged = base.optional.items.slice();
+  for (const it of extra.items) {
+    const key = it.itemId ?? it.heading;
+    if (!seen.has(key)) {
+      merged.push(it);
+      seen.add(key);
+    }
+  }
+  return {
+    groups: base.groups,
+    optional: { label: base.optional.label, items: merged, optional: true },
+  };
+}
+
+/**
+ * Fold `readiness.questionOptional` (the raw `computeQuestions`
+ * `optional[]` list of `{ id, ask, blocks }`) into AdapterItem shape
+ * so the PO layer renders open decisions as dashed cards.
+ *
+ * @param {object} readiness
+ * @returns {AdapterGroup | null}
+ */
+function buildOptionalFromRaw(readiness) {
+  const raw = /** @type {{ questionOptional?: Array<unknown> }} */ (readiness).questionOptional;
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  /** @type {AdapterItem[]} */
+  const items = [];
+  for (const row of raw) {
+    if (!row || typeof row !== 'object') continue;
+    const r = /** @type {Record<string, unknown>} */ (row);
+    const id = typeof r.id === 'string' ? r.id : '';
+    const ask = typeof r.ask === 'string' && r.ask.length > 0 ? r.ask : 'Decision has a default; answer now or let it stand.';
+    const heading = 'An open decision has a default';
+    const hint = 'Answer with the option letter, or let the default stand.';
+    items.push({
+      heading,
+      ask,
+      hint,
+      detail: id ? `open decision ${id}` : 'open decision',
+      checkId: 'D7/open-decision',
+      itemId: id || undefined,
+      optional: true,
+    });
+  }
+  if (items.length === 0) return null;
+  return { label: 'Optional: decisions with a default (they do not hold up the hand-over)', items, optional: true };
+}
+
+// ---- source A: readiness.questions[] (DEFINE step 3 PR 2) --------------
+//
+// Accepts both shapes:
+//   1. The real `computeQuestions` output: each question carries
+//      `.id` (a Q-...-...), `.itemId` (brief:7 / REQ-012 / ...),
+//      `.stage`, `.check`, `.heading`, `.ask`, and `.context` whose
+//      `.sourceSpan` or nested `.statement.source` names the span.
+//   2. A flattened test / adapter shape that pre-labels the group via
+//      `.sourceSpanLabel` and names the item on `.id` directly.
+// The group label falls back to a conservative prose sentence built
+// from the source span key when no `sourceSpanLabel` is present.
+
+function fromReadinessQuestions(readiness) {
+  const q = /** @type {Array<unknown>} */ (readiness.questions);
+  /** @type {Map<string, AdapterGroup>} */
+  const byLabel = new Map();
+  /** @type {AdapterItem[]} */
+  const optionalItems = [];
+  for (const raw of q) {
+    if (!raw || typeof raw !== 'object') continue;
+    const r = /** @type {Record<string, unknown>} */ (raw);
+    const checkId = typeof r.checkId === 'string'
+      ? r.checkId
+      : (typeof r.check === 'string' ? r.check : '');
+    const stage = typeof r.stage === 'string' ? r.stage : '';
+    const itemId = pickItemId(r);
+    const label = pickLabel(r, { checkId, itemId });
+    const pb = phrasebookEntry(checkId, itemId);
+    const heading = typeof r.heading === 'string' && r.heading.length > 0 ? r.heading : pb.heading;
+    const ask = typeof r.ask === 'string' && r.ask.length > 0 ? r.ask : pb.ask;
+    const hint = typeof r.hint === 'string' && r.hint.length > 0 ? r.hint : pb.hint;
+    const optional = typeof r.optional === 'boolean' ? r.optional : Boolean(pb.optional);
+    const why = typeof r.why === 'string' ? r.why : '';
+    const detail = buildDetail({ stage, checkId, itemId, why });
+    const item = { heading, ask, hint, detail, checkId: `${stage}/${checkId}`, itemId, optional };
+    if (optional) {
+      optionalItems.push(item);
+      continue;
+    }
+    if (!byLabel.has(label)) byLabel.set(label, { label, items: [] });
+    byLabel.get(label).items.push(item);
+  }
+  return {
+    groups: Array.from(byLabel.values()),
+    optional: optionalItems.length > 0
+      ? { label: 'Optional: decisions with a default (they do not hold up the hand-over)', items: optionalItems, optional: true }
+      : null,
+  };
+}
+
+/**
+ * Pick the human itemId from a question record. Prefers an explicit
+ * `.itemId` (the real computeQuestions shape); falls back to `.id`
+ * only when it looks like a bare itemId (brief:*, profile:*,
+ * decision:*, REQ-*, AC-*), never a Q-... question id, so the
+ * phrasebook sub-check keying still works.
+ */
+function pickItemId(r) {
+  if (typeof r.itemId === 'string' && r.itemId.length > 0) return r.itemId;
+  if (typeof r.id === 'string' && /^(brief:|profile:|decision:|REQ-|AC-)/.test(r.id)) return r.id;
+  return undefined;
+}
+
+/**
+ * Build the group label for a question. Honours an explicit
+ * `.sourceSpanLabel` first; then uses `.sourceSpan` or
+ * `.context.sourceSpan` / `.context.statement.source` (the real
+ * computeQuestions shape); then falls back to a plain prose sentence
+ * for brief:N / profile:* / REQ-* / stories:reqHasUs, matching the
+ * blockers-path labels so the PO layer reads the same way in both
+ * modes.
+ */
+function pickLabel(r, { checkId, itemId }) {
+  if (typeof r.sourceSpanLabel === 'string' && r.sourceSpanLabel.length > 0) return r.sourceSpanLabel;
+  const ctx = (r && typeof r.context === 'object' && r.context) ? r.context : null;
+  const stmtSrc = ctx && typeof ctx === 'object' && ctx.statement && typeof ctx.statement === 'object'
+    ? ctx.statement.source
+    : null;
+  const span = typeof r.sourceSpan === 'string' && r.sourceSpan.length > 0
+    ? r.sourceSpan
+    : (typeof stmtSrc === 'string' && stmtSrc.length > 0
+      ? stmtSrc
+      : (ctx && typeof ctx.sourceSpan === 'string' ? ctx.sourceSpan : ''));
+  if (span.startsWith('brief:')) {
+    const rest = span.slice('brief:'.length);
+    return /^\d+$/.test(rest) ? `Your document, statement ${rest}` : 'Your document';
+  }
+  if (/^REQ-/.test(span)) return `Requirement ${span}`;
+  // Fall back to the same mapping the blockers path uses, so the two
+  // sources render identical group labels on the dogfood tree.
+  return labelForBlocker({ stage: typeof r.stage === 'string' ? r.stage : '', check: checkId }, itemId);
+}
+
+// ---- source B: personas.productOwner.blockers (today's shape) ----------
+
+/**
+ * The source span label for a PO blocker. Brief checks name a brief
+ * statement number (`brief:7`); resolvedBy and reqIntent name a REQ;
+ * reqHasUs sits under "Requirements without a story yet"; everything
+ * else falls back to the plain stage label.
+ *
+ * @param {{ stage: string, check: string }} b
+ * @param {string} itemId
+ * @returns {string}
+ */
+function labelForBlocker(b, itemId) {
+  if (b.check === 'stories:reqHasUs') return 'Requirements without a story yet';
+  if (typeof itemId === 'string' && itemId.startsWith('brief:')) {
+    const n = itemId.slice('brief:'.length);
+    return /^\d+$/.test(n) ? `Your document, statement ${n}` : 'Your document';
+  }
+  if (b.check === 'brief:sinceFreeze') return 'About this project';
+  if (b.check === 'brief:profile') return 'How you want to review';
+  if (b.check === 'brief:openQuestions') return 'Open questions in your document';
+  if (b.check === 'brief:kinds') return 'Statements in your document';
+  if (b.check === 'skeleton:resolvedBy') return 'Your document, statements without a home';
+  if (b.check === 'skeleton:reqIntent') return 'Requirements that need a plain description';
+  if (b.check === 'decisions:wellFormed') return 'Decisions without options yet';
+  if (typeof itemId === 'string' && /^REQ-/.test(itemId)) return `Requirement ${itemId}`;
+  return `Stage ${b.stage || 'other'}`;
+}
+
+/**
+ * Build an engineer-style detail line for the inner "Show detail"
+ * block (never shown as the PO ask). This stays private to the PO
+ * layer; the For-engineers DocRow carries the full detail.
+ */
+function buildDetail({ stage, checkId, itemId, why }) {
+  const parts = [];
+  if (stage) parts.push(stage);
+  if (checkId) parts.push(checkId);
+  if (itemId) parts.push(`id ${itemId}`);
+  if (why) parts.push(why);
+  return parts.join(' / ');
+}
+
+function fromBlockers(readiness) {
+  const po = /** @type {{ personas?: { productOwner?: { blockers?: Array<unknown> } } }} */ (readiness);
+  const blockers = Array.isArray(po.personas?.productOwner?.blockers)
+    ? po.personas.productOwner.blockers
+    : [];
+  const stages = Array.isArray(/** @type {{stages?:unknown}} */(readiness).stages)
+    ? /** @type {Array<Record<string, unknown>>} */ (readiness.stages)
+    : [];
+  /** @type {Map<string, AdapterGroup>} */
+  const byLabel = new Map();
+  /** @type {AdapterItem[]} */
+  const optionalItems = [];
+  for (const raw of blockers) {
+    if (!raw || typeof raw !== 'object') continue;
+    const b = /** @type {Record<string, unknown>} */ (raw);
+    const stage = typeof b.stage === 'string' ? b.stage : '';
+    const checkId = typeof b.check === 'string' ? b.check : '';
+    const ids = Array.isArray(b.ids) ? b.ids : [];
+    const whyById = buildWhyById(stages, stage, checkId);
+    const items = ids.length > 0 ? ids : [null];
+    for (const idRaw of items) {
+      const itemId = typeof idRaw === 'string' ? idRaw : undefined;
+      const why = itemId && whyById[itemId] ? whyById[itemId] : '';
+      const pb = phrasebookEntry(checkId, itemId);
+      const label = labelForBlocker({ stage, check: checkId }, itemId);
+      const optional = Boolean(pb.optional);
+      const item = {
+        heading: pb.heading,
+        ask: pb.ask,
+        hint: pb.hint,
+        detail: buildDetail({ stage, checkId, itemId, why }),
+        checkId: `${stage}/${checkId}`,
+        itemId,
+        optional,
+      };
+      if (optional) {
+        optionalItems.push(item);
+        continue;
+      }
+      if (!byLabel.has(label)) byLabel.set(label, { label, items: [] });
+      byLabel.get(label).items.push(item);
+    }
+  }
+  return {
+    groups: Array.from(byLabel.values()),
+    optional: optionalItems.length > 0
+      ? { label: 'Optional: decisions with a default (they do not hold up the hand-over)', items: optionalItems, optional: true }
+      : null,
+  };
+}
+
+/**
+ * Build an id -> why map by walking stages[stage].checks[check].failing[].
+ */
+function buildWhyById(stages, stage, checkName) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  const s = stages.find((row) => row && row.stage === stage);
+  if (!s || !Array.isArray(s.checks)) return out;
+  const c = s.checks.find((row) => row && row.name === checkName);
+  if (!c || !Array.isArray(c.failing)) return out;
+  for (const f of c.failing) {
+    if (!f || typeof f !== 'object') continue;
+    const id = typeof f.id === 'string' ? f.id : null;
+    if (!id) continue;
+    out[id] = typeof f.why === 'string' ? f.why : '';
+  }
+  return out;
+}

package/src/view/readiness/stage-legend.js

@@ -0,0 +1,71 @@
+// Readiness StageLegend (viewer UI refresh PR 8, decision 16).
+//
+// Renders a `<dialog>` listing D1..D8 by name, one-line meaning and
+// posture (blocks the freeze, or warns until acknowledged). Opens
+// from any D-chip or D-prefixed check name; client wiring lives in
+// page-init.js (`wireStageLegend`). The dialog is server-rendered
+// HTML so the shell carries no inline script.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+import { STAGE_GATES, STAGE_ORDER } from '../../query/gates.js';
+
+/**
+ * Human-readable name and one-line meaning per stage, aligned with
+ * design doc section 4 and the readiness wireframe (STAGE_GATES).
+ *
+ * @type {Record<string, { name: string, meaning: string, posture: 'blocking'|'warn-with-ack' }>}
+ */
+export const STAGE_LEGEND = {
+  D1: { name: 'Brief', meaning: 'Brief intake and ledger: the owner\'s statements numbered and kinded, open questions answered or promoted, profile markers set.', posture: 'blocking' },
+  D2: { name: 'Skeleton', meaning: 'Requirements and architecture skeleton: every statement resolves to a requirement, an entity, an actor, a system or a surface; TAD persistence and a deploy decision exist.', posture: 'blocking' },
+  D3: { name: 'Shapes', meaning: 'Interface contracts and shapes on components and on shaped requirements (http, persistence, auth).', posture: 'warn-with-ack' },
+  D4: { name: 'Stories', meaning: 'Stories and criteria floors: every requirement has a story; stories carry failure and must-not criteria.', posture: 'blocking' },
+  D5: { name: 'Crosscut', meaning: 'Cross-cutting weave: security, operations and the other concerns are present where the requirements imply them.', posture: 'warn-with-ack' },
+  D6: { name: 'Consistency', meaning: 'Consistency and satisfiability probe: the tree validates clean and no probe is left open.', posture: 'warn-with-ack' },
+  D7: { name: 'Decisions', meaning: 'Decisions and review: every decision enumerated with options and a default; none open at freeze.', posture: 'blocking' },
+  D8: { name: 'Freeze', meaning: 'Freeze: prior stages passed or acknowledged, every criterion owned by one build spec, the queue head actionable, validate clean.', posture: 'blocking' },
+};
+
+/**
+ * Short title for a stage, used as the `title` attribute on D-chips
+ * and D-prefixed check names (hover-to-explain).
+ *
+ * @param {string} stage
+ * @returns {string}
+ */
+export function stageTitle(stage) {
+  const row = STAGE_LEGEND[stage];
+  if (!row) return stage;
+  return `${stage} ${row.name}: ${row.meaning.split(':')[0]}`;
+}
+
+/**
+ * Render the StageLegend `<dialog>` HTML.
+ *
+ * @returns {string}
+ */
+export function renderStageLegend() {
+  const rows = STAGE_ORDER.map((stage) => {
+    const row = STAGE_LEGEND[stage];
+    const gate = STAGE_GATES[stage];
+    const postureClass = row.posture === 'blocking' ? 'fail' : 'warn';
+    const postureLabel = row.posture === 'blocking' ? 'blocks freeze' : 'warns, acknowledge to pass';
+    return `<tr data-stage="${escapeHtml(stage)}">`
+      + `<td class="rcf-stage-legend__code"><code>${escapeHtml(stage)}</code></td>`
+      + `<td class="rcf-stage-legend__name"><strong>${escapeHtml(row.name)}</strong> <span class="muted"><code>${escapeHtml(gate)}</code></span></td>`
+      + `<td class="rcf-stage-legend__meaning">${escapeHtml(row.meaning)}</td>`
+      + `<td class="rcf-stage-legend__posture"><span class="rcf-pill rcf-pill--${postureClass}">${escapeHtml(postureLabel)}</span></td>`
+      + `</tr>`;
+  }).join('');
+  return `<dialog id="rcf-stage-legend" class="rcf-stage-legend" aria-labelledby="rcf-stage-legend-title">
+  <header class="rcf-stage-legend__head">
+    <h2 id="rcf-stage-legend-title">Stage guide: D1 to D8</h2>
+    <form method="dialog"><button type="submit" class="rcf-stage-legend__close">Close</button></form>
+  </header>
+  <p class="rcf-stage-legend__intro muted">The eight DEFINE stages the readiness object reports on. A blocking stage must pass before the tree can freeze; a warning stage passes once its findings are acknowledged. Codes are the chain's names; the viewer never asks a product owner to read them.</p>
+  <table class="rcf-stage-legend__table">
+    <thead><tr><th>Stage</th><th>Name</th><th>What it checks</th><th>Posture</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</dialog>`;
+}