rcf-lite 0.0.1 → 0.8.0

package/src/setup/knowledge-seed.js

@@ -0,0 +1,123 @@
+// Strand 2: seed writer for `rcf/knowledge/` (0.6.0 spec §3). Init
+// writes four files unconditionally on a fresh scaffold; on a re-run,
+// any managed file that already exists is left byte-identical. The
+// seed is convention-only in v1 (no CLI verb, no retrieval machinery);
+// what ships is the README that teaches the convention and a stub
+// INDEX.md for human bullets.
+//
+// Idempotency contract (§3.3): the four files above are the ones that
+// count as "managed by init". Any file the operator drops under
+// `rcf/knowledge/` stays as-is. If the whole tree is missing on a
+// re-run, init re-seeds it (a repo that pre-dates 0.6.0 gets the
+// convention retroactively without needing a hand-edit).
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** Canonical README (spec §3.4). Verbatim. */
+export const KNOWLEDGE_README = `# Knowledge
+
+This directory is the project's memory. Everything an agent working on
+this repo should not have to relearn from scratch belongs here.
+
+## The convention
+
+- **\`notes/\`**: internal facts. Decisions, gotchas, runtime facts,
+  the small things that always cost time to rediscover ("the CI matrix
+  uses Node 22 not 24", "the pnpm store path on this machine is
+  non-default", "the local Postgres is on port 5433 not 5432"). Written
+  for future agents and future you, not for public readers.
+- **\`docs/\`**: user-facing prose the project might surface elsewhere.
+  Design notes the operator wants tidy, sections that might land in a
+  README or a spec, prose intended for a wider audience.
+
+## The rules
+
+1. **One topic per file.** The filename is the topic
+   (\`notes/ci-node-version.md\`, not \`notes/general.md\`). One paragraph
+   is enough. An empty file that only carries a pointer to somewhere
+   else is fine. A file called \`misc.md\` or \`general.md\` is not.
+2. **Write on learn.** If this session established a fact the next
+   session should not have to rediscover, write it here before the
+   session ends.
+3. **Grep before asking.** Before asking the stakeholder a question,
+   \`rg -n '<topic>' rcf/knowledge/\` to see whether the answer is
+   already here.
+
+## \`INDEX.md\`
+
+\`INDEX.md\` is a human table of contents. Add a bullet when you add a
+file. Keep it grouped by area if it grows. Nobody scans it
+programmatically in v1; it is for the person landing on the repo cold.
+
+## What this is not
+
+This is not a knowledge graph. There is no CLI verb, no indexer, no
+vector search. If a project needs one, that is a v2 decision, not a v1
+default. The convention above is deliberately cheap. The value is in
+the discipline of using it.
+`;
+
+/** Canonical INDEX.md stub (spec §3.4). Verbatim. */
+export const KNOWLEDGE_INDEX = `# Knowledge index
+
+The human table of contents for \`rcf/knowledge/\`. Add a bullet when you
+add a file. Keep it grouped by area if it grows.
+
+## Notes
+
+_(none yet)_
+
+## Docs
+
+_(none yet)_
+`;
+
+/**
+ * Absolute path helpers for the seed files.
+ *
+ * @param {string} projectRoot
+ * @returns {{ dir: string, readme: string, index: string, notesKeep: string, docsKeep: string }}
+ */
+export function knowledgePaths(projectRoot) {
+  const dir = join(projectRoot, 'rcf', 'knowledge');
+  return {
+    dir,
+    readme: join(dir, 'README.md'),
+    index: join(dir, 'INDEX.md'),
+    notesKeep: join(dir, 'notes', '.gitkeep'),
+    docsKeep: join(dir, 'docs', '.gitkeep'),
+  };
+}
+
+async function writeIfMissing(path, contents) {
+  try {
+    await readFile(path, 'utf8');
+    return { path, action: /** @type {'kept'} */ ('kept') };
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== 'ENOENT') throw err;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents, 'utf8');
+  return { path, action: /** @type {'created'} */ ('created') };
+}
+
+/**
+ * Seed the four managed files under `rcf/knowledge/`. Any file already
+ * present is left byte-identical (AC-2.2). If the whole tree is missing
+ * on a re-run, all four are recreated (AC-2.3).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<{ writes: Array<{ file: string, action: 'created' | 'kept' }> }>}
+ */
+export async function writeKnowledgeSeed({ projectRoot }) {
+  const paths = knowledgePaths(projectRoot);
+  const results = [
+    { file: 'rcf/knowledge/README.md', ...(await writeIfMissing(paths.readme, KNOWLEDGE_README)) },
+    { file: 'rcf/knowledge/INDEX.md', ...(await writeIfMissing(paths.index, KNOWLEDGE_INDEX)) },
+    { file: 'rcf/knowledge/notes/.gitkeep', ...(await writeIfMissing(paths.notesKeep, '')) },
+    { file: 'rcf/knowledge/docs/.gitkeep', ...(await writeIfMissing(paths.docsKeep, '')) },
+  ];
+  return { writes: results.map((r) => ({ file: r.file, action: r.action })) };
+}

