rcf-lite 0.0.1 → 0.7.1

package/src/cli/view.js

@@ -0,0 +1,452 @@
+// `rcf view` subcommand handler. Wraps the Phase 3.8 HTTP + SSE server
+// (`src/server/index.js`) behind the unified bin surface. Phase 4 §D23
+// deletes the standalone `bin/rcf-view.js`; every call site becomes
+// `pnpm run rcf view` / `rcf view`, and the pure helpers formerly
+// exported from that bin now live here so the CLI tests can still
+// exercise them without spawning a subprocess.
+
+import { spawn } from 'node:child_process';
+import { platform } from 'node:process';
+
+import { formatErrors } from '#core/errors';
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { startServer } from '../server/index.js';
+// Track C+D §9 view-server persistence.
+import {
+  startDetached,
+  stopDetached,
+  statusOfDetached,
+  readLogTail,
+} from '../view-supervisor/index.js';
+import { parsePersistUntil } from '../view-supervisor/persist-until.js';
+
+export const DEFAULT_PORT = 4373;
+export const SHUTDOWN_BUDGET_MS = 2000;
+
+export const HELP = `Usage: rcf view [subverb] [options]
+
+Serve the on-disk RCF tree as a live HTML review surface. Runs a
+long-running HTTP + SSE server on 127.0.0.1 that watches rcf/ and pushes
+tree updates to the connected browser tab. No on-disk output; no static
+files are written.
+
+Subverbs (spec §9.2):
+  rcf view                  Foreground server (default; lifetime tied to
+                            the invoking session). Backward-compatible
+                            with pre-0.7.0 callers.
+  rcf view start [--detach|--foreground] [--persist-until <duration|iso>]
+                            Start the server. --detach forks a supervised
+                            background process that persists across the
+                            parent session's death; the manifest carries
+                            reviewSurface.viewServer for a subsequent
+                            session to pick up. --persist-until keeps the
+                            supervisor alive for the named duration
+                            (e.g. \`4h\`, \`30m\`, \`2h30m\`) or until
+                            the named ISO timestamp (e.g.
+                            \`2026-07-31T18:00:00Z\`); unrecognised
+                            values refuse (exit 2) rather than run
+                            forever. Default on an interactive TTY is
+                            --detach; non-interactive callers keep
+                            --foreground so a script does not orphan a
+                            process.
+  rcf view status [--json]  Print the supervisor state:
+                            running | stale | not-started.
+  rcf view stop             Send SIGTERM to the supervised process, wait
+                            for a clean shutdown, and clear the manifest
+                            record.
+  rcf view logs [--tail <n>] Print the supervisor log tail (default 200).
+
+Options:
+  --port <n>        Bind the HTTP server on the given port.
+                    Precedence: --port beats RCF_VIEW_PORT env
+                    beats the ${DEFAULT_PORT} default.
+                    EADDRINUSE is a hard failure (exit 2).
+  --strict          Startup gate: on boot, walk the tree once; if it
+                    has structural errors (broken references, schema
+                    failures) print them and exit 3 without opening
+                    the HTTP listener. Without --strict, the server
+                    starts regardless and streams walker errors to the
+                    client via walker-error SSE events.
+  --no-open         Do not open the rendered page in a browser
+                    (auto-open runs by default when stdout is a TTY
+                    and CI is unset).
+  --verbose         Log each watch event and each SSE broadcast to
+                    stderr.
+  --help            Print this help and exit.
+
+Security posture:
+  The view server binds 127.0.0.1 only - localhost trust. No CORS,
+  no auth, no rate limit. Do not expose it via SSH tunnel or reverse
+  proxy without adding an auth layer first.
+
+Shutdown:
+  Ctrl-C (SIGINT) or SIGTERM triggers a clean shutdown: watcher
+  closed, SSE connections drained with a shutdown event, port
+  released, 2s force-exit budget. Detached: rcf view stop sends
+  SIGTERM to the supervisor and waits for a clean unwind.
+
+Exit codes:
+  0   normal shutdown
+  1   render or runtime failure
+  2   usage error (unknown flag, EADDRINUSE, no project root)
+  3   validation failure (with --strict, on the initial walk)
+  130 SIGINT
+`;
+
+const SUBVERBS = new Set(['start', 'status', 'stop', 'logs']);
+
+/**
+ * Parse the view subcommand argv. Hand-rolled so the CLI can pass
+ * through argv slices without re-tokenising via parseArgs. Kept in the
+ * same shape as the Phase 3.8 rcf-view bin for test compatibility.
+ *
+ * @param {string[]} argv
+ * @returns {{ opts: object, errors: string[] }}
+ */
+export function parseArgs(argv) {
+  const opts = {
+    strict: false,
+    verbose: false,
+    help: false,
+    noOpen: false,
+    port: null,
+  };
+  const errors = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--strict':
+        opts.strict = true;
+        break;
+      case '--verbose':
+        opts.verbose = true;
+        break;
+      case '--no-open':
+        opts.noOpen = true;
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--port': {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          errors.push('--port requires a numeric argument');
+          break;
+        }
+        const n = Number(next);
+        if (!Number.isInteger(n) || n < 0 || n > 65535) {
+          errors.push(`--port expects an integer in [0, 65535], got ${next}`);
+        } else {
+          opts.port = n;
+        }
+        i += 1;
+        break;
+      }
+      default:
+        errors.push(`unknown option: ${arg}`);
+    }
+  }
+  return { opts, errors };
+}
+
+/**
+ * Resolve port precedence: --port beats RCF_VIEW_PORT env beats default.
+ *
+ * @param {number | null} flagPort
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ port: number, errors: string[] }}
+ */
+export function resolvePort(flagPort, env) {
+  const errors = [];
+  if (typeof flagPort === 'number') return { port: flagPort, errors };
+  const raw = env.RCF_VIEW_PORT;
+  if (raw !== undefined && raw !== '') {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+      errors.push(`RCF_VIEW_PORT expects an integer in [0, 65535], got ${raw}`);
+      return { port: DEFAULT_PORT, errors };
+    }
+    return { port: n, errors };
+  }
+  return { port: DEFAULT_PORT, errors };
+}
+
+/**
+ * Platform opener command. Kept module-visible so the CLI test suite
+ * can assert per-platform selection without spawning a browser.
+ *
+ * @param {string} plat
+ * @param {string} target
+ * @returns {{ command: string, args: string[] } | null}
+ */
+export function openerFor(plat, target) {
+  if (plat === 'darwin') return { command: 'open', args: [target] };
+  if (plat === 'linux') return { command: 'xdg-open', args: [target] };
+  if (plat === 'win32') return { command: 'start', args: ['""', target] };
+  return null;
+}
+
+/**
+ * Auto-open the served URL when we are on a TTY, CI is unset, and
+ * --no-open was not passed. Never blocks the parent and never throws;
+ * spawn failures fall through to a stderr warning.
+ *
+ * @param {object} args
+ * @returns {boolean}
+ */
+export function maybeAutoOpen({ target, noOpen, stream, env, stderr, spawnFn = spawn, platformName = platform }) {
+  if (noOpen) return false;
+  if (env.CI) return false;
+  if (!stream || !stream.isTTY) return false;
+  const opener = openerFor(platformName, target);
+  if (!opener) return false;
+  try {
+    const child = spawnFn(opener.command, opener.args, { detached: true, stdio: 'ignore' });
+    if (child && typeof child.unref === 'function') child.unref();
+    return true;
+  } catch (err) {
+    stderr.write(`[warn] auto-open: ${err.message}\n`);
+    return false;
+  }
+}
+
+/**
+ * Main entry for the `rcf view` subcommand. Mirrors the shape of the
+ * old bin/rcf-view.js main().
+ *
+ * @param {string[]} argv - the argv slice *after* the "view" positional
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const onSignal = deps.onSignal ?? ((sig, handler) => process.on(sig, handler));
+
+  // Track C+D §9: subverb routing. When the first argv token is
+  // `start | status | stop | logs`, dispatch to the lifecycle handler
+  // and skip the foreground-server path.
+  if (argv.length > 0 && SUBVERBS.has(argv[0])) {
+    const subverb = argv[0];
+    const rest = argv.slice(1);
+    return await runSubverb({ subverb, argv: rest, deps: { env, stdout, stderr } });
+  }
+
+  const { opts, errors: argErrors } = parseArgs(argv);
+  if (opts.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (argErrors.length > 0) {
+    for (const msg of argErrors) stderr.write(`[error] usage ${msg}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const { port: resolvedPort, errors: portErrors } = resolvePort(opts.port, env);
+  if (portErrors.length > 0) {
+    for (const msg of portErrors) stderr.write(`[error] usage ${msg}\n`);
+    return 2;
+  }
+
+  const cwd = deps.cwd ?? process.cwd();
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    stderr.write('Run `rcf init` or create rcf/manifest.json to start.\n');
+    return 2;
+  }
+
+  if (opts.strict) {
+    const { errors } = await walkTree({ projectRoot });
+    if (errors.length > 0) {
+      stderr.write(`${formatErrors(errors, { verbose: opts.verbose, strict: true })}\n`);
+      return 3;
+    }
+  }
+
+  const logSink = opts.verbose ? (line) => stderr.write(`${line}\n`) : () => {};
+
+  let server;
+  try {
+    server = await startServer({
+      projectRoot,
+      port: resolvedPort,
+      log: logSink,
+    });
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EADDRINUSE') {
+      stderr.write(`[error] usage port ${resolvedPort} is in use (another rcf view process, or a different service).\n`);
+      stderr.write('Pass --port <n> or set RCF_VIEW_PORT to pick a free port.\n');
+      return 2;
+    }
+    stderr.write(`[error] ioFailure server failed to start: ${err.message}\n`);
+    return 1;
+  }
+
+  stdout.write(`rcf view server listening at ${server.url}\n`);
+  stdout.write('watching rcf/ - Ctrl-C to shut down\n');
+
+  maybeAutoOpen({
+    target: server.url,
+    noOpen: opts.noOpen,
+    stream: stdout,
+    env,
+    stderr,
+  });
+
+  return new Promise((resolve) => {
+    let signalled = false;
+    async function handle(sig) {
+      if (signalled) return;
+      signalled = true;
+      stderr.write(`[info] received ${sig}, shutting down\n`);
+      let forced = false;
+      const forceExit = setTimeout(() => {
+        forced = true;
+        stderr.write('[warn] shutdown timeout - forcing exit\n');
+        resolve(sig === 'SIGINT' ? 130 : 1);
+      }, SHUTDOWN_BUDGET_MS);
+      if (typeof forceExit.unref === 'function') forceExit.unref();
+      try {
+        await server.close();
+      } catch (err) {
+        stderr.write(`[warn] shutdown error: ${err.message}\n`);
+      }
+      clearTimeout(forceExit);
+      if (!forced) resolve(sig === 'SIGINT' ? 130 : 0);
+    }
+    onSignal('SIGINT', () => { handle('SIGINT'); });
+    onSignal('SIGTERM', () => { handle('SIGTERM'); });
+  });
+}
+
+/**
+ * Route the four Track C+D lifecycle subverbs. Kept in the same file
+ * as the foreground main so the CLI test surface can exercise both
+ * without spawning a subprocess (except for the actual detach test,
+ * which spawns intentionally).
+ *
+ * @param {object} args
+ * @param {'start'|'status'|'stop'|'logs'} args.subverb
+ * @param {string[]} args.argv
+ * @param {{ env: NodeJS.ProcessEnv, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream }} args.deps
+ * @returns {Promise<number>}
+ */
+async function runSubverb({ subverb, argv, deps }) {
+  const { stdout, stderr, env } = deps;
+  const cwd = process.cwd();
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  if (subverb === 'status') {
+    const useJson = argv.includes('--json');
+    const status = await statusOfDetached(projectRoot);
+    if (useJson) {
+      stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+      return 0;
+    }
+    if (status.state === 'not-started') {
+      stdout.write('view server: not-started\n');
+      return 0;
+    }
+    stdout.write(`view server: ${status.state} (pid ${status.pid ?? '?'})\n`);
+    if (status.url) stdout.write(`  url: ${status.url}\n`);
+    if (status.lastHeartbeatAt) stdout.write(`  lastHeartbeatAt: ${status.lastHeartbeatAt}\n`);
+    return 0;
+  }
+
+  if (subverb === 'stop') {
+    const outcome = await stopDetached(projectRoot);
+    if (outcome.stopped) {
+      stdout.write(`view server stopped (pid ${outcome.pid})\n`);
+    } else if (outcome.pid !== null) {
+      stdout.write(`view server: pid ${outcome.pid} was not alive; cleared stale record\n`);
+    } else {
+      stdout.write('view server: not-started (no record to clear)\n');
+    }
+    return 0;
+  }
+
+  if (subverb === 'logs') {
+    const tailIdx = argv.indexOf('--tail');
+    const tail = tailIdx >= 0 ? Number.parseInt(argv[tailIdx + 1] ?? '', 10) : 200;
+    const lines = await readLogTail(projectRoot, Number.isFinite(tail) ? tail : 200);
+    if (lines.length === 0) {
+      stdout.write('view server: no log entries yet\n');
+      return 0;
+    }
+    for (const line of lines) stdout.write(`${line}\n`);
+    return 0;
+  }
+
+  // subverb === 'start'
+  let detach = null;
+  let persistUntilRaw = null;
+  let port = null;
+  const opts = argv.slice();
+  while (opts.length > 0) {
+    const flag = opts.shift();
+    if (flag === '--detach') detach = true;
+    else if (flag === '--foreground') detach = false;
+    else if (flag === '--persist-until') persistUntilRaw = opts.shift() ?? null;
+    else if (flag === '--port') {
+      const raw = opts.shift();
+      const n = Number.parseInt(raw ?? '', 10);
+      if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        stderr.write(`[error] usage view start: --port expects an integer 0..65535, got ${raw}\n`);
+        return 2;
+      }
+      port = n;
+    } else if (flag === '--help') {
+      stdout.write(HELP);
+      return 0;
+    } else {
+      stderr.write(`[error] usage view start: unknown option ${flag}\n`);
+      return 2;
+    }
+  }
+  // Parse --persist-until if supplied. The supervisor expects an ISO
+  // timestamp (its Date.parse silently no-ops on anything else); we
+  // accept the spec §9.2 sample form `4h` here and normalise to ISO
+  // before dispatch. Unrecognised input refuses cleanly (exit 2)
+  // instead of running forever.
+  let persistUntil = null;
+  if (persistUntilRaw !== null) {
+    const parsed = parsePersistUntil(persistUntilRaw);
+    if (!parsed.ok) {
+      stderr.write(`[error] usage view start: ${parsed.error}\n`);
+      return 2;
+    }
+    persistUntil = parsed.iso;
+  }
+  const envPort = Number.parseInt(env.RCF_VIEW_PORT ?? '', 10);
+  const resolvedPort = port ?? (Number.isFinite(envPort) && envPort >= 0 ? envPort : DEFAULT_PORT);
+  // Detach default: interactive TTY implies detach; script/CI keeps foreground.
+  const shouldDetach = detach === null ? Boolean(process.stdout.isTTY && process.stdin.isTTY) : detach;
+  if (!shouldDetach) {
+    // Fall through to the classic foreground behaviour, passing through
+    // any port/verbose flags via the standard main-loop arg surface.
+    const passArgs = [];
+    if (port !== null) { passArgs.push('--port', String(resolvedPort)); }
+    return await main(passArgs, { stdout, stderr, env });
+  }
+  try {
+    const started = await startDetached({ projectRoot, port: resolvedPort, persistUntil });
+    if (started.alreadyRunning) {
+      stdout.write(`view server already running at ${started.url} (pid ${started.pid})\n`);
+      return 0;
+    }
+    stdout.write(`view server started detached at ${started.url} (pid ${started.pid})\n`);
+    if (persistUntil) stdout.write(`  persistUntil: ${persistUntil}\n`);
+    return 0;
+  } catch (err) {
+    stderr.write(`[error] ioFailure view start --detach: ${err.message}\n`);
+    return 1;
+  }
+}

