rcf-lite 0.0.1 → 0.7.1

package/src/ui-baseline/manifest-writer.js

@@ -0,0 +1,282 @@
+// UI-baseline manifest writer (ui-design-gate-0.7.0-spec §3.2, §5.4).
+//
+// Owns id allocation (`uib-YYYY-MM-DD-NNN` monotonic per project),
+// atomic tmp-and-rename write against `rcf/manifest.json`, and
+// `uiBaselineHistory[]` folding on `--reset`. Every field is optional
+// on the schema; the enforcement happens via the interactive session
+// walking every field before writing `operatorAckAt`.
+//
+// The preflight seam (spec §3.2 + Track A preflight `skippedUiBaseline`
+// note): when the operator ratifies a `uiBaseline`, we look up
+// preflight-recorded design-shape answers whose `uiBaselineWritePath`
+// targets `defaults.*` and apply the deferred writes automatically.
+// Only APPLIED once (idempotent): the corresponding
+// `baselineAcOptOuts[]` entries stay in place as the durable ledger;
+// the seam itself is one-way from preflight into the baseline defaults.
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+import { composeDefaults, deepGet, deepSet } from './defaults.js';
+import { CATALOGUE_V1 } from '../preflight/design-shapes.js';
+
+/**
+ * Compute the next `uib-YYYY-MM-DD-NNN` id: monotonic per project.
+ *
+ * @param {object|null} manifest
+ * @param {Date} now
+ * @returns {string}
+ */
+export function nextUiBaselineId(manifest, now) {
+  const y = now.getUTCFullYear().toString().padStart(4, '0');
+  const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `uib-${y}-${m}-${d}-`;
+  const active = manifest?.uiBaseline?.id;
+  const history = Array.isArray(manifest?.uiBaselineHistory) ? manifest.uiBaselineHistory : [];
+  const ids = [active, ...history.map((h) => h?.id)].filter((id) => typeof id === 'string' && id.startsWith(prefix));
+  let maxN = 0;
+  for (const id of ids) {
+    const n = Number.parseInt(id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${(maxN + 1).toString().padStart(3, '0')}`;
+}
+
+/**
+ * Compose a fresh `uiBaseline` record. Applies preflight seam pickups
+ * (spec §3.2) that would otherwise sit fenced in preflight's
+ * `skippedUiBaseline` seam, plus any operator-supplied opt-outs.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.prdId
+ * @param {Array<{ field: string, reason: string }>} [args.optOuts]
+ * @param {object} [args.overrides]  dot-path -> value overrides (e.g. from preflight seam)
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composeUiBaselineRecord({
+  manifest, prdId, optOuts = [], overrides = {}, now = new Date(),
+}) {
+  const isoNow = now.toISOString();
+  const id = nextUiBaselineId(manifest, now);
+  const defaults = composeDefaults(overrides);
+  const record = {
+    id,
+    createdAt: isoNow,
+    prdId,
+    defaults,
+    operatorAckAt: isoNow,
+  };
+  if (optOuts.length > 0) {
+    record.operatorOptOuts = optOuts.map((o) => ({
+      field: o.field,
+      reason: o.reason,
+      operatorAckAt: isoNow,
+    }));
+  }
+  return record;
+}
+
+/**
+ * Given a manifest and its preFlightConfig[] record set, collect the
+ * dot-path overrides the preflight design-shape answers imply for
+ * `uiBaseline.defaults`. Idempotent seam: the answers stay in
+ * preflight; the values land as defaults on baseline creation.
+ *
+ * Generalised (Track B review N-4): reads
+ * `uiBaselineWritePath` + `uiBaselineWriteValue` off the catalogue's
+ * per-choice metadata rather than hard-coding a single question id. Any
+ * answered question whose selected choice carries a write path targeting
+ * `defaults.*` lands as a seeded override; newest ratification wins.
+ * A future Track C+D catalogue addition that names its own write path
+ * flows through this seam without any wiring change here.
+ *
+ * The catalogue is injectable for tests via the second argument; in
+ * production, callers use the default `CATALOGUE_V1` import.
+ *
+ * @param {object|null} manifest
+ * @param {Readonly<import('../preflight/design-shapes.js').DesignShapeQuestion[]>} [catalogue]
+ * @returns {object} dot-path -> value overrides (relative to `defaults`)
+ */
+export function preflightSeamOverrides(manifest, catalogue = CATALOGUE_V1) {
+  const overrides = {};
+  const questionsById = new Map();
+  for (const q of Array.isArray(catalogue) ? catalogue : []) {
+    if (q?.id) questionsById.set(q.id, q);
+  }
+  const records = Array.isArray(manifest?.preFlightConfig) ? manifest.preFlightConfig : [];
+  // Walk newest-first so a later ratification wins over an earlier one.
+  for (let i = records.length - 1; i >= 0; i -= 1) {
+    const rec = records[i];
+    const answers = Array.isArray(rec?.designShapeAnswers) ? rec.designShapeAnswers : [];
+    for (const answer of answers) {
+      const question = questionsById.get(answer?.questionId);
+      if (!question) continue;
+      const choice = Array.isArray(question.choices)
+        ? question.choices.find((c) => c?.value === answer?.answer)
+        : null;
+      if (!choice) continue;
+      const writePath = typeof choice.uiBaselineWritePath === 'string' ? choice.uiBaselineWritePath : null;
+      if (!writePath) continue;
+      // Strip the `defaults.` prefix (the write path is authored against
+      // the uiBaseline record; the seam applies against the defaults
+      // subtree, so the prefix is dropped here).
+      const key = writePath.startsWith('defaults.') ? writePath.slice('defaults.'.length) : writePath;
+      if (overrides[key] === undefined) {
+        overrides[key] = choice.uiBaselineWriteValue;
+      }
+    }
+  }
+  return overrides;
+}
+
+/**
+ * Persist a composed `uiBaseline` record. When a previous baseline
+ * exists and `options.reset` is true, the previous record is appended
+ * to `uiBaselineHistory[]` (spec §12 O-4).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {object} args.record
+ * @param {object} [args.options]
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeUiBaselineRecord({
+  projectRoot, tree, record, options = {},
+}) {
+  const manifest = tree.manifest ?? {};
+  const nextManifest = { ...manifest };
+  const priorBaseline = nextManifest.uiBaseline ?? null;
+
+  if (priorBaseline && options.reset) {
+    const history = Array.isArray(nextManifest.uiBaselineHistory) ? nextManifest.uiBaselineHistory : [];
+    nextManifest.uiBaselineHistory = [...history, priorBaseline];
+  }
+  nextManifest.uiBaseline = record;
+
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+
+  if (options.dryRun) return { record, dryRun: true };
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `ui-baseline: manifest write failed: ${err.message}`,
+      filePath: relPath,
+      stack: err.stack,
+    });
+  }
+  return { record };
+}
+
+/**
+ * Append an opt-out entry to an existing `uiBaseline` record. Refuses
+ * when no baseline exists (the operator must init first) or the field
+ * path is not a known baseline field.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.field   dot-path into defaults (or `defaults.<...>`; both accepted)
+ * @param {string} args.reason  operator's plain-text ruling
+ * @param {(path: string) => boolean} [args.isKnownField]
+ * @param {Date} [args.now]
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeUiBaselineOptOut({
+  projectRoot, tree, field, reason, isKnownField, now = new Date(),
+}) {
+  const manifest = tree.manifest ?? {};
+  const priorBaseline = manifest.uiBaseline;
+  if (!priorBaseline) {
+    return rcfError({
+      kind: 'usage',
+      message: 'ui-baseline opt-out: no uiBaseline record exists yet; run \'rcf ui-baseline init\' first.',
+    });
+  }
+  const normalisedField = String(field).startsWith('defaults.') ? String(field).slice('defaults.'.length) : String(field);
+  if (typeof isKnownField === 'function' && !isKnownField(normalisedField)) {
+    return rcfError({
+      kind: 'usage',
+      message: `ui-baseline opt-out: unknown baseline field '${normalisedField}' (see 'rcf ui-baseline show' for the field list).`,
+    });
+  }
+  const isoNow = now.toISOString();
+  const nextManifest = { ...manifest };
+  const nextRecord = { ...priorBaseline };
+  const existing = Array.isArray(nextRecord.operatorOptOuts) ? nextRecord.operatorOptOuts : [];
+  nextRecord.operatorOptOuts = [
+    ...existing.filter((o) => o.field !== normalisedField),
+    { field: normalisedField, reason, operatorAckAt: isoNow },
+  ];
+  nextManifest.uiBaseline = nextRecord;
+
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `ui-baseline opt-out: manifest write failed: ${err.message}`,
+      filePath: relPath,
+      stack: err.stack,
+    });
+  }
+  return { record: nextRecord };
+}
+
+/**
+ * True when a value in the baseline's `defaults` disagrees with a
+ * value on a FBS's `designStage`. Used by the design-mark-complete gate.
+ * Returns null on agreement or when no opinion is expressible; returns
+ * `{ path, baselineValue, designValue }` on disagreement.
+ *
+ * @param {object|null} baseline
+ * @param {object|null} designStage
+ * @param {string} path  dot-path relative to `defaults` (e.g. `themeMode`)
+ * @param {string} designStagePath  dot-path relative to `designStage` (e.g. `themeAndA11y.themeMode`)
+ * @returns {{ path: string, baselineValue: *, designValue: * }|null}
+ */
+export function baselineDesignDisagreement(baseline, designStage, path, designStagePath) {
+  if (!baseline || !designStage) return null;
+  const baselineValue = deepGet(baseline.defaults ?? {}, path);
+  const designValue = deepGet(designStage, designStagePath);
+  if (baselineValue === undefined || designValue === undefined) return null;
+  const optOuts = Array.isArray(baseline.operatorOptOuts) ? baseline.operatorOptOuts : [];
+  if (optOuts.some((o) => o.field === path)) return null;
+  if (baselineValue === designValue) return null;
+  return { path, baselineValue, designValue };
+}
+
+export { deepSet, deepGet };

package/src/ui-baseline/session.js

@@ -0,0 +1,178 @@
+// Interactive session for `rcf ui-baseline init` (spec §5.4).
+//
+// Two shapes:
+// - `runInteractiveSession(...)` - the TTY path. Presents an
+//   enter-to-accept-all summary screen. Typing a field name opens
+//   per-field editing for that field alone; typing `edit-all` walks
+//   every field sequentially. This preserves the "explicit never by
+//   silence" property (operator has seen every field on the summary)
+//   without the twelve-field walk ceremony that would reintroduce the
+//   verbosity defect from the Entry 1 cold-run feedback log.
+//
+// - `normaliseNonInteractiveInput(input)` - CI / automation path. The
+//   input file is a plain object with `optOuts` (array of { field,
+//   reason }) and optional `overrides` (dot-path -> value). Every
+//   field is treated as ack'd; the file's presence is the "seen every
+//   field" signal.
+
+import { UI_BASELINE_DEFAULTS_V1, deepGet, isKnownBaselinePath } from './defaults.js';
+
+/**
+ * @typedef {object} UiBaselineSessionResult
+ * @property {Array<{ field: string, reason: string }>} optOuts
+ * @property {object} overrides   dot-path -> value overrides for the defaults composer
+ */
+
+/**
+ * Interactive session (TTY). Callers supply `prompt` and `write`
+ * closures wrapping `readline.createInterface`. Refuses to exit
+ * without visiting every field.
+ *
+ * @param {object} args
+ * @param {(q: string) => Promise<string>} args.prompt
+ * @param {(s: string) => void} args.write
+ * @param {object} [args.preflightOverrides]  dot-path -> value seam pickup from preflight (spec §3.2)
+ * @returns {Promise<UiBaselineSessionResult>}
+ */
+export async function runInteractiveSession({ prompt, write, preflightOverrides = {} }) {
+  /** @type {Array<{ field: string, reason: string }>} */
+  const optOuts = [];
+  /** @type {Record<string, *>} */
+  const overrides = { ...preflightOverrides };
+  const editedFields = new Set(Object.keys(preflightOverrides));
+
+  let done = false;
+  while (!done) {
+    renderSummary({ write, overrides, optOuts, editedFields });
+    const answer = (await prompt('> ')).trim();
+    if (answer === '' || answer.toLowerCase() === 'accept') {
+      done = true;
+      break;
+    }
+    if (answer.toLowerCase() === 'cancel') {
+      throw new Error('ui-baseline: session cancelled by operator');
+    }
+    if (answer.toLowerCase() === 'edit-all') {
+      for (const spec of UI_BASELINE_DEFAULTS_V1) {
+        await editField({ spec, prompt, write, overrides, optOuts, editedFields });
+      }
+      continue;
+    }
+    if (isKnownBaselinePath(answer)) {
+      const spec = UI_BASELINE_DEFAULTS_V1.find((s) => s.path === answer);
+      await editField({ spec, prompt, write, overrides, optOuts, editedFields });
+      continue;
+    }
+    write(`Unknown option '${answer}'. Type a field path (e.g. ${UI_BASELINE_DEFAULTS_V1[0].path}), 'edit-all', or press ENTER to accept.`);
+  }
+  return { optOuts, overrides };
+}
+
+function renderSummary({ write, overrides, optOuts, editedFields }) {
+  write('');
+  write('UI baseline defaults (v1). Every value below is ruled by the estate playbook.');
+  write('');
+  for (const spec of UI_BASELINE_DEFAULTS_V1) {
+    const effective = Object.prototype.hasOwnProperty.call(overrides, spec.path) ? overrides[spec.path] : spec.value;
+    const marker = optOuts.some((o) => o.field === spec.path)
+      ? '*'
+      : (editedFields.has(spec.path) ? '+' : ' ');
+    write(`  ${marker} ${padEnd(spec.path, 46)}${formatValue(effective)}`);
+  }
+  write('');
+  write('Press ENTER to accept these defaults. Type a field path to edit one, or \'edit-all\' to walk every field, or \'cancel\'.');
+  write('  * = opt-out recorded, + = value differs from ruled default');
+}
+
+function padEnd(s, n) {
+  const str = String(s);
+  return str.length >= n ? str : str + ' '.repeat(n - str.length);
+}
+
+function formatValue(v) {
+  if (Array.isArray(v)) return `[${v.map((x) => JSON.stringify(x)).join(', ')}]`;
+  if (typeof v === 'string') return v;
+  return JSON.stringify(v);
+}
+
+async function editField({ spec, prompt, write, overrides, optOuts, editedFields }) {
+  write('');
+  write(`Field: ${spec.path}`);
+  write(`  ruled: ${formatValue(spec.value)}`);
+  write(`  source: ${spec.rulingSource}`);
+  const current = Object.prototype.hasOwnProperty.call(overrides, spec.path) ? overrides[spec.path] : spec.value;
+  write(`  current: ${formatValue(current)}`);
+  const raw = await prompt('  new value (JSON) or ENTER to accept ruled, \'opt-out <reason>\' to record ledger entry: ');
+  const answer = raw.trim();
+  if (answer === '') {
+    delete overrides[spec.path];
+    for (let i = optOuts.length - 1; i >= 0; i -= 1) if (optOuts[i].field === spec.path) optOuts.splice(i, 1);
+    editedFields.delete(spec.path);
+    return;
+  }
+  if (answer.startsWith('opt-out')) {
+    const reason = answer.slice('opt-out'.length).trim();
+    if (reason.length < 20) {
+      write(`  opt-out reason must be at least 20 characters (got ${reason.length}); no change written.`);
+      return;
+    }
+    for (let i = optOuts.length - 1; i >= 0; i -= 1) if (optOuts[i].field === spec.path) optOuts.splice(i, 1);
+    optOuts.push({ field: spec.path, reason });
+    editedFields.add(spec.path);
+    return;
+  }
+  try {
+    const parsed = JSON.parse(answer);
+    overrides[spec.path] = parsed;
+    editedFields.add(spec.path);
+  } catch (err) {
+    write(`  parse error (${err.message}); no change written. Value stays: ${formatValue(current)}`);
+  }
+}
+
+/**
+ * Normalise a non-interactive input file into the session result shape.
+ * Input file shape (spec §5.4):
+ *   {
+ *     "optOuts": [ { "field": "path.to.field", "reason": "..." } ],
+ *     "overrides": { "path.to.field": <json value>, ... }
+ *   }
+ * Every field named must be a known baseline path; opt-out reasons must
+ * be at least 20 characters (matches the opt-out ledger floor).
+ *
+ * @param {any} input
+ * @returns {UiBaselineSessionResult}
+ */
+export function normaliseNonInteractiveInput(input) {
+  if (input === null || typeof input !== 'object') {
+    throw new Error('ui-baseline: non-interactive input must be an object');
+  }
+  const optOuts = [];
+  const overrides = {};
+  for (const raw of Array.isArray(input.optOuts) ? input.optOuts : []) {
+    if (!raw || typeof raw.field !== 'string') {
+      throw new Error('ui-baseline: input.optOuts[] entry missing field');
+    }
+    const field = raw.field.startsWith('defaults.') ? raw.field.slice('defaults.'.length) : raw.field;
+    if (!isKnownBaselinePath(field)) {
+      throw new Error(`ui-baseline: input.optOuts[] unknown field '${field}'`);
+    }
+    if (typeof raw.reason !== 'string' || raw.reason.length < 20) {
+      throw new Error(`ui-baseline: input.optOuts[] for '${field}' needs a reason of at least 20 characters`);
+    }
+    optOuts.push({ field, reason: raw.reason });
+  }
+  const rawOverrides = input.overrides ?? {};
+  if (rawOverrides !== null && typeof rawOverrides === 'object' && !Array.isArray(rawOverrides)) {
+    for (const [rawKey, value] of Object.entries(rawOverrides)) {
+      const key = rawKey.startsWith('defaults.') ? rawKey.slice('defaults.'.length) : rawKey;
+      if (!isKnownBaselinePath(key)) {
+        throw new Error(`ui-baseline: input.overrides has unknown field '${key}'`);
+      }
+      overrides[key] = value;
+    }
+  }
+  return { optOuts, overrides };
+}
+
+export { deepGet };

package/src/ui-detection/classifier.js

@@ -0,0 +1,192 @@
+// UI-bearing FBS classifier (ui-design-gate-0.7.0-spec §4).
+//
+// Deterministic keyword scan over an FBS's own summary/title plus every
+// in-scope AC's description/given/when/then, every parent US's
+// iWant/soThat, every ancestor REQ's description/rationale, plus a
+// dependsOnServices signal (auth-shaped services imply an HTML login
+// page unless the operator has ruled otherwise).
+//
+// The classifier does NOT read source code. Design happens before code;
+// source signals are unavailable at classification time and would be
+// circular for an FBS classified pre-Build.
+//
+// Composition: `classifyFbs(tree, fbsId)` returns a `uiClassification`
+// block per spec §3.1 without writing the FBS document. The caller
+// (the `rcf ui-classify` verb + the `rcf build --next` runbook) is
+// responsible for surfacing the verdict to the operator; writing the
+// FBS document is the operator's choice via `rcf update`.
+//
+// Operator override precedence (§4.4): when `fbs.uiBearing` is a
+// boolean, that operator ruling wins over the classifier's opinion and
+// the returned block carries `verdict: operatorOverride` with the
+// classifier's own evidence preserved in `signals[]` for provenance.
+
+import { matchUiSignals } from '#core/patterns/ui-shapes';
+
+/**
+ * @typedef {'ui'|'notUi'|'operatorOverride'} UiClassifierVerdict
+ */
+
+/**
+ * @typedef {'keyword-scan'|'operator-tag'|'inheritedFromParent'|'operatorOverride'} UiClassifierReason
+ */
+
+/**
+ * @typedef {object} UiClassifierSignal
+ * @property {'summary'|'ac.description'|'us.iWant'|'us.soThat'|'req.description'} source
+ * @property {string} match
+ * @property {string} [acId]
+ */
+
+/**
+ * @typedef {object} UiClassificationBlock
+ * @property {UiClassifierVerdict} verdict
+ * @property {UiClassifierReason} reason
+ * @property {UiClassifierSignal[]} [signals]
+ * @property {string} classifiedAt
+ */
+
+const AUTH_SERVICE_CATEGORIES = new Set([
+  'auth', 'oauth', 'identityProvider', 'emailAuth',
+]);
+
+/**
+ * Classify an FBS as UI-bearing or not.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {string} fbsId
+ * @param {object} [opts]
+ * @param {Date} [opts.now]
+ * @returns {UiClassificationBlock|null}
+ */
+export function classifyFbs(tree, fbsId, opts = {}) {
+  const fbs = tree?.byId?.get(fbsId);
+  if (!fbs || tree.kindById?.get(fbsId) !== 'fbs') return null;
+  const now = (opts.now instanceof Date ? opts.now : new Date()).toISOString();
+
+  const signals = collectSignals(tree, fbs);
+
+  // Operator override wins. Field on the FBS document is authoritative
+  // per spec §4.4; we still preserve the classifier's evidence in
+  // signals[] for provenance so the operator can see what the machine
+  // would have said.
+  if (typeof fbs.uiBearing === 'boolean') {
+    const block = {
+      verdict: 'operatorOverride',
+      reason: 'operatorOverride',
+      classifiedAt: now,
+    };
+    if (signals.length > 0) block.signals = signals;
+    return block;
+  }
+
+  if (signals.length > 0) {
+    return {
+      verdict: 'ui',
+      reason: 'keyword-scan',
+      signals,
+      classifiedAt: now,
+    };
+  }
+  return {
+    verdict: 'notUi',
+    reason: 'keyword-scan',
+    classifiedAt: now,
+  };
+}
+
+/**
+ * Collect UI signals for one FBS. In-order: summary, then per-AC
+ * description/given/when/then with acId anchored, then parent US
+ * iWant/soThat, then ancestor REQ description/rationale, then the
+ * dependsOnServices auth-signal.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} fbs
+ * @returns {UiClassifierSignal[]}
+ */
+export function collectSignals(tree, fbs) {
+  /** @type {UiClassifierSignal[]} */
+  const signals = [];
+
+  // Summary + title. Title concatenated first so a title-only signal
+  // still lands under source: 'summary' (only one FBS-body source in
+  // the schema; the two fields cover the same intent).
+  const summaryText = [fbs.title, fbs.summary].filter(Boolean).join('. ');
+  for (const m of matchUiSignals(summaryText)) {
+    signals.push({ source: 'summary', match: m.match });
+  }
+
+  // ACs (in-scope for this FBS via acIds) + parents. Walker exposes
+  // arrays; build local ac/us/req lookups on the fly (small trees, one
+  // shot per classification, cheaper than an extra derived map on the
+  // walker for a build-side classifier that runs occasionally).
+  const usByAcId = new Map();
+  const reqById = new Map();
+  for (const us of Array.isArray(tree?.userStories) ? tree.userStories : []) {
+    for (const ac of Array.isArray(us?.acceptanceCriteria) ? us.acceptanceCriteria : []) {
+      if (ac?.id) usByAcId.set(ac.id, us);
+    }
+  }
+  for (const req of Array.isArray(tree?.requirements) ? tree.requirements : []) {
+    if (req?.reqId) reqById.set(req.reqId, req);
+  }
+  const seenUsIds = new Set();
+  const seenReqIds = new Set();
+  const fbsAcIds = Array.isArray(fbs.acIds) ? fbs.acIds : [];
+  for (const acId of fbsAcIds) {
+    const us = usByAcId.get(acId);
+    const ac = us?.acceptanceCriteria?.find((a) => a.id === acId);
+    if (ac) {
+      const acText = [ac.description, ac.given, ac.when, ac.then].filter(Boolean).join('. ');
+      for (const m of matchUiSignals(acText)) {
+        signals.push({ source: 'ac.description', acId, match: m.match });
+      }
+    }
+    if (us && !seenUsIds.has(us.usId)) {
+      seenUsIds.add(us.usId);
+      for (const m of matchUiSignals(us.iWant ?? '')) {
+        signals.push({ source: 'us.iWant', match: m.match });
+      }
+      for (const m of matchUiSignals(us.soThat ?? '')) {
+        signals.push({ source: 'us.soThat', match: m.match });
+      }
+      const req = reqById.get(us.reqId);
+      if (req && !seenReqIds.has(req.reqId)) {
+        seenReqIds.add(req.reqId);
+        const reqText = [req.description, req.rationale].filter(Boolean).join('. ');
+        for (const m of matchUiSignals(reqText)) {
+          signals.push({ source: 'req.description', match: m.match });
+        }
+      }
+    }
+  }
+
+  // Auth-shaped service dependency implies an HTML login flow (spec
+  // §4.2 bullet 5); the signal is packaged as a summary-level match so
+  // the operator sees it in the same list.
+  for (const dep of Array.isArray(fbs.dependsOnServices) ? fbs.dependsOnServices : []) {
+    const category = String(dep?.serviceCategory ?? '');
+    if (AUTH_SERVICE_CATEGORIES.has(category)) {
+      signals.push({ source: 'summary', match: `dependsOnServices:${category}` });
+    }
+  }
+
+  return signals;
+}
+
+/**
+ * True when the FBS is UI-bearing (operator-tagged true). Used by
+ * downstream gates that must not silently promote the classifier's
+ * `verdict: ui` into enforcement: the operator's boolean is the
+ * authority per spec §4.4, and the classifier verdict is a proposal
+ * the operator sees before ratifying.
+ *
+ * @param {object} fbs
+ * @returns {boolean}
+ */
+export function isUiBearing(fbs) {
+  if (!fbs) return false;
+  if (fbs.uiBearing === true) return true;
+  return false;
+}