package/src/setup/managed-block.js

@@ -0,0 +1,193 @@
+// Generic "managed block in file X" primitive (0.6.0 spec §11). Both
+// the agent-instructions check (strand 1) and the gitignore check
+// (strand 4) call into this module with their respective (marker-pair,
+// canonical-text) tuples. Doctor's per-check code stays small; every
+// managed-block check shares one implementation of the detect / extract
+// / splice / hash primitives.
+//
+// Design rules from the spec:
+// - Detection semantics enumerated at §2.6 / §4.4 (missing, stale-hash,
+//   legacy-markers, orphan-marker, duplicate-block).
+// - --fix is wholesale replacement inside the markers; zero bytes
+//   touched outside; newline normalisation is off (§2.7).
+// - Structurally corrupt files (orphan / duplicate) are refused by
+//   --fix; hand-repair message returned.
+// - Idempotent: running --fix on already-clean state is a no-op that
+//   writes zero files (§2.7 last bullet).
+
+import { createHash } from 'node:crypto';
+
+/**
+ * @typedef {'clean' | 'missing-block' | 'stale-hash' | 'legacy-markers' | 'orphan-marker' | 'duplicate-block'} BlockState
+ */
+
+/**
+ * @typedef {object} BlockOptions
+ * @property {string} markerBegin - current-generation begin marker.
+ * @property {string} markerEnd - current-generation end marker.
+ * @property {string | null} [legacyMarkerBegin] - pre-0.6.0 begin marker; omit to disable legacy detection.
+ * @property {string | null} [legacyMarkerEnd] - pre-0.6.0 end marker; omit to disable legacy detection.
+ */
+
+/**
+ * SHA-256 of the trimmed text, matching gen-managed-artefacts.mjs's
+ * hashOf. Whitespace around marker lines does not trip staleness.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function hashInnerContent(text) {
+  return createHash('sha256').update(text.trim(), 'utf8').digest('hex');
+}
+
+/**
+ * Locate the marker pair's byte offsets within `text`. Returns
+ * `beginIndex` (offset of MARKER_BEGIN's first char), `endIndex`
+ * (offset of the character AFTER MARKER_END, INCLUSIVE of a trailing
+ * newline if one exists), and `innerText` (bytes strictly between the
+ * markers, no surrounding newlines).
+ *
+ * @param {string} text
+ * @param {string} markerBegin
+ * @param {string} markerEnd
+ * @returns {{ beginIndex: number, endIndex: number, innerText: string } | null}
+ */
+export function locateMarkers(text, markerBegin, markerEnd) {
+  const beginIndex = text.indexOf(markerBegin);
+  if (beginIndex < 0) return null;
+  const innerStart = beginIndex + markerBegin.length;
+  const endStart = text.indexOf(markerEnd, innerStart);
+  if (endStart < 0) return null;
+  let endIndex = endStart + markerEnd.length;
+  if (text[endIndex] === '\n') endIndex += 1;
+  const innerText = text.slice(innerStart, endStart);
+  return { beginIndex, endIndex, innerText };
+}
+
+/**
+ * Count occurrences of `needle` in `haystack`.
+ *
+ * @param {string} haystack
+ * @param {string} needle
+ * @returns {number}
+ */
+function countOccurrences(haystack, needle) {
+  if (needle.length === 0) return 0;
+  let count = 0;
+  let i = 0;
+  while (true) {
+    const at = haystack.indexOf(needle, i);
+    if (at < 0) return count;
+    count += 1;
+    i = at + needle.length;
+  }
+}
+
+/**
+ * Classify the file's managed-block state given the current-generation
+ * markers, the pre-0.6.0 legacy markers (optional), and the canonical
+ * hash the caller expects the block's inner content to match.
+ *
+ * @param {string} fileText - the file's raw bytes as UTF-8 string.
+ * @param {string} canonicalHash - SHA-256 of the current canonical text (trimmed).
+ * @param {BlockOptions} opts
+ * @returns {BlockState}
+ */
+export function classifyBlock(fileText, canonicalHash, opts) {
+  const { markerBegin, markerEnd, legacyMarkerBegin, legacyMarkerEnd } = opts;
+  const beginCount = countOccurrences(fileText, markerBegin);
+  const endCount = countOccurrences(fileText, markerEnd);
+  // Duplicate block detection first: more than one pair is unambiguous.
+  if (beginCount >= 2 && endCount >= 2) return 'duplicate-block';
+  // Orphan (unpaired current-marker) after duplicate; either half missing.
+  if (beginCount !== endCount) return 'orphan-marker';
+  // If neither current marker present, fall through to legacy / missing.
+  if (beginCount === 0) {
+    if (legacyMarkerBegin && legacyMarkerEnd) {
+      const legBegin = countOccurrences(fileText, legacyMarkerBegin);
+      const legEnd = countOccurrences(fileText, legacyMarkerEnd);
+      if (legBegin >= 1 && legEnd >= 1) return 'legacy-markers';
+    }
+    return 'missing-block';
+  }
+  // Exactly one pair present; hash the inner content.
+  const located = locateMarkers(fileText, markerBegin, markerEnd);
+  if (!located) return 'orphan-marker';
+  const innerHash = hashInnerContent(located.innerText);
+  return innerHash === canonicalHash ? 'clean' : 'stale-hash';
+}
+
+/**
+ * Produce the composed block string (markers + canonical text). Callers
+ * splice this into the file at the location `locateMarkers` reported.
+ *
+ * @param {string} canonicalText
+ * @param {string} markerBegin
+ * @param {string} markerEnd
+ * @returns {string}
+ */
+export function composeBlock(canonicalText, markerBegin, markerEnd) {
+  const trimmed = canonicalText.trim();
+  return `${markerBegin}\n${trimmed}\n${markerEnd}\n`;
+}
+
+/**
+ * Rewrite `fileText` in place with the composed block:
+ * - `clean`: return the input unchanged (idempotent no-op).
+ * - `stale-hash`: splice the composed block over the current pair,
+ *   preserving every byte outside the markers.
+ * - `legacy-markers`: splice the composed block over the legacy pair,
+ *   preserving every byte outside the legacy markers.
+ * - `missing-block`: append the composed block at end of file, adding a
+ *   leading blank-line separator if the file did not end in a newline.
+ * - `orphan-marker` / `duplicate-block`: refused; returns null so the
+ *   caller emits the hand-repair message.
+ *
+ * @param {string} fileText
+ * @param {string} canonicalText
+ * @param {BlockOptions} opts
+ * @param {string} canonicalHash
+ * @returns {{ nextText: string, action: 'noop' | 'replaced' | 'migrated' | 'appended' } | null}
+ */
+export function applyFix(fileText, canonicalText, opts, canonicalHash) {
+  const state = classifyBlock(fileText, canonicalHash, opts);
+  const composed = composeBlock(canonicalText, opts.markerBegin, opts.markerEnd);
+  if (state === 'clean') {
+    return { nextText: fileText, action: 'noop' };
+  }
+  if (state === 'orphan-marker' || state === 'duplicate-block') {
+    return null;
+  }
+  if (state === 'stale-hash') {
+    const loc = locateMarkers(fileText, opts.markerBegin, opts.markerEnd);
+    if (!loc) return null;
+    const nextText = fileText.slice(0, loc.beginIndex) + composed + fileText.slice(loc.endIndex);
+    return { nextText, action: 'replaced' };
+  }
+  if (state === 'legacy-markers' && opts.legacyMarkerBegin && opts.legacyMarkerEnd) {
+    const loc = locateMarkers(fileText, opts.legacyMarkerBegin, opts.legacyMarkerEnd);
+    if (!loc) return null;
+    const nextText = fileText.slice(0, loc.beginIndex) + composed + fileText.slice(loc.endIndex);
+    return { nextText, action: 'migrated' };
+  }
+  // missing-block
+  const separator = fileText.length === 0
+    ? ''
+    : (fileText.endsWith('\n') ? '\n' : '\n\n');
+  return { nextText: `${fileText}${separator}${composed}`, action: 'appended' };
+}
+
+/**
+ * Extract only the inner content of the current-marker block, or null
+ * if the file has no clean pair. For diagnostics: doctor's `stale-hash`
+ * report can quote or diff the block if it wants to (v1 does not).
+ *
+ * @param {string} fileText
+ * @param {string} markerBegin
+ * @param {string} markerEnd
+ * @returns {string | null}
+ */
+export function extractInnerContent(fileText, markerBegin, markerEnd) {
+  const located = locateMarkers(fileText, markerBegin, markerEnd);
+  return located ? located.innerText : null;
+}