package/src/core/baseline-catalog/data/auth.json

@@ -0,0 +1,42 @@
+{
+  "sourceReqShape": "auth",
+  "specSource": "elicitation-and-playbook-hardening-0.7.0-spec.md §5.2.3",
+  "entries": [
+    {
+      "baselineKey": "auth.htmlLoginPage",
+      "canonicalText": "given the operator has not opted out via preflight rec-3 (Track A §4.6 seam), when `GET /login` is requested, then the response is a 200 with `content-type: text/html; charset=utf-8` and a form containing the fields the auth flow requires (email, password, or magic-link email box per the auth mechanism).",
+      "given": "the operator has not opted out via preflight rec-3 (Track A §4.6 seam)",
+      "when": "`GET /login` is requested",
+      "then": "the response is a 200 with `content-type: text/html; charset=utf-8` and a form containing the fields the auth flow requires (email, password, or magic-link email box per the auth mechanism)",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "auth.postLogout",
+      "canonicalText": "given a signed-in session, when `POST /logout` is invoked, then the session cookie is cleared (Set-Cookie with an expiry in the past), the response is 302 to `/login` (or the project-declared post-logout route), and subsequent requests to protected routes return 401 or 302 as the REQ defines.",
+      "given": "a signed-in session",
+      "when": "`POST /logout` is invoked",
+      "then": "the session cookie is cleared (Set-Cookie with an expiry in the past), the response is 302 to `/login` (or the project-declared post-logout route), and subsequent requests to protected routes return 401 or 302 as the REQ defines",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "auth.sessionCookieShape",
+      "canonicalText": "given any signed-in response, when the auth cookie is set, then the cookie carries `HttpOnly`, `Secure` (when the runtime is HTTPS), `SameSite=Lax` (or the project-declared value), and a documented expiry.",
+      "given": "any signed-in response",
+      "when": "the auth cookie is set",
+      "then": "the cookie carries `HttpOnly`, `Secure` (when the runtime is HTTPS), `SameSite=Lax` (or the project-declared value), and a documented expiry",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "auth.emptyTokenRejection",
+      "canonicalText": "given the auth mechanism uses tokens or magic-links, when a request presents an empty or malformed token, then the response is 400, 401, or a redirect to `/login` with an error parameter; NEVER a 200 that grants a session.",
+      "given": "the auth mechanism uses tokens or magic-links",
+      "when": "a request presents an empty or malformed token",
+      "then": "the response is 400, 401, or a redirect to `/login` with an error parameter; NEVER a 200 that grants a session",
+      "notes": null,
+      "testable": true
+    }
+  ]
+}