package/src/setup/managed-gitignore.js

@@ -0,0 +1,166 @@
+// Aggregator seam for the managed `.gitignore` block (0.6.0 spec §4,
+// D-4 normative aggregator function). The registry of "files RCF wants
+// ignored by default" is composed by `managedGitignoreEntries()`. This
+// module is the single shared file that 0.7.0+ extends: import a
+// per-feature entry constant from its owning module and insert into the
+// array, one file, two lines added, no doctor code change (§4.1's
+// worked 0.7.0 diff).
+//
+// The `.gitignore` marker convention shares the visual shape of the
+// agent-instructions markers but lives in a disjoint namespace
+// (gitignore uses `#` for comments). Doctor's per-check logic still
+// calls into the generic managed-block primitive in `managed-block.js`
+// with these markers as its (markerBegin, markerEnd) pair.
+//
+// Composition primitives split by concern:
+// - Production callers use the no-arg accessors `composeGitignoreBlock()`,
+//   `composeGitignoreInner()`, `computeGitignoreBlockHash()` — these
+//   compose from the module-owned aggregator (`managedGitignoreEntries()`).
+// - Tests that need to prove the extension pipeline works with a
+//   synthetic second entry call the `*FromEntries(entries)` helpers
+//   directly with an explicit entries array. No production code path
+//   accepts an entries override; the aggregator's registered set is the
+//   only source of truth at runtime.
+
+import { hashInnerContent } from './managed-block.js';
+import { identityEntry } from './identity-seed.js';
+import { preflightEntry } from '../preflight/secrets.js';
+// Track C+D §9.3: gitignore the view-server pid file and supervisor log.
+import { viewServerGitignoreEntry, viewServerLogGitignoreEntry } from '../view-supervisor/manifest-writer.js';
+
+/**
+ * @typedef {object} GitignoreEntry
+ * @property {string} path - gitignore-syntax line (glob or literal path relative to project root).
+ * @property {string} owner - human-readable feature name shown in the block's owner comment.
+ * @property {string} since - SemVer minor the entry landed on.
+ */
+
+/**
+ * Registered gitignore entries the managed block covers. Each entry
+ * exports from its owning feature module (per §4.1's contract: feature
+ * modules OWN their entry constant and do NOT import the aggregator,
+ * avoiding import-time mutation surprises); the aggregator imports and
+ * composes deterministically. Adding an entry (e.g. the 0.7.0
+ * credentials side-file) is a one-file edit here: import the constant
+ * and insert into the returned array. Do NOT mutate the returned array
+ * at runtime; callers should treat it as read-only.
+ *
+ * @returns {GitignoreEntry[]}
+ */
+export function managedGitignoreEntries() {
+  return [
+    identityEntry,
+    preflightEntry,
+    viewServerGitignoreEntry,
+    viewServerLogGitignoreEntry,
+  ];
+}
+
+/** Owner-comment header on the begin marker (§4.3 canonical text). */
+export const GITIGNORE_MARKER_BEGIN = '# rcf:managed:begin (managed by `rcf doctor`; do not edit inside)';
+export const GITIGNORE_MARKER_END = '# rcf:managed:end';
+
+/**
+ * Compose the full managed block (marker + inner + marker + terminating
+ * newline) from an explicit entries array. Pure helper — used by the
+ * production accessor `composeGitignoreBlock()` (which sources entries
+ * from the aggregator) AND by tests that need to exercise the
+ * composition pipeline with a synthetic entries array without any
+ * production test hook.
+ *
+ * @param {GitignoreEntry[]} entries
+ * @returns {string}
+ */
+export function composeGitignoreBlockFromEntries(entries) {
+  const lines = [GITIGNORE_MARKER_BEGIN];
+  for (const e of entries) {
+    lines.push(`# ${e.owner} (since ${e.since})`);
+    lines.push(e.path);
+  }
+  lines.push(GITIGNORE_MARKER_END);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Compose the inner content the block wraps (everything strictly
+ * between the marker lines) from an explicit entries array. Doctor's
+ * stale-hash primitive hashes this (trimmed) so operator whitespace
+ * around markers is ignored.
+ *
+ * @param {GitignoreEntry[]} entries
+ * @returns {string}
+ */
+export function composeGitignoreInnerFromEntries(entries) {
+  const lines = [];
+  for (const e of entries) {
+    lines.push(`# ${e.owner} (since ${e.since})`);
+    lines.push(e.path);
+  }
+  return `${lines.join('\n')}`;
+}
+
+/**
+ * SHA-256 of the composed inner content (trimmed) for an explicit
+ * entries array. Doctor compares this to the hash of the inner content
+ * extracted from the file; mismatch means stale.
+ *
+ * @param {GitignoreEntry[]} entries
+ * @returns {string}
+ */
+export function computeGitignoreBlockHashFromEntries(entries) {
+  return hashInnerContent(composeGitignoreInnerFromEntries(entries));
+}
+
+/**
+ * Compose the full managed block from the aggregator. Deterministic
+ * order (aggregator's registered order); each entry preceded by its
+ * one-line owner comment `# {owner} (since {since})`; trailing newline
+ * outside the end marker so the block sits cleanly inside a file.
+ * Callers splice the return value in place; the return is the FULL
+ * block (marker + inner + marker + terminating newline).
+ *
+ * @returns {string}
+ */
+export function composeGitignoreBlock() {
+  return composeGitignoreBlockFromEntries(managedGitignoreEntries());
+}
+
+/**
+ * The inner-content string the composed block wraps, sourced from the
+ * aggregator.
+ *
+ * @returns {string}
+ */
+export function composeGitignoreInner() {
+  return composeGitignoreInnerFromEntries(managedGitignoreEntries());
+}
+
+/**
+ * SHA-256 of the composed inner content (trimmed), sourced from the
+ * aggregator. Doctor's `stale-hash` production callsite.
+ *
+ * @returns {string}
+ */
+export function computeGitignoreBlockHash() {
+  return computeGitignoreBlockHashFromEntries(managedGitignoreEntries());
+}
+
+/**
+ * Locate the managed gitignore block within `text`. Same primitive as
+ * managed-block.js's `locateMarkers` but exported here for the doctor
+ * flow's convenience.
+ *
+ * @param {string} text
+ * @returns {{ beginIndex: number, endIndex: number, innerText: string } | null}
+ */
+export function extractGitignoreBlock(text) {
+  const beginIndex = text.indexOf(GITIGNORE_MARKER_BEGIN);
+  if (beginIndex < 0) return null;
+  const innerStart = beginIndex + GITIGNORE_MARKER_BEGIN.length;
+  const endStart = text.indexOf(GITIGNORE_MARKER_END, innerStart);
+  if (endStart < 0) return null;
+  let endIndex = endStart + GITIGNORE_MARKER_END.length;
+  if (text[endIndex] === '\n') endIndex += 1;
+  const innerText = text.slice(innerStart, endStart);
+  return { beginIndex, endIndex, innerText };
+}

package/src/setup/managed-markers.js

@@ -0,0 +1,49 @@
+// Marker constants for the agent-instructions managed block (0.6.0
+// spec §2.5, D-7). Extracted to a single module so a marker rename in
+// six months lands in one place, not scattered across agent-setup,
+// doctor, MCP funnel and tests. Drift between two definitions is the
+// exact bug the strand-1 legacy-markers migration exists to prevent.
+//
+// The legacy pair (`<!-- rcf:begin -->` / `<!-- rcf:end -->`) is also
+// exported so callers that need to recognise the pre-0.6.0 marker
+// generation (the MCP setup funnel, doctor's `legacy-markers` check)
+// have a single source of truth for its shape too.
+//
+// The managed-gitignore module owns its own marker constants in
+// `managed-gitignore.js` (disjoint namespace: gitignore uses `#`
+// comments rather than HTML comments).
+
+/** The 0.6.0+ managed-block markers `rcf init` writes into agent-instructions files. */
+export const MARKER_BEGIN = '<!-- rcf:managed:begin -->';
+export const MARKER_END = '<!-- rcf:managed:end -->';
+
+/** Pre-0.6.0 marker generation; kept for the transitional `hasAgentMarker` recogniser and doctor's `legacy-markers` check. */
+export const LEGACY_MARKER_BEGIN = '<!-- rcf:begin -->';
+export const LEGACY_MARKER_END = '<!-- rcf:end -->';
+
+/**
+ * Compose the replace-in-place regex for the current-marker managed
+ * block. Non-greedy match between MARKER_BEGIN and MARKER_END so a file
+ * with structural corruption (unpaired markers, duplicate blocks) does
+ * not silently swallow arbitrary regions - doctor detects those states
+ * explicitly and refuses to --fix them.
+ *
+ * @returns {RegExp}
+ */
+export function markerRegex() {
+  return new RegExp(`${escapeRegex(MARKER_BEGIN)}[\\s\\S]*?${escapeRegex(MARKER_END)}`);
+}
+
+/**
+ * Same shape as `markerRegex` for the legacy pair. Used by doctor's
+ * `legacy-markers` --fix path and by the transitional migration.
+ *
+ * @returns {RegExp}
+ */
+export function legacyMarkerRegex() {
+  return new RegExp(`${escapeRegex(LEGACY_MARKER_BEGIN)}[\\s\\S]*?${escapeRegex(LEGACY_MARKER_END)}`);
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/ui-baseline/defaults.js

@@ -0,0 +1,119 @@
+// Ruled UI-baseline defaults (ui-design-gate-0.7.0-spec §6.1).
+//
+// Every value is Baz-ruled (Entry 5 of the 2026-07-29 cold-run operator
+// feedback log) or a §4.3 mandate from the review-phase analysis. The
+// `rcf ui-baseline init` verb presents these values as the defaults;
+// the operator accepts (silence is NOT an opt-out) or overrides with a
+// reason via `operatorOptOuts[]` (spec §6.2).
+//
+// Editing this catalogue is a spec-level change: baseline evolution
+// happens via `rcf ui-baseline opt-out` per project, or a new spec
+// revision.
+
+/**
+ * @typedef {object} UiBaselineFieldSpec
+ * @property {string} path       dot-path into `uiBaseline.defaults` (for opt-out records + refusal messages)
+ * @property {*} value           the ruled value (the "present as default" for interactive init)
+ * @property {string} label      operator-facing short label (used in the summary screen)
+ * @property {string} rulingSource brief citation for provenance
+ */
+
+/**
+ * The v1 defaults catalogue. Ordered for stable presentation on the
+ * interactive summary screen: theme + layout first (most visible),
+ * then contrast + a11y, then typography + interaction, then auth flow.
+ * @type {UiBaselineFieldSpec[]}
+ */
+export const UI_BASELINE_DEFAULTS_V1 = Object.freeze([
+  { path: 'themeMode', value: 'light-default-with-toggle', label: 'Theme mode', rulingSource: 'Baz Entry 5' },
+  { path: 'sharedLayoutModule', value: 'src/ui/layout.ts', label: 'Shared layout module', rulingSource: 'Baz Entry 5 + review-phase mandate 3' },
+  { path: 'designTokensModule', value: 'src/ui/tokens.ts', label: 'Design tokens module', rulingSource: 'review-phase mandate 1' },
+  { path: 'noHexInViewFiles', value: true, label: 'No hex literals in view files', rulingSource: 'review-phase mandate 1' },
+  { path: 'contrastTarget', value: 'WCAG AA', label: 'Contrast target', rulingSource: 'Baz Entry 5 + review-phase mandate 6' },
+  { path: 'contrastTestBeforePalette', value: true, label: 'Contrast test authored before palette', rulingSource: 'review-phase mandate 10' },
+  { path: 'focusRingsRequired', value: true, label: 'Focus rings required', rulingSource: 'review-phase mandate 6' },
+  { path: 'hoverStatesRequired', value: true, label: 'Hover states required', rulingSource: 'review-phase mandate 8' },
+  { path: 'componentVocabulary.declaredComponents', value: ['Button', 'Input', 'Card', 'Badge', 'Table', 'Notice'], label: 'Component vocabulary', rulingSource: 'review-phase mandate 5' },
+  { path: 'componentVocabulary.singleBadgeShape', value: true, label: 'Single badge shape', rulingSource: 'review-phase mandate 5' },
+  { path: 'typography.baseFontStack', value: 'system-ui', label: 'Base font stack', rulingSource: 'review-phase mandate 7' },
+  { path: 'typography.bodyLineHeight', value: 1.5, label: 'Body line height', rulingSource: 'review-phase mandate 7' },
+  { path: 'typography.headingLineHeight', value: 1.25, label: 'Heading line height', rulingSource: 'review-phase mandate 7' },
+  { path: 'typography.proseMaxWidth', value: '72ch', label: 'Prose max width', rulingSource: 'review-phase mandate 7' },
+  { path: 'interactionDefaults.loadingIndicatorOnFetch', value: true, label: 'Loading indicator on fetch', rulingSource: 'review-phase mandate 8' },
+  { path: 'interactionDefaults.disabledStateVisuallyDistinct', value: true, label: 'Disabled state visually distinct', rulingSource: 'review-phase mandate 8' },
+  { path: 'authFlow.htmlLoginPageRequired', value: true, label: 'HTML login page required', rulingSource: 'review-phase mandate 9 + Baz "real login flow"' },
+  { path: 'authFlow.smokeChecksRequired', value: true, label: 'Auth-REQ smoke checks required', rulingSource: 'review-phase recommendation 9' },
+]);
+
+/**
+ * Deep-set a value at a dot-path on a plain object. Intermediate
+ * objects are created as needed. Arrays are copied (not shared with
+ * the caller). Returns the mutated top-level object for chaining.
+ *
+ * @param {object} obj
+ * @param {string} path  dot-path (e.g. `componentVocabulary.declaredComponents`)
+ * @param {*} value
+ * @returns {object}
+ */
+export function deepSet(obj, path, value) {
+  const parts = String(path).split('.');
+  let cursor = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+    if (typeof cursor[key] !== 'object' || cursor[key] === null || Array.isArray(cursor[key])) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key];
+  }
+  const last = parts[parts.length - 1];
+  cursor[last] = Array.isArray(value) ? [...value] : value;
+  return obj;
+}
+
+/**
+ * Deep-get a value at a dot-path. Returns `undefined` when any
+ * intermediate segment is absent.
+ *
+ * @param {object} obj
+ * @param {string} path
+ * @returns {*}
+ */
+export function deepGet(obj, path) {
+  const parts = String(path).split('.');
+  let cursor = obj;
+  for (const key of parts) {
+    if (cursor === null || cursor === undefined) return undefined;
+    cursor = cursor[key];
+  }
+  return cursor;
+}
+
+/**
+ * Compose the ruled defaults object from the v1 catalogue. Every field
+ * carries its Baz-ruled value; caller overrides land under
+ * `operatorOptOuts[]` on the surrounding record.
+ *
+ * @param {object} [overrides]  dot-path -> value overrides (used by preflight seam pickup)
+ * @returns {object}
+ */
+export function composeDefaults(overrides = {}) {
+  const out = {};
+  for (const spec of UI_BASELINE_DEFAULTS_V1) {
+    deepSet(out, spec.path, spec.value);
+  }
+  for (const [path, value] of Object.entries(overrides ?? {})) {
+    deepSet(out, path, value);
+  }
+  return out;
+}
+
+/**
+ * True when the given dot-path is a known baseline field. Used by
+ * `rcf ui-baseline opt-out` to refuse writes to non-existent fields.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isKnownBaselinePath(path) {
+  return UI_BASELINE_DEFAULTS_V1.some((s) => s.path === path);
+}

package/src/ui-baseline/index.js

@@ -0,0 +1,25 @@
+// Public surface for the UI-baseline module (ui-design-gate-0.7.0
+// spec §5.4, §6). The CLI handler lives at `src/cli/ui-baseline.js`;
+// consumers reach the module through this barrel.
+
+export {
+  UI_BASELINE_DEFAULTS_V1,
+  composeDefaults,
+  deepGet,
+  deepSet,
+  isKnownBaselinePath,
+} from './defaults.js';
+
+export {
+  baselineDesignDisagreement,
+  composeUiBaselineRecord,
+  nextUiBaselineId,
+  preflightSeamOverrides,
+  writeUiBaselineOptOut,
+  writeUiBaselineRecord,
+} from './manifest-writer.js';
+
+export {
+  normaliseNonInteractiveInput,
+  runInteractiveSession,
+} from './session.js';