package/src/core/baseline-catalog/data/http-api.json

@@ -0,0 +1,42 @@
+{
+  "sourceReqShape": "httpApi",
+  "specSource": "elicitation-and-playbook-hardening-0.7.0-spec.md §5.2.2",
+  "entries": [
+    {
+      "baselineKey": "httpApi.errorEnvelope",
+      "canonicalText": "given any endpoint, when the endpoint returns a non-2xx response, then the body is a JSON object with fields `error.code` (string, machine-readable), `error.message` (string, human-readable), and `error.requestId` (string, correlatable to logs).",
+      "given": "any endpoint",
+      "when": "the endpoint returns a non-2xx response",
+      "then": "the body is a JSON object with fields `error.code` (string, machine-readable), `error.message` (string, human-readable), and `error.requestId` (string, correlatable to logs)",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "httpApi.contentType",
+      "canonicalText": "given any endpoint returning a response body, when the response is emitted, then `content-type: application/json; charset=utf-8` (or the project-declared content type in the REQ's `rationale`) is set explicitly on the response.",
+      "given": "any endpoint returning a response body",
+      "when": "the response is emitted",
+      "then": "`content-type: application/json; charset=utf-8` (or the project-declared content type in the REQ's `rationale`) is set explicitly on the response",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "httpApi.authBoundary",
+      "canonicalText": "given an endpoint the REQ marks as protected, when a request without valid credentials is received, then the response is 401 with the standard error envelope (never 200 with a generic \"not found\" that leaks the endpoint's existence in some sessions and hides it in others).",
+      "given": "an endpoint the REQ marks as protected",
+      "when": "a request without valid credentials is received",
+      "then": "the response is 401 with the standard error envelope (never 200 with a generic \"not found\" that leaks the endpoint's existence in some sessions and hides it in others)",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "httpApi.rateLimitDisclosure",
+      "canonicalText": "given a REQ that opts into rate limiting (via a rate-limit field on the REQ or explicit AC), when a request is throttled, then the response is 429 with `retry-after` set to the number of seconds until retry; when a request is NOT throttled but rate limits exist, then `x-ratelimit-remaining` is present on the response. Opting out is the norm for REQs with no rate limiting.",
+      "given": "a REQ that opts into rate limiting (via a rate-limit field on the REQ or explicit AC)",
+      "when": "a request is throttled",
+      "then": "the response is 429 with `retry-after` set to the number of seconds until retry; when a request is NOT throttled but rate limits exist, then `x-ratelimit-remaining` is present on the response",
+      "notes": "Opting out is the norm for REQs with no rate limiting.",
+      "testable": true
+    }
+  ]
+}

package/src/core/baseline-catalog/data/notifications.json

@@ -0,0 +1,33 @@
+{
+  "sourceReqShape": "notifications",
+  "specSource": "elicitation-and-playbook-hardening-0.7.0-spec.md §5.2.5",
+  "entries": [
+    {
+      "baselineKey": "notifications.deliveryObservability",
+      "canonicalText": "given a notification is dispatched, when dispatch succeeds, then an observable delivery record is produced (a log line, a database row, an admin-UI entry) with fields recipient, channel, status, and timestamp.",
+      "given": "a notification is dispatched",
+      "when": "dispatch succeeds",
+      "then": "an observable delivery record is produced (a log line, a database row, an admin-UI entry) with fields recipient, channel, status, and timestamp",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "notifications.retryOrDeadLetter",
+      "canonicalText": "given a notification dispatch fails and the channel supports retry, when the failure is transient, then the dispatcher retries per a documented policy; when retries are exhausted, the notification lands in a dead-letter store the operator can inspect.",
+      "given": "a notification dispatch fails and the channel supports retry",
+      "when": "the failure is transient",
+      "then": "the dispatcher retries per a documented policy; when retries are exhausted, the notification lands in a dead-letter store the operator can inspect",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "notifications.channelIdentification",
+      "canonicalText": "given a REQ that names a channel (email, SMS, webhook), when a notification is dispatched, then the payload identifies the sender to the recipient (email `from` address, SMS sender ID, webhook `x-source` header) per project convention.",
+      "given": "a REQ that names a channel (email, SMS, webhook)",
+      "when": "a notification is dispatched",
+      "then": "the payload identifies the sender to the recipient (email `from` address, SMS sender ID, webhook `x-source` header) per project convention",
+      "notes": null,
+      "testable": true
+    }
+  ]
+}

package/src/core/baseline-catalog/data/persistence.json

@@ -0,0 +1,33 @@
+{
+  "sourceReqShape": "persistence",
+  "specSource": "elicitation-and-playbook-hardening-0.7.0-spec.md §5.2.4",
+  "entries": [
+    {
+      "baselineKey": "persistence.crashSafety",
+      "canonicalText": "given a write completes and the process is killed unexpectedly, when the process restarts and the data is read back, then the write is present and identical to what was written.",
+      "given": "a write completes and the process is killed unexpectedly",
+      "when": "the process restarts and the data is read back",
+      "then": "the write is present and identical to what was written",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "persistence.schemaMigration",
+      "canonicalText": "given the storage schema evolves across versions, when the app starts against an older schema, then the app either applies a documented migration and starts, or refuses to start with a clear error naming the schema version mismatch. Silent schema drift is the failure mode this AC exists to prevent.",
+      "given": "the storage schema evolves across versions",
+      "when": "the app starts against an older schema",
+      "then": "the app either applies a documented migration and starts, or refuses to start with a clear error naming the schema version mismatch",
+      "notes": "Silent schema drift is the failure mode this AC exists to prevent.",
+      "testable": true
+    },
+    {
+      "baselineKey": "persistence.backupObservable",
+      "canonicalText": "given a REQ that mentions backups or retention, when a backup runs, then the backup produces an observable artefact (a file, a log entry, a metrics counter) that a monitoring surface can read. Opt out where backups are entirely out of scope for the REQ.",
+      "given": "a REQ that mentions backups or retention",
+      "when": "a backup runs",
+      "then": "the backup produces an observable artefact (a file, a log entry, a metrics counter) that a monitoring surface can read",
+      "notes": "Opt out where backups are entirely out of scope for the REQ.",
+      "testable": true
+    }
+  ]
+}

package/src/core/baseline-catalog/data/web-ui.json

@@ -0,0 +1,60 @@
+{
+  "sourceReqShape": "webUi",
+  "specSource": "elicitation-and-playbook-hardening-0.7.0-spec.md §5.2.1",
+  "entries": [
+    {
+      "baselineKey": "webUi.sharedNav",
+      "canonicalText": "given the user is signed in, when any authenticated route is loaded, then the response HTML renders the shared nav element (declared by `uiBaseline.defaults.sharedLayoutModule`) with `aria-current=\"page\"` on the nav link whose href matches the current route.",
+      "given": "the user is signed in",
+      "when": "any authenticated route is loaded",
+      "then": "the response HTML renders the shared nav element (declared by `uiBaseline.defaults.sharedLayoutModule`) with `aria-current=\"page\"` on the nav link whose href matches the current route",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "webUi.themeToggle",
+      "canonicalText": "given a first-load with no theme cookie set, when the page renders, then `<html data-theme=\"light\">` is present; AND a user-visible theme toggle control is rendered on every authenticated route; AND clicking the toggle persists the choice via cookie or local storage for subsequent requests. The default-light case is hardcoded here per Track B §8.3 `themeDefaultsToLight` invariant; projects that opt into a dark default supersede this AC via a `baselineAcOptOuts[]` entry (§3.3), which Track B's `themeDefaultsToLight` tolerates by design.",
+      "given": "a first-load with no theme cookie set",
+      "when": "the page renders",
+      "then": "`<html data-theme=\"light\">` is present; AND a user-visible theme toggle control is rendered on every authenticated route; AND clicking the toggle persists the choice via cookie or local storage for subsequent requests",
+      "notes": "The default-light case is hardcoded here per Track B §8.3 `themeDefaultsToLight` invariant; projects that opt into a dark default supersede this AC via a `baselineAcOptOuts[]` entry (§3.3), which Track B's `themeDefaultsToLight` tolerates by design.",
+      "testable": true
+    },
+    {
+      "baselineKey": "webUi.contrastFloor",
+      "canonicalText": "given the shipped palette, when the contrast test declared at `designStage.themeAndA11y.contrastTestPath` (Track B §3.1) runs, then every text-on-background pair meets WCAG AA (4.5 for text, 3.0 for large text and UI components); AND the test was authored before the palette (per Track B §7 mandate 10, attested via the boolean at `designStage.themeAndA11y.contrastTestAuthoredBeforePalette`). The runtime chain check that couples this AC to the shipped chain is Track B §8.3 `contrastTestExists`; this AC is the elicitation-time expression of that check.",
+      "given": "the shipped palette",
+      "when": "the contrast test declared at `designStage.themeAndA11y.contrastTestPath` (Track B §3.1) runs",
+      "then": "every text-on-background pair meets WCAG AA (4.5 for text, 3.0 for large text and UI components); AND the test was authored before the palette (per Track B §7 mandate 10, attested via the boolean at `designStage.themeAndA11y.contrastTestAuthoredBeforePalette`)",
+      "notes": "The runtime chain check that couples this AC to the shipped chain is Track B §8.3 `contrastTestExists`; this AC is the elicitation-time expression of that check.",
+      "testable": true
+    },
+    {
+      "baselineKey": "webUi.focusRings",
+      "canonicalText": "given any interactive element (button, input, link), when the element receives keyboard focus, then a visible focus ring is rendered in the current theme.",
+      "given": "any interactive element (button, input, link)",
+      "when": "the element receives keyboard focus",
+      "then": "a visible focus ring is rendered in the current theme",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "webUi.signedInAffordance",
+      "canonicalText": "given the user is signed in and the request carries the auth cookie, when any authenticated route is loaded, then the response HTML contains a visible signed-in-as affordance (per Track B `browserVerification` invariant `signedInAsAffordance`).",
+      "given": "the user is signed in and the request carries the auth cookie",
+      "when": "any authenticated route is loaded",
+      "then": "the response HTML contains a visible signed-in-as affordance (per Track B `browserVerification` invariant `signedInAsAffordance`)",
+      "notes": null,
+      "testable": true
+    },
+    {
+      "baselineKey": "webUi.oneJourneyOrMore",
+      "canonicalText": "given the story defines a user-facing outcome, when the Design substage runs (Track B §5), then `designStage.journeys[]` contains at least one entry whose `goal` traces to this AC's `then`. Track B's Design gate enforces journey PRESENCE via `designStageComplete` (§5.2, §5.5 refuse when the artefact is absent or empty); this AC ensures the story-level goal-to-AC trace is at least declarative on the AC so a reviewer can confirm the trace by reading the journey's `goal` alongside the AC's `then`. The trace itself is a review touchpoint, not a machine-checked chain assertion.",
+      "given": "the story defines a user-facing outcome",
+      "when": "the Design substage runs (Track B §5)",
+      "then": "`designStage.journeys[]` contains at least one entry whose `goal` traces to this AC's `then`",
+      "notes": "Track B's Design gate enforces journey PRESENCE via `designStageComplete` (§5.2, §5.5 refuse when the artefact is absent or empty); this AC ensures the story-level goal-to-AC trace is at least declarative on the AC so a reviewer can confirm the trace by reading the journey's `goal` alongside the AC's `then`. The trace itself is a review touchpoint, not a machine-checked chain assertion.",
+      "testable": true
+    }
+  ]
+}